Memory management / Runtime and backend memory lowering

Different targets and profiles may receive different allocation and GC representations. The compiler-owned memory planner selects them per physical variant, and no backend chooses different language semantics.

Runtime and backend memory lowering

Design contract

Different targets and profiles may receive different allocation, region, counted, handle and ownership representations. The compiler-owned memory planner selects them per physical variant, backend lowering encodes the result, and no target may receive different language semantics.

Every backend must preserve shared read-only access, exclusive mutation, explicit copy behaviour, affine transfer safety, lifetime-topology legality, reactive liveness and identical observable results.

Collector-free release guarantee. Backends declare whether they support collector-free release lowering. A backend that advertises full memory control must lower every accepted topology in a release build without a tracing or reachability collector, and must not silently fall back to one. There is no source-visible or project-visible no-GC mode: this is a backend capability, not a language mode.

GC is a permitted runtime representation for a statically legal lifetime topology on debug profiles and GC-native backends. It is not a mechanism for accepting invalid retained edges, lateral lifetime promotion, unowned escapes or cross-region cycles.

Main backend paths

• src/backends/js/
• src/backends/wasm/
• src/backends/wasm/hir_to_lir/ownership.rs
• src/backends/wasm/lir/
• src/backends/wasm/runtime/

Backend-neutral semantics

• Borrow validation and lifetime-region validation precede target lowering.
• Invalid source access or topology is rejected before backend codegen.
• Backend doesn't infer access or topology from source syntax.
• Backend consumes HIR plus borrow facts and validated lifetime facts as validation context and assertion material only.
• ValidatedMemoryPlan is the single final physical authority for ownership decisions and count transitions. Backend consumes it rather than rediscovering or selecting strategy.
• Backend representation can't affect copy, alias or ~ semantics.
• Imprecise planning results in conservative retention, never in rejecting legal source.
• Missing topology proof is not a backend fallback.
• A missing physical strategy after successful topology validation is CompilerError.

Planning order

Physical memory strategy is chosen after target assignment, not before it.

validated HIR
    -> borrow and last-use analysis
    -> local allocation-family and retained-edge constraints
    -> exported lifetime and retention summaries
    -> project/package summary instantiation
    -> complete backend-neutral lifetime-topology validation
    -> non-lexical interval, frontier and epoch completion
    -> backend-neutral memory requirements
    -> target-affinity analysis and partition
    -> target-contract validation
    -> per-physical-variant family/layout refinement
    -> revalidate affected refined family-edge facts
    -> target/profile-aware compiler-owned memory planning
    -> ValidatedMemoryPlan
    -> backend lowering
    -> collector-free artefact verification where required

check runs through creation and validation of the ValidatedMemoryPlan. It stops before backend lowering and output emission.

Final physical ownership decisions and count transitions come only from the ValidatedMemoryPlan. Lowering starts after that plan has been validated.

• A ValidatedMemoryPlan is scoped to one target/profile physical variant, never to the whole project.
• Host GC versus affine, inferred-region, declared-region or REC representation is chosen by the compiler-owned planner, and only after target and build-profile information exists.
• Lowerers receive the already selected plan for their variant.
• Lowerers do not choose REC, GC, inferred-region or declared-region representation, and do not reconsider the plan.
• A missing physical strategy after successful planning is CompilerError.
• GC-native and collector-free variants share the same mandatory topology result. They differ only in the physical plan built on top of it.

ValidatedMemoryPlan contract

A ValidatedMemoryPlan belongs to one target/profile physical-variant scope. It is not:

• one plan per source module
• one project-global physical plan
• part of the canonical semantic module artefact
• a backend-owned strategy choice

Its conceptual contents are:

ValidatedMemoryPlan
    physical variant identity and capability inputs
    post-refinement allocation-family graph
    one selected physical family plan for every reachable family
    region plans and complete exits
    declared-region plans and complete exits
    planned affine-responsibility transitions
    planned retained-edge obligation transitions
    hidden-destination plans
    cleanup plans
    destruction plans
    REC layout and counter decisions
    physical coalescing decisions
    normalised memory-plan identity inputs

The accepted family strategy outcomes are:

Stack
Inline
Affine
InferredRegion
DeclaredRegion
REC
HostGC

Exact Rust enum decomposition remains open. Stack or inline placement may be separate from heap cleanup strategy. No accepted outcome may be omitted from the conceptual contract.

Before publication, plan validation proves:

