prometeu-studio/docs/agendas/Heap Model - Agenda.md

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.