discussion framework migration
This commit is contained in:
@@ -0,0 +1,356 @@
|
||||
# PBS Dynamic Semantics Specification
|
||||
|
||||
Status: Draft v1 (Temporary)
|
||||
Applies to: runtime-observable behavior of PBS core programs
|
||||
|
||||
## 1. Purpose
|
||||
|
||||
This document defines the normative dynamic semantics of PBS core.
|
||||
|
||||
Its purpose is to make runtime behavior convergent across implementations by fixing:
|
||||
|
||||
- execution ordering,
|
||||
- runtime evaluation of expressions and statements,
|
||||
- abrupt completion and propagation behavior,
|
||||
- runtime behavior of effect surfaces such as `optional` and `result`,
|
||||
- the execution boundary between ordinary PBS code, callbacks, contract calls, and host-backed calls.
|
||||
|
||||
## 2. Scope
|
||||
|
||||
This document defines:
|
||||
|
||||
- the observable execution model of PBS core,
|
||||
- evaluation order for expressions, statements, and blocks,
|
||||
- runtime branch selection for `if` and `switch`,
|
||||
- runtime application behavior for `apply`, call sugar, methods, contracts, callbacks, and host-backed call surfaces,
|
||||
- runtime behavior of `optional`, `result<E>`, `else`, `!`, and `handle`,
|
||||
- abrupt completion (`return`, `break`, `continue`) and trap propagation,
|
||||
- determinism requirements that affect execution behavior.
|
||||
|
||||
This document does not define:
|
||||
|
||||
- static typing or overload resolution rules,
|
||||
- GC algorithm internals,
|
||||
- exact IR shape or lowering passes,
|
||||
- diagnostics catalog wording,
|
||||
- the full PBX binary format.
|
||||
|
||||
## 3. Authority and Precedence
|
||||
|
||||
Normative precedence:
|
||||
|
||||
1. Runtime authority (`docs/specs/hardware/topics/chapter-2.md`, `chapter-3.md`, `chapter-9.md`, `chapter-12.md`, `chapter-16.md`)
|
||||
2. Bytecode authority (`docs/specs/bytecode/ISA_CORE.md`)
|
||||
3. `3. Core Syntax Specification.md`
|
||||
4. `4. Static Semantics Specification.md`
|
||||
5. This document
|
||||
|
||||
If a rule here conflicts with higher authority, it is invalid.
|
||||
|
||||
## 4. Normative Inputs
|
||||
|
||||
This document depends on, at minimum:
|
||||
|
||||
- `1. Language Charter.md`
|
||||
- `3. Core Syntax Specification.md`
|
||||
- `4. Static Semantics Specification.md`
|
||||
- `5. Manifest, Stdlib, and SDK Resolution Specification.md`
|
||||
- `6.2. Host ABI Binding and Loader Resolution Specification.md`
|
||||
|
||||
This document integrates the following accepted decisions:
|
||||
|
||||
- `docs/pbs/decisions/Dynamic Semantics - Execution Model Decision.md`
|
||||
- `docs/pbs/decisions/Dynamic Semantics - Effect Surfaces Decision.md`
|
||||
- `docs/pbs/decisions/Dynamic Semantics - Branch Selection Decision.md`
|
||||
- `docs/pbs/decisions/Host Memory Boundary Decision.md`
|
||||
|
||||
## 5. Already-Settled Inputs
|
||||
|
||||
The following inputs are already fixed elsewhere and must not be contradicted here:
|
||||
|
||||
- PBS prioritizes determinism and compatibility over ergonomics when the two conflict.
|
||||
- `FRAME_SYNC`-based execution semantics remain preserved.
|
||||
- No non-deterministic async execution model is part of PBS v1.
|
||||
- Function application is defined on the canonical `apply` surface, with call sugar desugaring to `apply`.
|
||||
- `optional T` function fallthrough yields `none`.
|
||||
- `result<E>` function fallthrough is a compile-time error.
|
||||
- `ok(...)` and `err(...)` are special result-flow forms rather than ordinary first-class runtime constructors.
|
||||
|
||||
## 6. Execution Baseline
|
||||
|
||||
PBS execution is single-threaded per program instance in v1.
|
||||
|
||||
User-visible execution is deterministic and does not expose concurrent interleaving.
|
||||
|
||||
User-visible sequencing is defined by:
|
||||
|
||||
- evaluation order,
|
||||
- branch selection,
|
||||
- abrupt completion,
|
||||
- result propagation,
|
||||
- trap propagation,
|
||||
- and host-call boundaries.
|
||||
|
||||
VM-internal frame layout, temporary storage, and lowering steps are not observable unless they change one of the semantic effects above.
|
||||
|
||||
`FRAME_SYNC` is the only normative safepoint in PBS v1.
|
||||
|
||||
## 7. Evaluation Order and Single Evaluation
|
||||
|
||||
### 7.1 Default rule
|
||||
|
||||
The default evaluation rule is strict left-to-right unless a construct explicitly states otherwise.
|
||||
|
||||
### 7.2 Call evaluation
|
||||
|
||||
For application:
|
||||
|
||||
1. form the call target,
|
||||
2. evaluate any receiver or callable artifact needed for target formation exactly once,
|
||||
3. evaluate arguments in source order from left to right,
|
||||
4. invoke the resolved target,
|
||||
5. produce one of:
|
||||
- normal return,
|
||||
- explicit `result<E>` propagation,
|
||||
- or `trap`.
|
||||
|
||||
This rule applies to canonical `apply` and to direct-call sugar that desugars to `apply`.
|
||||
|
||||
`apply` chains are parsed right-associatively, but their observable evaluation still follows the left-to-right rule above.
|
||||
|
||||
### 7.3 Exactly-once guarantees
|
||||
|
||||
The following expressions are evaluated exactly once where they appear:
|
||||
|
||||
- `if` condition,
|
||||
- `switch` selector,
|
||||
- the left operand of `opt else fallback`,
|
||||
- the payload expression of `some(expr)`,
|
||||
- the operand of `expr!`,
|
||||
- the operand of `handle expr { ... }`,
|
||||
- the context expression of `bind(context, fn_name)`,
|
||||
- call receivers, callees, and argument expressions as required by the call rule above.
|
||||
|
||||
## 8. Blocks and Abrupt Completion
|
||||
|
||||
Statements in a block execute in source order.
|
||||
|
||||
Only the final unsemicoloned expression in a block contributes to the block result.
|
||||
|
||||
Abrupt completion terminates the current construct immediately and prevents later sibling evaluation.
|
||||
|
||||
At minimum, the following are abrupt-completion forms:
|
||||
|
||||
- `return`,
|
||||
- `break`,
|
||||
- `continue`,
|
||||
- `!` on an error path,
|
||||
- `trap`.
|
||||
|
||||
## 9. `optional`
|
||||
|
||||
### 9.1 Runtime model
|
||||
|
||||
`optional` has exactly two runtime states:
|
||||
|
||||
- `some(payload)`
|
||||
- `none`
|
||||
|
||||
`none` is the canonical absence of payload.
|
||||
|
||||
### 9.2 Construction
|
||||
|
||||
`some(expr)` evaluates `expr` eagerly and exactly once before forming the `some(payload)` carrier.
|
||||
|
||||
### 9.3 Extraction
|
||||
|
||||
`opt else fallback`:
|
||||
|
||||
1. evaluates the left operand exactly once,
|
||||
2. yields the extracted payload if that operand evaluates to `some(payload)`,
|
||||
3. otherwise evaluates `fallback` and yields its value.
|
||||
|
||||
`else` is extraction with fallback, not error handling.
|
||||
|
||||
### 9.4 Trap behavior
|
||||
|
||||
`optional` is trap-free by itself.
|
||||
|
||||
Any trap associated with `some(expr)` or `opt else fallback` arises only from evaluating the relevant subexpressions.
|
||||
|
||||
## 10. `result<E>`
|
||||
|
||||
### 10.1 Runtime role
|
||||
|
||||
`result<E>` is the runtime carrier for success-or-modeled-failure at function boundaries and in expressions whose static type is `result<E> P`.
|
||||
|
||||
Expected, recoverable failures belong to `result<E>`, not to `trap`.
|
||||
|
||||
### 10.2 `!`
|
||||
|
||||
`expr!`:
|
||||
|
||||
1. evaluates `expr` exactly once,
|
||||
2. yields the extracted success payload if `expr` succeeds,
|
||||
3. performs immediate enclosing-function return with the same `err(...)` if `expr` yields error.
|
||||
|
||||
`!` does not:
|
||||
|
||||
- remap errors,
|
||||
- intercept traps,
|
||||
- or continue ordinary evaluation after the propagated error path is chosen.
|
||||
|
||||
### 10.3 `handle`
|
||||
|
||||
`handle expr { ... }`:
|
||||
|
||||
1. evaluates `expr` exactly once,
|
||||
2. yields the extracted success payload directly if `expr` succeeds,
|
||||
3. selects exactly one matching arm if `expr` yields error,
|
||||
4. executes that arm,
|
||||
5. requires the arm to terminate with either `ok(payload)` or `err(E2.case)`.
|
||||
|
||||
`ok(payload)` in a `handle` arm recovers locally and makes the `handle` expression yield `payload`.
|
||||
|
||||
`err(E2.case)` in a `handle` arm performs immediate enclosing-function return with `err(E2.case)`.
|
||||
|
||||
For the remap-only case, a short form such as `E1.case -> E2.case` is sugar for an arm block that returns `err(E2.case)`.
|
||||
|
||||
`handle` may execute user-defined logic inside an arm, but it remains specific to modeled `result` errors.
|
||||
|
||||
`handle` does not intercept or convert traps.
|
||||
|
||||
## 11. `apply`, Call Sugar, and `bind`
|
||||
|
||||
### 11.1 Canonical role of `apply`
|
||||
|
||||
`apply` is the canonical universal call surface in PBS v1.
|
||||
|
||||
The same observable call model applies to:
|
||||
|
||||
- top-level functions,
|
||||
- struct methods,
|
||||
- service methods,
|
||||
- contract calls,
|
||||
- callback calls,
|
||||
- host-backed calls.
|
||||
|
||||
Callable-specific dispatch may differ internally, but it does not change the user-visible sequencing model defined in this document.
|
||||
|
||||
### 11.2 Effect boundaries
|
||||
|
||||
`apply` does not introduce implicit effect composition.
|
||||
|
||||
If a callable returns:
|
||||
|
||||
- `optional<P>`, extraction remains explicit through `else`,
|
||||
- `result<E> P`, propagation or processing remains explicit through `!` or `handle`.
|
||||
|
||||
### 11.3 `bind`
|
||||
|
||||
`bind(context, fn_name)` is the explicit callback-formation mechanism in PBS v1.
|
||||
|
||||
It:
|
||||
|
||||
- evaluates `context` exactly once,
|
||||
- captures the same struct context identity without copying it,
|
||||
- attaches that context to the resolved top-level function target,
|
||||
- produces a callback value whose invocation behaves as if the target function were called with the captured context as its first argument.
|
||||
|
||||
At the language-semantics level, `bind` is trap-free.
|
||||
|
||||
Incompatible binding shape remains a compile-time matter rather than a runtime failure mode.
|
||||
|
||||
Retention and storage consequences of `bind` belong to `Memory and Lifetime Specification.md`.
|
||||
|
||||
## 12. Branch Selection
|
||||
|
||||
### 12.1 `if`
|
||||
|
||||
`if` evaluates its condition exactly once.
|
||||
|
||||
If the condition is `true`, only the selected `then` branch executes.
|
||||
If the condition is `false`, only the selected `else` branch executes.
|
||||
|
||||
The non-selected branch is not evaluated, even partially.
|
||||
|
||||
### 12.2 `switch`
|
||||
|
||||
`switch` evaluates its selector exactly once and executes exactly one selected arm.
|
||||
|
||||
The non-selected arms are not evaluated.
|
||||
|
||||
`switch` is restricted to statically discriminable selector categories in v1:
|
||||
|
||||
- literal-comparable scalar values,
|
||||
- enum values,
|
||||
- canonical `str` values,
|
||||
- and any other selector category admitted elsewhere by explicit specification.
|
||||
|
||||
`switch` does not accept:
|
||||
|
||||
- `result`,
|
||||
- `error`,
|
||||
- structs,
|
||||
- string object/reference types distinct from canonical `str`,
|
||||
- heap-backed selector categories.
|
||||
|
||||
Matching is exact and deterministic:
|
||||
|
||||
- enum selectors match by canonical enum-case identity,
|
||||
- scalar selectors match by the exact equality rule for that scalar category,
|
||||
- `str` selectors match by canonical static string identity.
|
||||
|
||||
`switch` does not perform structural matching, guard evaluation, or user-defined equality dispatch.
|
||||
|
||||
## 13. Trap, Determinism, and Host Interaction
|
||||
|
||||
### 13.1 Trap boundary
|
||||
|
||||
`trap` is reserved for failures that are:
|
||||
|
||||
- outside the ordinary userland contract,
|
||||
- not suitably representable as the declared `result<E>` surface,
|
||||
- caused by runtime or host invariant failure,
|
||||
- or severe enough that ordinary userland recovery is not part of the v1 language model.
|
||||
|
||||
PBS v1 does not define `try/catch` for traps.
|
||||
|
||||
Traps are not part of ordinary recoverable control flow.
|
||||
|
||||
Any trap aborts the current PBS program execution rather than returning control to ordinary userland flow.
|
||||
|
||||
Control then transfers to runtime or firmware crash handling outside the ordinary language model.
|
||||
|
||||
### 13.2 Host interaction
|
||||
|
||||
Host calls must not introduce user-visible reordering of already-defined PBS evaluation order.
|
||||
|
||||
Expected operational failures of host-backed surfaces should be modeled through their declared contract rather than through ad hoc trap usage.
|
||||
|
||||
Cross-boundary host/userland interaction remains stack-value-based as defined by the host-boundary decision track; direct host-memory manipulation is not part of PBS userland semantics.
|
||||
|
||||
## 14. TODO
|
||||
|
||||
The following items remain editorial or cross-spec integration tasks rather than open semantic agenda questions:
|
||||
|
||||
- the final wording split between this document and `16. Runtime Execution and Initialization Specification.md` for crash handoff after trap,
|
||||
- the final wording split between this document and `10. Memory and Lifetime Specification.md` for retention/allocation facts that arise during ordinary execution,
|
||||
- conformance-oriented example coverage once `13. Conformance Test Specification.md` is expanded.
|
||||
|
||||
## 15. Non-Goals
|
||||
|
||||
- Reopening grammar or static typing unless current text is impossible to execute normatively.
|
||||
- Defining exact GC collection strategy.
|
||||
- Designing future async, actor, or scheduler models.
|
||||
- Specifying backend optimization policy.
|
||||
|
||||
## 16. Exit Criteria
|
||||
|
||||
This document is ready to move beyond temporary draft status only when:
|
||||
|
||||
1. every runtime-observable core construct has deterministic evaluation wording,
|
||||
2. trap versus status-value behavior is explicit for every effect-bearing construct,
|
||||
3. host-call interaction rules are stated without relying on informal prose elsewhere,
|
||||
4. the document can drive runtime conformance tests without decision backfill,
|
||||
5. the remaining TODO items are reduced to editorial integration rather than semantic uncertainty.
|
||||
Reference in New Issue
Block a user