1. Every reachable post-refinement family has exactly one selected physical plan.
2. Every plan family belongs to this physical-variant scope.
3. Every retained-edge transition refers to valid direct post-refinement families.
4. Every family preserves its one validated semantic lifetime owner.
5. Every affine obligation reaches a planned discharge or safe transfer on every relevant path.
6. Every inferred region has complete exits.
7. Every declared region has complete bulk exits.
8. Declared-region-owned families are never individually releasable and never REC-selected.
9. Every REC family is acyclic and has a valid counter layout.
10. Every REC family keeps its validated fallback region.
11. Every destruction plan processes outgoing obligations exactly once.
12. Every projection representation preserves or recovers the allocation-family base.
13. Every hidden destination satisfies its validated destination and retained-edge constraints.
14. Every physical coalescing decision preserves the original semantic topology.
15. HostGC is rejected for a capable full-control release variant.
16. Normalised plan identity is deterministic for identical inputs.

Physical coalescing occurs before final plan validation and fingerprinting. It may retain storage slightly longer, but it never widens semantic topology, changes outlives, changes source legality or changes diagnostics.

Physical memory strategies

The memory planner selects one strategy per validated allocation family. Backends realise the plan; they do not choose semantics.

• stack or inline placement
• static affine cleanup at a proven final use
• inferred region allocation with a complete exit, including region epochs
• declared-region bulk reclamation
• Retained Edge Counting for unresolved runtime-many persistent edges
• host garbage-collected representation on debug profiles and GC-native backends

Arenas, handles, slabs, pools, grouped drop lists and hybrid representations are permitted for valid topology. Source-visible RC, weak references, finalizers and hidden unrestricted dynamic sharing are not.

Semantic intervals and physical coalescing

Semantic lifetime analysis chooses the narrowest proven useful interval for each allocation family. Physical memory planning may choose a slightly wider storage interval to reduce allocation and cleanup overhead, but that choice stays below the semantic proof.

Physical coalescing never widens semantic topology. It never changes an outlives relationship, makes an illegal retained edge legal or changes diagnostics. A coalesced arena or grouped drop may keep storage available longer than the semantic interval while preserving the same validated lifetime facts.

Garbage-collected representation

Where garbage collection is used, it represents an already-legal topology:

• Deterministic destruction is not required for observable correctness.
• Mandatory access and lifetime validation still run.
• Affine cleanup operations may be erased.
• discharge_if_owned may be a no-op.
• Handle tags may be erased when the host owns storage.

The representation can use host garbage collection, Wasm GC or a runtime tracing collector. Exact current target support belongs in the progress matrix.

Profiles and backend capability

Profiles differ only in analysis effort and physical representation, never in source legality.

• Debug and development profiles may deliberately use a garbage-collected representation even where collector-free lowering is available, because debuggability, instrumentation, faster compilation and predictable runtime behaviour take priority.
• GC-native backends may use their host collector on any profile.
• A capable full-control backend in a release build must be collector-free. It may not fall back per value when precision is unavailable; it retains conservatively under the owning region instead.
• Debug, GC-native and collector-free paths preserve identical observable Moth behaviour and identical source legality.

A project builder may verify after reachability and memory planning that a physical artefact contains no tracing runtime. That is an artefact property reported by the build, not a source mode or a project-wide language contract.

Build-owned target and lifecycle planning

The build system owns reachability, target partition, page/request/mount/frame roots and page runtime topology. Backends consume explicit plans rather than selecting them.

See docs/build-system-design.md for project and link orchestration.

Moth-linked page memory and imported components

Each page may own one runtime and memory shared by its linked Moth Wasm variants. Imported WIT components are separate runtimes with component-private memory and communicate only through the closed value boundary. This is build architecture, not source memory semantics. The one-page/one-memory rule applies to Moth-linked Wasm variants, not arbitrary imported components. Imported components are not members of Moth page memory or the Moth lifetime graph and do not need to declare a GC strategy to Moth.

WIT value-only V1 profile

Moth imports general external Wasm libraries as WIT-described Wasm Components. The V1 component boundary is value-only. Every supported argument is lowered from a shared read of a Moth value into an independent component value, and every result is lifted into an independent Moth result graph. No Moth alias, lifetime owner, ownership state, or destruction responsibility crosses the component boundary.

The component may use any private allocation or garbage-collection strategy. That strategy is not part of the Moth binding contract and does not require a GC declaration.

Fixed facts

| Fact | WIT value-only V1 | |---|---| | Parameter source access | Shared read | | Boundary crossing | Independent semantic value | | Retained Moth reference | Never | | Result provenance | Independent result graph | | Result aliases an argument | Never | | Source call consumes argument | Never | | Destruction responsibility crosses | Never | | External lifetime owner | Component-private | | Cross-runtime allocation cycle | Impossible by contract |

Supported V1 WIT value families

• primitives
• strings
• records whose members are supported values
• variants whose payloads are supported values
• options of supported values
• recursively supported lists

Rejected V1 WIT surfaces

