diff --git a/docs/agendas/Dynamic Semantics - Effect Surfaces Agenda.md b/docs/agendas/Dynamic Semantics - Effect Surfaces Agenda.md new file mode 100644 index 00000000..c797acd5 --- /dev/null +++ b/docs/agendas/Dynamic Semantics - Effect Surfaces Agenda.md @@ -0,0 +1,95 @@ +# Dynamic Semantics - Effect Surfaces Agenda + +Status: Working agenda (pre-spec) +Purpose: close the runtime behavior of PBS effect and control surfaces before drafting the dynamic semantics spec + +## 1. Context + +PBS v1 already commits to several user-visible effect surfaces: + +- `optional`, +- `result`, +- `apply`, +- `bind`, +- `switch`, +- `if`, +- `else`, +- `handle`, +- `!` result propagation. + +Static semantics explains where these forms are legal. +What is still missing is the runtime contract: evaluation timing, payload extraction behavior, propagation order, and interaction with traps and allocation. + +## 2. Decisions to Produce + +This agenda must end with decisions for: + +1. The runtime value model of `optional` and `result`. +2. The evaluation and propagation semantics of `apply`, `bind`, `else`, `!`, and `handle`. +3. The runtime branch-selection model for `if` and `switch`. +4. The exact boundary between explicit status values and true runtime traps. + +## 3. Core Questions + +### Q1. `optional` + +- Is `some(expr)` evaluated eagerly before container construction? +- Does `opt else fallback` evaluate `fallback` only on `none`? +- Is `optional` guaranteed trap-free at runtime except for traps produced by evaluating its subexpressions? + +### Q2. `result` + +- Is `ok(...)` / `err(...)` purely a return-flow construct with no standalone runtime value form in v1? +- How exactly does `expr!` propagate failure through the enclosing function? +- Does `handle expr { ... }` first evaluate `expr`, then dispatch exactly one remapping arm, or are there any hidden intermediate forms? + +### Q3. `apply` + +- Is direct-call sugar defined entirely through canonical `apply`, including runtime order? +- When `apply` resolves to a callback, method, contract implementation, or host-backed callable, what runtime steps are shared and what remains callable-specific? +- Must `apply` preserve a single common trap model regardless of callable kind? + +### Q4. `bind` + +- What runtime artifact does `bind(context, fn_name)` produce: a nominal callback pair, hidden object, or other VM-level value category? +- Is the `context` expression always evaluated exactly once at bind time? +- Does `bind` itself allocate, and if yes, must that be part of the visible cost contract? + +### Q5. `switch` and `if` + +- Is the selector/condition evaluated exactly once before branch selection? +- Does `switch` compare enum cases and scalar literals via a single equality model, or are there construct-specific rules? +- Are non-selected arm blocks guaranteed not to evaluate at all? + +### Q6. Status values vs traps + +- Which user-visible failures must stay in `optional` / `result` space instead of trapping? +- Are there any operations over these surfaces that may still trap despite their explicit effect model? + +### Q7. Allocation and copy visibility + +- Which of these constructs may allocate, copy, or retain heap state as part of normal execution? +- Which of those costs must be reflected later by the diagnostics spec? + +## 4. Expected Spec Material + +After discussion, this agenda should directly feed sections of `Dynamic Semantics Specification.md` covering: + +1. runtime values and carrier forms, +2. call and callback execution, +3. effect propagation and remapping, +4. conditional and branching execution, +5. trap versus status-value behavior for effect-bearing constructs. + +## 5. Non-Goals + +- Revisiting the static typing surface already settled in `4. Static Semantics Specification.md`. +- Designing collection APIs or general async/error subsystems. +- Reopening reserved syntax such as future `match`. + +## 6. Inputs + +- `3. Core Syntax Specification.md` +- `4. Static Semantics Specification.md` +- `Heap Model - Agenda.md` +- `Dynamic Semantics - Execution Model Agenda.md` diff --git a/docs/agendas/Dynamic Semantics - Execution Model Agenda.md b/docs/agendas/Dynamic Semantics - Execution Model Agenda.md new file mode 100644 index 00000000..87e1ed83 --- /dev/null +++ b/docs/agendas/Dynamic Semantics - Execution Model Agenda.md @@ -0,0 +1,86 @@ +# Dynamic Semantics - Execution Model Agenda + +Status: Working agenda (pre-spec) +Purpose: close the observable execution model for PBS before drafting the dynamic semantics spec + +## 1. Context + +Static semantics already fixes a large part of the source model, but several runtime-visible questions remain open: + +- exact evaluation order, +- what counts as a trap versus an ordinary control-flow outcome, +- how `FRAME_SYNC` and deterministic safepoints constrain execution, +- what host calls are allowed to observe or perturb execution order. + +These decisions should be closed before effect surfaces and memory/lifetime rules are written as normative dynamic semantics. + +## 2. Decisions to Produce + +This agenda must end with decisions for: + +1. The observable sequencing model for expressions, statements, and blocks. +2. The normative evaluation order for arguments, receivers, selectors, and chained `apply`. +3. The abrupt-completion model: `return`, `break`, `continue`, result propagation, and traps. +4. The interaction between host calls, safepoints, and deterministic execution. + +## 3. Core Questions + +### Q1. Global execution model + +- Is PBS execution defined as single-threaded per program instance in v1? +- Which execution steps are observable to user code, and which remain VM-internal? + +### Q2. Expression evaluation order + +- Is expression evaluation strictly left-to-right unless a construct says otherwise? +- For `f(a, b)` / `f apply (a, b)`, what is the order of evaluating callee, receiver, and argument expressions? +- For `f1 apply f2 apply x`, what is the runtime order implied by the right-associative parse? + +### Q3. Single-evaluation guarantees + +- Which constructs normatively evaluate subexpressions exactly once? +- Does that guarantee apply to `switch` selectors, `if` conditions, `opt else fallback`, `handle expr`, and `bind(context, fn_name)` context expressions? + +### Q4. Blocks and control transfer + +- How are statement sequencing and tail-expression evaluation defined inside blocks? +- At what point does `return`, `break`, or `continue` abort further evaluation in the current construct? + +### Q5. Trap model + +- Which runtime failures are traps rather than status values or compile-time rejection? +- Must trap categories be stable and named in the dynamic semantics spec? +- Are traps deterministic for the same program input and runtime capability set? + +### Q6. Host interaction + +- Can host calls introduce extra traps beyond ordinary PBS runtime failures? +- Where are safepoints guaranteed around host calls, allocation-heavy operations, and loop back-edges? + +### Q7. Determinism boundary + +- Which behaviors must be identical across conforming implementations? +- Which details may vary as implementation strategy without changing observable behavior? + +## 4. Expected Spec Material + +After discussion, this agenda should directly feed sections of `Dynamic Semantics Specification.md` covering: + +1. execution state and step ordering, +2. evaluation order by construct, +3. abrupt completion and trap propagation, +4. host-call interaction constraints, +5. determinism requirements for conforming runtimes. + +## 5. Non-Goals + +- Revisiting grammar or typing unless the current surface is impossible to specify dynamically. +- Defining diagnostics wording in detail. +- Designing allocator APIs or collection libraries. + +## 6. Inputs + +- `1. Language Charter.md` +- `3. Core Syntax Specification.md` +- `4. Static Semantics Specification.md` +- `Heap Model - Agenda.md` diff --git a/docs/agendas/Heap Model - Agenda.md b/docs/agendas/Heap Model - Agenda.md new file mode 100644 index 00000000..3dc37efb --- /dev/null +++ b/docs/agendas/Heap Model - Agenda.md @@ -0,0 +1,89 @@ +# PBS Heap Model - Agenda + +Status: Working umbrella agenda (pre-spec) +Purpose: coordinate the PBS discussions that define runtime-visible allocation, lifetime, and heap/host boundaries + +## 1. Context + +Legacy PBS experiments used explicit RC/HIP syntax (`alloc`, `borrow`, `mutate`, `peek`, `take`, `weak`). +Current runtime authority is GC-based with deterministic safepoints. + +The original heap agenda proved too broad because the open questions now span three different but coupled areas: + +- observable execution behavior, +- effect/control surfaces (`optional`, `result`, `apply`, `bind`, `switch`), +- memory ownership, GC, and host-memory boundaries. + +This file now acts as the umbrella agenda that keeps those discussions aligned instead of trying to close every detail in one pass. + +## 2. Agenda Split + +The work is split into the following dedicated agendas: + +1. `Dynamic Semantics - Execution Model Agenda.md` +2. `Dynamic Semantics - Effect Surfaces Agenda.md` +3. `Memory and Lifetime - Agenda.md` + +The heap model is still the cross-cutting reference because allocation visibility, traps, and host boundaries must line up across all three. + +## 3. Cross-Agenda Decisions This Umbrella Owns + +This umbrella must keep the following decisions coherent across the child agendas: + +1. GC is the baseline runtime model for PBS core unless a future profile explicitly says otherwise. +2. Core v1 does not require explicit lifetime syntax for ordinary user code. +3. Deterministic execution and `FRAME_SYNC` constraints override ergonomics when the two conflict. +4. Runtime-visible costs must be surfaced through diagnostics/tooling when code allocates, copies, crosses the host boundary, or can trap. +5. The VM heap and host-owned memory must remain distinct in the user model even when APIs make the boundary feel ergonomic. + +## 4. Questions That Must Stay Aligned + +### Q1. Baseline runtime authority + +- Is GC always the default execution model for PBS core? (expected: yes) +- Which safepoints are part of the observable contract versus implementation detail? + +### Q2. Language vs library boundary + +- Which old RC/HIP concepts stay reserved-only in core syntax? +- Which advanced workflows move to stdlib/tooling APIs rather than language keywords? + +### Q3. Cost visibility contract + +- Which allocations, copies, host transfers, and trap paths must be visible in diagnostics? +- Which cost facts are normative, and which remain profiler-quality best effort? + +### Q4. Host boundary + +- How does PBS communicate "VM heap vs host-owned memory" without exposing raw host pointers as ordinary user values? +- Which host operations are allowed to allocate or retain memory, and how must that appear to the user? + +### Q5. Migration policy + +- What is the official migration story from legacy RC/HIP concepts? +- What hard criteria must be met before any reserved lifetime keyword can be activated in a future profile? + +## 5. Expected Output Documents + +After the child agendas close, use their decisions to draft: + +1. `Dynamic Semantics Specification.md` +2. `Memory and Lifetime Specification.md` +3. `Diagnostics Specification.md` + +The existing `4. Static Semantics Specification.md` may receive follow-up clarifications where memory or effect rules need stronger static wording. + +## 6. Non-Goals for This Umbrella Agenda + +- Defining new VM opcodes. +- Reintroducing RC as mandatory runtime strategy. +- Designing full stdlib memory-management APIs in this pass. +- Settling backend/lowering internals that do not affect observable semantics. + +## 7. Working Assumptions + +1. GC remains baseline for PBS core. +2. Explicit heap control is opt-in and likely library/tooling-driven. +3. Deterministic behavior and frame-sync constraints are non-negotiable. +4. Language should expose cost signals without forcing expert-only syntax. +5. Child agendas may narrow terminology, but they must not conflict on runtime-observable behavior. diff --git a/docs/agendas/Host ABI Gate Validation Agenda.md b/docs/agendas/Host ABI Gate Validation Agenda.md new file mode 100644 index 00000000..a7be669e --- /dev/null +++ b/docs/agendas/Host ABI Gate Validation Agenda.md @@ -0,0 +1,63 @@ +# Host ABI Gate Validation Agenda + +Status: Resolved agenda +Purpose: validate whether the current Host ABI contract is already stable enough to stop blocking the next phase + +## 1. Context + +This agenda validates whether `6. Host ABI Binding and Loader Resolution Specification.md` is already sufficient as the working contract for the path: + +`declare host` -> PBX metadata -> loader resolution -> numeric syscall execution + +The question here is not whether every binary-format detail is final. +The question is whether the current contract is already stable enough to unblock the next phase. + +## 2. Decision + +Decision: sufficient for the next phase. + +The current Host ABI contract is explicit enough to unblock the next stage even if the specification remains marked `Temporary` for now. + +`Temporary` should be interpreted here as "final binary-format and integration details may still be hardened", not as "core contract still missing". + +## 3. Why This Is Sufficient + +The current specification already fixes the parts that matter for phase-gating: + +1. Canonical identity is stable and loader-facing: `(module, name, version)`. +2. The boundary between source-level `declare host` and runtime-facing canonical metadata is explicit. +3. The PBX contract is defined through mandatory `SYSC` metadata with required fields and validation rules. +4. Pre-load and post-load call forms are explicit: `HOSTCALL ` before load, `SYSCALL ` after patching. +5. The loader algorithm is normative, ordered, and deterministic. +6. ABI validation responsibility is split clearly between loader and verifier. +7. Capability gating is mandatory during load. +8. Deterministic failure cases are enumerated. + +This is enough to keep compiler, PBX emitter, loader, and VM behavior aligned on the critical host-binding path. + +## 4. Remaining Hardening That Does Not Block + +The following items remain open, but they are hardening and integration details rather than gate blockers: + +1. Final PBX section numbering and chunk registry policy. +2. Final opcode allocation for `HOSTCALL`. +3. Exact loader image materialization strategy (patch in place vs rebuild buffer). +4. Final integration shape with `ProgramImage` or equivalent loaded-program container. + +These items can remain deferred without reopening the core contract above. + +## 5. Practical Interpretation + +For planning purposes, the Host ABI path should now be treated as closed for gate evaluation. + +That means: + +- it does not block the next phase, +- it does not require a semantic redesign before backend/runtime work continues, +- and any remaining work is implementation hardening or binary-format finalization. + +## 6. References + +- `6. Host ABI Binding and Loader Resolution Specification.md` +- `7. Cartridge Manifest and Runtime Capabilities Specification.md` +- `8. Stdlib Environment Packaging and Loading Specification.md` diff --git a/docs/agendas/Memory and Lifetime - Agenda.md b/docs/agendas/Memory and Lifetime - Agenda.md new file mode 100644 index 00000000..4b4ebdfd --- /dev/null +++ b/docs/agendas/Memory and Lifetime - Agenda.md @@ -0,0 +1,94 @@ +# Memory and Lifetime - Agenda + +Status: Working agenda (pre-spec) +Purpose: define the authoritative PBS memory, ownership, and lifetime model for v1 + +## 1. Context + +PBS no longer exposes the old RC/HIP syntax as active core language, but the language still needs a precise memory story. +That story must explain: + +- what values live on the VM heap, +- what identity and aliasing mean, +- how baseline GC interacts with deterministic execution, +- where host-owned memory begins and ends, +- how allocation and copy costs become visible to advanced users. + +Without this agenda, the future `Memory and Lifetime Specification.md` would not have a stable scope. + +## 2. Decisions to Produce + +This agenda must end with decisions for: + +1. The value-category map: stack-like transient values, heap-backed values, callbacks, collections, and host-backed handles. +2. The lifetime and reachability model under baseline GC. +3. The VM heap vs host-memory boundary and the user-visible rules at that boundary. +4. The minimum cost/allocation visibility contract needed by diagnostics and profiling. +5. The migration and reservation policy for legacy RC/HIP concepts. + +## 3. Core Questions + +### Q1. Heap residency by value category + +- Which core values are heap-backed in v1: structs, callbacks, collections, tuples, `optional`, `result`, or only some of them? +- When a value is assigned, passed, or returned, what is copied versus what aliases the same heap identity? + +### Q2. Identity and aliasing + +- Which user-visible value kinds have stable identity? +- Are struct values always reference-like at runtime even when their fields are small and copyable? +- How should aliasing be described for beginner-facing semantics without hiding performance consequences? + +### Q3. Baseline GC contract + +- Which GC properties are normative: reachability, eventual reclamation, safepoints, no user finalizers? +- Which GC timing details remain non-normative implementation choices? +- Can user code observe reclamation directly, or only via indirect performance/diagnostic signals? + +### Q4. Host memory boundary + +- How are host-backed resources represented in PBS user space: opaque handles, nominal structs, services, or reserved host-bound values? +- Can host memory outlive PBS references, and if yes, what runtime contract prevents unsoundness? +- Is pinning, borrowing, or zero-copy transfer exposed in v1 at all? + +### Q5. Allocation visibility + +- Which operations are allowed to allocate on the VM heap? +- Which host calls may allocate host memory or retain VM-reachable references? +- What must tooling report as allocation, retention, copy, or escape risk? + +### Q6. Lifetime-related traps and safety + +- Which memory problems are impossible by construction in v1 core? +- Which remaining failures become traps, capability rejection, or host-defined status outcomes? + +### Q7. Future explicit control + +- Should pools, arenas, object reuse, or weak-reference patterns exist only as stdlib/tooling surfaces? +- What criteria must be met before reserved keywords like `alloc`, `borrow`, `take`, or `weak` can become active in a future profile? + +## 4. Expected Spec Material + +After discussion, this agenda should directly feed sections of `Memory and Lifetime Specification.md` covering: + +1. runtime memory spaces, +2. value representation classes, +3. identity, aliasing, and copy rules, +4. GC and safepoint guarantees, +5. host-memory boundary rules, +6. cost visibility hooks for `Diagnostics Specification.md`. + +## 5. Non-Goals + +- Defining exact GC algorithm internals. +- Designing complete stdlib pool/arena APIs. +- Reintroducing mandatory user-authored lifetime syntax in core v1. + +## 6. Inputs + +- `1. Language Charter.md` +- `3. Core Syntax Specification.md` +- `4. Static Semantics Specification.md` +- `Heap Model - Agenda.md` +- `Dynamic Semantics - Execution Model Agenda.md` +- `Dynamic Semantics - Effect Surfaces Agenda.md` diff --git a/docs/specs/pbs/6. Host ABI Binding and Loader Resolution Specification.md b/docs/specs/pbs/6. Host ABI Binding and Loader Resolution Specification.md index 4e910877..5fce7588 100644 --- a/docs/specs/pbs/6. Host ABI Binding and Loader Resolution Specification.md +++ b/docs/specs/pbs/6. Host ABI Binding and Loader Resolution Specification.md @@ -1,6 +1,6 @@ # Host ABI Binding and Loader Resolution Specification -Status: Draft v1 (Temporary) +Status: Draft v1 Applies to: PBX host-binding metadata, cartridge load, canonical syscall resolution, and loader-side capability gating ## 1. Purpose diff --git a/docs/specs/pbs/Heap Model - Discussion Agenda.md b/docs/specs/pbs/Heap Model - Discussion Agenda.md deleted file mode 100644 index 3eb0a2e2..00000000 --- a/docs/specs/pbs/Heap Model - Discussion Agenda.md +++ /dev/null @@ -1,90 +0,0 @@ -# PBS Heap Model - Discussion Agenda - -Status: Working agenda (pre-spec) -Purpose: define how PBS will expose heap usage after the RC/HIP era - -## 1. Context - -Legacy PBS experiments used explicit RC/HIP syntax (`alloc`, `borrow`, `mutate`, `peek`, `take`, `weak`). -Current runtime authority is GC-based with deterministic safepoints. - -We need a clear PBS heap story that: - -- stays compatible with closed VM/runtime authority, -- remains simple for beginners, -- gives advanced developers explicit performance control, -- keeps frame-time behavior predictable. - -## 2. Decisions to Produce - -This agenda must end with decisions for: - -1. Heap surface in core language (what is in/out of core syntax). -2. Heap control surface in stdlib/tooling (what is explicit but optional). -3. Cost visibility contract (what diagnostics/profiling must report). -4. Migration policy from legacy RC/HIP concepts. - -## 3. Core Questions - -### Q1. Baseline model - -- Is GC always the default execution model for PBS core? (expected: yes) -- Are there any mandatory explicit lifetime constructs in core syntax? (expected: no) - -### Q2. Language vs library boundary - -- Should explicit memory workflows live in syntax or only in stdlib APIs? -- Which old RC/HIP concepts become API patterns instead of keywords? - -### Q3. Reserved keywords strategy - -- Keep `alloc/borrow/mutate/peek/take/weak` reserved only? -- Or activate a subset in a future opt-in profile? -- What hard criteria must be met before activation? - -### Q4. Determinism and frame budget - -- How do we guarantee predictable frame behavior under GC pressure? -- What static/dynamic tooling must warn on hot-path allocations? - -### Q5. Heap collections and identity semantics - -- What collection semantics are required in v1 stdlib for games? -- Which operations must be explicit due to allocation/copy costs? - -### Q6. Host memory boundary - -- How does PBS communicate "VM heap vs host-owned memory" to users? -- Which host calls may allocate, and how should that appear in diagnostics? - -### Q7. Advanced performance patterns - -- Should pools/reuse patterns be standardized as library primitives? -- If yes, what minimum API contract is required (without changing VM model)? - -### Q8. Error and safety model - -- Which heap-related failures become traps vs status values? -- What compile-time checks are mandatory for safer defaults? - -## 4. Proposed Output Documents - -After discussion, produce: - -1. `4. Static Semantics Specification.md` (binding/mutability/type rules impacted by heap model). -2. `5. Dynamic Semantics Specification.md` (evaluation and runtime-visible behavior). -3. `6. Memory and Lifetime Specification.md` (authoritative PBS heap model). -4. `9. Diagnostics Specification.md` (heap/cost diagnostics contract). - -## 5. Non-Goals for This Agenda - -- Defining new VM opcodes. -- Reintroducing RC as mandatory runtime strategy. -- Designing full stdlib APIs in this discussion pass. - -## 6. Working Assumptions (to validate) - -1. GC remains baseline for PBS core. -2. Explicit heap control is opt-in and likely library/tooling-driven. -3. Deterministic behavior and frame-sync constraints are non-negotiable. -4. Language should expose cost signals without forcing expert-only syntax. diff --git a/docs/specs/pbs/TODO.md b/docs/specs/pbs/TODO.md index cc90f170..5d2bee40 100644 --- a/docs/specs/pbs/TODO.md +++ b/docs/specs/pbs/TODO.md @@ -45,15 +45,17 @@ Purpose: checklist curto para decidir se a spec da PBS pode ser aprovada para se ## Pautas Dedicadas -- [ ] Abrir pauta dedicada para dynamic semantics + memory and lifetime. +- [X] Abrir pauta dedicada para dynamic semantics + memory and lifetime. + Resolvido com uma pauta guarda-chuva de heap model e tres pautas filhas separando: modelo de execucao, superfices de efeito/controle e memory/lifetime. + Isso reduz o acoplamento da discussao e permite fechar semantica observavel antes de fixar as regras normativas de heap e lifetime. Objetivo: fechar o modelo de execucao observavel, ordem de avaliacao, traps, efeitos sobre `optional`/`result`/`apply`/`bind`/`switch`, baseline GC, fronteira heap VM vs memoria do host e visibilidade de custo/alocacao. Resultado esperado: material para futura `Dynamic Semantics Specification` e `Memory and Lifetime Specification`. - Referencia: `Heap Model - Discussion Agenda.md`. + Referencias: `Heap Model - Agenda.md`, `Dynamic Semantics - Execution Model Agenda.md`, `Dynamic Semantics - Effect Surfaces Agenda.md`, `Memory and Lifetime - Agenda.md`. -- [ ] Abrir pauta dedicada para validar se a `Host ABI Binding and Loader Resolution Specification` atual ja satisfaz o gate da fase seguinte ou se ainda precisa deixar de ser "Temporary". - Objetivo: confirmar se o contrato atual de `declare host` -> metadata PBX -> loader -> syscall numerico ja esta suficientemente estavel para nao bloquear a etapa posterior. - Resultado esperado: decisao explicita de "suficiente para a proxima fase" ou lista curta de endurecimentos pendentes. - Referencia: `6. Host ABI Binding and Loader Resolution Specification.md`. +- [X] Abrir pauta dedicada para validar se a `Host ABI Binding and Loader Resolution Specification` atual ja satisfaz o gate da fase seguinte ou se ainda precisa deixar de ser "Temporary". + Decisao: suficiente para a proxima fase. O contrato atual de `declare host` -> metadata PBX -> loader -> syscall numerico ja esta estavel o bastante para nao bloquear a etapa posterior. + Os pontos ainda abertos sao endurecimentos de formato/integracao, nao lacunas do contrato semantico principal. + Referencias: `Host ABI Gate Validation Agenda.md`, `6. Host ABI Binding and Loader Resolution Specification.md`. - [ ] FUTURO: abrir pauta de backend. Objetivo: tratar IR/lowering, linker, host integration, runtime behavior final e conformance somente depois de fechar o frontend e aparar as arestas da linguagem/spec.