diff --git a/docs/pbs/specs/1. Language Charter.md b/docs/pbs/specs/1. Language Charter.md index 159234a5..c159ba39 100644 --- a/docs/pbs/specs/1. Language Charter.md +++ b/docs/pbs/specs/1. Language Charter.md @@ -40,7 +40,7 @@ It must feel fluid for frame-driven gameplay code while remaining strict enough - 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. +- Explicit lifetime-control syntax before an explicit future design and profile activation. - User-authored declaration of canonical host primitive bindings outside reserved SDK/toolchain `declare host` surfaces. ## 7. Non-Negotiable Constraints diff --git a/docs/pbs/specs/10. Memory and Lifetime Specification.md b/docs/pbs/specs/10. Memory and Lifetime Specification.md index 7e413557..e15456a9 100644 --- a/docs/pbs/specs/10. Memory and Lifetime Specification.md +++ b/docs/pbs/specs/10. Memory and Lifetime Specification.md @@ -1,15 +1,15 @@ # 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 +Status: Draft v1 (Temporary) +Applies to: runtime memory spaces, value representation classes, identity, aliasing, GC baseline, host-memory boundaries, and cost visibility in PBS core ## 1. Purpose -This document will define the authoritative PBS memory and lifetime model for v1. +This document defines the authoritative PBS memory and lifetime model for v1. Its purpose is to make the language's runtime storage model explicit enough that: -- implementations agree on which values are heap-backed, +- implementations agree on the current core value categories, - identity and aliasing are not left implicit, - GC remains compatible with deterministic execution, - the VM heap and host-owned memory boundary stay understandable, @@ -17,7 +17,7 @@ Its purpose is to make the language's runtime storage model explicit enough that ## 2. Scope -This document is intended to define: +This document defines: - runtime memory spaces relevant to PBS user semantics, - value categories and their representation classes, @@ -58,74 +58,284 @@ This document depends on, at minimum: - `4. Static Semantics Specification.md` - `9. Dynamic Semantics Specification.md` -This document is expected to be closed using decisions from: +This document integrates the following accepted decisions: -- `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` +- `docs/pbs/decisions/Value Representation and Identity Decision.md` +- `docs/pbs/decisions/GC and Reachability Decision.md` +- `docs/pbs/decisions/Host Memory Boundary Decision.md` +- `docs/pbs/decisions/Allocation and Cost Visibility Decision.md` +- `docs/pbs/decisions/Lifetime Control and Future Profiles Decision.md` ## 5. Already-Settled Inputs The following inputs are already fixed elsewhere and must not be contradicted here: -- Struct values are heap-backed reference values in v1 core. -- Assigning a struct value copies the reference, not the underlying field storage. +- Struct values are reference-like and identity-bearing in v1 core. - 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. +- `FRAME_SYNC` is the only normative safepoint in PBS v1. +- Core PBS v1 does not expose explicit lifetime-control syntax in ordinary user code. -## 6. Initial Section Targets +## 6. Runtime Memory Spaces -At minimum, the completed document should contain normative sections for: +PBS v1 distinguishes, at minimum: -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. +1. VM-managed runtime storage used for GC-managed values and retained runtime state. +2. Stack-like transient value flow used for ordinary value exchange during evaluation. +3. Host-owned memory and resources that remain outside ordinary PBS userland memory semantics. -## 7. A Ver +The VM heap and host-owned memory remain distinct in the user model. -The following items remain to be closed in agenda discussion before this document can be considered complete. +Cross-boundary host/userland interaction is value-based rather than memory-sharing-based. -### 7.1 `Memory and Lifetime - Agenda.md` +## 7. Value Representation Classes -- 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`. -- Normative GC guarantees versus implementation-defined GC details. -- Representation and safety model of host-backed resources and handles. +### 7.1 Pure copied values -### 7.2 `Heap Model - Agenda.md` +The following value kinds are pure copied values in the user model: -- 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. +- `int` +- `float` +- `bool` +- enum values +- canonical `str` -### 7.3 `Dynamic Semantics - Execution Model Agenda.md` and `Dynamic Semantics - Effect Surfaces Agenda.md` +Assignment, parameter passing, and return of these values copy the value itself. -- 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. +### 7.2 Identity-bearing values -## 8. Non-Goals +The following value kinds carry stable user-visible identity: + +- struct values +- service values +- host-backed resource values on the PBS side + +Assignment, parameter passing, and return of these values preserve aliasing to the same runtime entity rather than copying an independent underlying object. + +### 7.3 Carrier-only values + +The following value kinds are carriers and do not introduce identity of their own: + +- tuples +- `optional` +- `result` + +If a carrier contains an identity-bearing payload, the carrier transports that same payload identity rather than inventing a new one. + +### 7.4 Contract values + +Contract values do not introduce a new user-visible identity distinct from the underlying struct or service value. + +They are runtime views over an underlying identity-bearing value together with the selected contract implementation used for dispatch. + +### 7.5 Callback values + +Callback values are first-class callable values in PBS v1. + +They may be assigned, passed, and returned, but callback identity is not promoted as a separate user-visible identity concept. + +When formed through `bind(context, fn_name)`, a callback value retains: + +- the target function, +- and the same captured struct context identity without copying it. + +## 8. Identity, Aliasing, and Copy Behavior + +### 8.1 Structs + +Struct values are always reference-like in PBS v1. + +Rules: + +- `new Struct(...)` produces a fresh struct identity. +- Assignment of a struct value copies the reference, not the underlying field storage. +- Passing or returning a struct value preserves aliasing to the same struct instance. +- Mutation through one alias is observable through other aliases to that same struct instance. + +### 8.2 Services + +Service values denote the same canonical singleton identity wherever used in the same resolved program. + +Assignment, parameter passing, and return preserve that same singleton identity. + +### 8.3 Carriers + +`optional`, `result`, and tuples preserve the semantics of their contained values. + +Examples: + +- assigning an `optional` that contains `some(player)` preserves the same `Player` identity inside the carrier, +- assigning a `result Player` success payload preserves the same `Player` identity inside the carrier. + +### 8.4 General rule + +The general rule for PBS v1 is: + +- pure value kinds are copied by value, +- identity-bearing kinds preserve aliasing, +- carrier kinds preserve the semantics of their contained values and do not create identity of their own. + +## 9. GC Baseline + +### 9.1 Reachability + +GC is the baseline runtime model for VM-owned memory in PBS core. + +For GC-managed VM-owned values, liveness is defined by reachability from the runtime roots that matter to PBS semantics. + +At minimum, those roots include: + +- currently active local/frame state, +- reachable fields of reachable struct instances, +- service singleton roots, +- retained callback state that remains reachable, +- and any other runtime roots required to preserve already-observable PBS behavior. + +If a GC-managed value remains reachable through the normative runtime state, the implementation must preserve its continued semantic availability. + +### 9.2 Reclamation + +PBS v1 guarantees eventual reclamation, not prompt reclamation. + +The language does not promise: + +- immediate reclamation, +- reclamation at a specific frame boundary, +- or a semantic event when reclamation occurs. + +### 9.3 Safepoint relationship + +`FRAME_SYNC` is the only normative safepoint in PBS v1. + +No user-visible program rule may depend on another safepoint existing. + +Implementations may perform internal GC work outside `FRAME_SYNC` only if doing so creates no additional user-visible semantic effects. + +### 9.4 Observability + +User code cannot observe reclamation directly. + +PBS v1 provides no user-visible mechanism for: + +- detecting that a value was collected, +- registering a callback on reclamation, +- forcing immediate collection, +- sequencing user code against collector timing. + +PBS v1 defines no user-authored finalizers or destructor-like reclamation hooks. + +## 10. Host Memory Boundary + +The host/userland boundary in PBS v1 is value-based rather than memory-sharing-based. + +Cross-boundary interaction between host and PBS userland is restricted to stack-only values. + +PBS userland does not expose host memory as ordinary language values. + +PBS v1 does not expose: + +- raw host pointers, +- borrowed host-memory views, +- pinning, +- zero-copy transfer, +- shared heap objects spanning host memory and VM memory. + +Long-lived host resources, if later exposed, must be specified by subsystem contract rather than inferred from a general host-memory-handle model in core PBS. + +## 11. Cost Visibility Hooks + +### 11.1 Normatively relevant cost facts + +The normatively relevant cost facts in PBS v1 are: + +- whether an operation may allocate VM-owned runtime storage, +- whether an operation retains state beyond the current evaluation, +- whether an operation copies payload versus preserves aliasing, +- whether an operation crosses the host boundary, +- whether an operation may trap. + +### 11.2 `bind` + +`bind(context, fn_name)` is retention-bearing and requires runtime storage sufficient to preserve: + +- the callback target identity, +- the captured context, +- and the captured context's continued liveness while the callback value remains alive. + +This document does not freeze the exact runtime layout used to implement that storage. + +### 11.3 Non-allocation-bearing surfaces by themselves + +The following constructs are not allocation-bearing by themselves in PBS v1: + +- `optional` +- `result` +- `handle` +- `!` +- `if` +- `switch` +- `apply` + +If allocation or retention occurs while evaluating one of these constructs, that cost arises from: + +- subexpression evaluation, +- called targets, +- payload formation already defined elsewhere, +- or runtime behavior outside the surface itself. + +### 11.4 Quantitative reporting + +The language does not normatively guarantee: + +- exact byte counts, +- exact object counts, +- exact collector timing, +- exact host-side allocation volume, +- precise performance ranking. + +Those belong to diagnostics/profiling quality rather than to the core language contract. + +## 12. Future Lifetime Control Policy + +PBS v1 adopts the following policy: + +- no dormant lifetime-control keyword is preserved merely for speculative future use, +- advanced memory workflows should default to library/tooling-first exploration, +- future explicit lifetime-oriented syntax, if introduced at all, must be profile-gated and justified by real need rather than by historical inertia. + +Core PBS v1 does not promise future activation of legacy RC/HIP-style syntax. + +## 13. Beginner-Facing Model + +The user-facing explanation should be: + +- some values are plain data, so passing them passes the value, +- structs and services are shared entities, so passing them passes access to the same entity, +- tuples, `optional`, and `result` only package values and do not become new entities by themselves, +- the runtime keeps reachable GC-managed values alive, +- the program does not directly hold or manipulate host memory. + +## 14. TODO + +The following items remain editorial or adjacent-spec integration tasks rather than open memory-model agenda questions: + +- subsystem-specific wording for long-lived host resources if those are later introduced, +- diagnostics-specific wording for cost warnings and notes, +- future profile mechanics if an explicit lifetime profile is ever proposed. + +## 15. Non-Goals - Designing full pool, arena, or weak-reference libraries in this pass. - Reintroducing mandatory user-authored lifetime syntax in core v1. - Defining exact collector implementation strategy. -- Rewriting already-settled source syntax. +- Rewriting already-settled source syntax beyond what is required for consistency with accepted decisions. -## 9. Exit Criteria +## 16. Exit Criteria -This document is ready to move beyond skeleton status only when: +This document is ready to move beyond temporary draft status only when: -1. every core value category has an explicit representation and aliasing story, +1. every current core value category has explicit representation and aliasing wording, 2. GC guarantees and non-guarantees are separated clearly, 3. the VM heap versus host-memory boundary is normatively described, -4. memory-related costs are specified well enough for diagnostics/tooling hooks, -5. the document no longer relies on unresolved `A Ver` items for ordinary v1 behavior. +4. memory-related cost facts are specified well enough for diagnostics/tooling hooks, +5. the remaining TODO items are reduced to editorial integration or future optional work rather than semantic uncertainty. diff --git a/docs/pbs/specs/11. Diagnostics Specification.md b/docs/pbs/specs/11. Diagnostics Specification.md index 383f43d2..5eb72902 100644 --- a/docs/pbs/specs/11. Diagnostics Specification.md +++ b/docs/pbs/specs/11. Diagnostics Specification.md @@ -1,36 +1,35 @@ # 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 +Status: Draft v1 (Temporary) +Applies to: deterministic diagnostics emitted by PBS-facing tooling across parsing, static analysis, manifest/import resolution, and load-facing validation surfaces ## 1. Purpose -This document will define the PBS diagnostics contract. +This document defines the current PBS diagnostics baseline for v1. 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. +- conforming tools report failures in the same phases, +- users receive deterministic and actionable source-facing feedback, +- conformance can validate rejection class and attribution, +- and frontend, manifest, and load-facing validation remain aligned. ## 2. Scope -This document is intended to define: +This document defines: -- 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. +- the current required diagnostic phases, +- the minimum source-facing attribution baseline, +- the relationship between higher-precedence rejection rules and diagnostics, +- and the current limits of v1 diagnostics while lowering and artifact-facing specs remain incomplete. This document does not define: -- the full runtime trap catalog, +- a full runtime trap catalog, - UI presentation or IDE styling, -- implementation-specific hint ranking, -- profiling output formats. +- one localization strategy, +- one diagnostics-code namespace, +- or profiling/reporting formats. ## 3. Authority and Precedence @@ -58,12 +57,14 @@ This document depends on, at minimum: - `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/` + +Later expansion of this document will also depend on: + +- `12. IR and Lowering Specification.md` +- `15. Bytecode and PBX Mapping Specification.md` +- `16. Runtime Execution and Initialization Specification.md` ## 5. Already-Settled Inputs @@ -74,60 +75,85 @@ The following inputs are already fixed elsewhere and must not be contradicted he - Manifest/import resolution failures are required to be deterministic compile-time errors. - Loader failures around malformed or unauthorized host usage are required to be deterministic. - Stable source span metadata is required at the token level and must remain useful to later diagnostics. +- Traps are fatal runtime outcomes rather than a recoverable userland diagnostic flow. +- Qualitative cost facts such as retention-bearing operations and host-boundary crossings are normative, but quantitative performance metrics are not. -## 6. Initial Section Targets +## 6. Required Diagnostic Phases -At minimum, the completed document should contain normative sections for: +At the current v1 baseline, PBS-facing tooling must distinguish at least the following diagnostic phases: -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. +1. syntax, +2. static semantics, +3. manifest and import resolution, +4. host-binding and capability admission, +5. load-facing rejection when directly attributable to malformed or unauthorized PBS-facing artifact usage. -## 7. A Ver +This document does not yet require a finer-grained normative phase split for lowering, verifier, or artifact diagnostics. That remains open until the corresponding backend-facing specs are closed. -The following items remain to be closed before this document can be considered complete. +## 7. Minimum Diagnostic Attribution -### 7.1 Depends on `9. Dynamic Semantics Specification.md` +For every required source-facing rejection that is attributable to source text, tooling must provide diagnostics with at least: -- 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. +1. deterministic phase attribution, +2. primary file attribution, +3. a useful primary source span or location, +4. and enough human-readable content to distinguish the rejection class. -### 7.2 Depends on `10. Memory and Lifetime Specification.md` +This document does not yet require one normalized diagnostics-code system or one fixed human wording template. -- Which allocations, copies, escapes, and host-boundary crossings must surface as normative diagnostics or warnings. -- Which cost facts are mandatory versus implementation-defined enrichment. +## 8. Required Diagnostic Coverage -### 7.3 Depends on the future backend agenda sequence tracked in `docs/agendas/` +At minimum, the current diagnostics baseline must cover: -- 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. +1. syntax errors already required by `3. Core Syntax Specification.md`, +2. static-semantics errors already required by `4. Static Semantics Specification.md`, +3. deterministic manifest and import-resolution failures required by `5. Manifest, Stdlib, and SDK Resolution Specification.md`, +4. malformed, unauthorized, or capability-rejected host usage required by `6.2. Host ABI Binding and Loader Resolution Specification.md` and `7. Cartridge Manifest and Runtime Capabilities Specification.md`. -### 7.4 Still to decide inside this document +Dynamic-semantics traps are not source-level recoverable diagnostics in the ordinary PBS userland model. This document therefore does not require a compile-time diagnostic surface for every possible fatal runtime trap. -- 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. +## 9. Cost and Runtime-Facing Diagnostics -## 8. Non-Goals +The current baseline is intentionally narrow. + +Tooling may surface cost-visibility notes or warnings around facts such as: + +- retention-bearing `bind`, +- observable copy-versus-alias semantics, +- and host-boundary crossings. + +However, this document does not yet make a detailed warning taxonomy normative. Quantitative metrics, exact ranking, and profiling detail remain implementation-defined. + +## 10. TODO + +The following items remain to be closed before this document can be considered complete: + +### 10.1 Depends on later closure of backend-facing specs + +- 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. + +### 10.2 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; +- which qualitative cost warnings, if any, become mandatory rather than optional tooling enrichment. + +## 11. 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 +## 12. Exit Criteria -This document is ready to move beyond skeleton status only when: +This document is ready to move beyond temporary status only when: 1. every required rejection in the current spec set is mapped to a diagnostic phase, 2. diagnostic 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. +3. cost-visibility expectations are explicit where they are intended to be normative, +4. and the document no longer relies on unresolved backend- and runtime-facing TODO items for v1 tooling behavior. diff --git a/docs/pbs/specs/12. IR and Lowering Specification.md b/docs/pbs/specs/12. IR and Lowering Specification.md index 1e72b41f..e84e07cc 100644 --- a/docs/pbs/specs/12. IR and Lowering Specification.md +++ b/docs/pbs/specs/12. IR and Lowering Specification.md @@ -64,7 +64,7 @@ This document depends on, at minimum: - `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/`. +This document is expected to close in coordination with `15. Bytecode and PBX Mapping Specification.md` and `16. Runtime Execution and Initialization Specification.md`. ## 5. Already-Settled Inputs @@ -95,7 +95,7 @@ At minimum, the completed document should contain normative sections for: 8. host-binding emission, 9. artifact invariants required before verifier/loader stages. -## 7. A Ver +## 7. TODO The following items remain to be closed before this document can be considered complete. @@ -110,7 +110,7 @@ The following items remain to be closed before this document can be considered c - 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/` +### 7.3 Still open across this document and adjacent backend-facing specs - 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. @@ -133,4 +133,4 @@ This document is ready to move beyond skeleton status only when: 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. +5. the document no longer relies on unresolved backend `TODO` items for ordinary v1 lowering behavior. diff --git a/docs/pbs/specs/13. Conformance Test Specification.md b/docs/pbs/specs/13. Conformance Test Specification.md index edde23aa..4121d5ba 100644 --- a/docs/pbs/specs/13. Conformance Test Specification.md +++ b/docs/pbs/specs/13. Conformance Test Specification.md @@ -1,36 +1,33 @@ # PBS Conformance Test Specification -Status: Draft v0 (Skeleton) +Status: Draft v1 (Temporary) Applies to: conformance obligations, test categories, and acceptance criteria for PBS implementations ## 1. Purpose -This document will define the PBS conformance testing contract. +This document defines the current PBS conformance-test baseline for v1. -Its purpose is to make the specification operational by defining: +Its purpose is to make the active specification operational by stating: -- 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. +- which categories of behavior must be tested, +- which outcomes must be deterministic across conforming implementations, +- and which parts of the corpus are not yet mature enough to demand full conformance coverage. ## 2. Scope -This document is intended to define: +This document defines: -- 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. +- required positive and negative source-level conformance surfaces, +- runtime-oracle expectations already fixed by active semantics, +- minimum host-binding and capability-gating test surfaces, +- and the current limits of v1 conformance while diagnostics and lowering remain incomplete. This document does not define: -- one specific test runner implementation, -- CI policy for one repository, +- one specific test harness or repository layout, - benchmark or performance certification, -- product release governance process. +- one artifact-level golden format, +- or product release governance policy. ## 3. Authority and Precedence @@ -53,22 +50,23 @@ This document must not weaken a normative requirement imposed by higher-preceden ## 4. Normative Inputs -This document depends on, at minimum, the full active PBS v1 spec set. +This document depends on the active PBS v1 spec set. -In the current phase, it should be drafted against: +For the currently integrated conformance baseline, the key inputs are: - `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` + +Later expansion of this document will also depend on: + - `11. Diagnostics Specification.md` - `12. IR and Lowering Specification.md` +- `15. Bytecode and PBX Mapping Specification.md` ## 5. Already-Settled Inputs @@ -78,61 +76,116 @@ The following inputs are already fixed elsewhere and must not be contradicted he - 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. +- Dynamic semantics are single-threaded and deterministic at the language-observable level. +- Memory semantics already distinguish identity-bearing values from pure-value and carrier forms. +- Traps are fatal runtime aborts rather than recoverable userland outcomes. -## 6. Initial Section Targets +## 6. Current Conformance Baseline -At minimum, the completed document should contain normative sections for: +At the current maturity level, a conforming PBS implementation must support tests in the following categories: -1. scope of conformance, -2. implementation claims and version domains, -3. required positive parsing/binding/type-checking tests, -4. required negative syntax/static tests, +1. positive syntax and parsing tests, +2. negative syntax rejection tests, +3. positive binding and static-typing tests, +4. negative static-semantics rejection 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. +6. host-binding and capability-gating tests, +7. source-level dynamic-semantics runtime tests, +8. source-level memory/identity behavior tests, +9. compatibility/regression tests for already-published behavior claims. -## 7. A Ver +## 7. Source-Level Runtime Oracle -The following items remain to be closed before this document can be considered complete. +The current conformance oracle for runtime behavior is source-level and language-observable. -### 7.1 Depends on `9. Dynamic Semantics Specification.md` and `10. Memory and Lifetime Specification.md` +At minimum, conformance tests must cover: -- 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. +1. strict left-to-right evaluation where the language does not define an exception, +2. exactly-once evaluation of: + - call-target formation, + - call arguments, + - `if` conditions, + - `switch` selectors, + - `some(expr)` payload formation, + - `bind(context, fn_name)` context capture, +3. `optional` behavior: + - `some(expr)` is eager, + - `none` is canonical absence, + - `opt else fallback` evaluates `fallback` only on `none`, +4. `result` behavior: + - `expr!` passes through success payload, + - `expr!` immediately propagates same-domain error, + - `handle expr { ... }` passes through success payload, + - `handle` block arms terminate with `ok(payload)` or `err(E.case)`, + - short `handle` arms remap error as specified, +5. branch-selection behavior: + - non-selected `if` and `switch` arms do not execute, + - `switch` selects deterministically over admitted static discriminants, +6. trap behavior: + - traps do not enter `result` flow, + - traps are not intercepted by `handle`, + - traps abort the running PBS program path. -### 7.2 Depends on `11. Diagnostics Specification.md` +Conformance does not currently require a userland-visible trap taxonomy. It requires only the fatal-abort boundary already defined by the runtime and dynamic-semantics specs. -- Whether conformance checks diagnostic codes, spans, categories, wording classes, or only rejection phase and location. -- Which warnings or cost diagnostics are in conformance scope. +## 8. Source-Level Memory and Identity Oracle -### 7.3 Depends on `12. IR and Lowering Specification.md` +At minimum, conformance tests must cover the following language-observable memory/identity facts: -- Whether artifact-level conformance is required in addition to source-level conformance. -- Which emitted host-binding and lowering invariants require golden tests. +1. `struct` values are identity-bearing and alias through assignment, parameter passing, and return, +2. `service` values preserve singleton identity, +3. tuples, `optional`, and `result` do not create new userland identity of their own, +4. carriers preserve the identity behavior of their payloads, +5. `bind(context, fn_name)` captures the same runtime identity of the `struct` context rather than copying it, +6. callback invocation after `bind` observes mutation against that same captured context identity, +7. GC timing itself is not a conformance oracle, +8. reclamation is validated only indirectly through correctness and safety boundaries, not through collection timing. -### 7.4 Still to decide inside this document +## 9. Host-Binding and Boundary Tests -- 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. +At minimum, conformance tests must cover: -## 8. Non-Goals +1. deterministic rejection of malformed or unauthorized host usage, +2. deterministic acceptance of valid host-backed declarations admitted by the active capability/runtime line, +3. correct source-level behavior of host-backed calls that are already admitted by the Host ABI and capability specs, +4. the absence of userland-visible raw pointers or heap-shared host-memory surfaces at the PBS boundary. + +This document does not yet require one artifact-level oracle for host-lowering shape. That remains dependent on later closure of lowering and PBX-mapping specifications. + +## 10. TODO + +The following items remain open before this document can be considered complete: + +### 10.1 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. + +### 10.2 Depends on `12. IR and Lowering Specification.md` and `15. Bytecode and PBX Mapping Specification.md` + +- whether artifact-level conformance is required in addition to source-level conformance; +- which emitted host-binding and lowering invariants require golden tests; +- which source-to-artifact mapping hooks are part of the conformance contract. + +### 10.3 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. + +## 11. 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 +## 12. Exit Criteria -This document is ready to move beyond skeleton status only when: +This document is ready to move beyond temporary 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, +3. diagnostics and artifact-level behavior have explicit oracle expectations where required, 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. +5. and the document no longer relies on unresolved TODO items for the intended conformance level. diff --git a/docs/pbs/specs/14. Name Resolution and Module Linking Specification.md b/docs/pbs/specs/14. Name Resolution and Module Linking Specification.md index dd795300..7adc9a40 100644 --- a/docs/pbs/specs/14. Name Resolution and Module Linking Specification.md +++ b/docs/pbs/specs/14. Name Resolution and Module Linking Specification.md @@ -76,7 +76,7 @@ At minimum, the completed document should contain normative sections for: 6. duplicate and shadowing rules, 7. cross-module resolution failures. -## 7. A Ver +## 7. TODO The following items remain to be closed in future agenda discussion. @@ -101,7 +101,7 @@ This document is ready to move beyond skeleton status only when: 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. +5. the document no longer relies on unresolved `TODO` items for ordinary v1 resolution behavior. ## 10. Reserved Stdlib Shell Resolution diff --git a/docs/pbs/specs/15. Bytecode and PBX Mapping Specification.md b/docs/pbs/specs/15. Bytecode and PBX Mapping Specification.md index 795dcf21..b44b702a 100644 --- a/docs/pbs/specs/15. Bytecode and PBX Mapping Specification.md +++ b/docs/pbs/specs/15. Bytecode and PBX Mapping Specification.md @@ -66,7 +66,7 @@ At minimum, the completed document should contain normative sections for: 5. intrinsic and builtin artifact obligations, 6. source-attribution hooks for diagnostics/conformance. -## 7. A Ver +## 7. TODO The following items remain to be closed in future agenda discussion. @@ -89,4 +89,4 @@ 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. +3. the document no longer relies on unresolved `TODO` items for ordinary v1 artifact mapping behavior. diff --git a/docs/pbs/specs/16. Runtime Execution and Initialization Specification.md b/docs/pbs/specs/16. Runtime Execution and Initialization Specification.md index 3f8153c7..5d7ee9ab 100644 --- a/docs/pbs/specs/16. Runtime Execution and Initialization Specification.md +++ b/docs/pbs/specs/16. Runtime Execution and Initialization Specification.md @@ -1,27 +1,36 @@ # PBS Runtime Execution and Initialization Specification -Status: Draft v0 (Skeleton) +Status: Draft v1 (Temporary) Applies to: runtime startup, entry behavior, module/service initialization, and execution lifecycle of PBS programs after successful load ## 1. Purpose -This document will define the runtime execution and initialization contract for PBS programs. +This document defines the PBS-visible runtime entry and execution-lifecycle contract after successful artifact load. + +Its purpose is to keep runtime startup, frame-driven execution, and fatal-failure behavior aligned with: + +- runtime authority, +- dynamic semantics, +- memory/lifetime guarantees, +- and the closed capability-gated host model. ## 2. Scope -This document is intended to define: +This document defines: -- 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. +- when PBS program execution may begin, +- which preconditions must already hold before userland runs, +- the runtime execution model of a loaded PBS program instance, +- the only normative frame/safepoint boundary in v1, +- and which startup or fatal-failure outcomes are PBS-visible. This document does not define: -- loader-side host resolution, -- full packaging format, -- scheduler models outside v1 execution assumptions. +- loader-side host resolution details, +- the full packaging or process model, +- scheduler models outside the v1 single-threaded execution contract, +- shutdown/finalization APIs or hooks, +- or subsystem-specific host resource lifecycles. ## 3. Authority and Precedence @@ -52,40 +61,95 @@ The following inputs are already fixed elsewhere and must not be contradicted he - `FRAME_SYNC`-based execution semantics are preserved. - Loader-side host binding resolution and capability gating happen before program execution begins. +- A PBS program instance executes single-threaded in v1. +- Dynamic semantics are deterministic at the language-observable level. +- Any runtime trap aborts PBS program execution and enters the runtime/firmware crash path rather than a userland recovery path. - Service values are canonical module-owned singleton values. - Top-level executable statements are forbidden in PBS source modules. -## 6. Initial Section Targets +## 6. Runtime Entry Preconditions -At minimum, the completed document should contain normative sections for: +PBS userland execution may begin only after all of the following are true: -1. execution entry assumptions, -2. initialization ordering, -3. service singleton runtime lifecycle, -4. runtime frame and step boundaries, -5. failure and non-start conditions. +1. the program artifact has been accepted by the relevant runtime/load authority, +2. capability gating and host-binding resolution required for startup have completed successfully, +3. runtime state required to begin frame-driven execution has been established, +4. and no prior fatal startup failure has occurred. -## 7. A Ver +If these preconditions are not satisfied, ordinary PBS userland execution does not begin. -The following items remain to be closed in future agenda discussion. +This document does not define loader-internal sequencing in detail; it only defines that the userland-visible start boundary occurs after successful load- and capability-level admission. -- 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. +## 7. Program Instance Model -## 8. Non-Goals +Each loaded PBS program executes as one single-threaded program instance in v1. + +Within a program instance: + +- userland execution is not concurrently interleaved by another userland thread, +- the dynamic-semantics evaluation order defined in `9. Dynamic Semantics Specification.md` remains authoritative, +- and runtime/host activity must not perturb that language-level sequencing. + +PBS source modules do not contribute a user-authored top-level execution phase. Any startup activity that exists outside ordinary function/method execution is runtime-owned unless and until another specification makes a narrower PBS-visible contract explicit. + +## 8. Frame Boundary and Host Work + +`FRAME_SYNC` is the only normative runtime step boundary and the only normative safepoint in PBS v1. + +Consequences: + +- the runtime may use the interval around `FRAME_SYNC` to process host-side demands and internal work, +- userland execution must remain semantically ordered as defined by `9. Dynamic Semantics Specification.md`, +- and PBS user code cannot rely on any other boundary as a guaranteed safepoint, collection point, or scheduling point. + +Internal runtime work may exist outside `FRAME_SYNC`, but it must remain semantically invisible to PBS userland unless a higher-precedence authority explicitly defines otherwise. + +## 9. Failure and Non-Start Conditions + +PBS distinguishes between two broad classes of failure at this layer: + +1. non-start conditions, where userland never begins because artifact admission, capability checks, or required startup preconditions fail; +2. fatal runtime traps, where an already-running PBS program aborts. + +Traps are not recoverable in PBS userland. When a trap occurs: + +- it does not enter `result` flow, +- it is not intercepted by `handle`, +- and it aborts the PBS program execution path into the runtime/firmware crash path. + +This document does not define a userland-visible trap catalog. + +## 10. Service and Module Initialization Boundaries + +The current v1 baseline is intentionally narrow: + +- service values are canonical singleton values, +- top-level executable statements do not exist, +- and no userland-visible module-initialization statement phase is defined here. + +The exact timing at which service-owned runtime state becomes initialized and observable remains an open item for this document. Until that is closed, implementations must not infer extra userland-visible initialization hooks beyond what is already guaranteed by higher-precedence specs. + +## 11. TODO + +The following items remain open for later closure: + +- the exact runtime entry contract between successful load and first userland-observable execution, +- whether service-owned runtime state has a more precise initialization point than the baseline stated here, +- which runtime lifecycle boundaries, if any, are userland-observable beyond `FRAME_SYNC` and trap abort, +- and whether shutdown behavior has any PBS-visible contract in v1. + +## 12. Non-Goals - Defining OS/process lifecycle outside Prometeu runtime authority. - Reopening the ban on top-level executable statements. - Designing a future async runtime. +- Defining userland recovery from trap. -## 9. Exit Criteria +## 13. Exit Criteria -This document is ready to move beyond skeleton status only when: +This document is ready to move beyond temporary status only when: -1. runtime startup and initialization order are normatively described, -2. service and module runtime lifecycle assumptions are explicit, +1. runtime startup and non-start boundaries are normatively described, +2. service and module runtime lifecycle assumptions are explicit enough to remove the remaining TODO items, 3. execution lifecycle boundaries are aligned with dynamic semantics and runtime authority, -4. the document no longer relies on unresolved `A Ver` items for ordinary v1 runtime startup behavior. +4. and the document no longer relies on unresolved TODO items for ordinary v1 runtime startup behavior. diff --git a/docs/pbs/specs/17. Compatibility and Evolution Policy.md b/docs/pbs/specs/17. Compatibility and Evolution Policy.md index 90628b56..f8fd8d31 100644 --- a/docs/pbs/specs/17. Compatibility and Evolution Policy.md +++ b/docs/pbs/specs/17. Compatibility and Evolution Policy.md @@ -64,7 +64,7 @@ At minimum, the completed document should contain normative sections for: 5. compatibility-matrix expectations, 6. artifact and runtime compatibility boundaries. -## 7. A Ver +## 7. TODO The following items remain to be closed in future agenda discussion. @@ -87,4 +87,4 @@ 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. +4. the document no longer relies on unresolved `TODO` items for ordinary v1 compatibility claims. diff --git a/docs/pbs/specs/18. Standard Library Surface Specification.md b/docs/pbs/specs/18. Standard Library Surface Specification.md index 4a916e9b..28e20e73 100644 --- a/docs/pbs/specs/18. Standard Library Surface Specification.md +++ b/docs/pbs/specs/18. Standard Library Surface Specification.md @@ -68,7 +68,7 @@ At minimum, the completed document should contain normative sections for: 5. host-backed SDK surfaces exposed to user code, 6. versioning and deprecation expectations for stdlib APIs. -## 7. A Ver +## 7. TODO The following items remain to be closed in future agenda discussion. @@ -93,7 +93,7 @@ This document is ready to move beyond skeleton status only when: 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. +5. the document no longer relies on unresolved `TODO` items for ordinary v1 stdlib contract claims. ## 10. Reserved Project-Space Responsibilities diff --git a/docs/pbs/specs/19. Verification and Safety Checks Specification.md b/docs/pbs/specs/19. Verification and Safety Checks Specification.md index f7d137d1..c73d32b1 100644 --- a/docs/pbs/specs/19. Verification and Safety Checks Specification.md +++ b/docs/pbs/specs/19. Verification and Safety Checks Specification.md @@ -63,7 +63,7 @@ At minimum, the completed document should contain normative sections for: 5. residual runtime safety assumptions, 6. required deterministic rejection conditions. -## 7. A Ver +## 7. TODO The following items remain to be closed in future agenda discussion. @@ -85,4 +85,4 @@ 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. +4. the document no longer relies on unresolved `TODO` items for ordinary v1 safety claims. diff --git a/docs/pbs/specs/3. Core Syntax Specification.md b/docs/pbs/specs/3. Core Syntax Specification.md index 1a351093..afca1159 100644 --- a/docs/pbs/specs/3. Core Syntax Specification.md +++ b/docs/pbs/specs/3. Core Syntax Specification.md @@ -93,7 +93,6 @@ Barrel-only keywords: Reserved (not active syntax in v1 core): -- `alloc`, `borrow`, `mutate`, `peek`, `take`, `weak` - `spawn`, `yield`, `sleep` - `match` @@ -524,7 +523,7 @@ Expr ::= HandleExpr HandleExpr ::= 'handle' ElseExpr HandleMap | ElseExpr HandleMap ::= '{' HandleArm (',' HandleArm)* ','? '}' -HandleArm ::= HandlePattern '=>' ErrorPath +HandleArm ::= HandlePattern '->' (ErrorPath | Block) HandlePattern ::= ErrorPath | '_' ErrorPath ::= Identifier ('.' Identifier)* EnumCasePath ::= Identifier '.' Identifier @@ -560,13 +559,15 @@ ArgList ::= Expr (',' Expr)* Literal ::= IntLit | FloatLit | StringLit | BoolLit BoolLit ::= 'true' | 'false' -PrimaryExpr ::= Literal | Identifier | ThisExpr | NewExpr | BindExpr | SomeExpr | NoneExpr | UnitExpr | TupleExpr | GroupExpr | Block +PrimaryExpr ::= Literal | Identifier | ThisExpr | NewExpr | BindExpr | SomeExpr | NoneExpr | OkExpr | ErrExpr | UnitExpr | TupleExpr | GroupExpr | Block ThisExpr ::= 'this' NewExpr ::= 'new' NewTarget '(' ArgList? ')' NewTarget ::= Identifier ('.' Identifier)? BindExpr ::= 'bind' '(' Expr ',' Identifier ')' SomeExpr ::= 'some' '(' Expr ')' NoneExpr ::= 'none' +OkExpr ::= 'ok' '(' Expr ')' +ErrExpr ::= 'err' '(' ErrorPath ')' UnitExpr ::= '(' ')' TupleExpr ::= '(' TupleExprItem ',' TupleExprItem (',' TupleExprItem){0,4} ')' TupleExprItem ::= Identifier ':' Expr | Expr @@ -648,7 +649,7 @@ Diagnostics that require name resolution, overload resolution, or type context a - invalid `some(...)` construction form, - invalid `ok(...)` construction form, - invalid `err(...)` construction form, -- use of `ok(...)` or `err(...)` outside `return`, +- use of `ok(...)` or `err(...)` outside allowed result-flow positions, - invalid `bind(...)` construction form, - invalid `else` extraction form, - invalid `if` expression form, @@ -679,7 +680,7 @@ Diagnostics that require name resolution, overload resolution, or type context a This section defines the `optional` type. All rules in this section are normative. -`optional` represents the explicit presence or absence of a payload, without exceptions, traps, or implicit unwrapping. +`optional` represents the explicit presence or absence of a payload, without exceptions or implicit unwrapping. ### 13.1 Purpose and Design Goals @@ -692,9 +693,8 @@ All rules in this section are normative. Design goals: - no implicit unwrapping, -- no runtime traps, -- no heap allocation, -- stack-only representation. +- no runtime trap behavior of its own, +- explicit fallback extraction. ### 13.2 Type Definition @@ -742,6 +742,7 @@ Rules: - If `opt` is `some(v)`, the expression evaluates to `v`. - If `opt` is `none`, the expression evaluates to `fallback`. - The type of `fallback` must be compatible with the declared payload carrier or tuple shape. +- `fallback` is evaluated only when `opt` is `none`. ### 13.5 Control Flow and Functions @@ -794,7 +795,6 @@ Design goals: - no exceptions, - no implicit error propagation, -- stack-only representation, - explicit, typed error handling. ### 14.2 Return-Only Definition @@ -814,7 +814,7 @@ Rules: ### 14.3 Construction Surface -A `result` outcome is produced only by function return forms: +A `result` outcome is produced through special result-flow forms: ```pbs return ok(value); @@ -825,11 +825,11 @@ Rules: - `ok(...)` always requires parentheses and exactly one expression argument. - `err(...)` always requires parentheses and exactly one expression argument. -- `ok(...)` and `err(...)` are built-in return special forms, not ordinary identifiers. +- `ok(...)` and `err(...)` are built-in result-flow special forms, not ordinary identifiers. - `ok(value)` produces a success payload. - `err(label)` produces a failure payload. - `label` must match error type `E`. -- `ok(...)` and `err(...)` are not general-purpose value constructors in v1 core; they are valid only in function return flow for `result`. +- `ok(...)` and `err(...)` are not general-purpose value constructors in v1 core; they are valid only in function return flow and in `handle` arm blocks. ### 14.4 `!` Propagation Operator @@ -848,17 +848,21 @@ Rules: - If `expr` is success, expression evaluates to wrapped value. - If `expr` is error, the enclosing function returns `err(e)` immediately. -### 14.5 Error Mapping with `handle` +### 14.5 Result Processing with `handle` -`handle` is the only active construct for extracting success values while remapping error labels. +`handle` is the active construct for extracting success values while processing typed `result` errors. Syntax: ```pbs value = handle expr { - ErrorA.case1 => ErrorB.mapped1, - ErrorA.case2 => ErrorB.mapped2, - _ => ErrorB.default, + ErrorA.case1 -> ErrorB.mapped1, + ErrorA.case2 -> { + ok(fallback_value) + }, + _ -> { + err(ErrorB.default) + }, }; ``` @@ -866,8 +870,13 @@ Rules: - `expr` must produce `result Payload1`. - The enclosing function must return `result Payload2`. -- Arms map `E1` labels to `E2` labels. +- Each arm matches one source error case or `_`. - Arms must be exhaustive (explicitly or with `_`). +- A short arm of the form `E1.case -> E2.case` is sugar for a block arm that returns `err(E2.case)`. +- A block arm must terminate with either `ok(payload)` or `err(E2.case)`. +- `ok(payload)` recovers locally and makes the `handle` expression yield `payload`. +- `err(E2.case)` performs immediate enclosing-function return with `err(E2.case)`. +- `handle` does not intercept `trap`. ### 14.6 Restrictions @@ -1141,8 +1150,8 @@ fn outer_propagate() -> result int { fn outer_remap() -> result int { let v: int = handle inner() { - ErrorA.bad_input => ErrorB.invalid, - _ => ErrorB.generic, + ErrorA.bad_input -> ErrorB.invalid, + _ -> ErrorB.generic, }; return ok(v); } diff --git a/docs/pbs/specs/4. Static Semantics Specification.md b/docs/pbs/specs/4. Static Semantics Specification.md index 3b5b7423..ae1ea01f 100644 --- a/docs/pbs/specs/4. Static Semantics Specification.md +++ b/docs/pbs/specs/4. Static Semantics Specification.md @@ -342,7 +342,7 @@ Rules: - `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. +- When that stored context is identity-bearing, the resulting callback preserves the same captured identity rather than copying an independent underlying object. - `bind(context, fn_name)` does not introduce general closures; it is explicit partial binding of the first parameter only. - Callback compatibility ignores labels and compares ordered input/output slot types plus the return-surface kind. @@ -620,17 +620,20 @@ Rules: - 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 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. +- `ok(...)` and `err(...)` are special result-flow forms rather than ordinary value expressions. - `expr!` requires `expr` to have static type `result P`. - `expr!` is valid only when the enclosing function returns `result 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 P`. - `handle expr { ... }` is valid only when the enclosing function returns `result 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(...)`. +- A short `handle` arm `E1.case -> E2.case` is valid only when `E2.case` resolves to a declared case of the target error type `E2`. +- A block `handle` arm must terminate with either `ok(payload)` or `err(E2.case)`. +- In a `handle` arm, `ok(payload)` is valid only when `payload` is compatible with the success payload shape `P`. +- In a `handle` arm, `err(E2.case)` is valid only when `E2.case` resolves to a declared case of the target error type `E2`. +- In a `handle` arm, `ok(payload)` yields the value of the `handle` expression, while `err(E2.case)` performs immediate enclosing-function return. ### 3.18 Required static diagnostics @@ -733,7 +736,7 @@ At minimum, deterministic static diagnostics are required for: - invalid `else` extraction over non-optional operand, - fallback type mismatch in `else` extraction, - invalid `some(...)` construction form, -- use of `ok(...)` or `err(...)` outside `return`, +- use of `ok(...)` or `err(...)` outside allowed result-flow positions, - invalid `ok(...)` construction form, - invalid `err(...)` construction form, - invalid error label in `err(...)`, @@ -743,6 +746,8 @@ At minimum, deterministic static diagnostics are required for: - non-exhaustive `handle` mapping, - duplicate `handle` mapping arm, - invalid mapped error label in `handle`, +- invalid `ok(...)` payload in `handle`, +- invalid terminal form of a `handle` arm block, - attempted use of a single-slot tuple literal where no such surface form exists, - member access on a missing struct field, - read access to an inaccessible private struct field, diff --git a/docs/pbs/specs/9. Dynamic Semantics Specification.md b/docs/pbs/specs/9. Dynamic Semantics Specification.md index 4d569c31..fdacf682 100644 --- a/docs/pbs/specs/9. Dynamic Semantics Specification.md +++ b/docs/pbs/specs/9. Dynamic Semantics Specification.md @@ -1,23 +1,23 @@ # PBS Dynamic Semantics Specification -Status: Draft v0 (Skeleton) +Status: Draft v1 (Temporary) Applies to: runtime-observable behavior of PBS core programs ## 1. Purpose -This document will define the normative dynamic semantics of PBS core. +This document defines the normative dynamic semantics of PBS core. Its purpose is to make runtime behavior convergent across implementations by fixing: - execution ordering, - runtime evaluation of expressions and statements, -- abrupt completion and trap propagation, +- abrupt completion and propagation behavior, - runtime behavior of effect surfaces such as `optional` and `result`, - the execution boundary between ordinary PBS code, callbacks, contract calls, and host-backed calls. ## 2. Scope -This document is intended to define: +This document defines: - the observable execution model of PBS core, - evaluation order for expressions, statements, and blocks, @@ -57,12 +57,12 @@ This document depends on, at minimum: - `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: +This document integrates the following accepted decisions: -- `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` +- `docs/pbs/decisions/Dynamic Semantics - Execution Model Decision.md` +- `docs/pbs/decisions/Dynamic Semantics - Effect Surfaces Decision.md` +- `docs/pbs/decisions/Dynamic Semantics - Branch Selection Decision.md` +- `docs/pbs/decisions/Host Memory Boundary Decision.md` ## 5. Already-Settled Inputs @@ -72,62 +72,285 @@ The following inputs are already fixed elsewhere and must not be contradicted he - `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` function fallthrough is a compile-time error. -- `ok(...)` and `err(...)` are not ordinary first-class runtime constructors in v1 core. +- `ok(...)` and `err(...)` are special result-flow forms rather than ordinary first-class runtime constructors. -## 6. Initial Section Targets +## 6. Execution Baseline -At minimum, the completed document should contain normative sections for: +PBS execution is single-threaded per program instance in v1. -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`, -6. runtime semantics of `apply`, call sugar, and callable categories, -7. branching semantics for `if` and `switch`, -8. traps, determinism, and host-call interaction. +User-visible execution is deterministic and does not expose concurrent interleaving. -## 7. A Ver +User-visible sequencing is defined by: -The following items remain to be closed in agenda discussion before this document can be considered complete. +- evaluation order, +- branch selection, +- abrupt completion, +- result propagation, +- trap propagation, +- and host-call boundaries. -### 7.1 `Dynamic Semantics - Execution Model Agenda.md` +VM-internal frame layout, temporary storage, and lowering steps are not observable unless they change one of the semantic effects above. -- 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. +`FRAME_SYNC` is the only normative safepoint in PBS v1. -### 7.2 `Dynamic Semantics - Effect Surfaces Agenda.md` +## 7. Evaluation Order and Single Evaluation -- Runtime value model of `optional` and `result`. -- 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.1 Default rule -### 7.3 `Heap Model - Agenda.md` and `Memory and Lifetime - Agenda.md` +The default evaluation rule is strict left-to-right unless a construct explicitly states otherwise. -- 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`. +### 7.2 Call evaluation -## 8. Non-Goals +For application: + +1. form the call target, +2. evaluate any receiver or callable artifact needed for target formation exactly once, +3. evaluate arguments in source order from left to right, +4. invoke the resolved target, +5. produce one of: + - normal return, + - explicit `result` propagation, + - or `trap`. + +This rule applies to canonical `apply` and to direct-call sugar that desugars to `apply`. + +`apply` chains are parsed right-associatively, but their observable evaluation still follows the left-to-right rule above. + +### 7.3 Exactly-once guarantees + +The following expressions are evaluated exactly once where they appear: + +- `if` condition, +- `switch` selector, +- the left operand of `opt else fallback`, +- the payload expression of `some(expr)`, +- the operand of `expr!`, +- the operand of `handle expr { ... }`, +- the context expression of `bind(context, fn_name)`, +- call receivers, callees, and argument expressions as required by the call rule above. + +## 8. Blocks and Abrupt Completion + +Statements in a block execute in source order. + +Only the final unsemicoloned expression in a block contributes to the block result. + +Abrupt completion terminates the current construct immediately and prevents later sibling evaluation. + +At minimum, the following are abrupt-completion forms: + +- `return`, +- `break`, +- `continue`, +- `!` on an error path, +- `trap`. + +## 9. `optional` + +### 9.1 Runtime model + +`optional` has exactly two runtime states: + +- `some(payload)` +- `none` + +`none` is the canonical absence of payload. + +### 9.2 Construction + +`some(expr)` evaluates `expr` eagerly and exactly once before forming the `some(payload)` carrier. + +### 9.3 Extraction + +`opt else fallback`: + +1. evaluates the left operand exactly once, +2. yields the extracted payload if that operand evaluates to `some(payload)`, +3. otherwise evaluates `fallback` and yields its value. + +`else` is extraction with fallback, not error handling. + +### 9.4 Trap behavior + +`optional` is trap-free by itself. + +Any trap associated with `some(expr)` or `opt else fallback` arises only from evaluating the relevant subexpressions. + +## 10. `result` + +### 10.1 Runtime role + +`result` is the runtime carrier for success-or-modeled-failure at function boundaries and in expressions whose static type is `result P`. + +Expected, recoverable failures belong to `result`, not to `trap`. + +### 10.2 `!` + +`expr!`: + +1. evaluates `expr` exactly once, +2. yields the extracted success payload if `expr` succeeds, +3. performs immediate enclosing-function return with the same `err(...)` if `expr` yields error. + +`!` does not: + +- remap errors, +- intercept traps, +- or continue ordinary evaluation after the propagated error path is chosen. + +### 10.3 `handle` + +`handle expr { ... }`: + +1. evaluates `expr` exactly once, +2. yields the extracted success payload directly if `expr` succeeds, +3. selects exactly one matching arm if `expr` yields error, +4. executes that arm, +5. requires the arm to terminate with either `ok(payload)` or `err(E2.case)`. + +`ok(payload)` in a `handle` arm recovers locally and makes the `handle` expression yield `payload`. + +`err(E2.case)` in a `handle` arm performs immediate enclosing-function return with `err(E2.case)`. + +For the remap-only case, a short form such as `E1.case -> E2.case` is sugar for an arm block that returns `err(E2.case)`. + +`handle` may execute user-defined logic inside an arm, but it remains specific to modeled `result` errors. + +`handle` does not intercept or convert traps. + +## 11. `apply`, Call Sugar, and `bind` + +### 11.1 Canonical role of `apply` + +`apply` is the canonical universal call surface in PBS v1. + +The same observable call model applies to: + +- top-level functions, +- struct methods, +- service methods, +- contract calls, +- callback calls, +- host-backed calls. + +Callable-specific dispatch may differ internally, but it does not change the user-visible sequencing model defined in this document. + +### 11.2 Effect boundaries + +`apply` does not introduce implicit effect composition. + +If a callable returns: + +- `optional