• WIT resources
• borrowed or owned resource handles
• resource constructors or methods
• callbacks into Moth
• retained closures or executable state
• async functions
• futures
• streams
• shared-memory views
• raw pointers or pointer/length escape hatches
• returned aliases
• retained Moth references
• project-authored Moth functions imported by the component

Unsupported interfaces must receive structured import diagnostics identifying:

• unsupported WIT feature
• function
• parameter or result
• why it cannot cross the value-only boundary
• whether a wrapper component could expose a supported value-only interface

Required importer metadata

The importer requires:

• stable package identity
• stable world identity
• stable interface identity
• stable function identity
• Moth-facing parameter and result types
• corresponding WIT value types
• component export identity
• trap or failure behavior
• required component imports
• target and runtime capability requirements

The boundary classification generates the fixed memory facts. The importer must not infer them from a generic Fresh result marker, and binding authors must not restate them per function. No uses_gc field is required.

Restricted host-binding profile

Existing Core, Builder, JavaScript-provider and curated platform bindings use a restricted host-binding profile.

• Ordinary Moth values cross by value as non-retained inputs.
• Host code cannot retain references into ordinary Moth storage.
• Mutable host access is supported only for opaque foreign handles.
• A mutable opaque-handle argument controls legal access to the foreign identity; it is not direct mutation of Moth storage.
• Ordinary Moth values are not passed by mutable reference to host code.
• Host operations that conceptually modify ordinary Moth data return a fresh or independent result instead of mutating Moth storage through copy-in/copy-out.
• V1 does not define copy-in/copy-out writeback semantics.
• Opaque handles represent foreign identities, not Moth reference types.
• Observable external resources require explicit close or teardown operations.
• Host finalization timing cannot define observable Moth behavior.

Restricted host-binding V1 permits mutable access only to opaque foreign handles. Ordinary Moth values cross by value as non-retained inputs. A host operation that conceptually changes ordinary Moth data returns a fresh or independent result instead of mutating Moth storage through the boundary.

Deferred resource-capable profiles

A future resource-capable profile requires a separate complete design for identity, transfer, teardown, callbacks, async suspension, reentrancy, cycles and failures. It is not part of V1.

JavaScript lowering

• Host references realise validated aliases.
• JS does not weaken topology.
• Explicit copy remains graph-independent semantically even if current implementation lags.
• Ownership-specific advisory facts may be ignored.
• JS host behaviour must not silently mutate shared aliases or duplicate values contrary to Moth semantics.
• Reactive mounts follow builder lifecycle roots and stay alive through runtime reachability.

Wasm lowering

• Borrow and lifetime facts precede LIR.
• Bit 0 of a family handle is affine cleanup responsibility only.
• Bit 1 identifies REC representation; declared region and region representation are separate memory-plan metadata.
• Imprecise planning keeps storage conservatively under the owning region; it does not reintroduce a collector in a capable release build.
• Missing topology proof is not a backend fallback.
• Ownership-aware heap values use allocation-family handles carrying the two tag bits.
• A projection must retain or recover the family base rather than masking an arbitrary interior pointer.
• The ValidatedMemoryPlan supplies each family's planned persistent-edge obligation transitions, including created and removed edges, affine-root reclassification and transition fusion. Wasm encodes those transitions at their planned semantic commit points.
• Wasm lowering does not independently derive physical count transitions. It must not emit a temporary decrement-to-zero followed by an increment for a same-family replacement whose planned net transition is zero.
• discharge_if_owned satisfies planned affine cleanup obligations. It destroys a family only where the plan says individual destruction is legal and no other obligation remains.
• Runtime helpers own allocation, discharge, destruction, string, collection and handle contracts.
• The unified ownership ABI applies across ownership-aware calls.
• Source semantics remain backend independent.

Current implementation debt

src/backends/wasm/hir_to_lir/ownership.rs is the ownership projection seam, and Wasm LIR includes conditional DropIfOwned plus reserved retained-edge transition support. The current direct path from borrow-checker advisory drop sites to DropIfOwned remains scaffolding: final lowering must consume a validated memory plan and support affine, inferred-region, declared-region and REC strategies. Treat the present implementation as migration debt, not as the accepted architecture.

Runtime ownership metadata

• two tag bits on allocation-family handles: affine responsibility and REC representation
• borrowed versus owned state
• mask and extract value representation
• callee responsibility
• propagation of ownership metadata through calls
• no source-visible owned/borrowed overload
• scalar values need not use tagged handles
• representation details can evolve while preserving the accepted contract

Planned discharge and retained-edge transitions

