prometeu-studio/docs/specs/pbs/10. Memory and Lifetime Specification.md

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.