Files
prometeu-studio/docs/specs/compiler-languages/pbs/10. Memory and Lifetime Specification.md
T
bquarkz bf31184d4d feat(pbs): add sprite animation and shared Studio authoring
Implement DEC-0084 with factory-only Sprite/Animator structs, complete result
lowering, validated animation sidecars, generated PBS factories and JavaFX/MCP
authoring through shared services.

Qualify native dev/release with ordinary and optimized producers, zero-allocation
playback, private-cycle reclamation, canonical Composer pixels, installed JARs
and JavaFX lifecycle. Preserve the runtime checkout and existing host ABI.
2026-11-05 15:16:07 +00:00

13 KiB

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; mirror and provenance policy)
  2. Bytecode authority (provider Core ISA)
  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.

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 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 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.

Animation ownership and allocation

Every AnimatorBuilder.build materializes independent private clips, frames and backing. Immutable strings retain normal sharing; assignment retains ordinary identity/aliasing. Final frame links may form private cycles and must remain rooted/reclaimable under existing GC. After construction, executed advance and sprite paths allocate no heap objects, including negative/overflow error returns.

See Core Sprite and Animation for the complete API, ranges, state table and conformance obligations.