# PBS Memory and Lifetime Specification

Status: Draft v0 (Skeleton)  
Applies to: runtime memory spaces, value representation classes, identity, aliasing, GC baseline, and host-memory boundaries in PBS core

## 1. Purpose

This document will define the authoritative PBS memory and lifetime model for v1.

Its purpose is to make the language's runtime storage model explicit enough that:

- implementations agree on which values are heap-backed,
- identity and aliasing are not left implicit,
- GC remains compatible with deterministic execution,
- the VM heap and host-owned memory boundary stay understandable,
- tooling can surface runtime-visible memory and allocation costs consistently.

## 2. Scope

This document is intended to define:

- runtime memory spaces relevant to PBS user semantics,
- value categories and their representation classes,
- identity, aliasing, and copy behavior,
- baseline GC guarantees and non-guarantees,
- host-memory boundary rules,
- memory-related safety invariants and remaining runtime failure boundaries,
- hooks that later diagnostics and tooling may rely on for cost reporting.

This document does not define:

- exact GC algorithm internals,
- general-purpose allocator APIs,
- future explicit lifetime syntax activation,
- final IR lowering details,
- subsystem-specific host resource APIs.

## 3. Authority and Precedence

Normative precedence:

1. Runtime authority (`docs/specs/hardware/topics/chapter-2.md`, `chapter-3.md`, `chapter-9.md`, `chapter-12.md`, `chapter-16.md`)
2. Bytecode authority (`docs/specs/bytecode/ISA_CORE.md`)
3. `1. Language Charter.md`
4. `3. Core Syntax Specification.md`
5. `4. Static Semantics Specification.md`
6. `9. Dynamic Semantics Specification.md`
7. This document

If a rule here conflicts with higher authority, it is invalid.

## 4. Normative Inputs

This document depends on, at minimum:

- `1. Language Charter.md`
- `3. Core Syntax Specification.md`
- `4. Static Semantics Specification.md`
- `9. Dynamic Semantics Specification.md`

This document is expected to be closed using decisions from:

- `docs/agendas/Heap Model - Agenda.md`
- `docs/agendas/Memory and Lifetime - Agenda.md`
- `docs/agendas/Dynamic Semantics - Execution Model Agenda.md`
- `docs/agendas/Dynamic Semantics - Effect Surfaces Agenda.md`

## 5. Already-Settled Inputs

The following inputs are already fixed elsewhere and must not be contradicted here:

- Struct values are heap-backed reference values in v1 core.
- Assigning a struct value copies the reference, not the underlying field storage.
- Service values are canonical module-owned singleton values in v1 core.
- Assigning a service value copies the same singleton identity and does not create a new instance.
- `declare const` values are compile-time constants rather than mutable runtime module storage.
- Advanced memory syntax such as `alloc`, `borrow`, `mutate`, `peek`, `take`, and `weak` is not active in PBS core v1.

## 6. Initial Section Targets

At minimum, the completed document should contain normative sections for:

1. runtime memory spaces,
2. value representation classes,
3. identity and aliasing,
4. copy and passing behavior,
5. GC guarantees and safepoint constraints,
6. host-memory boundary rules,
7. memory-related safety properties,
8. cost visibility hooks consumed by diagnostics/tooling.

## 7. A Ver

The following items remain to be closed in agenda discussion before this document can be considered complete.

### 7.1 `Memory and Lifetime - Agenda.md`

- Heap residency by value category beyond already-settled struct and service behavior.
- Which values have stable user-visible identity.
- Exact aliasing story for tuples, callbacks, collections, `optional`, and `result<E>`.
- Normative GC guarantees versus implementation-defined GC details.
- Representation and safety model of host-backed resources and handles.

### 7.2 `Heap Model - Agenda.md`

- Cross-cutting visibility of allocation, copy, retention, and host-boundary costs.
- Which memory facts are normative versus profiler-quality best effort.
- Migration policy and activation criteria for reserved lifetime keywords in future profiles.

### 7.3 `Dynamic Semantics - Execution Model Agenda.md` and `Dynamic Semantics - Effect Surfaces Agenda.md`

- Which constructs allocate or retain memory during ordinary execution.
- Which effect-bearing constructs may trap only because their subexpressions trap.
- Which safepoints are observable versus implementation detail.

## 8. Non-Goals

- Designing full pool, arena, or weak-reference libraries in this pass.
- Reintroducing mandatory user-authored lifetime syntax in core v1.
- Defining exact collector implementation strategy.
- Rewriting already-settled source syntax.

## 9. Exit Criteria

This document is ready to move beyond skeleton status only when:

1. every core value category has an explicit representation and aliasing story,
2. GC guarantees and non-guarantees are separated clearly,
3. the VM heap versus host-memory boundary is normatively described,
4. memory-related costs are specified well enough for diagnostics/tooling hooks,
5. the document no longer relies on unresolved `A Ver` items for ordinary v1 behavior.