Affine ownership and drops

Design contract

Moth ownership is a runtime cleanup discipline over statically validated topology. It isn't a separate source type system.

Cleanup responsibility is affine: it may move or be discharged, but it never duplicates. That single property is what makes deterministic cleanup safe without counting ordinary aliases.

Borrow and lifetime analysis prove transfer eligibility and topology legality. Ownership lowering only realises already-validated facts. The compiler-owned memory planner produces concrete responsibility and retained-edge obligation transitions plus cleanup and destruction plans. Backend lowering consumes the ValidatedMemoryPlan and encodes its planned transitions and cleanup decisions rather than reconstructing them from borrow-checker advisory cleanup sites.

The compiler may transfer cleanup responsibility only where static analysis proves that doing so can't invalidate a later source use. If that proof is unavailable, the operation remains a borrow and the allocation stays under its region owner.

Ownership is a runtime state, not a source type

Ownership metadata is separate from semantic TypeId.
Shared/mutable parameter syntax doesn't create owned/borrowed source types.
Cleanup responsibility never decides whether a program compiles.
A garbage-collected representation is permitted for a statically legal topology on debug profiles and GC-native backends.
Collector-free, GC-native and debug paths must preserve identical observable behaviour.

Bit 0: affine cleanup responsibility

Bit 0 of a full-control allocation-family handle records affine cleanup responsibility. It does not prove uniqueness, identify the final observer, establish lifetime legality or create dynamic shared ownership.

borrowed
    The runtime path must not destroy the value.

owned
    The runtime path carries cleanup or safe-transfer responsibility.

The two-bit logical handle

Cleanup responsibility and physical representation are independent dimensions of a full-control handle. Bit 0 is per-handle affine cleanup responsibility. Bit 1 describes the target allocation family's physical representation. Neither bit determines the other.

bit 0: affine cleanup responsibility
bit 1: REC representation

00: uncounted borrowed
01: uncounted affine-owned
10: REC-managed borrowed or counted persistent edge
11: REC-managed affine owner

The tags belong to an allocation-family handle, so a projection must retain or recover the family base. Scalars and target-native immediate values do not use this handle ABI, and GC-native backends may erase the tags while preserving the same semantic analysis.

Only retention-sensitive and cleanup-sensitive operations need to inspect bit 1. The compiler-owned memory planner decides REC selection, concrete obligation transitions and destruction plans. Backend lowering encodes those decisions. The retained-edge-counting page documents the REC representation contract.

Ownership responsibility versus lifetime ownership

Contrast these distinct concepts:

Lifetime owner: the one semantic region responsible for allocation lifetime, fixed statically
Static result provenance: where a result's storage came from and which outlives constraints apply
Cleanup-responsibility path: the runtime path that may perform individual cleanup, affine and movable
Shared aliases: observers that do not become additional lifetime owners
Inferred-region-owned or declared-region-owned allocation family: storage whose reclamation is owned by an inferred or declared region rather than an individual callee, recorded as static memory-plan metadata

Semantic lifetime ownership stays static even when cleanup responsibility moves at runtime. The bit does not imply individual releasability when the value belongs to an inferred-region-owned or declared-region-owned allocation family.

Discharging responsibility is not necessarily destruction

This section is the terminology authority for these four cleanup terms:

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

A discharged obligation is gone from this path. It does not by itself mean that the allocation family is destroyed. The selected physical strategy determines what happens after the obligation is discharged:

uncounted individually releasable family:
    discharge may destroy immediately

REC family:
    discharge removes the affine-root obligation
    destroy only when the total count reaches zero

inferred-region family:
    the individual handle does not own region reclamation

declared-region family:
    no individual discharge destroys declared-region-owned storage
    declared-region exit bulk-reclaims it

These terms are not synonyms.

Inferred transfer

Assignments and calls can be optional transfer points. Analysis proves eligibility. Lowering realises validated transfer facts. There is no move keyword.

No later use on every relevant path → transfer may occur.
Later use → operation remains a borrow.
Path-dependent or imprecise outcome → operation remains a borrow.
Failure to prove transfer must not reject the program.

When transfer is realised:

aliases can't remain usable after a possible transfer
a callee that receives ownership of an individually releasable family assumes eventual cleanup responsibility for it
responsibility may be discharged or transferred again at a further proven transfer point

Immutable and mutable parameters may both receive inferred cleanup responsibility at a proven final-use call site. Parameter mutability controls access; ownership metadata controls cleanup responsibility. An immutable parameter receiving ownership remains read-only. A mutable parameter receiving ownership may mutate according to the source contract.

Closed external boundary profiles override this general rule. WIT value-only calls are non-consuming. Restricted host-value crossings are non-consuming, and mutable opaque-handle access does not transfer Moth storage through the ordinary Moth ownership ABI.

Single ownership transfer

Ownership transfers at most once along a control-flow path.
A borrowed value is never discharged by the borrower.
An owned value from an individually releasable family must reach a valid discharge or transfer point. Inferred-region and declared-region-owned families stay under their region's bulk reclamation instead.
Joins conservatively account for paths that may own.

Declared-region-owned values

The declared region owns responsibility for bulk reclaim of its allocation family.
Ordinary calls normally borrow declared-region-owned storage.
An individual callee cannot discharge or destroy declared-region-owned storage merely because an owned bit exists.
Hidden destination allocation may produce a fresh result root directly in a declared region when every retained edge is legal for that destination.
Declared-region-owned values use bulk reclaim at declared-region exit rather than individual discharge.
Declared-region-owned allocations are count-free and never carry a REC representation.
Last-use analysis still checks access legality inside a declared region, but never shortens declared-region-owned physical lifetime.

Unified ownership ABI

