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
-20
View File
@@ -1,20 +0,0 @@
# General Documentation
This directory contains documentation that applies to language implementations in general, not only PBS.
## Tree
```text
docs/general/
└── specs/
```
## Purpose
`general/specs` is the cross-language acceptance layer.
Use it to define:
- shared conformance and quality-gate contracts,
- shared compatibility and verification policy,
- and backend/runtime acceptance boundaries that are language-agnostic.
@@ -1,135 +0,0 @@
# 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.
@@ -1,405 +0,0 @@
# 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.
@@ -1,178 +0,0 @@
# 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.
@@ -1,155 +0,0 @@
# 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.
@@ -1,119 +0,0 @@
# 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.
@@ -1,188 +0,0 @@
# 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.
@@ -1,135 +0,0 @@
# 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.
@@ -1,174 +0,0 @@
# 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.
@@ -1,124 +0,0 @@
# 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.
@@ -1,113 +0,0 @@
# 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
@@ -1,24 +0,0 @@
# 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.
+27 -14
View File
@@ -2,22 +2,35 @@
This directory contains active PBS discussion agendas.
Closed agendas are moved to `docs/pbs/agendas/archive`.
Closed agendas are moved to `docs/compiler/pbs/agendas/archive`.
## Active Agendas
1. `18.0. Backend VM Pipeline - Orchestration Agenda.md`
2. `18.1. Backend Workshop 1 - IRBackend Input Contract.md`
3. `18.2. Backend Workshop 2 - LowerToIRVM and IRVM Contract.md`
4. `18.3. Backend Workshop 3 - Bytecode Marshaling and Runtime Conformance.md`
5. `18.4. Asset References in Game Code - Names vs Compile-Time Lowering Agenda.md`
6. `18.5. Ignored Call Results in Executable Lowering Agenda.md`
7. `19. Globals, Synthetic Module Init, and FRAME_RET Agenda.md`
8. `19.1. PBS Globals Surface, Identity, and Module Boundaries Agenda.md`
9. `19.2. PBS Lifecycle Markers, Program Init, and Frame Root Semantics Agenda.md`
10. `19.3. Published Entrypoint, Synthetic Wrapper, and FRAME_RET Ownership Agenda.md`
11. `19.4. Globals and Lifecycle Lowering to IRBackend-IRVM Agenda.md`
12. `19.5. Diagnostics, Manifest Propagation, and Conformance Coverage Agenda.md`
1. `18.4. Asset References in Game Code - Names vs Compile-Time Lowering Agenda.md`
2. `18.5. Ignored Call Results in Executable Lowering Agenda.md`
3. `19. Globals, Synthetic Module Init, and FRAME_RET Agenda.md`
4. `19.1. PBS Globals Surface, Identity, and Module Boundaries Agenda.md`
5. `19.2. PBS Lifecycle Markers, Program Init, and Frame Root Semantics Agenda.md`
6. `19.3. Published Entrypoint, Synthetic Wrapper, and FRAME_RET Ownership Agenda.md`
7. `19.4. Globals and Lifecycle Lowering to IRBackend-IRVM Agenda.md`
8. `19.5. Diagnostics, Manifest Propagation, and Conformance Coverage Agenda.md`
## Consolidated Agenda 18 Material
Agenda 18 backend-orchestration material (`18.0` through `18.3`) is no longer part of the active agenda set.
That slice has already been propagated into:
1. the backend execution plan in `docs/compiler/pbs/pull-requests/INDEX.md` under `Backend VM Pipeline PR Sequence (Agenda 18)`,
2. decision material such as `docs/compiler/pbs/decisions/IRVM Optimization Stage Placement Decision.md`,
3. normative backend specs:
- `docs/compiler/general/specs/19. Verification and Safety Checks Specification.md`,
- `docs/compiler/general/specs/20. IRBackend to IRVM Lowering Specification.md`,
- `docs/compiler/general/specs/21. IRVM Optimization Pipeline Specification.md`,
- `docs/compiler/general/specs/22. Backend Spec-to-Test Conformance Matrix.md`,
4. and implemented/tested backend pipeline stages in `prometeu-compiler/prometeu-build-pipeline`.
Only `18.4` and `18.5` remain open from the `18.*` family.
## Purpose
@@ -30,7 +43,7 @@ Use an agenda when:
- the scope and non-goals need to be made explicit,
- the order of discussion matters.
Move an agenda to `docs/pbs/agendas/archive` once the topic is no longer active.
Move an agenda to `docs/compiler/pbs/agendas/archive` once the topic is no longer active.
## Expected Format
@@ -1,94 +0,0 @@
# 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.
@@ -1,341 +0,0 @@
# 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.
@@ -1,160 +0,0 @@
# 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.
@@ -1,243 +0,0 @@
# 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.
@@ -1,210 +0,0 @@
# 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.
@@ -1,153 +0,0 @@
# 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
@@ -1,772 +0,0 @@
# 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.
@@ -1,452 +0,0 @@
# 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.
@@ -1,377 +0,0 @@
# 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.
@@ -1,560 +0,0 @@
# 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.
@@ -1,428 +0,0 @@
# 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.
@@ -1,248 +0,0 @@
# 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.
@@ -1,251 +0,0 @@
# 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.
@@ -1,356 +0,0 @@
# 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.
-59
View File
@@ -1,59 +0,0 @@
# 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`