Allocation class abstract

A node of the_grid's third tree — a persistent managed object holding one live effect (ADR-0009 D1). Minted synchronously by Capability.createAllocation, then driven asynchronously by the Host through the four verbs (D4/D5).

Subclasses own their effect's state machine + freshness proof and REPORT through AllocationInputs.sink; they never write. The engine ships the ProcessAllocation + ServiceAllocation families; an asset may implement a custom Allocation for a custom Capability (tmux, app, lease).

Implementers

Constructors

Allocation(AllocationInputs inputs)
Binds the allocation to its inputs (the sync mint half of D4).

Properties

address → AllocationAddress
This effect's stable address (<sessionId>/<nodePath>).
no setter
hashCode → int
The hash code for this object.
no setterinherited
inputs ↔ AllocationInputs
The effect's values and services (args/transport/address/env/sink/fence).
getter/setter pair
isAdoptable → bool
Whether this effect type can be reattached to a survivor at its address (D4 — a per-type opt-in; a one-shot/service cannot, a daemon/lease can). When false, startOrAdopt always spawns fresh.
no setter
isDetachable → bool
Whether this effect type is safe to LEAVE RUNNING on unmount and re-adopt later (D4 — a per-type opt-in; the Host only calls detach when true).
no setter
runtimeType → Type
A representation of the runtime type of the object.
no setterinherited
state ↔ AllocationState
The current lifecycle state — a pure observation subclasses advance as their effect progresses (the Host maps reports → the persisted cursor; this field never writes).
getter/setter pair

Methods

canUpdate(Allocation next) → bool
Whether this allocation can absorb next's config in place, vs. the Host re-keying (dispose + recreate) — à la RenderObject canUpdate (D4). Update-vs-replace is a DOMAIN choice: a one-shot -p coding agent replaces (false); a tmux session updates (true). Defaults to replace.
detach() → Future<void>
LEAVE the live effect RUNNING and persist its handle so a later startOrAdopt reattaches it (D4 — a per-type opt-in, isDetachable). A DISTINCT verb, never an overloaded dispose (Nico's constraint). The base throws so a non-detachable effect can never silently leak a process; the Host only calls it for a detachable type.
didChangeDependencies(TreeWatchingReader reader, TreeDependencyScope scope) → void
Runs after initState and whenever a watched inherited value changes.
inherited
dispose() → Future<void>
KILL the live effect (the default / floor unmount verb): the effect is done/invalidated. A process family terminates its group; a service cancels its body + runs teardown.
initState(TreeSnapshotReader reader) → void
Runs once when the participant enters the tree.
inherited
noSuchMethod(Invocation invocation) → dynamic
Invoked when a nonexistent method or property is accessed.
inherited
startOrAdopt(TreeContext treeContext) → Future<void>
Spawn a fresh effect OR prove-and-adopt a survivor at address (D4). The engine owns only the stable address + no-adopt-on-faith (an adoptable type must return proof of freshness; can't prove → spawn fresh). Reports lifecycle through AllocationInputs.sink. The Host guards the single kick.
toString() → String
A string representation of this object.
inherited
update(Allocation next) → Future<void>
Mutate in place to serve next's config (only called when canUpdate is true). The TreeContext passed to startOrAdopt is call-scoped and is NEVER retained across update. The default implementation rebinds only inputs. A subclass with canUpdate returning true must re-read tree values from the TreeContext handed to each call, never cache one from an earlier call.

Operators

operator ==(Object other) → bool
The equality operator.
inherited