testing library

Public testing-support library for grid_engine.

The reusable, engine-only Fakes (not mocks) the offline suite drives the reactive kernel with — a controllable FakeRuntimeProvider, the recording bd-write chokepoint (RecordingBdRunner/GatedCreateBdRunner), the land ops (RecordingGitRunner/FakePrOpener), the observable FakeSnapshotSource, the buildFakes/bead/sessionBead builders, and the reentrant inflater fakes (RecordingCapabilityRegistry/FakeCapabilityHost). Promoted to a public library so downstream asset packages (grid_assets) reuse the SAME fakes — the cross-package enabler for the opinion extraction (ADR-0007 §1).

The code-asset-specific helpers (kCodeResolver, the code circuit) are NOT here — they reference the moved opinions and live in grid_assets's test support. Pure-Dart: no live tg/gc/claude/git/network.

Classes

EmptyBeadProbeReader

Empty lifecycle reader for mutation-only fixtures.

FakeCapabilityHost

A recording fake leaf (NOT the real CapabilityHost): records its mount / unmount with its capabilityId, session, and path, and is a pure Idle leaf.

FakePrOpener

A recording PrOpener: records every open call and returns a settable PullRequestResult (success with a configurable url, or a failure). Never touches real GitHub.

FakeRuntimeProvider

Records start/stop calls and exposes a controllable events stream so a test emits SessionStarted/Exited/Died on demand. Only the members the effect touches are meaningful; the rest are honest no-ops over an empty surface.

FakeSnapshotSource

A fake SnapshotSource: a broadcast StreamController the test pushes through, plus a settable current (mirroring the real runtime's last-emitted accessor). push updates current AND emits, 1:1, like the change-gated runtime.

FakeTreeContext

A fake TreeContext for driving an Allocation/Capability bare — no mounted tree. Ambient values resolve from values by EXACT type (mirroring genesis's exact-type inherited lookup). Flip mounted to false to exercise the loud async-gap protection (getInheritedSeedOfExactType then throws, like the real handle).

FixedRouteCapability

A RouteCapability that returns a FIXED verdict — the offline route stand-in every routing test drives the router with.

GatedCreateBdRunner

A BdRunner whose create parks until releaseCreate is called, so a test can drive a dispose into the middle of the async mint.

RecordingBdRunner

A recording BdRunner (the grid_runtime fake shape): records full argv + stdin so a test asserts the EXACT bd commands, and create returns a caller-controlled synthetic id so the mint+stamp is exercised with no real bd.

RecordingCapabilityRegistry

A recording CapabilityRegistry: host mounts a fake leaf that records START/STOP <capabilityId>(<sessionId>/<nodePath>) so a test asserts the inflation frontier AND the disjoint per-session routing; circuit resolves from circuits; now is a fixed clock.

RecordingDeliveryMethod

A recording DeliveryMethod: records every request and returns a settable StepOutcome. Set throwNext to prove the throwing-delivery → supervision path. Delivers nothing anywhere.

RecordingEscalationHandler

A recording EscalationHandler: records every escalation and returns a settable EscalationDecision (default: park, like HumanGate).

RecordingExplorationTransport

Records ExplorationTransport.flare calls for offline tests.

RecordingGitRunner

A recording GitRunner: records every git argv (with its cwd) in order, and returns a configurable result so commit/push read ok. Wrap it in the real GitOps so the land step's real add -A / commit -m / push -u argv is what gets recorded (Fakes, not mocks).

Constants

stateSubstation → const String

The_grid's owned state substation in the offline fakes.

Functions

advancingClock({DateTime? from, Duration step = const Duration(seconds: 1)}) → DateTime Function()

A monotonically ADVANCING clock (FT-1, tg-pez) — each call returns the next instant step apart, starting at from (default DateTime(2026)). Feed to RecordingCapabilityRegistry.new's nowFn so the host's kick and terminal read DISTINCT instants, proving startedAt < finishedAt and a deterministic durationMs (the first two now() calls of a clean transition are step apart).

bead(String id) → Bead

An open task bead with id.

buildFakes({String createdId = 'tgdog-sess1', WorkSignalProbe? workSignal}) → Fakes

Builds an StationServices over the fakes (the chokepoint writes through a recording bd runner; the transport is a controllable provider; land is wired to the recording git/PR ops) and returns it with the recorders.

sessionBead({required String id, required String workBeadId, bool closed = false, bool outcomeComplete = false, bool escalated = false, Map<String, String> metadata = const {}}) → Bead

A type=session state bead linking workBeadId — the row the join bridge projects + keys by work_bead, carrying the OWNED substation marker (the persisted metadata.rig key — codec law; so the chokepoint's ownership re-check passes) + the I-10 closed-session shapes (the engine's own DONE evidence via outcomeComplete, a HUMAN marker via escalated).

stepArgs(String nodePath, {Map<String, String> params = const {}, CancelToken? cancel}) → StepArgs

StepArgs for a bare-driven capability/allocation (a fresh CancelToken unless one is injected).

testWorkspace(String beadId, {String? workspaceDir, String branch = '', String baseBranch = 'main'}) → Workspace

A Workspace for a bare-driven test (the synthetic offline shape SessionScope mounts when no source control is wired).

Typedefs

Fakes = ({StationServices ctx, RecordingGitRunner git, FakePrOpener pr, FakeRuntimeProvider provider, RecordingBdRunner runner})

A bundle of an StationServices over the fakes plus the recording collaborators the test asserts against.