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