changes on docs and specs

This commit is contained in:
2026-03-24 13:42:17 +00:00
parent 6befcade91
commit a8f06922db
57 changed files with 0 additions and 0 deletions
@@ -0,0 +1,95 @@
# Dynamic Semantics - Effect Surfaces Agenda
Status: Working agenda (pre-spec)
Purpose: close the runtime behavior of PBS effect and control surfaces before drafting the dynamic semantics spec
## 1. Context
PBS v1 already commits to several user-visible effect surfaces:
- `optional`,
- `result<E>`,
- `apply`,
- `bind`,
- `switch`,
- `if`,
- `else`,
- `handle`,
- `!` result propagation.
Static semantics explains where these forms are legal.
What is still missing is the runtime contract: evaluation timing, payload extraction behavior, propagation order, and interaction with traps and allocation.
## 2. Decisions to Produce
This agenda must end with decisions for:
1. The runtime value model of `optional` and `result<E>`.
2. The evaluation and propagation semantics of `apply`, `bind`, `else`, `!`, and `handle`.
3. The runtime branch-selection model for `if` and `switch`.
4. The exact boundary between explicit status values and true runtime traps.
## 3. Core Questions
### Q1. `optional`
- Is `some(expr)` evaluated eagerly before container construction?
- Does `opt else fallback` evaluate `fallback` only on `none`?
- Is `optional` guaranteed trap-free at runtime except for traps produced by evaluating its subexpressions?
### Q2. `result<E>`
- Is `ok(...)` / `err(...)` purely a return-flow construct with no standalone runtime value form in v1?
- How exactly does `expr!` propagate failure through the enclosing function?
- Does `handle expr { ... }` first evaluate `expr`, then dispatch exactly one remapping arm, or are there any hidden intermediate forms?
### Q3. `apply`
- Is direct-call sugar defined entirely through canonical `apply`, including runtime order?
- When `apply` resolves to a callback, method, contract implementation, or host-backed callable, what runtime steps are shared and what remains callable-specific?
- Must `apply` preserve a single common trap model regardless of callable kind?
### Q4. `bind`
- What runtime artifact does `bind(context, fn_name)` produce: a nominal callback pair, hidden object, or other VM-level value category?
- Is the `context` expression always evaluated exactly once at bind time?
- Does `bind` itself allocate, and if yes, must that be part of the visible cost contract?
### Q5. `switch` and `if`
- Is the selector/condition evaluated exactly once before branch selection?
- Does `switch` compare enum cases and scalar literals via a single equality model, or are there construct-specific rules?
- Are non-selected arm blocks guaranteed not to evaluate at all?
### Q6. Status values vs traps
- Which user-visible failures must stay in `optional` / `result` space instead of trapping?
- Are there any operations over these surfaces that may still trap despite their explicit effect model?
### Q7. Allocation and copy visibility
- Which of these constructs may allocate, copy, or retain heap state as part of normal execution?
- Which of those costs must be reflected later by the diagnostics spec?
## 4. Expected Spec Material
After discussion, this agenda should directly feed sections of `Dynamic Semantics Specification.md` covering:
1. runtime values and carrier forms,
2. call and callback execution,
3. effect propagation and remapping,
4. conditional and branching execution,
5. trap versus status-value behavior for effect-bearing constructs.
## 5. Non-Goals
- Revisiting the static typing surface already settled in `4. Static Semantics Specification.md`.
- Designing collection APIs or general async/error subsystems.
- Reopening reserved syntax such as future `match`.
## 6. Inputs
- `3. Core Syntax Specification.md`
- `4. Static Semantics Specification.md`
- `Heap Model - Agenda.md`
- `Dynamic Semantics - Execution Model Agenda.md`
@@ -0,0 +1,86 @@
# Dynamic Semantics - Execution Model Agenda
Status: Working agenda (pre-spec)
Purpose: close the observable execution model for PBS before drafting the dynamic semantics spec
## 1. Context
Static semantics already fixes a large part of the source model, but several runtime-visible questions remain open:
- exact evaluation order,
- what counts as a trap versus an ordinary control-flow outcome,
- how `FRAME_SYNC` and deterministic safepoints constrain execution,
- what host calls are allowed to observe or perturb execution order.
These decisions should be closed before effect surfaces and memory/lifetime rules are written as normative dynamic semantics.
## 2. Decisions to Produce
This agenda must end with decisions for:
1. The observable sequencing model for expressions, statements, and blocks.
2. The normative evaluation order for arguments, receivers, selectors, and chained `apply`.
3. The abrupt-completion model: `return`, `break`, `continue`, result propagation, and traps.
4. The interaction between host calls, safepoints, and deterministic execution.
## 3. Core Questions
### Q1. Global execution model
- Is PBS execution defined as single-threaded per program instance in v1?
- Which execution steps are observable to user code, and which remain VM-internal?
### Q2. Expression evaluation order
- Is expression evaluation strictly left-to-right unless a construct says otherwise?
- For `f(a, b)` / `f apply (a, b)`, what is the order of evaluating callee, receiver, and argument expressions?
- For `f1 apply f2 apply x`, what is the runtime order implied by the right-associative parse?
### Q3. Single-evaluation guarantees
- Which constructs normatively evaluate subexpressions exactly once?
- Does that guarantee apply to `switch` selectors, `if` conditions, `opt else fallback`, `handle expr`, and `bind(context, fn_name)` context expressions?
### Q4. Blocks and control transfer
- How are statement sequencing and tail-expression evaluation defined inside blocks?
- At what point does `return`, `break`, or `continue` abort further evaluation in the current construct?
### Q5. Trap model
- Which runtime failures are traps rather than status values or compile-time rejection?
- Must trap categories be stable and named in the dynamic semantics spec?
- Are traps deterministic for the same program input and runtime capability set?
### Q6. Host interaction
- Can host calls introduce extra traps beyond ordinary PBS runtime failures?
- Where are safepoints guaranteed around host calls, allocation-heavy operations, and loop back-edges?
### Q7. Determinism boundary
- Which behaviors must be identical across conforming implementations?
- Which details may vary as implementation strategy without changing observable behavior?
## 4. Expected Spec Material
After discussion, this agenda should directly feed sections of `Dynamic Semantics Specification.md` covering:
1. execution state and step ordering,
2. evaluation order by construct,
3. abrupt completion and trap propagation,
4. host-call interaction constraints,
5. determinism requirements for conforming runtimes.
## 5. Non-Goals
- Revisiting grammar or typing unless the current surface is impossible to specify dynamically.
- Defining diagnostics wording in detail.
- Designing allocator APIs or collection libraries.
## 6. Inputs
- `1. Language Charter.md`
- `3. Core Syntax Specification.md`
- `4. Static Semantics Specification.md`
- `Heap Model - Agenda.md`
+89
View File
@@ -0,0 +1,89 @@
# PBS Heap Model - Agenda
Status: Working umbrella agenda (pre-spec)
Purpose: coordinate the PBS discussions that define runtime-visible allocation, lifetime, and heap/host boundaries
## 1. Context
Legacy PBS experiments used explicit RC/HIP syntax (`alloc`, `borrow`, `mutate`, `peek`, `take`, `weak`).
Current runtime authority is GC-based with deterministic safepoints.
The original heap agenda proved too broad because the open questions now span three different but coupled areas:
- observable execution behavior,
- effect/control surfaces (`optional`, `result`, `apply`, `bind`, `switch`),
- memory ownership, GC, and host-memory boundaries.
This file now acts as the umbrella agenda that keeps those discussions aligned instead of trying to close every detail in one pass.
## 2. Agenda Split
The work is split into the following dedicated agendas:
1. `Dynamic Semantics - Execution Model Agenda.md`
2. `Dynamic Semantics - Effect Surfaces Agenda.md`
3. `Memory and Lifetime - Agenda.md`
The heap model is still the cross-cutting reference because allocation visibility, traps, and host boundaries must line up across all three.
## 3. Cross-Agenda Decisions This Umbrella Owns
This umbrella must keep the following decisions coherent across the child agendas:
1. GC is the baseline runtime model for PBS core unless a future profile explicitly says otherwise.
2. Core v1 does not require explicit lifetime syntax for ordinary user code.
3. Deterministic execution and `FRAME_SYNC` constraints override ergonomics when the two conflict.
4. Runtime-visible costs must be surfaced through diagnostics/tooling when code allocates, copies, crosses the host boundary, or can trap.
5. The VM heap and host-owned memory must remain distinct in the user model even when APIs make the boundary feel ergonomic.
## 4. Questions That Must Stay Aligned
### Q1. Baseline runtime authority
- Is GC always the default execution model for PBS core? (expected: yes)
- Which safepoints are part of the observable contract versus implementation detail?
### Q2. Language vs library boundary
- Which old RC/HIP concepts stay reserved-only in core syntax?
- Which advanced workflows move to stdlib/tooling APIs rather than language keywords?
### Q3. Cost visibility contract
- Which allocations, copies, host transfers, and trap paths must be visible in diagnostics?
- Which cost facts are normative, and which remain profiler-quality best effort?
### Q4. Host boundary
- How does PBS communicate "VM heap vs host-owned memory" without exposing raw host pointers as ordinary user values?
- Which host operations are allowed to allocate or retain memory, and how must that appear to the user?
### Q5. Migration policy
- What is the official migration story from legacy RC/HIP concepts?
- What hard criteria must be met before any reserved lifetime keyword can be activated in a future profile?
## 5. Expected Output Documents
After the child agendas close, use their decisions to draft:
1. `Dynamic Semantics Specification.md`
2. `Memory and Lifetime Specification.md`
3. `Diagnostics Specification.md`
The existing `4. Static Semantics Specification.md` may receive follow-up clarifications where memory or effect rules need stronger static wording.
## 6. Non-Goals for This Umbrella Agenda
- Defining new VM opcodes.
- Reintroducing RC as mandatory runtime strategy.
- Designing full stdlib memory-management APIs in this pass.
- Settling backend/lowering internals that do not affect observable semantics.
## 7. Working Assumptions
1. GC remains baseline for PBS core.
2. Explicit heap control is opt-in and likely library/tooling-driven.
3. Deterministic behavior and frame-sync constraints are non-negotiable.
4. Language should expose cost signals without forcing expert-only syntax.
5. Child agendas may narrow terminology, but they must not conflict on runtime-observable behavior.
@@ -0,0 +1,94 @@
# Memory and Lifetime - Agenda
Status: Working agenda (pre-spec)
Purpose: define the authoritative PBS memory, ownership, and lifetime model for v1
## 1. Context
PBS no longer exposes the old RC/HIP syntax as active core language, but the language still needs a precise memory story.
That story must explain:
- what values live on the VM heap,
- what identity and aliasing mean,
- how baseline GC interacts with deterministic execution,
- where host-owned memory begins and ends,
- how allocation and copy costs become visible to advanced users.
Without this agenda, the future `Memory and Lifetime Specification.md` would not have a stable scope.
## 2. Decisions to Produce
This agenda must end with decisions for:
1. The value-category map: stack-like transient values, heap-backed values, callbacks, collections, and host-backed handles.
2. The lifetime and reachability model under baseline GC.
3. The VM heap vs host-memory boundary and the user-visible rules at that boundary.
4. The minimum cost/allocation visibility contract needed by diagnostics and profiling.
5. The migration and reservation policy for legacy RC/HIP concepts.
## 3. Core Questions
### Q1. Heap residency by value category
- Which core values are heap-backed in v1: structs, callbacks, collections, tuples, `optional`, `result`, or only some of them?
- When a value is assigned, passed, or returned, what is copied versus what aliases the same heap identity?
### Q2. Identity and aliasing
- Which user-visible value kinds have stable identity?
- Are struct values always reference-like at runtime even when their fields are small and copyable?
- How should aliasing be described for beginner-facing semantics without hiding performance consequences?
### Q3. Baseline GC contract
- Which GC properties are normative: reachability, eventual reclamation, safepoints, no user finalizers?
- Which GC timing details remain non-normative implementation choices?
- Can user code observe reclamation directly, or only via indirect performance/diagnostic signals?
### Q4. Host memory boundary
- How are host-backed resources represented in PBS user space: opaque handles, nominal structs, services, or reserved host-bound values?
- Can host memory outlive PBS references, and if yes, what runtime contract prevents unsoundness?
- Is pinning, borrowing, or zero-copy transfer exposed in v1 at all?
### Q5. Allocation visibility
- Which operations are allowed to allocate on the VM heap?
- Which host calls may allocate host memory or retain VM-reachable references?
- What must tooling report as allocation, retention, copy, or escape risk?
### Q6. Lifetime-related traps and safety
- Which memory problems are impossible by construction in v1 core?
- Which remaining failures become traps, capability rejection, or host-defined status outcomes?
### Q7. Future explicit control
- Should pools, arenas, object reuse, or weak-reference patterns exist only as stdlib/tooling surfaces?
- What criteria must be met before reserved keywords like `alloc`, `borrow`, `take`, or `weak` can become active in a future profile?
## 4. Expected Spec Material
After discussion, this agenda should directly feed sections of `Memory and Lifetime Specification.md` covering:
1. runtime memory spaces,
2. value representation classes,
3. identity, aliasing, and copy rules,
4. GC and safepoint guarantees,
5. host-memory boundary rules,
6. cost visibility hooks for `Diagnostics Specification.md`.
## 5. Non-Goals
- Defining exact GC algorithm internals.
- Designing complete stdlib pool/arena APIs.
- Reintroducing mandatory user-authored lifetime syntax in core v1.
## 6. Inputs
- `1. Language Charter.md`
- `3. Core Syntax Specification.md`
- `4. Static Semantics Specification.md`
- `Heap Model - Agenda.md`
- `Dynamic Semantics - Execution Model Agenda.md`
- `Dynamic Semantics - Effect Surfaces Agenda.md`
+94
View File
@@ -0,0 +1,94 @@
# PBS Language Charter
Status: Draft v1
Applies to: Prometeu Base Script (PBS) language design
## 1. Mission
PBS exists to make 2D game development on Prometeu intuitive for beginners and reliable for experienced developers, without sacrificing deterministic runtime behavior.
## 2. Product Vision
PBS is a game-first language for a logical, evolving hardware platform.
It must feel fluid for frame-driven gameplay code while remaining strict enough to produce stable, verifiable bytecode for a closed VM target.
## 3. Target Users
- Beginner creators building their first playable 2D games.
- Intermediate developers shipping complete games with predictable behavior.
- Advanced developers who need explicit control of architecture and performance costs.
## 4. Core Principles
1. Game-first ergonomics: common gameplay patterns must be concise.
2. Determinism first: same program + same inputs/events => same behavior.
3. Explicit boundaries: host interaction, costs, and side effects must be visible.
4. Safe defaults: simple code paths should be hard to misuse.
5. Progressive power: advanced control is opt-in, not mandatory.
6. Compatibility discipline: language evolution must not silently break cartridges.
## 5. Scope of PBS v1
- Stable core syntax and grammar contract.
- Static and dynamic semantics for deterministic game code.
- Toolchain-managed host binding model aligned with syscall/capability model.
- Module visibility and import model suitable for multi-file game projects.
- Diagnostics and conformance requirements for interoperable implementations.
## 6. Out of Scope for PBS v1
- New VM opcodes as a language requirement.
- Non-deterministic async execution models.
- Mandatory custom allocator model replacing runtime GC.
- Advanced memory syntax (`alloc/borrow/mutate/...`) before explicit 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. Diagnostics Specification.
8. IR and Lowering Specification.
9. Conformance Test Specification.
10. Compatibility and Evolution Policy.
## 11. Decision Rule
When trade-offs appear, decisions must prioritize, in order:
1. Determinism and compatibility.
2. Clarity for beginners.
3. Fluency for real game workflows.
4. Performance transparency for advanced users.
@@ -0,0 +1,131 @@
# PBS Memory and Lifetime Specification
Status: Draft v0 (Skeleton)
Applies to: runtime memory spaces, value representation classes, identity, aliasing, GC baseline, and host-memory boundaries in PBS core
## 1. Purpose
This document will define 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 which values are heap-backed,
- 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 is intended to define:
- 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 is expected to be closed using decisions from:
- `docs/agendas/Heap Model - Agenda.md`
- `docs/agendas/Memory and Lifetime - Agenda.md`
- `docs/agendas/Dynamic Semantics - Execution Model Agenda.md`
- `docs/agendas/Dynamic Semantics - Effect Surfaces Agenda.md`
## 5. Already-Settled Inputs
The following inputs are already fixed elsewhere and must not be contradicted here:
- Struct values are heap-backed reference values in v1 core.
- Assigning a struct value copies the reference, not the underlying field storage.
- Service values are canonical module-owned singleton values in v1 core.
- Assigning a service value copies the same singleton identity and does not create a new instance.
- `declare const` values are compile-time constants rather than mutable runtime module storage.
- Advanced memory syntax such as `alloc`, `borrow`, `mutate`, `peek`, `take`, and `weak` is not active in PBS core v1.
## 6. Initial Section Targets
At minimum, the completed document should contain normative sections for:
1. runtime memory spaces,
2. value representation classes,
3. identity and aliasing,
4. copy and passing behavior,
5. GC guarantees and safepoint constraints,
6. host-memory boundary rules,
7. memory-related safety properties,
8. cost visibility hooks consumed by diagnostics/tooling.
## 7. A Ver
The following items remain to be closed in agenda discussion before this document can be considered complete.
### 7.1 `Memory and Lifetime - Agenda.md`
- Heap residency by value category beyond already-settled struct and service behavior.
- Which values have stable user-visible identity.
- Exact aliasing story for tuples, callbacks, collections, `optional`, and `result<E>`.
- Normative GC guarantees versus implementation-defined GC details.
- Representation and safety model of host-backed resources and handles.
### 7.2 `Heap Model - Agenda.md`
- Cross-cutting visibility of allocation, copy, retention, and host-boundary costs.
- Which memory facts are normative versus profiler-quality best effort.
- Migration policy and activation criteria for reserved lifetime keywords in future profiles.
### 7.3 `Dynamic Semantics - Execution Model Agenda.md` and `Dynamic Semantics - Effect Surfaces Agenda.md`
- Which constructs allocate or retain memory during ordinary execution.
- Which effect-bearing constructs may trap only because their subexpressions trap.
- Which safepoints are observable versus implementation detail.
## 8. 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.
## 9. Exit Criteria
This document is ready to move beyond skeleton status only when:
1. every core value category has an explicit representation and aliasing story,
2. GC guarantees and non-guarantees are separated clearly,
3. the VM heap versus host-memory boundary is normatively described,
4. memory-related costs are specified well enough for diagnostics/tooling hooks,
5. the document no longer relies on unresolved `A Ver` items for ordinary v1 behavior.
@@ -0,0 +1,133 @@
# PBS Diagnostics Specification
Status: Draft v0 (Skeleton)
Applies to: deterministic diagnostics emitted by PBS-facing tooling across parsing, static analysis, manifest/import resolution, lowering boundaries, and related load-facing validation surfaces
## 1. Purpose
This document will define the PBS diagnostics contract.
Its purpose is to make diagnostics stable enough that:
- conforming tools report failures in the same places,
- users receive deterministic and actionable feedback,
- conformance can validate not only acceptance/rejection but also diagnostic class and location,
- frontend, manifest, and load-facing validation remain aligned.
## 2. Scope
This document is intended to define:
- diagnostic categories and phases,
- minimum metadata carried by diagnostics,
- stability expectations for source spans, file attribution, and phase attribution,
- the normative relationship between syntax/static diagnostics and later lowering/load diagnostics,
- which diagnostics are required versus implementation-defined enrichments,
- cost-visibility diagnostics or warnings once memory/effect decisions are closed.
This document does not define:
- the full runtime trap catalog,
- UI presentation or IDE styling,
- implementation-specific hint ranking,
- profiling output 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. `12. IR and Lowering 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`
This document will also depend on decisions closed in:
- `9. Dynamic Semantics Specification.md`
- `10. Memory and Lifetime Specification.md`
- the future backend agenda sequence tracked in `docs/agendas/`
## 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.
## 6. Initial Section Targets
At minimum, the completed document should contain normative sections for:
1. diagnostic phases,
2. required diagnostic metadata,
3. span and file attribution,
4. syntax-diagnostic contract,
5. static-diagnostic contract,
6. manifest/import-resolution diagnostics,
7. lowering and host-binding diagnostics,
8. load-facing and capability diagnostics,
9. cost-visibility diagnostics and warnings.
## 7. A Ver
The following items remain to be closed before this document can be considered complete.
### 7.1 Depends on `9. Dynamic Semantics Specification.md`
- Which runtime-observable trap categories need source-facing compile-time or conformance hooks.
- Which constructs require special diagnostics for abrupt completion, propagation, or effect misuse beyond what static semantics already lists.
### 7.2 Depends on `10. Memory and Lifetime Specification.md`
- Which allocations, copies, escapes, and host-boundary crossings must surface as normative diagnostics or warnings.
- Which cost facts are mandatory versus implementation-defined enrichment.
### 7.3 Depends on the future backend agenda sequence tracked in `docs/agendas/`
- Whether diagnostic stability includes IR/lowering phase names, artifact offsets, or source maps.
- How host-binding lowering failures are surfaced back to source locations.
- Whether verifier/load diagnostics are part of the PBS diagnostics contract directly or only through artifact-facing tooling.
### 7.4 Still to decide inside this document
- Whether diagnostic codes are mandatory in v1.
- Which portions of human-readable wording are normative versus illustrative.
- Whether notes/help text are required, optional, or outside conformance.
- Exact cross-file diagnostic expectations for module/barrel/import failures.
## 8. Non-Goals
- Mandating one UI or IDE presentation style.
- Freezing a localization strategy in this pass.
- Turning every optimization hint into a normative diagnostic.
- Replacing the acceptance/rejection rules already defined elsewhere.
## 9. Exit Criteria
This document is ready to move beyond skeleton status only when:
1. every required rejection in the current spec set is mapped to a diagnostic phase,
2. diagnostic metadata and attribution rules are explicit enough for conformance,
3. cost-visibility expectations are aligned with memory/effect specs,
4. the document no longer relies on unresolved backend and runtime-facing `A Ver` items for v1 tooling behavior.
@@ -0,0 +1,136 @@
# PBS IR and Lowering Specification
Status: Draft v0 (Skeleton)
Applies to: lowering of bound PBS programs into internal compiler IR and runtime-facing artifacts
## 1. Purpose
This document will define the normative lowering contract from PBS source semantics to implementation artifacts.
Its purpose is to make backend-facing behavior explicit enough that:
- different compilers lower the same bound program compatibly,
- host-binding emission does not drift from frontend resolution,
- builtin and intrinsic lowering does not drift from VM-owned metadata,
- later verifier and loader behavior can rely on stable artifact expectations,
- conformance can test more than parser and binder behavior.
## 2. Scope
This document is intended to define:
- the minimum semantic obligations of the compiler after parsing, binding, and type checking,
- the role of internal IR as an implementation stage,
- what semantic facts lowering must preserve,
- lowering of control flow, calls, callbacks, services, contracts, constants, and host-backed calls,
- lowering of builtin projections, builtin constants, and intrinsic member calls,
- artifact-facing requirements that must hold before loader/verifier consumption.
This document does not define:
- the full PBX binary layout,
- optimizer heuristics or performance tuning strategy,
- the exact in-memory data structures of one compiler implementation,
- runtime GC algorithm internals.
## 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. `5. Manifest, Stdlib, and SDK Resolution Specification.md`
6. `6. VM-owned vs Host-backed.md`
7. `6.1. Intrinsics and Builtin Types Specification.md`
8. `6.2. Host ABI Binding and Loader Resolution Specification.md`
9. `9. Dynamic Semantics Specification.md`
10. `10. Memory and Lifetime Specification.md`
11. This document
If a lowering rule here contradicts a higher-precedence semantic rule, the higher-precedence rule 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. VM-owned vs Host-backed.md`
- `6.1. Intrinsics and Builtin Types Specification.md`
- `6.2. Host ABI Binding and Loader Resolution Specification.md`
- `9. Dynamic Semantics Specification.md`
- `10. Memory and Lifetime Specification.md`
This document is expected to be closed using a future backend agenda sequence tracked in `docs/agendas/`.
## 5. Already-Settled Inputs
The following inputs are already fixed elsewhere and must not be contradicted here:
- The compiler consumes reserved `Host` metadata while resolving host-backed SDK members.
- The compiler consumes reserved `BuiltinType`, `BuiltinConst`, `IntrinsicCall`, and `Slot` metadata while resolving builtin shells.
- The compiler emits canonical host-binding declarations into the PBX `SYSC` table.
- The compiler emits host-backed callsites in pre-load form as `HOSTCALL <sysc_index>`.
- `SYSC` entries are deduplicated by canonical identity and ordered by first occurrence.
- The loader, not the compiler, resolves canonical host bindings to final numeric syscall identifiers.
- Builtin projection lowering remains VM-owned and does not emit host-binding metadata.
- Builtin constants lower through VM-owned materialization rather than through ordinary compile-time constant evaluation.
- Builtin intrinsic member calls lower through a VM-owned intrinsic path rather than through `SYSC`, `HOSTCALL`, or `SYSCALL`.
- Stdlib interface modules are compile-time-only and do not emit executable bytecode by themselves.
## 6. Initial Section Targets
At minimum, the completed document should contain normative sections for:
1. lowering preconditions,
2. semantic obligations preserved by IR,
3. lowering of expressions and control flow,
4. lowering of callable categories,
5. lowering of `optional` and `result<E>` constructs,
6. lowering of callbacks, services, and contracts,
7. lowering of builtin projections, builtin constants, and builtin intrinsic calls,
8. host-binding emission,
9. artifact invariants required before verifier/loader stages.
## 7. A Ver
The following items remain to be closed before this document can be considered complete.
### 7.1 Depends on `9. Dynamic Semantics Specification.md`
- Which evaluation-order guarantees must be preserved explicitly in lowering.
- Which traps, abrupt completions, and propagation paths require dedicated lowered forms.
- Whether callback formation and contract dispatch need dedicated runtime artifacts or only implementation-defined IR shapes.
### 7.2 Depends on `10. Memory and Lifetime Specification.md`
- Which lowered operations allocate, alias, retain, or cross the host-memory boundary.
- Which runtime storage/identity facts IR must preserve explicitly versus infer later.
### 7.3 Depends on the future backend agenda sequence tracked in `docs/agendas/`
- Whether one canonical IR is normative or only the preserved semantic obligations are normative.
- The exact mapping from bound PBS constructs to PBX/bytecode-facing artifacts beyond already-settled host-binding and intrinsic behavior.
- Lowering strategy for services, contracts, callbacks, tuples, and result propagation.
- Whether declaration-based intrinsic preload forms such as `INTRCALL` are part of v1 lowering or whether compilers should emit final `INTRINSIC <id>` directly for a selected VM line.
- Which artifact invariants belong here versus a future dedicated PBX/bytecode mapping document.
## 8. Non-Goals
- Freezing one optimizer design.
- Requiring one compiler implementation architecture.
- Repeating the full bytecode ISA specification.
- Defining loader-side patching internals already owned elsewhere.
## 9. Exit Criteria
This document is ready to move beyond skeleton status only when:
1. every semantically distinct core construct has an explicit lowering story,
2. the boundary between source semantics, compiler IR, and emitted artifacts is clear,
3. host-binding emission is fully aligned with the Host ABI spec,
4. builtin and intrinsic lowering is fully aligned with the VM-owned builtin spec,
5. the document no longer relies on unresolved backend `A Ver` items for ordinary v1 lowering behavior.
@@ -0,0 +1,138 @@
# PBS Conformance Test Specification
Status: Draft v0 (Skeleton)
Applies to: conformance obligations, test categories, and acceptance criteria for PBS implementations
## 1. Purpose
This document will define the PBS conformance testing contract.
Its purpose is to make the specification operational by defining:
- what an implementation must demonstrate to claim conformance,
- which parts of the spec require positive versus negative tests,
- how deterministic diagnostics and runtime behavior are validated,
- how compatibility and version claims are checked.
## 2. Scope
This document is intended to define:
- conformance levels or profiles, if any,
- required test categories,
- expectations for syntax, static, manifest, lowering, loader, and runtime tests,
- diagnostic-conformance expectations,
- artifact and runtime fixtures needed for host-binding and capability-gating tests,
- compatibility-matrix conformance hooks.
This document does not define:
- one specific test runner implementation,
- CI policy for one repository,
- benchmark or performance certification,
- product release governance process.
## 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. `5. Manifest, Stdlib, and SDK Resolution Specification.md`
6. `6.2. Host ABI Binding and Loader Resolution Specification.md`
7. `7. Cartridge Manifest and Runtime Capabilities Specification.md`
8. `9. Dynamic Semantics Specification.md`
9. `10. Memory and Lifetime Specification.md`
10. `11. Diagnostics Specification.md`
11. `12. IR and Lowering Specification.md`
12. This document
This document must not weaken a normative requirement imposed by higher-precedence specs.
## 4. Normative Inputs
This document depends on, at minimum, the full active PBS v1 spec set.
In the current phase, it should be drafted against:
- `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`
It will require closure of:
- `9. Dynamic Semantics Specification.md`
- `10. Memory and Lifetime Specification.md`
- `11. Diagnostics Specification.md`
- `12. IR and Lowering Specification.md`
## 5. Already-Settled Inputs
The following inputs are already fixed elsewhere and must not be contradicted here:
- The parser must behave deterministically.
- Syntax and static semantics already enumerate minimum required rejection cases.
- Import/manifest failures are required to be deterministic.
- Loader failures for malformed or unauthorized host usage are required to be deterministic.
- Governance requires conformance updates before release.
- Compatibility claims must be reflected in a published compatibility matrix.
## 6. Initial Section Targets
At minimum, the completed document should contain normative sections for:
1. scope of conformance,
2. implementation claims and version domains,
3. required positive parsing/binding/type-checking tests,
4. required negative syntax/static tests,
5. manifest/import-resolution tests,
6. dynamic-semantics runtime tests,
7. host-binding and capability-gating tests,
8. diagnostics-conformance tests,
9. compatibility and regression test expectations.
## 7. A Ver
The following items remain to be closed before this document can be considered complete.
### 7.1 Depends on `9. Dynamic Semantics Specification.md` and `10. Memory and Lifetime Specification.md`
- Exact runtime-oracle model for observable evaluation order, traps, and effect behavior.
- Which memory/aliasing facts must be tested directly versus only through diagnostics/tooling hooks.
### 7.2 Depends on `11. Diagnostics Specification.md`
- Whether conformance checks diagnostic codes, spans, categories, wording classes, or only rejection phase and location.
- Which warnings or cost diagnostics are in conformance scope.
### 7.3 Depends on `12. IR and Lowering Specification.md`
- Whether artifact-level conformance is required in addition to source-level conformance.
- Which emitted host-binding and lowering invariants require golden tests.
### 7.4 Still to decide inside this document
- Whether PBS v1 has one conformance level or staged claims such as frontend-only versus full toolchain.
- Fixture strategy for stdlib environments, host registries, and capability-grant scenarios.
- How compatibility-matrix claims are validated across language/profile/stdlib domains.
## 8. Non-Goals
- Replacing the normative specs with tests as the primary authority.
- Forcing one repository layout or one test harness.
- Treating performance benchmarking as language conformance.
- Inventing new language rules through test-only precedent.
## 9. Exit Criteria
This document is ready to move beyond skeleton status only when:
1. every active PBS v1 spec has a corresponding conformance surface,
2. positive and negative obligations are clearly separated,
3. diagnostics and runtime behavior have explicit oracle expectations,
4. compatibility and version claims can be tested rather than asserted informally,
5. the document no longer relies on unresolved `A Ver` items for the intended conformance level.
@@ -0,0 +1,169 @@
# PBS Name Resolution and Module Linking Specification
Status: Draft v0 (Skeleton)
Applies to: scope formation, name lookup, imports, exports, barrel visibility, cross-module resolution, and semantic linking of PBS programs
## 1. Purpose
This document will define the normative name-resolution and semantic-linking model for PBS.
## 2. Scope
This document is intended to define:
- scope formation and lookup order,
- namespace separation and collision rules,
- import and export resolution,
- barrel-mediated visibility and module linking,
- cross-file and cross-module symbol resolution,
- resolution of reserved stdlib shells for host-backed and VM-owned surfaces,
- linkage-time rejection conditions before lowering.
This document does not define:
- runtime execution behavior,
- optimizer or backend internals,
- full PBX binary linking.
## 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. `18. Standard Library Surface Specification.md`
7. 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`
- `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.
- 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.
## 6. Initial Section Targets
At minimum, the completed document should contain normative sections for:
1. scope construction,
2. lookup order by namespace,
3. import and alias resolution,
4. barrel export matching and linking,
5. reserved stdlib shell resolution for builtin and host-backed surfaces,
6. duplicate and shadowing rules,
7. cross-module resolution failures.
## 7. A Ver
The following items remain to be closed in future agenda discussion.
- Exact lookup order across local bindings, top-level declarations, imports, and reserved intrinsic surfaces.
- Whether shadowing rules differ by namespace or declaration kind.
- Whether semantic linking is fully part of static semantics or split into a distinct phase contract.
- Exact rejection model for ambiguous cross-module overload visibility and barrel-linked callable sets.
- Whether stdlib/interface-module linking imposes extra restrictions beyond ordinary modules.
- Whether builtin shell declarations may be synthesized by the toolchain in addition to being provided by stdlib modules.
## 8. Non-Goals
- Reopening the already-settled import surface syntax.
- Defining runtime loader behavior.
- Freezing one compiler symbol-table implementation.
## 9. Exit Criteria
This document is ready to move beyond skeleton 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 ambiguity and failure cases are normatively defined,
5. the document no longer relies on unresolved `A Ver` items for ordinary v1 resolution behavior.
## 10. Reserved Stdlib Shell Resolution
Reserved stdlib modules may expose compile-time-only declarations that do not
behave like ordinary user-authored implementation bodies.
Rules:
- `declare host` surfaces exported from reserved stdlib modules resolve in the host-owner namespace.
- `declare builtin type` surfaces exported from reserved stdlib modules resolve in the type namespace.
- builtin constants exported from reserved stdlib modules resolve in the value namespace.
- builtin intrinsic methods are not imported as free functions; they are resolved through the imported builtin type declaration of the receiver type.
- canonical host identity is not derived from the imported host owner spelling,
- and canonical builtin/intrinsic identity is not derived solely from the imported builtin type spelling.
Example:
- importing `Vec2` from `@core:math` may introduce the PBS-visible type name `Vec2`,
- while the declaration's metadata may still lower that type to canonical builtin identity `("vec2", 1)`.
## 11. Import and Barrel Rules for Builtin Shells
Builtin shells follow ordinary module visibility rules at the source level and
special metadata rules at lowering time.
Rules:
- a builtin type, builtin constant, or host owner may be imported only if it is exported through the target module's `mod.barrel`,
- aliasing an imported builtin type changes only the source-visible local name, not the canonical builtin identity declared by metadata,
- aliasing an imported builtin constant changes only the local binding name, not the canonical builtin constant identity declared by metadata,
- aliasing an imported host owner changes only the source-visible local name, not the canonical host identity declared by `Host(...)`,
- barrel matching for builtin declarations is declaration-based rather than executable-body based,
- and resolution must complete before lowering begins.
## 12. Lookup Order for Builtin and Intrinsic Surfaces
Lookup remains namespace-based.
Rules:
- type-position lookup considers visible builtin type declarations alongside other visible type declarations,
- value-position lookup considers visible builtin constants alongside other visible values,
- callable lookup does not treat builtin intrinsic members as top-level callable declarations,
- member lookup on a builtin-typed receiver considers builtin projection fields first as field-like surfaces of that builtin declaration,
- method lookup on a builtin-typed receiver considers builtin intrinsic member signatures declared by that builtin shell,
- and host-owner lookup remains separate from builtin type lookup.
This preserves the distinction between:
- imported builtin type shells,
- imported host owners,
- and compiler-recognized intrinsic method surfaces on existing core forms such as `optional` and enums.
## 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. ambiguous cross-module visibility of builtin declarations after barrel resolution,
5. duplicate visible builtin type declarations that claim the same canonical builtin identity in one resolved environment,
6. duplicate visible builtin constants that claim the same canonical builtin constant identity in one resolved environment,
7. member lookup on a builtin receiver where the imported builtin shell does not declare the requested field or intrinsic member,
8. any resolution path that attempts to derive host or builtin canonical identity from alias spelling alone.
@@ -0,0 +1,92 @@
# PBS Bytecode and PBX Mapping Specification
Status: Draft v0 (Skeleton)
Applies to: mapping from lowered PBS programs into PBX sections, bytecode-facing artifacts, and related source-to-artifact invariants
## 1. Purpose
This document will define the normative mapping between lowered PBS semantics and emitted PBX/bytecode-facing artifacts.
## 2. Scope
This document is intended to define:
- artifact-level obligations after lowering,
- mapping of semantic constructs into PBX-visible structures,
- source-to-artifact invariants required by verifier and loader stages,
- interaction points with host-binding metadata such as `SYSC`,
- interaction points with VM-owned builtin and intrinsic metadata.
This document does not define:
- the full bytecode ISA,
- UI/tooling presentation,
- one compiler's internal IR representation.
## 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. `6.1. Intrinsics and Builtin Types Specification.md`
4. `6.2. Host ABI Binding and Loader Resolution Specification.md`
5. `12. IR and Lowering 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:
- `6.1. Intrinsics and Builtin Types Specification.md`
- `6.2. Host ABI Binding and Loader Resolution Specification.md`
- `12. IR and Lowering Specification.md`
## 5. Already-Settled Inputs
The following inputs are already fixed elsewhere and must not be contradicted here:
- The compiler emits host-binding declarations into 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` into `SYSCALL`.
- VM-owned builtin projections, builtin constants, and intrinsic callsites do not emit host-binding metadata.
- VM-owned intrinsic artifacts are distinct from `SYSC`, `HOSTCALL`, and `SYSCALL`.
## 6. Initial Section Targets
At minimum, the completed document should contain normative sections for:
1. artifact mapping goals,
2. section-level invariants,
3. callsite and control-flow mapping invariants,
4. metadata mapping obligations,
5. intrinsic and builtin artifact obligations,
6. source-attribution hooks for diagnostics/conformance.
## 7. A Ver
The following items remain to be closed in future agenda discussion.
- Which PBX sections beyond `SYSC` are part of the PBS-facing contract.
- Whether a distinct intrinsic declaration section is part of the PBS-facing contract in v1.
- Which source-level constructs require dedicated artifact patterns versus implementation freedom.
- How much of artifact ordering, numbering, and layout is normative at PBS level versus owned purely by PBX authority.
- Whether compilers should emit final `INTRINSIC <id>` directly for a selected VM line or may emit a declaration-based preload form such as `INTRCALL <decl_index>`.
- Whether a separate debug/source-map surface is part of v1.
## 8. Non-Goals
- Repeating the full PBX or ISA documentation.
- Mandating one binary-emitter implementation strategy.
- Defining loader patching internals already owned elsewhere.
## 9. Exit Criteria
This document is ready to move beyond skeleton status only when:
1. the PBS-to-artifact boundary is explicit,
2. artifact-level invariants needed by verifier and loader are normative,
3. the document no longer relies on unresolved `A Ver` items for ordinary v1 artifact mapping behavior.
@@ -0,0 +1,91 @@
# PBS Runtime Execution and Initialization Specification
Status: Draft v0 (Skeleton)
Applies to: runtime startup, entry behavior, module/service initialization, and execution lifecycle of PBS programs after successful load
## 1. Purpose
This document will define the runtime execution and initialization contract for PBS programs.
## 2. Scope
This document is intended to define:
- entry and startup behavior,
- initialization ordering relevant to PBS-visible semantics,
- lifecycle of module-owned and service-owned runtime state,
- execution boundaries before, during, and after frame-driven program operation,
- runtime assumptions that are neither purely dynamic semantics nor purely loader behavior.
This document does not define:
- loader-side host resolution,
- full packaging format,
- scheduler models outside v1 execution assumptions.
## 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.
- Service values are canonical module-owned singleton values.
- Top-level executable statements are forbidden in PBS source modules.
## 6. Initial Section Targets
At minimum, the completed document should contain normative sections for:
1. execution entry assumptions,
2. initialization ordering,
3. service singleton runtime lifecycle,
4. runtime frame and step boundaries,
5. failure and non-start conditions.
## 7. A Ver
The following items remain to be closed in future agenda discussion.
- Exact runtime entry contract between loaded artifact and PBS-visible program behavior.
- Whether module initialization exists as a distinct semantic phase in v1 beyond load success.
- When service singleton state becomes initialized and observable.
- Which runtime lifecycle boundaries are observable to user code versus VM-internal.
- Whether shutdown/finalization behavior has any PBS-visible contract in v1.
## 8. Non-Goals
- Defining OS/process lifecycle outside Prometeu runtime authority.
- Reopening the ban on top-level executable statements.
- Designing a future async runtime.
## 9. Exit Criteria
This document is ready to move beyond skeleton status only when:
1. runtime startup and initialization order are normatively described,
2. service and module runtime lifecycle assumptions are explicit,
3. execution lifecycle boundaries are aligned with dynamic semantics and runtime authority,
4. the document no longer relies on unresolved `A Ver` items for ordinary v1 runtime startup behavior.
@@ -0,0 +1,90 @@
# PBS Compatibility and Evolution Policy
Status: Draft v0 (Skeleton)
Applies to: compatibility commitments, migration boundaries, deprecation discipline, and evolution constraints across PBS language and related domains
## 1. Purpose
This document will define the normative compatibility and evolution policy for PBS.
## 2. Scope
This document is intended to define:
- compatibility promises across language, profile, stdlib, and artifact domains,
- migration boundaries for additive versus incompatible changes,
- deprecation and removal policy details,
- behavioral versus binary compatibility expectations,
- obligations when publishing changes that affect older cartridges or projects.
This document does not define:
- one repository's release workflow,
- one implementation's branching strategy,
- detailed changelog formatting.
## 3. Authority and Precedence
Normative precedence:
1. `1. Language Charter.md`
2. `2. Governance and Versioning.md`
3. Runtime and bytecode authority where applicable
4. 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`
- `2. Governance and Versioning.md`
- `6.2. Host ABI Binding and Loader Resolution Specification.md`
- `7. Cartridge Manifest and Runtime Capabilities Specification.md`
## 5. Already-Settled Inputs
The following inputs are already fixed elsewhere and must not be contradicted here:
- Additive-first evolution is preferred for minor releases.
- Incompatible changes belong only in major lines with migration guidance.
- Canonical host primitive versioning uses `(module, name, version)`.
- Toolchains must reject unsupported targets deterministically.
- Older supported cartridges are expected to keep running across updates.
## 6. Initial Section Targets
At minimum, the completed document should contain normative sections for:
1. compatibility domains,
2. behavioral versus binary compatibility,
3. deprecation windows,
4. migration obligations,
5. compatibility-matrix expectations,
6. artifact and runtime compatibility boundaries.
## 7. A Ver
The following items remain to be closed in future agenda discussion.
- Exact compatibility window by domain.
- Whether PBX/binary compatibility has an independent policy track from source-level compatibility.
- How stdlib-line compatibility interacts with dependency projects over time.
- Which changes require migration tooling versus documentation-only migration notes.
- Whether frontend-only phased implementation claims need distinct compatibility labels.
## 8. Non-Goals
- Replacing governance with ad hoc decisions.
- Defining one product release calendar.
- Freezing every editorial clarification as a compatibility event.
## 9. Exit Criteria
This document is ready to move beyond skeleton status only when:
1. compatibility commitments are explicit by domain,
2. deprecation and migration duties are normatively described,
3. source, stdlib, artifact, and runtime compatibility boundaries are separated clearly,
4. the document no longer relies on unresolved `A Ver` items for ordinary v1 compatibility claims.
@@ -0,0 +1,185 @@
# 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.
- 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. A Ver
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 `A Ver` 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 method signatures carry `Host(...)`,
- user code may import those host owners through ordinary stdlib module imports,
- and lowering continues through canonical host identity, `SYSC`, `HOSTCALL`, loader resolution, and final `SYSCALL`.
## 13. Stdlib Contract Expectations for Builtin MVP
For the current builtin MVP, stdlib should be able to expose at least:
1. a builtin type shell for `Color`,
2. a builtin type shell for `Vec2`,
3. a builtin type shell for `Pixel`,
4. a builtin constant shell for `vec2.zero`,
5. and any associated documentation-level or teaching-level module organization needed to make those surfaces discoverable.
Illustrative example:
```pbs
import { Vec2, ZERO } from @core:math;
```
The imported names are source-visible conveniences.
Their canonical runtime-facing identities still come from builtin metadata such
as `BuiltinType(name="vec2", version=1)` and
`BuiltinConst(target="vec2", name="zero", version=1)`.
## 14. Deterministic Stdlib Surface Failures
At minimum, a conforming implementation must reject:
1. a stdlib builtin shell that attempts to use host-binding metadata for VM-owned intrinsic behavior,
2. a stdlib host shell that attempts to use builtin metadata in place of host-binding metadata,
3. a user-facing stdlib module that exports executable PBS bodies for builtin semantics,
4. a stdlib line that exposes conflicting canonical builtin identities through the same resolved environment,
5. a stdlib line that exposes conflicting canonical host identities through the same resolved environment.
@@ -0,0 +1,88 @@
# PBS Verification and Safety Checks Specification
Status: Draft v0 (Skeleton)
Applies to: verifier-facing safety obligations, artifact validation boundaries, and the division of safety checks across compiler, loader, verifier, and runtime
## 1. Purpose
This document will define the verification and safety-check model relevant to PBS-produced artifacts.
## 2. Scope
This document is intended to define:
- which safety obligations are enforced before runtime execution,
- the division of responsibility across compiler, loader, verifier, and runtime,
- verifier-facing assumptions about already-lowered artifacts,
- safety properties that must hold for conforming PBS-produced images.
This document does not define:
- full runtime trap semantics,
- source-language typing rules already owned elsewhere,
- one verifier 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. `6.2. Host ABI Binding and Loader Resolution Specification.md`
4. `12. IR and Lowering Specification.md`
5. `15. Bytecode and PBX Mapping 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:
- `6.2. Host ABI Binding and Loader Resolution Specification.md`
- `12. IR and Lowering Specification.md`
- `15. Bytecode and PBX Mapping Specification.md`
## 5. Already-Settled Inputs
The following inputs are already fixed elsewhere and must not be contradicted here:
- Loader-side ABI validation is mandatory.
- Capability gating is mandatory during load.
- The verifier runs after loader patching on the final numeric executable image.
- Loader and verifier validate different layers of the contract.
## 6. Initial Section Targets
At minimum, the completed document should contain normative sections for:
1. safety-check phase boundaries,
2. compiler-emitted safety assumptions,
3. loader-side safety checks,
4. verifier-side safety checks,
5. residual runtime safety assumptions,
6. required deterministic rejection conditions.
## 7. A Ver
The following items remain to be closed in future agenda discussion.
- Exact verifier obligations beyond what is already implied by runtime/bytecode authority.
- Which safety properties must be proven before execution versus checked defensively at runtime.
- Whether PBS-level conformance includes explicit verifier test surfaces or only artifact validity outcomes.
- How source-level diagnostics relate to verifier and artifact-level safety failures.
## 8. Non-Goals
- Replacing runtime or bytecode authority.
- Duplicating the full Host ABI spec.
- Freezing one verifier implementation algorithm.
## 9. Exit Criteria
This document is ready to move beyond skeleton status only when:
1. the division of safety responsibilities is explicit,
2. verifier-facing assumptions are aligned with lowering and artifact mapping,
3. deterministic rejection surfaces are normatively described,
4. the document no longer relies on unresolved `A Ver` items for ordinary v1 safety claims.
@@ -0,0 +1,152 @@
# 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.
## 12. Conflict Resolution
When maintainers disagree, the tie-breaker is:
1. determinism and compatibility,
2. clarity for beginners,
3. implementation feasibility and tooling stability.
## 13. Non-Goals
- Replacing runtime authority with governance-only decisions.
- Defining subsystem-specific API semantics in this document.
- Granting implementation behavior override over normative specs.
File diff suppressed because it is too large Load Diff
@@ -0,0 +1,760 @@
# 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`, `BuiltinType`, `BuiltinConst`, `IntrinsicCall`, and `Slot`.
- `Host` 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.
- `Slot` is valid only on a field declaration in the header of a reserved `declare builtin type`.
- 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` 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.
- 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.
- A builtin field `Slot` attribute, when present, MUST declare a non-negative integer literal and must match the declaration's canonical flattened layout.
- `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.
- The stored context follows normal value semantics for its type.
- `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(...)` do not denote ordinary value expressions in v1 core.
- `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`.
- Each mapped error path on the right side of a `handle` arm must resolve to a declared case of `E2`.
- `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.
- On error, `handle` performs an immediate enclosing-function return with the mapped `err(...)`.
### 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 `BuiltinType` attribute target,
- invalid `BuiltinConst` attribute target,
- invalid `IntrinsicCall` attribute target,
- invalid `Slot` 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`,
- 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`,
- invalid builtin field `Slot(...)`,
- overlapping builtin field slot range,
- builtin field type not builtin-layout-admissible,
- 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 `return`,
- 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`,
- attempted use of a single-slot tuple literal where no such surface form exists,
- member access on a missing struct field,
- read access to an inaccessible private struct field,
- write access to an inaccessible or non-`pub mut` struct field,
- member access on a missing struct method,
- member access on a missing service method,
- member access on a missing host method,
- member access on a missing contract method,
- member access on a missing builtin projection field,
- member access on a missing builtin intrinsic member,
- bare method extraction from a struct, service, host, builtin, or contract value,
- member projection on a single-slot carrier value,
- invalid optional intrinsic member call,
- invalid builtin intrinsic member call,
- member projection on a missing named output label.
@@ -0,0 +1,451 @@
# 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`,
- and compile-time-only host-binding metadata attached to those reserved modules.
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 and do not emit executable bytecode.
10. `declare host` remains reserved to stdlib/toolchain interface modules.
11. Reserved attributes such as `[Host(...)]` are compile-time metadata, not runtime objects.
12. The compiler consumes `Host` metadata to produce runtime-facing host-binding artifacts defined elsewhere.
@@ -0,0 +1,377 @@
# VM-owned vs Host-backed
Status: Draft v1 (Temporary)
Applies to: ownership classification of PBS-visible operations, runtime boundary selection, and the normative distinction between VM-defined semantics and host-provided services
## 1. Purpose
This document defines the normative distinction between:
- VM-owned operations,
- host-backed operations,
- and user-defined program operations.
Its purpose is to prevent semantic drift between:
- builtin language behavior,
- VM execution behavior,
- host/platform integration,
- and source-level surfaces that may look similar while belonging to different ownership domains.
This document exists because PBS must distinguish at least three different kinds
of callable behavior:
- program-owned functions,
- VM-owned intrinsic behavior,
- host-backed services.
Without this distinction, the language would conflate:
- builtin semantics with syscalls,
- source-level shells with runtime authority,
- and VM contracts with host capability-gated services.
## 2. Scope
This document defines:
- the ownership model for callable behavior visible to PBS programs,
- the normative difference between VM-owned and host-backed operations,
- the runtime boundary crossed by each operation category,
- the relationship between ownership and lowering form,
- the relationship between ownership and determinism,
- the relationship between ownership and capability checks,
- the relationship between ownership and loader resolution,
- and the classification rule used to decide whether a surface belongs to the VM or to the host.
This document does not define:
- the full parser grammar for builtin declarations,
- the full intrinsic registry binary format,
- the final PBX section numbering for intrinsic metadata,
- subsystem-specific host APIs such as GFX or AUDIO,
- or the complete dynamic semantics of every builtin type.
## 3. Authority and Precedence
Normative precedence:
1. Runtime authority (`docs/specs/hardware/topics/chapter-2.md`, `chapter-3.md`, `chapter-9.md`, `chapter-12.md`, `chapter-16.md`)
2. Bytecode authority (`docs/specs/bytecode/ISA_CORE.md`)
3. `1. Language Charter.md`
4. `3. Core Syntax Specification.md`
5. `4. Static Semantics Specification.md`
6. `5. Manifest, Stdlib, and SDK Resolution Specification.md`
7. `6.2. Host ABI Binding and Loader Resolution Specification.md`
8. This document
If a rule here conflicts with higher-precedence authority, the higher-precedence
authority wins.
## 4. Normative Inputs
This document depends on, at minimum:
- `1. Language Charter.md`
- `3. Core Syntax Specification.md`
- `4. Static Semantics Specification.md`
- `5. Manifest, Stdlib, and SDK Resolution Specification.md`
- `6.2. Host ABI Binding and Loader Resolution Specification.md`
## 5. Core Ownership Model
PBS distinguishes three ownership categories for callable behavior.
### 5.1 Program-owned function
A program-owned function is authored by the program and compiled from a PBS body.
Properties:
- semantic ownership belongs to the program,
- execution stays inside the VM,
- source definition includes an executable body,
- runtime dispatch uses ordinary function-call machinery,
- authority does not depend on host capability grants.
### 5.2 VM-owned operation
A VM-owned operation is part of the semantic contract of the PBS platform.
Properties:
- semantic ownership belongs to the VM platform,
- execution stays inside the VM,
- behavior is not defined by user-authored PBS bodies,
- behavior is not resolved against host registries,
- behavior is not granted or denied by host capabilities,
- and behavior is expected to remain semantically canonical across conforming implementations.
VM-owned operations include, at minimum:
- intrinsic operations over builtin types,
- compiler-recognized intrinsic method-call surfaces over core semantic forms,
- and other future VM-defined semantic helpers explicitly designated by spec.
### 5.3 Host-backed operation
A host-backed operation is provided by the runtime environment outside the VM's
closed semantic domain.
Properties:
- semantic authority belongs to the host platform,
- execution crosses the VM-to-host boundary,
- resolution uses canonical host identity,
- loader validation and capability checks are required before execution,
- and the final executable form is numeric host dispatch.
Host-backed operations are the domain of `declare host`, PBX `SYSC`, loader
resolution, and final `SYSCALL`.
## 6. The Boundary Question
The normative classification question is:
```text
Does this operation belong to the VM's semantic contract, or does it require a
service owned by the external host platform?
```
Rules:
- If the operation expresses builtin language or VM semantics, it is VM-owned.
- If the operation requires host-provided authority, devices, or platform services, it is host-backed.
- If the operation is implemented by ordinary source code in the current program, it is program-owned.
Heuristic:
- if the operation must still have a complete meaning in a host-minimal VM, it is VM-owned,
- if the operation loses meaning without external platform service, it is host-backed.
Examples:
- `Vec2.dot(other)` is VM-owned,
- `Color.rgb(r, g, b)` is VM-owned,
- `optional.hasSome()` is VM-owned,
- `enumValue.name()` is VM-owned,
- `Gfx.draw_pixel(x, y, c)` is host-backed,
- `Input.is_pressed(button)` is host-backed.
## 7. Runtime Boundary and Resolution Model
### 7.1 VM-owned operations
VM-owned operations do not cross the host boundary.
Rules:
- they do not resolve through the host syscall registry,
- they do not emit `SYSC`,
- they do not require loader-side capability checks,
- they are not represented by `declare host`,
- and they execute through VM-owned machinery such as intrinsic dispatch or other VM-defined execution paths.
### 7.2 Host-backed operations
Host-backed operations cross the VM boundary and require host authority.
Rules:
- they resolve by canonical host identity `(module, name, version)`,
- they are represented in source through reserved host-binding surfaces,
- they emit PBX host-binding metadata,
- they are validated against authoritative host metadata during load,
- and they execute in final form through `SYSCALL`.
## 8. Semantic Authority
The semantic owner of an operation is the layer that defines its normative
meaning.
### 8.1 VM-owned semantic authority
For VM-owned operations:
- the VM platform defines the operation's meaning,
- the frontend may expose shell declarations but does not define behavior,
- the host runtime must not redefine the operation's language-level semantics,
- and the HAL may consume produced values but must not own their semantic definition.
### 8.2 Host-backed semantic authority
For host-backed operations:
- the host platform defines the authoritative service identity and ABI,
- the frontend exposes a compile-time shell only,
- the loader resolves the shell's canonical identity against the host registry,
- and the VM executes only the numeric form after loader patching.
## 9. Determinism and Environmental Dependence
Determinism requirements differ by ownership category.
### 9.1 VM-owned operations
VM-owned operations must not derive meaning from host service behavior.
Rules:
- a VM-owned operation must not call the host as part of its semantic definition,
- a VM-owned operation must not require host capability grants,
- a VM-owned operation must not depend on wall-clock time unless a higher-precedence authority explicitly allows it,
- a VM-owned operation must not depend on frontend-generated helper algorithms for its canonical behavior,
- and the VM contract must be specific enough that conformance can test its behavior.
This does not require every VM-owned operation to be mathematically pure.
It does require the operation's meaning to be owned and specified by the VM
contract rather than delegated to the host.
### 9.2 Host-backed operations
Host-backed operations may depend on host state, devices, permissions, or
platform policy.
Rules:
- host-backed operations may be denied by capability policy,
- host-backed operations may vary by platform implementation within their ABI contract,
- and host-backed operations are not reclassified as VM-owned merely because the source surface resembles an ordinary method call.
## 10. Artifact Implications
Ownership classification determines artifact form.
### 10.1 Program-owned function artifact direction
Program-owned functions lower to ordinary program call machinery.
### 10.2 VM-owned artifact direction
VM-owned operations lower to VM-facing artifacts.
Illustrative forms:
- direct intrinsic ids such as `INTRINSIC <id>`,
- temporary intrinsic declaration tables plus pre-resolution callsites,
- or other VM-internal runtime forms explicitly defined by future spec.
Rules:
- VM-owned operations must not be encoded as host-binding metadata merely because they are not authored in user code,
- and VM-owned operations must not require host registry lookup.
### 10.3 Host-backed artifact direction
Host-backed operations lower to host-facing artifacts.
Rules:
- host-backed operations emit host-binding declarations into `SYSC`,
- host-backed callsites use `HOSTCALL <sysc_index>` before load,
- the loader resolves and patches those callsites,
- and final execution uses `SYSCALL <id>`.
## 11. Source Surface Similarity Does Not Collapse Ownership
Two source surfaces may look similar while belonging to different ownership
domains.
Examples:
- `Vec2.length()` may be VM-owned,
- `Gfx.clear(color)` may be host-backed,
- `value.name()` over an enum may be VM-owned,
- and `service.method()` may be program-owned or service-owned ordinary PBS behavior.
Rules:
- source-level method-call syntax does not determine ownership,
- declaration shape does not determine ownership,
- ownership is determined by semantic authority and runtime boundary,
- and toolchain metadata must classify the operation explicitly where ambiguity could arise.
## 12. Relationship to `declare host`
`declare host` is reserved exclusively for host-backed surfaces.
Rules:
- `declare host` must not be reused to model VM-owned builtin semantics,
- host attributes such as `Host(module, name, version)` must not be used to identify VM-owned intrinsic behavior,
- and a source surface that represents VM-owned behavior must use VM-specific metadata and lowering rules.
Rationale:
- `declare host` communicates external service ownership,
- host attributes communicate loader-facing canonical identity,
- and reusing them for VM-owned behavior would incorrectly imply host resolution, capability gating, and host semantic authority.
## 13. Relationship to Builtin Types and Intrinsics
Builtin types are VM-facing semantic types.
Rules:
- builtin types are not host APIs,
- builtin type operations that belong to the builtin domain are VM-owned,
- builtin constants, projections, constructors, and intrinsic methods are classified by VM semantics rather than by host service ownership,
- and builtin values may later be passed to host-backed operations without transferring semantic ownership of the type itself.
Example:
- `Color` is VM-owned as a semantic type,
- `Color.rgb(...)` is VM-owned,
- `Pixel` may contain `Color` in its builtin layout,
- `Gfx.draw_pixel(x, y, c)` is host-backed even when `c` has a VM-owned builtin type.
## 14. Relationship to `stdlib` and SDK Surfaces
`stdlib` and SDK packaging expose compile-time surfaces.
Rules:
- SDK or stdlib shells may expose both VM-owned and host-backed surfaces,
- shell placement alone does not determine runtime ownership,
- the runtime-facing artifact contract must preserve the true ownership category,
- and compile-time convenience must not collapse VM-owned and host-backed operations into the same runtime mechanism.
## 15. Classification Checklist
When introducing a new callable surface, the spec author or toolchain author
must answer at least these questions:
1. Who owns the semantic meaning of this operation?
2. Does the operation require host-provided authority, devices, or policy?
3. Must the loader resolve the operation against an external registry?
4. Can the operation be denied by capabilities?
5. Should the operation continue to exist with complete meaning in a host-minimal VM?
6. Is the operation part of builtin language semantics rather than platform service integration?
Classification rule:
- If answers 2, 3, or 4 are yes, the operation is host-backed.
- If answer 6 is yes and 2, 3, and 4 are no, the operation is VM-owned.
- Otherwise the operation is program-owned unless another spec defines a distinct category.
## 16. Conformance Expectations
Conforming implementations must preserve the ownership boundary.
Rules:
- an implementation must not lower VM-owned builtin semantics through the host syscall pipeline,
- an implementation must not treat host-backed operations as if they were VM-defined intrinsic semantics,
- an implementation must preserve the loader-facing host-binding contract for host-backed surfaces,
- and an implementation must preserve VM-facing semantic ownership for builtin and intrinsic operations.
## 17. Current Decision Summary
The current model is:
1. Program-authored functions are program-owned and execute through ordinary call machinery.
2. Builtin semantics and intrinsic behavior are VM-owned.
3. External platform services are host-backed.
4. VM-owned behavior must not be modeled as `declare host`.
5. Host-backed behavior must continue to use canonical host identity, `SYSC`, loader resolution, and final `SYSCALL`.
6. Ownership is determined by semantic authority and runtime boundary, not by source-level syntax resemblance.
@@ -0,0 +1,555 @@
# 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,
- and the runtime-facing artifact direction for intrinsic operations.
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`
- `12. IR and Lowering 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.
## 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(
[Slot(0)] pub x: float,
[Slot(1)] 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. `Slot` Metadata
`Slot(n)` identifies the starting flattened slot offset of a builtin field within
the enclosing builtin layout.
Rules:
- `n` is zero-based,
- `Slot(n)` refers to the starting slot offset after flattening nested builtin-layout-admissible fields,
- slot offsets must be unique,
- slot offsets must match the declaration's canonical flattened layout,
- and overlapping slot ranges are invalid.
`Slot` exists to make canonical layout explicit.
Future grammar may allow offset inference by declaration order, but explicit slot
metadata is valid and authoritative in this temporary contract.
## 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(
[Slot(0)] pub raw: int,
);
[BuiltinType(name="pixel", version=1)]
declare builtin type Pixel(
[Slot(0)] pub x: int,
[Slot(1)] pub y: int,
[Slot(2)] 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(
[Slot(0)] pub x: float,
[Slot(1)] 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. duplicate or overlapping slot assignments,
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. mismatched declared field slot metadata versus flattened layout,
11. executable member bodies inside builtin declarations,
12. any lowering that routes VM-owned builtin operations through the host-binding pipeline.
## 23. Current Decision Summary
The current temporary contract is:
1. Builtin types are VM-owned semantic types exposed through reserved shell declarations.
2. `BuiltinType(name, version)` maps source-visible type names to canonical VM builtin identities.
3. Builtin fields describe projection surfaces over canonical flattened layout.
4. Builtin field types must be builtin-layout-admissible and stack-only in this feature set.
5. Builtin types may contain other builtin-layout-admissible types, including nested builtin composition such as `Pixel` containing `Color`.
6. `IntrinsicCall(name, version?)` identifies VM-owned intrinsic member behavior and inherits owner identity from the enclosing builtin type.
7. `BuiltinConst(target, name, version)` exposes VM-owned builtin constants through reserved top-level `declare const` shells.
8. Builtin projections, constants, and intrinsic calls must not lower through `SYSC`, `HOSTCALL`, or `SYSCALL`.
9. Runtime-facing intrinsic artifacts are distinct from host-binding artifacts.
@@ -0,0 +1,426 @@
# 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)]
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,
- the cartridge manifest declares requested capabilities using a nominal capability list,
- the loader derives or receives the granted capability set from the cartridge/platform policy environment,
- if a required capability is not granted, load fails,
- the loader must fail before the program begins execution.
The compiler may infer which capabilities are required by the emitted `SYSC` table, but it does not grant authority.
Authority belongs to the cartridge/platform loading environment.
Runtime capability checks may still exist defensively in the VM, but they do not replace mandatory load-time validation.
## 13. Verifier Interaction
The loader and the verifier validate different layers of the contract.
Loader responsibilities:
- validate canonical host identity resolution,
- validate `SYSC`-declared ABI shape against host metadata,
- validate capabilities,
- patch `HOSTCALL <sysc_index>` into `SYSCALL <id>`.
Verifier responsibilities:
- run on the already-patched executable image,
- validate stack safety and control-flow safety,
- treat `SYSCALL <id>` exactly like any other final numeric instruction,
- derive stack effects from authoritative runtime syscall metadata.
This is intentional and not considered harmful duplication:
- the loader checks interface compatibility,
- the verifier checks structural correctness of the final program.
## 14. Execution Model After Load
After successful load:
- the VM executes numeric syscall identifiers only,
- runtime dispatch must not depend on canonical strings,
- canonical names exist only in PBX metadata and loader-side resolution,
- the runtime-facing execution form remains `SYSCALL <id>`.
This preserves the hardware contract:
- canonical identity is used for declaration and linking,
- numeric identity is used for execution.
## 15. Deterministic Loader Errors
The loader must fail deterministically for at least the following cases:
1. missing `SYSC` section,
2. malformed `SYSC` payload,
3. invalid UTF-8 in canonical names,
4. duplicate `(module, name, version)` declarations,
5. unknown canonical identity,
6. ABI mismatch between `SYSC` declaration and host registry metadata,
7. capability mismatch,
8. `HOSTCALL` references an out-of-bounds `sysc_index`,
9. a declared `SYSC` entry is unused by all `HOSTCALL` instructions,
10. a `HOSTCALL` remains in the executable image after loader patching,
11. any internal inconsistency between parsed host-binding metadata and the loader's host registry contract.
Diagnostics should identify the failing canonical identity whenever available.
## 16. Relationship to `stdlib`
`stdlib` selection is a compile-time concern that determines which SDK surfaces and host-backed declarations the compiler may use.
Rules:
- the loader does not resolve source imports such as `@sdk:gfx`,
- the loader only consumes canonical host-binding metadata emitted into the PBX,
- `stdlib` affects the loader indirectly through what the compiler emitted,
- the loader must not attempt to reconstruct SDK/module semantics from the PBX.
In other words:
- `stdlib` selects the compile-time SDK contract,
- `SYSC` carries the runtime-facing host-binding contract.
## 17. Relationship to Cartridge Manifest Capabilities
The cartridge manifest is the current declarative source for requested runtime capabilities.
Rules:
- cartridge capability declarations are external to `program.pbx`,
- capability declarations are serializable nominal identifiers such as `gfx` or `audio`,
- the loader converts that nominal declaration into the internal capability flag set used by the runtime,
- the loader MUST NOT infer granted authority solely from the presence of `SYSC` entries.
This keeps authority separate from code generation:
- PBX declares what the program needs,
- cartridge packaging declares what the cartridge requests,
- the loader/runtime environment decides what is granted.
## 18. Current Implementation Direction
This document aligns with the current Prometeu direction:
- SDK/toolchain-controlled `declare host` surfaces define host-backed APIs,
- the compiler emits canonical host-binding declarations into PBX `SYSC`,
- the compiler emits `HOSTCALL <sysc_index>` in pre-load code,
- the loader resolves those declarations at cartridge load,
- the loader patch-rewrites host calls to numeric syscalls,
- the VM continues to execute numeric syscalls only.
## 19. Open Items Deferred
The following remain deferred:
1. final PBX section numbering and chunk registry policy,
2. exact binary opcode allocation for `HOSTCALL`,
3. whether the loader patches bytecode in place or rebuilds a fresh executable image buffer,
4. final cartridge policy model when platform-level grants differ from manifest requests,
5. final chunk numbering and binary compatibility policy for PBX versions that predate mandatory `SYSC`,
6. final integration shape with `ProgramImage` or another loaded-program container.
## 20. Current Decision Summary
The current temporary contract is:
1. Host bindings are identified canonically by `(module, name, version)`.
2. `declare host` is reserved to SDK/toolchain modules and is compile-time surface only.
3. The compiler emits a unique, deduplicated `SYSC` table ordered by first occurrence.
4. Each `SYSC` entry carries `module`, `name`, `version`, `arg_slots`, and `ret_slots`.
5. The compiler emits host-backed call sites as `HOSTCALL <sysc_index>`.
6. The loader parses `SYSC` before execution.
7. The loader resolves canonical identities against the host registry during load.
8. The loader validates `arg_slots` and `ret_slots` against authoritative host metadata.
9. The loader enforces capability gating during load.
10. The loader rejects out-of-bounds and unused `SYSC` references.
11. The loader rewrites every `HOSTCALL <sysc_index>` into `SYSCALL <id>`.
12. The verifier runs after patching and validates the final numeric program.
13. The VM executes numeric syscall identifiers only.
@@ -0,0 +1,246 @@
# 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": "main",
"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,
- `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>`,
- does not grant authority.
Packer:
- produces the cartridge manifest,
- declares requested runtime capabilities,
- packages `manifest.json`, `program.pbx`, and assets.
Loader:
- reads the manifest,
- derives or receives granted capability flags,
- validates those capabilities against PBX host requirements.
## 10. Validation Rules
The cartridge manifest must fail validation if:
1. `capabilities` contains an unknown name,
2. `capabilities` contains duplicates,
3. `capabilities` is not an array of strings or nominal enum values under the chosen serialization form.
Cartridge load must fail if:
1. the manifest omits a capability required by a resolved `SYSC` entry,
2. a future platform policy denies a capability required by a resolved `SYSC` entry.
## 11. Serialization Guidance
The recommended manifest-facing model is a nominal enum list, not numeric masks.
Recommended JSON:
```json
{
"capabilities": ["gfx", "input", "audio"]
}
```
Rejected as normative surface:
- raw integer bitmasks,
- hex masks,
- unnamed positional arrays.
Rationale:
- nominal capability names are readable,
- manifest diffs remain understandable,
- packer and tooling validation is straightforward,
- runtime may still use bitflags internally after conversion.
## 12. Current Decision Summary
The current temporary contract is:
1. `manifest.json` is the cartridge-facing load descriptor.
2. `capabilities` is declared in `manifest.json`, not in `prometeu.json`.
3. `capabilities` uses nominal canonical names such as `gfx` and `audio`.
4. The runtime may keep using internal `CapFlags`.
5. The loader converts nominal manifest capabilities into internal flags.
6. PBX `SYSC` declares required host bindings, not authority.
7. Loader validation fails if PBX host requirements exceed granted cartridge capabilities.
@@ -0,0 +1,251 @@
# PBS Stdlib Environment Packaging and Loading Specification
Status: Draft v1 (Temporary)
Applies to: Studio PBS frontend stdlib packaging, stdlib environment discovery, reserved stdlib project spaces, and compiler-side stdlib loading abstractions
## 1. Purpose
This document defines a practical packaging and loading model for the PBS stdlib environment inside the Studio compiler frontend.
Its purpose is to make the stdlib:
- available to the compiler without hardcoded symbol tables,
- structured as real PBS interface modules,
- versioned by stdlib major line,
- and loadable through explicit compiler abstractions.
This document complements the normative language-level model in:
- [5. Manifest, Stdlib, and SDK Resolution Specification.md](/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/studio/docs/specs/pbs/5.%20Manifest,%20Stdlib,%20and%20SDK%20Resolution%20Specification.md)
## 2. Scope
This document defines:
- the recommended Studio packaging layout for stdlib interface modules,
- the logical mapping between stdlib line, reserved project space, and module path,
- the minimum compiler abstractions required to load stdlib modules,
- the relationship between `resources` packaging and the logical stdlib environment.
This document does not define:
- runtime loader behavior,
- PBX emission,
- registry publication of stdlib packs,
- final external distribution of stdlib outside Studio.
## 3. Core Model
The compiler must load stdlib modules as real interface modules, not as hardcoded built-ins.
Rules:
- the stdlib is selected by the root project's `stdlib` major,
- each stdlib line defines one stdlib environment,
- a stdlib environment exposes reserved project spaces such as `@sdk:*` and `@core:*`,
- each reserved project space contains one or more modules,
- each module is represented as PBS source plus `mod.barrel`.
## 4. Recommended Studio Packaging Layout
The recommended Studio layout is:
```text
prometeu-compiler/frontends/prometeu-frontend-pbs/
src/main/resources/
stdlib/
1/
sdk/
gfx/
main.pbs
mod.barrel
audio/
main.pbs
mod.barrel
core/
math/
main.pbs
mod.barrel
```
Interpretation:
- `stdlib/1` selects stdlib major line `1`,
- `sdk` and `core` are reserved project spaces,
- `gfx`, `audio`, `math` are module paths within those reserved spaces,
- `main.pbs` and `mod.barrel` form the interface module contents.
## 5. Logical Mapping
The compiler must treat the physical layout as a logical stdlib environment.
Required mapping:
- `stdlib/<N>/sdk/gfx` -> `@sdk:gfx`
- `stdlib/<N>/sdk/audio` -> `@sdk:audio`
- `stdlib/<N>/core/math` -> `@core:math`
- `stdlib/<N>/core/math/vector` -> `@core:math/vector`
Rules:
- physical storage is an implementation detail,
- logical module identity is authoritative,
- callers of the resolver should work with logical addresses such as `@sdk:gfx`, not resource paths.
## 6. Module File Convention
For the Studio implementation, each stdlib module should follow the same structural convention as ordinary PBS modules:
- one or more `.pbs` files,
- exactly one `mod.barrel`.
Recommended minimum convention:
- `main.pbs`
- `mod.barrel`
Rules:
- `main.pbs` is a convention, not a language-level requirement,
- the module remains an ordinary PBS module from the parser's perspective,
- it is interpreted under interface-module semantics because it lives in a reserved stdlib project space.
## 7. Required Compiler Abstractions
The compiler should not reach directly into `resources` paths throughout the frontend.
At minimum, the PBS frontend should define abstractions equivalent to:
### 7.1 `StdlibEnvironment`
Responsibility:
- represent the selected stdlib line for one compilation,
- expose reserved project spaces,
- provide access to interface modules by logical module address.
Minimum operations:
- select stdlib major line,
- answer whether a reserved project space exists,
- open a module by logical address.
### 7.2 `StdlibModuleResolver`
Responsibility:
- resolve logical imports in reserved project spaces,
- map `@sdk:*` and `@core:*` imports to concrete interface module sources,
- reject unknown stdlib modules deterministically.
Minimum operations:
- `resolve(@sdk:gfx)`
- `resolve(@core:math/vector)`
### 7.3 `StdlibModuleSource`
Responsibility:
- represent the source files of one stdlib module,
- provide access to the module's `.pbs` files and `mod.barrel`,
- hide whether content came from disk, `resources`, or another source.
Minimum contents:
- module address
- list of `.pbs` source texts or streams
- `mod.barrel` source text or stream
### 7.4 `InterfaceModuleLoader`
Responsibility:
- parse a stdlib module source using the normal PBS parser,
- validate it in interface-module mode,
- return compiler-facing symbols and metadata.
Minimum outputs:
- exported symbols
- declared types
- host owners
- host method signatures
- reserved attribute metadata such as `[Host(...)]`
## 8. Loading Algorithm
The recommended Studio compiler flow is:
1. read the root `prometeu.json`,
2. parse and normalize `stdlib`,
3. construct `StdlibEnvironment` for that stdlib major,
4. create a `StdlibModuleResolver`,
5. when an import targets a reserved project space, resolve it through the stdlib resolver,
6. obtain a `StdlibModuleSource`,
7. parse the module with the standard PBS parser,
8. validate it under interface-module semantic rules,
9. cache the resulting interface module graph for the duration of the compilation.
Rules:
- reserved stdlib modules must not be handled through ordinary dependency resolution,
- ordinary dependency modules must not be handled through the stdlib resolver,
- a failed stdlib import is a deterministic compile-time error.
## 9. Attributes and Interface Metadata
Stdlib interface modules may contain reserved compile-time attributes such as:
```pbs
declare host Gfx {
[Host(module = "gfx", name = "draw_pixel", version = 1)]
fn draw_pixel(x: int, y: int, c: color);
}
```
Rules:
- the parser reads the attribute as part of the interface module source,
- the interface-module loader validates that the attribute is legal in that position,
- the compiler stores the extracted metadata in its interface graph,
- the raw attribute surface is not treated as a runtime object,
- later lowering stages may consume the extracted metadata to produce PBX host-binding declarations.
## 10. Resources as an Implementation Strategy
For the Studio PBS frontend, packaging stdlib interface modules in frontend `resources` is a valid implementation strategy.
Rules:
- `resources` packaging is implementation-level, not language-level,
- the compiler should still access stdlib modules through `StdlibEnvironment` and related abstractions,
- code outside the stdlib loader should not depend on resource path layout directly.
Rationale:
- `resources` gives a simple bootstrap path,
- stdlib evolves as real source artifacts,
- the frontend avoids hardcoded built-ins,
- the implementation remains replaceable later.
## 11. Caching and Reuse
The compiler may cache stdlib interface modules within one compilation or across compilations.
Rules:
- caching must not change observable semantics,
- cache keys should include at least the stdlib major line and logical module address,
- cached modules must preserve the same parsed declarations and attribute metadata as uncached loads.
## 12. Current Decision Summary
The current Studio direction is:
1. the stdlib environment is loaded as real PBS interface modules,
2. the initial implementation may live under frontend `resources`,
3. the logical model remains `stdlib line -> reserved project space -> module path`,
4. the compiler should use explicit abstractions such as `StdlibEnvironment` and `StdlibModuleResolver`,
5. stdlib interface modules are parsed with the normal PBS parser and validated in interface-module mode,
6. reserved attributes such as `[Host(...)]` are extracted as compile-time metadata for later lowering.
@@ -0,0 +1,133 @@
# PBS Dynamic Semantics Specification
Status: Draft v0 (Skeleton)
Applies to: runtime-observable behavior of PBS core programs
## 1. Purpose
This document will define 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 trap propagation,
- 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 is intended to define:
- 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 is expected to be closed using decisions from:
- `docs/agendas/Dynamic Semantics - Execution Model Agenda.md`
- `docs/agendas/Dynamic Semantics - Effect Surfaces Agenda.md`
- `docs/agendas/Heap Model - Agenda.md`
- `docs/agendas/Memory and Lifetime - Agenda.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`.
- `bind(context, fn_name)` evaluates the `context` expression once at bind time.
- `switch` evaluates its selector expression once.
- `optional T` function fallthrough yields `none`.
- `result<E>` function fallthrough is a compile-time error.
- `ok(...)` and `err(...)` are not ordinary first-class runtime constructors in v1 core.
## 6. Initial Section Targets
At minimum, the completed document should contain normative sections for:
1. execution model and runtime state,
2. evaluation order by construct,
3. block execution and abrupt completion,
4. runtime semantics of `optional`,
5. runtime semantics of `result<E>`,
6. runtime semantics of `apply`, call sugar, and callable categories,
7. branching semantics for `if` and `switch`,
8. traps, determinism, and host-call interaction.
## 7. A Ver
The following items remain to be closed in agenda discussion before this document can be considered complete.
### 7.1 `Dynamic Semantics - Execution Model Agenda.md`
- Exact observable execution model for PBS v1.
- Normative evaluation order for receivers, callees, arguments, selectors, and nested `apply`.
- Exact abrupt-completion model for `return`, `break`, `continue`, `!`, and trap propagation.
- Deterministic safepoint interaction around host calls, allocation-heavy operations, and loop back-edges.
### 7.2 `Dynamic Semantics - Effect Surfaces Agenda.md`
- Runtime value model of `optional` and `result<E>`.
- Eagerness and single-evaluation guarantees for `some(...)`, `else`, `handle`, and `!`.
- Runtime artifact and cost model of `bind(context, fn_name)`.
- Exact runtime boundary between explicit status values and true traps.
### 7.3 `Heap Model - Agenda.md` and `Memory and Lifetime - Agenda.md`
- Which dynamic-semantic costs are observable and later diagnosable.
- Which constructs may allocate, copy, retain, or cross the host-memory boundary during ordinary execution.
- Which memory and safepoint facts belong in this document versus `Memory and Lifetime Specification.md`.
## 8. 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.
## 9. Exit Criteria
This document is ready to move beyond skeleton status only when:
1. every runtime-observable core construct has a deterministic evaluation model,
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 requiring agenda backfill,
5. the document no longer depends on unresolved `A Ver` items for core v1 behavior.