# 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 ([provider specifications](../../../../../runtime/docs/specs/runtime/README.md); [mirror and provenance policy](../../../vm-arch/README.md)) 2. Bytecode authority ([provider Core ISA](../../../../../runtime/docs/vm-arch/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: - `discussion/lessons/DSC-0007-pbs-learn-to-discussion-lessons-migration/LSN-0020-pbs-runtime-values-identity-memory-boundaries-legacy.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. - PBS uses the existing synthetic frame lifecycle. Runtime GC opportunities, including successful root return, follow the runtime contract; there is no PBS sync statement. - 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 Function values and closures Closures are ordinary managed objects retaining their typed captures. Reachable closures may survive across frames; unreachable closures are eligible for GC. Their invocations do not suspend across frames. See [First-class functions and explicit value captures](15.%20First-Class%20Functions%20and%20Captures%20Specification.md). ## 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 closure 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 PBS uses the existing synthetic frame lifecycle. Runtime GC opportunities, including successful root return, follow the runtime contract; there is no PBS sync statement. No user-visible program rule may depend on another safepoint existing. GC timing remains a runtime concern and introduces no user callback or observable scheduling operation. ### 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 Explicit capture storage Closure creation retains the values named in its explicit capture list, including shared object identities. Lifetime follows ordinary reachability and runtime resource limits. Captured bindings cannot be reassigned. ### 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. ## Typed arrays and optional execution extension The [Array owner chapter](14.%20Typed%20Arrays%20and%20Optional%20Execution%20Specification.md) defines the complete type, optional-flow and storage contract. This chapter supplies shared reachability and ownership rules; Array storage and complete-group packing are defined by that owner.