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