discussion framework migration

This commit is contained in:
2026-03-26 18:45:46 +00:00
parent e78b72f61a
commit 38d8c25bba
90 changed files with 1150 additions and 2585 deletions
@@ -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.
@@ -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.
@@ -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.
@@ -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.
@@ -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.
+24
View File
@@ -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.
@@ -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.
+75
View File
@@ -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.
+65
View File
@@ -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.