Ownership-aware lowering uses one calling convention rather than separate source-visible borrowed and owned function variants. Because responsibility and representation are independent handle dimensions, one convention covers every combination of the two bits.

Heap-managed or handle-based values that participate in ownership lowering carry ownership metadata with the runtime value. Scalar values may continue to use target-native representations.

ABI behaviour:

Borrowed metadata → callee must not destroy the value.
Owned metadata → callee receives cleanup responsibility.
Callee must discharge or safely transfer that responsibility before it ends.
Caller must not use a value again after a path that may have transferred ownership.
Source function signatures do not distinguish borrowed and owned variants.
Local specialisation may remove known tag checks without introducing source-visible owned/borrowed function overloads.

The unified ABI keeps dispatch static without generating separate borrowed and owned function families. It limits ownership-driven monomorphisation and binary-size growth, especially for Wasm, while preserving the same semantic ABI when local specialisation removes a known check.

Conditions for discharge

An individual discharge is legal only when:

topology is already valid
no observable alias remains
responsibility is owned
the allocation family is individually releasable

When an owning inferred or declared region ends, bulk reclaim handles region-owned storage instead of individual discharge.

Conditional destruction

discharge_if_owned is the conceptual operation at a possible individual-cleanup point. It checks ownership metadata and, when responsibility is owned, discharges that affine obligation according to the concrete transitions in ValidatedMemoryPlan. A discharge may destroy an uncounted individually releasable family immediately. For an REC family it removes the affine-root obligation and destroys the family only when the total count reaches zero. Inferred-region and declared-region families remain under their owning region's reclamation rules.

The current Wasm scaffolding instruction is spelled DropIfOwned; this page names it only when describing migration debt to discharge_if_owned, not as a second conceptual operation.

It is a conditional responsibility check only.
It is not an alias count.
It is not a topology validator.
It is a no-op for borrowed state.
Under pure GC it can lower to no-op or be erased where allowed.
Inferred-region-owned values remain until their validated inferred-region exit. Declared-region-owned values remain until declared-region exit. Neither is individually destroyed merely because a runtime owned bit exists.
It is a planned conceptual operation, not source syntax.
Backend lowering encodes the planner's transition and cleanup decisions. It does not select a strategy or reconstruct ownership or count transitions.

Control-flow exits

Possible cleanup points include:

normal region or scope exits
function returns
error returns
loop break and other reachable loop-exit paths
branch edges that leave an owning region
region/declared-region exits for bulk reclaim
return values that transfer responsibility out

A non-exiting loop needs no cleanup point. A loop that can exit must account for ownership on each reachable break, return, error-return or region-exit path.

A control-flow join determines whether a later exit may own. The join itself is not a cleanup point and is not automatically a discharge site.

Deterministic cleanup is enabled where analysis supports it. Where individual discharge cannot be placed, the allocation remains under its inferred or declared region owner and is bulk reclaimed at that owner's validated exit. Conservative retention is the acceptable outcome; falling back to a tracing collector in a capable release build is not.

Aggregates and stored values

Aggregates may contain shared and independently owned children.

Insertion follows ordinary borrow/copy/transfer rules.
Explicit copy is required for independent duplication.
Removal may transfer responsibility out under normal lifetime rules.
Aggregate destruction recursively follows validated child responsibility and topology.
Borrowed children are never destroyed through the aggregate.

Static specialisation

Accepted effect categories:

MayConsume
NeverConsumes
AlwaysConsumes

These are analysis/lowering facts only, not required exact Rust enum names and not source-visible signature categories.

MayConsume retains conditional ownership handling.
NeverConsumes can omit conditional discharge handling.
AlwaysConsumes may remove ownership-condition branches only after call-path proof.
Specialisation must not create source-visible overloads or ordinary mandatory-consuming function APIs.
At a site where responsibility state or REC state is statically known, lowering may locally constant-fold that state and remove its known tag check.
This local folding does not require whole-function duplication, cloning or monomorphisation.
Whole-function cloning policy is deferred to benchmarks.
The unified semantic contract remains fixed even if implementation encoding evolves.

Physical representations

Retained Edge Counting is permitted as a narrow physical representation for statically legal topology with runtime-many persistent retained edges. The memory planner selects it for eligible families, and backend lowering encodes the selected layout and planned transitions. Source-visible RC, explicit retain/release APIs, weak ownership, finalizers or dynamic shared-ownership semantics remain outside the language design.

Compatible extension points within the accepted memory model:

stronger future-use precision
inferred region allocation and region epochs
place- and projection-based alias precision
discharge elision and physical cleanup coalescing through region knowledge
static ownership specialisation
field-sensitive allocation splitting
escape analysis
REC selection and elision for proven families

These must preserve source-language semantics and the unified ownership contract. A missing physical strategy after successful topology validation is a CompilerError, not a silent collector fallback.

Common mistakes

Treating ownership as a source type.
Treating ~ as ownership transfer.
Using runtime ownership metadata to decide source legality.
Treating bit 0 as uniqueness or observer count.
Confusing bit 0 (affine responsibility) with bit 1 (REC representation).
Masking an arbitrary interior pointer to recover an allocation-family base.
Treating borrow-checker advisory cleanup sites as the final lowering authority.
Reconstructing count or ownership transitions in the backend instead of consuming the planned transitions from ValidatedMemoryPlan.
Treating discharge as destruction.
Treating individual owned bits as permission to free declared-region-owned children.
Generating separate visible borrowed/owned functions.
Assuming every scalar is a tagged pointer.
Destroying borrowed values.
Using advisory sites as exact lifetimes or complete topology proof.
Requiring ownership proof for correctness.
Allowing ownership optimisation to change alias behaviour.
Introducing an ordinary source-visible mandatory-consuming function API. Channel send remains the accepted deferred mandatory-transfer boundary.