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

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.