134 lines
5.4 KiB
Markdown
134 lines
5.4 KiB
Markdown
# 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.
|