• transfer moves affine cleanup responsibility to another path.
• discharge satisfies one affine cleanup obligation.
• destroy physically destroys one allocation family.
• bulk reclaim ends a region or declared region.
• discharge_if_owned is the only conceptual permanent name for the conditional operation.
• It never discharges borrowed values.
• The plan supplies each family's discharge sites and its normalised per-family obligation transitions. The backend encodes them.
• A discharge does not always destroy:
  • For an uncounted individually releasable family, discharge may destroy immediately.
  • For an REC family, discharge removes the affine-root obligation. Destroy occurs only when the total count reaches zero.
  • For an inferred-region family, the individual handle does not own region reclamation.
  • For a declared-region family, no individual discharge destroys declared-region-owned storage. Declared-region exit bulk-reclaims it.
• Garbage-collected lowering can erase ownership-specific operations.
• REC may be used only for already-legal topology, and only where the planner selected it.
• Counted destruction is iterative through a worklist, never recursive through the target stack.

Fact consumption

Borrow facts and validated lifetime topology are validation context and assertion material only. They do not supply final physical ownership, cleanup or count decisions.

Backends may consume:

• value access classifications and call effects
• complete result provenance, including detached stored results, retention, outcome-sensitive effects and outlives summaries
• optional affine-transfer candidates, ownership constraints and candidate cleanup sites
• ValidatedMemoryPlan as the single final physical authority, including allocation-family layout, selected representation, cleanup plans, destruction plans, REC decisions and physical coalescing decisions
• validated lifetime topology and allocation-family facts
• builder lifecycle roots
• region/exit information
• reactive invalidation and liveness metadata
• external boundary classifications

Advisory drop sites never form final backend input. The current Wasm path that consumes them remains explicitly labelled implementation debt above.

Backends must not:

• mutate those facts
• reinterpret source syntax
• invent new move points that invalidate borrow or lifetime validation
• treat missing facts as proof of ownership or topology legality
• reconsider source legality

Reactive and mounted-fragment liveness

Live reactive subscriptions and mounted fragments can keep state observable. Ownership-aware lowering must not free a source or template instance while its builder lifecycle or reactive subscription keeps it observable. A GC representation may realise those already-proven lifecycle and observability facts with reachability, but reachability does not define the semantic lifetime. Finer invalidation granularity may improve performance but not lifetime semantics. Runtime fragment and reactive mount behaviour remain separate concerns.

Backend specialisation

Allowed optimisations include:

• ownership-effect specialisation
• discharge-check elimination
• local tag-test elimination where ownership or representation state is statically known
• region allocation
• stack or arena allocation
• collector-free release lowering and artefact verification
• realisation of planned physical coalescing
• base-pointer mask hoisting as an encoding optimisation
• devirtualized runtime helpers
• target-specific handle representation

Transition fusion stays plan-owned and is not a backend optimisation. Backends may only encode the transitions after plan validation.

Requirements:

• same source behaviour
• same validation result
• no unchecked aliasing
• no source-visible lifetime or ownership surface
• conservative retention under the owning region when precision is unavailable

Imprecision requirements

When a backend can't place precise individual cleanup for a value, the allocation remains under its inferred or declared region owner and is reclaimed at that owner's validated exit.

Conservative retention is valid. Semantic divergence isn't. In a capable full-control release build, imprecision must not reintroduce a tracing collector, and unknown external retention is never a collector fallback. A missing physical strategy after successful topology validation is CompilerError.

What backends must not do

• Skip borrow validation or lifetime-region validation.
• Accept aliasing or topology rejected by other backends.
• Reinterpret ~ as an unconditional move.
• Silently copy shared values.
• Destroy borrowed data.
• Expose source lifetimes.
• Rediscover source dependencies or access syntax.
• Require deterministic destruction for observable correctness.
• Fall back to a tracing collector in a capable full-control release build.
• Upgrade an uncounted allocation to REC at runtime.
• Make reactive observability depend on target-specific early release.
• Assume page memory includes arbitrary imported components.
• Invent a numbered Stage 7 for backend lowering.

Common mistakes

• Treating the JS path as semantically weaker because it uses GC.
• Treating GC as permission for invalid topology.
• Presenting current Wasm scaffolding as the whole accepted memory architecture.
• Treating every runtime value as a tagged heap pointer.
• Lowering advisory drops without checking ownership.
• Freeing reactive state too early.
• Treating imprecise cleanup placement as an error.
• Treating missing topology proof as backend GC fallback.
• Presenting collector-free release as a source-visible or project-visible mode.
• Creating separate borrowed/owned language APIs.
• Assuming imported components share Moth page memory.

Related reading

• Memory management: core contract
• Affine ownership and drops: unified two-bit ABI and destruction
• Retained Edge Counting: counted layout, transitions and iterative destruction
• Borrow validation: analysis facts
• Lifetime regions and escape validation: topology legality
• Declared regions: declared lifetimes, placement, exits and declared-region crossing restrictions
• Compiler design overview
• Build-system design