grid_sdk library

The public authoring surface of the grid — "the grid" as concrete code (GLOSSARY R9). A station is authored as a Seed: consumers compose this SDK's composition types and drive them with runGrid; they never import the private grid_engine (ADR-0008 Decision 2 — compose, never subclass).

The thesis: code as config

Just as the org went Dart-first before TOML, the grid goes code-first before configuration. A station is not configured by a value the framework interprets — it is built, as a tree, in Dart, by its author. Plain language features are the configuration language: an if mounts a substation, a for fans out, a watched value re-composes. GridConfiguration stays thin and subordinate; the tree IS the configuration.

See docs/SCRATCH-station-config-model.md (the ratified model, v3) and docs/GRID-SDK-BUILD-ORDER.md (the track breakdown).

Tracks B + C + D fill the authoring layer in (composition Seeds + runGrid/GridDelegate + stores-at-roots + the substation init flow). The remaining commented sections map the later tracks.

Classes

AlwaysApplies
The asset applies unconditionally.
AssetArgument
One declared argument of an AssetArtifact — the mustache-templated prompt argument of the Packaged AI Assets format (ADR-0008 Decision 2).
AssetArtifact
One delivery leg of a logical asset: a package-relative path delivered to target, with the arguments THAT leg declares.
AssetArtifactKey
One delivery leg's identity — the logical asset plus its target.
AssetKey
One logical asset's identity — the vending package, its kind, and the pack-unique id.
AssetSelector
WHEN an asset applies to a substation — a DECLARED predicate, never an evaluated one.
AttachedRoster
The runtime-attached roster as an observed tree value.
AttachedSubstations
Fans the runtime-attached roster out as keyed substation subtrees.
BoardFilter
How a board read narrows the projection. Clauses AND together; an empty or absent clause matches everything.
BoardRow
One board row: a bead, or a store that could not be projected.
Branch
Mounted, persistent node in the tree — the Element analogue.
CacheTokenTotals
Cache-token components retained for lossless projection merges.
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.
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).
ComponentBranch
A branch that composes by building a single child Seed — the ComponentElement analogue. Defines the rebuild hook as re-running build, so a config update re-runs the builder.
DiagnosticsBuilder
Collects properties supplied by a diagnostic hook.
DiagnosticsDoubleProperty
DiagnosticsDurationProperty
DiagnosticsEnumProperty
DiagnosticsFlagProperty
DiagnosticsIntProperty
DiagnosticsObjectProperty
DiagnosticsProperty
One typed, severity-bearing property on a diagnostics tree node.
DiagnosticsReferenceProperty
DiagnosticsStringProperty
DiagnosticsTimestampProperty
DoltStoreConnection
The StoreConnection over a pooled DoltQueryService.
DryRunProvider
The dry-run transport: records every would-be spawn, spawns nothing.
DryStationGitService
The dry-run StationGitService: inherits the no-op-runner worktree probe and overrides provisionWorktree so a dry run materializes NO worktree — it returns a synthetic descriptor the host ignores. PUBLIC so the effect posture is assertable by type: the dry-run inertness tests pin that dryRun: true (and only dryRun: true) selects THIS service.
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).
FalseFMetrics
GridAssetDefinition
ONE logical asset, declared as a const, keyed, INERT Seed.
GridAssetPackDefinition
One package's asset collection — the Dart half of a pack that carries a top-level grid: block and therefore publishes generated definitions (decision the_grid#grid-block-packages-publish-dart-asset-definitions, which updates ADR-0008 Decision 2's clause blessing "AI-only packages with no Dart code").
GridAssetRegistry
The station-wide collection of packs — every asset a station's composed packs vend, indexed by identity.
GridCommandHandler
A composable extension implemented by a running station.
GridCommandRequest
One operator command for the resident station.
GridCommandResult
The typed outcome consumed by the control-surface adapter.
GridConfiguration
The grid's configuration — a thin, plain value (Q6): plausibly nothing more than the result of TOML loading, provided into the tree like any other value. There is no domain/aspect machinery (no of<T>(), no addDomain) until a real consumer earns the first typed domain — the §2 pseudo's GridConfiguration.of<ButaneGridConfiguration> is aspirational, deliberately deferred (v3 §1/§6, "earn it").
GridDelegate
The station author's delegate — rails, not layers (v3 §4).
GridHandle
A running grid — the handle runGrid returns.
GridRoot
The grid's home — the root RawAssetGrid was authored with.
GridStateStore
The grid's state store location — one per grid (Q5a).
InheritedBranch<T extends Object>
Mounted branch for InheritedSeed. Owns the dependent set, reconciles the single child via the rebuild hook, and invalidates dependents through Branch.dependencyChanged when the value changes.
InheritedModelBranch<T extends Object, A extends Object>
Mounted branch for InheritedModelSeed: InheritedBranch plus per-dependent aspect bookkeeping. notifyDependents consults InheritedModelSeed.updateShouldNotifyDependent with the aspects each dependent asked for and invalidates only those it reports as affected.
InheritedModelSeed<T extends Object, A extends Object>
Provides an ambient value of type T whose dependents may subscribe to a single ASPECT of it — the InheritedModel analogue.
InheritedSeed<T extends Object>
Provides an ambient value of type T to all descendants in the tree — the InheritedWidget analogue.
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.
Key
A first-class identity token for a Seed, used by keyed reconciliation to pair a new configuration with an existing mounted Branch across rebuilds.
LandedDeliveryTotals
Landed-delivery components retained for lossless projection merges.
LedgerNodeMetrics
LedgerSessionMetrics
MetricsDecodeIssue
MultiChildBranch
Mounted branch for a MultiChildSeed: keyed-reconciles the seed's declared MultiChildSeed.children — the MultiChildRenderObjectElement analogue.
MultiChildSeed
A Seed that carries a fixed, ordered list of child seeds directly in its configuration — the MultiChildRenderObjectWidget analogue, and the multi-child sibling of the single-child component seeds (StatelessSeed/StatefulSeed/Sprout).
Nest
A Seed that stacks a list of SingleChildSeeds into a vertical chain, each wrapping the next down to a single leaf child — the generic Nested/MultiProvider shape, and the vertical sibling of MultiChildSeed's horizontal fan-out.
NestBranch
Mounted branch for a Nest: folds the declared chain into a spine of hook branches and keeps it reconciled.
NoOpBdRunner
The DRY-RUN bd seam: returns a canned envelope so the engine's session mint runs end-to-end, but issues no real bd and touches no store.
ObjectKey
A Key backed by the identity of value; equal only when both keys wrap the identical (identical) object.
ObligationAppend
One record a repair wants appended, with the envelope provenance that repair carries.
ObligationQuery
A standing query over the projections plus the repair it authorizes.
OrphanSweepReport
The immutable outcome of one RestartReconciler.sweepOrphans pass — enough to assert in a test and to log a one-line teardown summary.
Provider<T extends Object>
A MOUNTED SEED providing an ambient value of type T to its subtree.
ProviderScope
The AVAILABILITY REGISTRY — one per tree, near the station root.
RawAssetGrid
The raw grid root — the WidgetsApp-to-MaterialApp relationship (v3 §3): unopinionated, low-level. A batteries-included Grid analogue can layer on top later.
ReassembleBus
The OFF-TREE reassemble bus: runGrid holds it and hands it to the configuration scope BY CONSTRUCTION — exactly as it holds the delegate. It never rides the tree, so no consumer can snapshot its .state (ADR-0008 D-H); only the request it emits reaches the scope, through the listener.
ReassembleReport
What a dev-mode re-composition DID — returned by GridHandle.hotReload / GridHandle.hotRestart, and (as toJson) the value body of the reload tool's reply when successful. A post-source-swap tree failure is represented as a refused variant so the VM-service caller receives a structured refusal instead of an unhandled microtask error.
ReassembleReportRefused
A refused dev-mode re-composition after sources were already swapped.
ReassembleReportSuccess
A successful dev-mode re-composition report.
ReassembleRequest
A dev-mode reassemble REQUEST — what the running grid must re-do. Sealed, consumed with an exhaustive switch (house style).
ReloadRequest
Re-run the master build on the SAME delegate.
RequiresAll
Applies where EVERY one of selectors applies.
RequiresPackage
Applies where the substation's package graph contains packageName.
RequiresPath
Applies where relativePath exists under the substation root.
RestartReconciler
Reconciles the restart survivors (worktrees + owned session beads) into a respawn-or-skip plan, BEFORE the kernel re-mounts the tree.
RestartReport
RestartRequest
Re-run the delegate FACTORY: delegate replaces the running one, and its build re-composes the tree.
ResultMetricFields
ResultTransport
RosterOutcome
The typed outcome of one live-roster mutation.
RosterSeat
One runtime-attached substation seat in the appended roster layer.
RoundContext
One bead's current-round identity, or the typed statement that it has none.
Seed
Immutable configuration node — the Widget analogue: planted, describes what grows.
SessionHeadMirror
The mutable owner of the P1 mirror — the harness holds ONE.
SessionHeadRowView
One SessionHeadRow read as the engine's SessionHeadView.
SessionHeadSnapshot
One immutable, versioned read of the P1 mirror.
SessionLedgerMetricsProjection
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.
SingleChildSeed
Marker interface for a Seed that can slot into a Nest as a link — the single-child analogue of package:nested's SingleChildWidget.
SingleChildState<T extends SingleChildStatefulSeed>
Mutable state for a SingleChildStatefulSeed — a State that describes its subtree through buildWithChild, with the full initState/didChangeDependencies/setState/dispose lifecycle inherited.
SingleChildStatefulBranch
Mounted branch for a SingleChildStatefulSeed: a StatefulBranch — full State lifecycle inherited — that, inside a Nest, builds with the injected downstream instead of the seed's own child.
SingleChildStatefulSeed
A SingleChildSeed whose branch owns mutable SingleChildState — the single-child StatefulSeed, built directly on StatefulSeed.
SingleChildStatelessBranch
Mounted branch for a SingleChildStatelessSeed: a StatelessBranch that, inside a Nest, builds with the injected downstream instead of the seed's own child.
SingleChildStatelessSeed
A SingleChildSeed that composes purely from its own configuration — the single-child StatelessSeed, built directly on StatelessSeed.
Sprout
A Seed whose branch holds its state in hooks declared inline in build — the hooks-style alternative to StatefulSeed + State<T>.
SproutBranch
Mounted branch for a Sprout: a ComponentBranch that owns the persistent hook slots and dispatches hooks by call order.
SproutContext
The build-time hook-dispatch handle passed to Sprout.build.
StalenessClear
Every checkout fresh — proceed silently.
StalenessPosture
The staleness posture a station delegate chooses over the inspected primary-checkout freshness vector — a station opinion (relocated from the command's inline refusal, tg-1fa2.4), rendered by the shell.
StalenessRefused
Stale and refused: the shell writes message on stderr and exits 64.
StalenessWarned
Stale but accepted (--allow-stale): the shell warns with message on stderr and proceeds.
State<T extends StatefulSeed>
Mutable state owned by a StatefulBranch, with the initState/didChangeDependencies/build/dispose lifecycle.
StateCell<T>
A mutable state cell returned by SproutContext.useState. Setting value marks the owning branch for rebuild (the setState analogue).
StatefulBranch
Mounted branch for a StatefulSeed: creates and owns the State, drives its lifecycle, and delegates build to it.
StatefulSeed
A Seed whose branch owns mutable State — the StatefulWidget analogue.
StatelessBranch
Mounted branch for a StatelessSeed: delegates build to the seed.
StatelessSeed
A Seed that composes purely from its own configuration — the StatelessWidget analogue.
StateNotifier<T>
An observable class that stores a single immutable state.
StateStoreGc
Performs threshold-gated offline collection of the station state store.
Station
The machine (GLOSSARY: Station) — one runtime, one reconcile loop, one capacity budget.
StationAdmissionStatus
A read-only station admission snapshot for operator status surfaces.
StationCommandHandler
Executes operator mutations against the controllers owned by one station.
StationScope
The enclosing station's identity — the machine (GLOSSARY: Station).
StationView
The narrow status view a station delegate vends — the VALUES the command shell's banner, /status view, and dev-mode seat read. A view over the boot-assembled work machinery; never the runtime object wholesale.
StationWork
The STATION-scoped work asset (tg-yl8): provides the engine's ambient work-axis stack — StationWorkWiring's four values — to everything below, so each Substation's SubstationWork can mount the engine's WorkList INSIDE the runGrid tree ("each child Substation establishes its WorkList", v3 §3).
StationWorkRuntime
The runner-held OFF-tree work machinery assembleStationWork assembles — the v3 successor to the deleted StationSources/StationWiring/ TreeRunWiring boot path (H3), re-shaped for runGrid: the tree no longer rides a kernel-owned TreeOwner; it mounts inside the runGrid composition (StationWork/SubstationWork) while THIS object owns everything off-tree.
StationWorkRuntimeState
The immutable lifecycle of one StationWorkRuntime.
StationWorkWiring
The station-level work-axis wiring — the ambient VALUES StationWork provides to the work subtree (the stack mounted above the engine's Station seed, tg-yl8): the work-axis JoinedSnapshotNotifier, the machine's StationServices, the bead→work-Seed SessionResolver, the reentrant CapabilityRegistry, and the molecule model's ProcessLeaseVendor (tg-2mb — the seam a circuit's allocation resolves; without it a molecule step's requireProcessLeaseVendor throws at the readiness gate and the station wedges to zero).
StepCursorMirror
The mutable owner of the P2 mirror — the harness holds ONE.
StepCursorRowView
One StepCursorRow read as the engine's StepCursorView.
StepCursorSnapshot
One immutable, versioned read of the P2 mirror.
StoreConnection
One open store connection, named for the operator's shutdown narrative.
StoreLocator
Locates grid stores at roots — the discovery service (stateless I/O; the reference type carries the classifier).
Substation
A project (GLOSSARY: Substation) — a name and ONE root, never sets, never defaults (v3 §0). Its work store lives at <root>/.beads/ — a store lives at a root, uniformly (Q5a).
SubstationConfig
Operator-supplied appended substation identity (the append-only roster layer a station shell parses from --substation and hands to the delegate's arming policy).
SubstationDrain
The drain narrowing observed by SubstationWork.
SubstationInitializer
The substation initialization flow (Q-mig) as first-class code: given a root and a name, it seeds a new substation's work store at its root, adopts its prefix, and yields the substation to mount in the tree. Documented as a process in docs/SUBSTATION-INIT.md.
SubstationInitResult
The result of a successful substation initialization — the freshly-seeded project, ready to mount in the tree.
SubstationProvisioner
Owns the off-tree half of a live substation attachment.
SubstationRoster
The mutable runtime-appended substation roster.
SubstationRosterScope
Observes a roster and provides only its emitted value to the tree.
Substations
The substation fan-out (v3 §3): a MultiChildSeed whose children are the station's Substations — literal, composed (a seed that builds a Substation, never subclasses it — ADR-0008 D2), or conditional (if (kDebug) Substation(...)). Plain language features ARE the configuration language (v3 §1).
SubstationScope
The enclosing substation's identity — a project: a name and ONE root (v3 §0: never sets, never defaults). Its work store lives at <root>/.beads/ — a store lives at a root, uniformly (Q5a).
SubstationWork
The SUBSTATION-scoped work seat (tg-yl8): mounts the engine's WorkList for the enclosing Substation — the node H2's placeholder leaf held open.
SubstationWorkSpec
One substation's assembly identity — mirrors the Substation the author mounts (same name / ONE root / prefix axes), because the OFF-tree machinery (controllers, worktree roots) is built per store while the tree is built per scope; the runner derives both from one config.
SubstationWorkStore
A substation's work store location — at <root>/.beads/, uniformly (Q5a). A substation is a name + ONE root; its work lives in the store at that root. The store is expected exactly here — never discovered by walking up.
TrajectoryAppendRequest
One derived record awaiting the single writer (§2.5). Constructed by the engine-side derivation layer, never by the harness — the extraction boundary keeps record vocabulary out of the mechanics.
TrajectoryAppendResult
The completed disposition of a decision-bearing trajectory append.
TrajectoryConfig
The one parameter assembleStationWork gains at Stage 1 (§1.3).
TrajectoryHarness
The fenced service's station-side owner (stage1-wiring §1.1).
TrajectoryHarnessStatus
One status read — plain derived values for a runner's banner//status block (the rendering is a space_station edit, §1.1).
TrajectoryRecord
One trajectory record, pre-envelope: the typed fact plus the identity grammar. The service stamps everything else (§2.6 rule 7).
TrajectoryStoreConnection
The StoreConnection over a TrajectoryHarness's own sessions.
TrajectoryTick
Runs the derived-obligation queries on an interval and to fixpoint.
TrajectoryTickFixpoint
The result of driving the tick to fixpoint (§5's clean-down path).
TrajectoryTickPass
One tick pass, as a value.
TreeContext
Build-time capability handle into the tree — the BuildContext analogue minus the Element≡BuildContext "original sin".
TreeNode
One semantic node in a TreeSnapshot.
TreeOwner
Owns the root branch, holds the dirty set, and drives synchronous depth-ordered flushes — the BuildOwner.buildScope analogue.
TreeProjector
Projects the live semantic tree after completed kernel flushes.
TreeSnapshot
A complete versioned projection of the live diagnostics tree.
ValueKey<T>
A Key backed by a value of type T; equal when both the runtime type and the value are equal.
Watch<T>
Subscribes to source and rebuilds with each event — the Attention primitive: pure composition + dart:async with zero domain semantics.
WatchState<T>
State for Watch: holds the latest value and the stream subscription; each event flows through the setState analogue into a rebuild.
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).
WorkBeadKeys
The mirrored asset-owned work-bead metadata keys.
WorkCommandStore
The resident read/write rails for one substation work store.
ZombieReap
One ZOMBIE running-node a flat-model restart pass reaped.

Enums

AssetAudience
Who an asset is authored FOR — the closed audience vocabulary.
AssetDeliveryTarget
WHERE one leg of an asset is delivered — the closed delivery vocabulary.
AssetKind
What an asset IS — the closed kind vocabulary a pack declares against.
AssetVisibility
The open/closed split — visibility: public|private, adopted from the Packaged AI Assets format by ADR-0008 Decision 2.
DiagnosticsLevel
Display severity attached to every diagnostics property.
LedgerGrade
ReassembleMode
WHICH dev-mode re-composition ran.
ReferenceKind
Link target classifier for a DiagnosticsProperty.reference.
StationWorkStartStage
The operation a StationWorkRuntime is entering during its first start.
TrajectoryConfigMode
§1.3's arming mode. Whatever the mode, a trajectory failure NEVER blocks the boot — the mode only decides whether the harness tries, and how loud a degradation is.
TrajectoryDiscipline
The station-wide trajectory write/read discipline.
TrajectoryHarnessMode
The harness's posture — what /status renders and the failure table in stage1-wiring §3 maps to.
TrajectoryProvenance
provenance ENUM (§8 Q18).

Mixins

Diagnosticable
An object that describes its diagnostic properties.
DiagnosticableTree
A Diagnosticable that also describes an ordered child tree.
SingleChildBranchMixin
The branch-side capability that lets a SingleChildSeed's branch receive a downstream injected by an enclosing Nest — the analogue of nested's SingleChildWidgetElementMixin.

Extensions

BoardFilterPatterns on BoardFilter
Adds pattern-matching-related methods to BoardFilter.
BoardRowPatterns on BoardRow
Adds pattern-matching-related methods to BoardRow.
GridCommandRequestPatterns on GridCommandRequest
Adds pattern-matching-related methods to GridCommandRequest.
GridCommandResultPatterns on GridCommandResult
Adds pattern-matching-related methods to GridCommandResult.
GridConfigurationPatterns on GridConfiguration
Adds pattern-matching-related methods to GridConfiguration.
GridRootPatterns on GridRoot
Adds pattern-matching-related methods to GridRoot.
GridRootStores on GridRoot
Derives the GridStateStore from the ambient grid root (Track B's scope).
ProviderTreeContext on TreeContext
Adds nullable provider lookup verbs to TreeContext (ADR-0008 D3/D-H — two verbs, one lookup system).
RosterOutcomePatterns on RosterOutcome
Adds pattern-matching-related methods to RosterOutcome.
RoundContextPatterns on RoundContext
Adds pattern-matching-related methods to RoundContext.
StationScopePatterns on StationScope
Adds pattern-matching-related methods to StationScope.
StationWorkRuntimeStatePatterns on StationWorkRuntimeState
Adds pattern-matching-related methods to StationWorkRuntimeState.
SubstationScopePatterns on SubstationScope
Adds pattern-matching-related methods to SubstationScope.
SubstationScopeStores on SubstationScope
Derives the SubstationWorkStore from the ambient substation scope.

Constants

copyWithAbsent → const Object
kDefaultShutdownDrainTimeout → const Duration
The bound on the clean-down drain (r2 major 9, hardened): "trajectory shutdown NEVER blocks sources shutdown" covers hangs as well as throws — a dead/half-open dolt socket can wedge the drain's SQL awaits forever, and an unbounded await there would hold down hostage. On expiry the remainder is counted + flared and shutdown proceeds to dispose; the successor boot's shadow-diff attributes the loss as the named non-atomic class.
kDefaultSyncFloorInterval → const Duration
Assembles the station's off-tree work machinery over REAL stores at their roots — the v3 replacement for the deleted buildControllers + buildLiveWiring + composeStation assembly (H3), consumed by every runner (space up) so a station author never imports the private engine (ADR-0008 D2).
kDefaultTrajectoryGcInterval → const Duration
The gc cadence (stage1-wiring §1.2 / M2): CALL DOLT_GC() every 5 minutes caps the working set; online, no quiesced window, never bd's proxy.
kDefaultTrajectoryQueueBound → const int
§2.5's append-queue bound: past it an incoming append is dropped and counted, never blocked on.
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.
kGridRuntimeDirName → const String
The runtime dir name under a grid root — holds the grid's STATE store and the station lock (Q5a: state lives under <grid.root>/.grid/…).
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.
kReconnectDebounce → const Duration
The floor between eager-reconnect ATTEMPTS (§3's AppendInternalError row, hardened): the reconnect stays eager — the first append after a failure tries — but with the server down and a filled queue, retrying the whole resolve+dial per queued record would storm the filesystem and the dead listener up to queueBound times per drain. Appends inside the window drop-and-count exactly like a failed reconnect.
kStateStoreGcThresholdBytes → const int
State-store databases larger than this are collected before a live boot.
kStationLockFileName → const String
The station lock file — one supervisor per station STATE store (D-A1). It colocates with the grid state store inside <grid.root>/.grid/.
kTrajectoryDatabase → const String
The one database the harness dials — CREATE DATABASE trajectory beside the ledger database (runbook step 2).
kWorkStoreDirName → const String
The store dir name at a root — .beads/ means work store, uniformly, everywhere (Q5a). A substation's work store is <root>/.beads/; the grid's own state store nests one under .grid/ (<grid.root>/.grid/.beads/) so the dual-role repo never collides its work store with its state store.

Functions

assembleStationWork({required GridStateStore stateStore, required List<SubstationWorkSpec> substations, required SessionResolver resolver, required bool dryRun, CapabilityRegistry? registry, CapabilityRegistryBuilder? registryBuilder, CapabilityRegistry registryBuilderWithSpecWriter(WorkNoteAppender appendWorkNote, SpecifyAuthoredSpecWriter writeSpecifyAuthoredSpec)?, int maxConcurrentWork = kDefaultMaxConcurrentWork, bool preferSql = true, RuntimeProvider? providerOverride, StationGitService? gitOverride, BdCliService? stateBdOverride, Map<String, BdCliService> workBdOverrides = const {}, ProcessGroupController? groupsOverride, void onRefusal(String message)?, void onOrphan(String message)?, void onUnresolvedExternalDep(String message)?, ExplorationTransport? transport, Duration wedgeThreshold = kDefaultWedgeThreshold, Duration wedgePollInterval = kDefaultWedgePollInterval, Duration syncFloorInterval = kDefaultSyncFloorInterval, TrajectoryConfig trajectoryConfig = const TrajectoryConfig(), TrajectoryHarness? trajectoryOverride, StationWorkBundleBuilder? bundleBuilder, StationWorkFederatedSourceBuilder? federatedSourceBuilder, StationWorkJoinBridgeBuilder? joinBridgeBuilder, StationWorkDriverBuilder? driverBuilder}) → Future<StationWorkRuntime>
beadMetadataText(Bead bead, String key) → String?
bead's metadata value at key when it is a non-blank String, else null.
buildDryStationGitService() → StationGitService
The INERT git service for dry-run — a no-op git (every invocation an empty success) so listBeadWorktrees parses an empty worktree set WITHOUT executing a real git, the restart reconcile finds no survivors, and provisionWorktree materializes NOTHING. Exposed for the inertness regression tests.
checkedEnum<T extends Enum>(List<T> values, String wireValue, String key) → T
checkedJsonDateTime(Map<String, Object?> json, String key) → DateTime
checkedJsonList(Map<String, Object?> json, String key) → List<Object?>
checkedJsonMap(Map<String, Object?> json, String key) → Map<String, Object?>
checkedJsonMapValue(Object? value, String key) → Map<String, Object?>
checkedJsonNullableValue<T>(Map<String, Object?> json, String key) → T?
checkedJsonValue<T>(Map<String, Object?> json, String key) → T
defaultBeadStoreSeeder({required String root, required String prefix}) → Future<void>
The real seeder: bd init --prefix <prefix> in root. Throws on a non-zero exit (LOUD — a failed seed must never look like a seeded store).
defaultDirectoryProbe(String path) → bool
The real directory-existence probe.
droppedReapReports(RestartReport report) → List<String>
The LOUD lines a restart pass's DROPPED zombie reaps produce.
droppedWorkTerminalSettlementReports(RestartReport report) → List<String>
ghRunner(String workDir, List<String> args) → Future<GitRunResult>
Execs gh for a delivery method's PR opener (inherits the parent env so gh finds its own auth).
listEquals<T>(List<T> left, List<T> right) → bool
liveWorkBeadsFor(SubstationWorkSpec spec, GraphSnapshot state) → Set<String>
Returns open-session work beads owned by spec, stripping rework rounds.
orderedStoreConnections({required DoltQueryService? state, required Map<String, DoltQueryService?> work, TrajectoryHarness? trajectory}) → List<StoreConnection>
Orders a station's open store connections for shutdown: the state store first (it is the last writer — the session/cursor beads land there), then the trajectory harness's own sessions (the same server, the other writer), then each work store by name for a deterministic narrative. A store on the CLI read path opened no socket (GridRuntimeBundle.dolt is null) and contributes no connection.
projectBoard({required String store, required String root, required GraphSnapshot snapshot, BoardFilter filter = const BoardFilter(), Map<String, Iterable<String>> linkBlockersByBeadId = const {}}) → List<BoardRow>
Projects snapshot into board rows for the store named store at root.
projectRoundContext({required Bead workBead, required Iterable<Bead> stateBeads}) → RoundContext
Joins workBead to its live session among stateBeads.
projectSessionLedgerMetrics(GraphSnapshot snapshot) → SessionLedgerMetricsProjection
requireAbsoluteRoot(String root, String owner) → String
Validates a root path is a non-empty ABSOLUTE path, LOUD (release-safe).
runGrid(GridDelegate delegate, {void onError(GridHookError refusal)?, Future<void> maintainStateStore({required String gridHome})?, void onFlushed()?, TreeProjector? treeProjector, Future<void> orphanSweep()?, GridDelegate delegateFactory()?, void onDelegateSwapped(GridDelegate next)?, Timer scheduleTimer(Duration, void ())?}) → Future<GridHandle>
Launches a grid from delegate — the entry point (v3 §4 / GLOSSARY R15: the delegation pattern's runGrid(delegate)). The framework root is final; all station behaviour enters through the delegate.
runWithGridErrorAttribution<T>({String? nodePath, String? stepId, required T body()}) → T
Runs body in a child zone carrying mounted-grid error attribution.
sessionClosureOf(Bead bead) → SessionClosure?
The closure of bead as the ledger records it, or null when the bead is open (a live round — nothing to heal). The caller decides whether bead is a session bead; this reads only the session-bead schema.
settle(String step, FutureOr<void> action(), {Duration? within, void onRefusal(String message)?}) → Future<bool>
Runs one named teardown action without letting its failure abort unwind.
stationWorkSignal(StationGitService git) → WorkSignalProbe
The station's WORK-SIGNAL probe — the live binding of the engine's COMPLETION FENCE.

Typedefs

AttachedSubstationBuilder = Seed Function(RosterSeat seat)
Builds the substation subtree for one attached seat.
BeadStoreSeeder = Future<void> Function({required String prefix, required String root})
Seeds a fresh beads work store at root whose id-prefix is prefix — the injected primitive behind the substation initialization flow (Fakes, not mocks). The default (defaultBeadStoreSeeder) shells out to bd init --prefix <prefix>.
CapabilityRegistryBuilder = CapabilityRegistry Function(WorkNoteAppender appendWorkNote)
Builds a station capability registry over its owned appendWorkNote seam.
DirectoryProbe = bool Function(String path)
Probes directory existence — the injected filesystem seam (Fakes, not mocks) that keeps store discovery pure and offline-testable. The default (defaultDirectoryProbe) is a real dart:io check.
DirectorySizeReader = Future<int> Function(String path)
Dispose = void Function()
A cleanup callback returned by a SproutContext.useEffect effect, run before the effect re-runs and on unmount.
ErrorListener = void Function(Object error, StackTrace? stackTrace)
A callback that can be passed to StateNotifier.onError.
InFlightProbe = Set<String> Function(SubstationWorkSpec spec)
Answers "which of spec's work beads still carry a live session".
InFlightProbeResolver = Future<InFlightProbe?> Function()
Produces an InFlightProbe against a FRESH read of the state store, or null when no snapshot is available.
Listener<T> = void Function(T state)
A listener that can be added to a StateNotifier using StateNotifier.addListener.
MaintenanceClock = DateTime Function()
MaintenanceProcessRunner = Future<ProcessResult> Function(String executable, List<String> arguments, {required String workingDirectory})
MaintenanceSink = void Function(String message)
ProviderCreate<T extends Object> = T Function(TreeContext context)
Creates the value a Provider OWNS, from ambient tree state.
ProviderDispose<T extends Object> = void Function(T value)
Disposes a value a Provider CREATED.
RemoveListener = void Function()
A callback that can be used to remove a listener added with StateNotifier.addListener.
SpecifyAuthoredSpecWriter = Future<void> Function(String beadId, {required String acceptanceCriteria, required String design})
Writes SPECIFY-authored prose to the owned work bead identified by beadId.
StationWorkBundleBuilder = Future<GridRuntimeBundle> Function({required Future<GridRuntimeBundle> buildDefault(), required String storeName, required BeadsWorkspace workspace})
Builds one initial station work or state runtime bundle.
StationWorkDriverBuilder = StationDriver Function({required StationDriver buildDefault()})
Builds the station driver around a lazy production default.
StationWorkFederatedSourceBuilder = FederatedSnapshotSource Function({required FederatedSnapshotSource buildDefault()})
Builds the initial federated work source around a lazy production default.
StationWorkJoinBridgeBuilder = StationJoinBridge Function({required StationJoinBridge buildDefault()})
Builds the station join bridge around a lazy production default.
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.
TrajectoryAdmissionHaltCallback = void Function({required String reason, required String recordClass})
Synchronously latches the station's cut-only admission breaker.
TrajectoryFlare = void Function(String name, Map<String, String> data)
The flare seam — shape-compatible with ExplorationTransport.flare.
VoidCallback = void Function()
Signature for argument-free callbacks.
WorkNoteAppender = Future<void> Function(String beadId, String line)
Appends line to the owned lifecycle bead identified by beadId.
WorkTerminalSettlementReport = ({String? failure, String sessionId, String terminalReason, String workBeadId})

Exceptions / Errors

CheckedFromJsonException
A loud failure while decoding the diagnostics wire contract.
CutPostureRefused
A cut boot whose explicitly requested posture contradicts the cut.
GridHookError
A lifecycle-rail failure, captured and attributed — which hook threw, on which delegateType — so it surfaces as a named refusal, never a bare stack trace from library plumbing (v3 §4; the guard principle: loud when an invariant is violated).
StationRefusal
A composition-time refusal (a live lock holder, a lost steal race, an unarmable roster) — the runner prints message and exits with code. The one arming gate the station shell and the delegate's roster resolution throw (the old station_runner assembly that also raised it is deleted; the boot path moved to the asset's own runner + runGrid).
StationWorkStartRefused
A repeated start refused because the first start permanently failed.
StoreRefusal
Raised when a required store is absent (or misplaced) at a root — a LOUD boot refusal, never a silent default (the guard principle: LOUD or gone).