prometeu-studio/docs/pbs/specs/9. Dynamic Semantics Specification.md

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.