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/compiler/pbs/learn/03. Runtime Values, Identity, and Memory Boundaries.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.