`, extraction remains explicit through `else`, +- `result P`, propagation or processing remains explicit through `!` or `handle`. + +### 11.3 `bind` + +`bind(context, fn_name)` is the explicit callback-formation mechanism in PBS v1. + +It: + +- evaluates `context` exactly once, +- captures the same struct context identity without copying it, +- attaches that context to the resolved top-level function target, +- produces a callback value whose invocation behaves as if the target function were called with the captured context as its first argument. + +At the language-semantics level, `bind` is trap-free. + +Incompatible binding shape remains a compile-time matter rather than a runtime failure mode. + +Retention and storage consequences of `bind` belong to `Memory and Lifetime Specification.md`. + +## 12. Branch Selection + +### 12.1 `if` + +`if` evaluates its condition exactly once. + +If the condition is `true`, only the selected `then` branch executes. +If the condition is `false`, only the selected `else` branch executes. + +The non-selected branch is not evaluated, even partially. + +### 12.2 `switch` + +`switch` evaluates its selector exactly once and executes exactly one selected arm. + +The non-selected arms are not evaluated. + +`switch` is restricted to statically discriminable selector categories in v1: + +- literal-comparable scalar values, +- enum values, +- canonical `str` values, +- and any other selector category admitted elsewhere by explicit specification. + +`switch` does not accept: + +- `result`, +- `error`, +- structs, +- string object/reference types distinct from canonical `str`, +- heap-backed selector categories. + +Matching is exact and deterministic: + +- enum selectors match by canonical enum-case identity, +- scalar selectors match by the exact equality rule for that scalar category, +- `str` selectors match by canonical static string identity. + +`switch` does not perform structural matching, guard evaluation, or user-defined equality dispatch. + +## 13. Trap, Determinism, and Host Interaction + +### 13.1 Trap boundary + +`trap` is reserved for failures that are: + +- outside the ordinary userland contract, +- not suitably representable as the declared `result` surface, +- caused by runtime or host invariant failure, +- or severe enough that ordinary userland recovery is not part of the v1 language model. + +PBS v1 does not define `try/catch` for traps. + +Traps are not part of ordinary recoverable control flow. + +Any trap aborts the current PBS program execution rather than returning control to ordinary userland flow. + +Control then transfers to runtime or firmware crash handling outside the ordinary language model. + +### 13.2 Host interaction + +Host calls must not introduce user-visible reordering of already-defined PBS evaluation order. + +Expected operational failures of host-backed surfaces should be modeled through their declared contract rather than through ad hoc trap usage. + +Cross-boundary host/userland interaction remains stack-value-based as defined by the host-boundary decision track; direct host-memory manipulation is not part of PBS userland semantics. + +## 14. TODO + +The following items remain editorial or cross-spec integration tasks rather than open semantic agenda questions: + +- the final wording split between this document and `16. Runtime Execution and Initialization Specification.md` for crash handoff after trap, +- the final wording split between this document and `10. Memory and Lifetime Specification.md` for retention/allocation facts that arise during ordinary execution, +- conformance-oriented example coverage once `13. Conformance Test Specification.md` is expanded. + +## 15. Non-Goals - Reopening grammar or static typing unless current text is impossible to execute normatively. - Defining exact GC collection strategy. - Designing future async, actor, or scheduler models. - Specifying backend optimization policy. -## 9. Exit Criteria +## 16. Exit Criteria -This document is ready to move beyond skeleton status only when: +This document is ready to move beyond temporary draft status only when: -1. every runtime-observable core construct has a deterministic evaluation model, +1. every runtime-observable core construct has deterministic evaluation wording, 2. trap versus status-value behavior is explicit for every effect-bearing construct, 3. host-call interaction rules are stated without relying on informal prose elsewhere, -4. the document can drive runtime conformance tests without requiring agenda backfill, -5. the document no longer depends on unresolved `A Ver` items for core v1 behavior. +4. the document can drive runtime conformance tests without decision backfill, +5. the remaining TODO items are reduced to editorial integration rather than semantic uncertainty.