prometeu-studio/docs/pbs/specs/8. Stdlib Environment Packaging and Loading Specification.md

PBS Stdlib Environment Packaging and Loading Specification

Status: Draft v1 (Temporary)
Applies to: Studio PBS frontend stdlib packaging, stdlib environment discovery, reserved stdlib project spaces, and compiler-side stdlib loading abstractions

1. Purpose

This document defines a practical packaging and loading model for the PBS stdlib environment inside the Studio compiler frontend.

Its purpose is to make the stdlib:

• available to the compiler without hardcoded symbol tables,
• structured as real PBS interface modules,
• versioned by stdlib major line,
• and loadable through explicit compiler abstractions.

This document complements the normative language-level model in:

• 5. Manifest, Stdlib, and SDK Resolution Specification.md

2. Scope

This document defines:

• the recommended Studio packaging layout for stdlib interface modules,
• the logical mapping between stdlib line, reserved project space, and module path,
• the minimum compiler abstractions required to load stdlib modules,
• the relationship between resources packaging and the logical stdlib environment.

This document does not define:

• runtime loader behavior,
• PBX emission,
• registry publication of stdlib packs,
• final external distribution of stdlib outside Studio.

3. Core Model

The compiler must load stdlib modules as real interface modules, not as hardcoded built-ins.

Rules:

• the stdlib is selected by the root project's stdlib major,
• each stdlib line defines one stdlib environment,
• a stdlib environment exposes reserved project spaces such as @sdk:* and @core:*,
• each reserved project space contains one or more modules,
• each module is represented as PBS source plus mod.barrel.

4. Recommended Studio Packaging Layout

The recommended Studio layout is:

prometeu-compiler/frontends/prometeu-frontend-pbs/
  src/main/resources/
    stdlib/
      1/
        sdk/
          gfx/
            main.pbs
            mod.barrel
          audio/
            main.pbs
            mod.barrel
        core/
          math/
            main.pbs
            mod.barrel

Interpretation:

• stdlib/1 selects stdlib major line 1,
• sdk and core are reserved project spaces,
• gfx, audio, math are module paths within those reserved spaces,
• main.pbs and mod.barrel form the interface module contents.

5. Logical Mapping

The compiler must treat the physical layout as a logical stdlib environment.

Required mapping:

• stdlib/<N>/sdk/gfx -> @sdk:gfx
• stdlib/<N>/sdk/audio -> @sdk:audio
• stdlib/<N>/core/math -> @core:math
• stdlib/<N>/core/math/vector -> @core:math/vector

Rules:

• physical storage is an implementation detail,
• logical module identity is authoritative,
• callers of the resolver should work with logical addresses such as @sdk:gfx, not resource paths.

6. Module File Convention

For the Studio implementation, each stdlib module should follow the same structural convention as ordinary PBS modules:

• one or more .pbs files,
• exactly one mod.barrel.

Recommended minimum convention:

• main.pbs
• mod.barrel

Rules:

• main.pbs is a convention, not a language-level requirement,
• the module remains an ordinary PBS module from the parser's perspective,
• it is interpreted under interface-module semantics because it lives in a reserved stdlib project space.

7. Required Compiler Abstractions

The compiler should not reach directly into resources paths throughout the frontend.

At minimum, the PBS frontend should define abstractions equivalent to:

7.1 StdlibEnvironment

Responsibility:

• represent the selected stdlib line for one compilation,
• expose reserved project spaces,
• provide access to interface modules by logical module address.

Minimum operations:

• select stdlib major line,
• answer whether a reserved project space exists,
• open a module by logical address.

7.2 StdlibModuleResolver

Responsibility:

• resolve logical imports in reserved project spaces,
• map @sdk:* and @core:* imports to concrete interface module sources,
• reject unknown stdlib modules deterministically.

Minimum operations:

• resolve(@sdk:gfx)
• resolve(@core:math/vector)

7.3 StdlibModuleSource

Responsibility:

• represent the source files of one stdlib module,
• provide access to the module's .pbs files and mod.barrel,
• hide whether content came from disk, resources, or another source.

Minimum contents:

• module address
• list of .pbs source texts or streams
• mod.barrel source text or stream

7.4 InterfaceModuleLoader

Responsibility:

• parse a stdlib module source using the normal PBS parser,
• validate it in interface-module mode,
• return compiler-facing symbols and metadata.

Minimum outputs:

• exported symbols
• declared types
• host owners
• host method signatures
• reserved attribute metadata such as [Host(...)]

8. Loading Algorithm

The recommended Studio compiler flow is:

1. read the root prometeu.json,
2. parse and normalize stdlib,
3. construct StdlibEnvironment for that stdlib major,
4. create a StdlibModuleResolver,
5. when an import targets a reserved project space, resolve it through the stdlib resolver,
6. obtain a StdlibModuleSource,
7. parse the module with the standard PBS parser,
8. validate it under interface-module semantic rules,
9. cache the resulting interface module graph for the duration of the compilation.

Rules:

• reserved stdlib modules must not be handled through ordinary dependency resolution,
• ordinary dependency modules must not be handled through the stdlib resolver,
• a failed stdlib import is a deterministic compile-time error.

9. Attributes and Interface Metadata

Stdlib interface modules may contain reserved compile-time attributes such as:

declare host Gfx {
  [Host(module = "gfx", name = "draw_pixel", version = 1)]
  fn draw_pixel(x: int, y: int, c: color);
}

Rules:

• the parser reads the attribute as part of the interface module source,
• the interface-module loader validates that the attribute is legal in that position,
• the compiler stores the extracted metadata in its interface graph,
• the raw attribute surface is not treated as a runtime object,
• later lowering stages may consume the extracted metadata to produce PBX host-binding declarations.

10. Resources as an Implementation Strategy

For the Studio PBS frontend, packaging stdlib interface modules in frontend resources is a valid implementation strategy.

Rules:

• resources packaging is implementation-level, not language-level,
• the compiler should still access stdlib modules through StdlibEnvironment and related abstractions,
• code outside the stdlib loader should not depend on resource path layout directly.

Rationale:

• resources gives a simple bootstrap path,
• stdlib evolves as real source artifacts,
• the frontend avoids hardcoded built-ins,
• the implementation remains replaceable later.

11. Caching and Reuse

The compiler may cache stdlib interface modules within one compilation or across compilations.

Rules:

• caching must not change observable semantics,
• cache keys should include at least the stdlib major line and logical module address,
• cached modules must preserve the same parsed declarations and attribute metadata as uncached loads.

12. Current Decision Summary

The current Studio direction is:

1. the stdlib environment is loaded as real PBS interface modules,
2. the initial implementation may live under frontend resources,
3. the logical model remains stdlib line -> reserved project space -> module path,
4. the compiler should use explicit abstractions such as StdlibEnvironment and StdlibModuleResolver,
5. stdlib interface modules are parsed with the normal PBS parser and validated in interface-module mode,
6. reserved attributes such as [Host(...)] are extracted as compile-time metadata for later lowering.