@graphrefly/graphrefly 0.44.0 → 0.46.0

package/dist/spawnable-5mDY501F.d.cts

@@ -0,0 +1,746 @@
+import { Node } from '@graphrefly/pure-ts/core';
+import { NodeInput } from '@graphrefly/pure-ts/extra';
+import { GraphOptions, Graph } from '@graphrefly/pure-ts/graph';
+import { TopicGraph, MessagingHubGraph, TopicMessage } from './utils/messaging/index.cjs';
+import { L as LLMAdapter, c as LLMResponse } from './types-BB5Lw-pB.cjs';
+import { G as GateController } from './pipeline-graph-Ce47CB6Y.cjs';
+import { e as HarnessJobPayload, k as QueueRoute, p as TriagedItem, n as StrategyModelGraph, I as IntakeItem, r as VerifyResult, c as ExecutePromptFn, H as HarnessExecutor, q as VerifyPromptFn, g as HarnessVerifier, f as HarnessLoopOptions } from './types-vCq7ShIm.cjs';
+import { JobFlowGraph, JobQueueGraph } from './utils/job-queue/index.cjs';
+import { A as AgentBundle, P as PresetRegistryBundle, g as AgentSpec } from './agents-C0Ji9ldU.cjs';
+
+/**
+ * refineLoop — universal prompt/artifact optimization loop as a reactive Graph.
+ *
+ * Roadmap §9.8 (Wave 2.5). The loop is a 4-topic reactive pipeline:
+ *
+ *   iterationTrigger ──▶ GENERATE ──▶ EVALUATE ──▶ ANALYZE ──▶ DECIDE
+ *                            │                                   │
+ *                            └───────  feedback + trigger  ◀─────┘
+ *
+ * Each stage is a `TopicGraph` so dispatches stay O(1) per subscriber (cursor-
+ * based) and every iteration is observable, replayable, and checkpointable.
+ *
+ * Composition invariants (from COMPOSITION-GUIDE):
+ *  - §7 feedback cycle: only `iterationTrigger` drives re-generation. Strategy
+ *    + feedback + dataset are read via closure updaters (§28 factory-time seed)
+ *    so mid-run swaps apply to the NEXT iteration, never retrigger the current.
+ *  - §28 factory-time seed: strategy, lastFeedback, prevCandidates, dataset
+ *    closures captured at wiring time + updated via subscribe handlers so the
+ *    first activation doesn't drop the initial pair.
+ *  - §32 nested-drain state-mirror: the decide-effect writes `lastFeedback`
+ *    BEFORE bumping `iterationTrigger` inside its `batch()`, guaranteeing the
+ *    mirror is current when the next-iteration wave reaches the generate fn.
+ *  - §19 terminal-emission: history / best emit once per iteration (settled),
+ *    not on every intermediate wave.
+ *  - §27 attachSnapshotStorage: the whole graph is checkpointable — pause overnight,
+ *    resume tomorrow from the exact iteration count, candidate set, strategy.
+ *
+ * Scope clamp (v1): core factory + `RefineStrategy<T>` + `blindVariation` and
+ * `errorCritique` built-ins + budget gating + checkpoint/resume.
+ * `mutateAndRefine` / registry / `autoSelectStrategy` / `optimizeCatalog` /
+ * `refineExecutor` are deferred.
+ *
+ * @module
+ */
+
+/** A single task row — the unit the evaluator scores one candidate against. */
+interface DatasetItem {
+    readonly id: string;
+    readonly [k: string]: unknown;
+}
+/**
+ * One candidate's score on one task. Higher is better by convention.
+ *
+ * Set `candidateIndex` when the evaluator fans out scores across multiple
+ * candidates (e.g. `candidates × tasks`). `pickBest` aggregates mean scores
+ * per `candidateIndex` when present; when absent, falls back to positional
+ * alignment (`scores[i]` ↔ `candidates[i]`).
+ */
+interface EvalResult {
+    readonly taskId: string;
+    readonly score: number;
+    readonly error?: string;
+    readonly detail?: unknown;
+    /** 0-based index into the `candidates` batch this score belongs to. */
+    readonly candidateIndex?: number;
+}
+/** Aggregated feedback the strategy produces from a scores batch. */
+interface Feedback {
+    readonly summary: string;
+    readonly critique?: unknown;
+    readonly weakTasks?: readonly string[];
+    readonly score: number;
+}
+/**
+ * Strategy interface — plain object, no base class. Strategies implement three
+ * pure hooks; the loop infrastructure wraps them in reactive nodes so every
+ * decision is visible in `describe()`.
+ *
+ * `generate` may be sync or async. Async generates yield a microtask per
+ * iteration — that's what gives `pause()` / `setStrategy()` a window to
+ * interleave. **A fully synchronous `generate` will drain the entire loop
+ * during factory activation** (all iterations run before `refineLoop()`
+ * returns), which is usually not what you want for observable, steerable
+ * loops. Real strategies that call LLMs / evals are async and Just Work;
+ * custom sync strategies for tests are fine but should be marked `async`
+ * to match real cadence.
+ */
+interface RefineStrategy<T> {
+    readonly name: string;
+    /** Produce initial candidates from the seed. Called at iteration 0. */
+    seed(seed: T): readonly T[];
+    /** Reduce scores to feedback. Pure function. */
+    analyze(scores: readonly EvalResult[], candidates: readonly T[]): Feedback;
+    /**
+     * Generate next-iteration candidates from feedback + prior candidates.
+     * Async allowed — the loop awaits via `fromAny`.
+     */
+    generate(feedback: Feedback, candidates: readonly T[]): Promise<readonly T[]> | readonly T[];
+}
+/**
+ * Evaluator shape — Shape 4 (2026-04-22): both `candidates` and `dataset` are
+ * reactive nodes; the evaluator's returned node IS the EVALUATE topic's source
+ * (no glue). Implementers can batch-eval (e.g. `funnel` with concurrency) or
+ * map per-candidate — user's code.
+ *
+ * **Cancel-on-input contract (load-bearing).** Evaluators with async work
+ * (LLM calls, network requests, etc.) MUST cancel any in-flight work when
+ * `candidates` emits a new batch. The canonical pattern is `switchMap` over
+ * `candidates`. If an evaluator does NOT cancel — e.g. naively kicks a
+ * `Promise.all` per-batch and emits whatever resolves — late scores from a
+ * prior iteration can arrive after the loop has already moved to the next
+ * iteration (especially after `pause()` / `resume()`). Such stale scores
+ * trip {@link refineLoop}'s `feedbackEnvelopeNode` with mismatched
+ * `iter`/`scores`/`items`, producing an incorrect `DecideEvent` and (worse)
+ * marking the iter as decided so the real iter's scores get skipped by
+ * de-dup, stalling the loop. See `optimizations.md` "refineLoop async-
+ * evaluator stale-scores follow-up" for the proposed `wrapEvaluator()`
+ * helper that would enforce cancellation.
+ *
+ * **`EvalResult.candidateIndex` semantics.** Optional per-result field.
+ * When present, multi-candidate aggregators ({@link errorCritique}'s
+ * `pickBest`) score per index, picking the candidate with the highest
+ * mean score. When absent across all results, those aggregators fall back
+ * to positional matching against `candidates[0]` — meaning a strategy that
+ * generates >1 candidate but emits unindexed scores effectively only ever
+ * critiques the first candidate. Set `candidateIndex` whenever the
+ * evaluator's score corresponds to a specific candidate in the batch.
+ */
+type Evaluator<T> = (candidates: Node<readonly T[]>, dataset: Node<readonly DatasetItem[]>) => Node<readonly EvalResult[]>;
+/**
+ * Early-stop controls. Each field fans into its own derived node; the four
+ * combine via `||` into `converged: Node<boolean>`. Callers see exactly
+ * which rule tripped via `status` / the DECIDE topic's `reason`.
+ */
+interface ConvergenceOptions {
+    /** Stop when aggregate score has not improved for N iterations. */
+    patience?: number;
+    /** Stop when aggregate score reaches or exceeds this. */
+    minScore?: number;
+    /** Stop when absolute delta between consecutive scores falls below this. */
+    minDelta?: number;
+    /** Stop after N total evaluations (iteration count × per-iter candidates). */
+    maxEvaluations?: number;
+    /** Stop after N iterations. Always set a finite bound in production. */
+    maxIterations?: number;
+}
+/** Emitted to the GENERATE topic each time the strategy produces a batch. */
+interface GenerateEvent<T> {
+    readonly iteration: number;
+    readonly candidates: readonly T[];
+    readonly timestamp_ns: number;
+}
+/** Emitted to the EVALUATE topic when scores settle for an iteration. */
+interface EvaluateEvent<T> {
+    readonly iteration: number;
+    readonly candidates: readonly T[];
+    readonly scores: readonly EvalResult[];
+    readonly timestamp_ns: number;
+}
+/** Emitted to the ANALYZE topic — strategy's reduction over scores. */
+interface AnalyzeEvent<T> {
+    readonly iteration: number;
+    readonly candidates: readonly T[];
+    readonly feedback: Feedback;
+    readonly timestamp_ns: number;
+}
+/** Emitted to the DECIDE topic — branch taken this iteration. */
+interface DecideEvent {
+    readonly iteration: number;
+    readonly decision: "continue" | "converged" | "budget" | "paused";
+    readonly reason?: string;
+    readonly timestamp_ns: number;
+}
+type RefineStatus = "running" | "converged" | "budget" | "paused" | "errored";
+interface Iteration<T> {
+    readonly n: number;
+    readonly candidates: readonly T[];
+    readonly scores: readonly EvalResult[];
+    readonly feedback: Feedback;
+    /** `null` iff the candidate batch for this iteration was empty. */
+    readonly best: T | null;
+    readonly bestScore: number;
+    readonly timestamp_ns: number;
+}
+interface RefineLoopOptions extends ConvergenceOptions {
+    /** Reactive dataset OR a plain array (auto-wrapped into `state`). */
+    dataset: NodeInput<readonly DatasetItem[]> | readonly DatasetItem[];
+    /** Total teacher calls cap across iterations. Default: unlimited. */
+    budget?: number;
+    /** Graph name. Default: `"refine-loop"`. */
+    name?: string;
+    /** Extra graph options forwarded to the underlying `Graph`. */
+    graph?: GraphOptions;
+}
+/**
+ * `class RefineLoopGraph<T> extends Graph` — the universal prompt/artifact
+ * optimization loop as a reactive Graph subclass.
+ *
+ * Constructed via the {@link refineLoop} factory in normal use; exported as a
+ * class so consumers can `instanceof`-narrow on returned values (Phase 13.G
+ * `agent(spec)` is the consumer that motivated the migration). All
+ * observability tools (`describe`, `explain`, `observe`, `attachSnapshotStorage`,
+ * `snapshot`) Just Work since this `extends Graph`.
+ *
+ * **Phase 12.D (2026-04-30):** Migrated from `Object.assign(graph, ...)` factory
+ * pattern to `class extends Graph` (Tier R5.1 deferral lifted; mirrors the
+ * `MemoryWith*Graph` precedent). `setStrategy` / `pause` / `resume` are now
+ * instance methods that read `this.strategy` / `this._pauseState` / `this.status`
+ * / `this._iteration` instead of factory-local closures.
+ */
+declare class RefineLoopGraph<T> extends Graph {
+    readonly best: Node<T | null>;
+    /**
+     * Best score so far. Pseudo-private (`_score`) to avoid colliding with any
+     * future `Graph.prototype.score` method (B5d forward-compat hazard
+     * prevention). Typed-public — read via `loop._score.cache` /
+     * `loop._score.subscribe(...)` from external code.
+     */
+    readonly _score: Node<number>;
+    readonly status: Node<RefineStatus>;
+    readonly history: Node<readonly Iteration<T>[]>;
+    readonly strategy: Node<RefineStrategy<T>>;
+    /**
+     * Monotonic iteration counter. Pseudo-private (`_iteration`) to avoid
+     * colliding with any future `Graph.prototype.iteration` method (B5d
+     * forward-compat hazard prevention). Typed-public — read via
+     * `loop._iteration.cache` / `loop._iteration.subscribe(...)`.
+     */
+    readonly _iteration: Node<number>;
+    /** Stage topic — subscribe for per-stage streaming / cursor consumers. */
+    readonly generate: TopicGraph<GenerateEvent<T>>;
+    /** Stage topic — subscribe for per-stage streaming / cursor consumers. */
+    readonly evaluate: TopicGraph<EvaluateEvent<T>>;
+    /** Stage topic — subscribe for per-stage streaming / cursor consumers. */
+    readonly analyze: TopicGraph<AnalyzeEvent<T>>;
+    /** Stage topic — subscribe for per-stage streaming / cursor consumers. */
+    readonly decide: TopicGraph<DecideEvent>;
+    /** Internal: paused-flag node. Mounted as "paused" in describe(). */
+    private readonly _pauseState;
+    constructor(seed: T, evaluator: Evaluator<T>, initialStrategy: RefineStrategy<T>, opts: RefineLoopOptions);
+    /** Swap the active strategy mid-run (human-in-the-loop handoff). */
+    setStrategy(next: RefineStrategy<T>): void;
+    /** Pause after the current iteration completes. */
+    pause(): void;
+    /**
+     * Resume a paused loop. Idempotent: only un-pauses from the "paused"
+     * terminal state. Converged / budget / errored are permanent — a user
+     * wanting to start over should construct a fresh refineLoop.
+     */
+    resume(): void;
+}
+/**
+ * Construct a {@link RefineLoopGraph} — the universal prompt/artifact
+ * optimization loop. Thin wrapper over `new RefineLoopGraph(...)` for
+ * call-site ergonomics.
+ */
+declare function refineLoop<T>(seed: T, evaluator: Evaluator<T>, initialStrategy: RefineStrategy<T>, opts: RefineLoopOptions): RefineLoopGraph<T>;
+/**
+ * Context passed to a `blindVariation` teacher per call. `reportCost` is a
+ * per-call hook — see `BlindVariationOptions.tokens`.
+ */
+interface BlindVariationContext<T> {
+    readonly prior: T;
+    /**
+     * Report tokens consumed by this teacher call. Aggregated per iteration
+     * and flushed to `opts.tokens` in the strategy's `finally` block so
+     * partial spend is preserved when the teacher throws mid-batch.
+     */
+    readonly reportCost: (tokens: number) => void;
+}
+interface BlindVariationOptions<T> {
+    /** Name — default: `"blindVariation"`. */
+    name?: string;
+    /** Number of candidates generated per iteration. Default: 4. */
+    width?: number;
+    /**
+     * Run teacher calls in parallel via `Promise.all`. Default `true` — the
+     * common case (independent LLM calls). Set `false` to run sequentially
+     * via `for/await` when teachers share stateful resources (rate limiters,
+     * rolling context, serial API ordering) that don't tolerate concurrency.
+     */
+    parallel?: boolean;
+    /**
+     * Optional cost counter node. Running total tokens reported via
+     * `ctx.reportCost` during each iteration is added to this node in the
+     * strategy's `finally` block — fires on success AND on teacher throw so
+     * partial spend is never lost. User owns the node; wire to `budgetGate`,
+     * `attachSnapshotStorage`, telemetry, etc.
+     */
+    tokens?: Node<number>;
+    /**
+     * Teacher — given `{prior, reportCost}`, produce one variant. Async
+     * allowed. Called `width` times per iteration. Call `ctx.reportCost(n)`
+     * to track tokens consumed per call (optional, no-op if `opts.tokens`
+     * is not set).
+     */
+    teacher: (ctx: BlindVariationContext<T>) => Promise<T> | T;
+}
+/**
+ * Simplest built-in strategy: generate N variants per iteration via the
+ * supplied `teacher`; no feedback-informed steering (equivalent to Random
+ * Search). Validates the loop infrastructure end-to-end and is the baseline
+ * every other strategy should outperform.
+ *
+ * `analyze` records the mean score and flags the worst task — strategies that
+ * care about per-task critique layer on top.
+ */
+declare function blindVariation<T>(opts: BlindVariationOptions<T>): RefineStrategy<T>;
+/**
+ * Context passed to an `errorCritique` teacher. `critique` is the pre-formatted
+ * summary a prompt template can drop in verbatim; `failures` carries the
+ * structured evidence (per-task error / score / detail) for richer prompts.
+ */
+interface ErrorCritiqueContext<T> {
+    readonly prior: T;
+    readonly critique: string;
+    readonly failures: readonly EvalResult[];
+    /**
+     * Report tokens consumed by this teacher call. Aggregated per iteration
+     * and flushed to `opts.tokens` in the strategy's `finally` block so
+     * partial spend is preserved when the teacher throws mid-batch.
+     */
+    readonly reportCost: (tokens: number) => void;
+}
+interface ErrorCritiqueOptions<T> {
+    /** Name — default: `"errorCritique"`. */
+    name?: string;
+    /** Number of candidates generated per iteration. Default: 4. */
+    width?: number;
+    /**
+     * Cut-off below which a task is classified as a failure and fed into the
+     * critique. Default: the batch mean — any task scoring below the batch
+     * mean is a failure. Pass a number for an absolute cut-off, or a function
+     * for per-batch computation (e.g. a percentile). When the default mean
+     * is non-finite (NaN / ±Infinity from a degenerate evaluator), ALL scores
+     * are treated as failures so the critique loop continues to steer.
+     */
+    failureThreshold?: number | ((scores: readonly EvalResult[]) => number);
+    /** Cap on failure samples packed into the critique. Default: 5. */
+    maxFailureSamples?: number;
+    /**
+     * Format failures into the `critique` string passed to the teacher. Default
+     * joins `- taskId (score=N) | error: …` lines. Override to shape LLM prompts.
+     *
+     * **Note:** the `feedback` argument is a shell with `{score, weakTasks}`
+     * populated; `summary` is empty because `analyze` computes the final summary
+     * AFTER `formatCritique` runs (the summary embeds the formatted count).
+     * Rely on `failures` and `feedback.score` — do not read `feedback.summary`
+     * here.
+     */
+    formatCritique?: (failures: readonly EvalResult[], feedback: Feedback) => string;
+    /**
+     * Run teacher calls in parallel via `Promise.all`. Default `true` — the
+     * common case (independent LLM calls). Set `false` to run sequentially
+     * via `for/await` when teachers share stateful resources (rate limiters,
+     * rolling context, serial API ordering) that don't tolerate concurrency.
+     */
+    parallel?: boolean;
+    /**
+     * Optional cost counter node. Running total tokens reported via
+     * `ctx.reportCost` during each iteration is added to this node in the
+     * strategy's `finally` block — fires on success AND on teacher throw so
+     * partial spend is never lost. User owns the node; wire to `budgetGate`,
+     * `attachSnapshotStorage`, telemetry, etc.
+     */
+    tokens?: Node<number>;
+    /**
+     * Teacher — given `{prior, critique, failures, reportCost}`, produce one
+     * refined variant. Called `width` times per iteration. Async allowed.
+     * Call `ctx.reportCost(n)` to track tokens consumed per call (optional,
+     * no-op if `opts.tokens` is not set).
+     */
+    teacher: (ctx: ErrorCritiqueContext<T>) => Promise<T> | T;
+}
+/**
+ * Critique-driven strategy (ProTeGi-style "textual gradient"). Each iteration:
+ *   1. `analyze` classifies tasks scoring below a threshold as failures, picks
+ *      the best candidate from the batch, and packs both plus a formatted
+ *      critique string into `feedback.critique` as a private payload.
+ *   2. `generate` unpacks that payload and calls the teacher with
+ *      `{prior, critique, failures, reportCost}` `width` times, returning the
+ *      refined batch.
+ *
+ * The teacher receives a pre-formatted string (drop into an LLM prompt) AND
+ * the structured failure list (for richer prompts that want per-task detail).
+ * Throws on empty candidate batches — matches `blindVariation`'s contract
+ * (no silent zero-candidate cycles).
+ *
+ * When `setStrategy()` swaps this strategy in mid-run, the first `generate`
+ * may receive a `Feedback` produced by the prior strategy (no private payload);
+ * the fallback path uses `candidates[last]` as the prior and the feedback
+ * summary as the critique, so the loop keeps running without a stall. When a
+ * private payload IS present, `priv.critiqueText` takes precedence over any
+ * edits a caller made to `feedback.summary` — treat `critique` as the
+ * strategy-owned channel.
+ */
+declare function errorCritique<T>(opts: ErrorCritiqueOptions<T>): RefineStrategy<T>;
+
+/**
+ * harnessLoop() factory (roadmap §9.0).
+ *
+ * Wires the static 7-stage topology: INTAKE → TRIAGE → QUEUE → GATE →
+ * EXECUTE → VERIFY → REFLECT. Static topology, flowing data — the Kafka
+ * insight applied to human+LLM collaboration.
+ *
+ * **Hub model (Wave B Unit 20 C + Q1).** All reactive-wire-crossing topics
+ * live in one `MessagingHubGraph` exposed as `HarnessGraph.queues`: the
+ * four per-route queues, an `__unrouted` dead-letter, plus `intake`,
+ * `retry`, `verify-results`, and the `triage-output` fan-in topic. The
+ * router is a single derived/effect pair that publishes to `triage-output`;
+ * per-route `topicBridge`s fan out by `map:` predicate. Routing is data
+ * (topic name), not code — every routing decision is a visible edge in
+ * `describe()` / `explain()`.
+ *
+ * **EXECUTE/VERIFY via JobFlow (Tier 6.5 C2 lock, 2026-04-28).** The
+ * stages 5–6 EXECUTE → VERIFY pair runs through an internal `executeFlow`
+ * JobFlow with two stages (`execute`, `verify`). Each stage's pump owns
+ * `claim → work → ack` for one claim; the verify stage's payload contains
+ * `{ item, execution, verify }` so the post-completed dispatch effect can
+ * route the 3-way verdict (verified / self-correctable retry / structural
+ * + reingest) without any cross-wave `withLatestFrom` pairing. Items
+ * arriving from per-route topics + retry feedback enter via a single
+ * `enqueueEffect` that pushes to `executeFlow.queue("execute")`.
+ *
+ * @module
+ */
+
+/**
+ * Build the default EXECUTE work fn — calls `adapter.invoke()` once per
+ * claimed job, parses the JSON response into an `ExecuteOutput<A>`, and
+ * returns a {@link HarnessJobPayload} with `execution` filled in.
+ *
+ * Errors (parse failure, adapter throw, malformed JSON) are caught and
+ * surfaced as a `failure`-outcome payload — the dispatch effect routes
+ * the item rather than dropping it via pump nack (see C2 contract on
+ * {@link HarnessExecutor}).
+ *
+ * Subsumes the pre-Tier-6.5 `promptNode`-based default: per-claim LLM
+ * calls don't benefit from `promptNode`'s cross-wave switchMap, and a
+ * fresh per-claim subgraph would be wasteful. Direct `adapter.invoke`
+ * is the right shape inside JobFlow pumps.
+ *
+ * @param adapter - LLMAdapter for the execute call.
+ * @param prompt  - Prompt template (string or `(item) => string`). Defaults
+ *                   to the harness's built-in execute prompt.
+ */
+declare function defaultLlmExecutor<A = unknown>(adapter: LLMAdapter, prompt?: string | ExecutePromptFn): HarnessExecutor<A>;
+/**
+ * Build the default VERIFY work fn — calls `adapter.invoke()` once per
+ * claimed job to review the prior-stage execution, parses the JSON
+ * response into a `VerifyOutput`, and returns a {@link HarnessJobPayload}
+ * with `verify` filled in.
+ *
+ * Same C2 error semantics as {@link defaultLlmExecutor}: parse / adapter
+ * failures are surfaced as a structural-failure verify payload so the
+ * dispatch effect routes the item.
+ */
+declare function defaultLlmVerifier<A = unknown>(adapter: LLMAdapter, prompt?: string | VerifyPromptFn<A>): HarnessVerifier<A>;
+/**
+ * The graph returned by {@link harnessLoop}. Wraps a single
+ * {@link MessagingHubGraph} that owns all reactive-wire-crossing topics
+ * (intake, per-route queues, `__unrouted`, retry, verify-results,
+ * triage-output), plus an `executeFlow` JobFlow that owns the
+ * EXECUTE → VERIFY pipeline (Tier 6.5 C2). Sugar getters expose the
+ * canonical topics so the surface stays ergonomic.
+ */
+declare class HarnessGraph<A = unknown> extends Graph {
+    /** Messaging hub — the routing-data plane. Queue topics live here. */
+    readonly queues: MessagingHubGraph;
+    /**
+     * EXECUTE → VERIFY JobFlow (Tier 6.5 C2). Pumps own claim/ack/nack
+     * lifecycle for each stage. Inspect via:
+     * - `harness.executeFlow.queue("execute").pending` — pending depth.
+     * - `harness.executeFlow.queue("verify").pending` — items mid-execute.
+     * - `harness.executeFlow.completed` — verified items waiting for the
+     *   dispatch effect's 3-way routing.
+     * - `harness.executeFlow.completedCount` — total terminal completions.
+     */
+    readonly executeFlow: JobFlowGraph<HarnessJobPayload<A>>;
+    /**
+     * Per-route JobQueueGraph audit mirrors. Each triaged item that reaches
+     * a queue is also enqueued here, giving reactive `depth` + `pending` +
+     * `jobs` observables per route. The dispatch effect ack/removeBy-id's
+     * the matching job on terminal verdict. The executeFlow JobFlow handles
+     * the EXECUTE → VERIFY data flow; this is a parallel audit-side ledger
+     * for per-route depth metrics. Inspect via
+     * `harness.jobs.get(route).depth.cache` for backpressure metrics.
+     */
+    readonly jobs: ReadonlyMap<QueueRoute, JobQueueGraph<TriagedItem>>;
+    /** Per-route gate controllers (only for gated queues). */
+    readonly gates: ReadonlyMap<QueueRoute, GateController<TriagedItem>>;
+    /**
+     * Per-route queue topics — typed accessor for the four
+     * {@link QUEUE_NAMES} entries (`auto-fix`, `needs-decision`,
+     * `investigation`, `backlog`). Mirrors the `gates` / `jobs` map
+     * shape so callers can iterate `[route, topic]` pairs without
+     * hand-rolling `harness.queues.topicNames()` + meta-topic exclusion.
+     *
+     * Excludes the meta topics that share the hub:
+     * `intake` (use {@link intake}), `verify-results` (use
+     * {@link verifyResults}), `retry` (use {@link retry}), `__unrouted`
+     * (use {@link unrouted}), and the internal `triage-output` fan-in.
+     */
+    readonly queueTopics: ReadonlyMap<QueueRoute, TopicGraph<TriagedItem>>;
+    /** Strategy model — `auditedSuccessTracker` keyed by `StrategyKey`. */
+    readonly strategy: StrategyModelGraph;
+    /** Global retry count across all items (circuit breaker). Reactive — subscribable. */
+    readonly totalRetries: Node<number>;
+    /** Global reingestion count across all items (circuit breaker). Reactive — subscribable. */
+    readonly totalReingestions: Node<number>;
+    /**
+     * Per-route priority score nodes, populated only when `opts.priority` is
+     * set on {@link harnessLoop}. Each node emits a score combining severity,
+     * attention decay, and strategy-model effectiveness for the route's
+     * current head-of-queue item. `undefined` means the caller did not opt
+     * in to priority scoring.
+     */
+    readonly priorityScores?: ReadonlyMap<QueueRoute, Node<number>>;
+    /**
+     * REFLECT-stage tick marker — emits one DATA per terminal verdict observed
+     * on `executeFlow.completed`. `equals: () => false` so each completion
+     * produces an observable tick (no Object.is collapse on identical
+     * `null` payloads). Inspection tools (`harnessTrace`, dashboards) can
+     * subscribe directly here instead of resolving by string path
+     * (`harness.node("reflect")`) — the field is the lock against rename
+     * drift.
+     */
+    readonly reflect: Node<null>;
+    constructor(name: string, queues: MessagingHubGraph, executeFlow: JobFlowGraph<HarnessJobPayload<A>>, queueTopics: Map<QueueRoute, TopicGraph<TriagedItem>>, jobs: Map<QueueRoute, JobQueueGraph<TriagedItem>>, gates: Map<QueueRoute, GateController<TriagedItem>>, strategy: StrategyModelGraph, totalRetries: Node<number>, totalReingestions: Node<number>, reflect: Node<null>, priorityScores?: Map<QueueRoute, Node<number>>);
+    /** Intake topic — publish items here to enter the loop. */
+    get intake(): TopicGraph<IntakeItem>;
+    /** Verify results topic — subscribe to see verification outcomes. */
+    get verifyResults(): TopicGraph<VerifyResult<A>>;
+    /** Retry feedback topic — fast-retry re-entry point. */
+    get retry(): TopicGraph<TriagedItem>;
+    /** Dead-letter topic for items whose LLM-chosen route is unknown. */
+    get unrouted(): TopicGraph<TriagedItem>;
+    /**
+     * Stage-label → observe-path map for the 7 pipeline stages.
+     *
+     * Decouples inspection tools (`harnessTrace`, `harnessProfile`, custom
+     * dashboards) from mount-structure churn: hub migration, future stage
+     * splits, gate remounting, or the Tier 6.5 C2 JobFlow rewire shouldn't
+     * require edits to `trace.ts` as long as this method stays accurate.
+     *
+     * Each stage yields `{ label, paths }`; consumers iterate paths per
+     * stage and attach observers. Tier 6.5: EXECUTE / VERIFY paths now
+     * resolve to the `executeFlow` stage queues + the `verify-dispatch`
+     * effect node.
+     */
+    stageNodes(): ReadonlyArray<{
+        label: string;
+        paths: readonly string[];
+    }>;
+}
+/**
+ * Wire the reactive collaboration loop as a static-topology graph.
+ *
+ * The loop has 7 stages:
+ * 1. **INTAKE** — items arrive from multiple sources via `intake.publish()`
+ * 2. **TRIAGE** — promptNode classifies, routes, and prioritizes
+ * 3. **QUEUE** — 4 priority-ordered TopicGraphs (auto-fix, needs-decision, investigation, backlog)
+ * 4. **GATE** — human approval on configurable queues
+ * 5. **EXECUTE** — JobFlow `execute` stage; user-supplied or default work fn
+ * 6. **VERIFY** — JobFlow `verify` stage; verifies the executed artifact
+ * 7. **REFLECT** — strategy model records outcomes; dispatch effect routes 3-way
+ *
+ * @param name - Graph name.
+ * @param opts - Configuration.
+ * @returns HarnessGraph with controller accessors.
+ */
+declare function harnessLoop<A = unknown>(name: string, opts: HarnessLoopOptions<A>): HarnessGraph<A>;
+
+/**
+ * Phase 13.I — `spawnable()` harness preset.
+ *
+ * Source: `archive/docs/SESSION-multi-agent-gap-analysis.md` G3 lock B + G5
+ * reframe.
+ *
+ * Wraps a {@link MessagingHubGraph} + {@link presetRegistry} +
+ * (per-request) {@link agent} mounting + depth-cap + termination contract.
+ * Consumers emit a `TopicMessage<SpawnPayload>` to the well-known
+ * {@link SPAWNS_TOPIC}; `spawnable()` mints a fresh agent from the
+ * matching preset, mounts it, and tracks it in `activeSlot` until the
+ * agent settles or expires. Out-of-policy requests (depth-cap exceeded,
+ * unknown presetId, schema-invalid, expired) flow to the `rejected`
+ * topic.
+ *
+ * **Cross-cut #1 lock (no `agent.run()`):** spawnable kicks each agent
+ * via `bundle.in.emit(taskInput)`; status transitions are observed via
+ * the agent's reactive `status` Node.
+ *
+ * **Termination contract:**
+ * - `done` / `error` from the agent's `status` → unmount + remove from
+ *   `activeSlot`.
+ * - `expiresAt` (set on the request envelope, ISO 8601) — when the wall
+ *   clock passes the deadline AND the agent is still active, the agent is
+ *   aborted (via `loop.abort()`) and reported on `rejected` with
+ *   `reason: "expired"`. (Per-spawn timeout via the `timeout` operator
+ *   recipe is documented in COMPOSITION-GUIDE-PATTERNS.)
+ *
+ * **Depth-cap:** locked recipe (DS-13.I) is `valve(spawnTopic, derived(
+ * [depthCounter], n => n < cap))`, but the practical pattern in
+ * `spawnable()` checks depth per-request inside the request handler so
+ * over-cap requests can be reported on `rejected`. Callers who want hard
+ * cuts (no rejection signal) can wrap their own publish path with
+ * `valve` per the recipe.
+ */
+
+/**
+ * Payload of a spawn request envelope. Wraps in a {@link Message}<...>:
+ * the request body sets `presetId` (the preset registry key) and
+ * `taskInput` (the typed input passed to the spawned agent's `bundle.in`).
+ */
+interface SpawnPayload<TIn> {
+    readonly presetId: string;
+    readonly taskInput: TIn;
+}
+/**
+ * Rejection record published to the `rejected` topic when a spawn request
+ * is denied. `reason` is a short human-readable code.
+ */
+interface SpawnRejection<TIn> {
+    readonly request: TopicMessage<SpawnPayload<TIn>>;
+    readonly reason: string;
+}
+/**
+ * Options for {@link spawnable}.
+ */
+interface SpawnableOpts<TIn, TOut> {
+    /** Existing messaging hub. {@link SPAWNS_TOPIC} is created lazily on it. */
+    readonly hub: MessagingHubGraph;
+    /** Preset registry — keys must match `request.payload.presetId`. */
+    readonly registry: PresetRegistryBundle<AgentSpec<TIn, TOut>>;
+    /**
+     * Local mount name on the hub for this spawnable's subgraph. Multiple
+     * spawnable instances on the same hub must use distinct names. Default
+     * `"spawnable"`.
+     */
+    readonly name?: string;
+    /** Maximum concurrently-active agents. Default unbounded. */
+    readonly depthCap?: number;
+    /**
+     * Initial cursor for the spawn-topic subscription. Default `"now"` —
+     * pre-existing retained spawn requests are NOT replayed at construction.
+     * Pass `"retained"` to replay or a number for explicit cursor offset.
+     */
+    readonly from?: "now" | "retained" | number;
+    /**
+     * Optional caller-supplied validator. Returns `true` to accept the
+     * request, `false` to reject. Reject reason on the `rejected` topic is
+     * `"schema validation failed"`. Pair with the `Message.schema` field carried
+     * in the envelope when full JSON-Schema validation is needed (consumer
+     * supplies the validator — ajv / zod / valibot — and reads the schema
+     * from the envelope to gate). The substrate itself does NOT ship a
+     * JSON-Schema validator; the `Message.schema` field is wire convention.
+     */
+    readonly validate?: (request: TopicMessage<SpawnPayload<TIn>>) => boolean;
+}
+/**
+ * The bundle returned by {@link spawnable}.
+ */
+interface SpawnableBundle<TIn, TOut> {
+    /** The well-known spawn topic — emit `TopicMessage<SpawnPayload<TIn>>` here. */
+    readonly spawnTopic: TopicGraph<TopicMessage<SpawnPayload<TIn>>>;
+    /** Reactive map of currently-active agent bundles, keyed by request id. */
+    readonly activeSlot: Node<ReadonlyMap<string, AgentBundle<TIn, TOut>>>;
+    /** Topic of rejected requests with reason. */
+    readonly rejected: TopicGraph<SpawnRejection<TIn>>;
+    /** The internal SpawnableGraph subgraph (mounted under the hub). */
+    readonly graph: SpawnableGraph<TIn, TOut>;
+}
+/**
+ * Graph subclass implementing {@link SpawnableBundle}'s topology.
+ * Mounted under the hub at `opts.name` (default `"spawnable"`).
+ *
+ * Topology:
+ * ```
+ * <hub>
+ * ├── spawns                (TopicGraph; well-known well-named spawn topic)
+ * └── <name>                (SpawnableGraph)
+ *     ├── spawn-sub         (SubscriptionGraph over hub::spawns::events)
+ *     ├── rejected          (TopicGraph<SpawnRejection>)
+ *     ├── active-slot       (Node<ReadonlyMap<id, AgentBundle>>)
+ *     └── spawn-{req.id}/   (mounted AgentGraph per active spawn)
+ * ```
+ */
+declare class SpawnableGraph<TIn, TOut> extends Graph {
+    readonly spawnTopic: TopicGraph<TopicMessage<SpawnPayload<TIn>>>;
+    readonly rejected: TopicGraph<SpawnRejection<TIn>>;
+    readonly activeSlot: Node<ReadonlyMap<string, AgentBundle<TIn, TOut>>>;
+    private readonly _spawnSub;
+    private readonly _registry;
+    private readonly _depthCap;
+    private readonly _validate;
+    private _disposed;
+    constructor(opts: SpawnableOpts<TIn, TOut>);
+    private _processRequest;
+}
+/**
+ * Constructs a {@link SpawnableGraph}, mounts it under `opts.hub` at
+ * `opts.name` (default `"spawnable"`), and returns the
+ * {@link SpawnableBundle} contract.
+ *
+ * **Composition with Phase 13 substrate:**
+ * - Builds on **13.B** ({@link Message} envelope, {@link SPAWNS_TOPIC}).
+ * - Builds on **13.G/H** ({@link agent}, {@link AgentBundle}).
+ * - Builds on **13.H** ({@link presetRegistry}).
+ * - The depth-cap gate is documented as a **13.D recipe**
+ *   (`valve(spawnTopic, derived([depthCounter], n => n < cap))`); inside
+ *   `spawnable()` the depth check is per-request so over-cap requests
+ *   surface on `rejected`. Callers wanting a hard cut (no rejection
+ *   signal) can wrap their publish path with `valve`.
+ *
+ * **Strategy-key axis (DS-13.I):** when `harnessLoop` is wired to a
+ * spawnable, downstream `strategy.record(...)` calls should pass the
+ * spawning agent's `presetId` for the {@link strategyKey} first axis.
+ * Single-agent harness keeps using {@link DEFAULT_PRESET_ID} as before.
+ *
+ * @example
+ * ```ts
+ * const hub = messagingHub("hub");
+ * const presets = presetRegistry<AgentSpec<string, LLMResponse>>();
+ * presets.put("researcher", { name: "researcher", adapter: openai, systemPrompt: "..." });
+ * presets.put("coder", { name: "coder", adapter: anthropic, systemPrompt: "..." });
+ *
+ * const sp = spawnable({ hub, registry: presets, depthCap: 5 });
+ *
+ * // Trigger a spawn:
+ * sp.spawnTopic.publish({
+ *   id: "req-42",
+ *   payload: { presetId: "researcher", taskInput: "what is reactive graph composition?" },
+ * });
+ *
+ * // Observe active agents:
+ * sp.activeSlot.subscribe((msgs) => { ... });
+ *
+ * // Observe rejections:
+ * sp.rejected.events.subscribe((msgs) => { ... });
+ * ```
+ *
+ * @category patterns
+ */
+declare function spawnable<TIn = string, TOut = LLMResponse>(opts: SpawnableOpts<TIn, TOut>): SpawnableBundle<TIn, TOut>;
+
+export { type AnalyzeEvent as A, type BlindVariationContext as B, type ConvergenceOptions as C, type DatasetItem as D, type ErrorCritiqueContext as E, type Feedback as F, type GenerateEvent as G, HarnessGraph as H, type Iteration as I, RefineLoopGraph as R, type SpawnPayload as S, type BlindVariationOptions as a, type DecideEvent as b, type ErrorCritiqueOptions as c, type EvalResult as d, type EvaluateEvent as e, type Evaluator as f, type RefineLoopOptions as g, type RefineStatus as h, type RefineStrategy as i, type SpawnRejection as j, type SpawnableBundle as k, SpawnableGraph as l, type SpawnableOpts as m, blindVariation as n, defaultLlmExecutor as o, defaultLlmVerifier as p, errorCritique as q, harnessLoop as r, refineLoop as s, spawnable as t };