12 KiB
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:
This document is PBS packaging. It MUST NOT define console ABI. Intrinsic
final_id values and host SyscallMeta remain runtime-owned. Physical stdlib
path MUST NOT imply VM-owned versus host-backed ownership.
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
resourcespackaging 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
stdlibmajor, - 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/
<target>/
stdlib/
1/
core/
color/
main.pbs
mod.barrel
sdk/
asset/
main.pbs
mod.barrel
composer/
main.pbs
mod.barrel
gfx/
main.pbs
mod.barrel
input/
main.pbs
mod.barrel
log/
main.pbs
mod.barrel
Interpretation:
<target>is theAppModeexport name (gamefor the current line-1 environment),game/stdlib/1selects stdlib major line1for that target,sdkandcoreare reserved project spaces,- current line
1modules arecolor,asset,composer,gfx,input, andlog, main.pbsandmod.barrelform the interface module contents.
Current line 1 MUST NOT be documented as shipping audio or @core:math.
Those names are not packaged in the current environment. @sdk:input is a
VM-owned builtin shell; its path does not make it host-backed.
5. Logical Mapping
The compiler must treat the physical layout as a logical stdlib environment.
Required mapping:
<target>/stdlib/<N>/<space>/<module>->@<space>:<module>
Current line 1 (game) mapping:
game/stdlib/1/core/color->@core:colorgame/stdlib/1/sdk/asset->@sdk:assetgame/stdlib/1/sdk/composer->@sdk:composergame/stdlib/1/sdk/gfx->@sdk:gfxgame/stdlib/1/sdk/input->@sdk:inputgame/stdlib/1/sdk/log->@sdk:log
Rules:
- physical storage is an implementation detail,
- logical module identity is authoritative,
- callers of the resolver should work with logical addresses such as
@sdk:gfxand@core:color, not resource paths, - physical path MUST NOT imply VM-owned versus host-backed ownership.
6. Module File Convention
For the Studio implementation, each stdlib module should follow the same structural convention as ordinary PBS modules:
- one or more
.pbsfiles, - exactly one
mod.barrel.
Recommended minimum convention:
main.pbsmod.barrel
Rules:
main.pbsis 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(@sdk:composer)resolve(@sdk:input)resolve(@core:color)
7.3 StdlibModuleSource
Responsibility:
- represent the source files of one stdlib module,
- provide access to the module's
.pbsfiles andmod.barrel, - hide whether content came from disk,
resources, or another source.
Minimum contents:
- module address
- list of
.pbssource texts or streams mod.barrelsource 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:
- read the root
prometeu.json, - parse and normalize
stdlib, - construct
StdlibEnvironmentfor that stdlib major, - create a
StdlibModuleResolver, - when an import targets a reserved project space, resolve it through the stdlib resolver,
- obtain a
StdlibModuleSource, - parse the module with the standard PBS parser,
- validate it under interface-module semantic rules,
- 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 = "gfx2d", name = "draw_pixel", version = 1)]
fn draw_pixel(x: int, y: int, c: color);
}
or:
declare host LowAssets {
[Host(module = "asset", name = "load", version = 1)]
[Capability(name = "asset")]
[AssetLowering(param = 0)]
fn load(addressable: Addressable, slot: int) -> (status: int, loading_handle: int);
}
or:
declare host LowComposer {
[Host(module = "composer", name = "emit_sprite", version = 1)]
[Capability(name = "composer")]
fn emit_sprite(
glyph_id: int,
palette_id: int,
x: int,
y: int,
layer: int,
bank_id: int,
flip_x: bool,
flip_y: bool,
priority: int
) -> int;
}
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.
- stdlib line
1MUST expose the sprite-composition interface module at@sdk:composer, - that module MUST declare
LowComposerand public serviceComposer, - that module MUST use runtime module
composerand capabilitycomposer, - that module MUST expose
bind_scene(scene_bank_id: int) -> int, - that module MUST expose
unbind_scene() -> int, - that module MUST expose
emit_sprite(glyph_id: int, palette_id: int, x: int, y: int, layer: int, bank_id: int, flip_x: bool, flip_y: bool, priority: int) -> int, - stdlib line
1MUST NOT exposeGfx.set_sprite, - stdlib line
1MUST expose the low-level asset interface module at@sdk:asset, - that module MUST declare
LowAssets, - that module MUST use runtime module
assetand capabilityasset, - that module MUST use the runtime-aligned signatures and reserved lowering metadata:
load(addressable: Addressable, slot: int) -> (status: int, loading_handle: int)together with[AssetLowering(param = 0)]status(loading_handle: int) -> intcommit(loading_handle: int) -> intcancel(loading_handle: int) -> int
10. Resources as an Implementation Strategy
For the Studio PBS frontend, packaging stdlib interface modules in frontend resources is a valid implementation strategy.
Rules:
resourcespackaging is implementation-level, not language-level,- the compiler should still access stdlib modules through
StdlibEnvironmentand related abstractions, - code outside the stdlib loader should not depend on resource path layout directly.
Rationale:
resourcesgives 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:
- the stdlib environment is loaded as real PBS interface modules,
- the initial implementation may live under frontend
resources, - the logical model remains
stdlib line -> reserved project space -> module path, - the compiler should use explicit abstractions such as
StdlibEnvironmentandStdlibModuleResolver, - stdlib interface modules are parsed with the normal PBS parser and validated in interface-module mode,
- reserved attributes such as
[Host(...)]are extracted as compile-time metadata for later lowering.
13. Installed Language and SDK Reference Bundle
The PBS frontend distribution MUST provide local, indexed documentation through the frontend reference-provider contract. This packaging does not create a new normative specification: the numbered PBS documents in their owner directory remain authoritative, and the quickstart/example remain informative.
The build MUST generate the reference index from owner-maintained sources:
- this directory's numbered specifications and README quickstart;
- the frontend's example manifest, PBS source and barrel;
- the actual packaged SDK
.pbsand.barrelfiles, including their documentation.
Generated copies MUST NOT be edited independently. SDK declarations MUST NOT be rewritten to manufacture a documentation-only API. The index MUST contain stable reference identities, titles, kinds, packaged-resource identities, content hashes and applicable SDK major/target. The loader MUST reject missing/corrupted indexed content instead of advertising unreadable references or consulting a checkout.
For the current distribution, SDK/example selection is Game / major 1. The general PBS specifications remain available for other selections, but Game SDK 1 references MUST NOT be presented as another SDK version or target. An absent SDK reference set MUST be explicit to consumers.
Language, compiler, SDK and index-schema versions remain independent. General specification references use an unknown release version when owner release metadata is absent; SDK-associated references identify the installed SDK major. Content hashes identify the packaged texts, not a semantic language release.
Conformance MUST include reading all indexed references from installed JARs outside the repository and compiling the shipped example against the installed SDK. No network access or source checkout may be required by that reference-read path.