grid_engine library

M4 tree engine — genesis_tree IS the engine (ADR-0007, Accepted 2026-06-24).

build(observed) reconciles the running system: keyed reconcile + Branch lifecycle = the work lifecycle (mount = spawn, unmount = kill, a cursor tick = a reconcile transition). The kernel is opinion-light — a work bead's running subtree is contributed by an extension via a SessionResolver; the engine holds no landing / VCS / provider opinion.

The tree: Station → SubstationScope → Substation → WorkList → WorkBead → (SessionResolver) → SessionScope → CircuitScope → CapabilityHost → Allocation (the live effect — ADR-0009's third tree). Config flows down the ancestors (SubstationScope/Substation); the work axis is observed by exactly one node, WorkList (derailment-invariant 1).

Classes

ActorIdentity
An actor identity whose scheme and identifier are opaque to the engine.
AdoptFence
The prior incarnation's identity, handed to Allocation.startOrAdopt so an adopt-capable effect can run its no-adopt-on-faith freshness proof (D4/D5) — pgid still alive ∧ token echoed. Empty (all null) for a fresh mint.
Advance
Move the cursor FORWARD: this node completes and its dependents unblock.
Allocation
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).
AllocationAddress
An Allocation's stable, addressable identity — the node path <sessionId>/<nodePath> (ADR-0009 D2: light, with identity).
AllocationAdvanced
The route ADVANCED (M5 D-4a) — the cursor moves forward. The Host persists state=complete (merged with the optional payload); at the ROOT circuit's TERMINAL step it FIRST actuates the bound DeliveryMethod and merges the receipt into that same write. A LATCHING terminal.
AllocationCompleted
A job ran to completion — a POSITIVE TERMINAL that latches. The Host persists state=complete merged with the optional payload (e.g. a critic's grade or a land step's pr_url) under the disjoint result namespace.
AllocationContext
Everything an Allocation needs to manage its effect — assembled by the Host and handed to Capability.createAllocation (ADR-0009 D5).
AllocationEscalated
The route ESCALATED (M5 D-4a) — the Host raises it to the substation's bound EscalationHandler (unbound ⇒ HumanGate ⇒ state=gated + a real type=gate bead, M5 D-7 exactly). Replaces the earlier gated-allocation type: the engine no longer assumes the authority is a human. A LATCHING terminal.
AllocationFailed
The effect failed — routes to supervision (D5). The Host persists the supervised failure (bumped restartCount + backoff cooldown, or the exhausted breaker) and latches.
AllocationReady
A daemon signalled it is up — a POSITIVE TERMINAL that satisfies a dependsOn while the daemon stays mounted (OQ-5). The Host persists state=ready and does NOT latch (a later death still reports AllocationFailed).
AllocationReport
What an Allocation reports to its host (ADR-0009 D5 — push). The Host maps each to a cursor write OFF-BUILD through the one chokepoint; the Allocation itself is never handed a writer (invariant 2 holds at this layer by construction, the same layering as the pure Capability).
AllocationRewound
The effect decided the work must REWIND — routing, the dual of fan-out (tg-o90). The Host re-keys the named sibling stepIds + their transitive dependents + this node back to pending in ONE chokepoint write; no gate bead is minted and the session is NOT re-minted. A LATCHING terminal for THIS incarnation (the node re-mounts as a fresh one once its deps re-complete).
AllocationStarted
The effect's process group came up — the Host persists state=running plus the per-node pgid/pid (the respawn/liveness fence). The freshness token is the Host's (it minted it), so it is not carried here.
Backoff
The mandatory backoff schedule for a supervised restart (M4-P1 §3 / D-5).
BlockEdge
One blocking edge the union frontier must enforce, whatever authored it.
CacheTokenTotals
Cache-token components retained for lossless projection merges.
CancelToken
A cooperative cancellation flag a Capability polls across async gaps — set when the host unmounts. The engine never force-kills a ServiceCapability body; the capability checks isCancelled and unwinds. It is ALSO the mounted-probe by proxy: cancelled ⟺ the host disposed, so an uncancelled token means the tree context is still safe to read.
Capability
A leaf the engine mounts. The engine ships three families — ProcessCapability (a spawned process), ServiceCapability (an async body), and LeaseCapability (a held lease) — and an asset may add its own (tmux, app, …).
CapabilityFacts
A typed bag of capability facts — a station's profile or an order's requirements (ADR-0011 D6).
CapabilityFactsConverter
Bridges CapabilityFacts into freezed/json_serializable's codec (the CapabilityStep.requires field, the honesty-pass D-B5, 2026-07-03) so a step's declared per-requirement CapabilityFacts round-trips through the SAME Circuit/CircuitStep JSON shape every other field already does. Reuses CapabilityFacts.toProfile/fromProfile — the identical wire form Presence.profile carries — rather than inventing a second serialization. Null-safe both ways: an undeclared requirement (the overwhelmingly common case — most steps resolve locally) round-trips as null, never {}.
CapabilityHost
The carrier for one mounted CapabilityStep. Built by the registry's host; keyed ValueKey('$nodePath#$restartCount') so a supervised restart re-keys.
CapabilityHostState
The pinned CapabilityHost lifecycle — the thin driver (ADR-0009 D5).
CapabilityProbe
Probes a station's CURRENT capability facts (ADR-0011 D6) — an observation.
CapabilityRegistry
The engine's capability/circuit/clock resolution seam (Track D). The default impl ships in the extension (Track E/H); tests inject a fake.
CapabilityRevalidator
Re-validates a held lease against CURRENT capabilities at TTL renewal (ADR-0011 D6, shift-revocation depth #2 — re-check at the renewal boundary, NOT continuously).
Circuit
A declared step-graph the engine inflates into a reconciled subtree (M4-P1 §3 — the reentrant unit).
CircuitResolver
An SessionResolver that roots a reentrant SessionScope subtree per work bead (Track D).
CircuitScope
The pure inflater for one circuit instance rooted at nodePath, under cursor (M4-P1 §4). Engine-private — an asset never subclasses it.
CircuitStep
One step in a Circuit — a sealed union the inflater maps to a child Seed (M4-P1 §3 / §4).
ClaimResultKeys
The keys leaseGrantToResultPayload writes / leaseGrantFromResultPayload reads — a granted lease's durable record, string-typed for the generic step-result payload (Map<String, String>).
One projected cross-repo blocking edge, read off an OPEN link bead.
CrossLinkKeys
Metadata keys on a grid-state type=link bead — the station's OWN record of a CROSS-REPO blocking edge.
DefaultCapabilityRegistry
The standard registry — a fixed-at-mount handle provided via a plain InheritedSeed<CapabilityRegistry> at the root.
DeliveryMethod
The DOMAIN half of a TERMINAL Advance (ADR-0008 Decision 5 — the engine knows a domain in CONCEPT, never in DETAIL). The engine knows only "actuate the terminal delivery"; WHAT delivery means is the substation's: open a PR / merge-queue / direct-merge for code (bead tg-hlz builds those three), commit- a-chapter or export for a book, hand the artifact back for an agent supporting an agent.
DeliveryRequest
Everything a DeliveryMethod gets — plain VALUES the router read from the tree at entry (never a TreeContext, never a writer).
DiagnosticProperty<T>
A typed property contributed by a Diagnosticable object.
DiagnosticsTreeWalker
Projects a mounted genesis tree into the version-1 semantic diagnostics tree.
DoubleProperty
A double-valued diagnostic property.
DualReadAccounting
The per-boot dual-read counters — the durable round summary's payload.
DualReadComparison
The result of comparing one legacy projection against its identity-matched P1 head.
DualReadDivergenceDetail
One first-counted field divergence, retained for the boot's summaries.
DualReadFieldMismatch
One field-level mismatch, rendered for the flare payload and the round summary. Values are stringified because that is what both surfaces carry.
DualReadSessionObserver
Runs the session-axis comparator and owns everything it accumulates.
DualReadStepObserver
Runs the step-axis comparator and owns everything it accumulates.
DurationProperty
A duration-valued diagnostic property.
EnumProperty<T extends Enum>
An enum-valued diagnostic property.
EpochScopedSessionHeadView
A session-head view that carries the epoch which last advanced its fold.
Escalate
The router DECLINES: raise to the substation's bound EscalationHandler.
EscalationDecision
What the bound handler decided — the arms the ROUTER effects.
EscalationHandler
The DOMAIN target of an Escalate verdict (ADR-0008 Decision 5). The engine RAISES; the bound handler DECIDES. Bound per-substation via ServiceBundle.escalation — UNBOUND ⇒ HumanGate, the M5 D-7 default. The engine hardcodes no authority: a parent-router / governor-queue handler drops in HERE with no engine change.
EscalationRequest
What the router RAISED — plain VALUES (ADR-0013 item 2: the distinguishing identity — here the spent rewindCount — rides IN the value; a handler never re-derives it from a side channel).
ExplorationTransport
Reserved outbound exploration transport — an emit-only sink, never an inbound pipeline handle (invariant 1). The live arm adapts it over the exploration host event stream leonard reads (A39/A40).
Failed
The capability failed (routes to supervision). Maps to StepState.failed.
FailToSupervision
The handler could NOT absorb the escalation: route the node to SUPERVISION (bumped restartCount + backoff, then the breaker → SessionScope's exhaustion escalation). The DECLINE arm — LOUD, never a silent park nobody owns (ADR-0008 Decision 3: LOUD or GONE).
FakeProbe
A controllable CapabilityProbe for tests: returns facts, which a test may reassign between reads to simulate a shifting configuration (a toolchain gained or lost). No IO.
FalseFMetrics
FederatedSnapshotSource
Unions N local work SnapshotSources into ONE change-gated SnapshotSource — the fan-in that runs BEFORE StationJoinBridge (D-F1).
FlagProperty
A boolean flag diagnostic property.
GridIssueTypes
the_grid's registered custom issue-type vocabulary.
HumanGate
The DEFAULT escalation binding (M5 D-7): raise to a HUMAN by parking at a real type=gate bead. Stateless + const — the engine's ONLY handler; every other authority ships in an asset.
Idle
The terminal leaf of an effect subtree — a branch with no children and the default (empty) rebuild hook (the genesis Leaf idiom).
IntProperty
An integer-valued diagnostic property.
JoinedSnapshot
The single immutable value the tree builds from: the read-workspace work graph JOINed with the_grid's owned session cursors, keyed by work bead id.
JoinedSnapshotNotifier
The single observable source the work axis builds from — a StateNotifier the join bridge (Track B) drives from OUTSIDE the tree.
LandedDeliveryTotals
Landed-delivery components retained for lossless projection merges.
LeaseAllocation<H>
The carrier for a HELD lease (ADR-0009 D6). Holds the bound handle as an instance field, drives the capability's hooks, and REPORTS through the sink — never writes. Transport-agnostic: it never names a bus.
LeaseBound<H>
A live lease binding carrying the concrete handle (opaque to the engine — the capability's own binding: a bus client + grant, a local slot, …).
LeaseCapability<H>
A Capability backed by a HELD lease (ADR-0009 lease family). The author implements the transport-specific hooks over an opaque handle H and NEVER a Seed; the LeaseAllocation carrier owns the tree lifecycle. The engine names no bus — a federation lease supplies H = (StationClient, LeaseGrant) and wires the bus inside these hooks; a local single-station lease supplies a local slot handle.
LeaseGrant
A granted lease (the POST /lease success body): the handle the lessee dispatches against, plus the TTL after which the lessor reaps it.
LeaseRequest
A lessee's request for one slot of kind (the POST /lease body).
LeaseResolution<H>
The outcome of a LeaseCapability.acquire (or an adopt resolution): a live binding carrying the opaque handle H, or a fail-closed reason. Sealed so a consumer's dispatch is exhaustive (house style).
LeaseUnavailable<H>
No lease was possible — fail-closed with a reason (no peer satisfies the requirements, capacity denied). The allocation reports it as a failure.
LedgerNodeMetrics
LedgerSessionMetrics
LinkedSessionVerdict
What a work bead's linked session rows MEAN for the mount boundary — a freezed SEALED union, so every consumer's dispatch is exhaustive (ADR-0001 Decision 1's house style).
MemberFreshness
One federation member's freshness (tg-nsj, docs/SCRATCH-multi-root-federation.md D-F3/D-Z3/D-Z4) — the per-member VECTOR FederatedSnapshotSource.freshness exposes instead of collapsing every member into one scalar capturedAt.
MetricsDecodeIssue
MoleculeCircuitKeys
Metadata keys on a type=molecule bead — one bead per circuit instance (the root circuit a session mints, or a nested SubCircuitStep's own circuit, recursively).
MoleculeStepKeys
Metadata keys on a type=step bead — one bead per leaf CapabilityStep.
MountAttemptKeys
The metadata keys carried by ONE type=mount-attempt bead per work bead.
MountAttemptRecord
One work bead's durable attempt record, projected out of the state store.
MountEligibilityDecision
The content-gate decision returned by MountEligibilityPredicate.
NodeCursor
One inflated node's cursor entry, keyed by its nodePath in a CircuitCursor.
ObjectProperty
A nested object diagnostic property.
Ok
The capability succeeded, optionally carrying a payload (e.g. a PR url) the engine may record. Maps to StepState.complete.
OriginTrustKeys
Metadata keys for the intake-authored origin trust stamp.
OrphanSweepReport
The immutable outcome of one RestartReconciler.sweepOrphans pass — enough to assert in a test and to log a one-line teardown summary.
ParkAtGate
PARK the node at a gate: state=gated + a real type=gate bead minted in the_grid's OWN state store through the chokepoint (never the foreign work bead — A37). The node withholds its dependents and re-arms when that gate bead CLOSES (SessionScope's M5 D-7 re-arm, untouched). HumanGate returns this — reproducing D-7 EXACTLY.
Presence
A station's advertised presence + current capacity (the GET /presence body) — discovery plus a liveness/health probe.
ProcessAllocation
The process family — drives a ProcessCapability over the process transport (ADR-0009 D6). A one-shot (StepKind.job) is respawn-or-skip (not adoptable, not detachable — the reconciler + frontier own respawn); a StepKind.daemon is adopt-or-respawn + detach-capable (Track C wires the daemon proof/detach; the base here spawns-and-reports, preserving P0's Agent/Verify behavior exactly).
ProcessCapability
A capability backed by a spawned, supervised process. The carrier owns provider.start/stop; the capability is PURE description.
ProcessLeaseVendor
A vendor of process leases, addressed per step bead (Decided item 5). One instance is provided ambient to the whole station tree (deferred to pm6-r5-drain's kernel-root provision, beside CapabilityRegistry); every process-backed capability on the molecule path calls leaseFor with ITS OWN durable step-bead id to obtain the LeaseCapability<ProcessHandle> it mounts.
ProcessSession
Protocol-neutral lifecycle and command surface owned by an Allocation.
ProcessSessionCommand
One durable, attempt-fenced command addressed to a live session.
ProcessSessionUpdate
One protocol-derived observation from a long-lived process session.
ReferenceProperty
A reference-valued diagnostic property.
ResourceRequest
A declared, statically-inspectable resource peak (M4-P1 §3 / D-7).
RestartEntry
One row of the RestartReport: the worktree, its disposition, and the mechanism outcome that produced it (so a caller/test can assert WHY without scraping logs).
RestartReconciler
Reconciles the restart survivors (worktrees + owned session beads) into a respawn-or-skip plan, BEFORE the kernel re-mounts the tree.
RestartReport
ResultKeys
The per-node RESULT keys — the payload a positive terminal publishes: a job's Ok.payload on complete (e.g. the land step's pr_url) OR a daemon's rendezvous payload on ready (e.g. the burn-follower's {endpoint, …}), recorded on the step's OWN type=step bead so a finished/ready step's artifact is durable (ADR-0006 D3: "record the PR on the lifecycle bead"; R1 re-homed the write from the session bead to the step bead — the keys are unchanged). Flat + merge-safe (D-1/D-3). Read back pull-free by a dependent step via projectCircuitResults → SessionProjection.results → the SiblingView (a route/burn-host reads a sibling's grade/endpoint — never a re-query, A39). Also the human-/audit-facing record of what a step produced.
ResultMetricFields
ResultTransport
RetirementLagTracker
The RETIREMENT-lag twin, with the same 90 s grace and a simpler rule: the entry heals when the row leaves the CURRENT partition, and ESCALATES to a divergence only when the successor session is already present in P1 and the row is STILL current past the grace (r9 — the retire-close runs at that mint; its record must have dropped).
RetryPolicy
One kind's retry declaration. Every field is optional; a null field INHERITS the owning Circuit's value, which stays the compatibility default.
RevalidationResult
The outcome of a TTL-renewal re-validation (ADR-0011 D6, depth #2).
Rewind
Re-run a sub-DAG of the rewinding node's OWN circuit — routing's lossy arm, re-homed off StepOutcome onto the verdict, UNCHANGED (A47).
RouteAllocation
The route family (ADR-0009 Decision 6's graduated conveniences) — drives a RouteCapability's body once and reports its verdict. Not a process: it holds no group to reap; dispose cancels the cooperative token and runs teardown.
RouteCapability
A capability whose whole job is to ROUTE: it reads its siblings' terminal states + results (the ambient SiblingView — M5 D-5's sibling-read affordance) and emits exactly ONE RouteVerdict.
RouteVerdict
What a RouteCapability decided — the ONE route primitive's output.
ServiceAllocation
The service family — the JobAllocation convenience (ADR-0009 D6): start-runs, no update, no adopt, no detach. Drives a ServiceCapability's async body once and reports its StepOutcome. This is literally P0's Land/route behavior, split onto the right object.
ServiceBundle
The pluggable collaborators a Capability drives (ADR-0008 D5) — ONE concrete bundle (genesis's exact-type inherited lookup can't resolve an abstract <SourceControl>), provided per-SubstationScope. Impls ship in assets.
ServiceCapability
A capability backed by an async body driving ServiceBundle collaborators (git/PR orchestration, the Burn coordinator). No process lifecycle; its run resolves to a StepOutcome.
SessionBeadKeys
Metadata keys on a the_grid session bead. work_bead + rig are stamped at mint by StationBeadWriter.createSession; the rest are written later through the chokepoint.
SessionDisposition
What a work bead's joined session means — a freezed SEALED union, so every consumer's dispatch is exhaustive (ADR-0001 Decision 1).
SessionHandle
An adopt-or-minted session's identity — the sessionId is the the_grid OWN session bead all of the circuit's cursor writes target (A37 / invariant 4).
SessionHeadCardinalityBreach
Partition case (2): more than one CURRENT open row on one bead — a genuine double-mount, never a rework, because retired rows are excluded from the decision partition. Serve NO row, flare trajectory.dualReadDivergence{field:'cardinality'}, count fallback.
SessionHeadFacts
P1's facts about one head, DERIVED into the legacy vocabulary — the only shape either side of the comparison is ever expressed in (§0.3: "compares the DERIVED tuple … never raw column-vs-stamp").
SessionHeadNone
No row is servable for this bead — either the mirror holds none, or the bead's only open rows are RETIRED (the rework window, successor not yet minted). The legacy side has no base-key projection there either, so this matches rather than diverges.
SessionHeadView
One proj_session_head row, as the engine reads it (P1 — §7's head summary).
SessionHeadWinner
What TrajectoryHeadSnapshot.byWorkBead resolved to.
SessionHeadWon
Exactly one row wins the bead — partition case (1) or (3).
SessionLedgerMetricsProjection
SessionOverlayResult
One resolved overlay — the projection to serve plus WHY.
SessionProjection
The_grid's projection of ONE work bead's owned session/lifecycle bead — the JOIN row A40 reconciles against.
SessionResolver
The opinion-light seam between the kernel and the running work subtree (ADR-0007 Decision 5 / ADR-0008 D4): given a work bead (and its linked session), return the Seed that runs it.
SessionScope
The tree execution lifecycle for one admitted work bead's circuit.
SessionScopeState
The {resolving | ready | failed} lifecycle (D-2). The async-gap guards (_cancelled set first in dispose, context.mounted after every await, the captured _ctx) are the same discipline as CapabilityHostState.
SiblingView
A read-only view of THIS session's per-node cursor + results — an ambient VALUE mounted by SessionScope (never a subscription/re-query — A39/ invariant 1). A ServiceCapability (e.g. route) reads its sibling steps' terminal states + result payloads by looking this up with the effect verb — the ONLY sibling-read affordance (no writer, no notifier; the derailment gates hold). D-5, plumbing moved ambient 2026-07-02.
SnapshotSource
The observable snapshot seam the join bridge subscribes to — the narrow surface of a GridControllerRuntime the bridge actually needs.
SourceControl
The first Service — WORKSPACE PROVISIONING, abstracted so the engine knows it in CONCEPT, not detail (the git impl ships in the asset pack). Clean + dependency-free so a future genesis-shared home is a move, not a rewrite (designed-to-be-lifted).
Station
The root of the running system (ADR-0007): a keyed-reconcile container of per-substation scopes. build(observed) starts here — the tree IS the engine, and the Station's children ARE the substations.
StationAdmissionAuthority
The single station-owned answer to “may this attempt start now?”.
StationAdmissionBatch
The immutable result of one synchronous admission request.
StationAdmissionCandidate
A work bead and the session projection that must ride with its mount.
StationAdmissionRefusal
A fail-closed admission answer carrying its named clause and explanation.
StationAdmissionReservation
One candidate whose station and substation capacity has been reserved.
StationAdmissionStatus
A read-only station admission snapshot for operator status surfaces.
StationClient
The cross-station bus, lessee view: presence, lease, dispatch, release. The pluggable, kind-agnostic transport seam (ADR-0011): impl #1 (HttpStationClient, over HTTP) lives in power_station's federated_grid_assets; a future MQTT/WS bus implements this same interface, so nothing above the seam changes (Nico, 2026-06-29).
StationDriver
The station's OFF-TREE work-axis machinery (extracted from the retired kernel so a tree mounted by a DIFFERENT owner — runGrid's, tg-yl8 — reuses it unchanged): the join-bridge lifecycle, the supervised-restart cooldown Timer (D-5/F1: the driver owns the wall clock + the cooldown Timer, NEVER a Seed), the backoff re-poke, and the unclaimed-frontier scan (D-B5 hook #1).
StationJoinBridge
The JOIN bridge — the only subscription into the snapshot pipelines (A39 / derailment-invariant 1).
StationProcessLeaseVendor
The real, breadcrumb-persisting ProcessLeaseVendor (Decided item 5's non-degraded mode). Holds the four collaborators leaseFor's vended lease needs — writer (the SAME StationBeadWriter chokepoint every other molecule write already rides, Decided conflict 3), spawn/dispatch (the deferred process transport), metadataOf (the deferred breadcrumb read), and liveness (StationServices.liveness, defaulting to neverLive — same offline default the flat model's AllocationContext.liveness uses).
StationServices
The STATION-level ambient services a node resolves from the tree in one inherited lookup (ADR-0009 D2/D3 — the MediaQuery pattern: related ambient data, one lookup, scoped to the station).
StepArgs
The irreducibly per-step values a capability receives alongside the tree context — NOT a context and NOT a grab-bag: everything ambient (bead, workspace, services, siblings) is read from the tree with the effect verb; only what is genuinely OF this step incarnation rides here.
StepCursorMerge
The result of merging P2 over one session's bead-carried cursor.
StepCursorOverlay
ONE session's step-axis overlay, as the pass hands it to the join.
StepCursorView
One proj_step_cursor row, as the engine reads it (P2 — the round-bearing step cursor on the two-ladder key).
StepLagTracker
THE STEP-LAG TRACKER — stepLag's escalation arithmetic, step-shaped.
StepMount
Everything the registry's CapabilityRegistry.host needs to mount one eligible CapabilityStep as an engine leaf.
StepNodeComparison
One node's compared pair, rendered for the flare payload and the summary.
StepOutcome
The outcome of an ordinary capability body — {Ok, Failed} and nothing else.
StringProperty
A string-valued diagnostic property.
Substation
A single substation's work root. Reads its ambient SubstationConfig (provided by the enclosing SubstationScope) and builds the substation's WorkList.
SubstationConfig
A substation's configuration — the config axis (ADR-0007: config nodes are ancestors of work nodes).
SubstationConfigNotifier
The observable source of the config axis for one substation — a StateNotifier SubstationScope observes.
SubstationScope
The per-substation config scope — an ancestor of the substation's work nodes (ADR-0007: config nodes are ancestors of work nodes).
SupervisionPolicy
A capability's whole supervision declaration — a per-kind RetryPolicy map.
TeardownReplayEntry
The immutable outcome of one RestartReconciler.reconcile pass — lists of entries bucketed by disposition, enough to assert in a test and to log a one-line restart summary. One session the teardown replay considered (tg-tlea).
TeardownReplayReport
What one boot's teardown replay did (tg-tlea).
TerminalLagTracker
THE ONE ESCALATION RULE, mechanized (§0.3 MONOTONIC TERMINALITY, r8).
TerminalReconcileRequest
One heal request, handed to the (async, store-touching) healer through an emit-only sink. The bridge decides WHETHER; the healer's guard pre-check decides whether the append is admissible.
TimestampProperty
A timestamp-valued diagnostic property.
ToolchainProbe
The real, LOCAL toolchain CapabilityProbe (ADR-0011 D6). Reports system-os from Platform (the authoritative host OS), and a host-default dart-target / flutter-target for whichever of dart / flutter is present (probed via --version). An absent toolchain emits NO target fact (fail-closed — never derived), so a station without flutter cannot match a flutter-target requirement.
TrajectoryAdmissionHalt
The single boot-lifetime admission breaker shared by the harness, mount authority, offline mount path, and decision-bearing call sites.
TrajectoryHeadSnapshot
One immutable, versioned read of the P1 mirror.
TrajectoryRecorderScope
The ambient value a Provider<TrajectoryRecorderScope> vends.
TrajectoryStepSnapshot
One immutable, versioned read of the P2 mirror (C4's; declared with P1 so the read seam is one file).
TreeProjector
Projects the live semantic tree after completed kernel flushes.
Trust
Resolves producer-owned actor identities for intake admission.
TrustFloor
The minimum origin trust a substation admits at its mount boundary.
UnclaimedRequirement
One session's unclaimed requirement — step (the pure per-circuit record) plus which session/work bead it belongs to, so a claim capability can correlate a broadcast reply back to the right node.
UnclaimedStep
One eligible step whose declared requirement the station cannot fulfill locally (D-A3/D-B5) — the unit an asset claim capability broadcasts.
WedgeMonitor
Samples the station's forward progress on a timer and flares a SUSTAINED stall exactly once per episode. Owned + driven by StationDriver.
WedgeSample
One instantaneous, pure count of the station's forward progress, taken over the LIVE (non-terminal) sessions of a JoinedSnapshot.
WedgeState
The station's sustained wedge state — a freezed SEALED union, so a consumer's dispatch is exhaustive (ADR-0001 Decision 1).
WorkBead
One unit of work as a persistent tree node (ADR-0007: a Branch IS the work lifecycle — mount = spawn, unmount = kill; progress is the per-node reentrant cursor advancing the inflated circuit subtree).
WorkList
The work-axis observer and projection of the station admission authority.
Workspace
The per-session workspace the work runs in — an ambient VALUE mounted by SessionScope (computed once per session from the per-substation SourceControl; ADR-0008 D5: the layout is the SourceControl impl's opinion, the engine's concept is "a workspace"). A capability reads it with the effect verb: context.getInheritedSeedOfExactType<Workspace>().
ZombieReap
One ZOMBIE running-node a flat-model restart pass reaped.

Enums

AllocationState
The lifecycle state of an Allocation (ADR-0009 D5: starting → live → [ready] → dying → gone, plus adopting).
CapabilityFailureKind
WHY a capability's turn failed — the engine-owned discriminant that replaces the transitional boolean on Failed.
CompletionContract
What a capability's FINISHED turn leaves behind — the capability's own declared working agreement, and the thing that lets the engine PROVE a completion (no-complete-on-faith, the dual of ADR-0009 D4/D5's no-adopt-on-faith).
DualReadClass
What ONE compared pair resolved to.
DualReadDivergenceCause
The mechanical evidence available when a divergence is first counted.
DualReadMissClass
Why a bead-projected session has no P1 row.
DualReadMode
The dual-read posture (cut-wiring C2's config line).
ExhaustionBehavior
What happens when a kind's restart budget is spent.
LedgerGrade
ProcessCommandDisposition
The exact result of offering one command to a live session.
RestartDisposition
The disposition of one surviving worktree after restart reconciliation.
SessionHeadOutcome
P1's outcome ENUM, engine-side — the decision-faithful terminal vocabulary verbatim, so the sdk's adapter is a name-for-name mapping and the engine never imports the trajectory package to read one.
SessionHeadProvenance
P1's terminal_provenance ENUM, engine-side.
SessionOverlayOutcome
Why resolveSessionOverlay served what it served — the accounting axis C3 needs and the reason a soak round can be read: "how many decisions did the fold actually change, and how many did a rule refuse?"
SessionPauseState
The SessionBeadKeys.pauseState vocabulary. Absence means none.
StepFailureClass
StepKind
The lifetime of a leaf step (M4-P1 §3 / OQ-1).
StepNodeClass
What the step comparator resolved for ONE node.
StepSignal
What an observed runtime or protocol event means to a process step.
StepState
The cursor state of one inflated node (M4-P1 §3).
SupervisionStrategy
How a Circuit supervises a failed child (M4-P1 §3 / D-5).
TerminalLagAction
What the tracker says to do about one terminalLag entry this pass.
TerminalReconcileOutcome
How a heal attempt resolved, reported back by the (async) healer.
TrajectorySnapshotHealth
A snapshot's trustworthiness, wave-1 semantics (§0.2, r4 — J6-B3/J7-M3).
TrustLevel
Origin trust on the single admission axis, ordered least to most trusted.

Mixins

GridDiagnosticable
Marks a genesis diagnostic object as part of the grid semantic projection.

Extensions

BackoffPatterns on Backoff
Adds pattern-matching-related methods to Backoff.
CacheTokenTotalsPatterns on CacheTokenTotals
Adds pattern-matching-related methods to CacheTokenTotals.
CircuitPatterns on Circuit
Adds pattern-matching-related methods to Circuit.
CircuitStepPatterns on CircuitStep
Adds pattern-matching-related methods to CircuitStep.
FalseFMetricsPatterns on FalseFMetrics
Adds pattern-matching-related methods to FalseFMetrics.
GridDiagnosticsBuilder on DiagnosticsBuilder
Adds grid's strongly typed property adapter to foundation's builder.
GridIssueTypeClassification on IssueType
the_grid-only classifications over beads' open IssueType.
IssueTypeDriveability on IssueType
The_grid's resident-station driveability narrowing (RS-3/D-R4) — a grid opinion layered on beads' generic IssueType, not a beads fact.
LandedDeliveryTotalsPatterns on LandedDeliveryTotals
Adds pattern-matching-related methods to LandedDeliveryTotals.
LedgerNodeMetricsPatterns on LedgerNodeMetrics
Adds pattern-matching-related methods to LedgerNodeMetrics.
LedgerSessionMetricsPatterns on LedgerSessionMetrics
Adds pattern-matching-related methods to LedgerSessionMetrics.
LinkedSessionVerdictPatterns on LinkedSessionVerdict
Adds pattern-matching-related methods to LinkedSessionVerdict.
MetricsDecodeIssuePatterns on MetricsDecodeIssue
Adds pattern-matching-related methods to MetricsDecodeIssue.
MountEligibilityDecisionPatterns on MountEligibilityDecision
Adds pattern-matching-related methods to MountEligibilityDecision.
NodeCursorPatterns on NodeCursor
Adds pattern-matching-related methods to NodeCursor.
ProcessSessionCommandPatterns on ProcessSessionCommand
Adds pattern-matching-related methods to ProcessSessionCommand.
ProcessSessionUpdatePatterns on ProcessSessionUpdate
Adds pattern-matching-related methods to ProcessSessionUpdate.
ResourceRequestPatterns on ResourceRequest
Adds pattern-matching-related methods to ResourceRequest.
ResultTransportPatterns on ResultTransport
Adds pattern-matching-related methods to ResultTransport.
SessionDispositionPatterns on SessionDisposition
Adds pattern-matching-related methods to SessionDisposition.
SessionLedgerMetricsProjectionPatterns on SessionLedgerMetricsProjection
Adds pattern-matching-related methods to SessionLedgerMetricsProjection.
SessionProjectionPatterns on SessionProjection
Adds pattern-matching-related methods to SessionProjection.
SubstationConfigPatterns on SubstationConfig
Adds pattern-matching-related methods to SubstationConfig.
WedgeSamplePatterns on WedgeSample
Adds pattern-matching-related methods to WedgeSample.
WedgeStatePatterns on WedgeState
Adds pattern-matching-related methods to WedgeState.

Constants

driveableTypes → const List<IssueType>
The plain coding-work core types — the DRIVEABLE-WORK boundary a resident station's all-ready arming narrows to (RS-3/D-R4): every other core type (epic/decision/spike/story/milestone) is organizational, not something an agent drives.
kCrossLinkBlocks → const String
The one CrossLinkKeys.type value the engine enforces.
kCrossLinkTargetCloseRule → const String
The lifecycle rule shared by engine and operator-facing cross-link text.
kDartTarget → const String
The dart-target fact key — the platform(s) the dart toolchain can build for. Set-valued; derives from kSystemOs when undeclared.
kDefaultKind → const String
The default resource-asset kind a request/offer carries when it leaves kind unspecified — a GENERIC placeholder, deliberately NOT a concrete kind (which each asset domain names for itself, ADR-0011 D3). The federation core treats kind as an opaque, equality-checked label and assumes no domain.
kDefaultMaxConcurrentWork → const int
The concurrency governor's generous default station cap (tg-42f) — chosen so ordinary single/few-bead dev and dry-run flows never throttle.
kDefaultWedgePollInterval → const Duration
The default cadence the station re-samples its own forward progress at.
kDefaultWedgeThreshold → const Duration
The default sustain window before a stall is called a WEDGE — long enough that no legitimate transition trips it (the supervised-restart backoff caps at 60s; a Rewind verdict's wave re-keys within a microtask flush — A47), short enough that the governor is pulled in within a poll or two rather than whenever a human happens to look.
kDualReadCounterSemantics → const Map<String, String>
Semantics for every scalar counter emitted by DualReadAccounting.toJson, plus the original map-valued divergence row. Scoped map twins inherit that row's cumulative semantics (documented at their insertion point below) rather than widening this legacy flat index.
kDualReadDivergenceFlare → const String
The flare a served-tuple mismatch raises. Axis-tagged, because C4 adds a step axis under the same name.
kDualReadRoundSummaryChannel → const String
The attempt.note channel the durable round evidence rides (§0.4).
kFlutterTarget → const String
The flutter-target fact key — the platform(s) the flutter toolchain can build for. Set-valued; derives from kDartTarget when undeclared.
kHarnessSilenceFloor → const Duration
An artifact-less failure under this floor is a harness non-result.
kHarnessThrottledFlare → const String
Non-blocking signal emitted when a harness exit is classified as infra.
kHarnessThrottleMarker → const String
Prefix persisted on every classified harness-throttle failure.
kMaxMountAttempts → const int
How many times one work bead may be mounted before the frontier stops remounting it and it becomes visibly human-attention-requiring.
kMaxReasonChars → const int
The max persisted length of a capture-only failure/escalation diagnostic (FT-1, tg-pez) — a pathological multi-KB stderr is truncated so telemetry never bloats the session bead's metadata (fail-safe).
kMaxReworkRounds → const int
The max rework rounds one work bead may accumulate before the grid REFUSES to rework it again — the cap RATIFIED in docs/M5-THE-CIRCUIT-BUILD-ORDER.md D-4 ("Bounded rework rounds (factoryskills' cap 3)").
kMountAttemptCapClause → const String
The clause name a capped bead is refused under — the string that rides work.mountEligibilityRefused so the refusal names itself in the log.
kNotWedged → const Flowing
The never-alarming default: what a status built WITHOUT a work runtime reports, so a status surface can never raise a phantom alarm.
kNoWedgeSample → const WedgeSample
The all-zero sample — no live session at all.
kOperatorRulingTransport → const String
The ResultKeys.transport provenance an OPERATOR RULING stamps on a lane result (tg-i08) — the marker distinguishing a human override from an automated verdict. A lane graded through the chokepoint with this transport is a deliberate operator decision, never a fail-closed/transport artifact.
kRadio → const String
The radio fact key — the radios a station exposes ({ble}, {ble, wifi}). Set-valued (it unions across composed domains).
kReconstructedTerminalSkippedFlare → const String
The flare a breadcrumbless teardown replay raises (r5): a missing record is a VISIBLE lag; a minted-id record would be an immutable lie that revert cannot remove and every traj replay reproduces.
kRetirementLagGrace → const Duration
The symmetric escalation grace on a retirementLag entry (r9, aligned with FINAL Q5): the re-key lands before the successor mint's roundRetired, and past this the retire-close's record must have dropped.
kRouteVerdictAdvance → const String
kRouteVerdictEscalate → const String
kSessionModelFlat → const String
The SessionBeadKeys.model value a LEGACY / flat-cursor session carries — written here for symmetry with kSessionModelMolecule even though the read side (projectSession) treats ABSENT the same as this value; a later rung (R5/R6) may stamp it explicitly rather than omitting the key.
kSessionModelMolecule → const String
The SessionBeadKeys.model value a MOLECULE-MINTED session carries, stamped once at createSession time by a later rung (R5) in the SAME write as SessionBeadKeys.workBead.
kSessionOutcomeCommitOnly → const String
The SessionBeadKeys.outcome value an unbound delivery close stamps.
kSessionOutcomeComplete → const String
The SessionBeadKeys.outcome value a delivered terminal close stamps.
kSessionOutcomeLegacy → const String
The SessionBeadKeys.outcome value stamped by the one-time A59 backfill.
kSetFactKeys → const Set<String>
The fact keys that are SET-valued this pass (the domains' set facts). When a flat wire profile carries one of these as a bare string, CapabilityFacts reads it as a singleton set; any other key with a string value is a scalar.
kStepLagGrace → const Duration
The grace a stepLag entry gets before it escalates to a divergence.
kSystemOs → const String
The system-os fact key — the operating system(s) a station runs ({linux}, {macos}, …). Set-valued (a singleton in practice).
kTargetChain → const List<String>
The derived-default chain, BROAD → NARROW (ADR-0011 D6): a missing narrower target derives from the nearest broader one (flutter-target ⟸ dart-target ⟸ system-os). Used by CapabilityFacts.deriveTargets; NOT applied by CapabilityFacts.matches (a probe reports ground truth — an absent toolchain must not be back-filled).
kTerminalLagHealGrace → const Duration
The heal grace on a terminalLag entry (r8 — V2-B2): three tick intervals, an order of magnitude past the post-ACK apply window, so a NORMAL terminal's transit through bd-first/append-later can never trigger anything.
kTrajectoryAdmissionHaltGateReason → const String
The stable gate reason for every cut-only trajectory admission halt.
kUnwedgedFlare → const String
The flare emitted ONCE on the falling edge — forward progress resumed.
kWedgedFlare → const String
The flare emitted ONCE on the rising edge of a wedge episode (ADR-0008 D9 — a non-blocking signal, never a gate: a flare-as-gate would wrongly halt the loop). Named like its siblings session.mintFailed / work.throttled.
kWorkSignalTimeout → const Duration
How long the completion fence waits for a WorkSignalProbe before calling the workspace unreadable (GateOutcome.probeError — fail closed, so the step respawns rather than stalling). Generous: the probe is one status call on a local workspace, so a breach means something is genuinely wedged (an index lock, a stalled network FS), not merely slow. Overridable per allocation via AllocationContext.workSignalTimeout (a test injects a short one).
kWorkTerminalReasonWorkBeadClosed → const String

Functions

applyBlockGuard({required Set<String> candidates, required Map<String, Bead> beadsById, required Iterable<BlockEdge> edges, void onUnresolved(String message)?, void onBlocked(String beadId, BlockEdge edge, Bead? target)?}) → Set<String>
Re-applies edges over candidates, fail-closed — the ONE implementation of what a cross-store block means.
applyTrustGuard({required Set<String> candidates, required Map<String, Bead> beadsById, required TrustFloor floor, required bool trustConfigured, void onUnresolved(String message)?}) → Set<String>
Narrows candidates to origins admitted by floor, synchronously and without I/O. An entirely absent origin stamp is backward-compatible and admitted. A present but unprovable stamp is refused fail-closed and LOUD.
assertProvisionedCheckout(String workspaceDir) → void
Verifies that workspaceDir is a Git checkout after workspace provisioning.
classifyDualReadMiss(SessionProjection legacy, DateTime? firstEpochClaimedAt) → DualReadMiss
Classifies one miss against the station's first epoch claim.
closedGateCountKey(String nodePath, int structuralIncarnation) → String
Encodes one node path plus its supersedes-chain incarnation ordinal.
collapseStepCursors(Iterable<StepCursorView> rows) → Map<String, StepCursorView>
THE COLLAPSE RULE (r7 — V1-M5): one P2 row per step_path.
compareHeadToProjection(SessionProjection legacy, SessionHeadView head) → DualReadComparison
Compares the DERIVED tuple (isTerminal, humanHeld, completed, sessionId) on both sides, plus the pgid/pid presence pair and the compare-only work_terminal_reason column.
composeMountEligibility(List<MountEligibilityPredicate> engine, MountEligibilityPredicate? asset) → MountEligibilityPredicate
Composes the engine's own clauses with the station's composed predicate into the ONE predicate the mount boundary calls.
configuredBdTypeNames(Map<String, dynamic> typesEnvelope, {Iterable<String> fields = const <String>['custom_types']}) → Set<String>
Returns the configured bd type names in typesEnvelope.
crossLinkEdges(Iterable<CrossLink> links) → List<BlockEdge>
Maps links onto the shared enforcement's edge shape.
crossLinkExclusionClause(Map<String, String> frontierExclusionsByBeadId, Map<String, SessionProjection> sessionsByWorkBead) → MountEligibilityPredicate
Refuses a fresh bead held out by the join's active cross-link projection.
crossLinkTypeRefusal(Map<String, dynamic> typesEnvelope, {required String store}) → String?
The LOUD arming refusal for a state store that has not registered the link custom type, or null when it has.
cursorNodeAt(CircuitCursor cursor, String path) → NodeCursor
The NodeCursor at path, defaulting to a fresh pending cursor for a node that has never run.
cursorStateAt(CircuitCursor cursor, String path) → StepState
The StepState at path, defaulting to StepState.pending.
decodeNodePathKey(String encoded) → String
Decodes a encodeNodePathKey-encoded node path back to its raw form.
defaultBackoffFor(StepFailureClass failureClass, Backoff circuit) → Backoff
The backoff a failureClass gets when the capability declares none — the circuit's, except for infra, which keeps the wall-clock throttle schedule.
defaultExhaustionFor(CapabilityFailureKind kind) → ExhaustionBehavior
The exhaustion behaviour a kind gets when the capability declares none.
defaultProcessLeaseVendor(StationServices services, {StationTrajectoryRecorder? recorder}) → StationProcessLeaseVendor
The production ProcessLeaseVendor over services — the kernel-root provision (tg-h4u): the chokepoint writer as the sole grid.lease.* writer, stationProcessSpawner/stationProcessDispatcher as the process transport, StationBeadWriter.metadataOf as the breadcrumb reader (ADR-0002 Decision 1's named grid_engine ──► grid_runtime edge), and the station's adopt-liveness seam (absent ⇒ neverLive ⇒ never adopt — no-adopt-on-faith's offline posture, co-wired with the reconciler's AdoptProof at the live arm). The crash-restart lease sweep does NOT ride this seam: its kill gate is the caller-bound LeaseGroupLiveness the reconciler binds to its own real controller, so leaving adoption unarmed never blinds the sweep.
demotesStepState(StepState bead, StepState fold) → bool
MONOTONE NO-DEMOTION's predicate (§C4, adapted from F-B4 verbatim).
demotesTerminalFact(SessionProjection legacy, SessionHeadFacts facts) → bool
MONOTONIC TERMINALITY's predicate, stated generally (§0.3): isTerminal true→false, completed true→false and humanHeld true→false are demotions the overlay never performs. A P1 value that would demote a legacy terminal fact is a LAG SIGNAL, never a served decision.
depsSatisfied(Circuit circuit, CircuitStep step, CircuitCursor cursor, String nodePath, {required Circuit? circuitById(String circuitId)}) → bool
Whether every dependsOn of step resolves to a sibling's POSITIVE TERMINAL (M4-P1 §4 step 2). The barrier IS multiple deps; await-all is "not yet satisfied". Fail-closed on a dangling/unresolvable dep.
depTerminalPath(Circuit circuit, String nodePath, String depId, Circuit? circuitById(String circuitId)) → String?
Resolves the cursor path a dependsOn on depId is satisfied by — the dep's own path for a CapabilityStep, or its terminal-step descendant for a SubCircuitStep. Returns null (unsatisfiable, fail-closed) for a dangling dep id or an unresolvable sub-circuit.
dispatchableWorkClause({required bool resident}) → MountEligibilityPredicate
Refuses a bead whose issue type is not dispatchable by this substation.
driveListClause(Set<String> driveList) → MountEligibilityPredicate
Refuses a bead omitted from this substation's configured drive list.
driveProcessSession({required ProcessSession session, required Stream<RuntimeEvent> runtimeEvents, RuntimeEvent? retainedTerminal}) → Future<ProcessSessionUpdate>
Drives session until its first protocol or failure terminal.
effectiveStepCursor(SessionProjection session, {required CircuitCursor siteCursor, CircuitCursor? beadCursor}) → CircuitCursor
THE SHARED HELPER the cursor consumers adopt (§C4's effectiveCursor(session, stepBeads)).
eligibleSteps(Circuit circuit, CircuitCursor cursor, String nodePath, {required Circuit? circuitById(String circuitId), required DateTime now}) → List<CircuitStep>
The eligible frontier of circuit under cursor at nodePath — the steps that should currently be MOUNTED, in declaration order (M4-P1 §4 step 2).
encodeNodePathKey(String nodePath) → String
Encodes nodePath for use inside a bd metadata KEY (tg-6e4j).
expectsFoldStepRow(StepState bead) → bool
Can a fold row EXIST yet for a node whose bead carries bead?
firstBrokenNode(Circuit circuit, CircuitCursor cursor, String nodePath, {required Circuit? circuitById(String circuitId)}) → ({NodeCursor node, String nodePath})?
The FIRST circuit-broken node in circuit's subtree — its full nodePath plus its NodeCursor — mirroring isCircuitBrokenDeep's traversal (declaration order, depth-first). Null when nothing is broken.
foldAheadOfLegacyStep(StepState bead, StepState fold) → bool
Is fold STRICTLY LATER than bead on the step lifecycle's progress ordering (_stepProgress)?
foldBackedSessionProjection(SessionProjection legacy, SessionHeadView head, List<StepCursorView> rows) → SessionProjection
Builds the complete fold-backed carrier consumed by mount decisions.
harnessThrottleGateReason({required String sessionId, required String nodePath, required DateTime since, required int silentExits, required String exitOutputHead}) → String
Builds the gate reason written when the infra restart budget is spent.
harnessThrottleReason({required DateTime since, required int silentExits, required String exitOutputHead, required String underlying}) → String
Builds the durable failure reason for a silent harness exit.
harnessThrottleSince({required String? priorReason, required DateTime now}) → DateTime
Recovers the opening instant of a persisted throttle window.
isCircuitBroken(Circuit circuit, CircuitCursor cursor, String nodePath) → bool
Whether any step in circuit is circuit-broken (D-5) — an empty frontier that is "broken" (escalate + tear down), never "done". Shallow (this level only); isCircuitBrokenDeep descends into sub-circuits.
isCircuitBrokenDeep(Circuit circuit, CircuitCursor cursor, String nodePath, {required Circuit? circuitById(String circuitId)}) → bool
Whether circuit is broken ANYWHERE in its subtree (D-5) — a step at this level is circuit-broken, OR a nested sub-circuit is broken-deep. This is what SessionScope (the one lifecycle owner, D-2) checks to escalate + tear down, because a nested harness can exhaust its breaker BELOW the top circuit (the top-level isCircuitBroken would miss it). Fail-open on an unresolvable sub-circuit (it cannot be inspected, so it is not reported broken here — its own un-satisfied dep withholds whatever depends on it).
isCircuitComplete(Circuit circuit, CircuitCursor cursor, String nodePath, {required Circuit? circuitById(String circuitId)}) → bool
Whether circuit's terminal step reached a POSITIVE TERMINAL — the circuit is "done" (D-2: the session close fires; D-5: distinguishes empty-because-complete from empty-because-broken).
isDeliveryTerminal({required Circuit circuit, required String circuitPath, required String stepId, required String beadId}) → bool
Whether the step stepId of circuit (rooted at circuitPath) is the TERMINAL step of the ROOT circuit for beadId — the ONE node whose Advance ACTUATES delivery.
isHarnessSilence({required CapabilityFailureKind kind, required Duration? ranFor}) → bool
Whether a failure is a fast NON-RESULT rather than failed work.
isRetired(CircuitStep step, CircuitCursor cursor, String nodePath) → bool
Whether step is a completed StepKind.job — pruned from the frontier (M4-P1 §4 step 2). A daemon never completes; a sub-circuit is never retired (it stays mounted to keep its daemons alive until the parent tears down).
isRetiredWorkBeadKey(String workBeadKey) → bool
True when workBeadKey is a RETIRED session key — <bead>#rN or <bead>#void-<sessionId>.
isStepBroken(Circuit circuit, CircuitStep step, CircuitCursor cursor, String nodePath) → bool
Whether step failed AND exhausted its restart budget (the D-5 escalation term) — withheld from the frontier; its emptiness is "broken", never "done".
leaseGrantFromResultPayload(Map<String, String> payload) → LeaseGrant?
Reads a LeaseGrant back out of a step's recorded result payload (the read half of leaseGrantToResultPayload) — null when the payload carries no claim record (a locally-fulfilled step never writes these keys, or the step hasn't resolved yet). The returned grant's ttlSeconds/ heartbeatSeconds are 0 (unrecorded by design — see leaseGrantToResultPayload); a consumer needing the live cadence re-leases rather than reading it from this durable record.
leaseGrantToResultPayload(LeaseGrant grant) → Map<String, String>
The durable claim-recording contract (D-B5 hook #4) — bridges a granted LeaseGrant into the step-result payload a Capability's positive terminal (Ok/AllocationReady) already carries (ADR-0006 D3), so the EXISTING one bd write chokepoint durably records "who claimed this requirement" under the disjoint grid.result.<nodePath>.* namespace with NO new write path: a claim+lease Capability's dispatchOn (or a daemon's ready) returns Ok(leaseGrantToResultPayload(grant)) exactly like any other step recording a result (e.g. land's pr_url) — the SAME merged write the cursor's terminal transition already makes (the Host persists it off-build, invariant 2). Claim-in-own-store (A37): this never touches the foreign work bead, only the_grid's OWN session bead.
legacyFactsOf(SessionProjection legacy) → SessionHeadFacts
The legacy projection's own facts in the same three-field shape.
legacyStepCursorOf(SessionProjection session) → CircuitCursor
The BEAD-CARRIED cursor for session — the legacy truth on the step axis.
linkedSessionVerdictOf(Iterable<SessionProjection> linked) → LinkedSessionVerdict
The verdict for linked — pure, total, no I/O and no circuit. Orders internally, so a caller may pass rows in any order.
maxReworkRound(String beadId, Iterable<String> workBeadKeys) → int
The highest retired round on record for beadId across workBeadKeys (every session's work_bead value) — 0 when none has been retired. The next round is maxReworkRound(...) + 1.
mergeOperatorRulings(Map<String, Map<String, String>> stepResults, Map<String, Map<String, String>> sessionResults) → Map<String, Map<String, String>>
Overlays explicit session-level operator rulings on molecule step results.
mergeStepCursor({required String sessionId, required CircuitCursor legacy, required CircuitCursor? traj, Map<String, StepCursorView> collapsed = const <String, StepCursorView>{}}) → StepCursorMerge
THE MERGE — P2 over the bead-carried cursor for ONE session, with the three step-axis protections applied per node.
mountAttemptClause(Map<String, MountAttemptRecord> attempts) → MountEligibilityPredicate
The attempt-cap clause, closed over the in-memory attempts projection.
neverLive(AdoptFence fence) → bool
The offline liveness default — no OS controller wired, so nothing proves live, so an adoptable effect respawns fresh (no-adopt-on-faith). Public so the composer / StationServices can use it as the explicit "adopt disabled" value (the two adopt halves — this liveness seam and the reconciler's AdoptProof — must be co-wired; see AllocationContext.liveness).
nodeResultMetadata(String nodePath, Map<String, String>? payload) → Map<String, String>
The targeted metadata payload recording ONE node's step RESULT — the optional Ok.payload (e.g. the land step's {pr_url: …}) namespaced under ResultKeys so it merges alongside the node's terminal state=complete write without colliding with any cursor key. An empty/absent payload yields an empty map (nothing extra is written). Merge-safe (disjoint keys).
nonResultGateReason({required StepFailureClass failureClass, required String sessionId, required String nodePath, required int attempts, required String reason}) → String
The gate reason written when a NON-RESULT class spends its budget.
noWorkSignal(String workspaceDir) → Future<GateOutcome>
The offline work-signal default — nothing is wired, so nothing is fenced and an inferred completion is taken at face value (today's behavior). Public so the composer / StationServices can name the "fence disabled" value explicitly, like neverLive.
operatorRulingMetadata(String nodePath, {required String grade, required String rationale, required String evidenceSession}) → Map<String, String>
The metadata payload of an OPERATOR RULING on ONE lane node (tg-i08): the corrected grade + the kOperatorRulingTransport provenance + the rationale, namespaced under grid.result.<nodePath>. Written through the chokepoint on the_grid's OWN session bead — BEFORE the gate closes — so the route re-reads the corrected grade instead of the persisted fail-closed F (the I-14 loop where plain gate resolve re-gates seconds after re-arming). Merge-safe (disjoint per-node keys), like every other result write.
orderLinkedSessions(Iterable<SessionProjection> linked) → List<SessionProjection>
Orders linked so .first is the row the join publishes.
parseToolchainOs(String versionOutput) → String?
Extracts the OS token from a dart --version line's platform tag — e.g. ... on "macos_arm64" → macos — or null when none is recognized. Pure; the recognized OS names mirror Platform.operatingSystem.
pauseStateOf(Map<String, Object?> metadata) → SessionPauseState
Reads the operator pause axis from raw session-bead metadata.
projectCircuitResults(Bead sessionBead) → Map<String, Map<String, String>>
Projects every grid.result.* key on sessionBead into a per-node result map (the read half of nodeResultMetadata): grid.result.{encoded nodePath}.{field} → resultsfield, with the path segment decoded through decodeNodePathKey — so consumers (the cursor algebra, the SiblingView) always see RAW node paths. A historical bead's raw (pre-encoding) key decodes to itself (the decoder's leniency), so retired rounds keep projecting. Values are stringified; a malformed key (no field segment) is skipped.
Projects every OPEN type=link bead in state (the station's own state store) into a CrossLink.
projectMoleculeCursor(Iterable<Bead> moleculeBeads, {Iterable<BeadDependency> dependencies = const []}) → ({Map<String, String> beadIdByNodePath, CircuitCursor cursor})
projectMountAttempt(Bead bead) → MountAttemptRecord?
Projects a type=mount-attempt bead into its record, or null when the bead is not an attempt record or carries no join key (nothing to key on).
projectSession(Bead sessionBead) → SessionProjection
Projects a the_grid session Bead into the SessionProjection the tree joins against. The session bead's OWN status is the terminal signal (closed ⇒ terminal); the markers + legacy scalar process identity come from metadata.
projectSessionLedgerMetrics(GraphSnapshot snapshot) → SessionLedgerMetricsProjection
requireProcessLeaseVendor(TreeContext context) → ProcessLeaseVendor
LOUD-or-GONE (Decided item 5): resolves the ambient ProcessLeaseVendor, a process-backed CapabilityHost on the molecule path MUST consult before mounting — THROWING when none is provided rather than silently falling back to SelfManagedProcessVendor. That fallback is a real, usable vendor, but choosing it is the composer's decision to make explicitly (mount one), never this call's decision to make for them.
resolveFailureClass({required CapabilityFailureKind kind, required Duration? ranFor, bool kindDeclared = false}) → StepFailureClass
The durable class for a reported kind plus the host's ranFor evidence.
resolveRetryPolicy({required SupervisionPolicy declared, required CapabilityFailureKind kind, required StepFailureClass failureClass, required Backoff circuitBackoff, required int circuitMaxRestarts}) → ResolvedRetry
Resolves declared against the owning circuit's defaults for one failure.
resolveSessionOverlay(SessionProjection legacy, SessionHeadView head) → SessionOverlayResult
THE OVERLAY, resolved — sessionProjectionOverlay plus the reason.
rewindNodePaths(Circuit circuit, String circuitPath, Set<String> targetStepIds, {required String selfStepId, required Circuit? circuitById(String circuitId)}) → Set<String>
The full node-path set ONE Rewind resets (tg-o90): the named targetStepIds ∪ their transitive dependents ∪ the rewinding selfStepId, each expanded to its whole subtree.
reworkKeyFor(String beadId, int round) → String
The retired-round work_bead value for beadId at round (<beadId>#r<N>) — the ONE place the key shape is authored.
reworkKeyPattern(String beadId) → RegExp
Matches a RETIRED round's work_bead value for beadId exactly (^<beadId>#r(\d+)$) — anchored, so a DIFFERENT bead id that merely starts with beadId (tg-x1j2#r1 vs tg-x1j) is never mistaken for one of its rounds.
reworkRoundOf(String beadId, String workBeadKey) → int?
The round number encoded in workBeadKey for beadId, or null when workBeadKey is not one of beadId's retired rounds.
reworkVerdictEvidence({required Bead session, required Iterable<Bead> steps}) → ReworkVerdictEvidence
Classifies the durable evidence owned by one retired rework round.
sampleWedge(JoinedSnapshot snapshot, {required DateTime now}) → WedgeSample
Counts the station's forward progress over snapshot's LIVE sessions — pure, allocation-light, no I/O. now fences the cooling-down check.
servesFoldStepState(StepState bead, StepState fold) → bool
The merge's rule in ONE predicate: P2's state is served only when it neither demotes the bead nor promotes off a stale rung.
sessionCommitOnlyMetadata() → Map<String, String>
The metadata payload an unbound-delivery close writes through the same completion chokepoint as sessionCompleteMetadata.
sessionCompleteMetadata() → Map<String, String>
The metadata payload a delivered terminal close writes through the chokepoint IMMEDIATELY BEFORE bd close (I-10) — durable landing evidence the mount boundary reads. Merge-safe (one disjoint key).
sessionDispositionOf(SessionProjection? session) → SessionDisposition
Dispositions session — pure, total, no I/O and no circuit (the mount boundary has neither). Order matters: a human marker outranks everything, commit-only voids before either delivered evidence or the legacy cursor fallback, and only then does an in-flight cursor void the key.
sessionHeadEpochOf(SessionHeadView? view) → int
Returns view's fold epoch, or zero for no row or an older adapter.
sessionHeadFactsOf(SessionHeadView head) → SessionHeadFacts
Derives head into the legacy vocabulary — the table above.
sessionHeadWinnerOf(Iterable<SessionHeadView> rows) → SessionHeadWinner
THE WINNER RULE (§0.2, r3 form), pure and total over one bead's rows.
sessionProjectionOverlay(SessionProjection legacy, SessionHeadView head) → SessionProjection
THE OVERLAY (§0.3): legacy as BASE with head overriding exactly {isTerminal, completed, humanHeld, closedAt} — and nothing else.
sessionWorkTerminalMetadata() → Map<String, String>
spentReworkRounds(String beadId, Iterable<RetiredReworkRound> retiredRounds) → int
The matching retired rounds for beadId that spent verdict budget.
staleFences(SessionProjection session) → List<AdoptFence>
The process fences a VOIDED session still records.
staleRungPromotion(StepState bead, StepState fold) → bool
The step axis's OWN hazard, which the monotone rule alone cannot catch: a P2 state that looks like a PROMOTION but is a prior incarnation's row.
startedIdentityMetadata({required int? pgid, required int pid, required String token}) → Map<String, String>
The metadata payload stamped at SessionStarted (Track D): the process identity for respawn-or-skip + the freshness fence. All string-valued (bd update --metadata is Map<String, String>).
stationUnclaimedFrontier(JoinedSnapshot snapshot, {required RootCircuitFor rootCircuitFor, required CapabilityRegistry registry, required CapabilityFacts stationFacts}) → List<UnclaimedRequirement>
Aggregates unclaimedSteps across every LIVE (non-terminal) session in snapshot — the unit StationDriver computes once per reconciliation phase and hands to its onUnclaimedFrontier hook (D-B5 hook #1).
stepPath(String nodePath, String stepId) → String
The full path of stepId within a circuit rooted at nodePath ('$nodePath/$stepId', or just stepId at an empty root).
stepStateFromWire(String wire) → StepState?
The engine's StepState for a P2 state wire word, or null when the column carries something this engine has no state for.
subtreeNodePaths(String circuitPath, CircuitStep step, {required Circuit? circuitById(String circuitId), Set<String> ancestors = const {}}) → Set<String>
Every node path in step's subtree, rooted at circuitPath: the step's own path, plus — for a SubCircuitStep — every descendant node path (recursing through circuitById).
supersedesVerdictCountByPath(Iterable<Bead> moleculeBeads, Iterable<BeadDependency> dependencies) → Map<String, int>
Verdict-spending supersedes incarnations for each active step path.
trajCursorOf(Iterable<StepCursorView> sessionRows) → CircuitCursor
P2's own cursor for one session — the collapsed rows as NodeCursors.
trajectoryAdmissionHaltedClause({required bool halted}) → MountEligibilityPredicate
Refuses every fresh mount once trajectory decision evidence is unsafe.
trajectoryRecorderOf(TreeContext context) → StationTrajectoryRecorder
Resolves the ambient recorder for a derivation site, falling back to the counting no-op.
transitiveDependents(Circuit circuit, Set<String> stepIds) → Set<String>
The step ids of circuit that transitively DEPEND on any of stepIds — the downstream closure (stepIds themselves are NOT included). Fixed-point iteration, so it terminates on any graph (a cyclic dependsOn simply saturates).
truncateReason(String reason) → String
Truncates reason to kMaxReasonChars (capture-only telemetry is never allowed to grow unbounded, and never blocks a transition).
unclaimedSteps(Circuit circuit, CircuitCursor cursor, String nodePath, {required CapabilityFacts stationFacts, required Circuit? circuitById(String circuitId), required DateTime now}) → List<UnclaimedStep>
The UNCLAIMED subset of circuit's eligible frontier under cursor at nodePath (D-A3/D-B5 hook #1) — every CapabilityStep eligibleSteps would mount whose declared CapabilityStep.requires the stationFacts do NOT satisfy by containment (CapabilityFacts.matches, ADR-0011 D6). A step with no declared requirement (requires null or empty) is NEVER unclaimed — it always resolves locally (today's P1-only behavior, unchanged).
voidKeyFor(String beadId, String deadSessionId) → String
The VOIDED-session work_bead value (I-10, tg-4rw) — the key a DEAD session is retired to when the engine mints fresh over it (<beadId>#void-<deadSessionId>).
voidRetireMetadata({required String workBeadId, required String deadSessionId, required String reason}) → Map<String, String>
The metadata payload that RETIRES a VOIDED session's dead JOIN key (I-10) — the mechanized form of the operator's hand re-key (work_bead=tg-1di#void-i8), and the FOURTH (engine-automatic) member of A47's re-run taxonomy.

Typedefs

AllocationLiveness = bool Function(AdoptFence fence)
The engine's pgid-liveness half of the daemon adopt-freshness proof (ADR-0009 D4: "pgid alive"). Returns whether the process group at fence is STILL a live OS group — bound to a ProcessGroupController by the composer (live); the offline default is false (no controller ⇒ can't prove liveness ⇒ respawn fresh, no-adopt-on-faith). The domain-specific "token echoed over its endpoint" half is ProcessCapability.proveFreshness.
AllocationSink = void Function(AllocationReport report)
The emit-only channel an Allocation reports transitions through (ADR-0009 D5). The Host supplies a guarded closure that persists each report off-build through the chokepoint — NEVER a writer/notifier handed into the effect layer (invariant 2). Safe to call across async gaps: the Host's closure drops a report reaching an unmounted/cancelled node.
CircuitCursor = Map<String, NodeCursor>
A circuit's cursor: every inflated node's NodeCursor keyed by its full nodePath (e.g. tg-7r9/harnessPeripheral/build).
DualReadAppendStats = ({int appended, int deduped, int dropped, int queueDepth, int refusedTestimony, int suppressed})
The harness's append counters, as the round summary reports them (§0.4's "drops" field, C3's soak-gate arithmetic).
DualReadFlareSink = void Function(String name, Map<String, String> data)
The emit-only flare sink shape the engine already uses everywhere else.
DualReadMiss = ({DualReadMissClass era, bool nullStartedAt})
One miss's classification: its era plus whether the projection's startedAt was NULL.
DualReadSummarySink = void Function(String sessionId, String body)
Emits one durable round-summary note (§0.4) — AttemptNote REQUIRES a sessionId, so the vehicle is always keyed to a real session: the session that just reached its terminal, or (at the clean-down fixpoint) the LAST terminal session of the boot.
HeadSnapshotSubscribe = void Function() Function(void listener(TrajectoryHeadSnapshot snapshot))
Subscribes to the P1 mirror's published snapshots and returns the remover (house convention) — the headChanges seam that makes a fold-side fact re-join PROMPTLY instead of waiting for the next work/state emission.
ListBeadWorktrees = Future<List<BeadWorktree>?> Function(RootCheckout root)
The worktree-list seam: lists the per-bead worktrees under root, each re-bound to its bead id (the dir name encodes the id). Returns null on a probe error so the caller fails closed. Bound to the grid git service's listBeadWorktrees by the composing extension/runtime — injected as a narrow function so the engine never names the concrete VCS service (ADR-0007 §1 opinion-free kernel).
MountEligibilityPredicate = MountEligibilityDecision Function(Bead bead)
Decides whether bead is fit to mount at this reconciliation.
ReapWorktree = Future<ReapOutcome> Function({bool dryRun, bool overrideUnsafe, required RootCheckout root, required BeadWorktree worktree})
The reap seam: the three-gate fail-closed worktree remover. dryRun previews after running the same probes; overrideUnsafe permits only known present gates and never a scope or probe failure. Both default false so lifecycle and restart callers retain their automatic behavior.
ResolvedRetry = ({Backoff backoff, int maxRestarts, ExhaustionBehavior onExhaustion})
The schedule the host applies to one reported failure.
RetiredReworkRound = ({bool reachedVerdict, String workBeadKey})
One retired rework round and whether durable result metadata proves that its session reached a committee or route verdict.
ReworkVerdictEvidence = ({String? freeReason, bool reachedVerdict})
RootCircuitFor = Circuit Function(Bead bead)
Picks the root Circuit for a work bead — the bead→circuit policy (P1: all coding work → the code circuit; the Burn bead → the burn circuit). The composing extension supplies it (Track H); tests inject a fake.
StepSnapshotSubscribe = void Function() Function(void listener(TrajectoryStepSnapshot snapshot))
Subscribes to the P2 mirror's published snapshots and returns the remover (house convention) — the step axis's own re-join seam, spelled as a plain function type for the same reason HeadSnapshotSubscribe is (the mirror is explicitly not notifier state).
SweptGroup = ({String nodePath, int pgid, int pid, GroupTerminateResult result})
One process group a flat-model fence sweep walked: the node that recorded it, its pgid + leader pid, and the guarded terminateGroup outcome.
TerminalReconcileHealer = void Function(TerminalReconcileRequest request)
ToolchainQuery = Future<String?> Function(String executable)
Runs <executable> --version and returns its combined output, or null when the tool is absent / not runnable. Injectable into ToolchainProbe so tests need no real toolchain; the default runs a real local Process.run (offline — a local toolchain query touches no network).
WorkSignalProbe = Future<GateOutcome> Function(String workspaceDir)
The engine's WORK-SIGNAL seam: whether the workspace at workspaceDir still holds UNCOMMITTED work. The engine knows this in CONCEPT ("what a finished turn leaves behind"); the concrete probe is the COMPOSER's opinion — it binds this to its own source-control service (ADR-0008 D5: the engine names no VCS, and holds no worktree-layout opinion). Reuses GateOutcome so the fence inherits ADR-0006 D3's ratified fail-closed-on-probe-error posture verbatim.
WorkTerminalSettlementReport = ({String? failure, String sessionId, String terminalReason, String workBeadId})

Exceptions / Errors

CapabilityFailure
A typed failure a ProcessCapability's result / probeCompletionArtifact body may THROW to name its own failure kind.
FederationException
Base for every federation-protocol failure.
LeaseDeniedException
Thrown when a lessor REFUSES a lease (no capacity / not offered / the wait-queue is full or the wait expired) — the declare-and-check denial (HTTP 409).
LeaseInvalidException
Thrown when a lease handle is no longer usable: the id is unknown, the TTL or max-lifetime reaped it, or the dispatch/release carries a stale fencing token (HTTP 404/410). Fencing rejections surface here so a zombie holder of a reaped-then-reissued slot cannot act on it (ADR-0011 Hazards).
StationMintVoided
Signals that a freshly-created session was durably voided after its pour timed out. The caller records its existing Stage-1 observations and waits for the authority's invalidation instead of parking the retired session.