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

# PBS Memory and Lifetime Specification

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

## 1. Purpose

This document defines 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 the current core value categories,
- 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 defines:

- 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 integrates the following accepted decisions:

- `docs/pbs/decisions/Value Representation and Identity Decision.md`
- `docs/pbs/decisions/GC and Reachability Decision.md`
- `docs/pbs/decisions/Host Memory Boundary Decision.md`
- `docs/pbs/decisions/Allocation and Cost Visibility Decision.md`
- `docs/pbs/decisions/Lifetime Control and Future Profiles Decision.md`

## 5. Already-Settled Inputs

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

- Struct values are reference-like and identity-bearing in v1 core.
- Service values are canonical module-owned singleton values in v1 core.
- `declare const` values are compile-time constants rather than mutable runtime module storage.
- `FRAME_SYNC` is the only normative safepoint in PBS v1.
- Core PBS v1 does not expose explicit lifetime-control syntax in ordinary user code.

## 6. Runtime Memory Spaces

PBS v1 distinguishes, at minimum:

1. VM-managed runtime storage used for GC-managed values and retained runtime state.
2. Stack-like transient value flow used for ordinary value exchange during evaluation.
3. Host-owned memory and resources that remain outside ordinary PBS userland memory semantics.

The VM heap and host-owned memory remain distinct in the user model.

Cross-boundary host/userland interaction is value-based rather than memory-sharing-based.

## 7. Value Representation Classes

### 7.1 Pure copied values

The following value kinds are pure copied values in the user model:

- `int`
- `float`
- `bool`
- enum values
- canonical `str`

Assignment, parameter passing, and return of these values copy the value itself.

### 7.2 Identity-bearing values

The following value kinds carry stable user-visible identity:

- struct values
- service values
- host-backed resource values on the PBS side

Assignment, parameter passing, and return of these values preserve aliasing to the same runtime entity rather than copying an independent underlying object.

### 7.3 Carrier-only values

The following value kinds are carriers and do not introduce identity of their own:

- tuples
- `optional`
- `result`

If a carrier contains an identity-bearing payload, the carrier transports that same payload identity rather than inventing a new one.

### 7.4 Contract values

Contract values do not introduce a new user-visible identity distinct from the underlying struct or service value.

They are runtime views over an underlying identity-bearing value together with the selected contract implementation used for dispatch.

### 7.5 Callback values

Callback values are first-class callable values in PBS v1.

They may be assigned, passed, and returned, but callback identity is not promoted as a separate user-visible identity concept.

When formed through `bind(context, fn_name)`, a callback value retains:

- the target function,
- and the same captured struct context identity without copying it.

## 8. Identity, Aliasing, and Copy Behavior

### 8.1 Structs

Struct values are always reference-like in PBS v1.

Rules:

- `new Struct(...)` produces a fresh struct identity.
- Assignment of a struct value copies the reference, not the underlying field storage.
- Passing or returning a struct value preserves aliasing to the same struct instance.
- Mutation through one alias is observable through other aliases to that same struct instance.

### 8.2 Services

Service values denote the same canonical singleton identity wherever used in the same resolved program.

Assignment, parameter passing, and return preserve that same singleton identity.

### 8.3 Carriers

`optional`, `result`, and tuples preserve the semantics of their contained values.

Examples:

- assigning an `optional<Player>` that contains `some(player)` preserves the same `Player` identity inside the carrier,
- assigning a `result<E> Player` success payload preserves the same `Player` identity inside the carrier.

### 8.4 General rule

The general rule for PBS v1 is:

- pure value kinds are copied by value,
- identity-bearing kinds preserve aliasing,
- carrier kinds preserve the semantics of their contained values and do not create identity of their own.

## 9. GC Baseline

### 9.1 Reachability

GC is the baseline runtime model for VM-owned memory in PBS core.

For GC-managed VM-owned values, liveness is defined by reachability from the runtime roots that matter to PBS semantics.

At minimum, those roots include:

- currently active local/frame state,
- reachable fields of reachable struct instances,
- service singleton roots,
- retained callback state that remains reachable,
- and any other runtime roots required to preserve already-observable PBS behavior.

If a GC-managed value remains reachable through the normative runtime state, the implementation must preserve its continued semantic availability.

