discussion framework migration
This commit is contained in:
@@ -0,0 +1,94 @@
|
||||
# PBS Language Charter
|
||||
|
||||
Status: Draft v1
|
||||
Applies to: Prometeu Base Script (PBS) language design
|
||||
|
||||
## 1. Mission
|
||||
|
||||
PBS exists to make 2D game development on Prometeu intuitive for beginners and reliable for experienced developers, without sacrificing deterministic runtime behavior.
|
||||
|
||||
## 2. Product Vision
|
||||
|
||||
PBS is a game-first language for a logical, evolving hardware platform.
|
||||
It must feel fluid for frame-driven gameplay code while remaining strict enough to produce stable, verifiable bytecode for a closed VM target.
|
||||
|
||||
## 3. Target Users
|
||||
|
||||
- Beginner creators building their first playable 2D games.
|
||||
- Intermediate developers shipping complete games with predictable behavior.
|
||||
- Advanced developers who need explicit control of architecture and performance costs.
|
||||
|
||||
## 4. Core Principles
|
||||
|
||||
1. Game-first ergonomics: common gameplay patterns must be concise.
|
||||
2. Determinism first: same program + same inputs/events => same behavior.
|
||||
3. Explicit boundaries: host interaction, costs, and side effects must be visible.
|
||||
4. Safe defaults: simple code paths should be hard to misuse.
|
||||
5. Progressive power: advanced control is opt-in, not mandatory.
|
||||
6. Compatibility discipline: language evolution must not silently break cartridges.
|
||||
|
||||
## 5. Scope of PBS v1
|
||||
|
||||
- Stable core syntax and grammar contract.
|
||||
- Static and dynamic semantics for deterministic game code.
|
||||
- Toolchain-managed host binding model aligned with syscall/capability model.
|
||||
- Module visibility and import model suitable for multi-file game projects.
|
||||
- Diagnostics and conformance requirements for interoperable implementations.
|
||||
|
||||
## 6. Out of Scope for PBS v1
|
||||
|
||||
- New VM opcodes as a language requirement.
|
||||
- Non-deterministic async execution models.
|
||||
- Mandatory custom allocator model replacing runtime GC.
|
||||
- Explicit lifetime-control syntax before an explicit future design and profile activation.
|
||||
- User-authored declaration of canonical host primitive bindings outside reserved SDK/toolchain `declare host` surfaces.
|
||||
|
||||
## 7. Non-Negotiable Constraints
|
||||
|
||||
- Runtime and bytecode authority override language preferences.
|
||||
- Closed VM compatibility is mandatory.
|
||||
- `FRAME_SYNC`-based execution semantics are preserved.
|
||||
- Host API usage remains capability-gated and versioned.
|
||||
- Canonical host primitive bindings remain reserved to SDK/toolchain-controlled `declare host` surfaces.
|
||||
|
||||
## 8. Evolution Commitments
|
||||
|
||||
- Additive-first evolution for minor releases.
|
||||
- Incompatible changes only in major lines with migration guidance.
|
||||
- Canonical host primitive versioning by `(module, name, version)`.
|
||||
- User-facing host-backed APIs evolve through SDK/stdlib surfaces, not direct user-authored host-binding declarations outside reserved `declare host` modules.
|
||||
- Deterministic loader rejection when target contracts are unsupported.
|
||||
|
||||
## 9. Quality Bar
|
||||
|
||||
PBS is considered healthy only if:
|
||||
|
||||
- newcomers can produce a working 2D game loop quickly,
|
||||
- generated behavior is deterministic and replayable,
|
||||
- diagnostics are stable and actionable,
|
||||
- performance risks are visible in tooling,
|
||||
- older supported cartridges keep running across updates.
|
||||
|
||||
## 10. Required Spec Set Before Implementation
|
||||
|
||||
Before implementation starts, PBS must define at least:
|
||||
|
||||
1. Core Syntax Specification.
|
||||
2. Static Semantics Specification.
|
||||
3. Dynamic Semantics Specification.
|
||||
4. Memory and Lifetime Specification.
|
||||
5. Host ABI Binding Specification.
|
||||
6. Module/Package Specification.
|
||||
7. AST Specification.
|
||||
8. Diagnostics Specification.
|
||||
9. Lowering IRBackend Specification.
|
||||
10. Shared acceptance specs in `docs/general/specs` (Conformance, Compatibility, Verification).
|
||||
|
||||
## 11. Decision Rule
|
||||
|
||||
When trade-offs appear, decisions must prioritize, in order:
|
||||
|
||||
1. Determinism and compatibility.
|
||||
2. Clarity for beginners.
|
||||
3. Fluency for real game workflows.
|
||||
4. Performance transparency for advanced users.
|
||||
@@ -0,0 +1,341 @@
|
||||
# PBS Memory and Lifetime Specification
|
||||
|
||||
Status: Draft v1 (Temporary)
|
||||
Applies to: runtime memory spaces, value representation classes, identity, aliasing, GC baseline, host-memory boundaries, and cost visibility in PBS core
|
||||
|
||||
## 1. Purpose
|
||||
|
||||
This document defines the authoritative PBS memory and lifetime model for v1.
|
||||
|
||||
Its purpose is to make the language's runtime storage model explicit enough that:
|
||||
|
||||
- implementations agree on the current core value categories,
|
||||
- identity and aliasing are not left implicit,
|
||||
- GC remains compatible with deterministic execution,
|
||||
- the VM heap and host-owned memory boundary stay understandable,
|
||||
- tooling can surface runtime-visible memory and allocation costs consistently.
|
||||
|
||||
## 2. Scope
|
||||
|
||||
This document defines:
|
||||
|
||||
- runtime memory spaces relevant to PBS user semantics,
|
||||
- value categories and their representation classes,
|
||||
- identity, aliasing, and copy behavior,
|
||||
- baseline GC guarantees and non-guarantees,
|
||||
- host-memory boundary rules,
|
||||
- memory-related safety invariants and remaining runtime failure boundaries,
|
||||
- hooks that later diagnostics and tooling may rely on for cost reporting.
|
||||
|
||||
This document does not define:
|
||||
|
||||
- exact GC algorithm internals,
|
||||
- general-purpose allocator APIs,
|
||||
- future explicit lifetime syntax activation,
|
||||
- final IR lowering details,
|
||||
- subsystem-specific host resource APIs.
|
||||
|
||||
## 3. Authority and Precedence
|
||||
|
||||
Normative precedence:
|
||||
|
||||
1. Runtime authority (`docs/specs/hardware/topics/chapter-2.md`, `chapter-3.md`, `chapter-9.md`, `chapter-12.md`, `chapter-16.md`)
|
||||
2. Bytecode authority (`docs/specs/bytecode/ISA_CORE.md`)
|
||||
3. `1. Language Charter.md`
|
||||
4. `3. Core Syntax Specification.md`
|
||||
5. `4. Static Semantics Specification.md`
|
||||
6. `9. Dynamic Semantics Specification.md`
|
||||
7. This document
|
||||
|
||||
If a rule here conflicts with higher authority, it is invalid.
|
||||
|
||||
## 4. Normative Inputs
|
||||
|
||||
This document depends on, at minimum:
|
||||
|
||||
- `1. Language Charter.md`
|
||||
- `3. Core Syntax Specification.md`
|
||||
- `4. Static Semantics Specification.md`
|
||||
- `9. Dynamic Semantics Specification.md`
|
||||
|
||||
This document integrates the following accepted decisions:
|
||||
|
||||
- `docs/pbs/decisions/Value Representation and Identity Decision.md`
|
||||
- `docs/pbs/decisions/GC and Reachability Decision.md`
|
||||
- `docs/pbs/decisions/Host Memory Boundary Decision.md`
|
||||
- `docs/pbs/decisions/Allocation and Cost Visibility Decision.md`
|
||||
- `docs/pbs/decisions/Lifetime Control and Future Profiles Decision.md`
|
||||
|
||||
## 5. Already-Settled Inputs
|
||||
|
||||
The following inputs are already fixed elsewhere and must not be contradicted here:
|
||||
|
||||
- Struct values are reference-like and identity-bearing in v1 core.
|
||||
- Service values are canonical module-owned singleton values in v1 core.
|
||||
- `declare const` values are compile-time constants rather than mutable runtime module storage.
|
||||
- `FRAME_SYNC` is the only normative safepoint in PBS v1.
|
||||
- Core PBS v1 does not expose explicit lifetime-control syntax in ordinary user code.
|
||||
|
||||
## 6. Runtime Memory Spaces
|
||||
|
||||
PBS v1 distinguishes, at minimum:
|
||||
|
||||
1. VM-managed runtime storage used for GC-managed values and retained runtime state.
|
||||
2. Stack-like transient value flow used for ordinary value exchange during evaluation.
|
||||
3. Host-owned memory and resources that remain outside ordinary PBS userland memory semantics.
|
||||
|
||||
The VM heap and host-owned memory remain distinct in the user model.
|
||||
|
||||
Cross-boundary host/userland interaction is value-based rather than memory-sharing-based.
|
||||
|
||||
## 7. Value Representation Classes
|
||||
|
||||
### 7.1 Pure copied values
|
||||
|
||||
The following value kinds are pure copied values in the user model:
|
||||
|
||||
- `int`
|
||||
- `float`
|
||||
- `bool`
|
||||
- enum values
|
||||
- canonical `str`
|
||||
|
||||
Assignment, parameter passing, and return of these values copy the value itself.
|
||||
|
||||
### 7.2 Identity-bearing values
|
||||
|
||||
The following value kinds carry stable user-visible identity:
|
||||
|
||||
- struct values
|
||||
- service values
|
||||
- host-backed resource values on the PBS side
|
||||
|
||||
Assignment, parameter passing, and return of these values preserve aliasing to the same runtime entity rather than copying an independent underlying object.
|
||||
|
||||
### 7.3 Carrier-only values
|
||||
|
||||
The following value kinds are carriers and do not introduce identity of their own:
|
||||
|
||||
- tuples
|
||||
- `optional`
|
||||
- `result`
|
||||
|
||||
If a carrier contains an identity-bearing payload, the carrier transports that same payload identity rather than inventing a new one.
|
||||
|
||||
### 7.4 Contract values
|
||||
|
||||
Contract values do not introduce a new user-visible identity distinct from the underlying struct or service value.
|
||||
|
||||
They are runtime views over an underlying identity-bearing value together with the selected contract implementation used for dispatch.
|
||||
|
||||
### 7.5 Callback values
|
||||
|
||||
Callback values are first-class callable values in PBS v1.
|
||||
|
||||
They may be assigned, passed, and returned, but callback identity is not promoted as a separate user-visible identity concept.
|
||||
|
||||
When formed through `bind(context, fn_name)`, a callback value retains:
|
||||
|
||||
- the target function,
|
||||
- and the same captured struct context identity without copying it.
|
||||
|
||||
## 8. Identity, Aliasing, and Copy Behavior
|
||||
|
||||
### 8.1 Structs
|
||||
|
||||
Struct values are always reference-like in PBS v1.
|
||||
|
||||
Rules:
|
||||
|
||||
- `new Struct(...)` produces a fresh struct identity.
|
||||
- Assignment of a struct value copies the reference, not the underlying field storage.
|
||||
- Passing or returning a struct value preserves aliasing to the same struct instance.
|
||||
- Mutation through one alias is observable through other aliases to that same struct instance.
|
||||
|
||||
### 8.2 Services
|
||||
|
||||
Service values denote the same canonical singleton identity wherever used in the same resolved program.
|
||||
|
||||
Assignment, parameter passing, and return preserve that same singleton identity.
|
||||
|
||||
### 8.3 Carriers
|
||||
|
||||
`optional`, `result`, and tuples preserve the semantics of their contained values.
|
||||
|
||||
Examples:
|
||||
|
||||
- assigning an `optional<Player>` that contains `some(player)` preserves the same `Player` identity inside the carrier,
|
||||
- assigning a `result<E> Player` success payload preserves the same `Player` identity inside the carrier.
|
||||
|
||||
### 8.4 General rule
|
||||
|
||||
The general rule for PBS v1 is:
|
||||
|
||||
- pure value kinds are copied by value,
|
||||
- identity-bearing kinds preserve aliasing,
|
||||
- carrier kinds preserve the semantics of their contained values and do not create identity of their own.
|
||||
|
||||
## 9. GC Baseline
|
||||
|
||||
### 9.1 Reachability
|
||||
|
||||
GC is the baseline runtime model for VM-owned memory in PBS core.
|
||||
|
||||
For GC-managed VM-owned values, liveness is defined by reachability from the runtime roots that matter to PBS semantics.
|
||||
|
||||
At minimum, those roots include:
|
||||
|
||||
- currently active local/frame state,
|
||||
- reachable fields of reachable struct instances,
|
||||
- service singleton roots,
|
||||
- retained callback state that remains reachable,
|
||||
- and any other runtime roots required to preserve already-observable PBS behavior.
|
||||
|
||||
If a GC-managed value remains reachable through the normative runtime state, the implementation must preserve its continued semantic availability.
|
||||
|
||||
### 9.2 Reclamation
|
||||
|
||||
PBS v1 guarantees eventual reclamation, not prompt reclamation.
|
||||
|
||||
The language does not promise:
|
||||
|
||||
- immediate reclamation,
|
||||
- reclamation at a specific frame boundary,
|
||||
- or a semantic event when reclamation occurs.
|
||||
|
||||
### 9.3 Safepoint relationship
|
||||
|
||||
`FRAME_SYNC` is the only normative safepoint in PBS v1.
|
||||
|
||||
No user-visible program rule may depend on another safepoint existing.
|
||||
|
||||
Implementations may perform internal GC work outside `FRAME_SYNC` only if doing so creates no additional user-visible semantic effects.
|
||||
|
||||
### 9.4 Observability
|
||||
|
||||
User code cannot observe reclamation directly.
|
||||
|
||||
PBS v1 provides no user-visible mechanism for:
|
||||
|
||||
- detecting that a value was collected,
|
||||
- registering a callback on reclamation,
|
||||
- forcing immediate collection,
|
||||
- sequencing user code against collector timing.
|
||||
|
||||
PBS v1 defines no user-authored finalizers or destructor-like reclamation hooks.
|
||||
|
||||
## 10. Host Memory Boundary
|
||||
|
||||
The host/userland boundary in PBS v1 is value-based rather than memory-sharing-based.
|
||||
|
||||
Cross-boundary interaction between host and PBS userland is restricted to stack-only values.
|
||||
|
||||
PBS userland does not expose host memory as ordinary language values.
|
||||
|
||||
PBS v1 does not expose:
|
||||
|
||||
- raw host pointers,
|
||||
- borrowed host-memory views,
|
||||
- pinning,
|
||||
- zero-copy transfer,
|
||||
- shared heap objects spanning host memory and VM memory.
|
||||
|
||||
Long-lived host resources, if later exposed, must be specified by subsystem contract rather than inferred from a general host-memory-handle model in core PBS.
|
||||
|
||||
## 11. Cost Visibility Hooks
|
||||
|
||||
### 11.1 Normatively relevant cost facts
|
||||
|
||||
The normatively relevant cost facts in PBS v1 are:
|
||||
|
||||
- whether an operation may allocate VM-owned runtime storage,
|
||||
- whether an operation retains state beyond the current evaluation,
|
||||
- whether an operation copies payload versus preserves aliasing,
|
||||
- whether an operation crosses the host boundary,
|
||||
- whether an operation may trap.
|
||||
|
||||
### 11.2 `bind`
|
||||
|
||||
`bind(context, fn_name)` is retention-bearing and requires runtime storage sufficient to preserve:
|
||||
|
||||
- the callback target identity,
|
||||
- the captured context,
|
||||
- and the captured context's continued liveness while the callback value remains alive.
|
||||
|
||||
This document does not freeze the exact runtime layout used to implement that storage.
|
||||
|
||||
### 11.3 Non-allocation-bearing surfaces by themselves
|
||||
|
||||
The following constructs are not allocation-bearing by themselves in PBS v1:
|
||||
|
||||
- `optional`
|
||||
- `result`
|
||||
- `handle`
|
||||
- `!`
|
||||
- `if`
|
||||
- `switch`
|
||||
- `apply`
|
||||
|
||||
If allocation or retention occurs while evaluating one of these constructs, that cost arises from:
|
||||
|
||||
- subexpression evaluation,
|
||||
- called targets,
|
||||
- payload formation already defined elsewhere,
|
||||
- or runtime behavior outside the surface itself.
|
||||
|
||||
### 11.4 Quantitative reporting
|
||||
|
||||
The language does not normatively guarantee:
|
||||
|
||||
- exact byte counts,
|
||||
- exact object counts,
|
||||
- exact collector timing,
|
||||
- exact host-side allocation volume,
|
||||
- precise performance ranking.
|
||||
|
||||
Those belong to diagnostics/profiling quality rather than to the core language contract.
|
||||
|
||||
## 12. Future Lifetime Control Policy
|
||||
|
||||
PBS v1 adopts the following policy:
|
||||
|
||||
- no dormant lifetime-control keyword is preserved merely for speculative future use,
|
||||
- advanced memory workflows should default to library/tooling-first exploration,
|
||||
- future explicit lifetime-oriented syntax, if introduced at all, must be profile-gated and justified by real need rather than by historical inertia.
|
||||
|
||||
Core PBS v1 does not promise future activation of legacy RC/HIP-style syntax.
|
||||
|
||||
## 13. Beginner-Facing Model
|
||||
|
||||
The user-facing explanation should be:
|
||||
|
||||
- some values are plain data, so passing them passes the value,
|
||||
- structs and services are shared entities, so passing them passes access to the same entity,
|
||||
- tuples, `optional`, and `result` only package values and do not become new entities by themselves,
|
||||
- the runtime keeps reachable GC-managed values alive,
|
||||
- the program does not directly hold or manipulate host memory.
|
||||
|
||||
## 14. TODO
|
||||
|
||||
The following items remain editorial or adjacent-spec integration tasks rather than open memory-model agenda questions:
|
||||
|
||||
- subsystem-specific wording for long-lived host resources if those are later introduced,
|
||||
- diagnostics-specific wording for cost warnings and notes,
|
||||
- future profile mechanics if an explicit lifetime profile is ever proposed.
|
||||
|
||||
## 15. Non-Goals
|
||||
|
||||
- Designing full pool, arena, or weak-reference libraries in this pass.
|
||||
- Reintroducing mandatory user-authored lifetime syntax in core v1.
|
||||
- Defining exact collector implementation strategy.
|
||||
- Rewriting already-settled source syntax beyond what is required for consistency with accepted decisions.
|
||||
|
||||
## 16. Exit Criteria
|
||||
|
||||
This document is ready to move beyond temporary draft status only when:
|
||||
|
||||
1. every current core value category has explicit representation and aliasing wording,
|
||||
2. GC guarantees and non-guarantees are separated clearly,
|
||||
3. the VM heap versus host-memory boundary is normatively described,
|
||||
4. memory-related cost facts are specified well enough for diagnostics/tooling hooks,
|
||||
5. the remaining TODO items are reduced to editorial integration or future optional work rather than semantic uncertainty.
|
||||
@@ -0,0 +1,160 @@
|
||||
# PBS AST Specification
|
||||
|
||||
Status: Draft v1
|
||||
Applies to: canonical AST contract emitted by PBS parser/frontend before IRBackend lowering
|
||||
|
||||
## 1. Purpose
|
||||
|
||||
This document defines the mandatory AST contract between PBS parsing and frontend lowering to `IRBackend`.
|
||||
|
||||
The contract is obligations-first: implementations may choose any internal representation, but must expose equivalent observable AST behavior and invariants.
|
||||
|
||||
## 2. Scope
|
||||
|
||||
This document defines:
|
||||
|
||||
- AST root and ordering invariants,
|
||||
- mandatory node families for declarations, statements, and expressions in the supported v1 slice,
|
||||
- mandatory node attribution and declaration metadata,
|
||||
- deterministic rejection and recovery boundaries,
|
||||
- and Gate U evidence obligations for AST conformance.
|
||||
|
||||
This document does not define:
|
||||
|
||||
- static-semantics algorithms,
|
||||
- runtime/bytecode/verifier behavior,
|
||||
- or `IRBackend -> IRVM` lowering.
|
||||
|
||||
## 3. Authority and Precedence
|
||||
|
||||
Normative precedence:
|
||||
|
||||
1. `3. Core Syntax Specification.md`
|
||||
2. `4. Static Semantics Specification.md`
|
||||
3. `12. Diagnostics Specification.md`
|
||||
4. This document
|
||||
5. `13. Lowering IRBackend Specification.md`
|
||||
|
||||
If a rule here conflicts with a higher-precedence source, the higher-precedence rule wins.
|
||||
|
||||
## 4. Normative Inputs
|
||||
|
||||
This document depends on:
|
||||
|
||||
- `3. Core Syntax Specification.md`
|
||||
- `4. Static Semantics Specification.md`
|
||||
- `12. Diagnostics Specification.md`
|
||||
- `13. Lowering IRBackend Specification.md`
|
||||
|
||||
## 5. AST Contract Model
|
||||
|
||||
The AST contract is defined by required observable behavior, not by one mandatory class hierarchy or parser architecture.
|
||||
|
||||
Conformance is implementation-language agnostic.
|
||||
|
||||
## 6. Root and Structural Invariants
|
||||
|
||||
Parser output must satisfy all of the following:
|
||||
|
||||
1. exactly one AST root per source file;
|
||||
2. deterministic child ordering consistent with source order;
|
||||
3. preserved declaration and lexical block hierarchy;
|
||||
4. parent/child span integrity (no structurally impossible attribution relationships);
|
||||
5. no post-parse AST rewrite that changes source-observable parse meaning.
|
||||
|
||||
## 7. Mandatory Attribution and Declaration Metadata
|
||||
|
||||
Every node consumed by diagnostics or lowering must carry stable source attribution:
|
||||
|
||||
- `file`,
|
||||
- `start`,
|
||||
- `end`.
|
||||
|
||||
Mandatory declaration metadata on required declaration nodes includes:
|
||||
|
||||
1. declaration name,
|
||||
2. declared signature/surface when applicable (parameters/return),
|
||||
3. declaration-level syntactic flags/attributes required by later phases,
|
||||
4. stable `file/start/end` attribution.
|
||||
|
||||
Missing required attribution or metadata on mandatory nodes is non-conformant.
|
||||
|
||||
## 8. Mandatory Declaration Families
|
||||
|
||||
The v1 AST must represent, at minimum, declaration families for:
|
||||
|
||||
- imports,
|
||||
- top-level `fn`,
|
||||
- `struct`,
|
||||
- `contract`,
|
||||
- `service`,
|
||||
- `error`,
|
||||
- `enum`,
|
||||
- `callback`,
|
||||
- `declare const`,
|
||||
- and declaration nodes required by barrel/linking flow.
|
||||
|
||||
Declaration identity must be preserved at AST boundary; implementations must not prematurely merge/collapse declarations (including overload sets).
|
||||
|
||||
## 9. Mandatory Statement and Expression Families
|
||||
|
||||
The v1 AST must represent statement/expression families for the supported core syntax slice, including at minimum:
|
||||
|
||||
- statements: `block`, `let`, `return`, expression statement;
|
||||
- expressions: `identifier`, literals, `unary`, `binary`, `call`, `group`.
|
||||
|
||||
Additional supported forms required by `3` are also in scope for explicit node representation.
|
||||
|
||||
## 10. Precedence, Associativity, and Rejection
|
||||
|
||||
Precedence and associativity outcomes are normative through AST shape.
|
||||
|
||||
Rules:
|
||||
|
||||
1. accepted forms must preserve parse outcome explicitly in AST shape;
|
||||
2. non-associative or forbidden chained forms are deterministic reject with stable diagnostics;
|
||||
3. unsupported forms outside the active source slice are deterministic reject;
|
||||
4. unsupported/invalid forms must not be masked by permissive synthetic nodes that imply accepted semantics.
|
||||
|
||||
## 11. Recovery and Diagnostics Integration
|
||||
|
||||
Parser recovery may continue after syntax errors for diagnostic collection, but recovered AST must remain:
|
||||
|
||||
- structurally coherent,
|
||||
- attribution-consistent,
|
||||
- and non-permissive (must not fabricate valid semantics that hide required rejection).
|
||||
|
||||
AST-facing diagnostics must follow `12` identity and attribution rules.
|
||||
|
||||
For conformance, required diagnostic identity is keyed by stable machine fields, not rendered sentence text.
|
||||
|
||||
## 12. Conformance and Gate U Evidence
|
||||
|
||||
AST conformance evidence is provided through Gate U fixtures as defined in `docs/general/specs/13. Conformance Test Specification.md`.
|
||||
|
||||
At minimum, Gate U must include:
|
||||
|
||||
1. representative valid AST fixtures for mandatory declaration/statement/expression families;
|
||||
2. malformed/recovery fixtures with deterministic rejection assertions;
|
||||
3. attribution assertions (`file/start/end`) on required nodes;
|
||||
4. precedence/associativity shape assertions for representative expressions;
|
||||
5. mandatory negative families:
|
||||
- unexpected token in declaration context,
|
||||
- missing required closer (`)`, `}`, or `;`) as applicable,
|
||||
- forbidden non-associative chains,
|
||||
- unsupported forms outside the active syntax slice.
|
||||
|
||||
## 13. Non-Goals
|
||||
|
||||
- Freezing one parser implementation architecture.
|
||||
- Replacing static semantics/linking decisions with AST-only rules.
|
||||
- Defining backend/runtime/bytecode/verifier behavior.
|
||||
|
||||
## 14. Exit Criteria
|
||||
|
||||
This document is healthy when:
|
||||
|
||||
1. mandatory AST families and metadata are explicit,
|
||||
2. recovery/rejection invariants are explicit and test-backed,
|
||||
3. attribution invariants are explicit and test-backed,
|
||||
4. lowering preconditions consumed by `13` are unambiguous.
|
||||
@@ -0,0 +1,243 @@
|
||||
# PBS Diagnostics Specification
|
||||
|
||||
Status: Draft v1
|
||||
Applies to: deterministic diagnostics emitted by PBS-facing tooling across parsing, static analysis, manifest/import resolution, linking, host-admission checks, and load-facing validation surfaces
|
||||
|
||||
## 1. Purpose
|
||||
|
||||
This document defines the PBS diagnostics baseline for v1.
|
||||
|
||||
Its purpose is to make diagnostics stable enough that:
|
||||
|
||||
- conforming tools report failures in the same phases,
|
||||
- users receive deterministic and actionable source-facing feedback,
|
||||
- diagnostics remain machine-identifiable even when rendered in different locales,
|
||||
- conformance can validate rejection class and attribution,
|
||||
- and frontend, linking, manifest, and load-facing validation remain aligned.
|
||||
|
||||
## 2. Scope
|
||||
|
||||
This document defines:
|
||||
|
||||
- the required external diagnostic phases,
|
||||
- the minimum machine-readable identity of a PBS-facing diagnostic,
|
||||
- the minimum source-facing payload and attribution baseline,
|
||||
- the boundary between normative diagnostic fields and implementation-defined rendering,
|
||||
- the boundary between PBS-facing diagnostics and artifact/tooling failures,
|
||||
- and the warning/cost-diagnostics boundary for v1.
|
||||
|
||||
This document does not define:
|
||||
|
||||
- a full runtime trap catalog,
|
||||
- UI presentation or IDE styling,
|
||||
- one exact localized sentence for every diagnostic,
|
||||
- one transport-specific schema such as LSP field mapping,
|
||||
- one standardized source-map or artifact-offset format,
|
||||
- or profiling/reporting formats.
|
||||
|
||||
## 3. Authority and Precedence
|
||||
|
||||
Normative precedence:
|
||||
|
||||
1. `1. Language Charter.md`
|
||||
2. `3. Core Syntax Specification.md`
|
||||
3. `4. Static Semantics Specification.md`
|
||||
4. `5. Manifest, Stdlib, and SDK Resolution Specification.md`
|
||||
5. `6.2. Host ABI Binding and Loader Resolution Specification.md`
|
||||
6. `7. Cartridge Manifest and Runtime Capabilities Specification.md`
|
||||
7. `9. Dynamic Semantics Specification.md`
|
||||
8. `10. Memory and Lifetime Specification.md`
|
||||
9. `13. Lowering IRBackend Specification.md`
|
||||
10. This document
|
||||
|
||||
If a diagnostic rule here contradicts a normative acceptance/rejection rule in a higher-precedence document, the higher-precedence document wins.
|
||||
|
||||
## 4. Normative Inputs
|
||||
|
||||
This document depends on, at minimum:
|
||||
|
||||
- `3. Core Syntax Specification.md`
|
||||
- `4. Static Semantics Specification.md`
|
||||
- `5. Manifest, Stdlib, and SDK Resolution Specification.md`
|
||||
- `6.2. Host ABI Binding and Loader Resolution Specification.md`
|
||||
- `7. Cartridge Manifest and Runtime Capabilities Specification.md`
|
||||
- `9. Dynamic Semantics Specification.md`
|
||||
- `10. Memory and Lifetime Specification.md`
|
||||
- `13. Lowering IRBackend Specification.md`
|
||||
|
||||
Relevant backend-facing integration points also include:
|
||||
|
||||
- `docs/general/specs/15. Bytecode and PBX Mapping Specification.md`
|
||||
- `docs/general/specs/16. Runtime Execution and Initialization Specification.md`
|
||||
- `docs/general/specs/19. Verification and Safety Checks Specification.md`
|
||||
|
||||
## 5. Already-Settled Inputs
|
||||
|
||||
The following inputs are already fixed elsewhere and must not be contradicted here:
|
||||
|
||||
- The syntax specification already enumerates minimum required syntax diagnostics.
|
||||
- The static semantics specification already enumerates minimum required static diagnostics.
|
||||
- Manifest/import resolution failures are required to be deterministic compile-time errors.
|
||||
- Loader failures around malformed or unauthorized host usage are required to be deterministic.
|
||||
- Stable source span metadata is required at the token level and must remain useful to later diagnostics.
|
||||
- Traps are fatal runtime outcomes rather than a recoverable userland diagnostic flow.
|
||||
- Qualitative cost facts such as retention-bearing operations and host-boundary crossings are normative, but quantitative performance metrics are not.
|
||||
|
||||
## 6. Required Diagnostic Phases
|
||||
|
||||
PBS-facing tooling must distinguish at least the following external diagnostic phases:
|
||||
|
||||
1. `syntax`,
|
||||
2. `static semantics`,
|
||||
3. `manifest/import resolution`,
|
||||
4. `linking`,
|
||||
5. `host-binding/capability admission`,
|
||||
6. `load-facing rejection` when directly attributable to malformed or unauthorized PBS-facing artifact usage.
|
||||
|
||||
`linking` is a first-class phase in the external diagnostics contract and must not be collapsed away into a generic resolution bucket.
|
||||
|
||||
This document does not require one finer-grained public phase split for verifier internals, artifact offsets, or transport-specific backend stages beyond what is stated here.
|
||||
|
||||
## 7. Required Diagnostic Identity, Payload, and Attribution
|
||||
|
||||
Every PBS-facing diagnostic must expose a stable machine-readable identity.
|
||||
|
||||
At minimum, every required source-facing diagnostic must include:
|
||||
|
||||
1. `diagnostic code`,
|
||||
2. `severity`,
|
||||
3. `phase`,
|
||||
4. `primary file`,
|
||||
5. `primary span/location`,
|
||||
6. `message template id`,
|
||||
7. stable named placeholders for that template when applicable,
|
||||
8. and a rendered human-readable message.
|
||||
|
||||
The stable identity of a diagnostic is carried primarily by:
|
||||
|
||||
- `diagnostic code`,
|
||||
- stable phase attribution,
|
||||
- `message template id`,
|
||||
- primary attribution,
|
||||
- and the rejection-class semantics represented by the code/template pair.
|
||||
|
||||
Human wording alone is not the identity of the diagnostic.
|
||||
|
||||
Conformance assertions must key diagnostics by stable machine fields (`code`, `phase`, `message template id`, attribution), not by localized rendered sentence text.
|
||||
|
||||
## 8. Cross-File Attribution, Notes, and Hint Surface
|
||||
|
||||
Cross-file attribution follows an action-first rule.
|
||||
|
||||
Rules:
|
||||
|
||||
- import failures must point primarily to the importing site,
|
||||
- barrel failures must point primarily to the barrel site or entry that triggered the failure,
|
||||
- linking and cross-module lookup failures must point primarily to the use or reference site that could not be resolved,
|
||||
- related sites may be attached when known,
|
||||
- and `duplicate` or `conflict` diagnostics must include at least one related site.
|
||||
|
||||
`notes` are optional by default in v1 except where another rule explicitly requires related-location reporting.
|
||||
|
||||
The stable visible categories currently reserved are:
|
||||
|
||||
- `error`,
|
||||
- `warning`,
|
||||
- `note`,
|
||||
- `hint`.
|
||||
|
||||
`hint` is part of the diagnostics model in v1, but hint content is not mandatory.
|
||||
|
||||
## 9. Wording, Templates, and Localization
|
||||
|
||||
Rendered wording does not need to be byte-for-byte identical across implementations or locales.
|
||||
|
||||
However:
|
||||
|
||||
- the rendered message must preserve the same normative rejection meaning,
|
||||
- the rendered message must not contradict the governing spec rule,
|
||||
- and the code/template/placeholder contract must remain stable.
|
||||
|
||||
This allows implementations to localize diagnostics while preserving conformance-friendly identity.
|
||||
|
||||
Human-readable messages may be rendered from locale-specific templates, but template/token identity remains stable across locales.
|
||||
|
||||
Implementations should preserve the ability to render an English default or fallback message for future interoperability-oriented transports such as a possible LSP integration, even when the local product surface renders another language by default.
|
||||
|
||||
Examples in this specification are illustrative unless explicitly marked normative.
|
||||
|
||||
`help` or guided remediation is outside the minimum mandatory contract in v1.
|
||||
|
||||
## 10. Required Diagnostic Coverage and Backend-Originated Failures
|
||||
|
||||
At minimum, the PBS diagnostics baseline must cover:
|
||||
|
||||
1. syntax errors already required by `3. Core Syntax Specification.md`,
|
||||
2. static-semantics errors already required by `4. Static Semantics Specification.md`,
|
||||
3. deterministic manifest and import-resolution failures required by `5. Manifest, Stdlib, and SDK Resolution Specification.md`,
|
||||
4. linking failures required by source-level name-resolution and module-linking rules,
|
||||
5. malformed, unauthorized, or capability-rejected host usage required by `6.2. Host ABI Binding and Loader Resolution Specification.md` and `7. Cartridge Manifest and Runtime Capabilities Specification.md`,
|
||||
6. source-attributable backend-originated failures that remain user-actionable under normative lowering or load-facing rules.
|
||||
7. dependency-scoped fail-fast admission at frontend boundary: when one module is rejected, modules that import it (directly or transitively) must not be emitted, while diagnostics collection for independent modules must continue.
|
||||
|
||||
At minimum, host-admission diagnostics must cover missing or malformed host capability metadata and unknown or undeclared capability names.
|
||||
|
||||
Only backend-originated failures that remain source-attributable and user-actionable belong to the PBS-facing diagnostics contract.
|
||||
|
||||
This means:
|
||||
|
||||
- lowering failures remain in scope when they reflect a normative source-facing lowering rule or impossibility,
|
||||
- verifier or loader failures remain in scope when they are directly attributable to malformed or unauthorized PBS-facing artifact usage already within the PBS contract,
|
||||
- and purely internal compiler exceptions, artifact corruption, or backend-internal failures with no stable user-facing source attribution remain outside the PBS-facing diagnostics contract.
|
||||
|
||||
When a backend-originated failure remains in scope for PBS-facing diagnostics, v1 requires at least one source location but does not require one standardized source-map, artifact-offset, or verifier-trace format.
|
||||
|
||||
Dynamic-semantics traps are not source-level recoverable diagnostics in the ordinary PBS userland model. This document therefore does not require a compile-time diagnostic surface for every possible fatal runtime trap.
|
||||
|
||||
Dependency-scoped fail-fast admission is not equivalent to global build abort.
|
||||
When failures exist, implementations must still preserve deterministic diagnostic identity and attribution for unaffected independent modules processed in the same build.
|
||||
|
||||
## 11. Cost Diagnostics and Warning Policy
|
||||
|
||||
Warnings are supported and recommended in v1, but they are not part of the minimum mandatory conformance baseline.
|
||||
|
||||
Tooling may surface qualitative cost facts as warnings or notes, especially for:
|
||||
|
||||
- retention-bearing `bind`,
|
||||
- observable copy-versus-alias semantics,
|
||||
- and host-boundary crossings.
|
||||
|
||||
The choice between `warning` and `note` is implementation-defined in v1.
|
||||
|
||||
This document does not make a detailed warning taxonomy normative and does not require a warning at every such site.
|
||||
|
||||
Quantitative metrics such as exact byte counts, exact allocation counts, collector timing, or performance ranking remain outside the diagnostics contract and belong to profiling/tooling rather than to language conformance.
|
||||
|
||||
## 12. Current Limits
|
||||
|
||||
The v1 diagnostics contract intentionally leaves the following items outside the currently standardized surface:
|
||||
|
||||
- transport-specific wire formats,
|
||||
- one exact source-map format,
|
||||
- one exact verifier/loader internal reporting shape,
|
||||
- one mandatory warning catalog,
|
||||
- and one mandatory remediation/help-content policy.
|
||||
|
||||
These are not licenses to weaken the required external fields defined above.
|
||||
|
||||
## 13. Non-Goals
|
||||
|
||||
- Mandating one UI or IDE presentation style.
|
||||
- Freezing one exact localization strategy or locale set.
|
||||
- Turning every optimization hint into a normative diagnostic.
|
||||
- Replacing the acceptance/rejection rules already defined elsewhere.
|
||||
- Standardizing profiler output as if it were language law.
|
||||
|
||||
## 14. Exit Criteria
|
||||
|
||||
This document is ready to move beyond temporary status only when:
|
||||
|
||||
1. every required rejection in the current spec set is mapped to a diagnostic phase,
|
||||
2. diagnostic identity, metadata, and attribution rules are explicit enough for conformance, including locale-agnostic token/template identity,
|
||||
3. the backend-originated failure boundary is explicit enough that PBS-facing diagnostics can be distinguished from internal tool failures,
|
||||
4. and cost/warning expectations are explicit where they are intended to be normative for v1.
|
||||
@@ -0,0 +1,210 @@
|
||||
# PBS Lowering IRBackend Specification
|
||||
|
||||
Status: Draft v1 (Frontend Scope + Backend Handoff Addendum)
|
||||
Applies to: first lowering boundary from bound PBS frontend model into `IRBackend`/`IRBackendFile`, plus executable-backend handoff obligations at this boundary
|
||||
|
||||
## 1. Purpose
|
||||
|
||||
This document defines the normative frontend lowering contract from PBS source semantics to `IRBackend`.
|
||||
|
||||
Its purpose is to keep the first lowering deterministic and shared across implementations while PBS and backend design evolve.
|
||||
|
||||
## 2. Scope
|
||||
|
||||
This document defines:
|
||||
|
||||
- required preconditions before lowering starts,
|
||||
- AST invariants that lowering may assume as hard contract,
|
||||
- semantic obligations preserved in `IRBackend`,
|
||||
- deterministic rejection behavior for unsupported frontend-lowering forms,
|
||||
- diagnostics attribution obligations for lowering failures in frontend scope,
|
||||
- and executable-backend handoff obligations at the `IRBackend` boundary.
|
||||
|
||||
This document does not define:
|
||||
|
||||
- VM lowering (`IRVM`),
|
||||
- bytecode/PBX mapping,
|
||||
- runtime execution behavior,
|
||||
- verifier/loader internals.
|
||||
|
||||
Those concerns belong to shared acceptance specs under `docs/general/specs`.
|
||||
|
||||
## 3. Authority and Precedence
|
||||
|
||||
Normative precedence:
|
||||
|
||||
1. `3. Core Syntax Specification.md`
|
||||
2. `4. Static Semantics Specification.md`
|
||||
3. `11. AST Specification.md`
|
||||
4. `12. Diagnostics Specification.md`
|
||||
5. This document
|
||||
|
||||
If a lowering rule here conflicts with higher-precedence syntax/semantics rules, the higher-precedence rule wins.
|
||||
|
||||
## 4. Normative Inputs
|
||||
|
||||
This document depends on:
|
||||
|
||||
- `3. Core Syntax Specification.md`
|
||||
- `4. Static Semantics Specification.md`
|
||||
- `11. AST Specification.md`
|
||||
- `12. Diagnostics Specification.md`
|
||||
- `docs/general/specs/20. IRBackend to IRVM Lowering Specification.md`
|
||||
|
||||
## 5. Lowering Preconditions
|
||||
|
||||
Frontend lowering into `IRBackend` may start only when:
|
||||
|
||||
1. source has been tokenized and parsed,
|
||||
2. required syntax diagnostics have been emitted,
|
||||
3. AST output satisfies `11` required invariants for this source unit, including:
|
||||
- one root per file,
|
||||
- deterministic child ordering,
|
||||
- mandatory node attribution (`file/start/end`) on nodes consumed by lowering,
|
||||
- mandatory declaration metadata on declaration nodes required by the active source slice,
|
||||
- and structural coherence after any parser recovery.
|
||||
4. linking/name-resolution outcomes required for the current lowering slice are available,
|
||||
5. and no unresolved semantic ambiguity is deferred to lowering.
|
||||
|
||||
Lowering must not invent unresolved semantic answers that belong to syntax/static/linking phases.
|
||||
|
||||
## 6. IRBackend Preserved Obligations
|
||||
|
||||
For each admitted source unit and callable in the current lowering slice, `IRBackend` must preserve at minimum:
|
||||
|
||||
1. callable identity (name/category as applicable),
|
||||
2. callable arity,
|
||||
3. declared return surface information,
|
||||
4. source attribution anchor (`file + span`) for diagnostics and traceability,
|
||||
5. source-observable parse intent for statement/expression structure (including precedence/associativity outcome already fixed by AST shape).
|
||||
6. deterministic `requiredCapabilities` derived from admitted host-binding metadata for packer/runtime-manifest assistance.
|
||||
7. frontend-declared executable `EntrypointRef` (`entryPointCallableName` + `entryPointModuleId`) for backend handoff.
|
||||
|
||||
Lowering must not collapse source categories in a way that erases required declaration/callable identity needed by downstream diagnostics or conformance assertions.
|
||||
|
||||
The normative contract is obligation-based, not tied to one mandatory in-memory class graph.
|
||||
|
||||
## 7. Deterministic Rejection Policy
|
||||
|
||||
If a source form is outside current frontend-lowering support:
|
||||
|
||||
1. rejection must be deterministic,
|
||||
2. diagnostics must expose stable `code`, `severity`, `phase`, `message template id`, and primary attribution,
|
||||
3. and unsupported forms must not silently degrade into different valid lowered behavior.
|
||||
|
||||
Lowering must not convert a required syntax/static rejection into accepted lowered behavior.
|
||||
|
||||
For multi-module builds, lowering admission must apply dependency-scoped fail-fast:
|
||||
|
||||
1. a module rejected in syntax, static semantics, linking, host-admission, or load-facing gates must not be emitted;
|
||||
2. any module that imports a rejected module (directly or transitively) must also be excluded from `IRBackend` emission;
|
||||
3. modules independent from the rejected dependency subgraph may continue to lower and emit in the same build.
|
||||
|
||||
## 8. Conformance Boundary
|
||||
|
||||
`IRBackend` is the first lowering boundary (frontend responsibility).
|
||||
|
||||
Conformance-valid claims at this boundary require Gate U evidence from `docs/general/specs/13. Conformance Test Specification.md`.
|
||||
|
||||
For this frontier, Gate U evidence is expected to cover at minimum:
|
||||
|
||||
- lexer behavior for covered inputs,
|
||||
- parser behavior and AST shape invariants required by `11`,
|
||||
- lowering outcomes at `IRBackend` boundary,
|
||||
- and deterministic diagnostics identity/attribution for rejection cases.
|
||||
|
||||
Conformance at this boundary may be claimed only when the full claimed PBS source surface is implemented at `IRBackend` level.
|
||||
|
||||
## 9. Explicit Deferrals
|
||||
|
||||
The following are intentionally out of scope for this document:
|
||||
|
||||
- `IRBackend -> IRVM` lowering,
|
||||
- artifact encoding and binary layout,
|
||||
- runtime lifecycle behavior,
|
||||
- verifier and loader checks.
|
||||
|
||||
## 10. Non-Goals
|
||||
|
||||
- Freezing one optimizer strategy.
|
||||
- Freezing one compiler architecture.
|
||||
- Repeating runtime or bytecode authority.
|
||||
|
||||
## 11. Exit Criteria
|
||||
|
||||
This document is healthy when:
|
||||
|
||||
1. lowering preconditions are explicit,
|
||||
2. preserved `IRBackend` obligations are explicit,
|
||||
3. deterministic rejection policy is explicit and test-backed,
|
||||
4. and scope boundaries with general/backend acceptance specs are explicit.
|
||||
|
||||
## 12. Executable Backend Handoff Addendum (v1)
|
||||
|
||||
For executable backends, the `IRBackend` output from this frontend boundary must satisfy the additional handoff obligations below.
|
||||
|
||||
### 12.1 Callable obligations
|
||||
|
||||
For each executable callable admitted into `IRBackend`, the frontend must preserve:
|
||||
|
||||
1. stable callable identity in the current build graph,
|
||||
2. observable callable signature (input arity and return shape),
|
||||
3. callable category needed by downstream lowering,
|
||||
4. source attribution anchor (`fileId`, `start`, `end`),
|
||||
5. and executable body representation that is backend-lowerable.
|
||||
|
||||
### 12.2 Callsite classification obligations
|
||||
|
||||
Each executable callsite in `IRBackend` must be classified into exactly one category:
|
||||
|
||||
1. `CALL_FUNC`,
|
||||
2. `CALL_HOST`,
|
||||
3. `CALL_INTRINSIC`.
|
||||
|
||||
Backend lowering must not infer this category by textual heuristics.
|
||||
|
||||
### 12.3 Host-backed metadata obligations
|
||||
|
||||
Each host-backed callsite admitted at this boundary must preserve canonical host identity:
|
||||
|
||||
1. `module`,
|
||||
2. `name`,
|
||||
3. `version`.
|
||||
|
||||
When available at this boundary, declared host ABI shape (`arg_slots`, `ret_slots`) must also be preserved for downstream validation.
|
||||
|
||||
### 12.4 VM-owned metadata obligations
|
||||
|
||||
VM-owned intrinsic callsites admitted at this boundary must preserve canonical intrinsic identity:
|
||||
|
||||
1. `canonicalName`,
|
||||
2. `canonicalVersion`.
|
||||
|
||||
VM-owned builtin projections/constants/intrinsics must not be reclassified as host bindings.
|
||||
|
||||
### 12.5 Deterministic capability obligations
|
||||
|
||||
`requiredCapabilities` derived at this boundary must be deterministic for the same admitted input graph.
|
||||
|
||||
### 12.6 Boundary with backend lowering specs
|
||||
|
||||
This addendum defines obligations preserved at the `IRBackend` boundary only.
|
||||
|
||||
It does not replace:
|
||||
|
||||
1. `docs/general/specs/20. IRBackend to IRVM Lowering Specification.md`,
|
||||
2. `docs/general/specs/21. IRVM Optimization Pipeline Specification.md`,
|
||||
3. or `docs/general/specs/15. Bytecode and PBX Mapping Specification.md`.
|
||||
|
||||
### 12.7 FrontendSpec Entry Point Obligation
|
||||
|
||||
For executable language frontends, `FrontendSpec` must declare one canonical qualified entrypoint reference (`EntrypointRef`):
|
||||
|
||||
1. `entryPointCallableName`,
|
||||
2. `entryPointModuleId`.
|
||||
|
||||
At `IRBackend` emission time:
|
||||
|
||||
1. frontend must copy this declaration into `IRBackend.entryPointCallableName` and `IRBackend.entryPointModuleId`,
|
||||
2. both values must be non-blank/non-none and deterministic for the same language/spec version,
|
||||
3. and backend stages must treat this qualified reference as authoritative for entrypoint selection instead of name-only fallbacks or hardcoded language-agnostic names.
|
||||
@@ -0,0 +1,153 @@
|
||||
# PBS Governance and Versioning
|
||||
|
||||
Status: Draft v1
|
||||
Applies to: PBS language, profiles, and related specifications
|
||||
|
||||
## 1. Purpose
|
||||
|
||||
This document defines how PBS decisions are made and how versions evolve without breaking the ecosystem unpredictably.
|
||||
|
||||
## 2. Scope
|
||||
|
||||
This policy governs:
|
||||
|
||||
- language specification changes,
|
||||
- profile changes (for example, Core/Game),
|
||||
- standard library specification changes,
|
||||
- compatibility policy updates,
|
||||
- release and deprecation decisions.
|
||||
|
||||
## 3. Governance Model
|
||||
|
||||
PBS uses a spec-first governance model.
|
||||
No implementation change is considered normative until the relevant spec change is accepted.
|
||||
|
||||
### 3.1 Roles
|
||||
|
||||
- Maintainers: approve/reject RFCs and cut releases.
|
||||
- Editors: keep specs coherent, complete, and cross-referenced.
|
||||
- Implementers: provide feasibility feedback and conformance evidence.
|
||||
- Community contributors: propose RFCs and review drafts.
|
||||
|
||||
### 3.2 Authority Rule
|
||||
|
||||
If a governance decision conflicts with runtime/bytecode authority, runtime/bytecode authority wins.
|
||||
|
||||
## 4. Decision Process (RFC)
|
||||
|
||||
All non-trivial changes MUST go through RFC.
|
||||
|
||||
### 4.1 RFC Lifecycle
|
||||
|
||||
1. Draft: problem, proposal, alternatives, migration impact.
|
||||
2. Review: open feedback period.
|
||||
3. Decision: `Accepted`, `Rejected`, or `Deferred`.
|
||||
4. Spec Merge: normative documents updated.
|
||||
5. Implementation: only after spec merge.
|
||||
6. Conformance: tests and diagnostics updated before release.
|
||||
|
||||
### 4.2 Fast-Track
|
||||
|
||||
Fast-track is allowed only for:
|
||||
|
||||
- critical correctness fixes,
|
||||
- security/capability violations,
|
||||
- deterministic behavior regressions.
|
||||
|
||||
Fast-track changes still require post-merge RFC backfill.
|
||||
|
||||
## 5. Version Domains
|
||||
|
||||
PBS versioning is separated by domain to avoid ambiguity.
|
||||
|
||||
1. Language Version (`pbs_lang`): syntax + semantics.
|
||||
2. Profile Version (`pbs_profile`): profile-specific surface (Core/Game).
|
||||
3. Stdlib Version (`pbs_stdlib`): standard library contract.
|
||||
4. Compatibility Policy Version (`pbs_compat`): evolution/deprecation policy text.
|
||||
|
||||
Host primitives remain versioned by canonical identity `(module, name, version)`.
|
||||
Direct declaration of canonical host primitive bindings is reserved to SDK/toolchain-managed `declare host` surfaces, not ordinary user-authored PBS modules.
|
||||
User-facing PBS and stdlib APIs over host primitives MAY evolve independently from those bindings as long as canonical host identity, capability policy, and compatibility commitments remain preserved.
|
||||
|
||||
## 6. Versioning Scheme
|
||||
|
||||
Each domain uses semantic versioning:
|
||||
|
||||
- `MAJOR`: incompatible changes.
|
||||
- `MINOR`: backward-compatible additions.
|
||||
- `PATCH`: clarifications/fixes with no intended behavior break.
|
||||
|
||||
## 7. Change Classification
|
||||
|
||||
### 7.1 Patch Changes
|
||||
|
||||
- wording fixes,
|
||||
- unambiguous typo corrections,
|
||||
- diagnostics wording adjustments without code/behavior contract changes.
|
||||
|
||||
### 7.2 Minor Changes
|
||||
|
||||
- additive syntax behind explicit profile gates,
|
||||
- new stdlib APIs,
|
||||
- new host primitive versions added without removing old supported versions.
|
||||
|
||||
### 7.3 Major Changes
|
||||
|
||||
- behavior changes that can alter valid program outcomes,
|
||||
- removal of previously supported constructs,
|
||||
- incompatible type or resolution rule changes.
|
||||
|
||||
## 8. Compatibility Rules
|
||||
|
||||
- Supported old versions MUST continue to compile/link/run as declared by the compatibility window.
|
||||
- A release MUST publish a compatibility matrix for language/profile/stdlib domains.
|
||||
- Toolchains MUST reject unsupported targets deterministically with explicit diagnostics.
|
||||
|
||||
## 9. Deprecation and Removal Policy
|
||||
|
||||
Deprecation stages:
|
||||
|
||||
1. Introduce deprecation notice in specs and tooling.
|
||||
2. Keep feature functional during declared support window.
|
||||
3. Remove only in a subsequent major version.
|
||||
|
||||
Every deprecation MUST include:
|
||||
|
||||
- replacement path,
|
||||
- migration notes,
|
||||
- timeline (first deprecated version, last supported version, removal version).
|
||||
|
||||
## 10. Release Requirements
|
||||
|
||||
Before any version release:
|
||||
|
||||
1. Specs for changed domains are updated.
|
||||
2. Changelog is published with change classification.
|
||||
3. Conformance suite is updated and passing.
|
||||
4. Compatibility matrix is published.
|
||||
5. Migration guide is provided for any major-impact changes.
|
||||
|
||||
## 11. Documentation Contract
|
||||
|
||||
Every accepted change MUST update, when relevant:
|
||||
|
||||
- normative spec sections,
|
||||
- examples,
|
||||
- diagnostics documentation,
|
||||
- conformance tests,
|
||||
- compatibility matrix/changelog.
|
||||
- For executable FE/BE conformance-relevant code changes, the backend conformance matrix (`docs/general/specs/22. Backend Spec-to-Test Conformance Matrix.md`) MUST be updated and pass hard-gate policy checks.
|
||||
|
||||
## 12. Conflict Resolution
|
||||
|
||||
When maintainers disagree, the tie-breaker is:
|
||||
|
||||
1. determinism and compatibility,
|
||||
2. clarity for beginners,
|
||||
3. implementation feasibility and tooling stability.
|
||||
|
||||
## 13. Non-Goals
|
||||
|
||||
- Replacing runtime authority with governance-only decisions.
|
||||
- Defining subsystem-specific API semantics in this document.
|
||||
- Granting implementation behavior override over normative specs.
|
||||
File diff suppressed because it is too large
Load Diff
@@ -0,0 +1,772 @@
|
||||
# PBS Static Semantics Specification
|
||||
|
||||
Status: Draft v1 (Normative)
|
||||
Scope: binding, callable formation, type checking, and deterministic function application
|
||||
|
||||
## 1. Purpose
|
||||
|
||||
This document defines the static semantics of PBS core language.
|
||||
|
||||
It is intended to:
|
||||
|
||||
- give deterministic meaning to declarations accepted by the syntax specification,
|
||||
- define callable identity and application rules,
|
||||
- make type checking stable across implementations,
|
||||
- preserve beginner-facing clarity without hidden callable behavior.
|
||||
|
||||
## 2. Core Semantic Model
|
||||
|
||||
### 2.1 Authority and precedence
|
||||
|
||||
Normative precedence:
|
||||
|
||||
1. Runtime authority (`docs/specs/hardware/topics/chapter-2.md`, `chapter-3.md`, `chapter-9.md`, `chapter-12.md`, `chapter-16.md`)
|
||||
2. Bytecode authority (`docs/specs/bytecode/ISA_CORE.md`)
|
||||
3. `3. Core Syntax Specification.md`
|
||||
4. This document
|
||||
|
||||
If a rule here conflicts with higher authority, it is invalid.
|
||||
|
||||
### 2.2 Semantic namespaces
|
||||
|
||||
PBS distinguishes at least:
|
||||
|
||||
- type namespace,
|
||||
- value namespace,
|
||||
- callable namespace.
|
||||
- host-owner namespace.
|
||||
|
||||
Rules:
|
||||
|
||||
- `declare struct`, `declare service`, `declare contract`, `declare error`, `declare enum`, `declare callback`, and `declare builtin type` introduce names in the type namespace.
|
||||
- `declare host` introduces names in the host-owner namespace.
|
||||
- `let`, parameters, and `declare const` introduce names in the value namespace.
|
||||
- `declare service Name` also introduces the canonical singleton value `Name` in the value namespace.
|
||||
- Top-level `fn`, service methods, and host methods participate in the callable namespace.
|
||||
- `fn` declarations are not first-class values in v1 core and therefore do not become ordinary value expressions.
|
||||
- `bind(...)` is a callback-formation construct, not a general function-value construct.
|
||||
- `declare host` declarations are reserved to SDK/toolchain-controlled modules and are not formable in ordinary user-authored PBS source.
|
||||
- `declare builtin type` declarations are reserved to SDK/toolchain-controlled modules and are not formable in ordinary user-authored PBS source.
|
||||
- A host owner name is not an ordinary value expression in v1 core; it is used only as a qualified host-call owner.
|
||||
- The builtin simple types `int`, `float`, `bool`, and `str` are always present in the type namespace.
|
||||
- Builtin simple types are resolved without import or declaration.
|
||||
- User-authored type declarations must not reuse builtin simple type names.
|
||||
|
||||
### 2.3 Attribute metadata
|
||||
|
||||
Attributes are compile-time metadata attached to declaration surfaces.
|
||||
|
||||
Rules:
|
||||
|
||||
- An attribute has no value-level or type-level meaning by itself.
|
||||
- Attributes are not first-class values and are not reflectable in v1 core.
|
||||
- Attributes do not automatically survive into runtime or bytecode artifacts.
|
||||
- An attribute affects runtime artifacts only when another specification defines an explicit lowering for its semantic effect.
|
||||
- In v1 core, the normative reserved attributes are `Host`, `Capability`, `BuiltinType`, `BuiltinConst`, and `IntrinsicCall`.
|
||||
- `Host` is valid only on a host method signature declared directly inside a reserved stdlib/interface-module `declare host` body.
|
||||
- `Capability` is valid only on a host method signature declared directly inside a reserved stdlib/interface-module `declare host` body.
|
||||
- `Host` is invalid on ordinary user-authored modules, top-level `fn`, struct methods, service methods, callbacks, contracts, and constants.
|
||||
- `Host` metadata is consumed by the compiler during host-binding lowering.
|
||||
- The `Host` attribute syntax itself is not exported as runtime metadata; instead, its canonical identity participates in PBX host-binding emission as defined by the Host ABI Binding specification.
|
||||
- `BuiltinType` is valid only on a reserved top-level `declare builtin type` declaration.
|
||||
- `BuiltinConst` is valid only on a reserved top-level `declare const` declaration that omits an initializer.
|
||||
- `IntrinsicCall` is valid only on a method signature declared directly inside a reserved `declare builtin type` body.
|
||||
- Builtin metadata is consumed by the compiler during VM-owned builtin and intrinsic lowering rather than by host-binding lowering.
|
||||
|
||||
### 2.4 Tuple shapes
|
||||
|
||||
Static checking uses tuple shapes as semantic objects.
|
||||
|
||||
Definitions:
|
||||
|
||||
- Input tuple shape: ordered sequence of zero or more input slots.
|
||||
- Output tuple shape: ordered sequence of zero or more output slots.
|
||||
- Each slot has a type and a stable label.
|
||||
|
||||
Rules:
|
||||
|
||||
- Tuple shapes in PBS core are always named, except for unit `()`.
|
||||
- Input slot labels come from parameter names and are local frame names.
|
||||
- Output slot labels come from return annotations and are visible for multi-slot member projection.
|
||||
- Tuple-shape identity for overload and resolution ignores labels.
|
||||
- Tuple-shape compatibility requires matching arity and positional slot types.
|
||||
- Labels must still be preserved as part of declaration surface and projection metadata.
|
||||
- A single-slot tuple shape has a distinguished carrier value type equal to its slot type.
|
||||
- In value positions, single-slot tuple values collapse to their carrier value type.
|
||||
- Single-slot tuple shapes have no dedicated tuple-literal surface in v1 core.
|
||||
|
||||
## 3. Functions and `apply`
|
||||
|
||||
### 3.1 Canonical function model
|
||||
|
||||
Every callable `fn` in PBS is modeled statically as:
|
||||
|
||||
```text
|
||||
Fn : InputTuple -> OutputTuple
|
||||
```
|
||||
|
||||
Rules:
|
||||
|
||||
- `fn f(a: A, b: B)` has input tuple shape `(a: A, b: B)`.
|
||||
- `fn f()` has empty input tuple shape `()`.
|
||||
- `-> void`, `-> ()`, and omitted return annotation all denote empty output tuple shape `()`.
|
||||
- `-> T` denotes a single-slot output tuple shape `(value: T)`.
|
||||
- `-> (x: T)` denotes a single-slot output tuple shape `(x: T)`.
|
||||
- `-> (x: T, y: U)` denotes a two-slot output tuple shape `(x: T, y: U)`.
|
||||
- `-> T` and `-> (x: T)` are identical for overload identity and differ only in preserved label metadata.
|
||||
- `optional T` is a regular value type and may appear in parameters, locals, fields, and plain returns.
|
||||
- `optional T` with single-slot payload is internally normalized to `optional<(value: T)>`.
|
||||
- `optional` and `optional void` are invalid type surfaces.
|
||||
- `-> result<E> T` denotes a result return surface over payload shape `T` and error type `E`.
|
||||
- `-> result<E> T` with single-slot payload is internally normalized to `result<E, (value: T)>`.
|
||||
- `-> result<E>` is valid and denotes a result return surface with unit payload.
|
||||
- A function return surface may be plain or `result<E>`.
|
||||
- A function return surface must not combine `optional` and `result` in the same declaration.
|
||||
- `result<E>` wraps the declared success payload; the payload itself may be scalar or a named tuple shape.
|
||||
|
||||
### 3.2 Callable categories
|
||||
|
||||
The following constructs are callable in v1 core:
|
||||
|
||||
- top-level `fn`,
|
||||
- struct methods on concrete receivers,
|
||||
- contract values,
|
||||
- callback values,
|
||||
- service methods,
|
||||
- host methods on declared host owners,
|
||||
- builtin intrinsic methods on declared builtin types.
|
||||
|
||||
Rules:
|
||||
|
||||
- All callable categories use the same input/output tuple model.
|
||||
- A struct method is identified by `(struct type, method name, input tuple shape excluding the receiver slot, output tuple shape)`.
|
||||
- A contract value is identified at the type level by its contract type and at runtime by an underlying concrete struct instance or service singleton value plus its selected implementation.
|
||||
- A callback declaration defines a nominal callable type with exactly one input/output tuple shape.
|
||||
- A service method is identified by `(service name, method name, input tuple shape, output tuple shape)`.
|
||||
- A host method is identified by `(host owner name, method name, input tuple shape, output tuple shape)` within the PBS declaration surface.
|
||||
- A builtin intrinsic method is identified within PBS declaration surface by `(builtin type name, method name, input tuple shape, output tuple shape)` and lowers further by canonical builtin/intrinsic metadata.
|
||||
- A top-level `fn` is identified by `(name, input tuple shape, output tuple shape)`.
|
||||
- A callback value is identified at the type level by its declared callback type and signature.
|
||||
- Contract signatures and barrel signatures must preserve the same callable shape.
|
||||
- Canonical host primitive identity and binding are governed by the Host ABI Binding specification rather than by ordinary v1 core declaration identity alone.
|
||||
|
||||
### 3.3 Declaration validity
|
||||
|
||||
Rules:
|
||||
|
||||
- Parameter names in a single `ParamList` must be unique.
|
||||
- Output labels in a named tuple return annotation must be unique.
|
||||
- Error case labels in a single `declare error` body must be unique.
|
||||
- Enum case labels in a single `declare enum` must be unique.
|
||||
- Enum case integer identifiers in a single `declare enum` must be unique.
|
||||
- Two declarations with the same callable name and the same input/output tuple shape are duplicates.
|
||||
- Changing only parameter names does not create a new callable.
|
||||
- Changing only input labels in `ParamList` does not create a new callable.
|
||||
- Changing only output labels does not create a new callable.
|
||||
- `mod.barrel` function entries are matched by callable identity, ignoring labels.
|
||||
- Barrel labels may differ from implementation labels.
|
||||
- Any return surface that combines `optional` and `result` is statically invalid.
|
||||
- Any payload-less `optional` type surface is statically invalid.
|
||||
- Any `optional void` type surface is statically invalid.
|
||||
- A host method signature in a reserved stdlib/interface module MUST carry exactly one `Host` attribute.
|
||||
- A host method signature in a reserved stdlib/interface module MUST carry exactly one `Capability` attribute.
|
||||
- A `Host` attribute MUST declare exactly the named arguments `module`, `name`, and `version`.
|
||||
- `Host.module` and `Host.name` MUST be non-empty string literals.
|
||||
- `Host.version` MUST be a positive integer literal.
|
||||
- A `Capability` attribute MUST declare exactly the named argument `name`.
|
||||
- `Capability.name` MUST be a non-empty lowercase capability identifier.
|
||||
- Two host methods in the same resolved stdlib environment MUST NOT lower to the same canonical `(module, name, version)` unless they denote the same host method declaration after project/module resolution.
|
||||
- A `declare const` declaration must include an explicit type annotation.
|
||||
- A `declare const` declaration without `BuiltinConst` metadata must include an initializer.
|
||||
- A `declare const` declaration with `BuiltinConst` metadata must omit the initializer.
|
||||
- A non-builtin `declare const` initializer must be a constant expression.
|
||||
- `declare const` dependency resolution is module-wide and must not depend on source-file processing order.
|
||||
- `declare const` dependencies must form an acyclic graph.
|
||||
- A `BuiltinType` attribute MUST declare exactly the named arguments `name` and `version`.
|
||||
- `BuiltinType.name` MUST be a non-empty string literal.
|
||||
- `BuiltinType.version` MUST be a positive integer literal.
|
||||
- Two builtin type declarations in the same resolved stdlib environment MUST NOT lower to the same canonical `(name, version)` unless they denote the same builtin declaration after project/module resolution.
|
||||
- A builtin field type must be builtin-layout-admissible as defined by the builtin/intrinsics specification.
|
||||
- Builtin field slot offsets are inferred by the compiler from canonical field order and flattened builtin layout width.
|
||||
- Builtin layout composition must be acyclic.
|
||||
- A builtin field that depends on a builtin layout with unresolved flattened width is statically invalid.
|
||||
- `IntrinsicCall` MUST declare exactly the named argument `name` and MAY additionally declare `version`.
|
||||
- `IntrinsicCall.name` MUST be a non-empty string literal.
|
||||
- `IntrinsicCall.version`, when present, MUST be a positive integer literal.
|
||||
- Two builtin methods in the same canonical builtin owner/version line MUST NOT lower to the same canonical intrinsic `(owner, name, version)` unless they denote the same builtin method declaration after project/module resolution.
|
||||
- `BuiltinConst` MUST declare exactly the named arguments `target`, `name`, and `version`.
|
||||
- `BuiltinConst.target` and `BuiltinConst.name` MUST be non-empty string literals.
|
||||
- `BuiltinConst.version` MUST be a positive integer literal.
|
||||
- Two builtin constant declarations in the same resolved stdlib environment MUST NOT lower to the same canonical `(target, name, version)` unless they denote the same builtin constant declaration after project/module resolution.
|
||||
|
||||
### 3.4 Constant expressions
|
||||
|
||||
PBS core v1 restricts top-level constant evaluation to a deterministic compile-time subset.
|
||||
|
||||
Rules:
|
||||
|
||||
- A non-builtin `declare const` initializer is evaluated at compile time.
|
||||
- A non-builtin `declare const` may depend only on previously resolved visible `declare const` declarations and enum case values.
|
||||
- Cross-file constant resolution within a module is defined by dependency analysis, not source-file order.
|
||||
- Constant evaluation fails if the dependency graph contains a cycle.
|
||||
- The allowed constant-expression forms in v1 core are:
|
||||
- scalar literals: `IntLit`, `FloatLit`, `StringLit`, `BoolLit`,
|
||||
- enum case paths `EnumName.caseName`,
|
||||
- a reference to another visible `declare const`,
|
||||
- unary `-` applied to an integer or float constant expression,
|
||||
- unary `not` or `!` applied to a boolean constant expression,
|
||||
- binary arithmetic operators over numeric constant expressions,
|
||||
- binary comparison operators over compatible constant expressions,
|
||||
- binary boolean operators over boolean constant expressions.
|
||||
- A non-builtin `declare const` initializer must not use:
|
||||
- callable application or call sugar,
|
||||
- `new`,
|
||||
- `bind(...)`,
|
||||
- `some(...)` or `none`,
|
||||
- tuple expressions,
|
||||
- block expressions,
|
||||
- `if`, `switch`, `handle`, `else` extraction, or `!` result propagation,
|
||||
- method calls or member access except enum case paths.
|
||||
- For non-builtin `declare const`, the initializer type must be compatible with the declared `const` type.
|
||||
- A `BuiltinConst` declaration is not part of ordinary compile-time constant evaluation and lowers through VM-owned builtin constant materialization instead.
|
||||
- A `declare const` exported through `mod.barrel` may be imported from another module only through ordinary module import rules.
|
||||
- A `declare const` does not introduce mutable runtime storage; implementations may inline, fold, or materialize it as an immutable constant as long as observable semantics remain unchanged.
|
||||
|
||||
### 3.5 Enum declarations and values
|
||||
|
||||
Rules:
|
||||
|
||||
- `declare enum Name(case1, case2, ...);` introduces a nominal enum type `Name`.
|
||||
- `declare enum Name(case1 = n1, case2 = n2, ...);` introduces explicit integer identifiers for enum cases.
|
||||
- If no enum case uses an explicit identifier, identifiers are assigned as `0..n-1` in declaration order.
|
||||
- If any enum case uses an explicit identifier, then every enum case in that declaration must use an explicit identifier.
|
||||
- `Name.case` is a valid enum value surface only when `Name` resolves to a declared enum type and `case` resolves to a declared case of that enum.
|
||||
- The static type of `Name.case` is the enum type `Name`.
|
||||
- Error labels are not enum cases and must not be used where enum case values are required.
|
||||
|
||||
### 3.6 Structs, services, methods, and contracts
|
||||
|
||||
Rules:
|
||||
|
||||
- Struct values are heap-backed reference values in v1 core.
|
||||
- Service values are canonical module-owned singleton values in v1 core.
|
||||
- `new Struct(args...)` allocates a new struct instance of the declared struct type.
|
||||
- `new Struct.ctorName(args...)` invokes a named constructor declared in the enclosing struct body and produces a new struct instance of that type.
|
||||
- Struct construction arguments are matched positionally to the declared struct field order.
|
||||
- Assigning a struct value copies the reference, not the underlying field storage.
|
||||
- Assigning a service value copies the same canonical singleton identity; it does not create a new instance.
|
||||
- A struct field with no access modifier is readable and writable only from methods and `ctor` bodies of its enclosing struct.
|
||||
- A `pub` struct field is externally readable but remains externally non-assignable.
|
||||
- A `pub mut` struct field is externally readable and externally assignable.
|
||||
- An assignment target `expr.name` to a struct field is valid only when the access site is permitted to write that field.
|
||||
- Writes to a private struct field are valid only through `this.name` inside methods and `ctor` bodies of the enclosing struct.
|
||||
- A struct method declared in a struct body has an implicit receiver binding `this` of type `Self`.
|
||||
- A service method declared in a service body has an implicit receiver binding `this` of type `Self`.
|
||||
- `this` is valid only inside struct method, service method, and `ctor` bodies.
|
||||
- `Self` is valid only in struct method, service method, and `ctor` declarations and denotes the enclosing owner type.
|
||||
- The enclosing struct name is in scope inside its own field declarations, enabling self-referential field types.
|
||||
- A named `ctor` declared in a struct body is not a method, but it does introduce an implicit under-construction `this`.
|
||||
- A `ctor` has no declared return annotation and is not a `fn`.
|
||||
- A `ctor` completes by falling off the end of its body after initializing the enclosing struct instance.
|
||||
- Every field of the enclosing struct must be definitely assigned on every completing `ctor` path.
|
||||
- Named constructors participate in overload resolution by name plus parameter signature.
|
||||
- `return;` and `return expr;` are both invalid inside `ctor` bodies.
|
||||
- Methods declared in a struct body belong to the direct method namespace of that concrete struct type.
|
||||
- Methods declared in a service body belong to the direct method namespace of that concrete service type.
|
||||
- `receiver.method(...)` on a concrete struct receiver resolves only against methods declared directly in that struct body.
|
||||
- `receiver.method(...)` on a service receiver resolves only against methods declared directly in that service body.
|
||||
- `receiver.ctorName(...)` is never valid on a concrete struct value.
|
||||
- Service values are ordinary value expressions and may be assigned, passed, and returned under their declared service type.
|
||||
- Services do not have fields.
|
||||
- Services do not declare named constructors and are never targets of `new`.
|
||||
- Contract implementations do not inject their methods into the direct method namespace of the concrete struct or service.
|
||||
- `implements Contract for Owner using s { ... }` is unique per `(Contract, Owner)` pair, where `Owner` is a declared struct or service.
|
||||
- A contract for a struct or service may be implemented only in the module where that owner itself is declared.
|
||||
- Contracts may be declared in other modules and implemented for the local struct or service in its owner module.
|
||||
- An `implements` block has no independent visibility; its observability follows the visibility of the owner declaration, and the contract must also be nameable at the use site.
|
||||
- Methods declared directly inside a struct or service follow the visibility of their enclosing owner declaration; they do not have independent visibility.
|
||||
- A struct value or service singleton value may be coerced to a contract value when exactly one visible `implements Contract for Owner ...` applies.
|
||||
- Contract coercion may happen by explicit `expr as ContractType` or by contextual typing in assignments, parameter passing, and returns.
|
||||
- `as` in expression position is reserved for explicit contract coercion only; no other cast semantics exist in v1 core.
|
||||
- The contract name in `expr as ContractName` must be a simple visible identifier resolved through ordinary scope and import rules.
|
||||
- A contract value carries the underlying struct reference or service singleton value together with the selected contract implementation for runtime dispatch.
|
||||
- Calling `contractValue.method(...)` uses dynamic dispatch through the contract value.
|
||||
- Calling `structValue.contractMethod(...)` is not valid unless that method is also declared directly on the struct.
|
||||
- Calling `serviceValue.contractMethod(...)` is not valid unless that method is also declared directly on the service.
|
||||
- Structs do not have static methods in v1 core; named constructors are their only type-qualified callable members.
|
||||
- Services are accessed through their canonical singleton value, not through `new` or static method declarations.
|
||||
|
||||
Example:
|
||||
|
||||
```pbs
|
||||
declare contract StasisProcess {
|
||||
fn stasis() -> int;
|
||||
}
|
||||
|
||||
declare struct Struct(pub a: int) {
|
||||
fn compute() -> int {
|
||||
return this.a;
|
||||
}
|
||||
|
||||
ctor createWithSomethingSpecial(x: int) {
|
||||
this.a = x;
|
||||
}
|
||||
}
|
||||
|
||||
implements StasisProcess for Struct using s {
|
||||
fn stasis() -> int {
|
||||
return s.compute();
|
||||
}
|
||||
}
|
||||
|
||||
fn demo() -> int {
|
||||
let s = new Struct(1);
|
||||
let s2 = new Struct.createWithSomethingSpecial(2);
|
||||
let sp: StasisProcess = s;
|
||||
let sp2 = s as StasisProcess;
|
||||
let a = s.a;
|
||||
let _ = s2.compute();
|
||||
let b = sp.stasis();
|
||||
let c = sp2.stasis();
|
||||
return a + b + c;
|
||||
}
|
||||
```
|
||||
|
||||
### 3.7 Nominal callbacks
|
||||
|
||||
Rules:
|
||||
|
||||
- `declare callback Name(params...) -> R;` introduces a nominal callback type `Name`.
|
||||
- A callback type is not a `fn`, and a `fn` declaration does not implicitly define a callback type.
|
||||
- A value of callback type may be formed only from a compatible top-level `fn` in v1 core.
|
||||
- A value of callback type may also be formed by `bind(context, fn_name)` when the surrounding static type context expects a callback type.
|
||||
- Service methods are not assignable to callback values in v1 core.
|
||||
- Host methods are not assignable to callback values in v1 core.
|
||||
- Callback values do not capture local environment implicitly.
|
||||
- Assignment of a top-level `fn` to a callback type succeeds only when exactly one visible overload matches the callback signature.
|
||||
- `bind(context, fn_name)` succeeds only when exactly one visible top-level `fn` overload matches after consuming the first parameter with `context`.
|
||||
- Valid expected callback contexts for `bind(context, fn_name)` include variable initialization with an explicit callback type, assignment to an explicitly typed callback location, argument passing to a callback-typed parameter, and return from a callback-typed function.
|
||||
- The context expression in `bind(context, fn_name)` is evaluated once at bind time and stored explicitly in the resulting callback value.
|
||||
- When that stored context is identity-bearing, the resulting callback preserves the same captured identity rather than copying an independent underlying object.
|
||||
- `bind(context, fn_name)` does not introduce general closures; it is explicit partial binding of the first parameter only.
|
||||
- Callback compatibility ignores labels and compares ordered input/output slot types plus the return-surface kind.
|
||||
|
||||
Example:
|
||||
|
||||
```pbs
|
||||
declare callback TickCb(dt: int) -> void;
|
||||
|
||||
fn on_tick(dt: int) -> void {
|
||||
}
|
||||
|
||||
fn install_tick() -> void {
|
||||
let cb: TickCb = on_tick;
|
||||
let _ = cb;
|
||||
}
|
||||
```
|
||||
|
||||
Bound example:
|
||||
|
||||
```pbs
|
||||
declare callback UpdateCb(dt: int) -> void;
|
||||
|
||||
declare struct Enemy(hp: int);
|
||||
|
||||
fn update_enemy(self: Enemy, dt: int) -> void {
|
||||
}
|
||||
|
||||
fn install_update(enemy: Enemy) -> void {
|
||||
let cb: UpdateCb = bind(enemy, update_enemy);
|
||||
let _ = cb;
|
||||
}
|
||||
```
|
||||
|
||||
Ambiguous overload example:
|
||||
|
||||
```pbs
|
||||
declare callback TickCb(dt: int) -> void;
|
||||
|
||||
fn tick(dt: int) -> void {
|
||||
}
|
||||
|
||||
fn tick(time: int) -> void {
|
||||
}
|
||||
|
||||
fn install_tick() -> void {
|
||||
let cb: TickCb = tick; // error: ambiguous overloaded fn assignment
|
||||
}
|
||||
```
|
||||
|
||||
### 3.8 Canonical application
|
||||
|
||||
The canonical surface form for function application is:
|
||||
|
||||
```pbs
|
||||
callee apply arg
|
||||
```
|
||||
|
||||
Rules:
|
||||
|
||||
- `apply` is an infix operator that is right-associative.
|
||||
- `f1 apply f2 apply x` is defined as `f1 apply (f2 apply x)`.
|
||||
- `f1 apply f2 apply f3 apply params` is defined as `f1 apply (f2 apply (f3 apply params))`.
|
||||
- The left operand of `apply` must resolve to one of: a callable candidate set, a bound struct method target, a bound service method target, a contract-method target, or a callback value.
|
||||
- The right operand of `apply` is an argument expression.
|
||||
- If the callable input arity is `0`, the argument expression must be `()`.
|
||||
- If the callable input arity is `1`, the argument expression is checked against the carrier type of the single input slot.
|
||||
- If the callable input arity is `2..6`, the argument expression must have a named tuple shape with matching arity and positional types.
|
||||
- Input labels are not used for compatibility.
|
||||
- No single-slot tuple argument literal is required or recognized in surface syntax.
|
||||
- There is no partial application in v1 core.
|
||||
- There is no currying in v1 core.
|
||||
- Chained `apply` is nested ordinary application, not callable composition as a first-class value.
|
||||
- Callback values, service methods, host methods, struct methods, and contract-method targets use the same `apply` rules as top-level `fn`.
|
||||
|
||||
### 3.9 Call sugar
|
||||
|
||||
The surface form:
|
||||
|
||||
```pbs
|
||||
callee(arg1, arg2, ..., argN)
|
||||
```
|
||||
|
||||
desugars to the canonical `apply` surface according to arity.
|
||||
|
||||
Rules:
|
||||
|
||||
- The desugaring is purely syntactic.
|
||||
- `f()` is exact sugar for `f apply ()`.
|
||||
- `f(x)` is exact sugar for `f apply x`.
|
||||
- `f(x1, x2, ..., xn)` for `n >= 2` is exact sugar for `f apply (x1, x2, ..., xn)`.
|
||||
- No semantic distinction exists between direct call sugar and its canonical `apply` form.
|
||||
- When `(arg1, ..., argN)` is used as positional tuple sugar, the callee input tuple shape supplies the effective labels.
|
||||
- All overload resolution, diagnostics, and type checking are defined on the canonical `apply` form.
|
||||
|
||||
### 3.10 Result type of application
|
||||
|
||||
Rules:
|
||||
|
||||
- If the selected callable output arity is `0`, the result of `apply` is unit.
|
||||
- If the selected callable output arity is `1`, the result of `apply` is the carrier type of the single output slot.
|
||||
- If the selected callable output arity is `2..6`, the result of `apply` has the named output tuple shape of the selected callable.
|
||||
- Multi-slot output tuple results expose their labels for member projection.
|
||||
- If the selected callable is a callback value, the visible multi-slot output labels come from the callback type rather than from the original source `fn`.
|
||||
- If the selected callable returns `()`, the application result is unit.
|
||||
|
||||
Example:
|
||||
|
||||
```pbs
|
||||
fn func(a: int, b: int) -> (c: int, d: float) {
|
||||
return (c: a + b, d: 2.0);
|
||||
}
|
||||
|
||||
fn demo_apply() -> int {
|
||||
let params: (a: int, b: int) = (1, 2);
|
||||
let r = func apply params;
|
||||
let c = r.c;
|
||||
let d = r.d;
|
||||
let _ = d;
|
||||
return c;
|
||||
}
|
||||
```
|
||||
|
||||
In the example above:
|
||||
|
||||
- `func` has input tuple shape `(a: int, b: int)`,
|
||||
- `func` has output tuple shape `(c: int, d: float)`,
|
||||
- `r` has named output tuple type `(c: int, d: float)`,
|
||||
- `r.c` has type `int`,
|
||||
- `r.d` has type `float`.
|
||||
|
||||
Single-slot example:
|
||||
|
||||
```pbs
|
||||
fn plus_one(x: int) -> int {
|
||||
return x + 1;
|
||||
}
|
||||
|
||||
fn demo_single() -> void {
|
||||
let r = plus_one apply 1;
|
||||
if r == 2 {
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
In the example above:
|
||||
|
||||
- `plus_one` has input tuple shape `(x: int)`,
|
||||
- the argument `1` is accepted directly as the carrier value for the single input slot,
|
||||
- `plus_one` has output tuple shape `(value: int)`,
|
||||
- the value produced by `plus_one apply 1` has carrier type `int`,
|
||||
- `r.value` is not required and should not be used.
|
||||
|
||||
### 3.11 Overload resolution
|
||||
|
||||
Rules:
|
||||
|
||||
- Overload resolution starts from the visible callable candidates with the selected name.
|
||||
- Candidate filtering first uses callable kind and input tuple arity.
|
||||
- Remaining candidates are filtered by positional input type compatibility.
|
||||
- If exactly one candidate remains, resolution succeeds.
|
||||
- If multiple candidates remain, expected output types or expected multi-slot output tuple shapes may be used as a tie-breaker when statically available.
|
||||
- If multiple candidates still remain, the `apply` is ambiguous and compilation fails.
|
||||
- If no candidate remains, the `apply` is unresolved and compilation fails.
|
||||
- Overloads that differ only by labels are duplicates and are forbidden.
|
||||
- Overloads that differ only by output positional types are permitted, but uncontextualized `apply` sites may become ambiguous.
|
||||
|
||||
### 3.12 Member access and projection
|
||||
|
||||
Rules:
|
||||
|
||||
- `TypeName.case` is valid when `TypeName` resolves to a declared enum type and `case` resolves to one of its declared enum cases.
|
||||
- `TypeName.case` has static type `TypeName`.
|
||||
- `expr.name` is valid when the static type of `expr` is a declared `struct` containing field `name` and the access site is permitted to read that field.
|
||||
- For `struct` field access, the projected member type is the declared field type.
|
||||
- Reads of a private struct field are valid only through `this.name` inside methods and `ctor` bodies of the enclosing struct.
|
||||
- `expr.method` is a valid method-call target when the static type of `expr` is a concrete struct type declaring method `method`.
|
||||
- `expr.method` over a concrete struct receiver does not search visible contract implementations.
|
||||
- `expr.method` is a valid method-call target when the static type of `expr` is a concrete service type declaring method `method`.
|
||||
- `expr.method` over a concrete service receiver does not search visible contract implementations.
|
||||
- `HostName.method` is a valid method-call target when `HostName` resolves to a visible declared host owner whose body declares method `method`.
|
||||
- `TypeName.ctorName` is not a general member access surface; named constructors are entered only through `new TypeName.ctorName(...)`.
|
||||
- `expr.method` is a valid method-call target when the static type of `expr` is a contract value whose contract declares method `method`.
|
||||
- Bare extraction of a struct, service, host, builtin, or contract method as a value is invalid in v1 core because methods are not first-class.
|
||||
- `expr.name` is valid when the static type of `expr` is a multi-slot named output tuple containing label `name`.
|
||||
- For named output tuples, the projected member type is the type of the corresponding output slot.
|
||||
- Projection is label-based, not position-based.
|
||||
- `expr.name` is valid when the static type of `expr` is a builtin type declaring projection field `name`.
|
||||
- For builtin projection fields, the projected member type is the declared builtin field type.
|
||||
- `expr.method` is a valid method-call target when the static type of `expr` is a builtin type declaring intrinsic member `method`.
|
||||
- `expr.hasSome()` and `expr.hasNone()` are valid intrinsic method-call surfaces when the static type of `expr` is `optional<P>`.
|
||||
- `expr.hasSome()` and `expr.hasNone()` both have static type `bool`.
|
||||
- `expr.name()` and `expr.key()` are valid intrinsic method-call surfaces when the static type of `expr` is an enum type.
|
||||
- `expr.name()` has static type `str`.
|
||||
- `expr.key()` has static type `int`.
|
||||
- Access to a missing output label is a compile-time error.
|
||||
- Access to a missing struct field is a compile-time error.
|
||||
- Read access to an inaccessible private struct field is a compile-time error.
|
||||
- Write access to an inaccessible or non-`pub mut` struct field is a compile-time error.
|
||||
- Access to a missing struct method is a compile-time error.
|
||||
- Access to a missing service method is a compile-time error.
|
||||
- Access to a missing host method is a compile-time error.
|
||||
- Access to a missing contract method is a compile-time error.
|
||||
- Access to a missing builtin projection field is a compile-time error.
|
||||
- Access to a missing builtin intrinsic member is a compile-time error.
|
||||
- Member projection is not defined for single-slot collapsed carrier values.
|
||||
|
||||
### 3.13 Block expressions and function fallthrough
|
||||
|
||||
Rules:
|
||||
|
||||
- A block expression with a `TailExpr` has the static type of that final expression.
|
||||
- A block expression without a `TailExpr` has static type unit.
|
||||
- Only the final unsemicoloned expression in a block contributes to the block result.
|
||||
- A function body does not implicitly return its trailing `TailExpr`; explicit `return` and ordinary control-flow rules still apply.
|
||||
- Reaching the end of a plain non-unit function is a compile-time error unless all control-flow paths are proven to return explicitly.
|
||||
- Reaching the end of a `void` or `()` function is valid and yields unit.
|
||||
- Reaching the end of an `optional P` function yields `none`.
|
||||
- Reaching the end of a `result<E>` function is a compile-time error.
|
||||
|
||||
### 3.14 Loop forms
|
||||
|
||||
Rules:
|
||||
|
||||
- `while cond { ... }` requires `cond` to have static type `bool`.
|
||||
- `for i: T from start until end { ... }` is the declarative counted loop form in v1 core.
|
||||
- `for i: T from start until end step s { ... }` is the explicit-step counted loop form in v1 core.
|
||||
- In `for`, the declared iteration variable `i` introduces a loop-local binding of type `T`.
|
||||
- `start`, `end`, and `step` expressions in `for` must be type-compatible with the declared iteration type `T`.
|
||||
- If `step` is omitted, the loop uses the integer value `1` of the iteration type domain.
|
||||
- `for` iteration proceeds by evaluating `start`, `end`, and optional `step` once before loop entry.
|
||||
- `for ... until ...` uses an exclusive upper bound.
|
||||
- `continue` inside `while` transfers control to the next condition check.
|
||||
- `continue` inside `for` transfers control to the step update and then to the next bound check.
|
||||
- `break` exits the nearest enclosing loop.
|
||||
|
||||
### 3.15 `if` and `switch` conditional expressions
|
||||
|
||||
Rules:
|
||||
|
||||
- In `if cond { a } else { b }`, `cond` must have static type `bool`.
|
||||
- Only the selected branch is evaluated at runtime.
|
||||
- The branch expressions `a` and `b` must have the same static type, subject only to ordinary contextual typing already defined elsewhere in the language.
|
||||
- The static result type of the `if` expression is that shared static type.
|
||||
- In `switch selector { pattern: { ... }, ... }`, the selector expression is evaluated once.
|
||||
- `switch` accepts enum selectors and literal-comparable scalar selectors; `error` selectors are invalid.
|
||||
- Each non-wildcard `switch` arm pattern must be unique within the same `switch`.
|
||||
- Each non-wildcard `switch` arm pattern must be type-compatible with the selector expression.
|
||||
- Enum-case switch patterns must resolve to declared cases of the selector's enum type.
|
||||
- Error labels are not valid switch patterns.
|
||||
- `default` and `_` are equivalent wildcard spellings for `switch`.
|
||||
- At most one wildcard arm may appear in a `switch`.
|
||||
- A `switch` must not mix `default` and `_` in the same arm set.
|
||||
- The blocks of all `switch` arms must have the same static type, subject only to ordinary contextual typing already defined elsewhere in the language.
|
||||
- The static result type of the `switch` expression is that shared static type.
|
||||
- A `switch` used as an `ExprStmt` is valid when the selected arm blocks evaluate to unit.
|
||||
- A `switch` expression used in a value-required position must be exhaustive, either by a wildcard arm or by another statically proven exhaustive case set.
|
||||
|
||||
### 3.16 `optional` construction and extraction
|
||||
|
||||
Rules:
|
||||
|
||||
- `some(expr)` forms an `optional<P>` value where `P` is the static type of `expr`, unless an expected `optional<Q>` context is present and constrains `expr` to be compatible with `Q`.
|
||||
- `some(expr)` is invalid when the payload normalizes to `void`.
|
||||
- `none` is valid only when an expected `optional<P>` type is available from context.
|
||||
- `opt else fallback` requires the left operand to have static type `optional<P>`.
|
||||
- In `opt else fallback`, the `fallback` expression must be compatible with payload shape `P`.
|
||||
- The static result type of `opt else fallback` is the carrier value type for single-slot payloads and the named tuple payload shape for multi-slot payloads.
|
||||
- `opt else fallback` does not introduce implicit mutation or unwrapping side effects beyond normal expression evaluation.
|
||||
|
||||
### 3.17 `result<E>` return flow and handling
|
||||
|
||||
Rules:
|
||||
|
||||
- `return ok(expr);` is valid only inside a function whose declared return surface is `result<E> P`.
|
||||
- In `return ok(expr);`, `expr` must be compatible with the declared success payload shape `P`.
|
||||
- `return err(E.label);` is valid only inside a function whose declared return surface is `result<E> P`.
|
||||
- In `return err(E.label);`, the error path must resolve to a declared case of the same error type `E`.
|
||||
- `ok(...)` and `err(...)` are special result-flow forms rather than ordinary value expressions.
|
||||
- `expr!` requires `expr` to have static type `result<E> P`.
|
||||
- `expr!` is valid only when the enclosing function returns `result<E> Q` for the same error type `E`.
|
||||
- The static result type of `expr!` is the extracted success payload shape `P`, collapsed to its carrier value when single-slot.
|
||||
- `handle expr { ... }` requires `expr` to have static type `result<E1> P`.
|
||||
- `handle expr { ... }` is valid only when the enclosing function returns `result<E2> Q` for some payload `Q`.
|
||||
- Each non-wildcard `handle` arm must match a distinct declared case of `E1`.
|
||||
- `handle` arms must be exhaustive over `E1`, either by naming all cases exactly once or by providing `_`.
|
||||
- The static result type of `handle expr { ... }` is the extracted success payload shape `P`, collapsed to its carrier value when single-slot.
|
||||
- A short `handle` arm `E1.case -> E2.case` is valid only when `E2.case` resolves to a declared case of the target error type `E2`.
|
||||
- A block `handle` arm must terminate with either `ok(payload)` or `err(E2.case)`.
|
||||
- In a `handle` arm, `ok(payload)` is valid only when `payload` is compatible with the success payload shape `P`.
|
||||
- In a `handle` arm, `err(E2.case)` is valid only when `E2.case` resolves to a declared case of the target error type `E2`.
|
||||
- In a `handle` arm, `ok(payload)` yields the value of the `handle` expression, while `err(E2.case)` performs immediate enclosing-function return.
|
||||
|
||||
### 3.18 Required static diagnostics
|
||||
|
||||
At minimum, deterministic static diagnostics are required for:
|
||||
|
||||
- duplicate parameter names in `fn` declarations,
|
||||
- duplicate declaration names in the same namespace/scope,
|
||||
- duplicate output labels in named tuple returns,
|
||||
- duplicate error case labels in `declare error`,
|
||||
- duplicate enum case labels in `declare enum`,
|
||||
- duplicate enum case identifiers in `declare enum`,
|
||||
- invalid mixed implicit/explicit enum case identifiers,
|
||||
- invalid `this` usage outside struct method, service method, or `ctor` body,
|
||||
- invalid `Self` type usage outside struct method, service method, or `ctor` declarations,
|
||||
- invalid struct method declaration shape,
|
||||
- invalid service method declaration shape,
|
||||
- invalid host declaration shape,
|
||||
- invalid host method declaration shape,
|
||||
- invalid attribute surface,
|
||||
- invalid `Host` attribute target,
|
||||
- invalid `Capability` attribute target,
|
||||
- invalid `BuiltinType` attribute target,
|
||||
- invalid `BuiltinConst` attribute target,
|
||||
- invalid `IntrinsicCall` attribute target,
|
||||
- duplicate `Host` attribute on one host method,
|
||||
- missing required `Host` attribute on a reserved host method,
|
||||
- malformed `Host(module=..., name=..., version=...)` argument set,
|
||||
- invalid empty `Host.module` or `Host.name`,
|
||||
- invalid non-positive `Host.version`,
|
||||
- malformed `Capability(name=...)` argument set,
|
||||
- invalid empty or non-canonical `Capability.name`,
|
||||
- invalid builtin declaration shape,
|
||||
- invalid builtin method declaration shape,
|
||||
- missing required `BuiltinType` attribute on a reserved builtin declaration,
|
||||
- malformed `BuiltinType(name=..., version=...)` argument set,
|
||||
- invalid empty `BuiltinType.name`,
|
||||
- invalid non-positive `BuiltinType.version`,
|
||||
- malformed `IntrinsicCall(name=..., version=...)` argument set,
|
||||
- invalid empty `IntrinsicCall.name`,
|
||||
- invalid non-positive `IntrinsicCall.version`,
|
||||
- malformed `BuiltinConst(target=..., name=..., version=...)` argument set,
|
||||
- invalid empty `BuiltinConst.target` or `BuiltinConst.name`,
|
||||
- invalid non-positive `BuiltinConst.version`,
|
||||
- builtin field type not builtin-layout-admissible,
|
||||
- cyclic builtin layout composition,
|
||||
- unresolved flattened builtin layout width,
|
||||
- duplicate canonical builtin type identity,
|
||||
- duplicate canonical builtin intrinsic identity,
|
||||
- duplicate canonical builtin constant identity,
|
||||
- invalid `ctor` declaration shape,
|
||||
- invalid `return` inside `ctor`,
|
||||
- incomplete field initialization on a completing `ctor` path,
|
||||
- duplicate `implements Contract for Owner` pair,
|
||||
- `implements` declared outside the owner module of the struct or service,
|
||||
- incompatible or missing contract method implementation,
|
||||
- invalid contract coercion from concrete struct or service value,
|
||||
- unresolved barrel function signature after label-insensitive matching,
|
||||
- unresolved host barrel entry,
|
||||
- unresolved callback barrel entry,
|
||||
- invalid enum case path,
|
||||
- invalid enum intrinsic member call,
|
||||
- invalid named constructor target,
|
||||
- unresolved named constructor overload,
|
||||
- ambiguous named constructor overload,
|
||||
- incompatible top-level `fn` assignment to callback type,
|
||||
- ambiguous overloaded top-level `fn` assignment to callback type,
|
||||
- attempted assignment of service method to callback type,
|
||||
- attempted assignment of host method to callback type,
|
||||
- use of `bind(...)` without an expected callback type,
|
||||
- incompatible `bind(...)` context type for callback target,
|
||||
- ambiguous overloaded top-level `fn` target in `bind(...)`,
|
||||
- `apply` on a non-callable target,
|
||||
- arity mismatch in `apply`,
|
||||
- argument type mismatch in `apply`,
|
||||
- `apply` chain with incompatible intermediate carrier/tuple shape,
|
||||
- ambiguous overload resolution,
|
||||
- unresolved callable application,
|
||||
- possible fallthrough of plain non-unit function,
|
||||
- non-boolean `while` condition,
|
||||
- invalid `for` iteration type,
|
||||
- incompatible `for` bound or step type,
|
||||
- non-boolean `if` expression condition,
|
||||
- incompatible `if` expression branch types,
|
||||
- duplicate `switch` arm pattern,
|
||||
- mixed `default` and `_` wildcard arms in `switch`,
|
||||
- invalid `switch` selector type,
|
||||
- selector-pattern type mismatch in `switch`,
|
||||
- invalid enum case switch pattern,
|
||||
- incompatible `switch` arm block types,
|
||||
- non-exhaustive `switch` expression in value position,
|
||||
- invalid mixed `optional`/`result` return surface,
|
||||
- invalid payload-less `optional` type surface,
|
||||
- invalid `optional void` type surface,
|
||||
- invalid reuse of a builtin simple type name for a user-authored type declaration,
|
||||
- missing explicit type annotation on `declare const`,
|
||||
- missing initializer on non-builtin `declare const`,
|
||||
- non-constant `declare const` initializer,
|
||||
- incompatible `declare const` initializer type,
|
||||
- cyclic dependency among `declare const` declarations,
|
||||
- unresolved referenced `declare const` in constant evaluation,
|
||||
- invalid `none` usage without expected optional type,
|
||||
- invalid `else` extraction over non-optional operand,
|
||||
- fallback type mismatch in `else` extraction,
|
||||
- invalid `some(...)` construction form,
|
||||
- use of `ok(...)` or `err(...)` outside allowed result-flow positions,
|
||||
- invalid `ok(...)` construction form,
|
||||
- invalid `err(...)` construction form,
|
||||
- invalid error label in `err(...)`,
|
||||
- invalid `!` propagation on non-result expression,
|
||||
- mismatched error type in `!` propagation,
|
||||
- invalid `handle` on non-result expression,
|
||||
- non-exhaustive `handle` mapping,
|
||||
- duplicate `handle` mapping arm,
|
||||
- invalid mapped error label in `handle`,
|
||||
- invalid `ok(...)` payload in `handle`,
|
||||
- invalid terminal form of a `handle` arm block,
|
||||
- attempted use of a single-slot tuple literal where no such surface form exists,
|
||||
- member access on a missing struct field,
|
||||
- read access to an inaccessible private struct field,
|
||||
- write access to an inaccessible or non-`pub mut` struct field,
|
||||
- member access on a missing struct method,
|
||||
- member access on a missing service method,
|
||||
- member access on a missing host method,
|
||||
- member access on a missing contract method,
|
||||
- member access on a missing builtin projection field,
|
||||
- member access on a missing builtin intrinsic member,
|
||||
- bare method extraction from a struct, service, host, builtin, or contract value,
|
||||
- member projection on a single-slot carrier value,
|
||||
- invalid optional intrinsic member call,
|
||||
- invalid builtin intrinsic member call,
|
||||
- member projection on a missing named output label.
|
||||
+452
@@ -0,0 +1,452 @@
|
||||
# PBS Manifest, Module, Stdlib, and SDK Resolution Specification
|
||||
|
||||
Status: Draft v2 (Normative)
|
||||
Applies to: `prometeu.json`, project and module terminology, workspace dependency resolution, stdlib selection, reserved stdlib projects, interface-module loading, and compile-time SDK metadata
|
||||
|
||||
## 1. Purpose
|
||||
|
||||
This document defines the normative compile-time model for:
|
||||
|
||||
- project manifests,
|
||||
- project and module identity,
|
||||
- import resolution,
|
||||
- stdlib selection,
|
||||
- reserved stdlib project spaces,
|
||||
- stdlib interface modules,
|
||||
- and the compile-time lifecycle of SDK host-binding metadata.
|
||||
|
||||
This document is the authority for how the compiler discovers and loads:
|
||||
|
||||
- ordinary project modules,
|
||||
- reserved stdlib modules such as `@sdk:gfx`,
|
||||
- compile-time reserved metadata attached to those reserved modules,
|
||||
- and interface-only service facades that wrap host surfaces for source ergonomics.
|
||||
|
||||
This document does not define runtime load behavior.
|
||||
PBX host-binding emission and loader-side syscall resolution are defined by the Host ABI Binding and Loader Resolution Specification.
|
||||
|
||||
## 2. Scope
|
||||
|
||||
This document defines:
|
||||
|
||||
- the role of `language` in `prometeu.json`,
|
||||
- the role of `stdlib` in `prometeu.json`,
|
||||
- the distinction between projects, modules, and imports,
|
||||
- the distinction between ordinary project dependencies and the stdlib environment,
|
||||
- root-project ownership of the effective stdlib line of a build,
|
||||
- reserved project spaces such as `@sdk:*` and `@core:*`,
|
||||
- the source model for stdlib interface modules,
|
||||
- the compile-time role of reserved attributes such as `[Host(...)]`.
|
||||
|
||||
This document does not define:
|
||||
|
||||
- PBX binary layout,
|
||||
- loader-side syscall resolution,
|
||||
- cartridge capability policy,
|
||||
- package registry protocol details,
|
||||
- runtime reflection over attributes.
|
||||
|
||||
## 3. Core Terms
|
||||
|
||||
### 3.1 Project
|
||||
|
||||
A project is the unit described by `prometeu.json`.
|
||||
|
||||
Rules:
|
||||
|
||||
- A project has a `name`, `version`, `language`, `stdlib`, and `dependencies`.
|
||||
- A project is the unit resolved by the workspace dependency graph.
|
||||
- A project is the unit selected by a dependency declaration.
|
||||
- A project is the unit published and versioned by ordinary dependency resolution.
|
||||
- A project contains one or more modules.
|
||||
|
||||
### 3.2 Module
|
||||
|
||||
A module is the unit of source import inside a project.
|
||||
|
||||
Rules:
|
||||
|
||||
- Every `.pbs` source file belongs to exactly one module.
|
||||
- Every module belongs to exactly one project.
|
||||
- Imports select modules, not whole projects.
|
||||
- A module is addressed by a project name plus a module path.
|
||||
|
||||
### 3.3 Canonical module address
|
||||
|
||||
The canonical PBS module address format is:
|
||||
|
||||
```text
|
||||
@project:path/to/module
|
||||
```
|
||||
|
||||
Rules:
|
||||
|
||||
- `project` identifies the owning project space.
|
||||
- `path/to/module` identifies the module path inside that project.
|
||||
- Module path segments are directory-style segments separated by `/`.
|
||||
- The syntax is Java-like in organization and JavaScript-like in import surface.
|
||||
|
||||
Examples:
|
||||
|
||||
- `@game:player/state`
|
||||
- `@physics:collision/shapes`
|
||||
- `@sdk:gfx`
|
||||
- `@core:math/vector`
|
||||
|
||||
### 3.4 Reserved project spaces
|
||||
|
||||
The following project spaces are reserved:
|
||||
|
||||
- `@sdk:*`
|
||||
- `@core:*`
|
||||
|
||||
Rules:
|
||||
|
||||
- Reserved project spaces belong to the selected stdlib environment.
|
||||
- Ordinary user-authored projects MUST NOT publish modules into reserved project spaces.
|
||||
- Ordinary dependency resolution MUST NOT satisfy `@sdk:*` or `@core:*` imports from user projects.
|
||||
- Reserved project spaces are resolved only from the selected stdlib environment.
|
||||
|
||||
## 4. `prometeu.json`
|
||||
|
||||
### 4.1 Required fields
|
||||
|
||||
The manifest format relevant to this document is:
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "main",
|
||||
"version": "1.0.0",
|
||||
"language": "pbs",
|
||||
"stdlib": "1",
|
||||
"dependencies": [
|
||||
{ "name": "dep1", "version": "1.0.0" }
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
Rules:
|
||||
|
||||
- `name` identifies the project.
|
||||
- `version` identifies the project version.
|
||||
- `language` identifies the frontend language.
|
||||
- `stdlib` identifies the selected stdlib major line.
|
||||
- `dependencies` declare ordinary project dependencies only.
|
||||
|
||||
### 4.2 `language`
|
||||
|
||||
Rules:
|
||||
|
||||
- `language` selects the compiler frontend.
|
||||
- All projects in one resolved workspace MUST use the same `language`.
|
||||
- Unknown `language` values are compile-time errors.
|
||||
|
||||
### 4.3 `stdlib`
|
||||
|
||||
Rules:
|
||||
|
||||
- `stdlib` is required in every manifest.
|
||||
- `stdlib` uses major-only version syntax in v1.
|
||||
- The manifest surface for `stdlib` is a string containing a positive decimal integer.
|
||||
- Examples of valid values: `"1"`, `"2"`.
|
||||
- Examples of invalid values: `"0"`, `"01"`, `"1.0"`, `"v1"`, `""`.
|
||||
- Implementations SHOULD normalize `stdlib` internally to an integer major version.
|
||||
|
||||
Diagnostics:
|
||||
|
||||
- Missing `stdlib` is a manifest error.
|
||||
- Invalid major-only format is a manifest error.
|
||||
|
||||
## 5. Ordinary Dependencies vs Stdlib Environment
|
||||
|
||||
### 5.1 Ordinary dependencies
|
||||
|
||||
Rules:
|
||||
|
||||
- `dependencies` model ordinary project relationships only.
|
||||
- A dependency may be local or registry-based according to the compiler's dependency resolver.
|
||||
- Dependencies contribute source projects, modules, and project-graph edges.
|
||||
- `dependencies` do not declare stdlib projects.
|
||||
|
||||
### 5.2 Stdlib environment
|
||||
|
||||
Rules:
|
||||
|
||||
- The stdlib environment is not declared through `dependencies`.
|
||||
- The stdlib environment is selected through `stdlib`.
|
||||
- `@sdk:*` and `@core:*` imports resolve against the stdlib environment selected for the build.
|
||||
- The presence of stdlib modules does not imply automatic visibility in source.
|
||||
- User code MUST still import stdlib modules explicitly through ordinary import syntax.
|
||||
|
||||
Example:
|
||||
|
||||
```pbs
|
||||
import { Gfx, color } from @sdk:gfx;
|
||||
|
||||
let c: color = color.red;
|
||||
Gfx.draw_pixel(1, 1, c);
|
||||
```
|
||||
|
||||
Rules:
|
||||
|
||||
- `Gfx` is not implicitly in scope.
|
||||
- `Gfx` becomes visible only through `import`.
|
||||
- The compiler accepts that import because the selected stdlib environment exposes `@sdk:gfx`.
|
||||
|
||||
## 6. Effective Stdlib of the Build
|
||||
|
||||
The root project owns the effective stdlib line of the build.
|
||||
|
||||
Rules:
|
||||
|
||||
- The resolved workspace has exactly one effective stdlib major version.
|
||||
- The effective stdlib major version is taken from the root project manifest.
|
||||
- All projects in the workspace compile under that same effective stdlib line.
|
||||
- Dependency projects do not activate separate stdlib environments for themselves.
|
||||
|
||||
This means:
|
||||
|
||||
- `stdlib` on a dependency is a compatibility declaration,
|
||||
- not an instruction to switch the compiler into another stdlib mode for that dependency.
|
||||
|
||||
## 7. Stdlib Compatibility Across Dependency Projects
|
||||
|
||||
Let:
|
||||
|
||||
- `R` be the root project's `stdlib` major,
|
||||
- `D` be a dependency project's `stdlib` major.
|
||||
|
||||
Rules:
|
||||
|
||||
- If `D > R`, dependency resolution MUST fail with a deterministic compile-time error.
|
||||
- If `D <= R`, dependency resolution MAY proceed.
|
||||
- `D <= R` does not guarantee semantic compatibility of all APIs used by the dependency; it only means the dependency is not asking for a newer stdlib line than the root selected.
|
||||
|
||||
Rationale:
|
||||
|
||||
- the build target is chosen by the root project,
|
||||
- dependency projects may target the same or an older stdlib line,
|
||||
- dependency projects must not force the build to silently adopt a newer stdlib than the root requested.
|
||||
|
||||
Example:
|
||||
|
||||
- root `stdlib = "1"`, dependency `stdlib = "2"`: error.
|
||||
- root `stdlib = "2"`, dependency `stdlib = "1"`: allowed.
|
||||
- root `stdlib = "1"`, dependency `stdlib = "1"`: allowed.
|
||||
|
||||
## 8. Import Resolution
|
||||
|
||||
### 8.1 Resolution sources
|
||||
|
||||
The compiler resolves imports against exactly two sources:
|
||||
|
||||
1. the selected stdlib environment,
|
||||
2. the resolved ordinary project dependency graph.
|
||||
|
||||
Rules:
|
||||
|
||||
- `@sdk:*` and `@core:*` are resolved only against the stdlib environment,
|
||||
- all other `@project:*` imports are resolved only against the ordinary dependency graph,
|
||||
- there is no fallback from reserved stdlib resolution to ordinary dependencies,
|
||||
- there is no fallback from ordinary dependency resolution to reserved stdlib spaces.
|
||||
|
||||
### 8.2 Resolution algorithm
|
||||
|
||||
For an import:
|
||||
|
||||
```pbs
|
||||
import { X } from @project:path/to/module;
|
||||
```
|
||||
|
||||
the compiler MUST:
|
||||
|
||||
1. parse the project space and module path,
|
||||
2. determine whether the project space is reserved,
|
||||
3. if reserved, resolve the module from the selected stdlib environment,
|
||||
4. otherwise, resolve the module from the root project or its dependency graph,
|
||||
5. load the target module,
|
||||
6. resolve the requested exported names from that module.
|
||||
|
||||
Failure at any step is a deterministic compile-time error.
|
||||
|
||||
## 9. Stdlib Interface Modules
|
||||
|
||||
### 9.1 Interface-module model
|
||||
|
||||
The selected stdlib environment MUST provide its modules as PBS-like interface modules.
|
||||
|
||||
Rules:
|
||||
|
||||
- Stdlib modules are `.pbs` modules loaded by the compiler.
|
||||
- Stdlib interface modules use the same parser surface as ordinary PBS modules.
|
||||
- Stdlib interface modules are interpreted in interface-module mode.
|
||||
- Interface-module mode is non-executable and compile-time only.
|
||||
- Interface modules participate in import resolution and type checking.
|
||||
- Interface modules do not emit executable bytecode by themselves.
|
||||
|
||||
### 9.2 Allowed role
|
||||
|
||||
At minimum, an interface module may provide:
|
||||
|
||||
- exported names,
|
||||
- types,
|
||||
- enums,
|
||||
- host owners,
|
||||
- method signatures,
|
||||
- compile-time metadata such as canonical host-binding attributes.
|
||||
|
||||
This list fixes the currently required declarative role of interface modules, but does not by itself freeze the final complete declaration set allowed in interface-module mode.
|
||||
|
||||
An interface module is not runtime code.
|
||||
|
||||
### 9.3 Interface-module restrictions
|
||||
|
||||
At minimum, an interface module MUST remain declarative.
|
||||
|
||||
Rules:
|
||||
|
||||
- Interface modules MUST NOT contain top-level executable statements.
|
||||
- Interface modules MUST NOT require runtime initialization.
|
||||
- Interface modules MUST NOT introduce executable method bodies that would emit bytecode.
|
||||
- `declare host` is permitted only in reserved stdlib/toolchain interface modules.
|
||||
- Reserved attributes such as `[Host(...)]` are permitted only where another specification explicitly allows them.
|
||||
|
||||
### 9.4 Example interface module
|
||||
|
||||
Illustrative stdlib interface module:
|
||||
|
||||
```pbs
|
||||
declare enum color(red, green, blue);
|
||||
|
||||
declare host Gfx {
|
||||
[Host(module = "gfx", name = "draw_pixel", version = 1)]
|
||||
fn draw_pixel(x: int, y: int, c: color);
|
||||
}
|
||||
```
|
||||
|
||||
Rules:
|
||||
|
||||
- This module is valid only in a reserved stdlib/interface-module context.
|
||||
- It contributes compile-time symbols and metadata.
|
||||
- It does not produce executable bytecode by itself.
|
||||
|
||||
## 10. Compiler Loading of the Stdlib Environment
|
||||
|
||||
The compiler loads the stdlib environment from the stdlib line selected by the root project.
|
||||
|
||||
Required model:
|
||||
|
||||
1. Read the root `prometeu.json`.
|
||||
2. Determine the effective stdlib major line.
|
||||
3. Mount or select the matching stdlib environment.
|
||||
4. Expose its reserved project spaces such as `@sdk:*` and `@core:*`.
|
||||
5. Load interface modules from that environment on demand during import resolution.
|
||||
6. Parse those modules with the ordinary PBS parser.
|
||||
7. Validate them under interface-module semantic rules.
|
||||
8. Populate the compiler's symbol graph from their exported declarations and attributes.
|
||||
|
||||
Rules:
|
||||
|
||||
- The compiler MUST behave as if it were loading real modules, not hardcoded symbol tables.
|
||||
- The physical storage format of the stdlib environment is an implementation detail.
|
||||
- The compiler MAY load the stdlib environment from disk, embedded resources, a virtual filesystem, or another implementation-defined source with equivalent behavior.
|
||||
- For the Studio PBS frontend, embedding stdlib interface modules under frontend `resources` is a valid implementation strategy.
|
||||
|
||||
## 11. Reserved Attributes and Metadata Lifecycle
|
||||
|
||||
### 11.1 General rule
|
||||
|
||||
Attributes are compile-time metadata, not runtime objects.
|
||||
|
||||
Rules:
|
||||
|
||||
- Attributes are parsed as part of the source module.
|
||||
- Attributes participate in declaration validation and compiler metadata extraction.
|
||||
- Attributes are not exported as ordinary values, types, or runtime-reflectable objects.
|
||||
- Attributes do not automatically survive into bytecode, PBX, or runtime metadata.
|
||||
|
||||
### 11.2 `Host` attribute
|
||||
|
||||
The canonical reserved host-binding attribute is:
|
||||
|
||||
```pbs
|
||||
[Host(module = "gfx", name = "draw_pixel", version = 1)]
|
||||
```
|
||||
|
||||
Rules:
|
||||
|
||||
- `Host` is valid only on a host method signature declared directly inside a reserved stdlib/interface-module `declare host` body.
|
||||
- `Host` provides the canonical host primitive identity used by compiler lowering.
|
||||
- `module` and `name` are string literals.
|
||||
- `version` is a positive integer literal.
|
||||
- The attribute surface itself is compile-time only.
|
||||
|
||||
### 11.3 Lowering effect
|
||||
|
||||
Although the attribute syntax itself is compile-time only, its semantic effect may be lowered.
|
||||
|
||||
Rules:
|
||||
|
||||
- The compiler consumes `Host` metadata while resolving host-backed SDK members.
|
||||
- The compiler uses that metadata to emit runtime-facing host-binding declarations as defined by the Host ABI Binding specification.
|
||||
- The compiler does not export the raw `[Host(...)]` syntax into runtime as a source-level attribute object.
|
||||
|
||||
In other words:
|
||||
|
||||
- the attribute is compile-time metadata,
|
||||
- the lowered host-binding declaration is runtime-facing artifact metadata,
|
||||
- they are not the same thing.
|
||||
|
||||
## 12. Relationship to `declare host`
|
||||
|
||||
Rules:
|
||||
|
||||
- `declare host` remains reserved to SDK/toolchain-controlled modules.
|
||||
- Ordinary user-authored project modules do not declare canonical host bindings directly.
|
||||
- User code consumes SDK exports through normal imports.
|
||||
- SDK-facing surfaces such as `Gfx.draw_pixel(...)` are resolved by the compiler against the selected stdlib environment.
|
||||
- Canonical host identity comes from reserved host-binding metadata such as `[Host(...)]`, not from the source spelling of the imported owner.
|
||||
|
||||
## 13. Project Publication and Distribution
|
||||
|
||||
Rules:
|
||||
|
||||
- Ordinary publication and dependency resolution operate at project granularity.
|
||||
- A published project version contains one or more modules.
|
||||
- Imports consume modules from a resolved project.
|
||||
- The stdlib environment is distributed separately from ordinary project dependencies.
|
||||
- The stdlib environment is selected by `stdlib`, not by `dependencies`.
|
||||
|
||||
## 14. Non-Goals
|
||||
|
||||
- Making stdlib modules implicitly visible without `import`.
|
||||
- Treating the stdlib as an ordinary dependency in the workspace graph.
|
||||
- Allowing each dependency project to activate its own stdlib line.
|
||||
- Hardcoding stdlib symbols directly into the compiler without a module model.
|
||||
- Runtime reflection over source-level attributes.
|
||||
|
||||
## 15. Open Items Deferred
|
||||
|
||||
The following remain intentionally deferred:
|
||||
|
||||
1. Exact on-disk distribution format of stdlib environment packs.
|
||||
2. Registry/publication protocol details for ordinary projects.
|
||||
3. Final diagnostics catalog for all import-resolution failures.
|
||||
4. Full list of declarations allowed inside interface modules beyond the already-fixed reserved host surfaces.
|
||||
|
||||
## 16. Current Decision Summary
|
||||
|
||||
The current PBS design direction is:
|
||||
|
||||
1. `prometeu.json` declares `language` and `stdlib` separately.
|
||||
2. A project is the unit described by `prometeu.json` and selected by `dependencies`.
|
||||
3. A module is the unit selected by `import`.
|
||||
4. Canonical module addresses use `@project:path/to/module`.
|
||||
5. `@sdk:*` and `@core:*` are reserved stdlib project spaces.
|
||||
6. The root project selects the effective stdlib line for the whole build.
|
||||
7. Dependency projects with a higher stdlib requirement than the root are rejected.
|
||||
8. Stdlib modules are loaded as PBS-like interface modules, not as ordinary dependencies.
|
||||
9. Interface modules are compile-time-only in packaging terms: they may carry declarative service facades with method bodies for source-level API ergonomics, but they still do not emit executable bytecode as standalone modules.
|
||||
10. `declare host` remains reserved to stdlib/toolchain interface modules.
|
||||
11. Reserved attributes such as `[Host(...)]` are compile-time metadata, not runtime objects.
|
||||
12. The compiler consumes `Host` metadata to produce runtime-facing host-binding artifacts defined elsewhere.
|
||||
@@ -0,0 +1,377 @@
|
||||
# VM-owned vs Host-backed
|
||||
|
||||
Status: Draft v1 (Temporary)
|
||||
Applies to: ownership classification of PBS-visible operations, runtime boundary selection, and the normative distinction between VM-defined semantics and host-provided services
|
||||
|
||||
## 1. Purpose
|
||||
|
||||
This document defines the normative distinction between:
|
||||
|
||||
- VM-owned operations,
|
||||
- host-backed operations,
|
||||
- and user-defined program operations.
|
||||
|
||||
Its purpose is to prevent semantic drift between:
|
||||
|
||||
- builtin language behavior,
|
||||
- VM execution behavior,
|
||||
- host/platform integration,
|
||||
- and source-level surfaces that may look similar while belonging to different ownership domains.
|
||||
|
||||
This document exists because PBS must distinguish at least three different kinds
|
||||
of callable behavior:
|
||||
|
||||
- program-owned functions,
|
||||
- VM-owned intrinsic behavior,
|
||||
- host-backed services.
|
||||
|
||||
Without this distinction, the language would conflate:
|
||||
|
||||
- builtin semantics with syscalls,
|
||||
- source-level shells with runtime authority,
|
||||
- and VM contracts with host capability-gated services.
|
||||
|
||||
## 2. Scope
|
||||
|
||||
This document defines:
|
||||
|
||||
- the ownership model for callable behavior visible to PBS programs,
|
||||
- the normative difference between VM-owned and host-backed operations,
|
||||
- the runtime boundary crossed by each operation category,
|
||||
- the relationship between ownership and lowering form,
|
||||
- the relationship between ownership and determinism,
|
||||
- the relationship between ownership and capability checks,
|
||||
- the relationship between ownership and loader resolution,
|
||||
- and the classification rule used to decide whether a surface belongs to the VM or to the host.
|
||||
|
||||
This document does not define:
|
||||
|
||||
- the full parser grammar for builtin declarations,
|
||||
- the full intrinsic registry binary format,
|
||||
- the final PBX section numbering for intrinsic metadata,
|
||||
- subsystem-specific host APIs such as GFX or AUDIO,
|
||||
- or the complete dynamic semantics of every builtin type.
|
||||
|
||||
## 3. Authority and Precedence
|
||||
|
||||
Normative precedence:
|
||||
|
||||
1. Runtime authority (`docs/specs/hardware/topics/chapter-2.md`, `chapter-3.md`, `chapter-9.md`, `chapter-12.md`, `chapter-16.md`)
|
||||
2. Bytecode authority (`docs/specs/bytecode/ISA_CORE.md`)
|
||||
3. `1. Language Charter.md`
|
||||
4. `3. Core Syntax Specification.md`
|
||||
5. `4. Static Semantics Specification.md`
|
||||
6. `5. Manifest, Stdlib, and SDK Resolution Specification.md`
|
||||
7. `6.2. Host ABI Binding and Loader Resolution Specification.md`
|
||||
8. This document
|
||||
|
||||
If a rule here conflicts with higher-precedence authority, the higher-precedence
|
||||
authority wins.
|
||||
|
||||
## 4. Normative Inputs
|
||||
|
||||
This document depends on, at minimum:
|
||||
|
||||
- `1. Language Charter.md`
|
||||
- `3. Core Syntax Specification.md`
|
||||
- `4. Static Semantics Specification.md`
|
||||
- `5. Manifest, Stdlib, and SDK Resolution Specification.md`
|
||||
- `6.2. Host ABI Binding and Loader Resolution Specification.md`
|
||||
|
||||
## 5. Core Ownership Model
|
||||
|
||||
PBS distinguishes three ownership categories for callable behavior.
|
||||
|
||||
### 5.1 Program-owned function
|
||||
|
||||
A program-owned function is authored by the program and compiled from a PBS body.
|
||||
|
||||
Properties:
|
||||
|
||||
- semantic ownership belongs to the program,
|
||||
- execution stays inside the VM,
|
||||
- source definition includes an executable body,
|
||||
- runtime dispatch uses ordinary function-call machinery,
|
||||
- authority does not depend on host capability grants.
|
||||
|
||||
### 5.2 VM-owned operation
|
||||
|
||||
A VM-owned operation is part of the semantic contract of the PBS platform.
|
||||
|
||||
Properties:
|
||||
|
||||
- semantic ownership belongs to the VM platform,
|
||||
- execution stays inside the VM,
|
||||
- behavior is not defined by user-authored PBS bodies,
|
||||
- behavior is not resolved against host registries,
|
||||
- behavior is not granted or denied by host capabilities,
|
||||
- and behavior is expected to remain semantically canonical across conforming implementations.
|
||||
|
||||
VM-owned operations include, at minimum:
|
||||
|
||||
- intrinsic operations over builtin types,
|
||||
- compiler-recognized intrinsic method-call surfaces over core semantic forms,
|
||||
- and other future VM-defined semantic helpers explicitly designated by spec.
|
||||
|
||||
### 5.3 Host-backed operation
|
||||
|
||||
A host-backed operation is provided by the runtime environment outside the VM's
|
||||
closed semantic domain.
|
||||
|
||||
Properties:
|
||||
|
||||
- semantic authority belongs to the host platform,
|
||||
- execution crosses the VM-to-host boundary,
|
||||
- resolution uses canonical host identity,
|
||||
- loader validation and capability checks are required before execution,
|
||||
- and the final executable form is numeric host dispatch.
|
||||
|
||||
Host-backed operations are the domain of `declare host`, PBX `SYSC`, loader
|
||||
resolution, and final `SYSCALL`.
|
||||
|
||||
## 6. The Boundary Question
|
||||
|
||||
The normative classification question is:
|
||||
|
||||
```text
|
||||
Does this operation belong to the VM's semantic contract, or does it require a
|
||||
service owned by the external host platform?
|
||||
```
|
||||
|
||||
Rules:
|
||||
|
||||
- If the operation expresses builtin language or VM semantics, it is VM-owned.
|
||||
- If the operation requires host-provided authority, devices, or platform services, it is host-backed.
|
||||
- If the operation is implemented by ordinary source code in the current program, it is program-owned.
|
||||
|
||||
Heuristic:
|
||||
|
||||
- if the operation must still have a complete meaning in a host-minimal VM, it is VM-owned,
|
||||
- if the operation loses meaning without external platform service, it is host-backed.
|
||||
|
||||
Examples:
|
||||
|
||||
- `Vec2.dot(other)` is VM-owned,
|
||||
- `Color.rgb(r, g, b)` is VM-owned,
|
||||
- `optional.hasSome()` is VM-owned,
|
||||
- `enumValue.name()` is VM-owned,
|
||||
- `Gfx.draw_pixel(x, y, c)` is host-backed,
|
||||
- `Input.is_pressed(button)` is host-backed.
|
||||
|
||||
## 7. Runtime Boundary and Resolution Model
|
||||
|
||||
### 7.1 VM-owned operations
|
||||
|
||||
VM-owned operations do not cross the host boundary.
|
||||
|
||||
Rules:
|
||||
|
||||
- they do not resolve through the host syscall registry,
|
||||
- they do not emit `SYSC`,
|
||||
- they do not require loader-side capability checks,
|
||||
- they are not represented by `declare host`,
|
||||
- and they execute through VM-owned machinery such as intrinsic dispatch or other VM-defined execution paths.
|
||||
|
||||
### 7.2 Host-backed operations
|
||||
|
||||
Host-backed operations cross the VM boundary and require host authority.
|
||||
|
||||
Rules:
|
||||
|
||||
- they resolve by canonical host identity `(module, name, version)`,
|
||||
- they are represented in source through reserved host-binding surfaces,
|
||||
- they emit PBX host-binding metadata,
|
||||
- they are validated against authoritative host metadata during load,
|
||||
- and they execute in final form through `SYSCALL`.
|
||||
|
||||
## 8. Semantic Authority
|
||||
|
||||
The semantic owner of an operation is the layer that defines its normative
|
||||
meaning.
|
||||
|
||||
### 8.1 VM-owned semantic authority
|
||||
|
||||
For VM-owned operations:
|
||||
|
||||
- the VM platform defines the operation's meaning,
|
||||
- the frontend may expose shell declarations but does not define behavior,
|
||||
- the host runtime must not redefine the operation's language-level semantics,
|
||||
- and the HAL may consume produced values but must not own their semantic definition.
|
||||
|
||||
### 8.2 Host-backed semantic authority
|
||||
|
||||
For host-backed operations:
|
||||
|
||||
- the host platform defines the authoritative service identity and ABI,
|
||||
- the frontend exposes a compile-time shell only,
|
||||
- the loader resolves the shell's canonical identity against the host registry,
|
||||
- and the VM executes only the numeric form after loader patching.
|
||||
|
||||
## 9. Determinism and Environmental Dependence
|
||||
|
||||
Determinism requirements differ by ownership category.
|
||||
|
||||
### 9.1 VM-owned operations
|
||||
|
||||
VM-owned operations must not derive meaning from host service behavior.
|
||||
|
||||
Rules:
|
||||
|
||||
- a VM-owned operation must not call the host as part of its semantic definition,
|
||||
- a VM-owned operation must not require host capability grants,
|
||||
- a VM-owned operation must not depend on wall-clock time unless a higher-precedence authority explicitly allows it,
|
||||
- a VM-owned operation must not depend on frontend-generated helper algorithms for its canonical behavior,
|
||||
- and the VM contract must be specific enough that conformance can test its behavior.
|
||||
|
||||
This does not require every VM-owned operation to be mathematically pure.
|
||||
It does require the operation's meaning to be owned and specified by the VM
|
||||
contract rather than delegated to the host.
|
||||
|
||||
### 9.2 Host-backed operations
|
||||
|
||||
Host-backed operations may depend on host state, devices, permissions, or
|
||||
platform policy.
|
||||
|
||||
Rules:
|
||||
|
||||
- host-backed operations may be denied by capability policy,
|
||||
- host-backed operations may vary by platform implementation within their ABI contract,
|
||||
- and host-backed operations are not reclassified as VM-owned merely because the source surface resembles an ordinary method call.
|
||||
|
||||
## 10. Artifact Implications
|
||||
|
||||
Ownership classification determines artifact form.
|
||||
|
||||
### 10.1 Program-owned function artifact direction
|
||||
|
||||
Program-owned functions lower to ordinary program call machinery.
|
||||
|
||||
### 10.2 VM-owned artifact direction
|
||||
|
||||
VM-owned operations lower to VM-facing artifacts.
|
||||
|
||||
Illustrative forms:
|
||||
|
||||
- direct intrinsic ids such as `INTRINSIC <id>`,
|
||||
- temporary intrinsic declaration tables plus pre-resolution callsites,
|
||||
- or other VM-internal runtime forms explicitly defined by future spec.
|
||||
|
||||
Rules:
|
||||
|
||||
- VM-owned operations must not be encoded as host-binding metadata merely because they are not authored in user code,
|
||||
- and VM-owned operations must not require host registry lookup.
|
||||
|
||||
### 10.3 Host-backed artifact direction
|
||||
|
||||
Host-backed operations lower to host-facing artifacts.
|
||||
|
||||
Rules:
|
||||
|
||||
- host-backed operations emit host-binding declarations into `SYSC`,
|
||||
- host-backed callsites use `HOSTCALL <sysc_index>` before load,
|
||||
- the loader resolves and patches those callsites,
|
||||
- and final execution uses `SYSCALL <id>`.
|
||||
|
||||
## 11. Source Surface Similarity Does Not Collapse Ownership
|
||||
|
||||
Two source surfaces may look similar while belonging to different ownership
|
||||
domains.
|
||||
|
||||
Examples:
|
||||
|
||||
- `Vec2.length()` may be VM-owned,
|
||||
- `Gfx.clear(color)` may be host-backed,
|
||||
- `value.name()` over an enum may be VM-owned,
|
||||
- and `service.method()` may be program-owned or service-owned ordinary PBS behavior.
|
||||
|
||||
Rules:
|
||||
|
||||
- source-level method-call syntax does not determine ownership,
|
||||
- declaration shape does not determine ownership,
|
||||
- ownership is determined by semantic authority and runtime boundary,
|
||||
- and toolchain metadata must classify the operation explicitly where ambiguity could arise.
|
||||
|
||||
## 12. Relationship to `declare host`
|
||||
|
||||
`declare host` is reserved exclusively for host-backed surfaces.
|
||||
|
||||
Rules:
|
||||
|
||||
- `declare host` must not be reused to model VM-owned builtin semantics,
|
||||
- host attributes such as `Host(module, name, version)` must not be used to identify VM-owned intrinsic behavior,
|
||||
- and a source surface that represents VM-owned behavior must use VM-specific metadata and lowering rules.
|
||||
|
||||
Rationale:
|
||||
|
||||
- `declare host` communicates external service ownership,
|
||||
- host attributes communicate loader-facing canonical identity,
|
||||
- and reusing them for VM-owned behavior would incorrectly imply host resolution, capability gating, and host semantic authority.
|
||||
|
||||
## 13. Relationship to Builtin Types and Intrinsics
|
||||
|
||||
Builtin types are VM-facing semantic types.
|
||||
|
||||
Rules:
|
||||
|
||||
- builtin types are not host APIs,
|
||||
- builtin type operations that belong to the builtin domain are VM-owned,
|
||||
- builtin constants, projections, constructors, and intrinsic methods are classified by VM semantics rather than by host service ownership,
|
||||
- and builtin values may later be passed to host-backed operations without transferring semantic ownership of the type itself.
|
||||
|
||||
Example:
|
||||
|
||||
- `Color` is VM-owned as a semantic type,
|
||||
- `Color.rgb(...)` is VM-owned,
|
||||
- `Pixel` may contain `Color` in its builtin layout,
|
||||
- `Gfx.draw_pixel(x, y, c)` is host-backed even when `c` has a VM-owned builtin type.
|
||||
|
||||
## 14. Relationship to `stdlib` and SDK Surfaces
|
||||
|
||||
`stdlib` and SDK packaging expose compile-time surfaces.
|
||||
|
||||
Rules:
|
||||
|
||||
- SDK or stdlib shells may expose both VM-owned and host-backed surfaces,
|
||||
- shell placement alone does not determine runtime ownership,
|
||||
- the runtime-facing artifact contract must preserve the true ownership category,
|
||||
- and compile-time convenience must not collapse VM-owned and host-backed operations into the same runtime mechanism.
|
||||
|
||||
## 15. Classification Checklist
|
||||
|
||||
When introducing a new callable surface, the spec author or toolchain author
|
||||
must answer at least these questions:
|
||||
|
||||
1. Who owns the semantic meaning of this operation?
|
||||
2. Does the operation require host-provided authority, devices, or policy?
|
||||
3. Must the loader resolve the operation against an external registry?
|
||||
4. Can the operation be denied by capabilities?
|
||||
5. Should the operation continue to exist with complete meaning in a host-minimal VM?
|
||||
6. Is the operation part of builtin language semantics rather than platform service integration?
|
||||
|
||||
Classification rule:
|
||||
|
||||
- If answers 2, 3, or 4 are yes, the operation is host-backed.
|
||||
- If answer 6 is yes and 2, 3, and 4 are no, the operation is VM-owned.
|
||||
- Otherwise the operation is program-owned unless another spec defines a distinct category.
|
||||
|
||||
## 16. Conformance Expectations
|
||||
|
||||
Conforming implementations must preserve the ownership boundary.
|
||||
|
||||
Rules:
|
||||
|
||||
- an implementation must not lower VM-owned builtin semantics through the host syscall pipeline,
|
||||
- an implementation must not treat host-backed operations as if they were VM-defined intrinsic semantics,
|
||||
- an implementation must preserve the loader-facing host-binding contract for host-backed surfaces,
|
||||
- and an implementation must preserve VM-facing semantic ownership for builtin and intrinsic operations.
|
||||
|
||||
## 17. Current Decision Summary
|
||||
|
||||
The current model is:
|
||||
|
||||
1. Program-authored functions are program-owned and execute through ordinary call machinery.
|
||||
2. Builtin semantics and intrinsic behavior are VM-owned.
|
||||
3. External platform services are host-backed.
|
||||
4. VM-owned behavior must not be modeled as `declare host`.
|
||||
5. Host-backed behavior must continue to use canonical host identity, `SYSC`, loader resolution, and final `SYSCALL`.
|
||||
6. Ownership is determined by semantic authority and runtime boundary, not by source-level syntax resemblance.
|
||||
@@ -0,0 +1,560 @@
|
||||
# Intrinsics and Builtin Types Specification
|
||||
|
||||
Status: Draft v1 (Temporary)
|
||||
Applies to: builtin type declarations, builtin constants, intrinsic member surfaces, builtin layout metadata, lowering direction, and artifact-facing intrinsic contracts
|
||||
|
||||
## 1. Purpose
|
||||
|
||||
This document defines the PBS-facing contract for:
|
||||
|
||||
- VM-owned builtin types,
|
||||
- VM-owned intrinsic operations,
|
||||
- and source-level shells that expose those features to PBS programs.
|
||||
|
||||
Its purpose is to let the frontend expose builtin semantic types such as
|
||||
`Vec2`, `Color`, and `Pixel` as first-class language types while preserving
|
||||
three invariants:
|
||||
|
||||
- semantic ownership remains with the VM,
|
||||
- builtin values have canonical stack layout,
|
||||
- and builtin domain behavior does not drift into host bindings or frontend helper code.
|
||||
|
||||
## 2. Scope
|
||||
|
||||
This document defines:
|
||||
|
||||
- the source-level shell model for `declare builtin type`,
|
||||
- the canonical metadata carried by builtin type declarations,
|
||||
- builtin constants declared through reserved metadata,
|
||||
- builtin field layout and projection rules,
|
||||
- admissible field types for builtin layouts,
|
||||
- intrinsic member metadata and owner inheritance,
|
||||
- lowering categories for builtin declarations and members,
|
||||
- the runtime-facing artifact direction for intrinsic operations,
|
||||
- and canonical intrinsic registry ownership at ISA/profile boundary.
|
||||
|
||||
This document does not define:
|
||||
|
||||
- the full final parser grammar integration into `3. Core Syntax Specification.md`,
|
||||
- the final PBX section numbering for intrinsic declarations,
|
||||
- the full VM intrinsic registry binary format,
|
||||
- user-extensible builtin types,
|
||||
- or heap-backed builtin layouts.
|
||||
|
||||
## 3. Authority and Precedence
|
||||
|
||||
Normative precedence:
|
||||
|
||||
1. Runtime authority (`docs/specs/hardware/topics/chapter-2.md`, `chapter-3.md`, `chapter-9.md`, `chapter-12.md`, `chapter-16.md`)
|
||||
2. Bytecode authority (`docs/specs/bytecode/ISA_CORE.md`)
|
||||
3. `1. Language Charter.md`
|
||||
4. `3. Core Syntax Specification.md`
|
||||
5. `4. Static Semantics Specification.md`
|
||||
6. `5. Manifest, Stdlib, and SDK Resolution Specification.md`
|
||||
7. `6.2. Host ABI Binding and Loader Resolution Specification.md`
|
||||
8. `6. VM-owned vs Host-backed.md`
|
||||
9. This document
|
||||
|
||||
If a rule here conflicts with higher-precedence authority, the higher-precedence
|
||||
authority wins.
|
||||
|
||||
## 4. Normative Inputs
|
||||
|
||||
This document depends on, at minimum:
|
||||
|
||||
- `1. Language Charter.md`
|
||||
- `3. Core Syntax Specification.md`
|
||||
- `4. Static Semantics Specification.md`
|
||||
- `5. Manifest, Stdlib, and SDK Resolution Specification.md`
|
||||
- `6.2. Host ABI Binding and Loader Resolution Specification.md`
|
||||
- `6. VM-owned vs Host-backed.md`
|
||||
- `13. Lowering IRBackend Specification.md`
|
||||
- `15. Bytecode and PBX Mapping Specification.md`
|
||||
|
||||
## 5. Core Model
|
||||
|
||||
### 5.1 Builtin type
|
||||
|
||||
A builtin type is a VM-owned semantic type whose language-visible identity is
|
||||
not authored by ordinary user code.
|
||||
|
||||
Properties:
|
||||
|
||||
- the type is first-class in the PBS type system,
|
||||
- the type has canonical layout metadata,
|
||||
- the type may expose field-like projection surfaces,
|
||||
- the type may expose intrinsic member-call surfaces,
|
||||
- and the type's semantic meaning is owned by the VM rather than by `stdlib`, SDK packaging, or the host.
|
||||
|
||||
### 5.2 Builtin declaration shell
|
||||
|
||||
`declare builtin type` is a reserved shell declaration.
|
||||
|
||||
Properties:
|
||||
|
||||
- it exists for binding, checking, lowering, and artifact emission,
|
||||
- it has no user-authored executable body,
|
||||
- and it does not transfer semantic ownership away from the VM registry.
|
||||
|
||||
### 5.3 Builtin constant
|
||||
|
||||
A builtin constant is a VM-owned named value exposed to source through a
|
||||
reserved top-level `declare const` shell carrying builtin metadata.
|
||||
|
||||
### 5.4 Intrinsic operation
|
||||
|
||||
An intrinsic operation is a VM-owned callable behavior with canonical
|
||||
definition in the VM contract.
|
||||
|
||||
### 5.5 Canonical intrinsic registry artifact
|
||||
|
||||
Final intrinsic ids are owned by one canonical ISA-scoped registry artifact.
|
||||
|
||||
Rules:
|
||||
|
||||
- compiler and runtime consumers must derive final intrinsic ids from that same artifact,
|
||||
- dual-authoring of compiler-local and runtime-local intrinsic-id maps is forbidden,
|
||||
- strict CI mode must fail on parity mismatch between consumer snapshots and canonical artifact.
|
||||
|
||||
## 6. Reserved Surface Forms
|
||||
|
||||
This document temporarily defines the intended source-level shell shape.
|
||||
Final parser integration belongs to `3. Core Syntax Specification.md`.
|
||||
|
||||
### 6.1 Builtin type shell
|
||||
|
||||
Illustrative form:
|
||||
|
||||
```pbs
|
||||
[BuiltinType(name="vec2", version=1)]
|
||||
declare builtin type Vec2(
|
||||
pub x: float,
|
||||
pub y: float,
|
||||
) {
|
||||
[IntrinsicCall(name="dot")]
|
||||
fn dot(other: Vec2) -> float;
|
||||
|
||||
[IntrinsicCall(name="length")]
|
||||
fn length() -> float;
|
||||
}
|
||||
```
|
||||
|
||||
### 6.2 Builtin constant shell
|
||||
|
||||
Illustrative form:
|
||||
|
||||
```pbs
|
||||
[BuiltinConst(target="vec2", name="zero", version=1)]
|
||||
declare const ZERO: Vec2;
|
||||
```
|
||||
|
||||
## 7. `BuiltinType` Metadata
|
||||
|
||||
`BuiltinType` declares the canonical VM-facing identity of a builtin type.
|
||||
|
||||
Required fields:
|
||||
|
||||
- `name`
|
||||
- `version`
|
||||
|
||||
Rules:
|
||||
|
||||
- the declaration name after `declare builtin type` is the PBS-visible type name,
|
||||
- `BuiltinType.name` is the canonical VM identity name,
|
||||
- `BuiltinType.version` is the canonical semantic version of that builtin contract,
|
||||
- the VM identity name need not equal the PBS-visible type name,
|
||||
- and the pair `(name, version)` is the canonical builtin type identity in v1.
|
||||
|
||||
Example:
|
||||
|
||||
- source-visible name: `Vec2`
|
||||
- canonical builtin identity: `("vec2", 1)`
|
||||
|
||||
## 8. Declaration Form and Structural Rules
|
||||
|
||||
`declare builtin type` uses a field-list surface similar to nominal aggregate
|
||||
declarations.
|
||||
|
||||
Rules:
|
||||
|
||||
- `declare builtin type` is reserved to SDK/toolchain-controlled modules,
|
||||
- ordinary user-authored modules must reject it,
|
||||
- the declaration introduces a type name in the type namespace,
|
||||
- the parenthesized member list declares builtin field projections,
|
||||
- the body may contain signatures only,
|
||||
- the body must not contain executable PBS statements,
|
||||
- builtin members must not declare PBS bodies,
|
||||
- and builtin declarations must not be used to encode ordinary user-defined structs.
|
||||
|
||||
This surface is intentionally shell-like.
|
||||
The declaration is not the implementation authority for builtin behavior.
|
||||
|
||||
## 9. Builtin Fields Are Projections, Not Ordinary Storage Fields
|
||||
|
||||
The field-like entries in a builtin declaration describe named projections over a
|
||||
canonical VM layout.
|
||||
|
||||
Rules:
|
||||
|
||||
- they are not ordinary user-defined struct fields,
|
||||
- their names are visible for projection syntax such as `value.x`,
|
||||
- they describe a canonical flattened layout order,
|
||||
- and their meaning is projection over VM-owned builtin value representation.
|
||||
|
||||
Consequences:
|
||||
|
||||
- a builtin field declaration does not imply ordinary mutability semantics,
|
||||
- a builtin field declaration does not imply that builtin values are structs,
|
||||
- and a builtin field declaration does not allow user code to provide storage-level implementation bodies.
|
||||
|
||||
## 10. Builtin Slot Inference
|
||||
|
||||
Builtin field slot offsets are inferred by the compiler, not authored in source.
|
||||
|
||||
Rules:
|
||||
|
||||
- slot offsets are zero-based and deterministic,
|
||||
- offsets are computed from declaration order plus flattened widths of field types,
|
||||
- nested builtin fields contribute their full flattened width to subsequent offsets,
|
||||
- and source-level `Slot(...)` metadata is forbidden in v1.
|
||||
|
||||
## 11. Builtin Layout Admissibility
|
||||
|
||||
Builtin field types are restricted.
|
||||
|
||||
A type is builtin-layout-admissible when it has:
|
||||
|
||||
- fixed width in slots,
|
||||
- finite flattened layout,
|
||||
- stack-only representation in this feature set,
|
||||
- and canonical VM-owned layout metadata.
|
||||
|
||||
In v1 temporary scope, builtin-layout-admissible types are:
|
||||
|
||||
- predeclared builtin scalar types whose runtime contract defines fixed slot width,
|
||||
- and declared builtin types whose own layout is fixed, finite, and stack-only.
|
||||
|
||||
The following are not builtin-layout-admissible unless a future spec explicitly
|
||||
changes the rule:
|
||||
|
||||
- user-declared structs,
|
||||
- services,
|
||||
- contracts,
|
||||
- callbacks,
|
||||
- `optional`,
|
||||
- `result`,
|
||||
- and any type with runtime-variable or heap-defined width.
|
||||
|
||||
## 12. Nested Builtin Layout and Flattening
|
||||
|
||||
Builtin fields may refer to other builtin-layout-admissible types.
|
||||
|
||||
Rules:
|
||||
|
||||
- nested builtin field types flatten recursively into the enclosing layout,
|
||||
- the enclosing builtin layout is the concatenation of its fields' flattened layouts in slot order,
|
||||
- a nested field retains its nominal field identity for projection purposes,
|
||||
- and verifier-facing slot widths are computed from the fully flattened layout.
|
||||
|
||||
Example:
|
||||
|
||||
```pbs
|
||||
[BuiltinType(name="color", version=1)]
|
||||
declare builtin type Color(
|
||||
pub raw: int,
|
||||
);
|
||||
|
||||
[BuiltinType(name="pixel", version=1)]
|
||||
declare builtin type Pixel(
|
||||
pub x: int,
|
||||
pub y: int,
|
||||
pub color: Color,
|
||||
);
|
||||
```
|
||||
|
||||
Canonical semantic layout:
|
||||
|
||||
```text
|
||||
Pixel -> [int, int, Color]
|
||||
```
|
||||
|
||||
Canonical flattened slot layout:
|
||||
|
||||
```text
|
||||
Pixel -> [int, int, int]
|
||||
```
|
||||
|
||||
## 13. Member Categories
|
||||
|
||||
Builtin members belong to one of the following semantic categories:
|
||||
|
||||
1. projection surface,
|
||||
2. builtin constant surface,
|
||||
3. layout-only constructor or factory surface,
|
||||
4. intrinsic call surface.
|
||||
|
||||
This document normatively defines projection, builtin constants, and intrinsic
|
||||
call surfaces.
|
||||
Layout-only constructors may be introduced by future syntax or by existing
|
||||
constructor lowering rules, but their implementation remains VM-facing rather
|
||||
than host-backed.
|
||||
|
||||
## 14. `IntrinsicCall` Metadata
|
||||
|
||||
`IntrinsicCall` identifies a VM-owned callable member over builtin semantics.
|
||||
|
||||
Required fields:
|
||||
|
||||
- `name`
|
||||
|
||||
Optional fields:
|
||||
|
||||
- `version`
|
||||
|
||||
Rules:
|
||||
|
||||
- `IntrinsicCall` is valid only on method signatures declared inside a `declare builtin type` body,
|
||||
- the enclosing `BuiltinType` provides the default intrinsic owner identity,
|
||||
- `IntrinsicCall.name` is the canonical intrinsic operation name within that owner,
|
||||
- if `IntrinsicCall.version` is omitted, it inherits the enclosing builtin type version,
|
||||
- if `IntrinsicCall.version` is present, it overrides only the operation version,
|
||||
- and `IntrinsicCall` must not be interpreted as host-binding metadata.
|
||||
|
||||
Canonical intrinsic identity in v1 is:
|
||||
|
||||
```text
|
||||
(owner, name, version)
|
||||
```
|
||||
|
||||
where:
|
||||
|
||||
- `owner` is inherited from `BuiltinType.name`,
|
||||
- `name` is taken from `IntrinsicCall.name`,
|
||||
- and `version` is inherited or overridden as above.
|
||||
|
||||
Example:
|
||||
|
||||
```pbs
|
||||
[BuiltinType(name="vec2", version=1)]
|
||||
declare builtin type Vec2(
|
||||
pub x: float,
|
||||
pub y: float,
|
||||
) {
|
||||
[IntrinsicCall(name="dot")]
|
||||
fn dot(other: Vec2) -> float;
|
||||
}
|
||||
```
|
||||
|
||||
declares canonical intrinsic identity:
|
||||
|
||||
```text
|
||||
("vec2", "dot", 1)
|
||||
```
|
||||
|
||||
## 15. `BuiltinConst` Metadata
|
||||
|
||||
`BuiltinConst` identifies a VM-owned named constant surface.
|
||||
|
||||
Required fields:
|
||||
|
||||
- `target`
|
||||
- `name`
|
||||
- `version`
|
||||
|
||||
Rules:
|
||||
|
||||
- `BuiltinConst` is valid only on reserved top-level `declare const` shells,
|
||||
- `target` identifies the canonical builtin owner name,
|
||||
- `name` identifies the canonical constant name within that builtin owner,
|
||||
- `version` identifies the constant contract version,
|
||||
- the declared PBS constant name is source-visible and may differ from the canonical constant name,
|
||||
- and builtin constants are VM-owned declarations, not host bindings.
|
||||
|
||||
Example:
|
||||
|
||||
```pbs
|
||||
[BuiltinConst(target="vec2", name="zero", version=1)]
|
||||
declare const ZERO: Vec2;
|
||||
```
|
||||
|
||||
declares a source-visible constant `ZERO` whose canonical builtin constant
|
||||
identity is:
|
||||
|
||||
```text
|
||||
("vec2", "zero", 1)
|
||||
```
|
||||
|
||||
## 16. Static Semantics
|
||||
|
||||
The following static rules apply.
|
||||
|
||||
### 16.1 Namespace rules
|
||||
|
||||
Rules:
|
||||
|
||||
- `declare builtin type` introduces a nominal type name in the type namespace,
|
||||
- builtin type names participate in visibility and import rules like other reserved type declarations,
|
||||
- ordinary user-authored type declarations must not redeclare visible builtin type names in the same scope,
|
||||
- and builtin constants declared through `declare const` introduce names in the value namespace.
|
||||
|
||||
### 16.2 Member lookup rules
|
||||
|
||||
Rules:
|
||||
|
||||
- `expr.field` is valid when `expr` has a builtin type declaring a projection field named `field`,
|
||||
- the projected type is the field's declared type,
|
||||
- `expr.method()` is valid when the builtin type declares a matching intrinsic member surface,
|
||||
- and missing builtin fields or members are compile-time errors.
|
||||
|
||||
### 16.3 Body restrictions
|
||||
|
||||
Rules:
|
||||
|
||||
- builtin declarations have no executable member bodies,
|
||||
- builtin methods are signature-only shells,
|
||||
- builtin constants are declaration-only shells,
|
||||
- and ordinary user code must not implement builtin semantics in PBS bodies.
|
||||
|
||||
## 17. Lowering Model
|
||||
|
||||
Builtin shells guide lowering; they do not supply executable implementation.
|
||||
|
||||
### 17.1 Projection lowering
|
||||
|
||||
Projection over builtin fields lowers to canonical projection over flattened
|
||||
layout.
|
||||
|
||||
Rules:
|
||||
|
||||
- field projection does not imply host interaction,
|
||||
- field projection does not emit `SYSC`,
|
||||
- field projection may lower to direct stack projection, reshaping operations, or another VM-owned form,
|
||||
- and the projected semantics are determined by builtin layout metadata.
|
||||
|
||||
### 17.2 Builtin constant lowering
|
||||
|
||||
Builtin constants lower to VM-owned constant materialization.
|
||||
|
||||
Rules:
|
||||
|
||||
- builtin constants must not lower through host binding resolution,
|
||||
- builtin constants may lower to direct value materialization, VM-owned constant pool lookup, or intrinsic-like constant fetch,
|
||||
- and the canonical constant identity determines which VM-owned value is materialized.
|
||||
|
||||
### 17.3 Intrinsic method lowering
|
||||
|
||||
Intrinsic methods lower to VM-owned intrinsic call behavior.
|
||||
|
||||
Rules:
|
||||
|
||||
- intrinsic methods must not lower through `SYSC`,
|
||||
- intrinsic methods must not emit `HOSTCALL`,
|
||||
- intrinsic method identities lower from `(owner, name, version)` metadata,
|
||||
- and the runtime-facing call form is VM-facing rather than host-facing.
|
||||
|
||||
## 18. Artifact Direction
|
||||
|
||||
This feature requires a distinct intrinsic artifact path.
|
||||
|
||||
Illustrative final executable form:
|
||||
|
||||
```text
|
||||
INTRINSIC <id>
|
||||
```
|
||||
|
||||
Illustrative optional pre-resolution form:
|
||||
|
||||
```text
|
||||
INTRCALL <decl_index>
|
||||
```
|
||||
|
||||
with declaration metadata carrying:
|
||||
|
||||
```text
|
||||
(owner, name, version)
|
||||
```
|
||||
|
||||
Rules:
|
||||
|
||||
- implementations may emit final `INTRINSIC <id>` directly when intrinsic ids are stable for the targeted VM contract,
|
||||
- implementations may emit declaration-based intrinsic callsites when a preload resolution step is desired,
|
||||
- any such intrinsic declaration path remains VM-facing and must not reuse host-binding metadata,
|
||||
- and intrinsic artifacts are distinct from `SYSC`, `HOSTCALL`, and `SYSCALL`.
|
||||
|
||||
## 19. Verifier Obligations
|
||||
|
||||
The verifier must treat intrinsics and builtin layouts as first-class structural
|
||||
facts.
|
||||
|
||||
Rules:
|
||||
|
||||
- each builtin type has a known flattened slot width,
|
||||
- each intrinsic has known argument and result layouts,
|
||||
- verifier stack effects are computed from flattened layouts rather than only from source spellings,
|
||||
- and verifier reasoning must preserve nominal builtin type identity even when two builtin layouts occupy the same slot width.
|
||||
|
||||
Example:
|
||||
|
||||
```text
|
||||
Vec2.dot(Vec2, Vec2) -> float
|
||||
```
|
||||
|
||||
If `Vec2` flattens to two float-width slots, the verifier-facing stack effect is:
|
||||
|
||||
```text
|
||||
pop 4, push 1
|
||||
```
|
||||
|
||||
## 20. Determinism and Ownership Rules
|
||||
|
||||
Builtin and intrinsic semantics are VM-owned.
|
||||
|
||||
Rules:
|
||||
|
||||
- builtin operations must not rely on host registry resolution,
|
||||
- builtin operations must not require runtime capability grants,
|
||||
- builtin operations must not be specified merely as frontend helper code,
|
||||
- and builtin operations must remain within the VM-owned category defined by `6. VM-owned vs Host-backed.md`.
|
||||
|
||||
## 21. Relationship to `stdlib` and SDK Packaging
|
||||
|
||||
`stdlib` and SDK packaging may expose builtin declarations as compile-time
|
||||
surfaces.
|
||||
|
||||
Rules:
|
||||
|
||||
- packaging location does not make builtin semantics host-backed,
|
||||
- source modules may import builtin shells from reserved stdlib surfaces,
|
||||
- the shell remains descriptive rather than semantically authoritative,
|
||||
- and the VM contract remains the owner of builtin identities, layouts, constants, and intrinsic behavior.
|
||||
|
||||
## 22. Deterministic Static Errors
|
||||
|
||||
At minimum, a conforming implementation must reject:
|
||||
|
||||
1. `declare builtin type` in an ordinary user-authored module,
|
||||
2. missing required `BuiltinType` metadata on a builtin declaration,
|
||||
3. duplicate builtin field names within one declaration,
|
||||
4. source-level `Slot(...)` usage in builtin declarations,
|
||||
5. builtin field types that are not builtin-layout-admissible,
|
||||
6. `IntrinsicCall` used outside a builtin declaration body,
|
||||
7. `BuiltinConst` used outside a reserved top-level `declare const` shell,
|
||||
8. duplicate canonical builtin type identities in the same compilation environment,
|
||||
9. duplicate intrinsic canonical identities within the same builtin owner and version line,
|
||||
10. cyclic or unresolved flattened builtin layout composition,
|
||||
11. executable member bodies inside builtin declarations,
|
||||
12. any lowering that routes VM-owned builtin operations through the host-binding pipeline.
|
||||
|
||||
## 23. Current Decision Summary
|
||||
|
||||
The current temporary contract is:
|
||||
|
||||
1. Builtin types are VM-owned semantic types exposed through reserved shell declarations.
|
||||
2. `BuiltinType(name, version)` maps source-visible type names to canonical VM builtin identities.
|
||||
3. Builtin fields describe projection surfaces over canonical flattened layout.
|
||||
4. Builtin field types must be builtin-layout-admissible and stack-only in this feature set.
|
||||
5. Builtin types may contain other builtin-layout-admissible types, including nested builtin composition such as `Pixel` containing `Color`.
|
||||
6. `IntrinsicCall(name, version?)` identifies VM-owned intrinsic member behavior and inherits owner identity from the enclosing builtin type.
|
||||
7. `BuiltinConst(target, name, version)` exposes VM-owned builtin constants through reserved top-level `declare const` shells.
|
||||
8. Builtin projections, constants, and intrinsic calls must not lower through `SYSC`, `HOSTCALL`, or `SYSCALL`.
|
||||
9. Runtime-facing intrinsic artifacts are distinct from host-binding artifacts.
|
||||
+428
@@ -0,0 +1,428 @@
|
||||
# Host ABI Binding and Loader Resolution Specification
|
||||
|
||||
Status: Draft v1 (Temporary)
|
||||
Applies to: PBX host-binding metadata, cartridge load, canonical syscall resolution, and loader-side capability gating
|
||||
|
||||
## 1. Purpose
|
||||
|
||||
This document defines the current contract between:
|
||||
|
||||
- the PBS compiler/toolchain,
|
||||
- the PBX program artifact,
|
||||
- the cartridge loader,
|
||||
- and the host syscall registry.
|
||||
|
||||
Its purpose is to let compiler and runtime work in parallel without diverging on the most critical boundary:
|
||||
how host-backed SDK calls become load-time-resolved numeric syscalls.
|
||||
|
||||
This document is intentionally narrower than a full PBX or VM specification.
|
||||
It focuses on loader behavior and the minimum artifact contract the loader must consume.
|
||||
|
||||
## 2. Scope
|
||||
|
||||
This document defines:
|
||||
|
||||
- the canonical identity of a host binding,
|
||||
- the relationship between `declare host` and canonical host bindings,
|
||||
- the minimum PBX metadata required for load-time host resolution,
|
||||
- the pre-load opcode form used for host-backed call sites,
|
||||
- the required loader algorithm,
|
||||
- the required loader patching step from pre-load host callsites to numeric syscalls,
|
||||
- the division of responsibility between loader-side ABI checks and verifier-side stack checks,
|
||||
- capability checks required during load,
|
||||
- deterministic loader failures for malformed or unauthorized host usage,
|
||||
- the requirement that VM execution remains numeric-only.
|
||||
|
||||
This document does not define:
|
||||
|
||||
- the full PBX module format,
|
||||
- the exact in-memory patching strategy used by the loader,
|
||||
- the publication format of stdlib SDK packs,
|
||||
- the semantics of individual subsystems such as GFX or AUDIO.
|
||||
|
||||
## 3. Normative Inputs
|
||||
|
||||
This document follows two prior decisions:
|
||||
|
||||
1. Canonical host identity is defined by the hardware ABI as `(module, name, version)`.
|
||||
2. User code does not declare host bindings directly; SDK/toolchain-controlled modules expose reserved `declare host` surfaces and the compiler lowers those usages into PBX host-binding metadata.
|
||||
|
||||
This document therefore treats:
|
||||
|
||||
- `declare host Gfx { fn draw_pixel(...); }`
|
||||
|
||||
as compile-time surface only, and treats:
|
||||
|
||||
- `("gfx", "draw_pixel", 1)`
|
||||
|
||||
as the normative runtime-facing identity.
|
||||
|
||||
## 4. Core Model
|
||||
|
||||
The host-binding pipeline is:
|
||||
|
||||
1. User code imports SDK surfaces such as `Gfx` from `@sdk:gfx`.
|
||||
2. The compiler resolves those surfaces against the selected stdlib line.
|
||||
3. The compiler maps each host-backed SDK member to a canonical identity `(module, name, version)`.
|
||||
4. The compiler emits those required canonical identities into the PBX `SYSC` table.
|
||||
5. The compiler emits pre-load host call sites as `HOSTCALL <sysc_index>`.
|
||||
6. At cartridge load time, the loader resolves `SYSC` entries against the host syscall registry.
|
||||
7. The loader verifies ABI compatibility and capabilities before execution starts.
|
||||
8. The loader rewrites every `HOSTCALL <sysc_index>` into `SYSCALL <id>`.
|
||||
9. The VM executes only numeric syscall identifiers.
|
||||
|
||||
The loader never resolves host bindings from source-level names such as `Gfx.draw_pixel`.
|
||||
It resolves only canonical identities declared in the PBX.
|
||||
|
||||
## 5. Canonical Host Binding Identity
|
||||
|
||||
Every host binding is identified by the triple:
|
||||
|
||||
```text
|
||||
(module, name, version)
|
||||
```
|
||||
|
||||
Rules:
|
||||
|
||||
- `module` is the canonical host subsystem namespace, such as `gfx` or `audio`.
|
||||
- `name` is the canonical host operation name within that module.
|
||||
- `version` is the canonical ABI version of that host operation.
|
||||
- This identity is stable across source languages and SDK naming styles.
|
||||
- This identity is the only identity used by the loader for host resolution.
|
||||
|
||||
Source-level owners such as `Gfx` are SDK-facing aliases.
|
||||
They are not loader-facing identities.
|
||||
|
||||
## 6. Relationship to `declare host`
|
||||
|
||||
`declare host` is a reserved SDK/toolchain surface used to expose host-backed APIs to source programs.
|
||||
|
||||
Rules:
|
||||
|
||||
- User-authored project modules do not declare canonical host bindings directly.
|
||||
- `declare host` exists to define compile-time interface shape, not executable PBS bodies.
|
||||
- The compiler is responsible for mapping each host-backed member to its canonical host identity.
|
||||
- The PBX must not depend on source spellings such as `Gfx` for runtime resolution.
|
||||
|
||||
Example:
|
||||
|
||||
```pbs
|
||||
import { Gfx, color } from @sdk:gfx;
|
||||
|
||||
let c: color = color.red;
|
||||
Gfx.draw_pixel(1, 1, c);
|
||||
```
|
||||
|
||||
The source-level call may originate from an SDK declaration such as:
|
||||
|
||||
```pbs
|
||||
declare host Gfx {
|
||||
[Host(module = "gfx", name = "draw_pixel", version = 1)]
|
||||
[Capability(name = "gfx")]
|
||||
fn draw_pixel(x: int, y: int, c: color);
|
||||
}
|
||||
```
|
||||
|
||||
but the PBX-facing declaration is canonical, for example:
|
||||
|
||||
```text
|
||||
("gfx", "draw_pixel", 1)
|
||||
```
|
||||
|
||||
## 7. PBX Host Binding Section
|
||||
|
||||
### 7.1 Temporary section contract
|
||||
|
||||
Until the full PBX host-binding format is stabilized elsewhere, the loader contract uses a dedicated PBX section for declared host bindings.
|
||||
|
||||
Temporary section identifier:
|
||||
|
||||
- `SYSC`
|
||||
|
||||
Meaning:
|
||||
|
||||
- the list of canonical host bindings required by the program.
|
||||
|
||||
This section is metadata only.
|
||||
It does not define the executable opcode stream itself.
|
||||
|
||||
### 7.2 Temporary binary layout
|
||||
|
||||
The current temporary layout is:
|
||||
|
||||
```text
|
||||
u32 count
|
||||
repeat count times:
|
||||
u16 module_len
|
||||
[module_len bytes UTF-8]
|
||||
u16 name_len
|
||||
[name_len bytes UTF-8]
|
||||
u16 version
|
||||
u16 arg_slots
|
||||
u16 ret_slots
|
||||
```
|
||||
|
||||
Rules:
|
||||
|
||||
- strings are UTF-8,
|
||||
- `module_len` and `name_len` are byte lengths,
|
||||
- `arg_slots` is the slot count the compiler expects the host binding to consume,
|
||||
- `ret_slots` is the slot count the compiler expects the host binding to produce,
|
||||
- duplicate `(module, name, version)` entries are invalid,
|
||||
- malformed lengths or invalid UTF-8 are load errors.
|
||||
|
||||
The `SYSC` table is:
|
||||
|
||||
- unique per program,
|
||||
- deduplicated by canonical identity,
|
||||
- ordered by first occurrence in the compiled program.
|
||||
|
||||
The loader MUST preserve the table order as emitted.
|
||||
|
||||
### 7.3 Presence requirements
|
||||
|
||||
The `SYSC` section is mandatory for every valid PBX artifact.
|
||||
|
||||
Rules:
|
||||
|
||||
- every valid `program.pbx` MUST contain a `SYSC` section,
|
||||
- the loader MUST inspect `SYSC` before execution begins,
|
||||
- an empty `SYSC` section is valid and means the program requires no host bindings,
|
||||
- absence of `SYSC` is a deterministic load error,
|
||||
- malformed or duplicate `SYSC` declarations are deterministic load errors.
|
||||
|
||||
Rationale:
|
||||
|
||||
- the Prometeu runtime is always host-aware,
|
||||
- PBX structural uniformity is preferred over optional host-binding metadata,
|
||||
- loader simplicity and deterministic testability take priority over omitting an empty section.
|
||||
|
||||
## 8. Loader Resolution Algorithm
|
||||
|
||||
The loader must perform host-binding resolution before VM execution starts.
|
||||
|
||||
Required algorithm:
|
||||
|
||||
1. Read the PBX header and section table.
|
||||
2. Locate and parse the `SYSC` section before launching the VM.
|
||||
3. Decode the declared canonical identities in source order.
|
||||
4. Reject duplicate identities.
|
||||
5. Resolve each identity against the host syscall registry.
|
||||
6. For each resolved entry, verify that declared `arg_slots` and `ret_slots` match the authoritative host metadata.
|
||||
7. Verify that the granted capability set covers every resolved binding.
|
||||
8. Scan the executable bytecode for every `HOSTCALL <sysc_index>` instruction.
|
||||
9. Reject any `HOSTCALL` whose `sysc_index` is out of bounds.
|
||||
10. Reject any `SYSC` entry that is never referenced by a `HOSTCALL`.
|
||||
11. Rewrite every `HOSTCALL <sysc_index>` into `SYSCALL <syscall_id>`.
|
||||
12. Reject the loaded image if any `HOSTCALL` remains after the rewrite pass.
|
||||
13. Produce the final executable program image.
|
||||
14. Abort load deterministically if any step fails.
|
||||
|
||||
The loader must not defer canonical-name resolution until the first call site executes.
|
||||
|
||||
## 9. Host Registry Resolution
|
||||
|
||||
The host maintains a canonical syscall registry:
|
||||
|
||||
```text
|
||||
(module, name, version) -> syscall_id + metadata
|
||||
```
|
||||
|
||||
That metadata includes, at minimum:
|
||||
|
||||
- numeric syscall identifier,
|
||||
- canonical identity,
|
||||
- argument slot count,
|
||||
- return slot count,
|
||||
- required capabilities.
|
||||
|
||||
Rules:
|
||||
|
||||
- the loader resolves only against this canonical registry,
|
||||
- unknown identities are load errors,
|
||||
- successful resolution yields numeric syscall identifiers and associated metadata,
|
||||
- the resolved metadata is authoritative for capability gating and later runtime verification.
|
||||
|
||||
## 10. Pre-Load Callsite Form
|
||||
|
||||
The compiler emits host-backed call sites in pre-load form as:
|
||||
|
||||
```text
|
||||
HOSTCALL <sysc_index>
|
||||
```
|
||||
|
||||
Rules:
|
||||
|
||||
- `sysc_index` is a zero-based index into the program's `SYSC` table,
|
||||
- every host-backed call site in PBX code must use `HOSTCALL`, not `SYSCALL`,
|
||||
- `HOSTCALL` exists only in the pre-load artifact form,
|
||||
- `HOSTCALL` must not remain in the final executable image passed to the VM.
|
||||
|
||||
Rationale:
|
||||
|
||||
- the compiler does not know final numeric syscall identifiers,
|
||||
- the loader resolves by canonical identity and materializes the numeric form,
|
||||
- the verifier and VM can stay numeric-only after the patch step.
|
||||
|
||||
## 11. Loader-Side ABI Validation
|
||||
|
||||
Load-time ABI validation is mandatory.
|
||||
|
||||
Rules:
|
||||
|
||||
- every `SYSC` entry declares `arg_slots` and `ret_slots`,
|
||||
- the loader resolves the entry to authoritative host metadata,
|
||||
- the loader MUST reject the image if declared `arg_slots` differs from host metadata,
|
||||
- the loader MUST reject the image if declared `ret_slots` differs from host metadata.
|
||||
|
||||
This validation is not a replacement for bytecode verification.
|
||||
It exists to detect mismatches between:
|
||||
|
||||
- the compiler's emitted host-binding contract,
|
||||
- and the host registry contract actually present in the runtime.
|
||||
|
||||
## 12. Capability Gating
|
||||
|
||||
Capability gating is mandatory during load.
|
||||
|
||||
Rules:
|
||||
|
||||
- every resolved host binding declares required capabilities,
|
||||
- frontend/build host-admission computes deterministic `requiredCapabilities` from host binding metadata for packer assistance,
|
||||
- the cartridge manifest declares requested capabilities using a nominal capability list,
|
||||
- the loader derives or receives the granted capability set from the cartridge/platform policy environment,
|
||||
- if a required capability is not granted, load fails,
|
||||
- the loader must fail before the program begins execution.
|
||||
|
||||
The compiler may infer which capabilities are required by the emitted `SYSC` table, but it does not grant authority.
|
||||
Authority belongs to the cartridge/platform loading environment.
|
||||
|
||||
Runtime capability checks may still exist defensively in the VM, but they do not replace mandatory load-time validation.
|
||||
|
||||
## 13. Verifier Interaction
|
||||
|
||||
The loader and the verifier validate different layers of the contract.
|
||||
|
||||
Loader responsibilities:
|
||||
|
||||
- validate canonical host identity resolution,
|
||||
- validate `SYSC`-declared ABI shape against host metadata,
|
||||
- validate capabilities,
|
||||
- patch `HOSTCALL <sysc_index>` into `SYSCALL <id>`.
|
||||
|
||||
Verifier responsibilities:
|
||||
|
||||
- run on the already-patched executable image,
|
||||
- validate stack safety and control-flow safety,
|
||||
- treat `SYSCALL <id>` exactly like any other final numeric instruction,
|
||||
- derive stack effects from authoritative runtime syscall metadata.
|
||||
|
||||
This is intentional and not considered harmful duplication:
|
||||
|
||||
- the loader checks interface compatibility,
|
||||
- the verifier checks structural correctness of the final program.
|
||||
|
||||
## 14. Execution Model After Load
|
||||
|
||||
After successful load:
|
||||
|
||||
- the VM executes numeric syscall identifiers only,
|
||||
- runtime dispatch must not depend on canonical strings,
|
||||
- canonical names exist only in PBX metadata and loader-side resolution,
|
||||
- the runtime-facing execution form remains `SYSCALL <id>`.
|
||||
|
||||
This preserves the hardware contract:
|
||||
|
||||
- canonical identity is used for declaration and linking,
|
||||
- numeric identity is used for execution.
|
||||
|
||||
## 15. Deterministic Loader Errors
|
||||
|
||||
The loader must fail deterministically for at least the following cases:
|
||||
|
||||
1. missing `SYSC` section,
|
||||
2. malformed `SYSC` payload,
|
||||
3. invalid UTF-8 in canonical names,
|
||||
4. duplicate `(module, name, version)` declarations,
|
||||
5. unknown canonical identity,
|
||||
6. ABI mismatch between `SYSC` declaration and host registry metadata,
|
||||
7. capability mismatch,
|
||||
8. `HOSTCALL` references an out-of-bounds `sysc_index`,
|
||||
9. a declared `SYSC` entry is unused by all `HOSTCALL` instructions,
|
||||
10. a `HOSTCALL` remains in the executable image after loader patching,
|
||||
11. any internal inconsistency between parsed host-binding metadata and the loader's host registry contract.
|
||||
|
||||
Diagnostics should identify the failing canonical identity whenever available.
|
||||
|
||||
## 16. Relationship to `stdlib`
|
||||
|
||||
`stdlib` selection is a compile-time concern that determines which SDK surfaces and host-backed declarations the compiler may use.
|
||||
|
||||
Rules:
|
||||
|
||||
- the loader does not resolve source imports such as `@sdk:gfx`,
|
||||
- the loader only consumes canonical host-binding metadata emitted into the PBX,
|
||||
- `stdlib` affects the loader indirectly through what the compiler emitted,
|
||||
- the loader must not attempt to reconstruct SDK/module semantics from the PBX.
|
||||
|
||||
In other words:
|
||||
|
||||
- `stdlib` selects the compile-time SDK contract,
|
||||
- `SYSC` carries the runtime-facing host-binding contract.
|
||||
|
||||
## 17. Relationship to Cartridge Manifest Capabilities
|
||||
|
||||
The cartridge manifest is the current declarative source for requested runtime capabilities.
|
||||
|
||||
Rules:
|
||||
|
||||
- cartridge capability declarations are external to `program.pbx`,
|
||||
- capability declarations are serializable nominal identifiers such as `gfx` or `audio`,
|
||||
- the loader converts that nominal declaration into the internal capability flag set used by the runtime,
|
||||
- the loader MUST NOT infer granted authority solely from the presence of `SYSC` entries.
|
||||
|
||||
This keeps authority separate from code generation:
|
||||
|
||||
- PBX declares what the program needs,
|
||||
- cartridge packaging declares what the cartridge requests,
|
||||
- the loader/runtime environment decides what is granted.
|
||||
|
||||
## 18. Current Implementation Direction
|
||||
|
||||
This document aligns with the current Prometeu direction:
|
||||
|
||||
- SDK/toolchain-controlled `declare host` surfaces define host-backed APIs,
|
||||
- the compiler emits canonical host-binding declarations into PBX `SYSC`,
|
||||
- the compiler emits `HOSTCALL <sysc_index>` in pre-load code,
|
||||
- the loader resolves those declarations at cartridge load,
|
||||
- the loader patch-rewrites host calls to numeric syscalls,
|
||||
- the VM continues to execute numeric syscalls only.
|
||||
|
||||
## 19. Open Items Deferred
|
||||
|
||||
The following remain deferred:
|
||||
|
||||
1. final PBX section numbering and chunk registry policy,
|
||||
2. exact binary opcode allocation for `HOSTCALL`,
|
||||
3. whether the loader patches bytecode in place or rebuilds a fresh executable image buffer,
|
||||
4. final cartridge policy model when platform-level grants differ from manifest requests,
|
||||
5. final chunk numbering and binary compatibility policy for PBX versions that predate mandatory `SYSC`,
|
||||
6. final integration shape with `ProgramImage` or another loaded-program container.
|
||||
|
||||
## 20. Current Decision Summary
|
||||
|
||||
The current temporary contract is:
|
||||
|
||||
1. Host bindings are identified canonically by `(module, name, version)`.
|
||||
2. `declare host` is reserved to SDK/toolchain modules and is compile-time surface only.
|
||||
3. The compiler emits a unique, deduplicated `SYSC` table ordered by first occurrence.
|
||||
4. Each `SYSC` entry carries `module`, `name`, `version`, `arg_slots`, and `ret_slots`.
|
||||
5. The compiler emits host-backed call sites as `HOSTCALL <sysc_index>`.
|
||||
6. The loader parses `SYSC` before execution.
|
||||
7. The loader resolves canonical identities against the host registry during load.
|
||||
8. The loader validates `arg_slots` and `ret_slots` against authoritative host metadata.
|
||||
9. The loader enforces capability gating during load.
|
||||
10. The loader rejects out-of-bounds and unused `SYSC` references.
|
||||
11. The loader rewrites every `HOSTCALL <sysc_index>` into `SYSCALL <id>`.
|
||||
12. The verifier runs after patching and validates the final numeric program.
|
||||
13. The VM executes numeric syscall identifiers only.
|
||||
+248
@@ -0,0 +1,248 @@
|
||||
# Cartridge Manifest and Runtime Capabilities Specification
|
||||
|
||||
Status: Draft v1 (Temporary)
|
||||
Applies to: `manifest.json` in Prometeu cartridges, runtime capability declaration, and loader capability input
|
||||
|
||||
## 1. Purpose
|
||||
|
||||
This document defines the current cartridge manifest contract relevant to runtime loading.
|
||||
|
||||
Its purpose is to stabilize:
|
||||
|
||||
- the JSON surface consumed by the cartridge loader,
|
||||
- the declaration of cartridge-requested runtime capabilities,
|
||||
- the boundary between cartridge packaging and loader authority,
|
||||
- the conversion from manifest-facing capability names to runtime capability flags.
|
||||
|
||||
This document is intentionally temporary and limited.
|
||||
It does not define cartridge publishing, signing, or store policy.
|
||||
|
||||
## 2. Scope
|
||||
|
||||
This document defines:
|
||||
|
||||
- the role of `manifest.json` in cartridge loading,
|
||||
- the current required manifest fields,
|
||||
- the new `capabilities` field,
|
||||
- the nominal capability enumeration used in JSON,
|
||||
- the mapping from nominal capabilities to runtime `CapFlags`,
|
||||
- the role of the loader when combining manifest capabilities with PBX `SYSC`.
|
||||
|
||||
This document does not define:
|
||||
|
||||
- the full package format beyond the current directory cartridge contract,
|
||||
- policy UI or permission prompts,
|
||||
- cartridge signing or trust chains,
|
||||
- final platform grant policy when the host wants to reduce requested capabilities.
|
||||
|
||||
## 3. Current Cartridge Manifest Role
|
||||
|
||||
The cartridge manifest is an external load-time descriptor for a cartridge.
|
||||
|
||||
It is not compiled from PBS source directly.
|
||||
It is produced by cartridge packaging tooling and consumed by the runtime loader.
|
||||
|
||||
The manifest currently carries:
|
||||
|
||||
- cartridge identity and metadata,
|
||||
- app entry information,
|
||||
- asset metadata,
|
||||
- preload metadata.
|
||||
|
||||
This document adds runtime capability declaration to that same manifest.
|
||||
|
||||
## 4. Manifest Shape
|
||||
|
||||
The current manifest shape relevant to this document is:
|
||||
|
||||
```json
|
||||
{
|
||||
"magic": "PMTU",
|
||||
"cartridge_version": 1,
|
||||
"app_id": 1001,
|
||||
"title": "Example",
|
||||
"app_version": "1.0.0",
|
||||
"app_mode": "game",
|
||||
"entrypoint": "frame",
|
||||
"capabilities": ["gfx", "input"],
|
||||
"asset_table": [],
|
||||
"preload": []
|
||||
}
|
||||
```
|
||||
|
||||
Rules:
|
||||
|
||||
- `magic` identifies a Prometeu cartridge manifest,
|
||||
- `cartridge_version` identifies the cartridge manifest format line,
|
||||
- `entrypoint` identifies the runtime entrypoint,
|
||||
- for PBS v1, `entrypoint` should align with frontend-declared callable (`frame`),
|
||||
- `capabilities` declares the cartridge's requested runtime capabilities,
|
||||
- `asset_table` and `preload` remain separate concerns.
|
||||
|
||||
## 5. `capabilities`
|
||||
|
||||
### 5.1 General rules
|
||||
|
||||
`capabilities` is a manifest-facing nominal list.
|
||||
|
||||
Rules:
|
||||
|
||||
- `capabilities` is optional,
|
||||
- when omitted, it behaves as an empty list,
|
||||
- capability names are canonical lowercase identifiers,
|
||||
- duplicate entries are invalid,
|
||||
- unknown capability names are manifest errors.
|
||||
|
||||
### 5.2 Nominal capability set
|
||||
|
||||
The current nominal capability set is:
|
||||
|
||||
- `system`
|
||||
- `gfx`
|
||||
- `input`
|
||||
- `audio`
|
||||
- `fs`
|
||||
- `log`
|
||||
- `asset`
|
||||
- `bank`
|
||||
|
||||
These names are the normative manifest-facing representation.
|
||||
|
||||
## 6. Relationship to Runtime `CapFlags`
|
||||
|
||||
The runtime may continue to represent capabilities internally as a bitflag set.
|
||||
|
||||
That internal representation is an implementation detail.
|
||||
|
||||
The normative external model is:
|
||||
|
||||
- a nominal capability enum in the manifest,
|
||||
- deterministic conversion by the loader into runtime flags.
|
||||
|
||||
Canonical mapping:
|
||||
|
||||
- `system` -> `SYSTEM`
|
||||
- `gfx` -> `GFX`
|
||||
- `input` -> `INPUT`
|
||||
- `audio` -> `AUDIO`
|
||||
- `fs` -> `FS`
|
||||
- `log` -> `LOG`
|
||||
- `asset` -> `ASSET`
|
||||
- `bank` -> `BANK`
|
||||
|
||||
This means the recommended runtime design is:
|
||||
|
||||
1. deserialize `capabilities` into a nominal enum or equivalent validated representation,
|
||||
2. convert that validated set into internal `CapFlags`,
|
||||
3. use those flags during host-binding resolution.
|
||||
|
||||
## 7. Loader Semantics
|
||||
|
||||
The loader consumes both:
|
||||
|
||||
- the cartridge manifest,
|
||||
- and the PBX `SYSC` table.
|
||||
|
||||
Required behavior:
|
||||
|
||||
1. parse `manifest.json`,
|
||||
2. parse `capabilities`,
|
||||
3. convert the nominal capability list to internal capability flags,
|
||||
4. parse `program.pbx`,
|
||||
5. resolve each `SYSC` entry against the host registry,
|
||||
6. obtain required capabilities from resolved syscall metadata,
|
||||
7. fail if required capabilities are not granted by the manifest/policy environment.
|
||||
|
||||
The manifest alone does not make a program valid.
|
||||
The manifest must be consistent with the actual syscalls required by the PBX.
|
||||
|
||||
## 8. Requested vs Granted Authority
|
||||
|
||||
The manifest declares requested cartridge capabilities.
|
||||
|
||||
The loader/runtime environment is the authority that decides what is granted.
|
||||
|
||||
Current direction:
|
||||
|
||||
- in the initial runtime model, the manifest may act as the immediate source of granted capabilities,
|
||||
- a future platform policy layer may reduce or deny requested capabilities before final load.
|
||||
|
||||
Normative rule:
|
||||
|
||||
- the compiler does not grant capabilities,
|
||||
- the PBX does not grant capabilities,
|
||||
- cartridge/runtime loading is the authority boundary.
|
||||
|
||||
## 9. Relationship to Compiler and Packer
|
||||
|
||||
Responsibilities are split as follows:
|
||||
|
||||
Compiler:
|
||||
|
||||
- compiles source to PBX,
|
||||
- emits `SYSC`,
|
||||
- emits `HOSTCALL <sysc_index>`,
|
||||
- computes deterministic `requiredCapabilities` from admitted host bindings for packer tooling,
|
||||
- does not grant authority.
|
||||
|
||||
Packer:
|
||||
|
||||
- produces the cartridge manifest,
|
||||
- declares requested runtime capabilities,
|
||||
- packages `manifest.json`, `program.pbx`, and assets.
|
||||
|
||||
Loader:
|
||||
|
||||
- reads the manifest,
|
||||
- derives or receives granted capability flags,
|
||||
- validates those capabilities against PBX host requirements.
|
||||
|
||||
## 10. Validation Rules
|
||||
|
||||
The cartridge manifest must fail validation if:
|
||||
|
||||
1. `capabilities` contains an unknown name,
|
||||
2. `capabilities` contains duplicates,
|
||||
3. `capabilities` is not an array of strings or nominal enum values under the chosen serialization form.
|
||||
|
||||
Cartridge load must fail if:
|
||||
|
||||
1. the manifest omits a capability required by a resolved `SYSC` entry,
|
||||
2. a future platform policy denies a capability required by a resolved `SYSC` entry.
|
||||
|
||||
## 11. Serialization Guidance
|
||||
|
||||
The recommended manifest-facing model is a nominal enum list, not numeric masks.
|
||||
|
||||
Recommended JSON:
|
||||
|
||||
```json
|
||||
{
|
||||
"capabilities": ["gfx", "input", "audio"]
|
||||
}
|
||||
```
|
||||
|
||||
Rejected as normative surface:
|
||||
|
||||
- raw integer bitmasks,
|
||||
- hex masks,
|
||||
- unnamed positional arrays.
|
||||
|
||||
Rationale:
|
||||
|
||||
- nominal capability names are readable,
|
||||
- manifest diffs remain understandable,
|
||||
- packer and tooling validation is straightforward,
|
||||
- runtime may still use bitflags internally after conversion.
|
||||
|
||||
## 12. Current Decision Summary
|
||||
|
||||
The current temporary contract is:
|
||||
|
||||
1. `manifest.json` is the cartridge-facing load descriptor.
|
||||
2. `capabilities` is declared in `manifest.json`, not in `prometeu.json`.
|
||||
3. `capabilities` uses nominal canonical names such as `gfx` and `audio`.
|
||||
4. The runtime may keep using internal `CapFlags`.
|
||||
5. The loader converts nominal manifest capabilities into internal flags.
|
||||
6. PBX `SYSC` declares required host bindings, not authority.
|
||||
7. Loader validation fails if PBX host requirements exceed granted cartridge capabilities.
|
||||
+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.
|
||||
@@ -0,0 +1,356 @@
|
||||
# PBS Dynamic Semantics Specification
|
||||
|
||||
Status: Draft v1 (Temporary)
|
||||
Applies to: runtime-observable behavior of PBS core programs
|
||||
|
||||
## 1. Purpose
|
||||
|
||||
This document defines the normative dynamic semantics of PBS core.
|
||||
|
||||
Its purpose is to make runtime behavior convergent across implementations by fixing:
|
||||
|
||||
- execution ordering,
|
||||
- runtime evaluation of expressions and statements,
|
||||
- abrupt completion and propagation behavior,
|
||||
- runtime behavior of effect surfaces such as `optional` and `result`,
|
||||
- the execution boundary between ordinary PBS code, callbacks, contract calls, and host-backed calls.
|
||||
|
||||
## 2. Scope
|
||||
|
||||
This document defines:
|
||||
|
||||
- the observable execution model of PBS core,
|
||||
- evaluation order for expressions, statements, and blocks,
|
||||
- runtime branch selection for `if` and `switch`,
|
||||
- runtime application behavior for `apply`, call sugar, methods, contracts, callbacks, and host-backed call surfaces,
|
||||
- runtime behavior of `optional`, `result<E>`, `else`, `!`, and `handle`,
|
||||
- abrupt completion (`return`, `break`, `continue`) and trap propagation,
|
||||
- determinism requirements that affect execution behavior.
|
||||
|
||||
This document does not define:
|
||||
|
||||
- static typing or overload resolution rules,
|
||||
- GC algorithm internals,
|
||||
- exact IR shape or lowering passes,
|
||||
- diagnostics catalog wording,
|
||||
- the full PBX binary format.
|
||||
|
||||
## 3. Authority and Precedence
|
||||
|
||||
Normative precedence:
|
||||
|
||||
1. Runtime authority (`docs/specs/hardware/topics/chapter-2.md`, `chapter-3.md`, `chapter-9.md`, `chapter-12.md`, `chapter-16.md`)
|
||||
2. Bytecode authority (`docs/specs/bytecode/ISA_CORE.md`)
|
||||
3. `3. Core Syntax Specification.md`
|
||||
4. `4. Static Semantics Specification.md`
|
||||
5. This document
|
||||
|
||||
If a rule here conflicts with higher authority, it is invalid.
|
||||
|
||||
## 4. Normative Inputs
|
||||
|
||||
This document depends on, at minimum:
|
||||
|
||||
- `1. Language Charter.md`
|
||||
- `3. Core Syntax Specification.md`
|
||||
- `4. Static Semantics Specification.md`
|
||||
- `5. Manifest, Stdlib, and SDK Resolution Specification.md`
|
||||
- `6.2. Host ABI Binding and Loader Resolution Specification.md`
|
||||
|
||||
This document integrates the following accepted decisions:
|
||||
|
||||
- `docs/pbs/decisions/Dynamic Semantics - Execution Model Decision.md`
|
||||
- `docs/pbs/decisions/Dynamic Semantics - Effect Surfaces Decision.md`
|
||||
- `docs/pbs/decisions/Dynamic Semantics - Branch Selection Decision.md`
|
||||
- `docs/pbs/decisions/Host Memory Boundary Decision.md`
|
||||
|
||||
## 5. Already-Settled Inputs
|
||||
|
||||
The following inputs are already fixed elsewhere and must not be contradicted here:
|
||||
|
||||
- PBS prioritizes determinism and compatibility over ergonomics when the two conflict.
|
||||
- `FRAME_SYNC`-based execution semantics remain preserved.
|
||||
- No non-deterministic async execution model is part of PBS v1.
|
||||
- Function application is defined on the canonical `apply` surface, with call sugar desugaring to `apply`.
|
||||
- `optional T` function fallthrough yields `none`.
|
||||
- `result<E>` function fallthrough is a compile-time error.
|
||||
- `ok(...)` and `err(...)` are special result-flow forms rather than ordinary first-class runtime constructors.
|
||||
|
||||
## 6. Execution Baseline
|
||||
|
||||
PBS execution is single-threaded per program instance in v1.
|
||||
|
||||
User-visible execution is deterministic and does not expose concurrent interleaving.
|
||||
|
||||
User-visible sequencing is defined by:
|
||||
|
||||
- evaluation order,
|
||||
- branch selection,
|
||||
- abrupt completion,
|
||||
- result propagation,
|
||||
- trap propagation,
|
||||
- and host-call boundaries.
|
||||
|
||||
VM-internal frame layout, temporary storage, and lowering steps are not observable unless they change one of the semantic effects above.
|
||||
|
||||
`FRAME_SYNC` is the only normative safepoint in PBS v1.
|
||||
|
||||
## 7. Evaluation Order and Single Evaluation
|
||||
|
||||
### 7.1 Default rule
|
||||
|
||||
The default evaluation rule is strict left-to-right unless a construct explicitly states otherwise.
|
||||
|
||||
### 7.2 Call evaluation
|
||||
|
||||
For application:
|
||||
|
||||
1. form the call target,
|
||||
2. evaluate any receiver or callable artifact needed for target formation exactly once,
|
||||
3. evaluate arguments in source order from left to right,
|
||||
4. invoke the resolved target,
|
||||
5. produce one of:
|
||||
- normal return,
|
||||
- explicit `result<E>` propagation,
|
||||
- or `trap`.
|
||||
|
||||
This rule applies to canonical `apply` and to direct-call sugar that desugars to `apply`.
|
||||
|
||||
`apply` chains are parsed right-associatively, but their observable evaluation still follows the left-to-right rule above.
|
||||
|
||||
### 7.3 Exactly-once guarantees
|
||||
|
||||
The following expressions are evaluated exactly once where they appear:
|
||||
|
||||
- `if` condition,
|
||||
- `switch` selector,
|
||||
- the left operand of `opt else fallback`,
|
||||
- the payload expression of `some(expr)`,
|
||||
- the operand of `expr!`,
|
||||
- the operand of `handle expr { ... }`,
|
||||
- the context expression of `bind(context, fn_name)`,
|
||||
- call receivers, callees, and argument expressions as required by the call rule above.
|
||||
|
||||
## 8. Blocks and Abrupt Completion
|
||||
|
||||
Statements in a block execute in source order.
|
||||
|
||||
Only the final unsemicoloned expression in a block contributes to the block result.
|
||||
|
||||
Abrupt completion terminates the current construct immediately and prevents later sibling evaluation.
|
||||
|
||||
At minimum, the following are abrupt-completion forms:
|
||||
|
||||
- `return`,
|
||||
- `break`,
|
||||
- `continue`,
|
||||
- `!` on an error path,
|
||||
- `trap`.
|
||||
|
||||
## 9. `optional`
|
||||
|
||||
### 9.1 Runtime model
|
||||
|
||||
`optional` has exactly two runtime states:
|
||||
|
||||
- `some(payload)`
|
||||
- `none`
|
||||
|
||||
`none` is the canonical absence of payload.
|
||||
|
||||
### 9.2 Construction
|
||||
|
||||
`some(expr)` evaluates `expr` eagerly and exactly once before forming the `some(payload)` carrier.
|
||||
|
||||
### 9.3 Extraction
|
||||
|
||||
`opt else fallback`:
|
||||
|
||||
1. evaluates the left operand exactly once,
|
||||
2. yields the extracted payload if that operand evaluates to `some(payload)`,
|
||||
3. otherwise evaluates `fallback` and yields its value.
|
||||
|
||||
`else` is extraction with fallback, not error handling.
|
||||
|
||||
### 9.4 Trap behavior
|
||||
|
||||
`optional` is trap-free by itself.
|
||||
|
||||
Any trap associated with `some(expr)` or `opt else fallback` arises only from evaluating the relevant subexpressions.
|
||||
|
||||
## 10. `result<E>`
|
||||
|
||||
### 10.1 Runtime role
|
||||
|
||||
`result<E>` is the runtime carrier for success-or-modeled-failure at function boundaries and in expressions whose static type is `result<E> P`.
|
||||
|
||||
Expected, recoverable failures belong to `result<E>`, not to `trap`.
|
||||
|
||||
### 10.2 `!`
|
||||
|
||||
`expr!`:
|
||||
|
||||
1. evaluates `expr` exactly once,
|
||||
2. yields the extracted success payload if `expr` succeeds,
|
||||
3. performs immediate enclosing-function return with the same `err(...)` if `expr` yields error.
|
||||
|
||||
`!` does not:
|
||||
|
||||
- remap errors,
|
||||
- intercept traps,
|
||||
- or continue ordinary evaluation after the propagated error path is chosen.
|
||||
|
||||
### 10.3 `handle`
|
||||
|
||||
`handle expr { ... }`:
|
||||
|
||||
1. evaluates `expr` exactly once,
|
||||
2. yields the extracted success payload directly if `expr` succeeds,
|
||||
3. selects exactly one matching arm if `expr` yields error,
|
||||
4. executes that arm,
|
||||
5. requires the arm to terminate with either `ok(payload)` or `err(E2.case)`.
|
||||
|
||||
`ok(payload)` in a `handle` arm recovers locally and makes the `handle` expression yield `payload`.
|
||||
|
||||
`err(E2.case)` in a `handle` arm performs immediate enclosing-function return with `err(E2.case)`.
|
||||
|
||||
For the remap-only case, a short form such as `E1.case -> E2.case` is sugar for an arm block that returns `err(E2.case)`.
|
||||
|
||||
`handle` may execute user-defined logic inside an arm, but it remains specific to modeled `result` errors.
|
||||
|
||||
`handle` does not intercept or convert traps.
|
||||
|
||||
## 11. `apply`, Call Sugar, and `bind`
|
||||
|
||||
### 11.1 Canonical role of `apply`
|
||||
|
||||
`apply` is the canonical universal call surface in PBS v1.
|
||||
|
||||
The same observable call model applies to:
|
||||
|
||||
- top-level functions,
|
||||
- struct methods,
|
||||
- service methods,
|
||||
- contract calls,
|
||||
- callback calls,
|
||||
- host-backed calls.
|
||||
|
||||
Callable-specific dispatch may differ internally, but it does not change the user-visible sequencing model defined in this document.
|
||||
|
||||
### 11.2 Effect boundaries
|
||||
|
||||
`apply` does not introduce implicit effect composition.
|
||||
|
||||
If a callable returns:
|
||||
|
||||
- `optional<P>`, extraction remains explicit through `else`,
|
||||
- `result<E> P`, propagation or processing remains explicit through `!` or `handle`.
|
||||
|
||||
### 11.3 `bind`
|
||||
|
||||
`bind(context, fn_name)` is the explicit callback-formation mechanism in PBS v1.
|
||||
|
||||
It:
|
||||
|
||||
- evaluates `context` exactly once,
|
||||
- captures the same struct context identity without copying it,
|
||||
- attaches that context to the resolved top-level function target,
|
||||
- produces a callback value whose invocation behaves as if the target function were called with the captured context as its first argument.
|
||||
|
||||
At the language-semantics level, `bind` is trap-free.
|
||||
|
||||
Incompatible binding shape remains a compile-time matter rather than a runtime failure mode.
|
||||
|
||||
Retention and storage consequences of `bind` belong to `Memory and Lifetime Specification.md`.
|
||||
|
||||
## 12. Branch Selection
|
||||
|
||||
### 12.1 `if`
|
||||
|
||||
`if` evaluates its condition exactly once.
|
||||
|
||||
If the condition is `true`, only the selected `then` branch executes.
|
||||
If the condition is `false`, only the selected `else` branch executes.
|
||||
|
||||
The non-selected branch is not evaluated, even partially.
|
||||
|
||||
### 12.2 `switch`
|
||||
|
||||
`switch` evaluates its selector exactly once and executes exactly one selected arm.
|
||||
|
||||
The non-selected arms are not evaluated.
|
||||
|
||||
`switch` is restricted to statically discriminable selector categories in v1:
|
||||
|
||||
- literal-comparable scalar values,
|
||||
- enum values,
|
||||
- canonical `str` values,
|
||||
- and any other selector category admitted elsewhere by explicit specification.
|
||||
|
||||
`switch` does not accept:
|
||||
|
||||
- `result`,
|
||||
- `error`,
|
||||
- structs,
|
||||
- string object/reference types distinct from canonical `str`,
|
||||
- heap-backed selector categories.
|
||||
|
||||
Matching is exact and deterministic:
|
||||
|
||||
- enum selectors match by canonical enum-case identity,
|
||||
- scalar selectors match by the exact equality rule for that scalar category,
|
||||
- `str` selectors match by canonical static string identity.
|
||||
|
||||
`switch` does not perform structural matching, guard evaluation, or user-defined equality dispatch.
|
||||
|
||||
## 13. Trap, Determinism, and Host Interaction
|
||||
|
||||
### 13.1 Trap boundary
|
||||
|
||||
`trap` is reserved for failures that are:
|
||||
|
||||
- outside the ordinary userland contract,
|
||||
- not suitably representable as the declared `result<E>` surface,
|
||||
- caused by runtime or host invariant failure,
|
||||
- or severe enough that ordinary userland recovery is not part of the v1 language model.
|
||||
|
||||
PBS v1 does not define `try/catch` for traps.
|
||||
|
||||
Traps are not part of ordinary recoverable control flow.
|
||||
|
||||
Any trap aborts the current PBS program execution rather than returning control to ordinary userland flow.
|
||||
|
||||
Control then transfers to runtime or firmware crash handling outside the ordinary language model.
|
||||
|
||||
### 13.2 Host interaction
|
||||
|
||||
Host calls must not introduce user-visible reordering of already-defined PBS evaluation order.
|
||||
|
||||
Expected operational failures of host-backed surfaces should be modeled through their declared contract rather than through ad hoc trap usage.
|
||||
|
||||
Cross-boundary host/userland interaction remains stack-value-based as defined by the host-boundary decision track; direct host-memory manipulation is not part of PBS userland semantics.
|
||||
|
||||
## 14. TODO
|
||||
|
||||
The following items remain editorial or cross-spec integration tasks rather than open semantic agenda questions:
|
||||
|
||||
- the final wording split between this document and `16. Runtime Execution and Initialization Specification.md` for crash handoff after trap,
|
||||
- the final wording split between this document and `10. Memory and Lifetime Specification.md` for retention/allocation facts that arise during ordinary execution,
|
||||
- conformance-oriented example coverage once `13. Conformance Test Specification.md` is expanded.
|
||||
|
||||
## 15. Non-Goals
|
||||
|
||||
- Reopening grammar or static typing unless current text is impossible to execute normatively.
|
||||
- Defining exact GC collection strategy.
|
||||
- Designing future async, actor, or scheduler models.
|
||||
- Specifying backend optimization policy.
|
||||
|
||||
## 16. Exit Criteria
|
||||
|
||||
This document is ready to move beyond temporary draft status only when:
|
||||
|
||||
1. every runtime-observable core construct has deterministic evaluation wording,
|
||||
2. trap versus status-value behavior is explicit for every effect-bearing construct,
|
||||
3. host-call interaction rules are stated without relying on informal prose elsewhere,
|
||||
4. the document can drive runtime conformance tests without decision backfill,
|
||||
5. the remaining TODO items are reduced to editorial integration rather than semantic uncertainty.
|
||||
@@ -0,0 +1,59 @@
|
||||
# PBS Specs
|
||||
|
||||
This directory contains the normative PBS specification set.
|
||||
|
||||
## Purpose
|
||||
|
||||
Specs define the official PBS language/frontend contract.
|
||||
|
||||
They exist to make behavior, constraints, and interfaces stable across implementations and reviews.
|
||||
|
||||
Cross-language acceptance rules are not defined here.
|
||||
Those are maintained in `docs/general/specs`.
|
||||
|
||||
## Expected Format
|
||||
|
||||
The exact structure may vary by document, but a spec should usually contain:
|
||||
|
||||
1. Title
|
||||
2. Status
|
||||
3. Scope or Applies To
|
||||
4. Purpose
|
||||
5. Authority and Precedence
|
||||
6. Normative Inputs
|
||||
7. Core Rules
|
||||
8. Non-Goals
|
||||
9. Exit Criteria
|
||||
|
||||
Some specs may also include:
|
||||
|
||||
- already-settled inputs,
|
||||
- initial section targets,
|
||||
- `TODO` sections for tracked unresolved items,
|
||||
- cross-references to adjacent specs.
|
||||
|
||||
## Writing Rules
|
||||
|
||||
- Write in normative language.
|
||||
- Integrate only decisions that have already been closed.
|
||||
- Keep debate history and exploratory alternatives out of the spec body.
|
||||
- Preserve clear boundaries between adjacent specs.
|
||||
- Use `TODO` only for explicitly tracked unresolved items, not as a substitute for agenda work.
|
||||
|
||||
## Upstream Rule
|
||||
|
||||
Specs should normally be fed by:
|
||||
|
||||
1. agendas that frame the open topic,
|
||||
2. decisions that close the architectural question,
|
||||
3. then spec integration.
|
||||
|
||||
If a spec edit would require guessing an unresolved design choice, the correct action is to stop and surface the missing decision first.
|
||||
|
||||
## Current Chapter Focus
|
||||
|
||||
The active PBS chapter focus is:
|
||||
|
||||
- `11. AST Specification.md`
|
||||
- `12. Diagnostics Specification.md`
|
||||
- `13. Lowering IRBackend Specification.md`
|
||||
@@ -0,0 +1,135 @@
|
||||
# PBS Conformance Test Specification
|
||||
|
||||
Status: Draft v1 (Quality-Gate Baseline)
|
||||
Applies to: executable quality gates for PBS language frontends and language-level regression evidence
|
||||
|
||||
## 1. Purpose
|
||||
|
||||
This document defines the minimum quality-gate contract for PBS language implementations.
|
||||
|
||||
The goal is practical and test-driven:
|
||||
|
||||
- keep quality measurable while language, lowering, and runtime integration are still evolving,
|
||||
- require only gates that can be proved with tests today,
|
||||
- avoid freezing speculative backend policy too early.
|
||||
|
||||
## 2. Scope
|
||||
|
||||
This document defines:
|
||||
|
||||
- required unit-test gates for language frontend work,
|
||||
- required regression gate behavior for published language behavior,
|
||||
- and the boundary for runtime integration regression tests when a backend can emit executable artifacts.
|
||||
|
||||
This document does not define:
|
||||
|
||||
- runtime semantics or VM behavior taxonomy,
|
||||
- full artifact-level compatibility matrices,
|
||||
- one test harness layout,
|
||||
- or one repository structure for fixtures.
|
||||
|
||||
## 3. Authority and Precedence
|
||||
|
||||
Normative precedence:
|
||||
|
||||
1. `1. Language Charter.md`
|
||||
2. `2. Governance and Versioning.md`
|
||||
3. `3. Core Syntax Specification.md`
|
||||
4. `4. Static Semantics Specification.md`
|
||||
5. `12. Diagnostics Specification.md`
|
||||
6. `13. Lowering IRBackend Specification.md`
|
||||
7. `20. IRBackend to IRVM Lowering Specification.md`
|
||||
8. `21. IRVM Optimization Pipeline Specification.md`
|
||||
9. This document
|
||||
|
||||
This document must not weaken normative requirements from higher-precedence specs.
|
||||
|
||||
## 4. Normative Inputs
|
||||
|
||||
This document depends on:
|
||||
|
||||
- `3. Core Syntax Specification.md`
|
||||
- `4. Static Semantics Specification.md`
|
||||
- `12. Diagnostics Specification.md`
|
||||
- `13. Lowering IRBackend Specification.md`
|
||||
- `20. IRBackend to IRVM Lowering Specification.md`
|
||||
- `21. IRVM Optimization Pipeline Specification.md`
|
||||
- `17. Compatibility and Evolution Policy.md`
|
||||
|
||||
## 5. Quality Gate Model
|
||||
|
||||
PBS v1 uses two practical gate families.
|
||||
|
||||
### 5.1 Gate U: Language Unit Quality Gate (Required)
|
||||
|
||||
Every language frontend integrated into Studio/compiler must have passing unit tests that cover, at minimum:
|
||||
|
||||
1. lexer behavior (valid tokenization and deterministic lexical rejection),
|
||||
2. parser behavior (valid parse and deterministic syntax rejection),
|
||||
3. AST shape for representative valid programs,
|
||||
4. frontend-to-IR backend emission (`IRBackend`/`IRBackendFile`) for representative valid programs,
|
||||
5. diagnostics surface for required rejection cases (`code`, `severity`, and primary attribution).
|
||||
|
||||
This gate is mandatory for each language regardless of backend maturity.
|
||||
|
||||
### 5.2 Gate I: Integration Regression Gate With Runtime (Conditional)
|
||||
|
||||
When a language backend can emit executable artifacts (for example bytecode), integration regression tests must be introduced for that language.
|
||||
|
||||
At minimum, those tests must:
|
||||
|
||||
1. compile selected fixtures through the executable pipeline for that language,
|
||||
2. execute them against the runtime line declared for that backend,
|
||||
3. assert deterministic observable outcomes for supported fixtures,
|
||||
4. preserve fixed bugs and published supported examples as regression tests,
|
||||
5. and cover deterministic behavior across `LowerToVM`, `OptimizeIRVM`, and `EmitBytecode` boundaries when those stages are present.
|
||||
|
||||
Until executable artifact emission exists for a language, Gate I is explicitly `deferred` for that language and does not block frontend progress.
|
||||
|
||||
## 6. Regression Policy
|
||||
|
||||
Published supported behavior must remain regression-protected.
|
||||
|
||||
At minimum, each language corpus must retain:
|
||||
|
||||
1. bug reproductions for fixes that remain in supported scope,
|
||||
2. published supported examples,
|
||||
3. and core gate fixtures required to justify the language support state.
|
||||
|
||||
Regression grouping by language is expected; one shared monolithic corpus is not required.
|
||||
|
||||
## 7. Claims and Evidence
|
||||
|
||||
For PBS quality claims at this stage:
|
||||
|
||||
- a language may be considered `frontend-ready` only with Gate U passing,
|
||||
- a language may be considered `integration-ready` only with Gate U and Gate I passing where Gate I applies,
|
||||
- and a published support claim must map to executable evidence from these gates.
|
||||
- conformance-relevant FE/BE changes in executable backend paths MUST update `22. Backend Spec-to-Test Conformance Matrix.md` and pass matrix hard-gate policy checks.
|
||||
|
||||
The exact publication vocabulary is owned by `17. Compatibility and Evolution Policy.md`.
|
||||
|
||||
## 8. Explicit Deferrals
|
||||
|
||||
The following are intentionally deferred until backend/runtime contracts stabilize further:
|
||||
|
||||
- detailed artifact-level conformance taxonomy,
|
||||
- verifier-facing conformance taxonomy,
|
||||
- full compatibility matrix axes beyond the current minimum support table,
|
||||
- and one mandatory fixture repository layout.
|
||||
|
||||
## 9. Non-Goals
|
||||
|
||||
- Replacing normative language specs with tests.
|
||||
- Defining runtime semantics in this document.
|
||||
- Freezing backend architecture decisions prematurely.
|
||||
- Treating performance benchmarks as conformance gates.
|
||||
|
||||
## 10. Exit Criteria
|
||||
|
||||
This document is in a healthy state when:
|
||||
|
||||
1. every active language has an explicit Gate U status,
|
||||
2. languages with executable backends have an explicit Gate I status,
|
||||
3. published supported language behavior has regression evidence,
|
||||
4. and no support claim exists without mapped test evidence.
|
||||
@@ -0,0 +1,405 @@
|
||||
# PBS Name Resolution and Module Linking Specification
|
||||
|
||||
Status: Draft v1 (Normative)
|
||||
Applies to: scope formation, name lookup, imports, exports, barrel visibility, cross-module resolution, and semantic linking of PBS programs
|
||||
|
||||
## 1. Purpose
|
||||
|
||||
This document defines the normative name-resolution and semantic-linking model for PBS v1.
|
||||
|
||||
Its purpose is to make the visible declaration space of a PBS program deterministic enough that:
|
||||
|
||||
- frontend implementations do not invent lookup or collision rules,
|
||||
- diagnostics can classify failures consistently,
|
||||
- conformance can test source-facing rejection classes,
|
||||
- and lowering begins from an already-linked visible program.
|
||||
|
||||
## 2. Scope
|
||||
|
||||
This document defines:
|
||||
|
||||
- module scope construction,
|
||||
- lookup order by namespace,
|
||||
- import and alias resolution,
|
||||
- barrel-mediated visibility,
|
||||
- reserved stdlib shell resolution for builtin and host-backed surfaces,
|
||||
- callable visibility across modules,
|
||||
- and linking-time rejection conditions before lowering.
|
||||
|
||||
This document does not define:
|
||||
|
||||
- runtime execution behavior,
|
||||
- optimizer or backend internals,
|
||||
- full PBX binary linking,
|
||||
- or loader/runtime artifact behavior after lowering.
|
||||
|
||||
## 3. Authority and Precedence
|
||||
|
||||
Normative precedence:
|
||||
|
||||
1. `3. Core Syntax Specification.md`
|
||||
2. `4. Static Semantics Specification.md`
|
||||
3. `5. Manifest, Stdlib, and SDK Resolution Specification.md`
|
||||
4. `6. VM-owned vs Host-backed.md`
|
||||
5. `6.1. Intrinsics and Builtin Types Specification.md`
|
||||
6. `6.2. Host ABI Binding and Loader Resolution Specification.md`
|
||||
7. `8. Stdlib Environment Packaging and Loading Specification.md`
|
||||
8. `18. Standard Library Surface Specification.md`
|
||||
9. This document
|
||||
|
||||
If a rule here conflicts with higher-precedence specs, it is invalid.
|
||||
|
||||
## 4. Normative Inputs
|
||||
|
||||
This document depends on, at minimum:
|
||||
|
||||
- `3. Core Syntax Specification.md`
|
||||
- `4. Static Semantics Specification.md`
|
||||
- `5. Manifest, Stdlib, and SDK Resolution Specification.md`
|
||||
- `6. VM-owned vs Host-backed.md`
|
||||
- `6.1. Intrinsics and Builtin Types Specification.md`
|
||||
- `6.2. Host ABI Binding and Loader Resolution Specification.md`
|
||||
- `8. Stdlib Environment Packaging and Loading Specification.md`
|
||||
- `18. Standard Library Surface Specification.md`
|
||||
|
||||
## 5. Already-Settled Inputs
|
||||
|
||||
The following inputs are already fixed elsewhere and must not be contradicted here:
|
||||
|
||||
- PBS has distinct type, value, callable, and host-owner namespaces.
|
||||
- `mod.barrel` is the single source of module visibility.
|
||||
- Imports target modules, not files.
|
||||
- Reserved stdlib project spaces are resolved only from the selected stdlib environment.
|
||||
- Only `pub` symbols may be imported from another module.
|
||||
- Reserved stdlib/interface modules may expose compile-time-only shells for both host-backed and VM-owned surfaces, and may expose service facades over non-public host owners.
|
||||
- Source-visible builtin names are resolved through imported builtin shell declarations rather than by hardcoded source spelling alone.
|
||||
- Canonical builtin identity and canonical intrinsic identity are governed by builtin metadata rather than by the imported PBS-visible declaration name alone.
|
||||
- Canonical host identity is governed by host metadata rather than by imported owner spelling alone.
|
||||
|
||||
## 6. Module Scope Construction
|
||||
|
||||
### 6.1 Module collection
|
||||
|
||||
For one module:
|
||||
|
||||
- the compiler collects top-level declarations from all `.pbs` files in that module,
|
||||
- forms one module-level declaration space,
|
||||
- and only then applies `mod.barrel` to determine `mod` and `pub` visibility.
|
||||
|
||||
Rules:
|
||||
|
||||
- declaration existence is not derived from barrel entries,
|
||||
- module-internal top-level declaration availability does not depend on source-file order,
|
||||
- and `mod.barrel` is a visibility filter over existing declarations rather than a declaration source.
|
||||
|
||||
### 6.2 Lexical scope
|
||||
|
||||
Inside executable bodies:
|
||||
|
||||
- lexical block scope nests normally over module scope,
|
||||
- nearest local bindings win within value lookup,
|
||||
- and lexical nesting remains independent from cross-module visibility.
|
||||
|
||||
## 7. Lookup Order By Namespace
|
||||
|
||||
Lookup in PBS remains namespace-based.
|
||||
|
||||
### 7.1 Value position
|
||||
|
||||
Value-position lookup follows this order:
|
||||
|
||||
1. nearest local lexical bindings,
|
||||
2. parameters in the current lexical function scope,
|
||||
3. visible module-local values,
|
||||
4. visible imported values.
|
||||
|
||||
For lookup purposes, parameters and local `let` bindings participate in one nearest lexical value layer.
|
||||
|
||||
### 7.2 Type position
|
||||
|
||||
Type-position lookup follows this order:
|
||||
|
||||
1. visible module-local type declarations,
|
||||
2. visible imported type declarations,
|
||||
3. builtin simple types `int`, `float`, `bool`, and `str` as always-available reserved type names.
|
||||
|
||||
Builtin simple types:
|
||||
|
||||
- are not treated as ordinary imported declarations,
|
||||
- do not participate in ordinary import competition,
|
||||
- and remain always available without import.
|
||||
|
||||
### 7.3 Callable position
|
||||
|
||||
Callable-position lookup follows this order:
|
||||
|
||||
1. visible module-local callables,
|
||||
2. visible imported callables.
|
||||
|
||||
Callable lookup operates only on already-formed visible callable sets as defined later in this document.
|
||||
|
||||
### 7.4 Host-owner position
|
||||
|
||||
Host-owner lookup follows this order:
|
||||
|
||||
1. visible module-local host owners,
|
||||
2. visible imported host owners.
|
||||
|
||||
Host-owner lookup remains separate from type, value, and callable lookup.
|
||||
|
||||
## 8. Import Surface And Naming
|
||||
|
||||
### 8.1 Effective local imported name
|
||||
|
||||
The local visible name introduced by an import is always the post-alias name when an alias is present.
|
||||
|
||||
Rules:
|
||||
|
||||
- `import { X } from @project:path;` introduces the visible local name `X`,
|
||||
- `import { X as Y } from @project:path;` introduces only the visible local name `Y`,
|
||||
- and alias spelling changes only the local visible name, never canonical builtin identity or canonical host identity.
|
||||
|
||||
### 8.2 Named import
|
||||
|
||||
`import { X } from @project:path;`:
|
||||
|
||||
- resolves the target module,
|
||||
- checks that `X` is exported and importable from that module,
|
||||
- and introduces `X` into the corresponding namespace locally.
|
||||
|
||||
### 8.3 Whole-module import
|
||||
|
||||
`import { * } from @project:path;`:
|
||||
|
||||
- resolves the target module,
|
||||
- introduces the target module's exported visible names under their exported spellings,
|
||||
- but does not create a module-valued binding,
|
||||
- does not create a namespace object,
|
||||
- and does not authorize qualified member access by itself.
|
||||
|
||||
If PBS later wants module-object or namespace-qualified source semantics, that must be added explicitly rather than inferred from this import form.
|
||||
|
||||
## 9. Collision And Ambiguity Rules
|
||||
|
||||
### 9.1 Local versus imported
|
||||
|
||||
If a module-local declaration and an imported declaration produce the same visible name in the same namespace:
|
||||
|
||||
- the program is rejected,
|
||||
- and the implementation must not silently shadow either declaration.
|
||||
|
||||
This includes function names.
|
||||
A module-local function and an imported function with the same visible name are rejected rather than merged.
|
||||
|
||||
### 9.2 Imported versus imported
|
||||
|
||||
If two imports produce the same visible name in the same namespace:
|
||||
|
||||
- the program is not rejected only when both imports resolve to the same canonical underlying declaration after module resolution,
|
||||
- such same-origin duplication is redundant but tolerated,
|
||||
- and the program is rejected if the imports resolve to different canonical underlying declarations.
|
||||
|
||||
### 9.3 Namespace separation
|
||||
|
||||
Names in different namespaces do not collide merely by spelling.
|
||||
|
||||
For example:
|
||||
|
||||
- a host owner and a type declaration do not collide by spelling alone,
|
||||
- because host-owner namespace remains distinct from type namespace.
|
||||
|
||||
### 9.4 Non-callable names do not merge
|
||||
|
||||
Non-callable namespaces do not merge by name.
|
||||
|
||||
## 10. Callable Sets And Cross-Module Linking
|
||||
|
||||
### 10.1 Imported callable set
|
||||
|
||||
`import { f } from @project:path;` imports the exported callable set named `f` from the target module.
|
||||
|
||||
Rules:
|
||||
|
||||
- the imported callable set for `f` consists only of those overload signatures of `f` that are exported through that module's `mod.barrel`,
|
||||
- non-exported overloads in the target module do not participate in the imported callable set,
|
||||
- and import operates on the exported callable name rather than on one overload at a time.
|
||||
|
||||
### 10.2 Same-origin versus different-origin callable imports
|
||||
|
||||
If the same visible callable name is imported more than once:
|
||||
|
||||
- same-origin duplicate imports are tolerated as redundancy when they resolve to the same canonical callable-set origin,
|
||||
- different-origin imports are rejected immediately,
|
||||
- and the implementation must not wait until a callsite to reject different-origin callable-name collisions.
|
||||
|
||||
### 10.3 Local versus imported callable names
|
||||
|
||||
If a module-local function name and an imported function name are the same visible callable name:
|
||||
|
||||
- the program is rejected immediately,
|
||||
- and the implementation must not merge the local and imported callable sets.
|
||||
|
||||
### 10.4 Overload-resolution boundary
|
||||
|
||||
PBS separates:
|
||||
|
||||
- callable-set formation,
|
||||
- and overload resolution at a callsite.
|
||||
|
||||
Rules:
|
||||
|
||||
- the implementation must first form one unambiguous visible callable set,
|
||||
- only then may ordinary overload resolution operate on the candidate signatures of that set,
|
||||
- and callsite context must not be used to resolve ambiguity between different imported callable origins.
|
||||
|
||||
## 11. Reserved Stdlib Shell Resolution
|
||||
|
||||
### 11.1 Reserved shells as imported declarations
|
||||
|
||||
Source-visible declarations exposed by reserved builtin shells are imported into their ordinary corresponding namespaces.
|
||||
|
||||
This means:
|
||||
|
||||
- builtin-exposed types enter type lookup as imported type declarations,
|
||||
- builtin-exposed constants enter value lookup as imported values,
|
||||
- and host owners enter host-owner lookup as imported host-owner declarations.
|
||||
|
||||
`declare builtin type` itself remains a reserved stdlib/toolchain declaration form rather than ordinary user-authored source syntax.
|
||||
|
||||
### 11.2 Builtin simple types versus imported builtin shells
|
||||
|
||||
PBS distinguishes:
|
||||
|
||||
- the predeclared builtin simple-type set `int`, `float`, `bool`, `str`,
|
||||
- and imported builtin shells such as `Vec2` or `Color`.
|
||||
|
||||
Imported builtin shells are not promoted to the same always-available status as builtin simple types.
|
||||
|
||||
### 11.3 Intrinsic member lookup
|
||||
|
||||
Builtin intrinsic methods:
|
||||
|
||||
- never participate in free lookup,
|
||||
- are not introduced by import as free functions,
|
||||
- and are resolved only through member lookup on a receiver already known to have the corresponding builtin type.
|
||||
|
||||
Alias changes to the imported builtin type affect only the local visible owner spelling, not the canonical builtin or intrinsic identity.
|
||||
|
||||
### 11.4 Collision policy for reserved shells
|
||||
|
||||
Reserved builtin shells and host owners follow the same collision policy as ordinary imported declarations.
|
||||
|
||||
Rules:
|
||||
|
||||
- same visible name in the same namespace is an error unless another already-closed rule explicitly permits otherwise,
|
||||
- reserved-shell status does not authorize silent shadowing,
|
||||
- and host owners do not collide with types or values merely by spelling because host-owner namespace remains separate.
|
||||
|
||||
### 11.5 Reserved project-space policy
|
||||
|
||||
For source-level policy:
|
||||
|
||||
- builtin shells are preferred under `@core:*`,
|
||||
- and host-facing capability surfaces remain the natural fit for `@sdk:*`.
|
||||
|
||||
### 11.6 Canonical identity
|
||||
|
||||
Canonical builtin identity and canonical host identity are not derived from local alias spelling.
|
||||
|
||||
Duplicate canonical builtin identities or duplicate canonical host identities in one resolved environment are rejected as linking failures.
|
||||
|
||||
## 12. Linking Phase Boundary And Deterministic Failures
|
||||
|
||||
### 12.1 Normative phase baseline
|
||||
|
||||
PBS v1 adopts the following normative phase baseline for name resolution and related frontend failures:
|
||||
|
||||
1. `syntax`
|
||||
2. `manifest/import resolution`
|
||||
3. `linking`
|
||||
4. `static semantics`
|
||||
|
||||
### 12.2 Syntax
|
||||
|
||||
`syntax` owns malformed import grammar and other token-shape or grammar-shape failures.
|
||||
|
||||
### 12.3 Manifest and import resolution
|
||||
|
||||
`manifest/import resolution` owns failures to resolve:
|
||||
|
||||
- project space,
|
||||
- reserved stdlib space,
|
||||
- dependency graph target,
|
||||
- module path,
|
||||
- or environment source.
|
||||
|
||||
### 12.4 Linking
|
||||
|
||||
`linking` owns assembly of visible declarations across files and modules.
|
||||
|
||||
At minimum, `linking` owns:
|
||||
|
||||
1. import of non-exported names,
|
||||
2. unresolved barrel entries against module declarations,
|
||||
3. collisions between visible imported names from different canonical origins,
|
||||
4. local-versus-import visibility collisions,
|
||||
5. callable-origin conflicts across module boundaries,
|
||||
6. duplicate canonical builtin identities in one resolved environment,
|
||||
7. duplicate canonical host identities in one resolved environment.
|
||||
|
||||
### 12.5 Static semantics
|
||||
|
||||
`static semantics` owns:
|
||||
|
||||
1. duplicate local declarations,
|
||||
2. declaration validity,
|
||||
3. type checking,
|
||||
4. member lookup once the receiver type is known,
|
||||
5. overload resolution within an already-formed visible callable set.
|
||||
|
||||
Member lookup failure on an already-typed builtin receiver therefore belongs to `static semantics`.
|
||||
|
||||
### 12.6 Imported-origin conflicts are rejected before callsite analysis
|
||||
|
||||
Conflicts between different imported origins are rejected in `linking` immediately.
|
||||
|
||||
The implementation must not:
|
||||
|
||||
- wait for a specific callsite,
|
||||
- use overload resolution to rescue imported-origin ambiguity,
|
||||
- or defer visible declaration conflicts to later typing work.
|
||||
|
||||
## 13. Deterministic Resolution Failures
|
||||
|
||||
At minimum, a conforming implementation must reject:
|
||||
|
||||
1. import of a non-exported builtin type shell,
|
||||
2. import of a non-exported builtin constant shell,
|
||||
3. import of a non-exported host owner shell,
|
||||
4. import of any non-exported name from a resolved module,
|
||||
5. unresolved barrel entries against module declarations,
|
||||
6. local-versus-import same-namespace collisions,
|
||||
7. imported same-name collisions from different canonical origins,
|
||||
8. local-versus-import function-name collisions,
|
||||
9. duplicate visible builtin type declarations that claim the same canonical builtin identity in one resolved environment,
|
||||
10. duplicate visible builtin constants that claim the same canonical builtin constant identity in one resolved environment,
|
||||
11. duplicate visible host owners that claim the same canonical host identity in one resolved environment,
|
||||
12. member lookup on a builtin receiver where the imported builtin shell does not declare the requested field or intrinsic member,
|
||||
13. any resolution path that attempts to derive host or builtin canonical identity from alias spelling alone.
|
||||
|
||||
## 14. Non-Goals
|
||||
|
||||
- Reopening the already-settled import surface syntax.
|
||||
- Defining runtime loader behavior.
|
||||
- Freezing one compiler symbol-table implementation.
|
||||
- Freezing one internal compiler pass graph.
|
||||
|
||||
## 15. Exit Criteria
|
||||
|
||||
This document is ready to move beyond its current draft status only when:
|
||||
|
||||
1. name lookup is deterministic across all relevant scopes,
|
||||
2. barrel and module linking behavior is explicit,
|
||||
3. reserved stdlib shell resolution is explicit for host-backed and VM-owned surfaces,
|
||||
4. cross-module callable visibility and ambiguity behavior are normatively defined,
|
||||
5. and the phase ownership of source-facing name-resolution failures is explicit enough for diagnostics and conformance.
|
||||
@@ -0,0 +1,178 @@
|
||||
# PBS Bytecode and PBX Mapping Specification
|
||||
|
||||
Status: Draft v1 (Backend Baseline)
|
||||
Applies to: mapping from lowered/optimized backend programs into PBX sections, bytecode-facing artifacts, and source-to-artifact invariants required by loader/verifier/runtime
|
||||
|
||||
## 1. Purpose
|
||||
|
||||
This document defines the normative mapping between backend-lowered semantics and emitted PBX/bytecode-facing artifacts.
|
||||
|
||||
Its purpose is to keep artifact emission deterministic and compatible with runtime loader/verifier contracts.
|
||||
|
||||
## 2. Scope
|
||||
|
||||
This document defines:
|
||||
|
||||
- artifact-level obligations at `IRVM -> BytecodeModule` emission boundary,
|
||||
- mapping invariants for function layout, code layout, callsite forms, and host-binding declarations,
|
||||
- minimum debug/source-attribution hooks for v1 backend/runtime diagnostics and conformance,
|
||||
- and deterministic artifact rejection expectations for emitter-side failures.
|
||||
|
||||
This document does not define:
|
||||
|
||||
- full ISA semantics,
|
||||
- runtime loader patching internals,
|
||||
- or one mandatory emitter implementation architecture.
|
||||
|
||||
## 3. Authority and Precedence
|
||||
|
||||
Normative precedence:
|
||||
|
||||
1. Runtime authority (`docs/specs/hardware/topics/chapter-2.md`, `chapter-3.md`, `chapter-9.md`, `chapter-12.md`, `chapter-16.md`)
|
||||
2. Bytecode authority (`docs/specs/bytecode/ISA_CORE.md`)
|
||||
3. `docs/pbs/specs/6.1. Intrinsics and Builtin Types Specification.md`
|
||||
4. `docs/pbs/specs/6.2. Host ABI Binding and Loader Resolution Specification.md`
|
||||
5. `20. IRBackend to IRVM Lowering Specification.md`
|
||||
6. `21. IRVM Optimization Pipeline Specification.md`
|
||||
7. This document
|
||||
|
||||
If a rule here conflicts with higher-precedence authorities, it is invalid.
|
||||
|
||||
## 4. Normative Inputs
|
||||
|
||||
This document depends on, at minimum:
|
||||
|
||||
- `docs/pbs/specs/6.1. Intrinsics and Builtin Types Specification.md`
|
||||
- `docs/pbs/specs/6.2. Host ABI Binding and Loader Resolution Specification.md`
|
||||
- `20. IRBackend to IRVM Lowering Specification.md`
|
||||
- `21. IRVM Optimization Pipeline Specification.md`
|
||||
|
||||
## 5. Already-Settled Inputs
|
||||
|
||||
The following are fixed and must not be contradicted:
|
||||
|
||||
- The compiler emits host-binding declarations in PBX `SYSC`.
|
||||
- Host-backed callsites are emitted in pre-load form as `HOSTCALL <sysc_index>`.
|
||||
- `SYSC` entries are deduplicated by canonical identity and ordered by first occurrence.
|
||||
- The loader resolves host bindings and rewrites `HOSTCALL` to `SYSCALL` before execution.
|
||||
- Raw `SYSCALL` in pre-load artifacts is rejected.
|
||||
- VM-owned intrinsic artifacts are distinct from `SYSC`, `HOSTCALL`, and `SYSCALL`.
|
||||
- `SYSC` section is mandatory in valid PBX artifacts (empty section is valid).
|
||||
|
||||
## 6. Artifact Mapping Contract (v1)
|
||||
|
||||
### 6.1 Required module surfaces
|
||||
|
||||
Emitter output must map to a `BytecodeModule` shape containing:
|
||||
|
||||
1. `const_pool`,
|
||||
2. `functions`,
|
||||
3. `code`,
|
||||
4. `exports`,
|
||||
5. `syscalls`,
|
||||
6. optional `debug_info` that still satisfies v1 minimum debug obligations.
|
||||
|
||||
### 6.2 Function ordering and IDs
|
||||
|
||||
Function ordering must be deterministic:
|
||||
|
||||
1. entrypoint function index is `0`,
|
||||
2. entrypoint index `0` is selected from qualified `EntrypointRef(entryPointModuleId, entryPointCallableName)`,
|
||||
3. remaining functions are ordered by `(moduleId -> modulePool canonical key, callable_name, source_start)`,
|
||||
4. identical admitted input graph yields identical function ordering and function ids.
|
||||
|
||||
### 6.3 Function code layout
|
||||
|
||||
Emitter must satisfy:
|
||||
|
||||
1. `code_offset` values are unique and monotonic over function order,
|
||||
2. `code_len` exactly matches emitted bytes for each function body,
|
||||
3. `code_offset + code_len` stays within `code.len`,
|
||||
4. and final code concatenation is deterministic.
|
||||
|
||||
### 6.4 Instruction encoding
|
||||
|
||||
Emitter must satisfy:
|
||||
|
||||
1. little-endian encoding,
|
||||
2. instruction layout `[opcode: u16][immediate]`,
|
||||
3. jump immediates as `u32` offsets relative to function start,
|
||||
4. immediate sizes matching selected Core ISA opcode spec.
|
||||
|
||||
### 6.5 Host-backed mapping obligations
|
||||
|
||||
For host-backed operations:
|
||||
|
||||
1. emit canonical declarations in `SYSC` (`module`, `name`, `version`, `arg_slots`, `ret_slots`),
|
||||
2. deduplicate by canonical identity,
|
||||
3. order by first occurrence,
|
||||
4. emit callsites as `HOSTCALL <sysc_index>` only,
|
||||
5. do not emit raw `SYSCALL` in pre-load artifact form.
|
||||
|
||||
### 6.6 VM-owned intrinsic mapping obligations
|
||||
|
||||
For VM-owned intrinsic operations:
|
||||
|
||||
1. emit VM-owned intrinsic call form (`INTRINSIC <id>`),
|
||||
2. resolve `<id>` from the canonical ISA-scoped intrinsic registry artifact,
|
||||
3. keep intrinsic path distinct from host-binding metadata and host call opcodes,
|
||||
4. and do not emit VM-owned builtin/intrinsic semantics through `SYSC`.
|
||||
|
||||
### 6.7 Internal symbolic-to-index mapping
|
||||
|
||||
Compilers may use internal symbolic references before final index materialization.
|
||||
|
||||
If used, symbolic references must be resolved deterministically to final numeric indices before serialization.
|
||||
|
||||
## 7. Minimum Debug Attribution Contract (v1)
|
||||
|
||||
For v1 backend/runtime diagnostics and conformance support, emitted artifacts must preserve at minimum:
|
||||
|
||||
1. `function_names` entries for all emitted function indices,
|
||||
2. `pc_to_span` entries for each emitted instruction start PC.
|
||||
|
||||
This minimum does not require one universal source-map format.
|
||||
|
||||
## 8. Deterministic Emitter Rejection
|
||||
|
||||
Emitter-side rejection must be deterministic for malformed or inconsistent artifact candidates, including at minimum:
|
||||
|
||||
1. inconsistent function layout bounds,
|
||||
2. unresolved symbolic references at serialization boundary,
|
||||
3. illegal pre-load host call form (`SYSCALL` in pre-load image),
|
||||
4. duplicate `SYSC` canonical identities,
|
||||
5. and declared host ABI shape mismatch detectable at compile target metadata line.
|
||||
|
||||
## 9. Conformance-Facing Baseline
|
||||
|
||||
At minimum, artifact conformance checks should assert:
|
||||
|
||||
1. canonical `SYSC` declarations for admitted host-backed operations,
|
||||
2. deterministic `SYSC` dedup/order,
|
||||
3. pre-load `HOSTCALL` callsites for host-backed paths,
|
||||
4. no host-binding leakage for VM-owned intrinsic/builtin operations,
|
||||
5. minimum debug attribution hooks required by v1,
|
||||
6. deterministic function ordering and code layout invariants.
|
||||
|
||||
## 10. Explicit Deferrals
|
||||
|
||||
The following remain deferred:
|
||||
|
||||
- richer optional debug/source-map formats,
|
||||
- additional PBX section-level contracts beyond current baseline,
|
||||
- and profile-specific binary compatibility policy details beyond current v1 baseline.
|
||||
|
||||
## 11. Non-Goals
|
||||
|
||||
- Repeating full ISA/runtime documentation.
|
||||
- Mandating one byte-for-byte whole-image golden as sole conformance oracle.
|
||||
- Defining loader patching internals already owned elsewhere.
|
||||
|
||||
## 12. Exit Criteria
|
||||
|
||||
This document is healthy when:
|
||||
|
||||
1. artifact mapping obligations are explicit and testable,
|
||||
2. host-backed and VM-owned emission boundaries are explicit,
|
||||
3. deterministic ordering/layout rules are explicit,
|
||||
4. and v1 minimum debug/source attribution contract is explicit.
|
||||
@@ -0,0 +1,155 @@
|
||||
# PBS Runtime Execution and Initialization Specification
|
||||
|
||||
Status: Draft v1 (Temporary)
|
||||
Applies to: runtime startup, entry behavior, module/service initialization, and execution lifecycle of PBS programs after successful load
|
||||
|
||||
## 1. Purpose
|
||||
|
||||
This document defines the PBS-visible runtime entry and execution-lifecycle contract after successful artifact load.
|
||||
|
||||
Its purpose is to keep runtime startup, frame-driven execution, and fatal-failure behavior aligned with:
|
||||
|
||||
- runtime authority,
|
||||
- dynamic semantics,
|
||||
- memory/lifetime guarantees,
|
||||
- and the closed capability-gated host model.
|
||||
|
||||
## 2. Scope
|
||||
|
||||
This document defines:
|
||||
|
||||
- when PBS program execution may begin,
|
||||
- which preconditions must already hold before userland runs,
|
||||
- the runtime execution model of a loaded PBS program instance,
|
||||
- the only normative frame/safepoint boundary in v1,
|
||||
- and which startup or fatal-failure outcomes are PBS-visible.
|
||||
|
||||
This document does not define:
|
||||
|
||||
- loader-side host resolution details,
|
||||
- the full packaging or process model,
|
||||
- scheduler models outside the v1 single-threaded execution contract,
|
||||
- shutdown/finalization APIs or hooks,
|
||||
- or subsystem-specific host resource lifecycles.
|
||||
|
||||
## 3. Authority and Precedence
|
||||
|
||||
Normative precedence:
|
||||
|
||||
1. Runtime authority (`docs/specs/hardware/topics/chapter-2.md`, `chapter-3.md`, `chapter-9.md`, `chapter-12.md`, `chapter-16.md`)
|
||||
2. `1. Language Charter.md`
|
||||
3. `6.2. Host ABI Binding and Loader Resolution Specification.md`
|
||||
4. `9. Dynamic Semantics Specification.md`
|
||||
5. `10. Memory and Lifetime Specification.md`
|
||||
6. This document
|
||||
|
||||
If a rule here conflicts with higher-precedence authorities, it is invalid.
|
||||
|
||||
## 4. Normative Inputs
|
||||
|
||||
This document depends on, at minimum:
|
||||
|
||||
- `1. Language Charter.md`
|
||||
- `6.2. Host ABI Binding and Loader Resolution Specification.md`
|
||||
- `7. Cartridge Manifest and Runtime Capabilities Specification.md`
|
||||
- `9. Dynamic Semantics Specification.md`
|
||||
- `10. Memory and Lifetime Specification.md`
|
||||
|
||||
## 5. Already-Settled Inputs
|
||||
|
||||
The following inputs are already fixed elsewhere and must not be contradicted here:
|
||||
|
||||
- `FRAME_SYNC`-based execution semantics are preserved.
|
||||
- Loader-side host binding resolution and capability gating happen before program execution begins.
|
||||
- A PBS program instance executes single-threaded in v1.
|
||||
- Dynamic semantics are deterministic at the language-observable level.
|
||||
- Any runtime trap aborts PBS program execution and enters the runtime/firmware crash path rather than a userland recovery path.
|
||||
- Service values are canonical module-owned singleton values.
|
||||
- Top-level executable statements are forbidden in PBS source modules.
|
||||
|
||||
## 6. Runtime Entry Preconditions
|
||||
|
||||
PBS userland execution may begin only after all of the following are true:
|
||||
|
||||
1. the program artifact has been accepted by the relevant runtime/load authority,
|
||||
2. capability gating and host-binding resolution required for startup have completed successfully,
|
||||
3. runtime state required to begin frame-driven execution has been established,
|
||||
4. and no prior fatal startup failure has occurred.
|
||||
|
||||
If these preconditions are not satisfied, ordinary PBS userland execution does not begin.
|
||||
|
||||
This document does not define loader-internal sequencing in detail; it only defines that the userland-visible start boundary occurs after successful load- and capability-level admission.
|
||||
|
||||
## 7. Program Instance Model
|
||||
|
||||
Each loaded PBS program executes as one single-threaded program instance in v1.
|
||||
|
||||
Within a program instance:
|
||||
|
||||
- userland execution is not concurrently interleaved by another userland thread,
|
||||
- the dynamic-semantics evaluation order defined in `9. Dynamic Semantics Specification.md` remains authoritative,
|
||||
- and runtime/host activity must not perturb that language-level sequencing.
|
||||
|
||||
PBS source modules do not contribute a user-authored top-level execution phase. Any startup activity that exists outside ordinary function/method execution is runtime-owned unless and until another specification makes a narrower PBS-visible contract explicit.
|
||||
|
||||
## 8. Frame Boundary and Host Work
|
||||
|
||||
`FRAME_SYNC` is the only normative runtime step boundary and the only normative safepoint in PBS v1.
|
||||
|
||||
Consequences:
|
||||
|
||||
- the runtime may use the interval around `FRAME_SYNC` to process host-side demands and internal work,
|
||||
- userland execution must remain semantically ordered as defined by `9. Dynamic Semantics Specification.md`,
|
||||
- and PBS user code cannot rely on any other boundary as a guaranteed safepoint, collection point, or scheduling point.
|
||||
|
||||
Internal runtime work may exist outside `FRAME_SYNC`, but it must remain semantically invisible to PBS userland unless a higher-precedence authority explicitly defines otherwise.
|
||||
|
||||
## 9. Failure and Non-Start Conditions
|
||||
|
||||
PBS distinguishes between two broad classes of failure at this layer:
|
||||
|
||||
1. non-start conditions, where userland never begins because artifact admission, capability checks, or required startup preconditions fail;
|
||||
2. fatal runtime traps, where an already-running PBS program aborts.
|
||||
|
||||
Traps are not recoverable in PBS userland. When a trap occurs:
|
||||
|
||||
- it does not enter `result` flow,
|
||||
- it is not intercepted by `handle`,
|
||||
- and it aborts the PBS program execution path into the runtime/firmware crash path.
|
||||
|
||||
This document does not define a userland-visible trap catalog.
|
||||
|
||||
## 10. Service and Module Initialization Boundaries
|
||||
|
||||
The current v1 baseline is intentionally narrow:
|
||||
|
||||
- service values are canonical singleton values,
|
||||
- top-level executable statements do not exist,
|
||||
- and no userland-visible module-initialization statement phase is defined here.
|
||||
|
||||
The exact timing at which service-owned runtime state becomes initialized and observable remains an open item for this document. Until that is closed, implementations must not infer extra userland-visible initialization hooks beyond what is already guaranteed by higher-precedence specs.
|
||||
|
||||
## 11. TODO
|
||||
|
||||
The following items remain open for later closure:
|
||||
|
||||
- the exact runtime entry contract between successful load and first userland-observable execution,
|
||||
- whether service-owned runtime state has a more precise initialization point than the baseline stated here,
|
||||
- which runtime lifecycle boundaries, if any, are userland-observable beyond `FRAME_SYNC` and trap abort,
|
||||
- and whether shutdown behavior has any PBS-visible contract in v1.
|
||||
|
||||
## 12. Non-Goals
|
||||
|
||||
- Defining OS/process lifecycle outside Prometeu runtime authority.
|
||||
- Reopening the ban on top-level executable statements.
|
||||
- Designing a future async runtime.
|
||||
- Defining userland recovery from trap.
|
||||
|
||||
## 13. Exit Criteria
|
||||
|
||||
This document is ready to move beyond temporary status only when:
|
||||
|
||||
1. runtime startup and non-start boundaries are normatively described,
|
||||
2. service and module runtime lifecycle assumptions are explicit enough to remove the remaining TODO items,
|
||||
3. execution lifecycle boundaries are aligned with dynamic semantics and runtime authority,
|
||||
4. and the document no longer relies on unresolved TODO items for ordinary v1 runtime startup behavior.
|
||||
@@ -0,0 +1,119 @@
|
||||
# PBS Compatibility and Evolution Policy
|
||||
|
||||
Status: Draft v0 (Quality-Gate Baseline)
|
||||
Applies to: practical support states and compatibility publication policy tied to executable quality gates
|
||||
|
||||
## 1. Purpose
|
||||
|
||||
This document defines how PBS support is published at the current project stage.
|
||||
|
||||
The policy is intentionally minimal:
|
||||
|
||||
- publish only support claims that are backed by tests,
|
||||
- use a small support-state model that a solo project can maintain,
|
||||
- and avoid over-specifying compatibility promises before backend/runtime contracts settle.
|
||||
|
||||
## 2. Scope
|
||||
|
||||
This document defines:
|
||||
|
||||
- support-state vocabulary for language lines,
|
||||
- minimum published support table fields,
|
||||
- and how support-state changes must be recorded.
|
||||
|
||||
This document does not define:
|
||||
|
||||
- full deprecation-window math per domain,
|
||||
- one binary/PBX compatibility model,
|
||||
- one release process implementation.
|
||||
|
||||
## 3. Authority and Precedence
|
||||
|
||||
Normative precedence:
|
||||
|
||||
1. `1. Language Charter.md`
|
||||
2. `2. Governance and Versioning.md`
|
||||
3. `13. Conformance Test Specification.md`
|
||||
4. This document
|
||||
|
||||
If a rule here conflicts with higher-precedence authorities, it is invalid.
|
||||
|
||||
## 4. Normative Inputs
|
||||
|
||||
This document depends on:
|
||||
|
||||
- `2. Governance and Versioning.md`
|
||||
- `13. Conformance Test Specification.md`
|
||||
|
||||
## 5. Support States
|
||||
|
||||
PBS currently uses three support states:
|
||||
|
||||
- `unsupported`
|
||||
- `experimental`
|
||||
- `supported`
|
||||
|
||||
Meaning:
|
||||
|
||||
- `unsupported`: no compatibility promise.
|
||||
- `experimental`: active development; behavior may change; tests may exist but are not yet a stable support promise.
|
||||
- `supported`: active compatibility promise for declared scope, backed by required quality gates.
|
||||
|
||||
## 6. Gate-Backed Support Rule
|
||||
|
||||
Support states must map to quality-gate evidence:
|
||||
|
||||
1. `frontend-ready` evidence requires Gate U from `13`.
|
||||
2. `integration-ready` evidence requires Gate U plus Gate I when Gate I applies to the language/backend.
|
||||
3. `supported` state requires maintained evidence for the scope being promised.
|
||||
|
||||
No published `supported` claim may exist without mapped test evidence.
|
||||
Unsupported executable surfaces excluded from a claim (for example `SPAWN`/`YIELD` outside `core-v1`) MUST be stated explicitly in published notes.
|
||||
|
||||
## 7. Minimum Published Support Table
|
||||
|
||||
A published support table must include, at minimum:
|
||||
|
||||
1. language identifier,
|
||||
2. language line/version scope,
|
||||
3. runtime line (or `N/A` when Gate I is not applicable yet),
|
||||
4. Gate U status,
|
||||
5. Gate I status (`pass`, `fail`, or `deferred`),
|
||||
6. support state (`unsupported`, `experimental`, `supported`),
|
||||
7. optional notes.
|
||||
|
||||
No additional matrix dimensions are mandatory at this stage.
|
||||
|
||||
## 8. Support-State Changes
|
||||
|
||||
When support changes, the project must update together:
|
||||
|
||||
1. support table state,
|
||||
2. gate evidence status,
|
||||
3. and a short rationale note when users could be affected.
|
||||
|
||||
This document requires visibility of change, not a specific changelog format.
|
||||
|
||||
## 9. Explicit Deferrals
|
||||
|
||||
The following remain intentionally open:
|
||||
|
||||
- domain-specific promise strength beyond the current gate-backed model,
|
||||
- exact deprecation/removal windows,
|
||||
- PBX/binary compatibility policy details,
|
||||
- mandatory migration tooling triggers.
|
||||
|
||||
## 10. Non-Goals
|
||||
|
||||
- Simulating large-organization compatibility governance.
|
||||
- Freezing domains that are still not implemented.
|
||||
- Requiring one matrix tooling format.
|
||||
|
||||
## 11. Exit Criteria
|
||||
|
||||
This document is in a healthy state when:
|
||||
|
||||
1. every active language line has an explicit support state,
|
||||
2. every `supported` state has mapped gate evidence,
|
||||
3. support changes are reflected in table + evidence + note,
|
||||
4. and no compatibility promise depends on undocumented assumptions.
|
||||
@@ -0,0 +1,188 @@
|
||||
# PBS Standard Library Surface Specification
|
||||
|
||||
Status: Draft v0 (Skeleton)
|
||||
Applies to: normative stdlib-facing API surface, reserved stdlib project spaces, and versioned standard-library contracts exposed to PBS programs
|
||||
|
||||
## 1. Purpose
|
||||
|
||||
This document will define the normative user-facing standard-library surface for PBS.
|
||||
|
||||
## 2. Scope
|
||||
|
||||
This document is intended to define:
|
||||
|
||||
- what counts as part of the PBS stdlib contract,
|
||||
- how stdlib modules are grouped and versioned,
|
||||
- which APIs are normative versus implementation-private,
|
||||
- how VM-owned builtin shells are exposed to user code,
|
||||
- how reserved stdlib project spaces expose user-facing surfaces over host-backed capabilities.
|
||||
|
||||
This document does not define:
|
||||
|
||||
- one physical packaging layout,
|
||||
- registry/publication mechanics,
|
||||
- host loader behavior,
|
||||
- implementation-private helper modules.
|
||||
|
||||
## 3. Authority and Precedence
|
||||
|
||||
Normative precedence:
|
||||
|
||||
1. `5. Manifest, Stdlib, and SDK Resolution Specification.md`
|
||||
2. `8. Stdlib Environment Packaging and Loading Specification.md`
|
||||
3. `6. VM-owned vs Host-backed.md`
|
||||
4. `6.1. Intrinsics and Builtin Types Specification.md`
|
||||
5. `6.2. Host ABI Binding and Loader Resolution Specification.md`
|
||||
6. This document
|
||||
|
||||
If a rule here conflicts with higher-precedence specs, it is invalid.
|
||||
|
||||
## 4. Normative Inputs
|
||||
|
||||
This document depends on, at minimum:
|
||||
|
||||
- `5. Manifest, Stdlib, and SDK Resolution Specification.md`
|
||||
- `6. VM-owned vs Host-backed.md`
|
||||
- `6.1. Intrinsics and Builtin Types Specification.md`
|
||||
- `6.2. Host ABI Binding and Loader Resolution Specification.md`
|
||||
- `8. Stdlib Environment Packaging and Loading Specification.md`
|
||||
|
||||
## 5. Already-Settled Inputs
|
||||
|
||||
The following inputs are already fixed elsewhere and must not be contradicted here:
|
||||
|
||||
- Reserved stdlib project spaces include `@sdk:*` and `@core:*`.
|
||||
- Stdlib interface modules are compile-time-only and loaded as PBS-like modules.
|
||||
- Stdlib interface modules may include service facades whose bodies delegate to reserved host owners; such bodies are source-surface ergonomics and not standalone runtime modules.
|
||||
- User code must import stdlib modules explicitly.
|
||||
- Canonical host identity comes from reserved host-binding metadata, not from source owner spelling.
|
||||
- VM-owned builtin type, builtin constant, and intrinsic surfaces may be exposed through reserved stdlib shells without transferring semantic ownership away from the VM.
|
||||
|
||||
## 6. Initial Section Targets
|
||||
|
||||
At minimum, the completed document should contain normative sections for:
|
||||
|
||||
1. stdlib contract boundaries,
|
||||
2. reserved stdlib project spaces and module families,
|
||||
3. normative versus non-normative API surfaces,
|
||||
4. VM-owned builtin shells exposed to user code,
|
||||
5. host-backed SDK surfaces exposed to user code,
|
||||
6. versioning and deprecation expectations for stdlib APIs.
|
||||
|
||||
## 7. TODO
|
||||
|
||||
The following items remain to be closed in future agenda discussion.
|
||||
|
||||
- Which stdlib modules are mandatory in each active stdlib line.
|
||||
- Which APIs are part of the normative core teaching surface versus optional library growth.
|
||||
- Whether `@core:*` is specified as language-adjacent utility surface or as ordinary stdlib contract.
|
||||
- How stdlib API evolution is documented and conformance-tested.
|
||||
- Whether some interface modules remain toolchain-private and outside user-facing stdlib surface.
|
||||
- Whether builtin shells may appear in `@sdk:*` as well as `@core:*`, or whether `@sdk:*` should remain host-facing only by policy.
|
||||
|
||||
## 8. Non-Goals
|
||||
|
||||
- Replacing the resolution/packaging specs.
|
||||
- Defining all future libraries in one pass.
|
||||
- Hardcoding one distribution format.
|
||||
|
||||
## 9. Exit Criteria
|
||||
|
||||
This document is ready to move beyond skeleton status only when:
|
||||
|
||||
1. the normative user-facing stdlib surface is explicitly bounded,
|
||||
2. reserved project-space API responsibilities are clear,
|
||||
3. VM-owned and host-backed stdlib surfaces are explicitly separated,
|
||||
4. stdlib versioning and deprecation expectations are aligned with compatibility policy,
|
||||
5. the document no longer relies on unresolved `TODO` items for ordinary v1 stdlib contract claims.
|
||||
|
||||
## 10. Reserved Project-Space Responsibilities
|
||||
|
||||
The current stdlib direction distinguishes two user-facing reserved spaces.
|
||||
|
||||
### 10.1 `@core:*`
|
||||
|
||||
`@core:*` is the preferred surface for VM-owned declarations that belong to the
|
||||
language-adjacent semantic platform.
|
||||
|
||||
Examples:
|
||||
|
||||
- builtin type shells,
|
||||
- builtin constants,
|
||||
- and other VM-owned helper declarations that are not host capability surfaces.
|
||||
|
||||
### 10.2 `@sdk:*`
|
||||
|
||||
`@sdk:*` is the preferred surface for host-backed capability-facing APIs.
|
||||
|
||||
Examples:
|
||||
|
||||
- `declare host` surfaces,
|
||||
- capability-facing wrappers over host services,
|
||||
- and domain SDK modules whose execution meaning ultimately depends on host-backed operations.
|
||||
|
||||
Rules:
|
||||
|
||||
- source packaging location is part of the stdlib contract surface,
|
||||
- but ownership remains governed by the VM-owned vs host-backed classification,
|
||||
- and placing a builtin shell in stdlib does not make it host-backed.
|
||||
|
||||
## 11. Builtin Shell Surfaces
|
||||
|
||||
Reserved stdlib modules may expose builtin declarations as compile-time-only
|
||||
shells.
|
||||
|
||||
Rules:
|
||||
|
||||
- stdlib builtin shells may expose `declare builtin type` declarations,
|
||||
- stdlib builtin shells may expose reserved `declare const` declarations carrying `BuiltinConst(...)`,
|
||||
- stdlib builtin shells may expose builtin methods carrying `IntrinsicCall(...)`,
|
||||
- these shells exist for import, name resolution, type checking, and lowering,
|
||||
- and these shells do not provide executable PBS bodies for builtin behavior.
|
||||
|
||||
Stdlib is therefore the delivery surface, not the semantic owner.
|
||||
|
||||
## 12. Host-backed SDK Surfaces
|
||||
|
||||
Reserved stdlib modules may expose host-backed declarations as compile-time-only
|
||||
shells.
|
||||
|
||||
Rules:
|
||||
|
||||
- host-backed stdlib surfaces use `declare host`,
|
||||
- host-backed stdlib modules may also expose `declare service` facades that call internal non-public host owners,
|
||||
- host-backed method signatures carry `Host(...)`,
|
||||
- internal low-level host owners can remain non-public via `mod` barrel visibility while higher-level services are exported with `pub`,
|
||||
- user code may import those host owners through ordinary stdlib module imports,
|
||||
- and lowering continues through canonical host identity, `SYSC`, `HOSTCALL`, loader resolution, and final `SYSCALL`.
|
||||
|
||||
## 13. Stdlib Contract Expectations for Builtin MVP
|
||||
|
||||
For the current builtin MVP, stdlib should be able to expose at least:
|
||||
|
||||
1. a builtin type shell for `Color`,
|
||||
2. a builtin type shell for `Vec2`,
|
||||
3. a builtin type shell for `Pixel`,
|
||||
4. a builtin constant shell for `vec2.zero`,
|
||||
5. and any associated documentation-level or teaching-level module organization needed to make those surfaces discoverable.
|
||||
|
||||
Illustrative example:
|
||||
|
||||
```pbs
|
||||
import { Vec2, ZERO } from @core:math;
|
||||
```
|
||||
|
||||
The imported names are source-visible conveniences.
|
||||
Their canonical runtime-facing identities still come from builtin metadata such
|
||||
as `BuiltinType(name="vec2", version=1)` and
|
||||
`BuiltinConst(target="vec2", name="zero", version=1)`.
|
||||
|
||||
## 14. Deterministic Stdlib Surface Failures
|
||||
|
||||
At minimum, a conforming implementation must reject:
|
||||
|
||||
1. a stdlib builtin shell that attempts to use host-binding metadata for VM-owned intrinsic behavior,
|
||||
2. a stdlib host shell that attempts to use builtin metadata in place of host-binding metadata,
|
||||
3. a user-facing stdlib module that exports executable PBS bodies for builtin semantics,
|
||||
4. a stdlib line that exposes conflicting canonical builtin identities through the same resolved environment,
|
||||
5. a stdlib line that exposes conflicting canonical host identities through the same resolved environment.
|
||||
@@ -0,0 +1,135 @@
|
||||
# PBS Verification and Safety Checks Specification
|
||||
|
||||
Status: Draft v1 (Quality-Gate Baseline)
|
||||
Applies to: test-backed safety gates for backend compiler stages and integration regression safety checks against runtime
|
||||
|
||||
## 1. Purpose
|
||||
|
||||
This document defines the minimum safety/verification quality gates that must be enforced for executable backend pipelines.
|
||||
|
||||
Its purpose is to keep safety measurable and deterministic across:
|
||||
|
||||
- lowering,
|
||||
- optimization,
|
||||
- emission,
|
||||
- and runtime integration boundaries.
|
||||
|
||||
## 2. Scope
|
||||
|
||||
This document defines:
|
||||
|
||||
- mandatory compiler-stage safety checks for executable pipeline stages,
|
||||
- conditional integration safety regression checks against runtime line,
|
||||
- and evidence requirements for safety-related support claims.
|
||||
|
||||
This document does not define:
|
||||
|
||||
- full runtime verifier algorithm internals,
|
||||
- formal proof of all runtime safety properties,
|
||||
- or one mandatory verifier/optimizer architecture.
|
||||
|
||||
## 3. Authority and Precedence
|
||||
|
||||
Normative precedence:
|
||||
|
||||
1. `docs/pbs/specs/2. Governance and Versioning.md`
|
||||
2. `docs/pbs/specs/12. Diagnostics Specification.md`
|
||||
3. `20. IRBackend to IRVM Lowering Specification.md`
|
||||
4. `21. IRVM Optimization Pipeline Specification.md`
|
||||
5. `15. Bytecode and PBX Mapping Specification.md`
|
||||
6. `13. Conformance Test Specification.md`
|
||||
7. This document
|
||||
|
||||
If a rule here conflicts with higher-precedence authorities, it is invalid.
|
||||
|
||||
## 4. Normative Inputs
|
||||
|
||||
This document depends on:
|
||||
|
||||
- `docs/pbs/specs/12. Diagnostics Specification.md`
|
||||
- `13. Conformance Test Specification.md`
|
||||
- `15. Bytecode and PBX Mapping Specification.md`
|
||||
- `20. IRBackend to IRVM Lowering Specification.md`
|
||||
- `21. IRVM Optimization Pipeline Specification.md`
|
||||
|
||||
## 5. Safety Gate Model
|
||||
|
||||
### 5.1 Gate S-U: Compiler-Stage Safety Unit Tests (Required)
|
||||
|
||||
For executable pipelines, S-U must cover stage-level safety checks at minimum:
|
||||
|
||||
1. `LowerToVM` safety checks:
|
||||
- deterministic control-flow lowering checks,
|
||||
- deterministic function-id assignment checks,
|
||||
- mandatory slot/return shape checks,
|
||||
- mandatory callsite form checks.
|
||||
2. `OptimizeIRVM` safety checks:
|
||||
- semantic-preservation regression checks,
|
||||
- deterministic output checks for same input graph,
|
||||
- profile-compatibility checks (`vm_profile`).
|
||||
3. `EmitBytecode` safety checks:
|
||||
- deterministic function/code layout checks,
|
||||
- host-backed pre-load form checks (`HOSTCALL`, `SYSC`),
|
||||
- deterministic rejection for malformed emission candidates,
|
||||
- minimum debug-attribution output checks.
|
||||
4. deterministic diagnostics identity for required rejection surfaces (`code`, `severity`, primary attribution when applicable).
|
||||
|
||||
This gate is mandatory regardless of backend maturity stage.
|
||||
|
||||
### 5.2 Gate S-I: Integration Safety Regression With Runtime (Required for Executable Backends)
|
||||
|
||||
For backends that emit executable artifacts, S-I must cover integration safety at minimum:
|
||||
|
||||
1. valid pre-load host path that loader patches and runtime executes,
|
||||
2. rejection of out-of-bounds `HOSTCALL` index,
|
||||
3. rejection of unused `SYSC` declarations,
|
||||
4. rejection of raw `SYSCALL` in pre-load artifact,
|
||||
5. rejection of host ABI mismatch (`arg_slots`/`ret_slots`),
|
||||
6. rejection of missing capability at load-time,
|
||||
7. valid VM-owned intrinsic path,
|
||||
8. repeatability across declared runtime line.
|
||||
|
||||
When executable artifact emission is not present, S-I may be explicitly `deferred`.
|
||||
|
||||
## 6. Evidence Requirements
|
||||
|
||||
Safety claims must map to gate evidence:
|
||||
|
||||
1. S-U evidence is required for baseline safety posture,
|
||||
2. S-I evidence is required for integration-ready safety claims,
|
||||
3. and published safety-related support claims must remain evidence-backed and current.
|
||||
|
||||
For executable backends, evidence should include deterministic regression fixtures that prove pipeline order and stage-boundary safety behavior.
|
||||
|
||||
## 7. Deterministic Failure Taxonomy Expectations
|
||||
|
||||
Backend safety checks should expose stable rejection families at minimum:
|
||||
|
||||
1. `MARSHAL_FORMAT_*`,
|
||||
2. `MARSHAL_LINKAGE_*`,
|
||||
3. `MARSHAL_VERIFY_PRECHECK_*`.
|
||||
|
||||
This taxonomy complements existing diagnostics contracts and does not replace runtime loader/verifier error surfaces.
|
||||
|
||||
## 8. Explicit Deferrals
|
||||
|
||||
The following are intentionally deferred:
|
||||
|
||||
- full formal verifier obligation catalog,
|
||||
- formal proof frameworks for optimizer equivalence,
|
||||
- and richer standardized source-map formats beyond v1 minimum hooks.
|
||||
|
||||
## 9. Non-Goals
|
||||
|
||||
- Replacing runtime or bytecode authority.
|
||||
- Freezing optimizer/verifier internal architecture prematurely.
|
||||
- Defining performance tooling in a safety specification.
|
||||
|
||||
## 10. Exit Criteria
|
||||
|
||||
This document is healthy when:
|
||||
|
||||
1. required stage-level safety checks are test-backed,
|
||||
2. executable backends have explicit S-I status (`pass`/`fail`/`deferred`),
|
||||
3. integration safety regressions are preserved in tests,
|
||||
4. and safety-related support claims remain evidence-backed.
|
||||
@@ -0,0 +1,174 @@
|
||||
# PBS IRBackend to IRVM Lowering Specification
|
||||
|
||||
Status: Draft v1 (Backend Baseline)
|
||||
Applies to: executable-backend lowering from `IRBackend` handoff into `IRVM`
|
||||
|
||||
## 1. Purpose
|
||||
|
||||
This document defines the normative lowering contract from executable `IRBackend` to `IRVM`.
|
||||
|
||||
Its purpose is to make backend lowering deterministic, reviewable, and compatible with runtime ISA/verification authority.
|
||||
|
||||
## 2. Scope
|
||||
|
||||
This document defines:
|
||||
|
||||
- required backend preconditions before `IRBackend -> IRVM` starts,
|
||||
- `IRVM` structural obligations needed before optimization/emission,
|
||||
- deterministic function-id assignment and control-flow lowering obligations,
|
||||
- callsite lowering obligations across function, host-backed, and VM-owned intrinsic paths,
|
||||
- mandatory compiler-side structural pre-verification before bytecode emission,
|
||||
- and deterministic rejection obligations for backend-originated failures.
|
||||
|
||||
This document does not define:
|
||||
|
||||
- binary PBX layout details,
|
||||
- loader patching internals,
|
||||
- runtime execution internals,
|
||||
- or one mandatory optimizer implementation.
|
||||
|
||||
## 3. Authority and Precedence
|
||||
|
||||
Normative precedence:
|
||||
|
||||
1. Runtime authority (`docs/specs/hardware/topics/chapter-2.md`, `chapter-3.md`, `chapter-9.md`, `chapter-12.md`, `chapter-16.md`)
|
||||
2. Bytecode authority (`docs/specs/bytecode/ISA_CORE.md`)
|
||||
3. `docs/pbs/specs/13. Lowering IRBackend Specification.md`
|
||||
4. This document
|
||||
|
||||
If a rule here conflicts with higher-precedence authorities, it is invalid.
|
||||
|
||||
## 4. Normative Inputs
|
||||
|
||||
This document depends on:
|
||||
|
||||
- `docs/pbs/specs/13. Lowering IRBackend Specification.md`
|
||||
- `docs/pbs/specs/6.1. Intrinsics and Builtin Types Specification.md`
|
||||
- `docs/pbs/specs/6.2. Host ABI Binding and Loader Resolution Specification.md`
|
||||
- `15. Bytecode and PBX Mapping Specification.md`
|
||||
- `21. IRVM Optimization Pipeline Specification.md`
|
||||
|
||||
## 5. Backend Entry Preconditions
|
||||
|
||||
Lowering from `IRBackend` to `IRVM` may start only when:
|
||||
|
||||
1. frontend admission to `IRBackend` is complete for the active slice,
|
||||
2. required callsite categories (`CALL_FUNC`/`CALL_HOST`/`CALL_INTRINSIC`) are available,
|
||||
3. required canonical host/intrinsic metadata is available for admitted callsites,
|
||||
4. dependency-scoped fail-fast exclusions have already been applied at the `IRBackend` boundary,
|
||||
5. frontend-declared qualified `EntrypointRef` is present:
|
||||
- `IRBackend.entryPointCallableName` is non-blank,
|
||||
- `IRBackend.entryPointModuleId` is non-none,
|
||||
6. and target `vm_profile` is selected deterministically.
|
||||
|
||||
## 6. IRVM Model Obligations
|
||||
|
||||
`IRVM` v1 is a quasi-ISA backend form:
|
||||
|
||||
1. it may contain Core ISA ops and internal extension ops (`IRVM_EXT`),
|
||||
2. each `IRVM_EXT` must declare structural metadata equivalent to opcode-spec needs:
|
||||
- `pops`,
|
||||
- `pushes`,
|
||||
- `is_branch`,
|
||||
- `is_terminator`,
|
||||
3. and `IRVM_EXT` must be eliminable before bytecode emission.
|
||||
|
||||
`IRVM` must preserve, per function:
|
||||
|
||||
1. `param_slots`,
|
||||
2. `local_slots`,
|
||||
3. `return_slots`,
|
||||
4. `max_stack_slots`,
|
||||
5. function entry mapping and deterministic identity.
|
||||
|
||||
## 7. Control-Flow Lowering Obligations
|
||||
|
||||
Control-flow lowering must satisfy:
|
||||
|
||||
1. symbolic labels are allowed internally in lowering,
|
||||
2. final jump immediates must be resolved to `u32` offsets relative to function start before emission,
|
||||
3. jump targets must be instruction-boundary-valid within function ranges,
|
||||
4. and reachable fallthrough beyond function end without terminator is rejected.
|
||||
|
||||
## 8. Deterministic Function-ID Assignment
|
||||
|
||||
Function indexing must be deterministic:
|
||||
|
||||
1. entrypoint callable is selected by exact qualified match against `EntrypointRef(entryPointModuleId, entryPointCallableName)`,
|
||||
2. selected entrypoint function id is `0`,
|
||||
3. remaining functions are ordered by `(moduleId -> modulePool canonical key, callable_name, source_start)`,
|
||||
4. name-only entrypoint fallback is forbidden,
|
||||
5. and identical admitted input graphs must produce identical function-id assignments.
|
||||
|
||||
## 9. Callsite Lowering Obligations
|
||||
|
||||
### 9.1 Function calls
|
||||
|
||||
`CALL_FUNC` lowers to `CALL <func_id>` with valid index and arity-consistent signature contracts.
|
||||
|
||||
### 9.2 Host-backed calls
|
||||
|
||||
`CALL_HOST` lowers to pre-load `HOSTCALL <sysc_index>`, not raw `SYSCALL`.
|
||||
|
||||
### 9.3 VM-owned intrinsic calls
|
||||
|
||||
`CALL_INTRINSIC` lowers to VM-owned intrinsic path and must remain distinct from host-binding paths.
|
||||
|
||||
Final intrinsic id resolution rules:
|
||||
|
||||
1. compiler must resolve final intrinsic ids from the canonical ISA-scoped intrinsic registry artifact,
|
||||
2. compiler-local hardcoded maps or runtime-source parsing must not be authoritative identity sources,
|
||||
3. runtime and compiler consumers must validate parity against the same canonical artifact in strict CI mode.
|
||||
|
||||
### 9.4 Closure and coroutine constraints (v1)
|
||||
|
||||
1. closure calls with unknown static callee are rejected in v1,
|
||||
2. `SPAWN` and `YIELD` are outside the executable `core-v1` claim scope and MUST be rejected as unsupported forms in v1 backend admission,
|
||||
3. `SPAWN` argument-count and `YIELD` stack-shape invariants remain reserved for a future profile that explicitly admits these opcodes,
|
||||
4. and any profile that admits `SPAWN`/`YIELD` MUST publish dedicated conformance evidence before claiming support.
|
||||
|
||||
## 10. Mandatory Compiler-Side Pre-Verification
|
||||
|
||||
Before bytecode emission, backend must run structural pre-verification on lowered `IRVM` (after resolving to Core-ISA-compatible form), covering at minimum:
|
||||
|
||||
1. jump target validity,
|
||||
2. stack-depth join consistency,
|
||||
3. underflow/overflow against declared limits,
|
||||
4. return-shape consistency,
|
||||
5. function-id validity,
|
||||
6. callsite arity consistency,
|
||||
7. and structural validity of host/intrinsic call forms.
|
||||
|
||||
This pre-verification does not replace runtime verifier authority.
|
||||
|
||||
## 11. Deterministic Rejection Policy
|
||||
|
||||
When backend lowering fails at this boundary:
|
||||
|
||||
1. rejection must be deterministic,
|
||||
2. diagnostics identity and phase must remain stable,
|
||||
3. and source attribution must be preserved whenever the failure remains source-attributable and user-actionable.
|
||||
|
||||
## 12. Explicit Deferrals
|
||||
|
||||
The following are intentionally deferred:
|
||||
|
||||
- optimizer pass catalog and tuning policy,
|
||||
- richer internal IR analysis models beyond v1 obligations,
|
||||
- advanced closure/lifetime optimizations beyond v1 constraints,
|
||||
- and executable support for `SPAWN`/`YIELD` in `core-v1`.
|
||||
|
||||
## 13. Non-Goals
|
||||
|
||||
- Defining one in-memory IR implementation graph.
|
||||
- Redefining runtime verifier/loader internals.
|
||||
- Defining PBX binary chunk policy in this document.
|
||||
|
||||
## 14. Exit Criteria
|
||||
|
||||
This document is healthy when:
|
||||
|
||||
1. `IRBackend -> IRVM` obligations are explicit and testable,
|
||||
2. deterministic function/call/control-flow lowering rules are explicit,
|
||||
3. mandatory pre-verification boundary is explicit,
|
||||
4. and scope boundaries with optimization/emission specs are explicit.
|
||||
@@ -0,0 +1,124 @@
|
||||
# PBS IRVM Optimization Pipeline Specification
|
||||
|
||||
Status: Draft v1 (Pipeline Baseline)
|
||||
Applies to: placement and invariants of the `OptimizeIRVM` stage between lowering and bytecode emission
|
||||
|
||||
## 1. Purpose
|
||||
|
||||
This document defines the normative placement and safety invariants of the `OptimizeIRVM` stage.
|
||||
|
||||
Its purpose is to allow optimization in the backend pipeline without transferring semantic optimization responsibility to runtime.
|
||||
|
||||
## 2. Scope
|
||||
|
||||
This document defines:
|
||||
|
||||
- canonical stage placement for `OptimizeIRVM`,
|
||||
- input/output contracts of optimization stage boundaries,
|
||||
- semantic-preservation invariants for optimization passes,
|
||||
- profile-compatibility obligations (`vm_profile`) across optimization and emission,
|
||||
- and minimum validation expectations for optimization-stage regressions.
|
||||
|
||||
This document does not define:
|
||||
|
||||
- a mandatory list of optimization passes,
|
||||
- pass scheduling heuristics,
|
||||
- or runtime dynamic optimization/JIT policies.
|
||||
|
||||
## 3. Authority and Precedence
|
||||
|
||||
Normative precedence:
|
||||
|
||||
1. Runtime authority (`docs/specs/hardware/topics/chapter-2.md`, `chapter-3.md`, `chapter-9.md`, `chapter-12.md`, `chapter-16.md`)
|
||||
2. Bytecode authority (`docs/specs/bytecode/ISA_CORE.md`)
|
||||
3. `20. IRBackend to IRVM Lowering Specification.md`
|
||||
4. `15. Bytecode and PBX Mapping Specification.md`
|
||||
5. This document
|
||||
|
||||
If a rule here conflicts with higher-precedence authorities, it is invalid.
|
||||
|
||||
## 4. Normative Inputs
|
||||
|
||||
This document depends on:
|
||||
|
||||
- `20. IRBackend to IRVM Lowering Specification.md`
|
||||
- `15. Bytecode and PBX Mapping Specification.md`
|
||||
- `19. Verification and Safety Checks Specification.md`
|
||||
- `docs/pbs/decisions/IRVM Optimization Stage Placement Decision.md`
|
||||
|
||||
## 5. Canonical Backend Pipeline Order
|
||||
|
||||
For executable backends, the canonical order is:
|
||||
|
||||
1. `LowerToVM`: `IRBackend -> IRVM`,
|
||||
2. `OptimizeIRVM`: `IRVM -> IRVM` optimized,
|
||||
3. `EmitBytecode`: optimized `IRVM -> BytecodeModule` pre-load artifact.
|
||||
|
||||
`OptimizeIRVM` must not be skipped in a pipeline that claims this profile unless explicitly configured as a no-op stage that still preserves contracts.
|
||||
|
||||
## 6. Input and Output Contracts
|
||||
|
||||
### 6.1 Input contract
|
||||
|
||||
`OptimizeIRVM` input must:
|
||||
|
||||
1. satisfy lowering obligations from `20`,
|
||||
2. carry selected `vm_profile`,
|
||||
3. and remain structurally valid for optimizer analyses.
|
||||
|
||||
### 6.2 Output contract
|
||||
|
||||
`OptimizeIRVM` output must:
|
||||
|
||||
1. be semantically equivalent to input under the selected `vm_profile`,
|
||||
2. preserve callable/slot/return contracts,
|
||||
3. preserve deterministic mapping behavior required by emission,
|
||||
4. and be valid for bytecode emission and subsequent runtime verification.
|
||||
|
||||
## 7. Optimization Invariants
|
||||
|
||||
Optimization passes must satisfy all of:
|
||||
|
||||
1. semantic preservation of observable program behavior,
|
||||
2. determinism for the same admitted input graph and selected profile,
|
||||
3. profile compatibility (no introduction of out-of-profile executable opcode forms),
|
||||
4. preservation of host-backed vs VM-owned call-boundary classification,
|
||||
5. and preservation of diagnostics/source-attribution hooks required at v1 minimum.
|
||||
|
||||
## 8. Runtime Responsibility Boundary
|
||||
|
||||
1. Semantic/structural program optimization belongs to compile-time backend stages.
|
||||
2. Runtime remains responsible for load, patch, verify, and execute responsibilities.
|
||||
3. Runtime-internal micro-optimizations are allowed only when they do not alter bytecode-observable semantics or contract behavior.
|
||||
|
||||
## 9. Validation Expectations
|
||||
|
||||
At minimum, optimization-stage validation must include:
|
||||
|
||||
1. equivalence-oriented regression fixtures across optimized vs non-optimized pipeline outputs,
|
||||
2. preservation of known negative loader/verifier rejection behavior,
|
||||
3. and deterministic reproduction of artifact-level invariants required by `15`.
|
||||
|
||||
## 10. Explicit Deferrals
|
||||
|
||||
The following are intentionally deferred:
|
||||
|
||||
- target-specific optimization profitability models,
|
||||
- advanced interprocedural pipelines beyond v1 baseline,
|
||||
- and formal equivalence proof frameworks.
|
||||
|
||||
## 11. Non-Goals
|
||||
|
||||
- Defining runtime JIT or adaptive execution.
|
||||
- Replacing loader/verifier contracts.
|
||||
- Mandating one optimizer architecture or pass framework.
|
||||
|
||||
## 12. Exit Criteria
|
||||
|
||||
This document is healthy when:
|
||||
|
||||
1. stage placement is explicit and implemented in pipeline order,
|
||||
2. optimization invariants are explicit and test-backed,
|
||||
3. backend/runtime responsibility boundary is explicit,
|
||||
4. and integration safety evidence references this stage concretely.
|
||||
|
||||
@@ -0,0 +1,113 @@
|
||||
# Backend Spec-to-Test Conformance Matrix
|
||||
|
||||
Status: Draft v1 (Traceability Baseline)
|
||||
Applies to: backend conformance traceability for `IRBackend -> IRVM -> OptimizeIRVM -> EmitBytecode`
|
||||
|
||||
Last Updated: 2026-03-09
|
||||
|
||||
## 1. Purpose
|
||||
|
||||
This matrix maps each normative backend MUST from:
|
||||
|
||||
1. `docs/general/specs/19. Verification and Safety Checks Specification.md`
|
||||
2. `docs/general/specs/20. IRBackend to IRVM Lowering Specification.md`
|
||||
3. `docs/general/specs/21. IRVM Optimization Pipeline Specification.md`
|
||||
4. `docs/pbs/specs/13. Lowering IRBackend Specification.md` (Section 12 addendum only)
|
||||
|
||||
to concrete positive/negative test evidence and current status.
|
||||
|
||||
## 2. Status Legend
|
||||
|
||||
- `pass`: requirement has explicit positive and/or negative evidence and currently passes.
|
||||
- `partial`: requirement is partially covered; evidence exists but scope is incomplete.
|
||||
- `missing`: no concrete automated evidence yet.
|
||||
- `deferred`: intentionally out of current executable scope.
|
||||
|
||||
## 3. Normative Matrix
|
||||
|
||||
| Requirement ID | Source MUST | Positive Tests | Negative Tests | Status | Notes |
|
||||
| --- | --- | --- | --- | --- | --- |
|
||||
| G19-5.1.1 | Gate S-U MUST cover LowerToVM stage safety checks. | `LowerToIRVMServiceTest#lowerMustAssignEntrypointIdZeroAndSortRemainingDeterministically`; `LowerToIRVMServiceTest#lowerMustResolveJumpTargetsFromLabels` | `LowerToIRVMServiceTest#lowerMustRejectMissingCallee`; `LowerToIRVMServiceTest#lowerMustRejectMissingJumpTargetLabel`; `LowerToIRVMServiceTest#lowerMustRejectUnterminatedFunction` | pass | Includes deterministic id/callsite/control-flow checks. |
|
||||
| G19-5.1.2 | Gate S-U MUST cover OptimizeIRVM stage safety checks. | `OptimizeIRVMServiceTest#optimizeDefaultPassesMustRemoveUnreachableInstructions`; `OptimizeIRVMServiceTest#simplifyJumpToNextPcPassMustRemoveDirectFallthroughJump` | `OptimizeIRVMServiceTest#optimizeMustRejectPassThatMutatesVmProfile` | pass | Determinism also covered by `BackendSafetyGateSUTest#optimizeStageMustBeDeterministicForSameInputProgram`. |
|
||||
| G19-5.1.3 | Gate S-U MUST cover EmitBytecode stage safety checks. | `EmitBytecodePipelineStageTest#runMustEmitBytecodeWhenPreconditionsAreSatisfied`; `BytecodeEmitterTest#emitMustDeduplicateSyscallsByCanonicalIdentityAndPreserveFirstOccurrenceOrder` | `EmitBytecodePipelineStageTest#runMustFailWhenInternalOpcodesRemain`; `BytecodeEmitterTest#emitMustRejectRawSyscallInPreloadPlan` | pass | Covers layout, host-backed preload form and deterministic rejection. |
|
||||
| G19-5.1.4 | Gate S-U MUST cover deterministic diagnostics identity for required rejection surfaces. | `BackendSafetyGateSUTest#lowerStageMustExposeDeterministicFailureCodeForSameInvalidInput` | `BackendSafetyGateSUTest#emitStageMustExposeMarshalingLinkageFailureDeterministically` | pass | Uses stable `code` and `phase`. |
|
||||
| G19-5.2.1 | Gate S-I MUST cover valid pre-load host path. | `BackendGateIIntegrationTest#gateI_validHostcallPath` | N/A | pass | Runtime-backed and local adapter paths covered. |
|
||||
| G19-5.2.2 | Gate S-I MUST reject out-of-bounds HOSTCALL index. | N/A | `BackendGateIIntegrationTest#gateI_rejectHostcallOutOfBounds` | pass | |
|
||||
| G19-5.2.3 | Gate S-I MUST reject unused SYSC declarations. | N/A | `BackendGateIIntegrationTest#gateI_rejectUnusedSyscallDeclaration` | pass | |
|
||||
| G19-5.2.4 | Gate S-I MUST reject raw SYSCALL in pre-load artifact. | N/A | `BackendGateIIntegrationTest#gateI_rejectRawSyscallInPreloadArtifact` | pass | |
|
||||
| G19-5.2.5 | Gate S-I MUST reject host ABI mismatch. | N/A | `BackendGateIIntegrationTest#gateI_rejectHostAbiMismatchAtEmitTime` | pass | |
|
||||
| G19-5.2.6 | Gate S-I MUST reject missing capability at load-time. | N/A | `BackendGateIIntegrationTest#gateI_rejectMissingCapability` | pass | |
|
||||
| G19-5.2.7 | Gate S-I MUST cover valid VM-owned intrinsic path. | `BackendGateIIntegrationTest#gateI_validIntrinsicPath` | N/A | pass | |
|
||||
| G19-5.2.8 | Gate S-I MUST cover repeatability across runtime line. | `RuntimeBackedCompatibilityAdapterTest#checkMustPassInStrictModeWhenRuntimeCommandIsValid`; `RuntimeBackedCompatibilityAdapterTest#checkMustBeRepeatableAcrossDeclaredRuntimeLinesInStrictMode` | `RuntimeBackedCompatibilityAdapterTest#checkMustFailInStrictModeWhenRuntimeCommandIsUnavailable` | pass | Multi-line repeatability is asserted with strict runtime-backed checks over distinct declared runtime lines. |
|
||||
| G20-6.2 | `IRVM_EXT` MUST declare structural metadata (`pops/pushes/is_branch/is_terminator`). | `IRVMValidatorTest#validateMustApplyStructuralMetadataForCustomInternalExtension`; `IRVMValidatorTest#validateMustRejectCustomInternalExtensionWhenStructuralMetadataUnderflowsStack`; `IRVMOp` record contract (`pops/pushes/branch/terminator/internal`) | N/A | pass | Dedicated extension fixtures now assert structural metadata is consumed by validation behavior. |
|
||||
| G20-6.3 | `IRVM_EXT` MUST be eliminable before bytecode emission. | `OptimizeIRVMServiceTest#optimizeDefaultPassesMustEliminateUnreachableInternalExtensionBeforeEmission` | `EmitBytecodePipelineStageTest#runMustFailWhenInternalOpcodesRemain`; `EmitBytecodePipelineStageTest#runMustFailWhenInternalOpcodesRemainEvenWithNonEmptyEmissionPlan`; `IRVMValidatorTest#validateMustRejectInternalOpcodeWhenConfigured` | pass | Optimizer elimination path and emit-stage hard rejection path are both covered. |
|
||||
| G20-6.4 | IRVM MUST preserve per-function slot and identity headers. | `IRVMProgramTest#constructorMustRejectModuleAndEmissionPlanMismatch` | `IRVMProgramTest#constructorMustRejectModuleAndEmissionPlanMismatch` | pass | Header mismatch is rejected deterministically. |
|
||||
| G20-7.2 | Jump immediates MUST resolve to u32 function-relative offsets before emission. | `LowerToIRVMServiceTest#lowerMustResolveJumpTargetsFromLabels`; `BytecodeEmitterTest#emitMustEncodeJumpOpcodesWithU32Immediate` | `LowerToIRVMServiceTest#lowerMustRejectMissingJumpTargetLabel` | pass | |
|
||||
| G20-7.3 | Jump targets MUST be instruction-boundary valid. | N/A | `IRVMValidatorTest#validateMustRejectInvalidJumpTarget` | pass | |
|
||||
| G20-7.4 | Reachable fallthrough beyond function end MUST be rejected. | N/A | `LowerToIRVMServiceTest#lowerMustRejectUnterminatedFunction`; `IRVMValidatorTest#validateMustRejectRetShapeMismatch` | pass | |
|
||||
| G20-8.1 | Qualified entrypoint function id MUST be 0. | `LowerToIRVMServiceTest#lowerMustAssignEntrypointIdZeroAndSortRemainingDeterministically`; `LowerToIRVMServiceTest#lowerMustUseQualifiedEntrypointIdentityWhenProvided` | `LowerToIRVMServiceTest#lowerMustRejectWhenEntrypointDeclarationIsMissing`; `LowerToIRVMServiceTest#lowerMustRejectMissingQualifiedEntrypointIdentity`; `LowerToIRVMServiceTest#lowerMustRejectWhenEntrypointIsAmbiguous` | pass | Entrypoint is resolved strictly by `EntrypointRef(entryPointModuleId, entryPointCallableName)`. |
|
||||
| G20-8.2 | Remaining function ids MUST follow deterministic moduleId-only ordering. | `LowerToIRVMServiceTest#lowerMustAssignEntrypointIdZeroAndSortRemainingDeterministically`; `LowerToIRVMServiceTest#lowerMustUseModulePoolCanonicalIdentityForNonEntrypointOrdering` | N/A | pass | Ordering key is `(moduleId -> modulePool canonical key, callable_name, source_start)`. |
|
||||
| G20-8.3 | Same admitted input graph MUST produce identical function-id assignment. | `BackendSafetyGateSUTest#fullPipelineMustProduceDeterministicBytecodeForSameInput` | N/A | pass | Artifact determinism implies stable function mapping for fixed input. |
|
||||
| G20-9.3 | `CALL_INTRINSIC` MUST remain distinct from host-binding path and resolve ids from canonical registry artifact. | `LowerToIRVMServiceTest#lowerMustMapHostAndIntrinsicCallsites`; `BackendGateIIntegrationTest#gateI_validIntrinsicPath`; `IRVMIntrinsicRegistryParityTest#registryResourceMustExposeExpectedCanonicalEntries`; `IRVMIntrinsicRegistryParityTest#registryMustStayInSyncWithRuntimeBuiltinsTable` | `IRVMValidatorTest#validateProgramMustRejectIntrinsicWithoutSignatureMetadata` | pass | Distinct operation kinds and canonical registry parity checks are enforced. |
|
||||
| G20-9.4.2 | `SPAWN` arg count MUST match callee `param_slots`. | `BackendClaimScopeSpecTest#loweringSpecMustDeclareSpawnYieldOutsideCoreV1ClaimScope`; `BackendClaimScopeSpecTest#matrixMustMarkSpawnYieldRowsAsClaimRescoped`; `BackendClaimScopeSpecTest#decisionRecordMustExistForSpawnYieldClaimRescope` | N/A | pass | Requirement is out of scope for core-v1 claim by accepted Track B rescope decision; future profile must reintroduce executable coverage with dedicated tests. |
|
||||
| G20-9.4.3 | `YIELD` with non-empty operand stack MUST be rejected. | `BackendClaimScopeSpecTest#loweringSpecMustDeclareSpawnYieldOutsideCoreV1ClaimScope`; `BackendClaimScopeSpecTest#matrixMustMarkSpawnYieldRowsAsClaimRescoped`; `BackendClaimScopeSpecTest#decisionRecordMustExistForSpawnYieldClaimRescope` | N/A | pass | Requirement is out of scope for core-v1 claim by accepted Track B rescope decision; future profile must reintroduce executable coverage with dedicated tests. |
|
||||
| G20-10 | Backend MUST run structural pre-verification before emission. | `LowerToIRVMService` + `OptimizeIRVMService` validator invocation; `LowerToIRVMServiceTest` positive fixtures | `IRVMValidatorTest#validateMustRejectStackMismatchJoin`; `IRVMValidatorTest#validateProgramMustApplyHostcallStackEffectsFromMetadata` | pass | Pre-verification checks jump/stack/ret/callsite constraints. |
|
||||
| G20-11.1 | Lowering rejection MUST be deterministic. | `BackendSafetyGateSUTest#lowerStageMustExposeDeterministicFailureCodeForSameInvalidInput` | same | pass | |
|
||||
| G20-11.2 | Diagnostics identity/phase MUST remain stable. | `BackendSafetyGateSUTest#lowerStageMustExposeDeterministicFailureCodeForSameInvalidInput` | `BackendSafetyGateSUTest#emitStageMustExposeMarshalingLinkageFailureDeterministically` | pass | Stable rejection families are exercised. |
|
||||
| G20-11.3 | Source attribution MUST be preserved when source-actionable. | `LowerToIRVMPipelineStageTest#runMustAttachSourceAttributionForLoweringFailure`; `LowerToIRVMServiceTest#lowerMustMapHostAndIntrinsicCallsites` | `LowerToIRVMServiceTest#lowerMustRejectMissingCallee` | pass | Stage-level failure now carries explicit `file/start/end` attribution for lowering errors. |
|
||||
| G21-5 | `OptimizeIRVM` MUST NOT be skipped in canonical pipeline order. | `BuilderPipelineServiceOrderTest#canonicalOrderMustContainOptimizeBetweenLowerAndEmit` | N/A | pass | Canonical stage order is enforced. |
|
||||
| G21-6.1 | Optimize input MUST satisfy lowering obligations/profile/structural validity. | `OptimizeIRVMPipelineStageTest#runMustAcceptSupportedNonDefaultVmProfile` | `OptimizeIRVMPipelineStageTest#runMustRejectUnsupportedVmProfile` | pass | Input validation occurs before pass execution. |
|
||||
| G21-6.2 | Optimize output MUST preserve semantics/contracts and remain emission-valid. | `OptimizeIRVMEquivalenceHarnessTest#optimizeOnOffMustPreserveObservableTraceForLoweredHostIntrinsicFixture`; `OptimizeIRVMEquivalenceHarnessTest#optimizeOnOffMustPreserveObservableTraceForConditionalJoinFixture`; `OptimizeIRVMEquivalenceHarnessTest#optimizeOnOffMustPreserveObservableTraceForSimpleLoopFixture`; `OptimizeIRVMEquivalenceHarnessTest#optimizeOnOffMustPreserveObservableTraceForLinearCallFixture`; `EmitBytecodePipelineStageTest#runMustEmitBytecodeWhenPreconditionsAreSatisfied` | `OptimizeIRVMServiceTest#optimizeMustRejectPassThatMutatesVmProfile` | pass | Equivalence harness now validates on/off semantics and emission validity over CFG corpus with host/intrinsic paths. |
|
||||
| G21-7.1 | Optimization passes MUST preserve observable semantics. | `OptimizeIRVMEquivalenceHarnessTest#optimizeOnOffMustPreserveObservableTraceForConditionalJoinFixture`; `OptimizeIRVMEquivalenceHarnessTest#optimizeOnOffMustPreserveObservableTraceForSimpleLoopFixture`; `OptimizeIRVMEquivalenceHarnessTest#optimizeOnOffMustPreserveObservableTraceForLinearCallFixture` | N/A | pass | Observable trace equivalence is asserted across branching, loops, and call graphs. |
|
||||
| G21-7.2 | Optimization passes MUST be deterministic for same input/profile. | `BackendSafetyGateSUTest#optimizeStageMustBeDeterministicForSameInputProgram` | N/A | pass | |
|
||||
| G21-7.3 | Optimization passes MUST preserve profile compatibility. | `OptimizeIRVMPipelineStageTest#runMustAcceptSupportedNonDefaultVmProfile` | `OptimizeIRVMServiceTest#optimizeMustRejectPassThatMutatesVmProfile` | pass | |
|
||||
| G21-7.4 | Optimization passes MUST preserve host-vs-intrinsic boundary classification. | `LowerToIRVMServiceTest#lowerMustMapHostAndIntrinsicCallsites`; `BackendGateIIntegrationTest#gateI_validIntrinsicPath` | N/A | pass | No pass rewrites operation kind domains. |
|
||||
| G21-7.5 | Optimization passes MUST preserve diagnostics/source-attribution hooks. | `OptimizeIRVMServiceTest#unreachableInstructionEliminationPassMustPreserveJumpSpanWhenTargetIsRemapped`; `OptimizeIRVMServiceTest#normalizeRedundantJumpTargetsPassMustPreserveJumpSpanAfterRewrite`; `OptimizeIRVMServiceTest#simplifyJumpToNextPcPassMustPreserveSpanOnSurvivingOperation`; `LowerToIRVMServiceTest#lowerMustMapHostAndIntrinsicCallsites` | N/A | pass | Dedicated optimizer regressions now assert span/source-hook preservation for rewrite and elimination paths. |
|
||||
| G21-9.1 | Validation MUST include optimized-vs-non-optimized equivalence fixtures. | `OptimizeIRVMEquivalenceHarnessTest#optimizeOnOffMustPreserveObservableTraceForLoweredHostIntrinsicFixture`; `OptimizeIRVMEquivalenceHarnessTest#optimizeOnOffMustPreserveObservableTraceForConditionalJoinFixture`; `OptimizeIRVMEquivalenceHarnessTest#optimizeOnOffMustPreserveObservableTraceForSimpleLoopFixture`; `OptimizeIRVMEquivalenceHarnessTest#optimizeOnOffMustPreserveObservableTraceForLinearCallFixture` | N/A | pass | Dedicated opt on/off harness with reusable interpreter and deterministic trace assertions is in place. |
|
||||
| G21-9.2 | Validation MUST preserve known negative loader/verifier behavior. | `BackendSafetyGateSUTest#emitStageMustExposeMarshalingLinkageFailureDeterministically`; `BackendGateIIntegrationTest` rejection suite | N/A | pass | |
|
||||
| G21-9.3 | Validation MUST preserve deterministic artifact-level invariants. | `BackendSafetyGateSUTest#fullPipelineMustProduceDeterministicBytecodeForSameInput`; `BytecodeEmitterTest#emitMustRemainDeterministicAfterInterning` | N/A | pass | |
|
||||
| PBS13-12.0 | Executable backend handoff MUST satisfy addendum obligations. | `IRBackendExecutableContractTest` suite | N/A | pass | Row group `PBS13-12.x` details each obligation. |
|
||||
| PBS13-12.1.1 | Callable identity MUST be preserved at handoff. | `IRBackendExecutableContractTest#aggregatorMustPreserveExecutableFunctionOrderDeterministically` | N/A | pass | |
|
||||
| PBS13-12.1.2 | Observable callable signature MUST be preserved at handoff. | `IRBackendExecutableContractTest#functionContractMustRejectInvalidSlotAndSpanBounds` | N/A | pass | |
|
||||
| PBS13-12.1.3 | Callable category MUST be preserved at handoff. | `PbsFrontendCompilerTest#shouldLowerExecutableFunctionsWithCallsiteCategories` | N/A | pass | |
|
||||
| PBS13-12.1.4 | Source anchor (`fileId/start/end`) MUST be preserved. | `IRBackendExecutableContractTest#aggregatorMustPreserveExecutableSourceAttribution`; `IRBackendExecutableContractTest#functionContractMustRejectInvalidSlotAndSpanBounds` | N/A | pass | Handoff preserves function and instruction source anchors after aggregation/reindexing. |
|
||||
| PBS13-12.1.5 | Executable body representation MUST be backend-lowerable. | `LowerToIRVMServiceTest#lowerMustMapHostAndIntrinsicCallsites` | `LowerToIRVMServiceTest#lowerMustRejectMissingCallee` | pass | |
|
||||
| PBS13-12.2.1 | Callsite MUST be exactly one of `CALL_FUNC/CALL_HOST/CALL_INTRINSIC`. | `IRBackendExecutableContractTest#callInstructionMustRequireCategorySpecificMetadata` | `IRBackendExecutableContractTest#instructionContractMustRejectMixedMetadataKinds` | pass | |
|
||||
| PBS13-12.2.2 | Backend MUST NOT infer callsite category by textual heuristics. | `PbsFrontendCompilerTest#shouldClassifyCallableCallEvenWhenNameLooksHostLike`; `PbsFrontendCompilerTest#shouldNotInferCallableCategoryFromMemberCallText`; `PbsFrontendCompilerTest#shouldRejectAmbiguousCallableIdentityInsteadOfGuessingByText`; `IRBackendExecutableContractTest#callInstructionMustRequireCategorySpecificMetadata` | N/A | pass | Dedicated regression fixtures now cover textually misleading names and ambiguous callable identity without category guessing. |
|
||||
| PBS13-12.3.1 | Host-backed callsite MUST preserve canonical `(module,name,version)`. | `LowerToIRVMServiceTest#lowerMustMapHostAndIntrinsicCallsites` | N/A | pass | |
|
||||
| PBS13-12.3.2 | Host ABI shape (`arg_slots`,`ret_slots`) MUST be preserved when available. | `LowerToIRVMServiceTest#lowerMustMapHostAndIntrinsicCallsites` | `BytecodeEmitterTest#emitMustRejectAbiMismatch` | pass | |
|
||||
| PBS13-12.4.1 | Intrinsic callsite MUST preserve canonical intrinsic identity. | `IRBackendExecutableContractTest#aggregatorMustReindexIntrinsicsToBuildGlobalPool` | N/A | pass | |
|
||||
| PBS13-12.4.2 | VM-owned intrinsics MUST NOT be reclassified as host bindings. | `LowerToIRVMServiceTest#lowerMustMapHostAndIntrinsicCallsites`; `BackendGateIIntegrationTest#gateI_validIntrinsicPath` | N/A | pass | |
|
||||
| PBS13-12.5 | `requiredCapabilities` MUST be deterministic for same admitted graph. | `PbsFrontendCompilerTest#shouldExtractReservedMetadataForInterfaceModuleSurfaces` | `PbsFrontendCompilerTest#shouldRejectHostBindingCapabilityNotDeclaredInStrictContext`; `PBSFrontendPhaseServiceTest#shouldBlockDependentModulesWhenUpstreamModuleFailsHostAdmission` | pass | Deterministic derivation + strict admission path. |
|
||||
|
||||
## 4. PR-05.0.X Identity Foundation Coverage
|
||||
|
||||
| PR Item | Scope | Evidence | Status |
|
||||
| --- | --- | --- | --- |
|
||||
| PR-05.0.1 | Shared `NameTable` context across frontend phases | `NameTableTest`; `PBSFrontendPhaseServiceTest` multi-module fixtures | pass |
|
||||
| PR-05.0.2 | `ModuleId` dense table and module wiring | `ModuleTableTest`; `PBSFrontendPhaseServiceTest#shouldBlockDependentModulesTransitivelyWhenUpstreamModuleFailsLinking` | pass |
|
||||
| PR-05.0.3 | Typed `CallableId`/`IntrinsicId` in executable contract | `IRBackendExecutableContractTest`; `LowerToIRVMServiceTest` | pass |
|
||||
| PR-05.0.4 | Callable shape and type-surface interning | `CallableShapeTableTest`; `TypeSurfaceTableTest`; `PbsModuleVisibilityTest` | pass |
|
||||
| PR-05.0.5 | Synthetic stdlib `FileId` via `FileTable` | `InterfaceModuleLoaderTest#shouldRegisterSyntheticStdlibFilesInFileTable` | pass |
|
||||
| PR-05.0.6 | Host binding canonical identity interning | `HostBindingTableTest`; host admission fixtures in `PbsFrontendCompilerTest` | pass |
|
||||
|
||||
## 5. Maintenance Procedure
|
||||
|
||||
1. Any backend PR that changes conformance-relevant behavior in FE/BE pipeline MUST update this matrix.
|
||||
2. If requirement coverage changes, update: mapped tests, status, and `Last Updated` date.
|
||||
3. New normative MUSTs in specs `19/20/21` or PBS `13` addendum MUST add a new matrix row before merge.
|
||||
4. Conformance-relevant FE/BE code paths for hard-gate are:
|
||||
- `prometeu-compiler/prometeu-build-pipeline/`
|
||||
- `prometeu-compiler/frontends/prometeu-frontend-pbs/`
|
||||
- `prometeu-compiler/prometeu-frontend-api/`
|
||||
- `prometeu-compiler/prometeu-compiler-core/`
|
||||
|
||||
## 6. Review/Lint Gate
|
||||
|
||||
Matrix integrity is enforced by automated document lint:
|
||||
|
||||
- `BackendConformanceMatrixSpecTest` validates file presence, required requirement IDs, and row status integrity.
|
||||
- `BackendConformanceMatrixSpecTest` enforces hard-gate policy:
|
||||
- if `PROMETEU_MATRIX_HARD_GATE=true` and `PROMETEU_CHANGED_FILES` contains a path under conformance-relevant FE/BE prefixes,
|
||||
- then this matrix file MUST be present in `PROMETEU_CHANGED_FILES`, otherwise the gate fails.
|
||||
- CI policy uses strict Gate I mode via `PROMETEU_GATE_I_STRICT=true` (or `CI=true`) and requires `PROMETEU_RUNTIME_CHECK_CMD` for runtime-backed evidence.
|
||||
@@ -0,0 +1,24 @@
|
||||
# General Specs
|
||||
|
||||
This directory contains shared acceptance specifications for all supported languages in Prometeu.
|
||||
|
||||
## Scope
|
||||
|
||||
These specs are above language-specific specs and should be reused by each language line.
|
||||
|
||||
Typical topics:
|
||||
|
||||
- conformance gates and evidence,
|
||||
- compatibility publication policy,
|
||||
- verification/safety acceptance boundaries,
|
||||
- artifact/runtime acceptance contracts.
|
||||
|
||||
Current backend-facing chapter additions:
|
||||
|
||||
- `20. IRBackend to IRVM Lowering Specification.md`
|
||||
- `21. IRVM Optimization Pipeline Specification.md`
|
||||
- `22. Backend Spec-to-Test Conformance Matrix.md`
|
||||
|
||||
## Rule
|
||||
|
||||
Language-specific specs (for example `docs/pbs/specs`) must reference this layer instead of duplicating cross-language acceptance policy.
|
||||
@@ -0,0 +1,72 @@
|
||||
# Domain and Artifact Boundary Specification
|
||||
|
||||
Status: Draft
|
||||
Scope: Packer domain core boundary
|
||||
Purpose: Define what the packer owns, what it emits, and where its responsibility stops.
|
||||
|
||||
## Authority and Precedence
|
||||
|
||||
This specification consolidates the initial packer agenda and decision wave into normative form.
|
||||
|
||||
Runtime-side reading semantics for `assets.pa` are defined upstream in `../runtime/docs/runtime/specs/13-cartridge.md` and `../runtime/docs/runtime/specs/15-asset-management.md`.
|
||||
|
||||
## Normative Inputs
|
||||
|
||||
- project workspace with `assets/`
|
||||
- packer registry and control data under `assets/.prometeu/`
|
||||
- registered asset roots anchored by `asset.json`
|
||||
|
||||
## Core Rules
|
||||
|
||||
1. The packer owns asset workspace management and artifact production.
|
||||
2. The packer emits the runtime-facing asset artifact `assets.pa`.
|
||||
3. The packer may emit companion build artifacts for Studio and tooling.
|
||||
4. The packer does not own cartridge shipping/publication.
|
||||
5. A future shipper is a consumer of packer artifacts, not a co-author of the asset contract.
|
||||
6. Runtime reading semantics are not redefined by the packer.
|
||||
7. The packer must stop at artifact publication, not cartridge assembly.
|
||||
|
||||
## Packer-Owned Artifacts
|
||||
|
||||
The packer owns production of at least:
|
||||
|
||||
- `assets.pa`
|
||||
- `build/asset_table.json`
|
||||
- `build/preload.json`
|
||||
- `build/asset_table_metadata.json`
|
||||
- `asset.json`
|
||||
- `assets/.prometeu/index.json`
|
||||
|
||||
## Runtime-Facing Boundary
|
||||
|
||||
`assets.pa` is the authoritative runtime-facing artifact.
|
||||
|
||||
Rules:
|
||||
|
||||
- the internal header of `assets.pa` is the runtime-facing source of truth for asset table and preload data;
|
||||
- companion JSON outputs must not replace the internal header as the runtime contract;
|
||||
- offsets and preload semantics must remain aligned with runtime specs.
|
||||
|
||||
## Future Shipper Boundary
|
||||
|
||||
The future shipper may consume packer artifacts to assemble cartridges.
|
||||
|
||||
Rules:
|
||||
|
||||
- the packer must not depend on a concrete shipper implementation now;
|
||||
- shipper-specific workflow detail is deferred;
|
||||
- published artifact names and meanings must remain documented and stable enough for later consumption.
|
||||
|
||||
## Non-Goals
|
||||
|
||||
- cartridge assembly flow
|
||||
- package distribution format design
|
||||
- runtime asset loading implementation detail
|
||||
|
||||
## Exit Criteria
|
||||
|
||||
This specification is complete enough when:
|
||||
|
||||
- packer ownership is unambiguous;
|
||||
- runtime-facing artifact authority is explicit;
|
||||
- future shipper integration is bounded without overdesign.
|
||||
@@ -0,0 +1,145 @@
|
||||
# Workspace, Registry, and Asset Identity Specification
|
||||
|
||||
Status: Draft
|
||||
Scope: Registered asset roots, registry authority, and stable identity
|
||||
Purpose: Define how the packer recognizes, tracks, and preserves asset identity.
|
||||
|
||||
## Authority and Precedence
|
||||
|
||||
This specification consolidates the initial packer agenda and decision wave into normative form.
|
||||
|
||||
## Normative Inputs
|
||||
|
||||
- `assets/`
|
||||
- `assets/.prometeu/index.json`
|
||||
- per-asset `asset.json`
|
||||
|
||||
## Core Rules
|
||||
|
||||
1. One registered asset equals one asset root directory.
|
||||
2. One asset root contains exactly one anchor `asset.json`.
|
||||
3. `assets/.prometeu/index.json` is the authoritative registry of registered assets.
|
||||
4. `asset.json` is the authoritative asset-local declaration.
|
||||
5. `asset.json` must carry the stable `asset_uuid` identity anchor for that asset root.
|
||||
6. An asset root absent from the registry is `unregistered`.
|
||||
7. `unregistered` assets are always `excluded` from build participation.
|
||||
8. Registered assets may be `included` or `excluded` from build participation without losing identity.
|
||||
9. The baseline build set includes registered assets whose registry entry is marked as build-included.
|
||||
|
||||
## Identity Model
|
||||
|
||||
Each registered asset has:
|
||||
|
||||
- `asset_id`: stable project-local identity
|
||||
- `asset_uuid`: stable long-lived identity for migration/tooling scenarios
|
||||
- `included_in_build`: build participation flag persisted in the registry
|
||||
|
||||
Identity authority is intentionally split:
|
||||
|
||||
- `asset_uuid` is anchored locally in `asset.json`;
|
||||
- `asset_id` is allocated and persisted by the registry;
|
||||
- registry-managed location and build participation remain catalog concerns in `index.json`.
|
||||
|
||||
The following are not primary identity:
|
||||
|
||||
- `asset_name`
|
||||
- filesystem path
|
||||
- internal input file names
|
||||
|
||||
`asset_name` may still be used by authoring and runtime-facing APIs as a logical reference label.
|
||||
|
||||
## Local Identity Anchor
|
||||
|
||||
`asset_uuid` is the stable asset-local identity anchor.
|
||||
|
||||
Rules:
|
||||
|
||||
- `asset_uuid` must be present in `asset.json`;
|
||||
- `asset_uuid` is stable across relocate and rename flows;
|
||||
- `asset_uuid` is not allocated from path shape or `asset_name`;
|
||||
- `asset_uuid` allows the packer to reconcile manual workspace changes with the registry/catalog model;
|
||||
- `asset_uuid` does not replace registry authority over `asset_id`, build participation, or managed root tracking.
|
||||
|
||||
## Relocation and Rename
|
||||
|
||||
Moving or renaming an asset root does not change identity.
|
||||
|
||||
Rules:
|
||||
|
||||
- `asset_id` remains unchanged;
|
||||
- `asset_uuid` remains unchanged;
|
||||
- registry location is updated;
|
||||
- relocation is not recreation.
|
||||
|
||||
Renaming `asset_name` is an API-visible change, but not an identity change.
|
||||
|
||||
## Unregistered Roots
|
||||
|
||||
An `asset.json` without a corresponding registry entry is an unregistered asset root.
|
||||
|
||||
Rules:
|
||||
|
||||
- it is excluded from the build automatically;
|
||||
- it is diagnosable;
|
||||
- it becomes registered only through explicit flow;
|
||||
- its local `asset_uuid` still matters for structural validation and future reconcile behavior.
|
||||
|
||||
## Build Participation
|
||||
|
||||
Build participation is registry-owned for registered assets.
|
||||
|
||||
Rules:
|
||||
|
||||
- excluding a registered asset from builds does not remove `asset_id`;
|
||||
- excluding a registered asset from builds does not remove `asset_uuid`;
|
||||
- inclusion changes must preserve asset identity and registry location;
|
||||
- unregistered assets cannot be marked as build-included.
|
||||
|
||||
## Asset ID Allocation
|
||||
|
||||
`asset_id` allocation is registry-owned and strictly monotonic within a project.
|
||||
|
||||
Rules:
|
||||
|
||||
- allocation occurs at registration time;
|
||||
- issued IDs are not silently recycled;
|
||||
- allocator state is persisted in the registry;
|
||||
- rollback is not baseline behavior.
|
||||
|
||||
## Structural Conflicts
|
||||
|
||||
Identity-bearing conflicts are structural errors.
|
||||
|
||||
Examples:
|
||||
|
||||
- duplicate or ambiguous anchors under registered expectations;
|
||||
- manual copy that creates identity collision;
|
||||
- registered root missing anchor;
|
||||
- duplicate `asset_uuid` across different asset roots;
|
||||
- registry/catalog location that no longer matches the asset root carrying the expected `asset_uuid`;
|
||||
- `asset.json` missing or malformed in a root expected to preserve identity.
|
||||
|
||||
## Reconcile Expectations
|
||||
|
||||
The packer may need to reconcile registry/catalog state against the authoring workspace.
|
||||
|
||||
Rules:
|
||||
|
||||
- manual move or rename of an asset root must not imply identity loss by itself;
|
||||
- reconcile should prefer `asset_uuid` when matching a durable asset identity across changed paths;
|
||||
- path drift must not silently rebind one registered asset to another distinct `asset_uuid`;
|
||||
- unresolved identity drift remains diagnosable until explicit repair or successful reconcile.
|
||||
|
||||
## Non-Goals
|
||||
|
||||
- full `asset.json` schema
|
||||
- asset format-specific metadata
|
||||
- UI/editor workflow detail
|
||||
|
||||
## Exit Criteria
|
||||
|
||||
This specification is complete enough when:
|
||||
|
||||
- registered asset boundaries are unambiguous;
|
||||
- registry authority is explicit;
|
||||
- identity survives relocation without ambiguity.
|
||||
@@ -0,0 +1,217 @@
|
||||
# Asset Declaration and Virtual Asset Contract Specification
|
||||
|
||||
Status: Draft
|
||||
Scope: Common `asset.json` contract
|
||||
Purpose: Define the shared declaration model for raw and virtual assets.
|
||||
|
||||
## Authority and Precedence
|
||||
|
||||
This specification consolidates the initial packer agenda and decision wave into normative form.
|
||||
|
||||
## Core Rules
|
||||
|
||||
The common `asset.json` contract requires these top-level fields:
|
||||
|
||||
- `schema_version`
|
||||
- `asset_uuid`
|
||||
- `name`
|
||||
- `type`
|
||||
- `inputs`
|
||||
- `output`
|
||||
- `preload`
|
||||
|
||||
The common contract may also include:
|
||||
|
||||
- `build`
|
||||
|
||||
## Meaning of `asset_uuid`
|
||||
|
||||
`asset_uuid` is the stable asset-local identity anchor.
|
||||
|
||||
Rules:
|
||||
|
||||
- it is required;
|
||||
- it must be stable across relocate and rename flows;
|
||||
- it is not the project-local runtime artifact identity;
|
||||
- it is not a substitute for registry-owned `asset_id`;
|
||||
- it exists so the asset root can preserve identity even when path-based assumptions drift;
|
||||
- it must remain compatible with packer reconcile behavior and migration flows.
|
||||
|
||||
## Meaning of `name`
|
||||
|
||||
`name` is the logical asset reference label.
|
||||
|
||||
Rules:
|
||||
|
||||
- it is required;
|
||||
- it is not the stable artifact identity;
|
||||
- it may still be used by runtime-facing APIs and source-level workflows.
|
||||
|
||||
## Meaning of `type`
|
||||
|
||||
`type` identifies the authoring-side asset family.
|
||||
|
||||
Rules:
|
||||
|
||||
- it is not the runtime bank identity;
|
||||
- the runtime-facing technical target belongs in `output.format`.
|
||||
|
||||
Examples:
|
||||
|
||||
- `tile_bank`
|
||||
- `sound_bank`
|
||||
|
||||
## Inputs
|
||||
|
||||
`inputs` is a structured object keyed by semantic role.
|
||||
|
||||
Rules:
|
||||
|
||||
- each key names an input role such as `sprites`, `palettes`, or `sources`;
|
||||
- each value is a list of paths;
|
||||
- paths are relative to the asset root;
|
||||
- even a single input is represented as a list.
|
||||
|
||||
This model supports grouped virtual assets such as atlases and bank-style assets.
|
||||
|
||||
## Output
|
||||
|
||||
`output` is the runtime-relevant output declaration.
|
||||
|
||||
Required baseline fields:
|
||||
|
||||
- `output.format`
|
||||
- `output.codec`
|
||||
|
||||
Optional baseline field:
|
||||
|
||||
- `output.metadata`
|
||||
- `output.pipeline`
|
||||
|
||||
Rules:
|
||||
|
||||
- `output.format` defines the semantic/runtime format contract;
|
||||
- `output.codec` defines storage/extraction behavior;
|
||||
- `output.metadata` carries runtime-relevant format-specific detail;
|
||||
- `output.pipeline` carries pipeline-injected metadata kept separate at authoring time;
|
||||
- codec must remain explicit and must not be hidden inside format naming.
|
||||
|
||||
### Explicit Index Collections
|
||||
|
||||
When `output.pipeline` carries ordered collections whose members need stable semantic identity, that identity must not depend on raw list position alone.
|
||||
|
||||
Rules:
|
||||
|
||||
- collections such as `output.pipeline.palettes` may remain JSON arrays for authoring ergonomics;
|
||||
- when a collection member has runtime- or packing-relevant identity, each entry must carry an explicit `index`;
|
||||
- `output.pipeline.palettes` entries must use the shape `{ "index": <int>, "palette": { ... } }`;
|
||||
- the packer must sort such entries by numeric `index`, not by physical array position;
|
||||
- duplicate or malformed indices are structural errors;
|
||||
- missing or malformed `palette` payloads are structural errors;
|
||||
- editorial reordering of the JSON array alone must not change semantic meaning.
|
||||
|
||||
Example:
|
||||
|
||||
```json
|
||||
{
|
||||
"output": {
|
||||
"pipeline": {
|
||||
"palettes": [
|
||||
{
|
||||
"index": 0,
|
||||
"palette": {
|
||||
"originalArgb8888": [4294901760, 4278255360],
|
||||
"convertedRgb565": [63488, 2016]
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Metadata Source Segmentation and Runtime Sink
|
||||
|
||||
`asset.json` may keep metadata segmented by concern during authoring.
|
||||
|
||||
Rules:
|
||||
|
||||
- declaration-time metadata may come from multiple sources under the asset contract (for example, format metadata, codec-related metadata, and build/pipeline-derived declarations);
|
||||
- `output.pipeline` may carry nested pipeline-derived metadata objects;
|
||||
- this segmentation exists for authoring clarity and does not define multiple runtime sinks;
|
||||
- runtime consumers must read effective metadata from the runtime asset entry metadata sink (`AssetEntry.metadata`);
|
||||
- convergence/normalization behavior is normative in the build artifact specification.
|
||||
|
||||
## Build
|
||||
|
||||
`build` is optional and process-oriented.
|
||||
|
||||
Rules:
|
||||
|
||||
- it may describe how authoring inputs are transformed or organized;
|
||||
- if a parameter affects the runtime-facing output contract, it belongs in `output.metadata`;
|
||||
- `build` must not hide runtime-relevant semantics.
|
||||
|
||||
## Operational State Exclusion
|
||||
|
||||
`asset.json` is a declaration artifact, not a catalog cache.
|
||||
|
||||
Rules:
|
||||
|
||||
- transient UI state must not be stored in `asset.json`;
|
||||
- registry-managed fields such as `asset_id` and `included_in_build` must not be duplicated into `asset.json`;
|
||||
- packer cache or snapshot bookkeeping must not be materialized into `asset.json` as normal operational state;
|
||||
- `asset.json` should remain focused on identity anchoring plus declared authoring/packing behavior.
|
||||
|
||||
## Preload
|
||||
|
||||
Each registered asset must declare preload intent explicitly.
|
||||
|
||||
Baseline shape:
|
||||
|
||||
```json
|
||||
{
|
||||
"preload": {
|
||||
"enabled": true
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Rules:
|
||||
|
||||
- `preload.enabled` is required and boolean;
|
||||
- preload participation is declared, not inferred;
|
||||
- richer preload policy fields are deferred.
|
||||
|
||||
## Defaults and Materialization
|
||||
|
||||
Defaults that affect runtime-visible behavior must not remain hidden.
|
||||
|
||||
Rules:
|
||||
|
||||
- runtime-relevant defaults should be materialized in `asset.json` whenever practical;
|
||||
- if materialized later, the resulting artifact must expose effective values explicitly.
|
||||
|
||||
## Versioning
|
||||
|
||||
The `asset.json` schema is versioned independently from:
|
||||
|
||||
- registry schema
|
||||
- runtime-facing artifact schema
|
||||
- format contract versions
|
||||
|
||||
Format-specific contracts evolve through values such as `TILES/indexed_v1`.
|
||||
|
||||
## Non-Goals
|
||||
|
||||
- field-level format schemas for every output family
|
||||
- rich preload policies
|
||||
- source-language lowering behavior for asset references
|
||||
|
||||
## Exit Criteria
|
||||
|
||||
This specification is complete enough when:
|
||||
|
||||
- the common `asset.json` shape is stable;
|
||||
- raw and virtual assets share a coherent baseline contract;
|
||||
- format-specific specs can build on it cleanly.
|
||||
@@ -0,0 +1,231 @@
|
||||
# Build Artifacts and Deterministic Packing Specification
|
||||
|
||||
Status: Draft
|
||||
Scope: Runtime-facing artifacts and deterministic build behavior
|
||||
Purpose: Define how the packer emits `assets.pa` and companion artifacts.
|
||||
|
||||
## Authority and Precedence
|
||||
|
||||
This specification consolidates the initial packer agenda and decision wave into normative form.
|
||||
|
||||
Runtime-side reading semantics remain upstream in:
|
||||
|
||||
- `../runtime/docs/runtime/specs/13-cartridge.md`
|
||||
- `../runtime/docs/runtime/specs/15-asset-management.md`
|
||||
|
||||
## Core Rules
|
||||
|
||||
1. `assets.pa` is the authoritative runtime-facing artifact.
|
||||
2. Companion JSON files do not replace the internal header as the runtime contract.
|
||||
3. The global asset table order is deterministic by increasing `asset_id`.
|
||||
4. The runtime-facing `asset_id` is the same stable `asset_id` allocated by the packer registry.
|
||||
|
||||
## `assets.pa` Structure
|
||||
|
||||
Baseline structure:
|
||||
|
||||
```text
|
||||
[fixed binary prelude]
|
||||
[canonical JSON header]
|
||||
[binary payload region]
|
||||
```
|
||||
|
||||
### Prelude Fields
|
||||
|
||||
The baseline prelude includes:
|
||||
|
||||
- `magic`
|
||||
- `schema_version`
|
||||
- `header_len`
|
||||
- `payload_offset`
|
||||
- `flags`
|
||||
- `reserved`
|
||||
|
||||
Rules:
|
||||
|
||||
- `flags` and `reserved` exist from day 1;
|
||||
- `flags = 0` unless later specified otherwise;
|
||||
- `reserved = 0` unless later specified otherwise;
|
||||
- `header_checksum` is not part of the baseline envelope contract.
|
||||
|
||||
## Canonical JSON Header
|
||||
|
||||
The header is serialized canonically.
|
||||
|
||||
Rules:
|
||||
|
||||
- UTF-8 encoding;
|
||||
- no extra whitespace;
|
||||
- object keys sorted lexicographically;
|
||||
- arrays preserve declared order;
|
||||
- canonicalization applies recursively;
|
||||
- runtime-facing header values in v1 must avoid floating-point numbers.
|
||||
|
||||
## Header Contents
|
||||
|
||||
The header carries:
|
||||
|
||||
- `asset_table`
|
||||
- `preload`
|
||||
|
||||
### Asset Table
|
||||
|
||||
`asset_table` is emitted as a deterministically ordered list of asset entries.
|
||||
|
||||
Rules:
|
||||
|
||||
- one entry per included asset in the current build set;
|
||||
- no secondary runtime-only identity layer;
|
||||
- no synthetic dense reindexing layer;
|
||||
- `asset_name` remains present as logical/API-facing metadata.
|
||||
|
||||
### Asset Entry Metadata Convergence
|
||||
|
||||
Each emitted asset entry has one runtime metadata sink: `AssetEntry.metadata`.
|
||||
|
||||
Rules:
|
||||
|
||||
- packer materialization must normalize all runtime-consumable metadata-producing sources into `asset_table[].metadata`;
|
||||
- equivalent declaration/build inputs must produce equivalent normalized metadata;
|
||||
- metadata key collisions across independent sources must fail build unless the family/format spec declares an explicit merge rule;
|
||||
- normalization behavior must be testable and covered by conformance-oriented tests.
|
||||
|
||||
Baseline normalized metadata segmentation:
|
||||
|
||||
- `output.metadata` materializes at the metadata root;
|
||||
- `output.codec_configuration` materializes under `metadata.codec`;
|
||||
- `output.pipeline` materializes under `metadata.pipeline`;
|
||||
- format-specific runtime-required fields may remain directly readable at the metadata root when the runtime consumer requires them there.
|
||||
|
||||
### Preload
|
||||
|
||||
Preload is emitted deterministically from per-asset declaration.
|
||||
|
||||
Rules:
|
||||
|
||||
- assets with `preload.enabled = false` do not appear in emitted preload data;
|
||||
- assets with `preload.enabled = true` do appear;
|
||||
- preload ordering is deterministic by increasing `asset_id`.
|
||||
|
||||
## Companion Artifacts
|
||||
|
||||
The baseline companion artifacts are:
|
||||
|
||||
- `build/asset_table.json`
|
||||
- `build/preload.json`
|
||||
- `build/asset_table_metadata.json`
|
||||
|
||||
Rules:
|
||||
|
||||
- `build/asset_table.json` mirrors `header.asset_table` 1:1;
|
||||
- `build/preload.json` mirrors `header.preload` 1:1;
|
||||
- `build/asset_table_metadata.json` is tooling-only;
|
||||
- richer tooling data must not be added to the 1:1 mirror files.
|
||||
|
||||
## Alignment and Offsets
|
||||
|
||||
Alignment exists only when explicitly required by spec.
|
||||
|
||||
Rules:
|
||||
|
||||
- there is no implicit baseline alignment beyond envelope and format requirements;
|
||||
- any required alignment must be normative and visible;
|
||||
- emitted offsets are always relative to the payload region, never the start of the full file.
|
||||
|
||||
Offset ambiguity guardrail:
|
||||
|
||||
- `asset_table[].offset`/`asset_table[].size` describe payload slicing inside `assets.pa`;
|
||||
- internal pipeline indexing data (for example per-sample ranges for audio banks) must live under `asset_table[].metadata`;
|
||||
- internal indexing fields must not be interpreted as payload slicing fields.
|
||||
|
||||
## Format-Specific Baseline: `TILES/indexed_v1`
|
||||
|
||||
The first-wave producer contract for `TILES/indexed_v1` is fixed and runtime-aligned.
|
||||
|
||||
### Tile Selection and Identity
|
||||
|
||||
Rules:
|
||||
|
||||
- only selected artifacts participate in the emitted tile bank;
|
||||
- `1 artifact = 1 tile` in v1;
|
||||
- artifacts are normalized by ascending `artifacts[*].index`;
|
||||
- emitted `tile_id` equals the normalized artifact index;
|
||||
- duplicate or gapped artifact indices are build-blocking structural failures.
|
||||
|
||||
### Emitted Sheet Shape
|
||||
|
||||
Rules:
|
||||
|
||||
- the emitted tile-bank sheet is always `256 x 256` in v1;
|
||||
- tile placement within that emitted sheet is row-major;
|
||||
- runtime `width` and `height` for the bank entry therefore refer to the full emitted sheet, not one individual artifact;
|
||||
- resulting per-bank capacities are:
|
||||
- `tile_size = 8` -> `1024` tiles
|
||||
- `tile_size = 16` -> `256` tiles
|
||||
- `tile_size = 32` -> `64` tiles
|
||||
- capacity overflow is a build-blocking structural failure.
|
||||
|
||||
### Payload Layout
|
||||
|
||||
Rules:
|
||||
|
||||
- the serialized payload for `TILES/indexed_v1` is:
|
||||
1. one packed `u4` pixel plane for the full emitted sheet;
|
||||
2. one palette block of `64 * 16 * 2 = 2048` bytes;
|
||||
- packed pixel bytes must be emitted by the packer, not inferred later by the runtime;
|
||||
- the palette block is serialized as `RGB565` `u16` values;
|
||||
- palette bytes must be emitted in little-endian order;
|
||||
- payload interpretation must not depend on incidental per-artifact boundaries.
|
||||
|
||||
### Runtime Entry Derivation
|
||||
|
||||
Rules:
|
||||
|
||||
- emitted tile-bank entries use:
|
||||
- `bank_type = TILES`
|
||||
- `codec = NONE`
|
||||
- tile-bank v1 metadata must expose at least:
|
||||
- `tile_size`
|
||||
- `width`
|
||||
- `height`
|
||||
- `palette_count`
|
||||
- tile-bank v1 requires `palette_count = 64`;
|
||||
- tile-bank v1 size formulas are:
|
||||
- `size = ceil(width * height / 2) + 2048`
|
||||
- `decoded_size = (width * height) + 2048`
|
||||
|
||||
### Palette Contract
|
||||
|
||||
Rules:
|
||||
|
||||
- bank palettes are declared under `output.pipeline.palettes`;
|
||||
- each palette declaration uses the shape `{ "index": <int>, "palette": { ... } }`;
|
||||
- palette ordering is ascending numeric `index`, never raw array position;
|
||||
- palette ids in the emitted tile bank are the normalized declared palette indices;
|
||||
- any tile in the bank may be rendered with any palette in the bank at runtime;
|
||||
- palette selection is a runtime draw concern, not a tile-payload embedding concern.
|
||||
|
||||
## Determinism
|
||||
|
||||
Equivalent build inputs must produce equivalent outputs.
|
||||
|
||||
Rules:
|
||||
|
||||
- no filesystem iteration dependence;
|
||||
- no hidden defaults that affect output;
|
||||
- no usage-based hot-first packing in the baseline contract;
|
||||
- determinism is preferred over speculative physical-layout optimization.
|
||||
|
||||
## Non-Goals
|
||||
|
||||
- per-format payload internals for every output family
|
||||
- future locality optimization policy
|
||||
- cartridge-level integrity/signature strategy
|
||||
|
||||
## Exit Criteria
|
||||
|
||||
This specification is complete enough when:
|
||||
|
||||
- runtime-facing artifact authority is explicit;
|
||||
- companion artifacts are bounded;
|
||||
- emitted ordering and header behavior are deterministic.
|
||||
+257
@@ -0,0 +1,257 @@
|
||||
# Diagnostics, Operations, and Studio Integration Specification
|
||||
|
||||
Status: Draft
|
||||
Scope: Diagnostics, service operations, and Studio-facing event/reporting model
|
||||
Purpose: Define how the packer exposes safe operational behavior to Studio and tooling.
|
||||
|
||||
## Authority and Precedence
|
||||
|
||||
This specification consolidates the initial packer agenda and decision wave into normative form.
|
||||
|
||||
## Diagnostics Model
|
||||
|
||||
Diagnostics are divided into:
|
||||
|
||||
- structural registered-world errors;
|
||||
- advisory workspace hygiene diagnostics.
|
||||
|
||||
Rules:
|
||||
|
||||
- structural registered-world errors block builds;
|
||||
- hygiene findings do not block baseline builds by default;
|
||||
- workspace scanning is broader than build validation.
|
||||
|
||||
## Doctor Model
|
||||
|
||||
Baseline doctor behavior:
|
||||
|
||||
- registered-world validation by default;
|
||||
- broader workspace hygiene scanning in expanded workspace mode;
|
||||
- safe mechanical fix application only for baseline fix flows.
|
||||
|
||||
Unsafe automatic mutation is out of scope for baseline doctor behavior.
|
||||
|
||||
## Safety and Consent
|
||||
|
||||
Rules:
|
||||
|
||||
- destructive or relocational mutations require explicit consent;
|
||||
- quarantine is explicit and reversible;
|
||||
- duplicate content detection is advisory, not structurally invalid by itself;
|
||||
- unregistered asset roots are diagnosable and remain excluded from builds.
|
||||
|
||||
## Studio-First Service Surface
|
||||
|
||||
The normative operational surface is service-based.
|
||||
|
||||
The packer is a filesystem-first operational runtime.
|
||||
|
||||
Rules:
|
||||
|
||||
- the active project may maintain a coherent in-memory operational snapshot;
|
||||
- normal read requests should be served from that coherent snapshot when the runtime is active;
|
||||
- the runtime snapshot is an operational projection of packer-owned workspace artifacts, not a replacement authoring store;
|
||||
- the durable authoring workspace remains the persisted source of truth after successful commit.
|
||||
|
||||
### Embedded Bootstrap Rule
|
||||
|
||||
When the packer is embedded inside another host such as Studio, the host must bootstrap the packer integration explicitly.
|
||||
|
||||
Rules:
|
||||
|
||||
- the embedded packer runtime must receive a typed event bus reference from the host when shared host visibility is part of the integration contract;
|
||||
- that reference is the baseline path for packer publish/subscribe integration in the embedded host;
|
||||
- the embedded packer runtime must not quietly create a disconnected parallel event system when host integration expects shared operational visibility;
|
||||
- in Studio, this shared typed event bus reference is owned by the Studio `Container`.
|
||||
|
||||
Baseline core services:
|
||||
|
||||
- `init_workspace`
|
||||
- `register_asset`
|
||||
- `include_asset_in_build`
|
||||
- `exclude_asset_from_build`
|
||||
- `remove_asset`
|
||||
- `list_assets`
|
||||
- `get_asset_details`
|
||||
- `doctor`
|
||||
- `build`
|
||||
|
||||
## Operation Classes
|
||||
|
||||
Operations must distinguish:
|
||||
|
||||
- read-only operations;
|
||||
- registry mutations;
|
||||
- workspace mutations.
|
||||
|
||||
This distinction is part of the service semantics and must be visible to the UI.
|
||||
|
||||
## Runtime State and Visibility
|
||||
|
||||
The packer runtime must make operational freshness explicit.
|
||||
|
||||
At minimum, the model should support states equivalent to:
|
||||
|
||||
- `healthy`
|
||||
- `stale`
|
||||
- `diverged`
|
||||
- `committing`
|
||||
- `reconciling`
|
||||
- `failed`
|
||||
|
||||
Rules:
|
||||
|
||||
- successful durable commit defines the visibility boundary for committed write state;
|
||||
- reads must not present torn in-progress writes as committed truth;
|
||||
- background divergence detection may move a project or asset view into stale/diverged/reconciling state;
|
||||
- Studio may render these states, but must not invent their semantics.
|
||||
|
||||
## Concurrency Model
|
||||
|
||||
The packer concurrency model is conservative and project-scoped.
|
||||
|
||||
Rules:
|
||||
|
||||
- observable correctness takes priority over speculative parallelism;
|
||||
- operations are coordinated per project workspace, not globally across unrelated projects;
|
||||
- Studio is a consumer of packer coordination results, not the owner of packer concurrency policy.
|
||||
|
||||
### Baseline Operation Matrix
|
||||
|
||||
- read/read may run concurrently when each read observes a coherent snapshot;
|
||||
- read/write must not expose torn intermediate state to consumers;
|
||||
- write/write on the same project is serialized;
|
||||
- build/write on the same project is serialized unless a future spec introduces an explicit transactional coordination model;
|
||||
- background observation may continue while a serialized write lane is active, but it must not publish misleading post-state before commit visibility.
|
||||
|
||||
### Write Ownership
|
||||
|
||||
- writes on one project execute through a packer-owned write lane;
|
||||
- caller timing must not define final write interleaving semantics;
|
||||
- preview generation may occur before the final commit section when safe;
|
||||
- apply/commit remains the packer-owned visibility boundary.
|
||||
|
||||
## Preview/Apply Model
|
||||
|
||||
Sensitive mutations use staged intent.
|
||||
|
||||
Rules:
|
||||
|
||||
- preview or analysis precedes broad mutation where appropriate;
|
||||
- safe-fix flows are modeled as services, not merely terminal flags;
|
||||
- `exclude_asset_from_build` and `remove_asset` remain distinct operations.
|
||||
|
||||
## Structured Responses
|
||||
|
||||
Service responses must be structured.
|
||||
|
||||
At minimum, the model should support fields equivalent to:
|
||||
|
||||
- `status`
|
||||
- `summary`
|
||||
- `runtime_state`
|
||||
- `affected_assets`
|
||||
- `diagnostics`
|
||||
- `proposed_actions`
|
||||
- `applied_actions`
|
||||
- `blockers`
|
||||
|
||||
## Asset Event Lane
|
||||
|
||||
The system includes a dedicated asset workspace event/reporting lane.
|
||||
|
||||
Responsibilities:
|
||||
|
||||
- observe relevant asset and registry changes;
|
||||
- report diagnostics/build/cache activity to the UI;
|
||||
- support live refresh and progress reporting;
|
||||
- avoid blocking the main UI thread.
|
||||
- surface operational freshness and reconcile transitions when they affect Studio-visible state.
|
||||
|
||||
### Initial Event Set
|
||||
|
||||
The initial structured event set includes:
|
||||
|
||||
- `asset_discovered`
|
||||
- `asset_changed`
|
||||
- `diagnostics_updated`
|
||||
- `build_started`
|
||||
- `build_finished`
|
||||
- `cache_hit`
|
||||
- `cache_miss`
|
||||
- `preview_ready`
|
||||
- `action_applied`
|
||||
- `action_failed`
|
||||
- `progress_updated`
|
||||
|
||||
Additional runtime/reconcile state events may exist as the operational runtime evolves, but adapters must preserve their causal meaning instead of collapsing them into generic refresh noise.
|
||||
|
||||
### Mutation Serialization
|
||||
|
||||
Mutating asset workflows are serialized semantically.
|
||||
|
||||
Rules:
|
||||
|
||||
- background observation and reporting may be continuous;
|
||||
- conflicting sensitive mutations must not race arbitrarily;
|
||||
- observable mutation behavior remains coherent from the UI perspective.
|
||||
- the baseline write policy is a single-writer semantic lane per project;
|
||||
- preview generation may run outside the final commit section, but apply/commit remains serialized;
|
||||
- build and sensitive mutation apply must not interleave on the same project in a way that obscures final state;
|
||||
- cancellation or failure must leave the observable project state in a coherent post-operation condition.
|
||||
- divergence detection must not silently rewrite user-authored workspace content as if it were a normal mutation apply.
|
||||
|
||||
### Event Envelope
|
||||
|
||||
Packer events must be structured enough for adapters to preserve causality and user-facing meaning.
|
||||
|
||||
At minimum, each event must carry fields equivalent to:
|
||||
|
||||
- `project_id` or workspace identity
|
||||
- `operation_id`
|
||||
- `sequence`
|
||||
- `kind`
|
||||
- `timestamp`
|
||||
- `summary`
|
||||
- `progress` when applicable
|
||||
- `affected_assets` when applicable
|
||||
|
||||
Rules:
|
||||
|
||||
- `operation_id` is stable for the full lifecycle of one logical operation;
|
||||
- `sequence` is monotonic within one operation;
|
||||
- adapters may remap event shapes for UI consumption, but must not invent causal relationships not present in packer events.
|
||||
- embedded hosts should preserve the same typed event bus reference across packer bootstrap and adapter wiring so subscription and publication stay causally coherent.
|
||||
|
||||
### Event Ordering and Coalescing
|
||||
|
||||
Rules:
|
||||
|
||||
- events emitted for one operation must be observable in causal order;
|
||||
- repeated progress updates may be coalesced by adapters or sinks;
|
||||
- lifecycle boundaries such as preview-ready, apply-success, apply-failure, build-started, and build-finished must remain individually observable;
|
||||
- low-value repeated observation events must not drown out actionable failures or terminal state.
|
||||
|
||||
## Incremental and Watch Integration
|
||||
|
||||
Incremental behavior is an optimization only.
|
||||
|
||||
Rules:
|
||||
|
||||
- full and incremental builds must be observably equivalent;
|
||||
- watch mode is optional in the baseline contract;
|
||||
- watch does not authorize silent dangerous mutation.
|
||||
|
||||
## Non-Goals
|
||||
|
||||
- final visual design of Studio asset panels
|
||||
- future CLI grammar
|
||||
- remote/shared cache orchestration
|
||||
|
||||
## Exit Criteria
|
||||
|
||||
This specification is complete enough when:
|
||||
|
||||
- Studio-facing operational semantics are explicit;
|
||||
- safety/preview/apply behavior is clear;
|
||||
- event/reporting integration has a stable baseline.
|
||||
@@ -0,0 +1,124 @@
|
||||
# Versioning, Migration, and Trust Model Specification
|
||||
|
||||
Status: Draft
|
||||
Scope: Artifact/schema versioning, migration ownership, and conservative trust boundaries
|
||||
Purpose: Define how the packer evolves safely over time and what trust assumptions it makes.
|
||||
|
||||
## Authority and Precedence
|
||||
|
||||
This specification consolidates the initial packer agenda and decision wave into normative form.
|
||||
|
||||
## Core Rules
|
||||
|
||||
1. Versioning is explicit and per artifact/schema.
|
||||
2. Migration applies only to artifacts the packer owns.
|
||||
3. Compatibility is governed by a support window, not indefinite backward guarantees.
|
||||
4. Inputs are untrusted until validated.
|
||||
5. Baseline packer architecture does not execute arbitrary plugins or scripts.
|
||||
|
||||
## Explicit Versioning Surfaces
|
||||
|
||||
The packer versioning model applies to at least:
|
||||
|
||||
- `asset.json`
|
||||
- `index.json`
|
||||
- `assets.pa`
|
||||
- the `assets.pa` header contract
|
||||
- companion build artifacts where a stable reader exists
|
||||
- packer-owned cache/control schemas where migration is supported
|
||||
|
||||
## Migration Ownership
|
||||
|
||||
The packer owns migration of artifacts it controls.
|
||||
|
||||
This includes:
|
||||
|
||||
- `asset.json`
|
||||
- `index.json`
|
||||
- packer-owned caches and control files
|
||||
|
||||
Rules:
|
||||
|
||||
- migration may be automatic within the supported window;
|
||||
- unsupported versions fail clearly and early;
|
||||
- migration failures must be diagnosable in Studio and CI.
|
||||
- migration may need to preserve or repair identity-bearing fields such as `asset_uuid` without fabricating a different asset identity silently.
|
||||
|
||||
## Runtime Compatibility Boundary
|
||||
|
||||
Runtime reading semantics for `assets.pa` belong upstream to runtime specs.
|
||||
|
||||
Rules:
|
||||
|
||||
- the packer implements the corresponding writer-side production contract;
|
||||
- the packer must not redefine runtime reader semantics;
|
||||
- companion artifacts do not redefine the runtime-facing contract.
|
||||
|
||||
## Future Shipper Boundary
|
||||
|
||||
The future shipper is a consumer of packer artifacts.
|
||||
|
||||
Rules:
|
||||
|
||||
- the shipper is not a current packer dependency;
|
||||
- the shipper must not become a silent repair layer for invalid packer artifacts;
|
||||
- shipper workflow detail is deferred until the shipper exists.
|
||||
|
||||
## Trust Model
|
||||
|
||||
The trust posture is conservative.
|
||||
|
||||
Untrusted until validated:
|
||||
|
||||
- source asset files;
|
||||
- hand-edited or legacy declarations;
|
||||
- imported external project content;
|
||||
- legacy packer artifacts and control data.
|
||||
- runtime snapshot observations that have not yet been reconciled against changed workspace files.
|
||||
|
||||
Trusted only after:
|
||||
|
||||
- strict parse;
|
||||
- structural validation;
|
||||
- semantic validation;
|
||||
- version compatibility check.
|
||||
- reconcile or refresh when divergence between snapshot and filesystem has been detected.
|
||||
|
||||
## Plugin and Script Execution
|
||||
|
||||
The baseline packer contract forbids arbitrary external execution as part of normal asset processing.
|
||||
|
||||
Rules:
|
||||
|
||||
- no untrusted plugins;
|
||||
- no ad hoc script execution;
|
||||
- no implicit foreign-code extension hooks.
|
||||
|
||||
Any future extensibility model requires a separate decision.
|
||||
|
||||
## Failure Surfacing
|
||||
|
||||
Version and migration failures must be actionable.
|
||||
|
||||
At minimum, diagnostics should make clear:
|
||||
|
||||
- the version found;
|
||||
- the supported range or expectation;
|
||||
- whether migration was attempted;
|
||||
- whether identity-bearing fields or registry/catalog alignment were implicated;
|
||||
- whether manual action is required;
|
||||
- whether the failure blocks build or Studio workflow.
|
||||
|
||||
## Non-Goals
|
||||
|
||||
- artifact signing strategy
|
||||
- distribution security beyond current tooling trust posture
|
||||
- remote/shared artifact registry behavior
|
||||
|
||||
## Exit Criteria
|
||||
|
||||
This specification is complete enough when:
|
||||
|
||||
- artifact versioning boundaries are explicit;
|
||||
- migration ownership is unambiguous;
|
||||
- trust assumptions are conservative and enforceable.
|
||||
@@ -0,0 +1,75 @@
|
||||
# Packer Specs
|
||||
|
||||
This directory contains the normative packer specification set.
|
||||
|
||||
## Purpose
|
||||
|
||||
Specs define the official packer contract.
|
||||
|
||||
They exist to make behavior, constraints, interfaces, and artifact guarantees stable across implementation and review.
|
||||
|
||||
The packer normative content is maintained directly in this `specs/` corpus.
|
||||
|
||||
## Expected Format
|
||||
|
||||
The exact structure may vary by document, but a packer spec should usually contain:
|
||||
|
||||
1. Title
|
||||
2. Status
|
||||
3. Scope or Applies To
|
||||
4. Purpose
|
||||
5. Authority and Precedence
|
||||
6. Normative Inputs
|
||||
7. Core Rules
|
||||
8. Non-Goals
|
||||
9. Exit Criteria
|
||||
|
||||
Some specs may also include:
|
||||
|
||||
- artifact schemas,
|
||||
- invariants,
|
||||
- diagnostic contracts,
|
||||
- examples,
|
||||
- migration notes,
|
||||
- explicit TODO sections for tracked unresolved items.
|
||||
|
||||
## Writing Rules
|
||||
|
||||
- Write in normative language.
|
||||
- Integrate only decisions that have already been closed.
|
||||
- Keep debate history and option analysis out of the spec body.
|
||||
- Preserve clear boundaries between adjacent packer specs.
|
||||
- Use TODO only for explicitly tracked unresolved items, not as a substitute for agenda work.
|
||||
|
||||
## Upstream Rule
|
||||
|
||||
Specs should normally be fed by:
|
||||
|
||||
1. agendas that frame the open topic,
|
||||
2. decisions that close the architectural question,
|
||||
3. pull-request plans that define propagation,
|
||||
4. then spec integration.
|
||||
|
||||
If a spec edit would require guessing an unresolved design choice, stop and surface the missing decision first.
|
||||
|
||||
## Current Corpus
|
||||
|
||||
The current packer core corpus is:
|
||||
|
||||
1. [`1. Domain and Artifact Boundary Specification.md`](1.%20Domain%20and%20Artifact%20Boundary%20Specification.md)
|
||||
2. [`2. Workspace, Registry, and Asset Identity Specification.md`](2.%20Workspace,%20Registry,%20and%20Asset%20Identity%20Specification.md)
|
||||
3. [`3. Asset Declaration and Virtual Asset Contract Specification.md`](3.%20Asset%20Declaration%20and%20Virtual%20Asset%20Contract%20Specification.md)
|
||||
4. [`4. Build Artifacts and Deterministic Packing Specification.md`](4.%20Build%20Artifacts%20and%20Deterministic%20Packing%20Specification.md)
|
||||
5. [`5. Diagnostics, Operations, and Studio Integration Specification.md`](5.%20Diagnostics,%20Operations,%20and%20Studio%20Integration%20Specification.md)
|
||||
6. [`6. Versioning, Migration, and Trust Model Specification.md`](6.%20Versioning,%20Migration,%20and%20Trust%20Model%20Specification.md)
|
||||
|
||||
## Reading Order
|
||||
|
||||
Recommended order:
|
||||
|
||||
1. domain and artifact boundary;
|
||||
2. workspace and identity;
|
||||
3. asset declaration;
|
||||
4. build artifacts;
|
||||
5. diagnostics and Studio operation model;
|
||||
6. versioning and trust.
|
||||
@@ -0,0 +1,123 @@
|
||||
# Studio Shell and Workspace Layout Specification
|
||||
|
||||
Status: Draft
|
||||
Scope: Studio shell, project entry, and workspace frame
|
||||
Purpose: Define the normative shell structure of the Studio UI.
|
||||
|
||||
## Authority and Precedence
|
||||
|
||||
This specification consolidates the accepted Studio shell decision into normative form.
|
||||
|
||||
## Normative Inputs
|
||||
|
||||
- the Studio application shell
|
||||
- project entry or launcher flow
|
||||
- shell-level workspace navigation
|
||||
- shell-level utility and run surfaces
|
||||
|
||||
## Core Rules
|
||||
|
||||
1. The Studio must open through a project launcher or home surface before entering the main workspace shell.
|
||||
2. The main shell must expose a top global menu region.
|
||||
3. The main shell must expose a left fixed workspace selector.
|
||||
4. The main shell must expose a center workspace host.
|
||||
5. The main shell must expose a right global utility panel.
|
||||
6. The main shell must expose an always-visible run surface in the top-right area.
|
||||
7. Workspaces mounted in the shell must follow the Studio event-driven workspace framework.
|
||||
8. The shell must preserve a clear path for reusable workspace framework primitives shared across workspaces.
|
||||
|
||||
## Project Entry
|
||||
|
||||
The Studio must not land directly into a workspace as its primary entry behavior.
|
||||
|
||||
Baseline project entry behavior is:
|
||||
|
||||
- show a lightweight launcher or home surface first;
|
||||
- show existing or recent projects;
|
||||
- expose `Open Project` and `Create Project` as first-class actions;
|
||||
- enter the main workspace shell only after a concrete project is selected or created.
|
||||
|
||||
## Workspace Model
|
||||
|
||||
The left workspace selector remains fixed in the baseline Studio shell.
|
||||
|
||||
The baseline workspace set includes:
|
||||
|
||||
- Code Editor;
|
||||
- Asset Management;
|
||||
- Debugger/Profiler;
|
||||
- Shipper, temporarily represented by the current `BuilderWorkspace`.
|
||||
|
||||
`BuilderWorkspace` is transitional and must not be treated as a long-term architectural reference for the final shipping surface.
|
||||
|
||||
## Workspace Architecture Model
|
||||
|
||||
The shell-level workspace host exists to mount independently authored workspaces under one Studio contract.
|
||||
|
||||
Baseline workspace architecture rules are:
|
||||
|
||||
- each workspace should have a composition root that mounts the workspace into the shell;
|
||||
- a workspace composition root should coordinate workspace services, state orchestration, and structural sync, but it should not own every local render path directly;
|
||||
- event-observing workspace controls must be lifecycle-managed;
|
||||
- workspace-local updates should flow through the Studio event system rather than ad hoc imperative redraw chains;
|
||||
- future workspaces should consume shared Studio workspace framework primitives where those primitives already cover the needed behavior.
|
||||
|
||||
The shell must not encourage a workspace model where every interaction falls back to whole-workspace refresh.
|
||||
|
||||
## Right Utility Panel
|
||||
|
||||
The right-side global utility surface is tab-based.
|
||||
|
||||
Baseline rules:
|
||||
|
||||
- the initial tab set contains only `Activity`;
|
||||
- the panel must be extendable with additional tabs later;
|
||||
- `Run` is not a tab.
|
||||
|
||||
The right utility panel exists for shell-level visibility and utility, not for general per-workspace log dumping.
|
||||
|
||||
## Logs and Operational Detail
|
||||
|
||||
Detailed execution output belongs to the active workspace that owns the operation.
|
||||
|
||||
Rules:
|
||||
|
||||
- the shell must not define a single mandatory global console as the baseline logging model;
|
||||
- each workspace may expose its own logs, console, or detailed operational output;
|
||||
- shell-level utility surfaces may summarize shared activity, but they do not replace workspace-owned detail.
|
||||
|
||||
## UI Remodeling Scope
|
||||
|
||||
The Studio UI may be remodeled substantially during this wave.
|
||||
|
||||
That flexibility is constrained by:
|
||||
|
||||
- theme support must remain preserved;
|
||||
- i18n support must remain preserved;
|
||||
- the resulting shell must keep a clear path for reusable Studio controls.
|
||||
|
||||
## Deferred Docking
|
||||
|
||||
A fully docked IDE shell is not baseline behavior.
|
||||
|
||||
Rules:
|
||||
|
||||
- docking is explicitly deferred;
|
||||
- shell topology and workspace responsibilities must be proven first;
|
||||
- future dockability may be revisited only after the baseline shell is stable in actual use.
|
||||
|
||||
## Non-Goals
|
||||
|
||||
- defining the full internal layout of every workspace
|
||||
- defining the final future tab set of the right utility panel
|
||||
- defining the detailed activity rendering model
|
||||
- defining every reusable workspace primitive in this document
|
||||
|
||||
## Exit Criteria
|
||||
|
||||
This specification is complete enough when:
|
||||
|
||||
- project entry and shell regions are unambiguous;
|
||||
- workspace and shell responsibilities are clearly separated;
|
||||
- the shell-level expectations for workspace architecture are explicit;
|
||||
- the baseline Studio frame is stable enough for implementation planning.
|
||||
@@ -0,0 +1,191 @@
|
||||
# Studio UI Foundations Specification
|
||||
|
||||
Status: Draft
|
||||
Scope: Naming, event publication model, and Studio UI foundations
|
||||
Purpose: Define the shared infrastructure rules that all Studio UI work must follow.
|
||||
|
||||
## Authority and Precedence
|
||||
|
||||
This specification consolidates the accepted Studio UI foundations decision into normative form.
|
||||
|
||||
## Normative Inputs
|
||||
|
||||
- Studio shell structures
|
||||
- workspace UI structures
|
||||
- Studio-owned services
|
||||
- shell and workspace event publication needs
|
||||
- reusable Studio control infrastructure
|
||||
|
||||
## Core Rules
|
||||
|
||||
1. Studio UI naming must be explicit by role.
|
||||
2. The Studio must define its own typed event system.
|
||||
3. The Studio event system must include one global bus and one bus per workspace.
|
||||
4. Every event published on a workspace bus must also be published on the global bus automatically.
|
||||
5. Studio UI must preserve theme and i18n compatibility by construction.
|
||||
6. Lifecycle-managed event subscription is the canonical way Studio controls observe external state.
|
||||
7. The Studio must provide a reusable workspace framework for event-driven workspace composition.
|
||||
8. Studio workspaces must consume that framework rather than invent refresh-heavy workspace-local patterns.
|
||||
|
||||
## Naming by Role
|
||||
|
||||
Studio naming must follow role-oriented conventions.
|
||||
|
||||
Baseline naming guidance:
|
||||
|
||||
- `StudioShell*` for shell-level structures;
|
||||
- `*Workspace` for workspaces;
|
||||
- `*Panel` for composed regions or panels;
|
||||
- `*View` for focused visual views;
|
||||
- `*Item` or `*Row` for list and cell-like elements;
|
||||
- `StudioEvent*` for event types;
|
||||
- `*Service` for operational services;
|
||||
- `*Control` for reusable low-level visual controls.
|
||||
|
||||
Names must communicate responsibility directly.
|
||||
Vague naming that hides shell, panel, workspace, or control roles is non-conforming.
|
||||
|
||||
## Studio Event System
|
||||
|
||||
The Studio must not rely on stringly-typed event routing as its primary contract.
|
||||
|
||||
Baseline event rules:
|
||||
|
||||
- event publication is local to the process;
|
||||
- event publication is strongly typed;
|
||||
- event payloads are DTOs and should be immutable where practical;
|
||||
- event publication and subscription management must be thread-safe;
|
||||
- the baseline model should remain intentionally small;
|
||||
- a large reactive framework is not baseline behavior.
|
||||
|
||||
Thread safety is required because background work such as asset recognition, scanning, diagnostics refresh, or other asynchronous Studio activity may publish events that eventually affect visible UI state.
|
||||
|
||||
## Global and Workspace Buses
|
||||
|
||||
The baseline event topology includes:
|
||||
|
||||
- one global `StudioEventBus`;
|
||||
- one workspace-local event bus per workspace.
|
||||
|
||||
Propagation rules:
|
||||
|
||||
- every event published on a workspace bus is automatically republished on the global bus;
|
||||
- propagation is workspace to global;
|
||||
- global-to-workspace rebroadcast is not baseline behavior.
|
||||
|
||||
The global Studio bus is backed by a typed event bus reference owned by the Studio application container.
|
||||
|
||||
Container rules:
|
||||
|
||||
- the Studio `Container` owns the global typed event bus reference used by `StudioEventBus`;
|
||||
- host-integrated services that need shared Studio operational visibility should receive that container-owned typed event bus reference during bootstrap instead of allocating disconnected local buses;
|
||||
- the `Container` must be initialized during Studio boot before packer-backed integration services, workspaces, or adapters begin use.
|
||||
|
||||
This topology exists so callers do not need to duplicate publication decisions manually.
|
||||
|
||||
## Event Categories
|
||||
|
||||
The exact event catalog may evolve incrementally.
|
||||
|
||||
Illustrative baseline categories include:
|
||||
|
||||
- project lifecycle events;
|
||||
- project loading lifecycle events;
|
||||
- workspace selection events;
|
||||
- run and build intent events;
|
||||
- activity publication events;
|
||||
- progress update events;
|
||||
- diagnostics update events;
|
||||
- asset selection events.
|
||||
|
||||
For project bootstrap and splash/loading integration, the Studio event catalog should reserve typed events for:
|
||||
|
||||
- project loading started;
|
||||
- project loading progress;
|
||||
- project loading completed;
|
||||
- project loading failed.
|
||||
|
||||
Project loading progress events should carry at least:
|
||||
|
||||
- the project identity,
|
||||
- a typed loading phase,
|
||||
- a user-facing status message,
|
||||
- and either determinate progress or an explicit indeterminate marker.
|
||||
|
||||
## Theme and i18n Compatibility
|
||||
|
||||
Shared Studio UI foundations must preserve:
|
||||
|
||||
- CSS-based theming;
|
||||
- locale-safe user-facing text behavior;
|
||||
- safe runtime locale updates where text changes dynamically;
|
||||
- no hardcoded user-facing text in reusable Studio controls.
|
||||
|
||||
Theme and i18n compatibility are admission requirements for shared UI infrastructure.
|
||||
|
||||
## Foundation Boundary
|
||||
|
||||
Shared Studio foundations include:
|
||||
|
||||
- shell-level UI conventions;
|
||||
- event publication and observation infrastructure;
|
||||
- reusable workspace framework primitives;
|
||||
- reusable Studio control conventions.
|
||||
|
||||
## Subscription Lifecycle
|
||||
|
||||
Reusable Studio controls must have an explicit subscription lifecycle when they observe events or external state.
|
||||
|
||||
Baseline rule:
|
||||
|
||||
- Studio controls that need event observation should expose subscribe and unsubscribe lifecycle hooks that can be overridden when needed.
|
||||
- Studio controls should also expose attach and detach lifecycle hooks for integration with the UI tree.
|
||||
- `onAttached()` should trigger subscription setup.
|
||||
- `onDetached()` should trigger subscription teardown.
|
||||
|
||||
This exists to make event wiring visible, testable, and safe under UI lifecycle changes.
|
||||
|
||||
The exact base class or interface shape is an implementation concern, but the lifecycle itself is normative.
|
||||
|
||||
## Canonical Workspace Framework
|
||||
|
||||
The Studio workspace model is not just a collection of unrelated screens.
|
||||
|
||||
Baseline workspace-framework rules are:
|
||||
|
||||
- a workspace should be built as a composition root plus lifecycle-managed child controls;
|
||||
- child controls should subscribe only to the workspace events or external state they actually consume;
|
||||
- local UI changes should be propagated through typed events and targeted patches where identity is preserved;
|
||||
- structural synchronization should be explicit and separate from local patch propagation;
|
||||
- whole-workspace refresh is a structural recovery path, not the default routine interaction path.
|
||||
|
||||
The baseline reusable workspace framework should cover at least:
|
||||
|
||||
- composition-root conventions;
|
||||
- lifecycle-managed event-subscriber controls;
|
||||
- projection-host patterns for list/tree/detail surfaces;
|
||||
- local-patch versus structural-sync orchestration rules.
|
||||
|
||||
The first concrete proving ground for this framework may be a single workspace, but the resulting framework is normative for future Studio workspace implementation.
|
||||
|
||||
Shared Studio foundations do not include:
|
||||
|
||||
- domain-specific workspace business logic;
|
||||
- speculative control catalogs;
|
||||
- unrelated non-visual infrastructure that does not directly serve Studio UI.
|
||||
|
||||
## Non-Goals
|
||||
|
||||
- defining the full event catalog in advance
|
||||
- defining every future workspace interaction
|
||||
- defining the first concrete control implementation wave in detail
|
||||
- allowing each workspace to define its own incompatible event/lifecycle model
|
||||
|
||||
## Exit Criteria
|
||||
|
||||
This specification is complete enough when:
|
||||
|
||||
- naming rules are stable enough to guide new Studio code;
|
||||
- the event topology is explicit;
|
||||
- the lifecycle and workspace-framework rules are explicit;
|
||||
- theme and i18n constraints are unambiguous for shared Studio UI work.
|
||||
@@ -0,0 +1,169 @@
|
||||
# Studio Components Module Specification
|
||||
|
||||
Status: Draft
|
||||
Scope: `prometeu-studio-components` role, admission policy, and JavaFX wrapping boundary
|
||||
Purpose: Define the authoritative visual control layer for the Studio.
|
||||
|
||||
## Authority and Precedence
|
||||
|
||||
This specification consolidates the accepted Studio components module decision into normative form.
|
||||
|
||||
## Normative Inputs
|
||||
|
||||
- `prometeu-studio-components`
|
||||
- Studio shell and workspace UI needs
|
||||
- JavaFX controls actively used by the Studio
|
||||
|
||||
## Core Rules
|
||||
|
||||
1. `prometeu-studio-components` is the official visual control module for Studio UI.
|
||||
2. Studio UI should normally consume visual controls from `prometeu-studio-components`, not directly from raw JavaFX.
|
||||
3. A control enters the module when it is needed by the current Studio UI wave.
|
||||
4. Controls in the module wrap and shape the JavaFX controls the Studio actively uses, but do not clone the full JavaFX API.
|
||||
5. Every admitted control must preserve theme and i18n compatibility.
|
||||
6. Reusable event-driven workspace controls should be admitted when they are part of the active Studio workspace framework.
|
||||
|
||||
## Module Role
|
||||
|
||||
`prometeu-studio-components` is:
|
||||
|
||||
- the authoritative Studio control layer;
|
||||
- the home of the Studio visual dialect;
|
||||
- the place where Studio-facing controls are shaped for Studio use;
|
||||
- the preferred home for reusable lifecycle-aware workspace controls when those controls are part of the visible Studio UI dialect.
|
||||
|
||||
`prometeu-studio-components` is not:
|
||||
|
||||
- a speculative generic framework;
|
||||
- a full reimplementation of JavaFX;
|
||||
- a dumping ground for unrelated non-visual infrastructure.
|
||||
|
||||
## Admission Policy
|
||||
|
||||
A control is admissible when it is needed by the current Studio UI work.
|
||||
|
||||
Rules:
|
||||
|
||||
- immediate current Studio use is sufficient justification;
|
||||
- a second use is not required when the control is clearly part of the shell or the current workspace surface;
|
||||
- no control should be added without an immediate Studio consumer.
|
||||
- a control needed first by one workspace may still be admitted when it is clearly intended as a reusable Studio workspace primitive.
|
||||
|
||||
## Studio Usage Rule
|
||||
|
||||
The baseline Studio UI should not rely on raw JavaFX controls as its normal visual surface.
|
||||
|
||||
Rules:
|
||||
|
||||
- a visual control used by Studio should normally come from `prometeu-studio-components`;
|
||||
- extremely trivial local composition may stay in `prometeu-studio`;
|
||||
- local exceptions must remain exceptional rather than becoming the default path.
|
||||
|
||||
## Wrapping Boundary
|
||||
|
||||
Controls in `prometeu-studio-components` must wrap the JavaFX controls the Studio actively uses.
|
||||
|
||||
Rules:
|
||||
|
||||
- the Studio-layer control should expose the Studio-facing API actually needed;
|
||||
- exhaustive mirroring of upstream JavaFX APIs is not required;
|
||||
- the goal is consistency and clarity, not a perfect one-to-one mirror of every JavaFX type.
|
||||
|
||||
## Control Lifecycle Hooks
|
||||
|
||||
Studio controls may need to observe event buses or other external state.
|
||||
|
||||
Rules:
|
||||
|
||||
- the control layer must provide explicit subscribe and unsubscribe lifecycle methods that can be overridden when needed;
|
||||
- the control layer should also provide `onAttached()` and `onDetached()` lifecycle hooks;
|
||||
- `onAttached()` should call `subscribe()`;
|
||||
- `onDetached()` should call `unsubscribe()`;
|
||||
- controls that attach subscriptions must also define how those subscriptions are released;
|
||||
- event-driven controls must not hide subscription lifecycle completely inside ad hoc local wiring.
|
||||
|
||||
These hooks exist so event-driven controls remain predictable and safe to embed in shell and workspace UI.
|
||||
|
||||
## Reusable Workspace Primitives
|
||||
|
||||
Some reusable controls are not shell-only and are not domain-specific either.
|
||||
|
||||
They may still belong in `prometeu-studio-components` when they are part of the visible Studio workspace framework.
|
||||
|
||||
Illustrative admissible examples include:
|
||||
|
||||
- projection hosts for list/tree/detail surfaces;
|
||||
- lifecycle-managed row or item controls;
|
||||
- reusable section or inspector surfaces;
|
||||
- visible controls that encode local-patch versus structural-sync interaction patterns.
|
||||
|
||||
What does not belong here:
|
||||
|
||||
- workspace-specific orchestration logic;
|
||||
- domain-specific service calls;
|
||||
- hidden coordination code with no visible control responsibility.
|
||||
|
||||
## Typical Control Scope
|
||||
|
||||
Typical controls that belong in the module include:
|
||||
|
||||
- shell controls;
|
||||
- action controls and buttons;
|
||||
- tab systems;
|
||||
- tree and list controls;
|
||||
- inspector and panel surfaces;
|
||||
- activity and feedback surfaces;
|
||||
- badges, headers, and related Studio primitives.
|
||||
|
||||
What stays outside the module:
|
||||
|
||||
- workspace-specific composition logic;
|
||||
- non-visual domain behavior;
|
||||
- speculative controls with no immediate Studio consumer.
|
||||
|
||||
## Theme and i18n
|
||||
|
||||
Every admitted control must support:
|
||||
|
||||
- CSS-based theming;
|
||||
- safe locale-aware text behavior when text is exposed;
|
||||
- no hardcoded user-facing text;
|
||||
- explicit visual states where state matters.
|
||||
|
||||
## Organization Guidance
|
||||
|
||||
The module should be organized by Studio role rather than vague technical buckets.
|
||||
|
||||
Illustrative areas include:
|
||||
|
||||
- shell;
|
||||
- actions;
|
||||
- navigation;
|
||||
- feedback;
|
||||
- inspection;
|
||||
- trees.
|
||||
|
||||
## Anti-Bloat Rule
|
||||
|
||||
The module must remain:
|
||||
|
||||
- intentional;
|
||||
- Studio-driven;
|
||||
- small enough to reason about;
|
||||
- broad enough to prevent UI entropy in the application.
|
||||
|
||||
## Non-Goals
|
||||
|
||||
- defining the first concrete component set in full detail
|
||||
- defining final package layout exhaustively
|
||||
- mirroring the entire JavaFX control hierarchy
|
||||
- storing domain-specific workspace orchestration code in the components module
|
||||
|
||||
## Exit Criteria
|
||||
|
||||
This specification is complete enough when:
|
||||
|
||||
- the module role is unambiguous;
|
||||
- admission rules are stable enough to guide implementation;
|
||||
- reusable workspace-control admission is clear enough to prevent local reimplementation drift;
|
||||
- the JavaFX wrapping boundary is clear enough to prevent drift.
|
||||
@@ -0,0 +1,364 @@
|
||||
# Assets Workspace Specification
|
||||
|
||||
## Status
|
||||
|
||||
Active
|
||||
|
||||
## Applies To
|
||||
|
||||
- `prometeu-studio`
|
||||
- the Studio `Assets` workspace
|
||||
- packer-facing Studio service integration for asset browsing, inspection, diagnostics, and staged mutations
|
||||
|
||||
## Purpose
|
||||
|
||||
Define the normative Studio contract for the `Assets` workspace.
|
||||
|
||||
This specification stabilizes:
|
||||
|
||||
- the information architecture of the workspace,
|
||||
- the navigation and selection model,
|
||||
- the selected-asset details structure,
|
||||
- the relationship between activity, progress, and logs,
|
||||
- and the preview/confirm/apply flow for sensitive mutations.
|
||||
|
||||
## Authority and Precedence
|
||||
|
||||
This specification extends:
|
||||
|
||||
- [`1. Studio Shell and Workspace Layout Specification.md`](1.%20Studio%20Shell%20and%20Workspace%20Layout%20Specification.md)
|
||||
- [`2. Studio UI Foundations Specification.md`](2.%20Studio%20UI%20Foundations%20Specification.md)
|
||||
- [`3. Studio Components Module Specification.md`](3.%20Studio%20Components%20Module%20Specification.md)
|
||||
|
||||
For packer-facing semantics, this specification must align with:
|
||||
|
||||
- [`../../packer/specs/1. Domain and Artifact Boundary Specification.md`](../../packer/specs/1.%20Domain%20and%20Artifact%20Boundary%20Specification.md)
|
||||
- [`../../packer/specs/2. Workspace, Registry, and Asset Identity Specification.md`](../../packer/specs/2.%20Workspace,%20Registry,%20and%20Asset%20Identity%20Specification.md)
|
||||
- [`../../packer/specs/3. Asset Declaration and Virtual Asset Contract Specification.md`](../../packer/specs/3.%20Asset%20Declaration%20and%20Virtual%20Asset%20Contract%20Specification.md)
|
||||
- [`../../packer/specs/5. Diagnostics, Operations, and Studio Integration Specification.md`](../../packer/specs/5.%20Diagnostics,%20Operations,%20and%20Studio%20Integration%20Specification.md)
|
||||
|
||||
If this document conflicts with the global Studio shell specifications, the shell specifications control shell-wide behavior and this document controls workspace-local behavior.
|
||||
|
||||
## Normative Inputs
|
||||
|
||||
The `Assets` workspace is a Studio view over packer services.
|
||||
|
||||
The workspace must assume:
|
||||
|
||||
- registered and unregistered assets may coexist inside `assets/`;
|
||||
- unregistered assets remain visible but excluded from builds;
|
||||
- assets may aggregate many internal inputs;
|
||||
- runtime-facing output contract data exists for each asset;
|
||||
- diagnostics, activity, progress, and staged mutation responses are available from Studio-facing services;
|
||||
- packer-facing operational freshness may surface states such as `healthy`, `stale`, `diverged`, `reconciling`, or `failed`.
|
||||
|
||||
Packer-backed operational events consumed by this workspace are expected to enter Studio through the container-owned typed event bus path rather than through workspace-local ad hoc bus creation.
|
||||
|
||||
## Workspace Model
|
||||
|
||||
The `Assets` workspace is:
|
||||
|
||||
- `asset-first`,
|
||||
- `path-aware`,
|
||||
- didactic toward the packer model,
|
||||
- and explicitly not a raw filesystem explorer clone.
|
||||
|
||||
The workspace must help the user understand:
|
||||
|
||||
- what the asset registration and build status are;
|
||||
- where the asset root lives;
|
||||
- which internal inputs belong to that asset;
|
||||
- what the asset declares toward the runtime-facing contract;
|
||||
- which operations are safe, staged, blocked, or destructive;
|
||||
- whether the current view reflects healthy, stale, diverged, or reconciling packer state.
|
||||
|
||||
The `Assets` workspace is also the first concrete consumer of the Studio event-driven workspace framework.
|
||||
|
||||
That means:
|
||||
|
||||
- `Assets` must prove the canonical Studio workspace architecture in real use;
|
||||
- reusable lifecycle and projection patterns extracted here should be consumable by future Studio workspaces;
|
||||
- `Assets` must not rely on a monolithic workspace root that redraws most of the UI after local interactions.
|
||||
|
||||
## Baseline Layout
|
||||
|
||||
The baseline workspace layout is:
|
||||
|
||||
- a custom `Asset Tree` / `Asset Navigator` on the left;
|
||||
- a selected-asset details area in the main panel;
|
||||
- inline diagnostics and action surfaces attached to the selected asset;
|
||||
- global `Activity` in the shell right-side utility area;
|
||||
- logs in the lower workspace region.
|
||||
|
||||
Filesystem structure may be visible and actionable as supporting context, but it is not the primary identity model of the workspace.
|
||||
|
||||
## Component Ownership Rules
|
||||
|
||||
The `Assets` workspace must be implemented as a composition root plus lifecycle-managed child controls.
|
||||
|
||||
Rules:
|
||||
|
||||
- the workspace root should coordinate service calls, workspace state, and structural synchronization;
|
||||
- the workspace root should not own the render and update path of every navigator row, details section, and form control directly;
|
||||
- the navigator host, asset rows, selected-asset details host, and details-internal sections/forms should subscribe only to the events and state they consume;
|
||||
- event-consuming controls must subscribe only while mounted in the UI tree;
|
||||
- reusable framework primitives should be consumed where the Studio already provides them instead of duplicating local refresh-oriented mechanisms.
|
||||
|
||||
## Asset Navigator Rules
|
||||
|
||||
### Primary Navigation Unit
|
||||
|
||||
- The primary navigation unit is the asset, not the raw file.
|
||||
- The navigator must not degrade into a generic file tree.
|
||||
- Grouping may reflect path or parent-folder structure, but asset nodes remain the primary navigable and selectable unit.
|
||||
|
||||
### Visual Rules
|
||||
|
||||
- The left navigation surface must be a custom `Asset Tree` / `Asset Navigator`.
|
||||
- Asset nodes must expose strong visual semantics through icons, badges, and state styling.
|
||||
- Asset nodes must surface:
|
||||
- registration status,
|
||||
- build participation,
|
||||
- diagnostics presence,
|
||||
- preload intent,
|
||||
- and broad asset family or type where available.
|
||||
- Path context may appear as secondary information.
|
||||
|
||||
### Filters and Search
|
||||
|
||||
- The baseline filters are:
|
||||
- `Registered`
|
||||
- `Unregistered`
|
||||
- `Diagnostics`
|
||||
- `Preload`
|
||||
- The navigator must support textual search.
|
||||
- Baseline search must cover at least:
|
||||
- `asset_name`
|
||||
- asset root path
|
||||
- path context
|
||||
|
||||
### Workspace Actions
|
||||
|
||||
- Workspace-scoped actions must appear above the main asset workspace split, not inside the navigator list region.
|
||||
- Workspace-scoped actions must not be mixed into the selected-asset details surface.
|
||||
- Workspace actions should remain visible without requiring a selected asset.
|
||||
- Global asset-manager actions such as `Add Asset`, `Doctor`, and `Pack` belong to this workspace-level action area.
|
||||
|
||||
### Navigator Actions
|
||||
|
||||
- Navigator-local controls may include search and filters that are specifically about asset discovery and navigation.
|
||||
|
||||
### Selection Rules
|
||||
|
||||
- The baseline navigator is single-select.
|
||||
- Registered asset selection must be preserved by `asset_id`.
|
||||
- Unregistered selection must be preserved by asset root path until the asset becomes registered.
|
||||
- If an asset changes state while preserving identity, selection must remain attached to it.
|
||||
- If the selected asset is removed from the navigator, selection must clear explicitly.
|
||||
- Selection must never silently drift to another asset due to refresh ordering.
|
||||
|
||||
### Local Rendering Rules
|
||||
|
||||
- The workspace must use event-directed local redraws for routine interactions.
|
||||
- The navigator host must react to projection-level events rather than whole-workspace rerender requests.
|
||||
- Asset row items should react to row-scoped patch and selection events when identity is preserved.
|
||||
- Selecting an asset must update navigator selection styling and the selected-asset details surface without rebuilding the entire workspace shell.
|
||||
- Search and filter changes must redraw the navigator projection only.
|
||||
- Details-local interactions such as preview input selection, preview zoom, or runtime-contract edits must redraw the selected-asset details surface only.
|
||||
- Structural operations such as asset creation, removal, relocation, or full workspace reload may rebuild both navigator and details projections.
|
||||
- Workspace-scoped progress and logging updates must not force navigator or selected-asset details redraw unless the underlying projection actually changed.
|
||||
|
||||
### State Rules
|
||||
|
||||
- The navigator must define explicit `loading assets` state.
|
||||
- The navigator must define explicit `no assets` state.
|
||||
- The navigator must define explicit `no results` state.
|
||||
- The navigator must define explicit `workspace error` state.
|
||||
- The workspace must define explicit operational freshness states when packer runtime divergence is surfaced.
|
||||
- Unregistered assets must appear in the same navigator flow as registered assets.
|
||||
- Unregistered styling must communicate `present but not yet registered`, not `broken`.
|
||||
|
||||
### Inputs Expansion
|
||||
|
||||
- Internal inputs may appear only as optional expansion or inspection surfaces.
|
||||
- Inputs must not replace asset nodes as the default navigation unit.
|
||||
|
||||
## Selected Asset Details Rules
|
||||
|
||||
The selected asset view must use this stable composition:
|
||||
|
||||
1. top row with `Summary` and `Actions` side by side
|
||||
2. `Runtime Contract`
|
||||
3. `Inputs / Preview`
|
||||
4. `Diagnostics`
|
||||
|
||||
This composition is stable across asset families.
|
||||
|
||||
The selected-asset details area must follow component-local ownership.
|
||||
|
||||
Rules:
|
||||
|
||||
- the details host should react to details lifecycle events such as loading, ready, and error;
|
||||
- details sections should update independently when only one section's projection changed;
|
||||
- forms and preview-local controls should publish and consume narrow typed events rather than trigger full details rebuild by default.
|
||||
|
||||
### Summary
|
||||
|
||||
- `Summary` must always be present for a selected asset.
|
||||
- `Summary` must show:
|
||||
- `asset_name`
|
||||
- registration status
|
||||
- build participation
|
||||
- `asset_id` when available
|
||||
- family/type
|
||||
- asset root path
|
||||
|
||||
### Runtime Contract
|
||||
|
||||
- `Runtime Contract` must present runtime-facing asset output data in short, didactic form.
|
||||
- `Runtime Contract` must surface:
|
||||
- `output.format`
|
||||
- `codec`
|
||||
- `preload`
|
||||
- Runtime-facing output information must not require raw JSON inspection.
|
||||
|
||||
### Inputs / Preview
|
||||
|
||||
- `Inputs / Preview` must expose internal inputs as part of the selected asset.
|
||||
- Inputs should be structured by role where that information is available.
|
||||
- Preview should be available for previewable materials such as:
|
||||
- images
|
||||
- palettes
|
||||
- audio
|
||||
- text
|
||||
- similar lightweight input artifacts
|
||||
- Preview of derived output may exist, but input preview has baseline priority.
|
||||
|
||||
### Diagnostics
|
||||
|
||||
- Diagnostics for the selected asset must appear inline in the selected asset view.
|
||||
- Blockers, warnings, and hints must be distinguishable.
|
||||
- Inline diagnostics must not be replaced by raw logs.
|
||||
|
||||
### Actions
|
||||
|
||||
- Actions must be explicit.
|
||||
- Actions that target the selected asset must appear beside `Summary`, not in the navigator area.
|
||||
- Safe and routine actions must be visually separated from sensitive mutations.
|
||||
- Hidden or automatic repair behavior is not allowed in the selected-asset view.
|
||||
- If packer surfaces stale/diverged/reconciling state, the selected-asset view may expose explicit refresh or reconcile-oriented actions, but it must not invent repair semantics locally.
|
||||
|
||||
## Action Rules
|
||||
|
||||
- Registered assets excluded from builds must expose an explicit `Include In Build` action.
|
||||
- Primary actions for unregistered assets include `Register`.
|
||||
- `Register` is a direct action in Studio UX. If registration is valid, clicking it must register immediately without an extra acknowledgement step.
|
||||
- If registration is blocked, Studio may surface the blocking preview inline so the user can inspect why registration cannot proceed.
|
||||
- Sensitive actions such as `Exclude From Build`, `Remove`, and `Relocate` must be visually separated from routine actions.
|
||||
- Sensitive actions must not look interchangeable with routine actions.
|
||||
- `Relocate` must collect an explicit user-chosen destination root before the staged preview is generated.
|
||||
- Automatic relocation targets are not sufficient Studio UX for `Relocate`.
|
||||
- `Exclude From Build` and `Remove` must confirm in a modal review surface rather than an inline staged panel.
|
||||
|
||||
## Activity, Progress, and Logs Rules
|
||||
|
||||
### Activity
|
||||
|
||||
- `Activity` belongs to the global right-side shell panel.
|
||||
- `Activity` is the structured operational timeline of the Studio.
|
||||
- Activity entries must be user-oriented rather than service-trace-oriented.
|
||||
- Repetitive background events must be aggregated or summarized.
|
||||
- Significant lifecycle milestones should remain visible in the feed.
|
||||
|
||||
### Progress
|
||||
|
||||
- Progress must be visible globally in the shell.
|
||||
- Progress may also appear inline when the current asset or action clearly owns that progress.
|
||||
- Progress tick events must update progress state rather than create feed spam.
|
||||
|
||||
### Logs
|
||||
|
||||
- Logs belong to the lower workspace region as detailed textual output.
|
||||
- Logs are secondary drill-down, not the primary explanation surface.
|
||||
- The user must not need raw logs to understand ordinary operational state.
|
||||
|
||||
### Failure Retention
|
||||
|
||||
- Recent actionable failures must remain visible until acknowledged.
|
||||
- Failures tied to the selected asset should also surface inline in the selected asset view.
|
||||
- Critical failures must not disappear merely because low-value events continue to arrive.
|
||||
|
||||
## Staged Mutation Rules
|
||||
|
||||
Sensitive asset mutations are `preview-first`.
|
||||
|
||||
The review surface depends on the mutation class.
|
||||
|
||||
Inline staged panels are allowed for non-destructive blocked or inspect-only flows.
|
||||
|
||||
Modal review and confirmation is required for `Exclude From Build`, `Remove`, and relocation commits.
|
||||
|
||||
Routine state patches such as `preload`, `Include In Build`, and `Exclude From Build` must patch the affected asset projection locally when identity is preserved. Full workspace refresh is reserved for operations that change workspace structure or identity resolution.
|
||||
|
||||
Operation orchestration must follow this rule:
|
||||
|
||||
- local patch when stable identity and local projection are preserved;
|
||||
- explicit structural sync when collection shape, identity, or projection membership changes;
|
||||
- no routine mutation path should fall back to whole-workspace refresh merely for implementation convenience.
|
||||
|
||||
### Mutations Requiring Preview
|
||||
|
||||
- `Exclude From Build`
|
||||
- `Remove`
|
||||
- relocational changes such as move or rename of asset roots
|
||||
- batch operations
|
||||
|
||||
Navigator-level `Doctor` and `Pack`, plus asset-level `Include In Build` and successful `Register`, remain outside this sensitive mutation staging flow.
|
||||
|
||||
### Preview Content
|
||||
|
||||
- Preview must show affected assets.
|
||||
- Relocation preview must show the planned target root chosen by the user.
|
||||
- Preview must show proposed actions.
|
||||
- Preview must distinguish registry impact from workspace impact.
|
||||
- Preview must show blockers, warnings, and safe fixes as separate visual sections.
|
||||
- Preview must show diff-style effects such as:
|
||||
- create
|
||||
- move
|
||||
- delete
|
||||
- registry update
|
||||
|
||||
### Apply Rules
|
||||
|
||||
- `Apply` must remain disabled while blockers exist.
|
||||
- Batch operations must present an aggregate summary first.
|
||||
- Batch operations may expose drill-down detail after the aggregate summary.
|
||||
- Destructive or relocational actions must not bypass preview.
|
||||
|
||||
### Activity Integration
|
||||
|
||||
- `preview_ready` should surface in global `Activity`.
|
||||
- `action_applied` should surface in global `Activity`.
|
||||
- `action_failed` should surface in global `Activity`.
|
||||
- reconcile or divergence state transitions should remain visible when they affect current workspace truth.
|
||||
- The preview itself remains a workspace-local review surface.
|
||||
|
||||
## Non-Goals
|
||||
|
||||
This specification does not define:
|
||||
|
||||
- the exact JavaFX component tree or control class structure of the `Assets` workspace;
|
||||
- final reusable component boundaries for all preview surfaces;
|
||||
- future multi-select or bulk-edit UX beyond the currently defined staged batch summary rules.
|
||||
|
||||
## Exit Criteria
|
||||
|
||||
This specification is satisfied when the Studio `Assets` workspace:
|
||||
|
||||
- navigates by assets rather than raw files;
|
||||
- preserves path awareness without collapsing into a file explorer;
|
||||
- explains the selected asset through summary, contract, inputs, diagnostics, and actions;
|
||||
- keeps activity, progress, and logs clearly separated;
|
||||
- stages sensitive mutations through preview-first flows;
|
||||
- proves the Studio event-driven workspace framework through lifecycle-managed local ownership;
|
||||
- and behaves as a didactic helper for the packer model.
|
||||
@@ -0,0 +1,65 @@
|
||||
# Studio Specs
|
||||
|
||||
This directory contains the normative Studio specification set.
|
||||
|
||||
## Purpose
|
||||
|
||||
Specs define the official Studio contract.
|
||||
|
||||
They exist to stabilize:
|
||||
|
||||
- the application shell,
|
||||
- workspace responsibilities,
|
||||
- interaction flows,
|
||||
- service and event integration expectations,
|
||||
- UX behavior that implementation should preserve.
|
||||
|
||||
## Expected Format
|
||||
|
||||
The exact structure may vary by document, but a Studio spec should usually contain:
|
||||
|
||||
1. Title
|
||||
2. Status
|
||||
3. Scope or Applies To
|
||||
4. Purpose
|
||||
5. Authority and Precedence
|
||||
6. Normative Inputs
|
||||
7. Core Rules
|
||||
8. Non-Goals
|
||||
9. Exit Criteria
|
||||
|
||||
## Writing Rules
|
||||
|
||||
- Write in normative language.
|
||||
- Integrate only decisions that have already been closed.
|
||||
- Keep design exploration and option analysis out of the spec body.
|
||||
- Preserve clear boundaries between shell, workspace, and integration specs.
|
||||
|
||||
## Upstream Rule
|
||||
|
||||
Specs should normally be fed by:
|
||||
|
||||
1. agendas that frame the open Studio topic,
|
||||
2. decisions that close the product or interaction choice,
|
||||
3. pull-request plans that define propagation,
|
||||
4. then spec integration.
|
||||
|
||||
If a spec edit would require guessing unresolved UI behavior, stop and surface the missing decision first.
|
||||
|
||||
## Current Corpus
|
||||
|
||||
The current Studio core corpus is:
|
||||
|
||||
1. [`1. Studio Shell and Workspace Layout Specification.md`](1.%20Studio%20Shell%20and%20Workspace%20Layout%20Specification.md)
|
||||
2. [`2. Studio UI Foundations Specification.md`](2.%20Studio%20UI%20Foundations%20Specification.md)
|
||||
3. [`3. Studio Components Module Specification.md`](3.%20Studio%20Components%20Module%20Specification.md)
|
||||
4. [`4. Assets Workspace Specification.md`](4.%20Assets%20Workspace%20Specification.md)
|
||||
|
||||
## Reading Order
|
||||
|
||||
Recommended order:
|
||||
|
||||
1. shell and workspace layout;
|
||||
2. shared UI foundations;
|
||||
3. components module policy;
|
||||
4. assets workspace behavior.
|
||||
Reference in New Issue
Block a user