add discussion agendas

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<E>`,
+- `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<E>`.
+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<E>`
+
+- 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`

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`

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.

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 <sysc_index>` before load, `SYSCALL <id>` 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`

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`

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

docs/specs/pbs/Heap Model - Discussion Agenda.md

@@ -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.

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".
+- [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".
-  Objetivo: confirmar se o contrato atual de `declare host` -> metadata PBX -> loader -> syscall numerico ja esta suficientemente estavel para nao bloquear a etapa posterior.
+  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.
-  Resultado esperado: decisao explicita de "suficiente para a proxima fase" ou lista curta de endurecimentos pendentes.
+  Os pontos ainda abertos sao endurecimentos de formato/integracao, nao lacunas do contrato semantico principal.
-  Referencia: `6. Host ABI Binding and Loader Resolution Specification.md`.
+  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.