### 9.2 Reclamation

PBS v1 guarantees eventual reclamation, not prompt reclamation.

The language does not promise:

- immediate reclamation,
- reclamation at a specific frame boundary,
- or a semantic event when reclamation occurs.

### 9.3 Safepoint relationship

`FRAME_SYNC` is the only normative safepoint in PBS v1.

No user-visible program rule may depend on another safepoint existing.

Implementations may perform internal GC work outside `FRAME_SYNC` only if doing so creates no additional user-visible semantic effects.

### 9.4 Observability

User code cannot observe reclamation directly.

PBS v1 provides no user-visible mechanism for:

- detecting that a value was collected,
- registering a callback on reclamation,
- forcing immediate collection,
- sequencing user code against collector timing.

PBS v1 defines no user-authored finalizers or destructor-like reclamation hooks.

## 10. Host Memory Boundary

The host/userland boundary in PBS v1 is value-based rather than memory-sharing-based.

Cross-boundary interaction between host and PBS userland is restricted to stack-only values.

PBS userland does not expose host memory as ordinary language values.

PBS v1 does not expose:

- raw host pointers,
- borrowed host-memory views,
- pinning,
- zero-copy transfer,
- shared heap objects spanning host memory and VM memory.

Long-lived host resources, if later exposed, must be specified by subsystem contract rather than inferred from a general host-memory-handle model in core PBS.

## 11. Cost Visibility Hooks

### 11.1 Normatively relevant cost facts

The normatively relevant cost facts in PBS v1 are:

- whether an operation may allocate VM-owned runtime storage,
- whether an operation retains state beyond the current evaluation,
- whether an operation copies payload versus preserves aliasing,
- whether an operation crosses the host boundary,
- whether an operation may trap.

### 11.2 `bind`

`bind(context, fn_name)` is retention-bearing and requires runtime storage sufficient to preserve:

- the callback target identity,
- the captured context,
- and the captured context's continued liveness while the callback value remains alive.

This document does not freeze the exact runtime layout used to implement that storage.

### 11.3 Non-allocation-bearing surfaces by themselves

The following constructs are not allocation-bearing by themselves in PBS v1:

- `optional`
- `result`
- `handle`
- `!`
- `if`
- `switch`
- `apply`

If allocation or retention occurs while evaluating one of these constructs, that cost arises from:

- subexpression evaluation,
- called targets,
- payload formation already defined elsewhere,
- or runtime behavior outside the surface itself.

### 11.4 Quantitative reporting

The language does not normatively guarantee:

- exact byte counts,
- exact object counts,
- exact collector timing,
- exact host-side allocation volume,
- precise performance ranking.

Those belong to diagnostics/profiling quality rather than to the core language contract.

## 12. Future Lifetime Control Policy

PBS v1 adopts the following policy:

- no dormant lifetime-control keyword is preserved merely for speculative future use,
- advanced memory workflows should default to library/tooling-first exploration,
- future explicit lifetime-oriented syntax, if introduced at all, must be profile-gated and justified by real need rather than by historical inertia.

Core PBS v1 does not promise future activation of legacy RC/HIP-style syntax.

## 13. Beginner-Facing Model

The user-facing explanation should be:

- some values are plain data, so passing them passes the value,
- structs and services are shared entities, so passing them passes access to the same entity,
- tuples, `optional`, and `result` only package values and do not become new entities by themselves,
- the runtime keeps reachable GC-managed values alive,
- the program does not directly hold or manipulate host memory.

## 14. TODO

The following items remain editorial or adjacent-spec integration tasks rather than open memory-model agenda questions:

- subsystem-specific wording for long-lived host resources if those are later introduced,
- diagnostics-specific wording for cost warnings and notes,
- future profile mechanics if an explicit lifetime profile is ever proposed.

## 15. 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 beyond what is required for consistency with accepted decisions.

## 16. Exit Criteria

This document is ready to move beyond temporary draft status only when:

1. every current core value category has explicit representation and aliasing wording,
2. GC guarantees and non-guarantees are separated clearly,
3. the VM heap versus host-memory boundary is normatively described,
4. memory-related cost facts are specified well enough for diagnostics/tooling hooks,
5. the remaining TODO items are reduced to editorial integration or future optional work rather than semantic uncertainty.