# 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` that contains `some(player)` preserves the same `Player` identity inside the carrier, - assigning a `result 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.