@tangle-network/agent-runtime 0.44.0 → 0.46.0

package/dist/runtime.d.ts

@@ -0,0 +1,1964 @@
+import { AgentProfile as AgentProfile$1, BackendType, CreateSandboxOptions, SandboxInstance, SandboxEvent } from '@tangle-network/sandbox';
+export { AgentProfile, CreateSandboxOptions, SandboxEvent, SandboxInstance } from '@tangle-network/sandbox';
+import { R as ResultBlobStore, a as SpawnJournal, N as NodeId, b as SpawnEvent, T as TreeView, c as Settled, E as ExecutorFactory, d as AgentSpec, e as ExecutorRegistry, B as Budget, A as Agent, f as RootHandle, g as SupervisedResult, h as Spend, S as Scope, U as UsageEvent, i as Supervisor } from './types-BfoeiQRZ.js';
+export { j as Executor, k as ExecutorContext, l as ExecutorResult, H as Handle, m as NodeSnapshot, n as NodeStatus, o as Restart, p as RootSignal, q as Runtime, r as SpawnOpts, s as SupervisorOpts, W as WidenGate } from './types-BfoeiQRZ.js';
+export { A as AnalyzeInput, a as CompletionAnalyst, b as CompletionEvidence, c as CompletionPolicy, d as CompletionVerdict, C as CreateDriverOptions, D as DriverDecision, P as PlannerContext, e as TopologyMove, T as TopologyPlanner, f as completionAuthorizes, g as createDriver, h as deterministicCompletion, r as renderAnalyses, s as sentinelCompletion, i as stopSentinel } from './driver-C-mtBo7h.js';
+import { S as SandboxClient, b as LoopResult, c as LoopTokenUsage, R as RuntimeStreamEvent, A as AgentRunSpec, E as ExecCtx, I as Iteration } from './types-DnYoHvvZ.js';
+export { D as Driver, C as LoopDecisionPayload, F as LoopEndedPayload, G as LoopIterationDispatchPayload, H as LoopIterationEndedPayload, J as LoopIterationStartedPayload, a as LoopLineageOptions, M as LoopPlanDescription, N as LoopPlanPayload, f as LoopSandboxPlacement, P as LoopStartedPayload, Q as LoopTeardownFailedPayload, e as LoopTraceEmitter, T as LoopTraceEvent, L as LoopWinner, O as OutputAdapter, U as ValidationCtx, V as Validator } from './types-DnYoHvvZ.js';
+import { AgentProfile, AnalystFinding, DefaultVerdict } from '@tangle-network/agent-eval';
+export { DefaultVerdict } from '@tangle-network/agent-eval';
+import { Scenario, ProfileDispatchFn } from '@tangle-network/agent-eval/campaign';
+import { R as RunLoopOptions } from './run-loop-CU2Y00Si.js';
+export { c as createSandboxForSpec, d as defaultSelectWinner, r as runLoop } from './run-loop-CU2Y00Si.js';
+import { R as RuntimeHooks } from './runtime-hooks-C7JwKb9E.js';
+
+/**
+ * @experimental
+ *
+ * Event-sourced spawn journal for the recursive execution atom (build steps 3 + 7).
+ *
+ * The supervision tree is journaled as an append-only event log: every `spawned`,
+ * `settled`, and `cancelled` is recorded AFTER it is observed-committed (never
+ * speculative), mirroring `ConversationJournal`'s begin/append/load shape. The log
+ * holds only the THIN decision record — ids, parentage, budget, the spend a decision
+ * consumed, and a content-addressed `outRef`. The payloads the driver branched on
+ * (the `out` artifacts) live in a separate `ResultBlobStore`, keyed by `outRef`, so
+ * the journal stays small (decisions) and replay rehydrates the exact `Settled` from
+ * the blob store (evidence). This is the decision/payload split the replay argument
+ * rests on (B1/B2).
+ *
+ * Replay determinism (B2): `seq` is the monotonic cursor order `scope.next()` yielded
+ * each settlement — NOT wall-clock. `replaySpawnTree` sorts strictly by `seq` before
+ * touching the blob store, so the order in which rehydration `get`s resolve can never
+ * reorder the replayed `Settled[]`; the result is identical regardless of blob latency.
+ */
+
+/**
+ * Mint the content-addressed `outRef` for a result artifact: `sha256:<hex>` over a
+ * stable JSON encoding. Producers call this to derive the `outRef` they journal and
+ * `put`; the FS/in-mem stores re-derive it on `put` to verify the supplied ref
+ * matches (fail loud on a mismatch — a forged ref breaks the replay invariant).
+ *
+ * Stable encoding: object keys are sorted recursively so two structurally-equal
+ * artifacts hash identically regardless of key insertion order.
+ */
+declare function contentAddress(artifact: unknown): string;
+/**
+ * In-memory `ResultBlobStore`. Content-addressed: `put` verifies the supplied
+ * `outRef` matches the artifact's hash so a stale/forged ref fails loud rather than
+ * silently rehydrating the wrong payload. Idempotent on an identical re-put.
+ */
+declare class InMemoryResultBlobStore implements ResultBlobStore {
+    private readonly blobs;
+    put(outRef: string, artifact: unknown): Promise<void>;
+    get(outRef: string): Promise<unknown | undefined>;
+}
+/**
+ * FS `ResultBlobStore`. One JSON file per artifact under `dir`, named by a
+ * filesystem-safe encoding of the `outRef` (`sha256:<hex>` → `sha256-<hex>.json`).
+ * `put` fsyncs so a crash between writes never loses an acknowledged blob.
+ */
+declare class FileResultBlobStore implements ResultBlobStore {
+    private readonly dir;
+    constructor(dir: string);
+    put(outRef: string, artifact: unknown): Promise<void>;
+    get(outRef: string): Promise<unknown | undefined>;
+    private blobPath;
+}
+/**
+ * In-memory `SpawnJournal`. Appends are observed-committed only; the impl enforces
+ * the corruption guards a durable replay rests on:
+ *  - an event before `beginTree` is a corrupted tree (fail loud),
+ *  - a duplicate `seq` within a tree is a corrupted cursor (fail loud) — two
+ *    settlements cannot share the cursor position replay orders by.
+ */
+declare class InMemorySpawnJournal implements SpawnJournal {
+    private readonly trees;
+    loadTree(root: NodeId): Promise<SpawnEvent[] | undefined>;
+    beginTree(root: NodeId, at: string): Promise<void>;
+    appendEvent(root: NodeId, ev: SpawnEvent): Promise<void>;
+}
+/**
+ * JSONL on disk. One line per record: the first record is `begin`, subsequent records
+ * are `event` envelopes wrapping a `SpawnEvent`. `loadTree` replays the whole file,
+ * filtering by `root`, and applies the same begin-precedes-events + unique-seq
+ * corruption guards as the in-memory impl. Each append fsyncs so a crash between
+ * writes never loses an acknowledged event.
+ */
+declare class FileSpawnJournal implements SpawnJournal {
+    private readonly path;
+    constructor(path: string);
+    loadTree(root: NodeId): Promise<SpawnEvent[] | undefined>;
+    beginTree(root: NodeId, at: string): Promise<void>;
+    appendEvent(root: NodeId, ev: SpawnEvent): Promise<void>;
+    private loadTreeBegin;
+    private appendRecord;
+}
+/**
+ * Re-feed a journaled spawn tree in strict `seq` order, rehydrating each settled
+ * child's `out` from the blob store by `outRef`, and return the `Settled[]` exactly
+ * as `scope.next()` originally delivered them.
+ *
+ * Determinism (B2): the events are sorted by `seq` BEFORE any blob `get`, so the
+ * replay order is the recorded cursor order regardless of how fast each rehydration
+ * resolves. `at` (wall-clock) is never a replay input. Fail loud on a tree that was
+ * never begun, a settled-done event missing its `outRef`, or a blob the store can't
+ * rehydrate — a silent gap would let `act` branch on the wrong evidence.
+ */
+declare function replaySpawnTree(journal: SpawnJournal, blobs: ResultBlobStore, root: NodeId): Promise<Settled<unknown>[]>;
+/**
+ * Materialize the live tree (`TreeView`) from a journaled event list for resume. Folds
+ * `spawned`/`settled`/`cancelled` into a per-node snapshot in `seq` order so the
+ * resumed view matches what `scope.view` showed at the recorded cursor position.
+ */
+declare function materializeTreeView(events: SpawnEvent[]): TreeView;
+
+/**
+ * Adapt an `ExecutorFactory` into a `SandboxClient` for `runLoop`. The factory is
+ * instantiated fresh per `streamPrompt` (mirrors the per-spawn executor lifecycle):
+ * run once on the prompt, emit the terminal result event, tear down.
+ */
+declare function inlineSandboxClient(factory: ExecutorFactory<unknown>): SandboxClient;
+
+/**
+ * `loopDispatch` — turn `runLoop` into an agent-eval campaign dispatch.
+ *
+ * Without this adapter a consumer wiring `runLoop` into `runProfileMatrix` /
+ * `runCampaign` has to, by hand, every time: (a) build an `ExecCtx` with a
+ * sandbox client, (b) adapt the campaign `DispatchContext.trace` into a
+ * `LoopTraceEmitter` (or lose all loop trace correlation), and (c) remember to
+ * forward the loop's cost + tokens via `ctx.cost` (forgetting it yields a
+ * `{0,0}` cell the backend-integrity guard reads as a stub). Three foot-guns,
+ * the third silent. The fleet's products skipped (c) and fell back to a
+ * `workerRecords[]` side-channel — the exact anti-pattern the substrate exists
+ * to kill.
+ *
+ * `loopDispatch` collapses all three into one typed call:
+ *
+ *   const dispatch = loopDispatch({
+ *     sandboxClient,
+ *     toLoopOptions: (scenario, profile) => ({ driver, agentRun, output, validator, task }),
+ *   })
+ *   await runProfileMatrix({ profiles, scenarios, dispatch, judges, commitSha })
+ *
+ * Usage is reported automatically; trace events are forwarded automatically;
+ * the ctx is built automatically. The seam becomes impossible to mis-wire.
+ *
+ * Typed structurally against the campaign `DispatchContext` (imported type-only
+ * from `@tangle-network/agent-eval/campaign`) — a downward dependency, never an
+ * inversion.
+ */
+
+/** runLoop options minus the `ctx` (loopDispatch builds the ctx). */
+type LoopOptionsForDispatch<Task, Output, Decision> = Omit<RunLoopOptions<Task, Output, Decision>, 'ctx'>;
+interface LoopDispatchOptions<Task, Output, Decision, TScenario extends Scenario, TArtifact> {
+    /** Sandbox client used for every cell's `runLoop`. Supplied once. */
+    sandboxClient: SandboxClient;
+    /** Build the per-cell runLoop options from the scenario (+ profile, when
+     *  used with `runProfileMatrix`). */
+    toLoopOptions: (scenario: TScenario, profile: AgentProfile) => LoopOptionsForDispatch<Task, Output, Decision>;
+    /** Map the finished loop to the artifact the judges score. Default:
+     *  `result.winner?.output`. A loop with no winner yields `undefined` (judges
+     *  skip the cell) — but the loop's token usage is STILL reported, so the
+     *  integrity guard sees real activity. */
+    toArtifact?: (result: LoopResult<Task, Output, Decision>) => TArtifact;
+    /** Forward `loop.*` trace events into the campaign's scoped trace so loop
+     *  spans correlate with the cell. Default true. */
+    forwardTrace?: boolean;
+    /** Cost-meter source label for the loop's spend. Default `'loop'`. */
+    costSource?: string;
+}
+/**
+ * Adapter for `runProfileMatrix` (profile is an axis). Returns a
+ * `ProfileDispatchFn` that runs `runLoop` per (profile, scenario) cell and
+ * reports usage automatically.
+ */
+declare function loopDispatch<Task, Output, Decision, TScenario extends Scenario, TArtifact>(opts: LoopDispatchOptions<Task, Output, Decision, TScenario, TArtifact>): ProfileDispatchFn<TScenario, TArtifact>;
+
+/**
+ * @experimental
+ *
+ * The personify layer — the "act like X" knob on top of the recursive keystone.
+ *
+ * The keystone (`src/loops/supervise/`) is pure STRUCTURE: a recursive `Agent` atom inside
+ * a budget-conserving `Scope`, an `ExecutorRegistry` mapping an `AgentSpec` to a runtime,
+ * and a `Supervisor` that runs a root agent to a typed `SupervisedResult`. It carries no
+ * CONTENT — no model, no prompt, no goal framing, no notion of "who this loop is".
+ *
+ * This layer adds exactly that content seam without inventing a second engine:
+ *  - A `Persona` is a thin record: the root `AgentSpec` (profile + harness + optional BYO
+ *    executor), a root `directive` (the goal framing handed to the chosen shape), a
+ *    `context` blob (who the loop is acting as), and the executor seams the registry needs.
+ *    `definePersona` builds it; it is data, not behavior.
+ *  - A `LoopShape` is a reusable act-body FACTORY: `(ctx: ShapeContext) => Agent`. The shape
+ *    owns the STRUCTURE (how to decompose / fan out / verify / synthesize); the persona's
+ *    content parameterizes it. A new shape is ONE file + one `registerShape` call.
+ *  - `Outcome<D>` is the contract every shape synthesizes into: a finished deliverable OR a
+ *    list of concrete blockers — "100% done or 100%-defined blockers", never a vague middle.
+ *
+ * Layering: this module imports ONLY keystone runtime types (`./supervise/types`) and the
+ * substrate `AgentProfile`/`BackendType`. It typechecks standalone — no impl, no engine.
+ * Extensibility is structural: `Persona` carries an open `extensions` bag so a later
+ * world-model / memory field is additive (a new optional key), never a breaking change.
+ */
+
+/**
+ * The terminal contract Drew wants: a loop returns a FINISHED deliverable, or the concrete
+ * list of blockers that stopped it — never a half-done best-effort coercion. A `blocked`
+ * outcome with an empty `blockers` list is a contract violation (a shape that can't finish
+ * MUST name why); impls fail loud on it rather than emitting a vacuous block.
+ *
+ * `Outcome` is the `Out` type a personified `Agent`/`Supervisor` is parameterized by, so the
+ * keystone's typed `SupervisedResult<Outcome<D>>` carries it end to end with no coercion.
+ */
+type Outcome<D> = {
+    kind: 'done';
+    deliverable: D;
+} | {
+    kind: 'blocked';
+    blockers: string[];
+};
+/**
+ * The "act like X" record. A thin composition over the keystone's `AgentSpec`: it pairs the
+ * root spec (the executor mapping for the root agent the shape builds) with the CONTENT a
+ * shape consumes — the goal framing (`directive`) and who the loop is acting as (`context`).
+ *
+ * The framework never reads `directive`/`context` semantically; it threads them to the shape
+ * verbatim through `ShapeContext`. This is the rule the mandate names: the FRAMEWORK is
+ * structure, the PERSONA carries model/prompt/tools/directive. No model name, prompt, or
+ * persona string is ever hardcoded in a shape or the engine.
+ *
+ * `D` is the deliverable type this persona's loops produce; it flows into `Outcome<D>`.
+ */
+interface Persona<D = unknown> {
+    /** Stable persona name — used as the trace/journal label root, never as content. */
+    readonly name: string;
+    /**
+     * The root agent's executor mapping (profile + harness + optional BYO executor). The
+     * shape's root `Agent` carries THIS as its `executorSpec`; child specs the shape spawns
+     * are derived from / resolved against the same persona registry (see `ShapeContext`).
+     */
+    readonly root: AgentSpec;
+    /** The goal framing handed to the shape — the "what to achieve", not "how". */
+    readonly directive: string;
+    /** Who the loop is acting as — the opaque persona context blob the shape may inject into
+     *  child tasks. Opaque to the framework; only the persona's profiles/prompts interpret it. */
+    readonly context: PersonaContext;
+    /**
+     * The executor seams (router endpoint+key, sandbox client, cli bin) the built-in runtimes
+     * read off `ExecutorContext.seams`, OR a fully pre-configured registry. The supervisor
+     * threads an EMPTY seam bag to the root scope, so a persona that uses built-in metered
+     * runtimes MUST supply a registry whose factories close over their seams (or BYO executors
+     * on each `AgentSpec`). Carried here so `runPersonified` can build `SupervisorOpts.executors`.
+     */
+    readonly executors: PersonaExecutors;
+    /**
+     * Forward-compatible extension bag — a later world-model / memory / tool-budget field is an
+     * additive key here, never a breaking change to the `Persona` shape. Opaque to the engine.
+     */
+    readonly extensions?: Readonly<Record<string, unknown>>;
+    /** Phantom: binds the persona to its deliverable type so `runPersonified` infers `D` from
+     *  the persona and the chosen shape must agree. Type-only — never present at runtime. */
+    readonly __deliverable?: D;
+}
+/** The persona context blob — who the loop is acting as. Open by intent: a persona names its
+ *  own role/audience/constraints; the framework treats it as opaque content. */
+interface PersonaContext {
+    /** The role the loop embodies ("senior staff engineer", "equity research analyst", …). */
+    readonly role: string;
+    /** Optional freeform framing the persona's prompts/profiles consume. */
+    readonly notes?: string;
+    /** Open content bag — persona-specific fields a shape's child tasks may carry. */
+    readonly [key: string]: unknown;
+}
+/**
+ * How a persona supplies executor resolution. Either a pre-built registry (factories already
+ * closed over their seams) OR the raw seam bag the engine uses to construct a registry +
+ * thread the seams onto each spawn. Exactly one is required — fail loud if neither is set.
+ */
+interface PersonaExecutors {
+    /** A registry whose factories already capture their seams. Highest precedence. */
+    readonly registry?: ExecutorRegistry;
+    /** Raw seams to thread onto built-in runtimes (`router`/`sandbox`/`cli` keys). */
+    readonly seams?: Readonly<Record<string, unknown>>;
+}
+/** The minimal input to build a `Persona`. Mirrors `Persona` but lets the builder default
+ *  the executors-supplied invariant check and freeze the record. */
+interface DefinePersonaInput<D = unknown> {
+    readonly name: string;
+    readonly root: AgentSpec;
+    readonly directive: string;
+    readonly context: PersonaContext;
+    readonly executors: PersonaExecutors;
+    readonly extensions?: Readonly<Record<string, unknown>>;
+    /** Phantom: pins the input's deliverable type so `definePersona<D>` returns a `Persona<D>`
+     *  the caller's shape must agree with. Type-only — never supplied at a call site. */
+    readonly __deliverable?: D;
+}
+/** Builds a frozen `Persona`, failing loud on the executors-supplied invariant (neither a
+ *  registry nor seams = an unresolvable persona). Pure — no I/O, no engine. */
+type DefinePersona = <D = unknown>(input: DefinePersonaInput<D>) => Persona<D>;
+/**
+ * Budget knobs a shape reads to size its fanout/children WITHOUT owning the conserved pool.
+ * The root budget lives on `SupervisorOpts.budget`; the shape only needs the per-child
+ * sizing hints + the fanout width it is allowed to open. All ceilings — the pool reserves
+ * against them and fails closed, so an over-eager shape can never overspend.
+ */
+interface ShapeBudget {
+    /** Per-child spawn budget the shape reserves for each leaf/sub-loop it opens. */
+    readonly perChild: Budget;
+    /** Max children a fanout step may open in one round (the shape's structural width). */
+    readonly fanout: number;
+}
+/**
+ * The construction context a `LoopShape` factory receives. Carries the persona's resolved
+ * executor seams + the budget knobs, plus the ONE helper a shape needs to spawn a child
+ * through the keystone: `spawnChild` resolves an `AgentSpec` (or a persona-derived child
+ * profile) into an `Agent` the shape hands to `scope.spawn`. The shape never touches the
+ * registry directly — it asks the context, keeping resolution single-sourced.
+ */
+interface ShapeContext<D = unknown> {
+    readonly persona: Persona<D>;
+    readonly budget: ShapeBudget;
+    /**
+     * Wrap an `AgentSpec` into a leaf `Agent` carrying it as `executorSpec`, so the shape can
+     * `scope.spawn(spawnChild(spec), task, opts)`. `name` labels the child for traces. The
+     * returned agent's `act` is never invoked by the keystone (it is spawned, not run) — the
+     * spec drives the resolved `Executor`; `act` exists only to satisfy the `Agent` shape.
+     */
+    spawnChild(name: string, spec: AgentSpec): Agent<unknown, Outcome<D>>;
+    /** Derive a child `AgentSpec` from the persona's root spec with an overridden profile —
+     *  the seam a shape uses to give a worker a narrower role/prompt than the root persona. */
+    childSpec(profile: AgentProfile$1, harness?: BackendType | null): AgentSpec;
+}
+/**
+ * A reusable act-body factory. Given the persona's content + seams (`ShapeContext`), it
+ * returns the root `Agent<Task, Outcome<D>>` whose `act` decomposes the task, fans out
+ * children through `scope.spawn`, verifies/selects across their settlements (selector≠judge:
+ * via `settledToIteration` + `defaultSelectWinner`, never re-ranking behind the driver), and
+ * synthesizes the terminal `Outcome<D>`. The shape is STRUCTURE; the persona is CONTENT.
+ */
+type LoopShape<Task, D> = (ctx: ShapeContext<D>) => Agent<Task, Outcome<D>>;
+/**
+ * The open shape registry — the extension point that makes a new loop-shape ONE file + one
+ * `registerShape` call with zero edits elsewhere. `resolve` returns a typed outcome (inspect
+ * `succeeded` before `value`); `register` fails loud on a duplicate name.
+ */
+interface ShapeRegistry {
+    register<Task, D>(name: string, factory: LoopShape<Task, D>): void;
+    resolve<Task, D>(name: string): {
+        succeeded: true;
+        value: LoopShape<Task, D>;
+    } | {
+        succeeded: false;
+        error: string;
+    };
+    /** The registered shape names — for diagnostics + a fail-loud "unknown shape" message. */
+    names(): string[];
+}
+/**
+ * The end-to-end entrypoint. Builds the persona's root `Agent` from the chosen shape, then
+ * runs it through a fresh `createSupervisor` over the persona's executors + the supplied
+ * budget/journal/blobs. Returns the keystone's typed `SupervisedResult<Outcome<D>>` — a
+ * `winner` carries the synthesized `Outcome<D>`; a `no-winner` is never coerced into one.
+ *
+ * `shape` is either a resolved `LoopShape` or a registered shape NAME (resolved through the
+ * default registry). The journal/blobs default to in-memory impls in the engine when omitted
+ * (durable FS impls are passed explicitly for a persisted run).
+ */
+interface RunPersonifiedOptions<Task, D> {
+    readonly persona: Persona<D>;
+    /** A resolved shape factory OR a registered shape name. */
+    readonly shape: LoopShape<Task, D> | string;
+    readonly task: Task;
+    readonly budget: Budget;
+    /** Per-child sizing + fanout width handed to the shape. Defaults derive from `budget`. */
+    readonly shapeBudget?: Partial<ShapeBudget>;
+    /** Trace/journal root key. Defaults to the persona name + a run discriminator in the engine. */
+    readonly runId?: string;
+    readonly journal?: SpawnJournal;
+    readonly blobs?: ResultBlobStore;
+    /** Runtime recursion-depth ceiling, paired with the conserved pool. */
+    readonly maxDepth?: number;
+    /** OTP intensity breaker bounds, forwarded to the supervisor verbatim. */
+    readonly maxRestarts?: number;
+    readonly withinMs?: number;
+    /** A live root handle to attach (view/signal/abort) before the run starts. */
+    readonly handle?: RootHandle<Outcome<D>>;
+    readonly now?: () => number;
+    readonly signal?: AbortSignal;
+}
+/** The composed run signature. */
+type RunPersonified = <Task, D>(options: RunPersonifiedOptions<Task, D>) => Promise<SupervisedResult<Outcome<D>>>;
+
+/**
+ * @experimental
+ *
+ * The RSI-wave type surface — the FROZEN contracts the wave's Core + Compose build to.
+ *
+ * The keystone (`../supervise/`) is pure execution structure: a recursive `Agent` atom in a
+ * budget-conserving `Scope`, run to a typed `SupervisedResult` by a `Supervisor`. The persona
+ * layer (`./types`, `./persona`) adds the "act like X" content seam (`Persona` = `AgentSpec` +
+ * `directive` + `context`, `LoopShape = (ctx) => Agent`, `Outcome<D>`). This module freezes the
+ * remaining four wave seams ON TOP of those — and nothing more:
+ *
+ *  1. GENERIC COMBINATORS — the content-free act-library. Five composable shapes
+ *     (`pipeline`/`fanout`/`loopUntil`/`panel`/`verify`) plus the streaming widener (G5). Each
+ *     is a `CombinatorShape` (a `LoopShape` whose `Agent.act` runs the combinator over `Scope`),
+ *     so a combinator IS just a `LoopShape` — no new engine type. The SHAPE is here; the DOMAIN
+ *     (model, prompt, role) stays on the `Persona`. There is no "research" or "code" combinator:
+ *     a research sweep is `fanout` under a research persona; a build is `pipeline` under a coder.
+ *  2. ANALYST-ON-SCOPE (G1, a PORT) — `ScopeAnalyst` carries the round-synchronous driver's
+ *     analyze→findings→steer wire (dynamic.ts) across to the reactive `Scope`, behind
+ *     the same trace-derived firewall (`assertTraceDerivedFindings` semantics): a reactive
+ *     combinator steers from trace FINDINGS, never a child's raw `verdict`.
+ *  3. CROSS-RUN CORPUS (G2) — `Corpus` is the DURABLE accreted-fact store, DISTINCT from the
+ *     per-run `SpawnJournal`/`ResultBlobStore`. `renderCorpusToInstructions` is the read-back:
+ *     it projects accreted facts into `AgentProfile.prompt.instructions` / `resources.instructions`
+ *     for the next run's persona (the learning-flywheel READ side).
+ *  4. TRAJECTORY TRACE + COST LEDGER — `trajectoryReport(journal, blobs)` reconstructs the whole
+ *     spawn tree with per-node + rolled-up `Spend`; `equalKOnCost` compares arms on conserved
+ *     COST (tokens/usd), NOT raw iteration count — closing the leaf-fanout confound.
+ *
+ * Layering: imports ONLY keystone runtime types (`../supervise/types`), persona types
+ * (`./types`), the substrate `AnalystFinding`/`AgentProfile`, and the durable-store interfaces.
+ * Pure types/interfaces — this module typechecks standalone, owns no impl, invents no engine.
+ */
+
+/**
+ * A combinator is just a `LoopShape`: a factory `(ShapeContext) => Agent` whose `Agent.act`
+ * runs the combinator's structure over the `Scope` (spawn children, drain `next()`, select via
+ * the single-sourced `settledToIteration`+`defaultSelectWinner`, synthesize an `Outcome<D>`).
+ * Aliased — NOT a new type — so a combinator stays a first-class shape the persona layer's
+ * `runPersonified`/`ShapeRegistry` resolve with zero new machinery. The SHAPE is content-free;
+ * the persona carries the domain.
+ */
+type CombinatorShape<Task, D> = LoopShape<Task, D>;
+/**
+ * `pipeline(stages)` — sequential composition: each stage's `Outcome.deliverable` feeds the next
+ * stage's task (via `feed`). The first `blocked` stage short-circuits the whole pipeline (its
+ * blockers ARE the pipeline's blockers — never coerced past a failed stage). The terminal
+ * stage's `done` deliverable is the pipeline's deliverable. Spawns one child per stage in order;
+ * a stage that the conserved pool cannot admit is a concrete blocker.
+ *
+ * No domain: "code build test" is `pipeline([plan, implement, integrate])` under a coder persona,
+ * not a named shape. A stage names only its label + how to derive its task from the prior output.
+ */
+interface PipelineStage<Task, StepIn, StepOut> {
+    /** Trace/journal label for this stage's spawned child. */
+    readonly label: string;
+    /** Derive this stage's task from the prior stage's deliverable (or the root task for stage 0).
+     *  Pure projection — the framework never interprets the result; the resolved leaf does. */
+    feed(prior: StepIn, ctx: ShapeContext<unknown>, rootTask: Task): unknown;
+    /** Read this stage's settled child output into the typed `StepOut` the next stage feeds on.
+     *  Fail loud (return a `blocked`) when the child produced nothing usable for the next stage. */
+    collect(settled: Settled<Outcome<StepOut>>): Outcome<StepOut>;
+}
+/** `pipeline(stages)` — build the sequential combinator from an ordered stage list. The first
+ *  stage's `StepIn` is the root `Task`; the last stage's `StepOut` is the deliverable `D`. */
+type Pipeline = <Task, D>(stages: ReadonlyArray<PipelineStage<Task, unknown, unknown>>) => CombinatorShape<Task, D>;
+/**
+ * `fanout(items, { synthesize? })` — N children spawned in one round (one per item, bounded by
+ * the conserved pool's fail-closed admission), drained via `scope.next()`, then optionally a
+ * single SYNTHESIS child over the gathered results. Without `synthesize`, the combinator returns
+ * the best-valid child via the single-sourced selector (selector≠judge). A round that admitted
+ * zero children, or whose synthesis child could not be admitted, is a concrete blocker.
+ *
+ * No domain: a "research sweep over angles" is `fanout(angles, { synthesize: cite })` under a
+ * research persona; a "fanout-vote" is `fanout(copies)` with the default selector. The item list
+ * + the synthesis posture are the SHAPE's args; the prompt that turns an item into work is the
+ * persona's.
+ */
+interface FanoutOptions<Item, D> {
+    /** One child task per item: `item` + the index discriminator. The persona's directive/context
+     *  is threaded in by the combinator; this only supplies the per-item discriminator. */
+    itemTask(item: Item, index: number, ctx: ShapeContext<D>): unknown;
+    /** Per-item child label (defaults to `item:<index>` in the impl). */
+    label?(item: Item, index: number): string;
+    /**
+     * Optional synthesis over the gathered child results: when present, the combinator spawns ONE
+     * synthesis child whose task is built from the drained settlements, and its `done` output is
+     * the deliverable. When absent, the deliverable is the best-valid child via `defaultSelectWinner`.
+     * The synthesis child is a SEPARATE keystone agent (not a re-rank behind the driver).
+     */
+    synthesize?: FanoutSynthesis<D>;
+}
+/** How a fanout's synthesis child is built + read. `synthesisTask` projects the drained child
+ *  settlements into the synthesis child's task; `collect` reads its settled output into the
+ *  deliverable `Outcome<D>`. */
+interface FanoutSynthesis<D> {
+    synthesisTask(gathered: ReadonlyArray<Settled<Outcome<D>>>, ctx: ShapeContext<D>): unknown;
+    collect(settled: Settled<Outcome<D>>): Outcome<D>;
+}
+/** `fanout(items, opts)` — build the fanout combinator over a static item list. */
+type Fanout = <Task, Item, D>(items: ReadonlyArray<Item>, opts: FanoutOptions<Item, D>) => CombinatorShape<Task, D>;
+/**
+ * `loopUntil({ until, step })` — iterative deepening inside the conserved pool: spawn one `step`
+ * child per round, ask `until` whether the accumulated state satisfies the goal, and stop when it
+ * does OR when the pool can no longer admit a step (budget IS the loop bound — no unbounded
+ * while). The deployable, non-oracle stop: `until` is the satisfiability gate, read from trace
+ * findings + accumulated deliverables, never a fresh raw verdict the loop minted to stop itself.
+ *
+ * No domain: "refine until tests pass" is `loopUntil` with a coder persona + a `step` that edits
+ * and an `until` that reads the test-finding; the combinator owns only the round/stop wiring.
+ */
+interface LoopUntilSpec<Task, State, D> {
+    /** Build the next step child's task from the root task + the state accumulated so far. */
+    step(rootTask: Task, state: LoopUntilState<State>, ctx: ShapeContext<D>): unknown;
+    /** Fold one settled step into the accumulated state (the loop's running deliverable candidate). */
+    fold(prior: LoopUntilState<State>, settled: Settled<Outcome<D>>): LoopUntilState<State>;
+    /**
+     * The satisfiability gate: given the accumulated state + the round's trace findings, has the
+     * goal been reached? Returns the terminal deliverable when satisfied, or `null` to keep going.
+     * Reads `findings` (trace-derived), NOT a raw verdict score — the deployable-stop discipline.
+     */
+    until(state: LoopUntilState<State>, findings: ReadonlyArray<AnalystFinding>): Outcome<D> | null;
+    /** Per-round step label (defaults to `step:<round>` in the impl). */
+    label?(round: number): string;
+}
+/** The accumulated state `loopUntil` threads across rounds — the running candidate + the round
+ *  index, so `step`/`fold`/`until` are pure functions of it (replay-safe, no wall-clock). */
+interface LoopUntilState<State> {
+    readonly round: number;
+    readonly value: State;
+}
+/** `loopUntil(spec)` — build the iterative-deepening combinator. `seed` is the initial state. */
+type LoopUntil = <Task, State, D>(seed: State, spec: LoopUntilSpec<Task, State, D>) => CombinatorShape<Task, D>;
+/**
+ * `panel(judges)` — M judges over ONE artifact, merged WRITE-ONLY (selector≠judge taken to its
+ * limit). The combinator spawns the M judge children over the same input artifact, drains their
+ * settlements, and MERGES their findings into a panel verdict via `merge` — a pure WRITE-ONLY
+ * fold (a judge's output is never fed back to steer another judge, and the merge never re-ranks
+ * the children behind the driver). The merged verdict gates the deliverable.
+ *
+ * No domain: a "code review panel" and an "essay rubric panel" are the same `panel` shape under
+ * different personas; the rubric lives in each judge persona's profile, not the combinator.
+ */
+interface PanelSpec<Artifact, D> {
+    /** The M judge child specs: each is a persona-derived child (a narrower judge profile). The
+     *  combinator spawns one child per entry over the SAME `artifact` and never lets one judge's
+     *  output reach another's task (write-only). */
+    readonly judges: ReadonlyArray<PanelJudge>;
+    /** Build one judge child's task from the shared artifact under review + the judge descriptor. */
+    judgeTask(artifact: Artifact, judge: PanelJudge, ctx: ShapeContext<D>): unknown;
+    /**
+     * Write-only merge: fold the M settled judge verdicts into the panel's terminal `Outcome<D>`.
+     * Pure over the drained settlements — it MUST NOT spawn, re-judge, or feed one verdict into
+     * another. A panel that reached no quorum is a concrete blocker (fail loud, never a vacuous done).
+     */
+    merge(verdicts: ReadonlyArray<PanelVerdict>, artifact: Artifact): Outcome<D>;
+}
+/** One judge in a panel — a labeled persona-derived judge child. Content (the rubric) lives in
+ *  the judge's profile; this carries only the label + the optional weight the merge may read. */
+interface PanelJudge {
+    readonly label: string;
+    /** Optional merge weight (a write-only hint the `merge` fold may use; default-equal in the impl). */
+    readonly weight?: number;
+}
+/** One judge child's settled verdict, surfaced to the write-only `merge`. `down` judges carry no
+ *  verdict (excluded from the merge `n`, like an infra-errored cell). */
+interface PanelVerdict {
+    readonly judge: PanelJudge;
+    readonly verdict?: DefaultVerdict;
+    /** The judge child's raw output — what it was asked to assess, for a merge that quotes it. */
+    readonly output?: unknown;
+    /** True when the judge child went `down` (no usable verdict — kept out of the merge denominator). */
+    readonly down: boolean;
+}
+/** `panel(spec)` — build the M-judge write-only-merge combinator. */
+type Panel = <Task, Artifact, D>(spec: PanelSpec<Artifact, D>) => CombinatorShape<Task, D>;
+/**
+ * `verify({ implement, verifier })` — the 2-node sequential gate: an IMPLEMENT child produces a
+ * candidate, then a SEPARATE VERIFIER child's verdict GATES shippability. A `valid` verifier
+ * verdict ships the implement deliverable; any other outcome (implement down, verifier down,
+ * invalid verdict) becomes a concrete blocker carrying the failure verbatim — never a coerced
+ * "done". The verifier is a distinct keystone agent (selector≠judge: the implement child does
+ * not grade itself).
+ *
+ * No domain: "write code then run the test gate" and "draft then fact-check" are the same `verify`
+ * shape under different personas; the gate rubric is the verifier persona's, not the combinator's.
+ */
+interface VerifySpec<Task, Candidate, D> {
+    /** Build the implement child's task from the root task. */
+    implement(rootTask: Task, ctx: ShapeContext<D>): unknown;
+    /** Build the verifier child's task from the implement child's settled candidate. */
+    verifier(candidate: Settled<Outcome<Candidate>>, ctx: ShapeContext<D>): unknown;
+    /** Project the gated (verifier-`valid`) candidate into the terminal deliverable. */
+    collect(candidate: Settled<Outcome<Candidate>>, verdict: DefaultVerdict): Outcome<D>;
+    /** Implement / verifier child labels (default `implement` / `verify` in the impl). */
+    readonly implementLabel?: string;
+    readonly verifierLabel?: string;
+}
+/** `verify(spec)` — build the 2-node implement→verifier-gate combinator. */
+type Verify = <Task, Candidate, D>(spec: VerifySpec<Task, Candidate, D>) => CombinatorShape<Task, D>;
+/**
+ * `widen({ gate })` (G5) — the STREAMING spawn-on-completion driver. Unlike the static-fanout
+ * combinators above, the widener REACTS to each `scope.next()`: as each child settles it consults
+ * the `WidenGate` and, when a lineage is `promising`, widens by AT MOST ONE child toward it under
+ * the remaining conserved pool. Defaults to FLAT (the gate never widens) so a gate run stays
+ * non-widening and the R2 selector≠judge collision is dormant. `promising` is derived from the
+ * round's analyst FINDINGS (via `ScopeAnalyst`, §2), NOT a child's raw `verdict` — the firewall.
+ *
+ * This is the progressive-widening (MCTS-PW) combinator: the one shape whose breadth is decided
+ * at runtime from the diagnosis, not fixed at spawn. It is the mechanism the diverse-strategy-vs-
+ * blind GATE is run with — kept FLAT by default until that gate returns positive (don't build
+ * mechanism ahead of the gate).
+ */
+interface WidenSpec<Seed, D> {
+    /** The initial children to spawn before any widening — the seed lineages the gate widens from.
+     *  One child task per seed; bounded by the conserved pool's fail-closed admission. */
+    readonly seeds: ReadonlyArray<Seed>;
+    seedTask(seed: Seed, index: number, ctx: ShapeContext<D>): unknown;
+    /**
+     * The progressive-widening gate. Consulted on EVERY settled child with the round's
+     * trace-derived `findings`; returns a widen decision (spawn one more toward a lineage) or a
+     * stop. DEFAULTS to flat via `flatWidenGate` — never widens, so the firewall stays dormant.
+     */
+    readonly gate: ScopeWidenGate<D>;
+    /** Build the widened child's task from the lineage the gate chose to extend. */
+    widenTask(toward: WidenLineage<D>, ctx: ShapeContext<D>): unknown;
+    /** Synthesize the terminal deliverable from every settled lineage (selector≠judge: the
+     *  single-sourced selector over the gathered children, never a re-judge). */
+    synthesize(gathered: ReadonlyArray<Settled<Outcome<D>>>, ctx: ShapeContext<D>): Outcome<D>;
+}
+/**
+ * The runtime widening gate (the reactive analogue of the keystone's `WidenGate`, lifted to read
+ * trace FINDINGS instead of a raw verdict). `decide` is consulted per settled child; it MUST
+ * derive `promising` from `findings`, never from `settled.verdict`, unless `judgeExempt` is
+ * explicitly argued (the documented off-by-default escape hatch). Flat default never widens.
+ */
+interface ScopeWidenGate<D> {
+    decide(settled: Settled<Outcome<D>>, findings: ReadonlyArray<AnalystFinding>, budget: Scope<Outcome<D>>['budget']): WidenDecision<D>;
+    /** When true, `decide` may read `settled.verdict` directly — collides with the steer firewall,
+     *  so it must be argued per cell, never defaulted on (mirrors the keystone `WidenGate`). */
+    readonly judgeExempt?: boolean;
+}
+/** A widening decision: extend one lineage by one child, or stop widening. `flatWidenGate`
+ *  always returns `{ kind: 'stop' }`. */
+type WidenDecision<D> = {
+    kind: 'widen';
+    toward: WidenLineage<D>;
+} | {
+    kind: 'stop';
+    rationale?: string;
+};
+/** A lineage the gate may widen toward — the settled child that looked promising + the findings
+ *  that justified it (the trace-derived provenance the firewall requires). */
+interface WidenLineage<D> {
+    readonly settled: Extract<Settled<Outcome<D>>, {
+        kind: 'done';
+    }>;
+    readonly findings: ReadonlyArray<AnalystFinding>;
+}
+/** `widen(spec)` — build the streaming progressive-widening combinator. */
+type Widen = <Task, Seed, D>(spec: WidenSpec<Seed, D>) => CombinatorShape<Task, D>;
+/** The flat default `ScopeWidenGate` factory contract — never widens, keeping the R2 firewall
+ *  conflict dormant. Exported so a gate run can pass it explicitly and a test can assert the
+ *  default is flat. */
+type FlatWidenGate = <D>() => ScopeWidenGate<D>;
+/**
+ * The reactive analyst seam — the PORT of the round-synchronous driver's `analyze` hook
+ * (dynamic.ts) onto the reactive `Scope`. The old driver wired the analyst at round
+ * boundaries (`plan` ran the analyst over `history` BEFORE the planner); the reactive `Scope` has
+ * no rounds, so this carries the wire across: a combinator's `act` asks the `ScopeAnalyst` to turn
+ * the settled children SO FAR into `AnalystFinding[]`, and steers from THOSE findings.
+ *
+ * The firewall is preserved (selector≠judge): `analyze` runs the trace-derived analyst and the
+ * impl asserts `assertTraceDerivedFindings` semantics — a finding citing judge/verdict/score
+ * `metric` evidence aborts the round. The steer decision reads `findings`, NEVER the children's
+ * raw `verdict`. Fail loud — a throwing or non-array analyst aborts (no silent empty findings).
+ */
+interface ScopeAnalyst<D> {
+    /**
+     * Turn the children settled so far into trace-derived findings. `settledSoFar` is the cursor-
+     * ordered settlement list a combinator has drained (the reactive analogue of the old driver's
+     * `history`). The impl runs the analyst, then enforces the trace-derived firewall before
+     * returning — a judge-derived finding is rejected, not filtered.
+     */
+    analyze(input: ScopeAnalyzeInput<D>): Promise<ReadonlyArray<AnalystFinding>>;
+}
+/** Input to a `ScopeAnalyst.analyze` — the root task framing + the children settled so far. The
+ *  reactive analogue of the old `AnalyzeInput { task, history }`. */
+interface ScopeAnalyzeInput<D> {
+    /** Opaque root-task framing (whatever the combinator was invoked with). */
+    readonly task: unknown;
+    /** The children this combinator has drained off `scope.next()`, in cursor order. */
+    readonly settledSoFar: ReadonlyArray<Settled<Outcome<D>>>;
+    /** This combinator's scope id (the trace-correlation root for the analyst). */
+    readonly nodeId: NodeId;
+}
+/**
+ * How a combinator's `act` consumes findings to steer — the SINGLE firewalled steer surface a
+ * reactive combinator reads. `loopUntil.until`, `widen` gate, and any future steer all funnel
+ * through a `SteerContext` so the firewall is enforced in one place: `findings` is trace-derived
+ * (the analyst already asserted it), and a combinator MUST NOT reach back to `settled.verdict`
+ * for the steer decision. `lastValidScore` is provided for OBSERVABILITY only (rendering/traces),
+ * explicitly NOT for steering — reading it to steer is the coupling the architecture forbids.
+ */
+interface SteerContext<D> {
+    readonly findings: ReadonlyArray<AnalystFinding>;
+    readonly settledSoFar: ReadonlyArray<Settled<Outcome<D>>>;
+    /** Observability-only: the best valid score seen so far. Rendering/trace use ONLY — steering
+     *  off this re-introduces selector=judge. Marked so a reviewer catches a misuse. */
+    readonly lastValidScore?: number;
+}
+/**
+ * The firewall assertion contract, re-stated for the reactive seam (PORT of
+ * `assertTraceDerivedFindings`). A PROVENANCE check, not a content check: span/event/artifact/
+ * finding refs and empty-evidence findings pass; only a `metric` ref whose uri is a
+ * judge/verdict/score scheme is rejected. Fail loud — a tainted finding aborts. The impl lives in
+ * `analyst.ts`; this type pins its signature so callers depend on the contract, not the impl.
+ */
+type AssertTraceDerivedFindings = (findings: ReadonlyArray<AnalystFinding>) => void;
+/**
+ * One accreted fact in the cross-run corpus — the learning-flywheel's durable unit. DISTINCT from
+ * a `SpawnEvent` (a per-run decision record): a `CorpusRecord` is a fact a run LEARNED that a
+ * FUTURE run should read back (the world-model for story 5). It is content the next persona reads,
+ * not a replay input. Tagged + scored so `query`/`renderCorpusToInstructions` can project the
+ * relevant, high-confidence subset.
+ */
+interface CorpusRecord {
+    readonly schemaVersion: '1.0.0';
+    /** Stable id over identity-defining fields (claim + tags) so a re-learned fact dedups. */
+    readonly id: string;
+    /** The run that produced this fact (the journal `runId`/`root`) — provenance back to the trace. */
+    readonly runId: NodeId;
+    readonly producedAt: string;
+    /** Coarse classification the query/render filters on (free-form, mirrors `AnalystFinding.area`). */
+    readonly area: string;
+    /** The accreted fact — the instruction-shaped statement the next run reads back. */
+    readonly claim: string;
+    /** Optional supporting detail the renderer may include under the claim. */
+    readonly rationale?: string;
+    /** Free-form tags for `query` filtering (domain, persona, surface). */
+    readonly tags: ReadonlyArray<string>;
+    /** 0..1 — the producing run's confidence in this fact (the render threshold reads it). */
+    readonly confidence: number;
+    /** Optional provenance back into the run that learned it (a finding id / outRef / span). */
+    readonly evidence?: ReadonlyArray<{
+        readonly kind: string;
+        readonly uri: string;
+    }>;
+}
+/** A corpus query filter — every field is an AND-narrowing; an omitted field does not constrain. */
+interface CorpusFilter {
+    readonly area?: string;
+    /** Match records carrying ALL of these tags. */
+    readonly tags?: ReadonlyArray<string>;
+    /** Minimum confidence a record must clear to be returned (the render gate). */
+    readonly minConfidence?: number;
+    /** Only records from this run (rare — usually a cross-run read). */
+    readonly runId?: NodeId;
+    /** Cap the result count (most-confident first in the impl). */
+    readonly limit?: number;
+}
+/**
+ * The durable cross-run corpus — the learning-flywheel store. DISTINCT from `SpawnJournal`
+ * (per-run decisions, replay) and `ResultBlobStore` (per-run payloads): `Corpus` holds accreted
+ * FACTS across runs that the next run reads back. `InMemoryCorpus` + `FileCorpus` (JSONL) impls
+ * live in `corpus.ts` and MAY share a storage spine with the JSONL journal, but the INTERFACE is
+ * separate so a consumer never confuses a replay record with a learned fact.
+ *
+ * Fail-loud, typed-outcome boundary: `append` is idempotent on an identical record (same `id` +
+ * `claim`); a conflicting re-append under the same `id` is a typed error, never a silent overwrite.
+ */
+interface Corpus {
+    /** Append one accreted fact. Idempotent on an identical record; returns a typed outcome —
+     *  inspect `succeeded` before treating it as durable (no silent write-through on conflict). */
+    append(record: CorpusRecord): Promise<{
+        succeeded: true;
+    } | {
+        succeeded: false;
+        error: string;
+    }>;
+    /** Query accreted facts by filter — most-confident first. Returns the matching records (an
+     *  empty array when none match is a valid result, NOT an error). */
+    query(filter: CorpusFilter): Promise<ReadonlyArray<CorpusRecord>>;
+}
+/**
+ * Project accreted corpus facts into an `AgentProfile`'s instruction seams — the learning-flywheel
+ * READ side. Reads the corpus through `filter`, renders the matching facts into instruction lines,
+ * and returns a NEW profile with them merged into `prompt.instructions` (the append-line seam) so
+ * the next run's persona reads the accreted world-model. Pure projection over the queried records;
+ * never mutates the input profile (returns a fresh one). The impl lives in `corpus.ts`.
+ *
+ * `resources.instructions` is `string | AgentProfileResourceRef`; `prompt.instructions` is
+ * `string[]`. The render targets `prompt.instructions` (additive lines) by default; a caller that
+ * wants the single-blob `resources.instructions` form passes `target: 'resources'`.
+ */
+interface RenderCorpusToInstructionsOptions {
+    readonly corpus: Corpus;
+    readonly filter: CorpusFilter;
+    /** The profile to project the facts into. The result is a fresh profile — the input is unchanged. */
+    readonly profile: AgentProfile$1;
+    /** Where the rendered facts land: appended to `prompt.instructions[]` (default) or folded into
+     *  the single-blob `resources.instructions` string. */
+    readonly target?: 'prompt' | 'resources';
+    /** Optional cap on rendered lines (most-confident first), independent of the query `limit`. */
+    readonly maxLines?: number;
+}
+/** `renderCorpusToInstructions(opts)` — the flywheel read-back projection. Async (queries the
+ *  durable corpus); returns a fresh `AgentProfile` with the accreted facts merged in. */
+type RenderCorpusToInstructions = (opts: RenderCorpusToInstructionsOptions) => Promise<AgentProfile$1>;
+/**
+ * One node in the reconstructed trajectory tree — a driver OR a leaf, with its OWN spend and the
+ * spend ROLLED UP over its subtree. Reconstructed from the `SpawnJournal` (structure + per-node
+ * `Spend`) + the `ResultBlobStore` (the `out` artifact, rehydrated by `outRef`). The realized tree
+ * shape: `parent`/`children` are the actual spawn edges the run took, not a planned topology.
+ */
+interface TrajectoryNode {
+    readonly id: NodeId;
+    readonly parent?: NodeId;
+    readonly children: ReadonlyArray<NodeId>;
+    readonly label: string;
+    readonly runtime: string;
+    /** Terminal status the journal recorded for this node. */
+    readonly status: 'done' | 'failed' | 'cancelled' | 'pending';
+    /** This node's OWN conserved spend (from its `settled` event). */
+    readonly ownSpend: Spend;
+    /** This node's spend PLUS every descendant's — the rolled-up subtree cost. The cost a parent
+     *  "really" consumed inclusive of its children's fanout (the equal-k-on-cost basis). */
+    readonly rolledUpSpend: Spend;
+    /** The node's verdict, when its settlement carried one (observability — NOT a steer input). */
+    readonly verdict?: DefaultVerdict;
+    /** The rehydrated output artifact, when `withOutputs` was requested + the blob resolved. */
+    readonly output?: unknown;
+    readonly outRef?: string;
+}
+/** The whole reconstructed trajectory — the realized tree + its root-rolled-up total. The
+ *  per-node + rolled-up `Spend` is the evidence both the trace viewer and `equalKOnCost` read. */
+interface TrajectoryReport {
+    readonly root: NodeId;
+    /** Every node, in cursor/spawn order — the realized tree (`parent`/`children` are the real edges). */
+    readonly nodes: ReadonlyArray<TrajectoryNode>;
+    /** The root's rolled-up spend — the whole run's conserved total (tokens + usd + iterations + ms). */
+    readonly total: Spend;
+    /** Count of nodes by terminal status — a quick "how did the tree end" readout. */
+    readonly statusCounts: Readonly<Record<TrajectoryNode['status'], number>>;
+}
+/**
+ * `trajectoryReport(journal, blobs, root, { withOutputs? })` — reconstruct the whole tree with
+ * per-node + rolled-up `Spend`. Reads the journal for structure + spend and (when `withOutputs`)
+ * the blob store for each `done` node's artifact. Fail loud on a tree that was never journaled or
+ * a `done` node whose blob the store cannot rehydrate (a silent gap would mis-cost the tree). The
+ * impl lives in `trajectory.ts`.
+ */
+interface TrajectoryReportOptions {
+    /** Rehydrate each `done` node's `output` from the blob store. Off by default (cost-only report). */
+    readonly withOutputs?: boolean;
+}
+/** `trajectoryReport(...)` — the tree+cost reconstructor. Async (reads journal + optionally blobs). */
+type TrajectoryReportFn = (journal: SpawnJournal, blobs: ResultBlobStore, root: NodeId, options?: TrajectoryReportOptions) => Promise<TrajectoryReport>;
+/**
+ * One arm of an equal-k comparison — a labeled trajectory (a `TrajectoryReport` is one arm's whole
+ * run). The arm's conserved COST is `report.total` (tokens + usd), which the sandbox executor
+ * already reports INCLUSIVE of a leaf's internal sub-agent fanout — so comparing arms on this cost
+ * (not raw `iterations`) closes the leaf-fanout confound: a treatment arm whose leaf fanned out
+ * internally is charged for that fanout in `total.tokens`/`total.usd`, not hidden behind one
+ * iteration count.
+ */
+interface EqualKArm {
+    readonly label: string;
+    readonly report: TrajectoryReport;
+}
+/**
+ * The equal-k-on-cost verdict: whether every arm spent within `tolerance` of the others on the
+ * CONSERVED cost channels (tokens + usd), so a downstream metric comparison is "at equal k". Per-
+ * arm cost is surfaced so a caller can see HOW close. `withinTolerance: false` means the arms are
+ * NOT comparable at equal compute — a confound to report, not a result to publish.
+ */
+interface EqualKVerdict {
+    readonly withinTolerance: boolean;
+    /** Per-arm conserved cost (the basis: tokens total + usd). */
+    readonly arms: ReadonlyArray<{
+        readonly label: string;
+        readonly tokens: number;
+        readonly usd: number;
+        readonly iterations: number;
+    }>;
+    /** The realized spread on each channel (max − min across arms), for the report. */
+    readonly spread: {
+        readonly tokens: number;
+        readonly usd: number;
+    };
+    /** The fractional tolerance the check used (spread / median ≤ tolerance per channel). */
+    readonly tolerance: number;
+}
+/**
+ * `equalKOnCost(arms, { tolerance? })` — assert arms are comparable at EQUAL conserved COST
+ * (tokens + usd), NOT raw iteration count. The conserved-pool guarantees `Σk` equal by
+ * construction WITHIN one supervised run; this checks it ACROSS arms (separate runs) where the
+ * pool cannot, so a cross-arm gate comparison can prove equal compute before claiming a win. The
+ * impl lives in `trajectory.ts`. Pure over the reports — no I/O.
+ */
+interface EqualKOnCostOptions {
+    /** Max fractional spread (spread/median) per channel for arms to count as equal-k. Default in
+     *  the impl (e.g. 0.05). A tighter tolerance = a stricter equal-compute claim. */
+    readonly tolerance?: number;
+}
+/** `equalKOnCost(arms, opts)` — the cross-arm equal-compute check on conserved cost. */
+type EqualKOnCost = (arms: ReadonlyArray<EqualKArm>, options?: EqualKOnCostOptions) => EqualKVerdict;
+
+/**
+ * @experimental
+ *
+ * Analyst-on-scope (G1) — the PORT of the round-synchronous driver's analyze→findings→steer
+ * wire (`dynamic.ts`) onto the reactive `Scope`.
+ *
+ * The old dynamic driver wired the analyst at round boundaries: `plan` ran the analyst over
+ * `history` BEFORE the planner and handed the findings forward via `PlannerContext.analyses`,
+ * behind a provenance firewall (`assertTraceDerivedFindings`) that keeps the external write-only
+ * judge out of the steer decision (selector ≠ judge). The reactive `Scope` has no rounds, so this
+ * module carries the same wire across: a combinator's `act` asks a `ScopeAnalyst` to turn the
+ * children it has drained off `scope.next()` SO FAR into `AnalystFinding[]`, and steers from THOSE
+ * findings through a single `SteerContext`.
+ *
+ * The analyst itself is not a new type — it is "just an `Agent<unknown, AnalystFinding[]>`" the
+ * combinator spawns over a child's trace (harness `null`/`cli`). `createScopeAnalyst` spawns that
+ * agent through `Scope.spawn` (so its compute is metered by the conserved pool like any child),
+ * drains its settlement, then enforces the firewall on the way out — a judge-derived finding
+ * ABORTS, it is never filtered. Fail loud: a down analyst, a non-array result, or a tainted finding
+ * throws; there is no silent empty-findings path that would let a combinator steer on nothing.
+ */
+
+declare const assertTraceDerivedFindings: AssertTraceDerivedFindings;
+/**
+ * The analyst run an `Agent<unknown, AnalystFinding[]>` performs over the children settled so far.
+ * The combinator supplies the analyst's task projection (how to frame the drained settlements as
+ * the analyst's input) — the analyst's `act` reads the trace and returns its raw findings; the
+ * firewall is enforced afterwards by `createScopeAnalyst`, not by the analyst itself.
+ */
+interface CreateScopeAnalystOptions<D> {
+    /** The analyst agent the combinator spawns over the trace. `harness` is the persona's choice
+     *  (`null` for an inline router analyst, a `BackendType` for a sandboxed one). Its `act` returns
+     *  the RAW findings; this module asserts the firewall on them before returning. */
+    readonly analyst: Agent<unknown, ReadonlyArray<AnalystFinding>>;
+    /** Build the analyst agent's task from the analyze input (the root-task framing + the children
+     *  drained so far). Pure projection — the analyst interprets it, this never reads it. */
+    buildTask(input: ScopeAnalyzeInput<D>): unknown;
+    /** The conserved budget reserved for one analyst spawn. The pool reserves against it and fails
+     *  closed; an analyst that cannot be admitted is a fail-loud abort, never silent empty findings. */
+    readonly budget: Budget;
+    /** Trace/journal label for the spawned analyst child. Default `'analyst'`. */
+    readonly label?: string;
+}
+/**
+ * Build a `ScopeAnalyst` that spawns the analyst agent through `Scope.spawn` (so its compute is
+ * metered by the conserved pool), drains its single settlement, and enforces the trace-derived
+ * firewall before returning. The `scope` is the SAME scope the combinator is draining its children
+ * from — the analyst is spawned as a sibling and its result is read off `scope.next()` in cursor
+ * order, replay-safe like any other child.
+ *
+ * Fail loud (no silent empty findings):
+ *  - the pool refuses the analyst spawn → `AnalystError` (the steer would otherwise run on nothing)
+ *  - the analyst settles `down` → `AnalystError` (a broken capture path, not a verdict)
+ *  - the analyst returns a non-array → `PlannerError`
+ *  - any finding cites judge-derived metric evidence → `PlannerError` via the firewall
+ */
+declare function createScopeAnalyst<D>(scope: Scope<Outcome<D>>, options: CreateScopeAnalystOptions<D>): ScopeAnalyst<D>;
+/**
+ * Build the `SteerContext` a combinator reads to steer (its `loopUntil.until`, `widen` gate, any
+ * future steer). One place enforces the firewall: `findings` is asserted trace-derived before it is
+ * surfaced, and `lastValidScore` is provided for OBSERVABILITY only — a combinator that steers off
+ * it re-introduces selector = judge, the coupling the architecture forbids.
+ *
+ * `findings` is re-asserted here even when it came from `createScopeAnalyst` (which already asserted
+ * it): the assertion is cheap and idempotent, and a `SteerContext` may be built from findings that
+ * arrived by another path (a caller-supplied diagnosis). Belt-and-suspenders on the one coupling
+ * that must never leak.
+ */
+declare function buildSteerContext<D>(findings: ReadonlyArray<AnalystFinding>, settledSoFar: ReadonlyArray<Settled<Outcome<D>>>): SteerContext<D>;
+
+/**
+ * @experimental
+ *
+ * The generic combinator library — the content-free act-bodies the wave's §1 contract froze.
+ *
+ * Each export is a `CombinatorShape<Task, D>` (an alias of `LoopShape<Task, D>`): a factory
+ * `(ShapeContext) => Agent<Task, Outcome<D>>` whose `act` runs ONE composition shape over the
+ * keystone `Scope` — spawn children through `ctx.spawnChild` + `scope.spawn`, drain settlements
+ * via `scope.next()`, select across `done` children with the SINGLE-SOURCED `settledToIteration`
+ * + `defaultSelectWinner` (selector≠judge — never a re-rank behind the driver), and synthesize a
+ * terminal `Outcome<D>`.
+ *
+ * The shapes carry NO domain: a "research sweep over angles" is `fanout(angles, { synthesize })`
+ * under a research persona; a "code build test" is `pipeline([plan, implement, integrate])` under
+ * a coder persona. The SHAPE is here; the model/prompt/role/goal live on the `Persona` + task,
+ * threaded to each child verbatim by the spec-objects the builders take. No model name, prompt,
+ * role, or domain noun appears below.
+ *
+ * Two fail-loud invariants every combinator honors: a child the conserved pool cannot admit is a
+ * CONCRETE blocker (never an eager over-fan, never a silent drop), and a `blocked` outcome always
+ * names at least one blocker (a shape that cannot finish MUST say why — `blocked([])` throws).
+ */
+
+/**
+ * `pipeline(stages)` — run the stages in order, feeding each stage's `done` deliverable into the
+ * next stage's task. The first stage that ends `blocked` (a child that went down, a child the
+ * pool would not admit, or a stage whose `collect` chose to block) short-circuits — its blockers
+ * ARE the pipeline's blockers, never coerced past a failed stage. The terminal stage's `done`
+ * deliverable is the pipeline's deliverable.
+ */
+declare function pipeline<Task, D>(stages: ReadonlyArray<PipelineStage<Task, unknown, unknown>>): CombinatorShape<Task, D>;
+/**
+ * `fanout(items, opts)` — spawn one child per item in a single round (bounded by the conserved
+ * pool's fail-closed admission), drain via `scope.next()`, then either synthesize over the
+ * gathered settlements (one SEPARATE synthesis child) or return the best-valid child via the
+ * single-sourced selector. A round that admitted zero children, or whose synthesis child could
+ * not be admitted, is a concrete blocker.
+ */
+declare function fanout<Task, Item, D>(items: ReadonlyArray<Item>, opts: FanoutOptions<Item, D>): CombinatorShape<Task, D>;
+/**
+ * `loopUntil(seed, spec)` — one `step` child per round; `fold` accumulates each settlement into
+ * the running state; `until` (reading the round's trace findings, NOT a fresh raw verdict) is
+ * the deployable stop. The conserved pool IS the loop bound: once `spawn` fails closed the loop
+ * stops. A loop that exhausted the pool without `until` ever satisfying is a concrete blocker.
+ *
+ * Findings are threaded through the `SteerContext` firewall in the analyst seam (`analyst.ts`);
+ * absent a wired analyst on this surface the firewall stays dormant and `until` is consulted with
+ * an empty findings array — never a fabricated finding (fail-loud honesty over a silent default).
+ */
+declare function loopUntil<Task, State, D>(seed: State, spec: LoopUntilSpec<Task, State, D>): CombinatorShape<Task, D>;
+/**
+ * `panel(spec)` — spawn the M judge children over the SAME artifact, drain their settlements,
+ * and fold them into a panel verdict via the pure WRITE-ONLY `merge` (a judge's output never
+ * reaches another judge's task; the merge never spawns or re-ranks). A `down` judge carries no
+ * verdict and is excluded from the merge denominator. A panel that admitted no judge is a
+ * concrete blocker before `merge` is consulted.
+ */
+declare function panel<Task, Artifact, D>(spec: PanelSpec<Artifact, D>): CombinatorShape<Task, D>;
+/**
+ * `verify(spec)` — an IMPLEMENT child produces a candidate, then a SEPARATE VERIFIER child grades
+ * it; only a `valid` verifier verdict ships. Any other outcome (implement down, verifier down,
+ * verifier verdict absent or not `valid`) is a concrete blocker carrying the failure verbatim —
+ * never a coerced "done". The implement child does not grade itself.
+ */
+declare function verify<Task, Candidate, D>(spec: VerifySpec<Task, Candidate, D>): CombinatorShape<Task, D>;
+/**
+ * `widen(spec)` — the streaming spawn-on-completion driver. Spawns the seed lineages, then REACTS
+ * to each `scope.next()`: on every settled child it consults `spec.gate.decide` and, when the gate
+ * returns `widen`, spawns AT MOST ONE more child toward the chosen lineage under the remaining
+ * conserved pool. `promising` is derived from the round's trace findings (the analyst seam),
+ * never a child's raw `verdict` — and the default gate (`flatWidenGate`) never widens, so the R2
+ * firewall stays dormant. Terminal selection is `spec.synthesize` over every settled lineage.
+ *
+ * No analyst is wired on this frozen surface, so `decide` is consulted with an empty findings
+ * array; a flat gate ignores it. A non-flat gate that wants findings reads them through the
+ * `SteerContext` firewall the analyst seam owns — never fabricated here.
+ */
+declare function widen<Task, Seed, D>(spec: WidenSpec<Seed, D>): CombinatorShape<Task, D>;
+/**
+ * The flat default `ScopeWidenGate` — never widens, keeping the R2 selector≠judge collision
+ * dormant. A gate run passes this explicitly; a test asserts the default is flat.
+ */
+declare function flatWidenGate<D>(): ScopeWidenGate<D>;
+
+/**
+ * @experimental
+ *
+ * The cross-run corpus (G2) — the learning-flywheel's durable accreted-fact store.
+ *
+ * `Corpus` is DISTINCT from the per-run `SpawnJournal` (decisions/replay) and `ResultBlobStore`
+ * (payloads): a `CorpusRecord` is a FACT one run LEARNED that a FUTURE run reads back (the
+ * world-model), not a replay input. This module owns the two impls the wave surface pins —
+ * `InMemoryCorpus` and `FileCorpus` (JSONL, append-only) — plus `renderCorpusToInstructions`,
+ * the READ side that projects accreted facts into a fresh `AgentProfile`'s instruction seams.
+ *
+ * The boundary is fail-loud, typed-outcome: `append` is idempotent on an identical record and
+ * returns a typed error (never throws, never a silent overwrite) on a conflicting re-append under
+ * the same `id`. Malformed records — a structurally-invalid `CorpusRecord` from disk or a caller —
+ * fail loud (the validator throws), since a corpus that silently accepts garbage would poison
+ * every downstream run that reads it back.
+ */
+
+/**
+ * In-memory `Corpus`. Keyed by record `id`; `append` validates the record, is idempotent on an
+ * identical re-append, and returns a typed `{ succeeded: false }` on a conflicting re-append under
+ * the same `id` (never overwrites). `query` routes through the single-sourced `applyFilter`.
+ */
+declare class InMemoryCorpus implements Corpus {
+    private readonly byId;
+    append(record: CorpusRecord): Promise<{
+        succeeded: true;
+    } | {
+        succeeded: false;
+        error: string;
+    }>;
+    query(filter: CorpusFilter): Promise<ReadonlyArray<CorpusRecord>>;
+}
+/**
+ * JSONL on disk — one validated `CorpusRecord` per line, append-only. `query` replays the whole
+ * file, validating every line (a malformed line fails loud — a corrupted corpus must never read
+ * back silently) and folding by `id`: a later identical line dedups, a later conflicting line
+ * under the same `id` is a corruption (fail loud). `append` first replays to enforce the same
+ * idempotence/conflict contract as the in-mem impl, then fsyncs the new line so a crash between
+ * writes never loses an acknowledged fact. Shares the JSONL append-line spine with the spawn
+ * journal, but the interface stays separate (a learned fact is not a replay record).
+ */
+declare class FileCorpus implements Corpus {
+    private readonly path;
+    constructor(path: string);
+    append(record: CorpusRecord): Promise<{
+        succeeded: true;
+    } | {
+        succeeded: false;
+        error: string;
+    }>;
+    query(filter: CorpusFilter): Promise<ReadonlyArray<CorpusRecord>>;
+    private load;
+    private appendLine;
+}
+/**
+ * The learning-flywheel READ side. Queries the corpus through `filter`, renders the matching facts
+ * (most-confident first, capped by `maxLines`) into instruction lines, and returns a FRESH
+ * `AgentProfile` with them merged in — never mutates the input profile. Default `target: 'prompt'`
+ * appends the lines to `prompt.instructions[]` (the additive append-line seam); `target:
+ * 'resources'` folds them into the single-blob `resources.instructions` string (preserving any
+ * existing blob, but failing loud on a non-string existing blob — a `resources.instructions` that
+ * was already an `AgentProfileResourceRef` cannot be string-appended without dropping it).
+ *
+ * An empty query result returns a fresh COPY of the profile with no instruction change (a valid
+ * "nothing learned yet" read, not an error).
+ */
+declare function renderCorpusToInstructions(opts: RenderCorpusToInstructionsOptions): Promise<AgentProfile$1>;
+
+/**
+ * @experimental
+ *
+ * The personify layer impl — `definePersona` (the thin builder) + `runPersonified` (composes
+ * the persona + chosen shape onto the keystone `Supervisor`), plus `createShapeContext`, the
+ * seam that hands a shape its spawn helpers without it touching the registry.
+ *
+ * This file adds NO engine: `runPersonified` is `createSupervisor().run(rootAgent, task, …)`
+ * where `rootAgent` is the persona's chosen `LoopShape` applied to a `ShapeContext`. All the
+ * conserved-budget / journal / abort / typed-result machinery is the keystone's; this layer
+ * only wires the persona's CONTENT (root spec + directive + context + seams) into it.
+ *
+ * One non-obvious invariant it must honor: `createSupervisor().run` builds the root `Scope`
+ * with an EMPTY seam bag (`seams: {}`), so the built-in metered runtimes (router/sandbox/cli)
+ * cannot read their seams off `ExecutorContext` through the default supervisor path. A persona
+ * that supplies raw `seams` is therefore wrapped here into a registry whose resolved factories
+ * receive a ctx with the persona seams merged in — so a persona never has to pre-close its
+ * factories by hand. A persona may instead supply a fully-built `registry` and skip the wrap.
+ */
+
+/**
+ * Build a frozen `Persona`. Fails loud on the executors-supplied invariant: a persona with
+ * neither a pre-built registry nor a seam bag cannot resolve its built-in runtimes, so it is
+ * unrunnable — refuse it at definition time, not at the first spawn. Pure; no I/O.
+ */
+declare function definePersona<D = unknown>(input: DefinePersonaInput<D>): Persona<D>;
+/**
+ * Compose the persona + chosen shape onto a fresh keystone `Supervisor`. Resolves the shape
+ * (a factory verbatim, or a registered name through `builtinShapes`), applies it to a
+ * `ShapeContext`, and runs the resulting root `Agent` to a typed `SupervisedResult<Outcome>`.
+ * Fail loud on an unknown shape name or an unresolvable persona registry — never a silent
+ * default-shape fallback.
+ */
+declare function runPersonified<Task, D>(options: RunPersonifiedOptions<Task, D>): Promise<SupervisedResult<Outcome<D>>>;
+
+/**
+ * @experimental
+ *
+ * The loop-shape registry — the OPEN, content-free extension point for the personify layer.
+ *
+ * A `LoopShape` is reusable STRUCTURE (how to decompose / fan out / verify / synthesize),
+ * parameterized by a persona's CONTENT. The registry lets a caller resolve a composed shape by
+ * NAME: register a factory once, then `runPersonified({ shape: '<name>' })` resolves it with zero
+ * edits elsewhere. `register` fails loud on a duplicate; `resolve` returns a typed outcome so an
+ * unknown name is a named error, never a silent default.
+ *
+ * No shape is pre-registered: the generic combinators (`pipeline`/`fanout`/`loopUntil`/`panel`/
+ * `verify`/`widen`) take spec arguments, so they are not bare zero-arg factories — a caller that
+ * wants name-resolution registers its own COMPOSED shape (a combinator already applied to its
+ * spec) on a registry instance. The registry carries SHAPE only; the domain lives on the persona.
+ */
+
+/**
+ * Build a fresh open `ShapeRegistry`. A factory is stored type-erased and re-cast on resolve — the
+ * caller asserts the `<Task, D>` it expects, exactly as the executor registry stores its factories.
+ */
+declare function createShapeRegistry(): ShapeRegistry;
+/** The default registry `runPersonified` resolves a shape name against. Empty by construction —
+ *  a caller registers its own composed shapes; the engine ships no domain shape. */
+declare const builtinShapes: ShapeRegistry;
+/** Register a composed shape on the default `builtinShapes` registry — the one-call extension
+ *  point a caller invokes so its shape is resolvable by name with zero edits to the engine. */
+declare function registerShape<Task, D>(name: string, factory: LoopShape<Task, D>): void;
+
+/**
+ * @experimental
+ *
+ * Trajectory trace + cost ledger — the post-hoc tree reconstructor (§4 of `wave-types`).
+ *
+ * `trajectoryReport` rebuilds the WHOLE realized spawn tree from the durable
+ * `SpawnJournal` (+ optionally the `ResultBlobStore` for `done` artifacts): every node
+ * (driver AND leaf), the real parent/child edges, each node's terminal status, its OWN
+ * conserved `Spend`, and the `Spend` ROLLED UP over its subtree. Roll-up is a post-order
+ * fold over the parent edges: a node's `rolledUpSpend` is its own spend plus every
+ * descendant's, so a driver is charged for the fanout it caused — the root's roll-up is
+ * the whole run's conserved total (tokens + usd + iterations + ms).
+ *
+ * `equalKOnCost` compares separate runs (arms) on that conserved COST, not on raw
+ * iteration COUNT. The sandbox executor reports tokens/usd INCLUSIVE of a leaf's internal
+ * sub-agent fanout, so charging an arm by `total.tokens`/`total.usd` (not by how many
+ * `next()` cursors it logged) closes the leaf-fanout confound: a treatment leaf that fanned
+ * out internally pays for it in cost, where a per-iteration count would hide it. The
+ * within-run conserved pool already guarantees `Σk` equal by construction; this check is the
+ * CROSS-run analogue the pool cannot reach — proving equal compute before any win is claimed.
+ *
+ * Pure over the journal/blobs — no live agent calls; safe to run on a finished run's log.
+ */
+
+/**
+ * Reconstruct the whole spawn tree for `root` with per-node + rolled-up `Spend`. Reads the
+ * journal for structure + spend and, when `withOutputs`, the blob store for each `done`
+ * node's artifact. Fail loud on a tree that was never journaled, a settle/cancel for an
+ * un-spawned node (a corrupted log), or — under `withOutputs` — a `done` node whose blob the
+ * store cannot rehydrate (a silent gap would mis-cost or mis-evidence the tree).
+ */
+declare function trajectoryReport(journal: SpawnJournal, blobs: ResultBlobStore, root: NodeId, options?: TrajectoryReportOptions): Promise<TrajectoryReport>;
+/**
+ * Assert the arms are comparable at EQUAL conserved COST (tokens + usd), NOT raw iteration
+ * count. Compares each arm's root-rolled-up `total` on the two conserved channels: an arm is
+ * within-tolerance when the per-channel spread (max − min across arms) over the median is
+ * `≤ tolerance`. Pure over the reports — no I/O. Fails loud on an empty arm list (nothing to
+ * compare) so a vacuous "equal" is never returned.
+ */
+declare function equalKOnCost(arms: ReadonlyArray<EqualKArm>, options?: EqualKOnCostOptions): EqualKVerdict;
+
+/**
+ * Bridge a finished `runLoop` into an agent-eval campaign / profile-matrix
+ * dispatch.
+ *
+ * `runProfileMatrix` (and `runCampaign`) run the backend-integrity guard over
+ * the token usage a dispatch reports through `ctx.cost`. A dispatch that wraps
+ * `runLoop` must forward the loop's cost AND token usage, or the guard reads
+ * the run as a stub and throws. `reportLoopUsage` is that one line:
+ *
+ *   const dispatch: ProfileDispatchFn<S, A> = async (profile, scenario, ctx) => {
+ *     const result = await runLoop({ ...optsFor(profile, scenario), ctx: loopCtx })
+ *     reportLoopUsage(ctx, result)
+ *     return result.winner?.output as A
+ *   }
+ *
+ * Typed structurally against the campaign `DispatchContext.cost` so this module
+ * stays free of an agent-eval import — it works with any cost meter exposing
+ * `observe` + `observeTokens`.
+ */
+
+/** The slice of an agent-eval campaign `DispatchContext.cost` this needs. */
+interface UsageSink {
+    observe(amountUsd: number, source: string): void;
+    observeTokens(usage: LoopTokenUsage): void;
+}
+/**
+ * Forward a `LoopResult`'s aggregated cost + token usage into a campaign cost
+ * meter so the backend-integrity guard sees real LLM activity. `source`
+ * defaults to `'loop'`.
+ */
+declare function reportLoopUsage<Task, Output, Decision>(cost: UsageSink, result: Pick<LoopResult<Task, Output, Decision>, 'costUsd' | 'tokenUsage'>, source?: string): void;
+
+/**
+ * @experimental
+ *
+ * `acquireSandbox` — cold-start-resilient sandbox acquisition. Eliminates the
+ * "create timed out at the proxy" failure mode conceptually by DECOUPLING "the
+ * create HTTP call returned" from "the sandbox is ready":
+ *
+ *   - Create is initiated with a known `name`.
+ *   - Readiness is observed from the sandbox's own `status` (`refresh()` polls
+ *     true state), NOT from whether the create call returned in time.
+ *   - If the create call itself times out at a gateway (502/503/504/522/524 or
+ *     a transport timeout), provisioning is still running server-side — so we
+ *     find the named sandbox via `list()` and wait for it to reach `running`.
+ *
+ * Result: a scale-from-zero cold start (node boot + host-agent registration,
+ * minutes) can no longer surface as a create failure behind a ~100s proxy
+ * limit. The loop becomes indifferent to whether the host pool is warm or cold.
+ *
+ * Invariant: an instance reporting no `status` (the minimal test fakes) is
+ * treated as ready; only an explicit `pending`/`provisioning` status triggers
+ * waiting, and only a retryable THROW triggers the find-by-name path. Real
+ * errors (auth, validation, budget) fail loud. A box that is created (or found)
+ * but never reaches `running` (abort, terminal status, budget) is torn down
+ * before the failure propagates, so an abort storm during cold start does not
+ * leak live sandboxes.
+ */
+
+/** @experimental */
+interface AcquireOptions {
+    /**
+     * Total budget for the sandbox to reach `running`, covering on-demand node
+     * cold-start. Default 600_000ms — matches the orchestrator's pending-host
+     * registration window so we never give up before the platform itself would.
+     */
+    readyTimeoutMs?: number;
+    /** Poll interval while waiting for `running` / for the named sandbox to appear. */
+    pollIntervalMs?: number;
+    /** Cancellation (user abort). Distinct from create-call timeouts. */
+    signal?: AbortSignal;
+    /** Stamp a name so a timed-out create is recoverable by lookup. Auto-generated if absent. */
+    name?: string;
+    /** Clock override for deterministic tests. */
+    now?: () => number;
+    /** Sleep override for deterministic tests. */
+    sleep?: (ms: number) => Promise<void>;
+}
+/** @experimental */
+declare function acquireSandbox(client: SandboxClient, options: CreateSandboxOptions, acquire?: AcquireOptions): Promise<SandboxInstance>;
+
+/**
+ * @experimental
+ *
+ * Capability probe for the loop kernel's backend-blind lineage seams. The
+ * kernel must NEVER ask "is this Docker or Firecracker?"; it asks "can this
+ * platform fork a checkpoint?" via `client.criuStatus()` and degrades to fresh
+ * boxes when the answer is no. CRIU availability is a per-platform fact, so the
+ * probe is memoized per client — one network round-trip, reused across every
+ * fanout in the run.
+ *
+ * Invariant: a client with no `criuStatus` method (the loop's test fakes, the
+ * raw SDK before it grew the probe) reports `canFork = false`. The seam is
+ * fail-CLOSED — never assume forking works, only enable it on a positive probe.
+ */
+
+/**
+ * What the loop kernel is allowed to know about a sandbox backend: a single
+ * capability bit, never the backend's identity. `canFork` gates the
+ * checkpoint+fork fanout path; everything else (session continuation) is a
+ * universal SDK feature that needs no probe.
+ *
+ * @experimental
+ */
+interface SandboxCapabilities {
+    /**
+     * True only when `client.criuStatus()` returned `{ available: true }`. When
+     * false, a fork-enabled fanout degrades to independent fresh boxes — same
+     * result, no shared context prefix.
+     */
+    canFork: boolean;
+}
+/**
+ * Probe (and memoize per client) what the loop may rely on. A client without a
+ * `criuStatus` method, or whose probe rejects, yields `canFork = false` — a
+ * failed probe must never claim a capability the platform may not have. The
+ * promise is cached so concurrent fanout branches share one round-trip.
+ *
+ * @experimental
+ */
+declare function probeSandboxCapabilities(client: SandboxClient): Promise<SandboxCapabilities>;
+/**
+ * Narrowed view of the optional CRIU probe. The loop-side `SandboxClient`
+ * does not require `criuStatus`; this widens it optionally so the probe can be
+ * read without importing sandbox-backend specifics. @experimental
+ */
+interface CriuCapableClient {
+    criuStatus?: () => Promise<{
+        available: boolean;
+        criuVersion?: string;
+        reason?: string;
+    }>;
+}
+
+/**
+ * Sandbox-event → runtime-event mapping.
+ *
+ * The sandbox SDK emits a polymorphic `SandboxEvent = { type, data, id? }`
+ * whose `type` vocabulary is backend-determined (opencode, etc.) rather than
+ * enumerated by the SDK. Two consumers project it:
+ *   - the loop kernel's cost ledger (`extractLlmCallEvent`) — sums usage off
+ *     every cost-bearing event, regardless of stream shape;
+ *   - the `AgentRuntime.act` streaming contract (`mapSandboxEvent`) — projects
+ *     incremental events to the `RuntimeStreamEvent` chat-UX vocabulary.
+ *
+ * Both live here so the empirically-observed `type` vocabulary has one home.
+ */
+
+/**
+ * Extract a `RuntimeStreamEvent`-shaped `llm_call` from a sandbox event when
+ * the event carries usage/cost data. Returns `undefined` for non-cost events
+ * so the kernel can iterate the full stream without branching.
+ *
+ * Canonical cost-carrying types observed in the wild:
+ *   - `llm_call` — `data: { model, tokensIn, tokensOut, costUsd, ... }`
+ *   - `message.completed` / `result` — `data: { usage: { inputTokens,
+ *      outputTokens, totalCostUsd? } }`
+ *   - `cost.usage` / `usage` — same shape under a dedicated type
+ *
+ * Numeric coercion is strict: `Number.isFinite` gates every accumulator write
+ * so a sentinel `NaN` from a misbehaving backend cannot poison the ledger.
+ */
+declare function extractLlmCallEvent(event: SandboxEvent, agentRunName: string): (RuntimeStreamEvent & {
+    type: 'llm_call';
+}) | undefined;
+/**
+ * Project one `SandboxEvent` onto the `RuntimeStreamEvent` chat-UX vocabulary,
+ * for runtimes that bridge a sandbox `streamPrompt` into the
+ * `AgentRuntime.act` streaming contract. Returns `undefined` for events that
+ * have no faithful projection — the raw stream is preserved separately for the
+ * `OutputAdapter`, so an unmapped event never loses data.
+ *
+ * Mapped (the task-optional incremental variants — no synthesized task
+ * lifecycle, no guessed tool-part shapes):
+ *   - `message.part.updated` text part → `text_delta`
+ *   - `message.part.updated` reasoning/thinking part → `reasoning_delta`
+ *   - cost-bearing events → `llm_call` (shared with the ledger extractor)
+ *
+ * The opencode backend emits incremental text as
+ * `{ type: 'message.part.updated', data: { part: { type, text }, delta } }`;
+ * `delta` is the increment, `part.text` the running accumulation.
+ */
+declare function mapSandboxEvent(event: SandboxEvent, opts?: {
+    agentRunName?: string;
+}): RuntimeStreamEvent | undefined;
+
+/**
+ * @experimental
+ *
+ * `SandboxLineage` — the backend-blind owner of box + session handles for a
+ * single `runLoop` invocation. It exists so `run-loop.ts` never references a
+ * backend (Docker / Firecracker): the lineage turns "continue this session" and
+ * "fork this branch" into capability-gated sandbox-SDK calls and degrades to
+ * fresh boxes when a capability is absent.
+ *
+ * Three operations, mirroring the kernel's per-iteration choices:
+ *   - `start(spec, prompt)`  → a fresh box; the FIRST `streamPrompt` carries a
+ *      minted `sessionId` so later `continue` calls reuse the same server-side
+ *      conversation instead of re-injecting prior context as prompt text.
+ *   - `continue(handle, prompt)` → the SAME box, `streamPrompt({ sessionId })`.
+ *      The context lives in the sandbox; the prompt is only the new turn. Before
+ *      streaming it ASSERTS the session is still live server-side (via
+ *      `box.session(id).status()`): if the platform never honored the
+ *      client-minted id (or reaped it), `status()` is `null` and `continue`
+ *      fails loud rather than silently re-running the turn without prior context.
+ *   - `fork(handle, n, ...)` → when `canFork`, `checkpoint({ leaveRunning })` on
+ *      the parent then `fork(checkpointId)` × n so N branches inherit a shared
+ *      context prefix; otherwise N independent fresh boxes (same result, no
+ *      prefix). Either way each branch streams its own turn. Child-box creation
+ *      is bounded by the lineage's `maxConcurrency` — a 20-way fanout under a
+ *      concurrency cap of 2 provisions boxes in bounded waves, not all at once.
+ *
+ * Invariant: the lineage OWNS every box it starts or forks and tears them all
+ * down on `teardown()` (or earlier via `prune`). It never tears down a box
+ * mid-flight — the kernel decides when a handle is done. Streaming itself stays
+ * in `run-loop.ts`; the lineage only hands back the live `streamPrompt` iterable
+ * so the kernel keeps ownership of event collection, cost accounting, and trace
+ * emission.
+ */
+
+/**
+ * A live box plus the session that threads its iterations together. Handed back
+ * by `start`/`fork`, passed into `continue`/`fork` to descend from. Opaque to
+ * the kernel beyond `box` (for placement/teardown) and `sessionId` (trace).
+ *
+ * @experimental
+ */
+interface SandboxLineageHandle {
+    /** The owned, running sandbox this handle drives. */
+    box: SandboxInstance;
+    /**
+     * Stable session id threaded through this box's `streamPrompt` calls. Minted
+     * by the lineage on `start`; reused on `continue` so the server continues the
+     * same conversation. A forked handle starts a fresh session on its new box —
+     * the shared context comes from the checkpoint, not a shared session id.
+     */
+    sessionId: string;
+}
+/**
+ * Owns box + session handles for one loop run and offers the three
+ * capability-gated lifecycle moves. Construct via `createSandboxLineage`.
+ *
+ * @experimental
+ */
+interface SandboxLineage {
+    /**
+     * Acquire a fresh box and begin a new session on it. Returns the handle and
+     * the live `streamPrompt` iterable for the first turn (caller drains it).
+     */
+    start(spec: AgentRunSpec<unknown>, prompt: string, signal: AbortSignal): Promise<{
+        handle: SandboxLineageHandle;
+        events: AsyncIterable<SandboxEvent>;
+    }>;
+    /**
+     * Continue an existing handle's session with one more turn on the SAME box.
+     * The prior context is server-side; `prompt` is only the new turn. Asserts the
+     * session is still known to the sandbox first (fail-loud) so a platform that
+     * silently dropped the client-minted session id surfaces as an error instead
+     * of a contextless turn the caller mistakes for a real continuation.
+     */
+    continue(handle: SandboxLineageHandle, prompt: string, signal: AbortSignal): Promise<AsyncIterable<SandboxEvent>>;
+    /**
+     * Branch `count` children from `parent`. When the platform can fork, each
+     * child inherits `parent`'s checkpoint — and therefore the parent's IMAGE and
+     * PROFILE: under a real fork `specs[i]` does NOT re-select a per-branch
+     * profile (the SDK forks the running box, it can't swap the image). `specs[i]`
+     * picks the per-branch profile ONLY on the degraded fresh-box path (no CRIU).
+     * A heterogeneous-profile fanout therefore homogenizes to the parent's profile
+     * when fork is available — pass a single shared spec for forked fanouts, or
+     * use `random@k` (no fork) when branches must differ. Each child's first turn
+     * streams `prompts[i]`. Child-box creation is bounded by `maxConcurrency`.
+     */
+    fork(parent: SandboxLineageHandle, prompts: string[], specs: AgentRunSpec<unknown>[], signal: AbortSignal): Promise<{
+        handle: SandboxLineageHandle;
+        events: AsyncIterable<SandboxEvent>;
+    }[]>;
+    /**
+     * Destroy every owned box whose handle is NOT in `keep`, freeing it before
+     * loop end. The kernel calls this after a round when it can prove no future
+     * round will descend from the pruned boxes (deterministic, monotonic branch
+     * selection); boxes still reachable as a future branch source are retained.
+     * Best-effort, bounded, parallel — a failed delete never throws.
+     */
+    prune(keep: Iterable<SandboxLineageHandle>): Promise<void>;
+    /** Destroy every box this lineage owns. Best-effort, bounded, parallel. */
+    teardown(): Promise<void>;
+}
+/**
+ * Build a lineage bound to one client + its probed capabilities. The
+ * capabilities are passed in (not re-probed) so the kernel probes once per run
+ * and the lineage stays a pure function of "what this platform can do".
+ *
+ * @experimental
+ */
+declare function createSandboxLineage(client: SandboxClient, capabilities: SandboxCapabilities, options?: {
+    maxConcurrency?: number;
+    streaming?: 'sse' | 'poll';
+}): SandboxLineage;
+/**
+ * Loop-side widening of the box's optional checkpoint method. The
+ * `SandboxClient`/`SandboxInstance` surface the kernel relies on does not
+ * require checkpointing; this reads it optionally so the lineage can probe-gate
+ * without importing sandbox-backend specifics. @experimental
+ */
+interface CheckpointCapableBox {
+    checkpoint?: (options?: {
+        leaveRunning?: boolean;
+        tags?: string[];
+    }) => Promise<{
+        checkpointId: string;
+    }>;
+}
+/** Loop-side widening of the box's optional fork method. @experimental */
+interface ForkCapableBox {
+    fork?: (checkpointId: string, options?: {
+        name?: string;
+    }) => Promise<SandboxInstance>;
+}
+/**
+ * Loop-side widening of the box's optional session accessor. The real
+ * `SandboxInstance` exposes `session(id).status()`; the loop reads it optionally
+ * so `continue` can assert session liveness without requiring it of the test
+ * fakes. `status()` resolves `null` when the id is unknown to the sandbox.
+ * @experimental
+ */
+interface SessionCapableBox {
+    session?: (id: string) => {
+        status: () => Promise<unknown | null>;
+    };
+}
+
+/**
+ * `openSandboxRun` — the ONE harness-agnostic seam for running an agent in a
+ * sandbox over a persistent artifact: run it, stream it, RESUME the same session
+ * across turns. Domain-agnostic: a coding agent, a research agent, a tax/legal
+ * agent — all flow through this; the domain lives only in the `Deliverable<Out>`
+ * the caller supplies, never in a per-domain copy of this function.
+ *
+ * It is a thin facade (NOT a new layer) over code that already exists and is
+ * already hardened:
+ *   - `acquireSandbox` — cold-start / 502-503-504 / gateway-timeout recovery,
+ *   - `buildBackendOptions` — the harness IS `backend.type` (opencode / codex /
+ *     claude-code / kimi-code / hermes / pi); the only "which agent" knob,
+ *   - `createSandboxLineage` — `start` mints a session; `resume` continues the
+ *     SAME server-side session with a fail-loud `assertSessionLive`.
+ *
+ * The one genuinely-new piece is {@link Deliverable}: it widens the pure
+ * `OutputAdapter.parse(events)` to ALSO admit a post-turn read off the box FS —
+ * the structural gap that made the bench gates hand-roll `box.fs.read`, because a
+ * large produced file (a git diff, a generated document) truncates in the chat
+ * stream and a pure events-parser cannot reach the workspace. Per the SDK, a
+ * RELATIVE `deliverable.path` resolves from the workspace root and an ABSOLUTE one
+ * (e.g. `/tmp/solution.patch`) reads the container filesystem directly — both are
+ * valid; pick the one the agent actually wrote to. Avoid `..` traversal segments.
+ *
+ * What this deliberately does NOT do (so it stays a facade, not slop): no custom
+ * reconnect/replay (the SDK + platform own per-session buffering + `Last-Event-ID`);
+ * no fork verb (platform CRIU is probe-gated and currently absent — fork lives in
+ * `SandboxLineage.fork` behind the capability probe, surfaced only if it returns).
+ * It is also distinct from `runLoop`: `runLoop` is the multi-round, driver-driven
+ * kernel (fresh box per round, events deliverable); this is a SINGLE rollout +
+ * artifact-or-events deliverable + resume over ONE persistent box.
+ */
+
+/**
+ * @experimental
+ * How a typed deliverable `Out` is materialized from a finished turn.
+ * - `events`   — pure parse over the event array (identical to `OutputAdapter`).
+ * - `artifact` — read a file off the box AFTER the turn drains, then map it (+ the
+ *                events). For diffs/codebases/documents that don't fit the chat
+ *                stream. `path` relative ⇒ workspace root; absolute ⇒ container FS.
+ */
+type Deliverable<Out> = {
+    kind: 'events';
+    fromEvents: (events: SandboxEvent[]) => Out;
+} | {
+    kind: 'artifact';
+    path: string;
+    fromArtifact: (raw: string, events: SandboxEvent[]) => Out;
+};
+/**
+ * @experimental
+ * One finished turn over the artifact. A failed FS read is surfaced in `readError`
+ * (never masked as an empty deliverable) so a caller distinguishes "agent produced
+ * nothing" from a transport/FS fault.
+ */
+interface TurnResult<Out> {
+    out: Out;
+    events: SandboxEvent[];
+    readError?: string;
+}
+/** @experimental A live run over ONE persistent artifact (box + session). Close it
+ *  when done — `close()` tears the box down. */
+interface SandboxRun<Out> {
+    readonly box: SandboxInstance;
+    readonly sessionId: string;
+    /** First turn over the fresh box (mints the session). Throws if already started. */
+    start(prompt: string): Promise<TurnResult<Out>>;
+    /** Continue THE SAME session over THE SAME artifact — a resumed turn/rollout. */
+    resume(prompt: string): Promise<TurnResult<Out>>;
+    close(): Promise<void>;
+}
+/** @experimental */
+interface OpenSandboxRunOptions {
+    /** Profile + sandbox env/overrides. `sandboxOverrides.backend.type` is the harness. */
+    agentRun: AgentRunSpec<string>;
+    signal: AbortSignal;
+    /** Optional execution-scoped observers. Hook failures never fail the run. */
+    hooks?: RuntimeHooks;
+    /** Stable run id for trace joins. Defaults to a short runtime-minted id. */
+    runId?: string;
+    /** Optional benchmark/scenario id carried into emitted hook events. */
+    scenarioId?: string;
+    /** Test seam for deterministic hook timestamps. Defaults to `Date.now`. */
+    now?: () => number;
+    /** Bounds box-creation bursts inside lineage fanout. Default from lineage. */
+    maxConcurrency?: number;
+    /** Base backoff (ms) for retrying a transient artifact `fs.read` failure; the i-th
+     *  retry waits `readRetryDelayMs * i`. Default 1000. Set 0 to disable the wait (tests). */
+    readRetryDelayMs?: number;
+}
+/**
+ * @experimental
+ * Open a sandbox run. Harness-agnostic: the harness lives in
+ * `options.agentRun.sandboxOverrides.backend.type`, so opencode/codex/claude-code/
+ * kimi-code all flow through this one entrypoint with identical env/auth wiring.
+ */
+declare function openSandboxRun<Out>(client: SandboxClient, options: OpenSandboxRunOptions, deliverable: Deliverable<Out>): Promise<SandboxRun<Out>>;
+
+/**
+ * @experimental
+ *
+ * The conserved budget reservation pool — the invariant the whole instrument
+ * rests on (critique M5/B3). One root `Budget` becomes a conserved pool of three
+ * quantities (tokens, usd, iterations) plus an absolute deadline. Children RESERVE
+ * atomically at spawn and RECONCILE at settle:
+ *
+ *   total ≡ free + reserved + committed          (invariant, always)
+ *
+ * `reserve` moves a child's whole ceiling from `free` → `reserved` and FAILS CLOSED
+ * when `free` can't cover it (never read-then-spawn overcommit, so `Σk(treatment) ≡
+ * Σk(blind)` by construction). `reconcile` releases the reservation, commits ACTUAL
+ * spend, and refunds the unspent remainder to `free`. Tokens and usd are SEPARATE
+ * channels (`LoopTokenUsage` has no `usd`); iterations are conserved alongside them.
+ *
+ * Pure and deterministic: `now()` is injected, there is no I/O, and no wall-clock or
+ * RNG read. A `reserve`/`reconcile` ticket is single-use (fail-loud on double or
+ * unknown reconcile) so a child can never refund twice.
+ */
+
+/** Opaque, single-use reservation handle returned by `reserve` and consumed by
+ *  `reconcile`. Carries the reserved ceilings so reconciliation needs no lookup. */
+interface ReservationTicket {
+    readonly id: number;
+    readonly reserved: {
+        readonly tokens: number;
+        readonly usd: number;
+        readonly iterations: number;
+    };
+}
+/** Post-reservation pool readout — the shape `Scope.budget` exposes. `tokensLeft`,
+ *  `usdLeft`, and `reservedTokens` reflect committed-but-unsettled reservations;
+ *  `deadlineMs` is the ABSOLUTE wall-clock deadline (0 when the root set none). */
+type BudgetReadout = Readonly<{
+    tokensLeft: number;
+    usdLeft: number;
+    deadlineMs: number;
+    reservedTokens: number;
+}>;
+interface BudgetPool {
+    /**
+     * Atomically reserve a child's full ceiling from the free balance. Fails closed
+     * ({ ok: false }) when the pool can't cover tokens, usd, or iterations — the
+     * caller inspects `ok` before `ticket`.
+     */
+    reserve(b: Budget): {
+        ok: true;
+        ticket: ReservationTicket;
+    } | {
+        ok: false;
+        reason: 'budget-exhausted';
+    };
+    /**
+     * Release a reservation: commit the actual `spent`, refund the unspent remainder
+     * to the free pool. Throws on an unknown or already-reconciled ticket (fail loud —
+     * a double refund would silently break conservation).
+     */
+    reconcile(ticket: ReservationTicket, spent: Spend): void;
+    /** Fold a normalized `UsageEvent` stream (or array) into a `Spend`. Tokens via
+     *  `addTokenUsage`, usd on its own channel, iterations from `'iteration'` events.
+     *  `ms` is left zero — wall-clock duration is the caller's to record, not the pool's. */
+    spendFrom(events: AsyncIterable<UsageEvent> | UsageEvent[]): Promise<Spend>;
+    /** The current readout, reflecting all outstanding reservations. */
+    readout(): BudgetReadout;
+    /** Fail loud if any reservation is still open — the conserved-pool leak detector. Called at the
+     *  supervisor's join barrier: once every child has settled, no ticket may remain (a leaked
+     *  reservation would silently break `total ≡ free + reserved + committed`). */
+    assertNoOpenTickets(): void;
+}
+/** Fold a normalized `UsageEvent` array into a `Spend`. Tokens and usd are separate
+ *  channels; iterations come from `'iteration'` events. Pure; `ms` stays zero (the
+ *  pool does not read wall-clock). */
+declare function spendFromUsageEvents(events: UsageEvent[]): Spend;
+/**
+ * Create a conserved reservation pool from a root `Budget`. `now()` is injected so the
+ * deadline readout is deterministic; defaults to `Date.now` for non-test callers. The
+ * absolute deadline is fixed at construction (`now() + budget.deadlineMs`) so the
+ * readout's `deadlineMs` is a stable wall-clock instant, not a shrinking remainder.
+ */
+declare function createBudgetPool(root: Budget, now?: () => number): BudgetPool;
+
+/**
+ * @experimental
+ *
+ * The leaf runtime — the built-in `Executor` IMPLEMENTATIONS behind the ONE
+ * open interface frozen in `./types`, plus the open resolver/registry that maps
+ * an `AgentSpec` to one of them OR accepts a bring-your-own executor verbatim.
+ *
+ * The interface is the extension point, not a closed `inline|sandbox|cli` union:
+ *   - router/inline : a direct OpenAI-compatible Router call, no box (one-shot).
+ *   - sandbox       : COMPOSES the existing `runLoop` kernel as a single-task
+ *                     leaf and surfaces its token/cost usage as `UsageEvent`s;
+ *                     forwards PR #150's optional `lineage` passthrough WITHOUT
+ *                     reinventing checkpoint/fork (streaming).
+ *   - cli           : a Halo/RLM subprocess; `budgetExempt` (no token accounting),
+ *                     excluded from the equal-k arms by construction (streaming).
+ * Every metered runtime reports through the SAME normalized `UsageEvent` channel
+ * so the conserved budget pool meters them identically. A user's own agent is
+ * first-class the moment it implements `Executor` — register it by name or
+ * pass it as `AgentSpec.executor`.
+ *
+ * Layering: `estimateCost`/`isModelPriced` are substrate primitives from
+ * `@tangle-network/agent-eval`; `runLoop`/`acquireSandbox` are runtime kernels
+ * from this package. No per-vendor adapters live here.
+ */
+
+/**
+ * Router/inline connection seam. A direct OpenAI-compatible Router endpoint —
+ * the cheapest leaf, no box, no tools. `model` overrides the profile's model
+ * hint when present; otherwise the profile's `model.default` is required.
+ */
+interface RouterSeam {
+    routerBaseUrl: string;
+    routerKey: string;
+    model?: string;
+}
+/**
+ * Sandbox executor seam. The `sandboxClient` the composed `runLoop` creates
+ * boxes through, plus the optional trace/run/lineage wiring forwarded into the
+ * loop. `lineage` is opaque here (PR #150's `RunLoopOptions.lineage`): forwarded
+ * forward-compatibly, never inspected — this executor does NOT reinvent
+ * checkpoint/fork.
+ */
+interface SandboxSeam {
+    sandboxClient: SandboxClient;
+    /** Forwarded into the composed `runLoop`'s `ctx` (trace emitter, run handle, etc.). */
+    loopCtx?: Partial<Omit<ExecCtx, 'sandboxClient' | 'signal'>>;
+    /** PR #150 `RunLoopOptions.lineage` passthrough — opaque; forwarded, not parsed. */
+    lineage?: unknown;
+    /** Hard cap on the composed loop's iterations. The budget pool reserves against
+     *  the spawn `Budget.maxIterations`; this is the leaf's own ceiling. Default 1. */
+    maxIterations?: number;
+}
+/** CLI subprocess seam. `bin` + `args` describe the Halo/RLM process to spawn. */
+interface CliSeam {
+    bin: string;
+    args?: string[];
+    /** Extra environment for the subprocess (merged over `process.env`). */
+    env?: Record<string, string>;
+    /** Working directory for the subprocess. */
+    cwd?: string;
+}
+/**
+ * cli-bridge seam. A local OpenAI-compatible bridge that fronts harness CLIs
+ * (claude-code / opencode / kimi / pi) behind one HTTP surface; `model` doubles
+ * as the harness selector (e.g. `claude-code/sonnet`, `opencode/<provider>/<model>`).
+ * `agentProfile` is the bridge-dialect profile (metadata.disallowedTools, mcp)
+ * forwarded verbatim per request — how an arm disables native tools or injects
+ * a provider search MCP.
+ */
+interface BridgeSeam {
+    bridgeUrl: string;
+    bridgeBearer: string;
+    model: string;
+    agentProfile?: Record<string, unknown>;
+    timeoutMs?: number;
+}
+/**
+ * The single built-in executor entrypoint. The backend is DATA — the cost dial a
+ * profile, an experiment config, or a replay journal can name — not an import
+ * choice. Injects the matching seam and delegates to the built-in implementation;
+ * the port stays OPEN: bring-your-own agents implement `Executor` directly and
+ * never pass through here.
+ */
+type ExecutorConfig = ({
+    backend: 'router';
+} & RouterSeam) | ({
+    backend: 'bridge';
+} & BridgeSeam) | ({
+    backend: 'cli';
+} & CliSeam) | ({
+    backend: 'sandbox';
+    harness?: BackendType;
+} & SandboxSeam);
+declare function createExecutor(config: ExecutorConfig): ExecutorFactory<unknown>;
+/**
+ * The open resolver/registry. Pre-registers the three built-ins under their
+ * runtime tags (`'router'`, `'sandbox'`, `'cli'`) and accepts `register(name,
+ * factory)` for any additional runtime — and a BYO `AgentSpec.executor` resolves
+ * without touching the registry at all. NOT a closed switch; registration + BYO
+ * ARE the extension points.
+ *
+ * `resolve` precedence (frozen in `ExecutorRegistry`): a BYO `spec.executor` →
+ * `harness === null` → the `'router'` factory; else a registered factory for the
+ * harness-derived runtime (`'sandbox'` for any `BackendType`); else fail loud.
+ */
+declare function createExecutorRegistry(): ExecutorRegistry;
+
+/**
+ * @experimental
+ *
+ * The reactive `Scope` impl (KEYSTONE, build step 4 + the step-8 adapter).
+ *
+ * An `Agent.act` runs inside a `Scope`. It `spawn`s children dynamically and reacts to
+ * them via `next()`. The scope owns ONE in-memory nursery — the authoritative live set —
+ * and is the single place that drives a child's lifecycle: reserve budget atomically,
+ * resolve a `Executor` through the open registry, run it (one-shot OR streaming),
+ * fold its normalized `UsageEvent`s into a conserved `Spend`, reconcile the reservation
+ * (refunding the unspent remainder), persist the result blob + journal records, and
+ * deliver the `Settled` through the `next()` cursor.
+ *
+ * Three invariants this impl enforces by construction:
+ *  - `next()` is a ray.wait n=1 cursor over THIS scope's live set; it assigns the
+ *    monotonic `seq` (the recorded cursor order) at the moment it yields a settlement, so
+ *    replay re-delivers in the identical order — `seq` is never wall-clock.
+ *  - Budget is reserved at spawn and reconciled at settle through the shared `BudgetPool`,
+ *    so `spawn` fails CLOSED on an exhausted pool and total ≡ free + reserved + committed.
+ *  - `view` reads the in-memory nursery, never the journal — O(live), synchronous.
+ *
+ * The settle path is the only writer of journal `settled` events; the spawn path the only
+ * writer of `spawned` events. The result blob is `put` BEFORE the journal `settled` record
+ * references its `outRef`, so a crash can never leave a journaled ref with no blob.
+ */
+
+/** Construction args for `createScope`. The supervisor threads the shared pool, journal,
+ *  blob store, and executor registry through; `depth`/`maxDepth` pair the runtime
+ *  recursion ceiling with the conserved pool (R3). */
+interface ScopeArgs {
+    /** This scope's owning node id — children get `${parentId}:s${seq}` ids. */
+    readonly parentId: NodeId;
+    /** Journal/blob root key the supervisor `beginTree`'d. */
+    readonly root: NodeId;
+    /** The shared conserved reservation pool (one per supervised run). */
+    readonly pool: BudgetPool;
+    /** Append-only spawn journal; this scope writes `spawned` + `settled` records. */
+    readonly journal: SpawnJournal;
+    /** Content-addressed result store backing `outRef` rehydration. */
+    readonly blobs: ResultBlobStore;
+    /** The open executor resolver (BYO → router/inline → registered harness factory). */
+    readonly executors: ExecutorRegistry;
+    /** Per-spawn executor-construction seams (sandbox client, router config, cli bin). */
+    readonly seams: Readonly<Record<string, unknown>>;
+    /** This scope's recursion depth (root = 0). */
+    readonly depth: number;
+    /** Runtime recursion-depth ceiling — a spawn past it fails closed `depth-exceeded`. */
+    readonly maxDepth?: number;
+    /** Abort signal for this scope; an abort cascades into every live child's executor. */
+    readonly signal: AbortSignal;
+    /** Injected clock — keeps the journal `at` timestamp deterministic in tests. */
+    readonly now?: () => number;
+    /** Lifecycle stream sink. `spawn` emits `agent.spawn`, `next` emits `agent.child` — the
+     *  SAME stream `runLoop`/`tool-loop` feed, so the recursive tree is ONE observable stream
+     *  (the topology viewer reads it). Undefined ⇒ the journal stays the only record. */
+    readonly hooks?: RuntimeHooks;
+}
+declare function createScope<Out>(args: ScopeArgs): Scope<Out>;
+/**
+ * The step-8 merge-boundary adapter (M4): rehydrate a `Settled.done` into the kernel's
+ * `Iteration` shape so `defaultSelectWinner` stays single-sourced — the supervisor selects
+ * across settled children with the SAME argmax the loop kernel uses, not a forked copy.
+ *
+ * `index` is the cursor `seq` (the recorded, replay-stable order); `output`/`verdict`/
+ * `tokenUsage`/`costUsd` are read straight off the settlement (already rehydrated from the
+ * `outRef` blob by `next()`). Events are empty — a settled child is an opaque leaf result,
+ * not a sandbox event stream — and the timing/cost fields project its conserved `Spend`.
+ * Fail loud on a `down` settlement: only a `done` child is an iteration.
+ */
+declare function settledToIteration<Out>(settled: Settled<Out>): Iteration<unknown, Out>;
+
+/**
+ * @experimental
+ *
+ * The `Supervisor` impl (KEYSTONE, build step 5).
+ *
+ * Owns the four things a free-running recursive `act` cannot own itself: the GLOBAL
+ * conserved budget pool, the event-sourced spawn log, the abort cascade over the whole
+ * live tree, and the OTP intensity breaker. `run` builds the root `Scope` over those,
+ * runs the root `Agent.act`, and returns a TYPED `SupervisedResult` — a no-winner is
+ * never coerced into a best-effort `Out`.
+ *
+ * Three lifecycle invariants this impl enforces by construction:
+ *  - Join barrier: when `act()` settles (resolve OR reject), every still-live child is
+ *    torn down before `run` returns — the generalization of the kernel's
+ *    `finally{ Promise.allSettled(destroy) }` barrier (run-loop.ts) from boxes to the
+ *    whole sub-tree. A teardown failure is `allSettled`'d and journaled as a
+ *    `cancelled` event; it NEVER masks act()'s own outcome. act()'s rejection is the
+ *    PRIMARY error (the kernel's firstError precedence), so a teardown throw during the
+ *    barrier can never overwrite the real failure.
+ *  - Abort cascade: a root abort (caller signal, `RootHandle.abort`, a tripped breaker,
+ *    or pool exhaustion) aborts ONE internal controller whose signal is the root scope's
+ *    signal. The scope cascades that into every live child's executor abort — which, for
+ *    an `acquiring` child, chains into the `acquireSandbox` signal and reaps the
+ *    find-by-name orphan box (M1). The supervisor never reaps children directly.
+ *  - The supervisor NEVER re-enters a child (m3): the kernel/`acquireSandbox` already
+ *    retried at the leaf, and a driver re-spawns through `scope.spawn`. The breaker only
+ *    COUNTS `down` settlements within the intensity window and trips to a typed
+ *    no-winner; it does not restart anything.
+ *
+ * Selection lives in the driver, not here (selector≠judge): `act` returns the synthesized
+ * winner `Out`. The supervisor content-addresses that `Out` for its replay `outRef`,
+ * reads `spentTotal` off the conserved pool, and wraps it as a typed `winner` — it does
+ * not re-rank children behind the driver's back.
+ */
+
+declare function createSupervisor<Task, Out>(): Supervisor<Task, Out>;
+/**
+ * Mint a `RootHandle` plus its supervisor-private control. The handle is the substrate a
+ * chat/pi-viz client attaches to (Q2): `view()` reads the live tree, `signal()` delivers
+ * an out-of-band message, `abort()` cascades. Before `run` binds it (and after `run`
+ * unbinds it) the handle is fail-loud: a client that talks to a handle that is not
+ * driving a live run gets a typed error, never a silent no-op.
+ */
+declare function createRootHandle<Out>(): RootHandle<Out>;
+
+export { Agent, AgentRunSpec, AgentSpec, type AssertTraceDerivedFindings, type BridgeSeam, Budget, type BudgetPool, type BudgetReadout, type CheckpointCapableBox, type CliSeam, type CombinatorShape, type Corpus, type CorpusFilter, type CorpusRecord, type CreateScopeAnalystOptions, type CriuCapableClient, type DefinePersona, type DefinePersonaInput, type Deliverable, type EqualKArm, type EqualKOnCost, type EqualKOnCostOptions, type EqualKVerdict, ExecCtx, type ExecutorConfig, ExecutorFactory, ExecutorRegistry, type Fanout, type FanoutOptions, type FanoutSynthesis, FileCorpus, FileResultBlobStore, FileSpawnJournal, type FlatWidenGate, type ForkCapableBox, InMemoryCorpus, InMemoryResultBlobStore, InMemorySpawnJournal, Iteration, type LoopDispatchOptions, type LoopOptionsForDispatch, LoopResult, type LoopShape, LoopTokenUsage, type LoopUntil, type LoopUntilSpec, type LoopUntilState, NodeId, type OpenSandboxRunOptions, type Outcome, type Panel, type PanelJudge, type PanelSpec, type PanelVerdict, type Persona, type PersonaContext, type PersonaExecutors, type Pipeline, type PipelineStage, type RenderCorpusToInstructions, type RenderCorpusToInstructionsOptions, type ReservationTicket, ResultBlobStore, RootHandle, type RouterSeam, RunLoopOptions, type RunPersonified, type RunPersonifiedOptions, type SandboxCapabilities, SandboxClient, type SandboxLineage, type SandboxLineageHandle, type SandboxRun, type SandboxSeam, Scope, type ScopeAnalyst, type ScopeAnalyzeInput, type ScopeWidenGate, type SessionCapableBox, Settled, type ShapeBudget, type ShapeContext, type ShapeRegistry, SpawnEvent, SpawnJournal, Spend, type SteerContext, SupervisedResult, Supervisor, type TrajectoryNode, type TrajectoryReport, type TrajectoryReportFn, type TrajectoryReportOptions, TreeView, type TurnResult, UsageEvent, type UsageSink, type Verify, type VerifySpec, type Widen, type WidenDecision, type WidenLineage, type WidenSpec, acquireSandbox, assertTraceDerivedFindings, buildSteerContext, builtinShapes, contentAddress, createBudgetPool, createExecutor, createExecutorRegistry, createRootHandle, createSandboxLineage, createScope, createScopeAnalyst, createShapeRegistry, createSupervisor, definePersona, equalKOnCost, extractLlmCallEvent, fanout, flatWidenGate, inlineSandboxClient, loopDispatch, loopUntil, mapSandboxEvent, materializeTreeView, openSandboxRun, panel, pipeline, probeSandboxCapabilities, registerShape, renderCorpusToInstructions, replaySpawnTree, reportLoopUsage, runPersonified, settledToIteration, spendFromUsageEvents, trajectoryReport, verify, widen };