discussion framework migration
This commit is contained in:
+251
@@ -0,0 +1,251 @@
|
||||
# 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](/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/studio/docs/specs/pbs/5.%20Manifest,%20Stdlib,%20and%20SDK%20Resolution%20Specification.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:
|
||||
|
||||
```text
|
||||
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:
|
||||
|
||||
```pbs
|
||||
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.
|
||||
Reference in New Issue
Block a user