@graphrefly/graphrefly 0.27.0 → 0.29.0

package/dist/index-dig-r2tQ.d.cts

@@ -0,0 +1,873 @@
+import { a as Node } from './node-Dd6wHSib.cjs';
+import { T as TopicGraph } from './index-BanNUILp.cjs';
+import { E as Evaluator, D as DatasetItem, a as EvalResult$1, R as RefineStrategy, b as RefineStatus, c as RefineLoopOptions } from './index-D38duMCv.cjs';
+import { G as Graph, s as GraphProfileResult, r as GraphProfileOptions } from './graph-DgohqXK-.cjs';
+import { L as LLMAdapter } from './types-O3GzJY2U.cjs';
+import { G as GateController } from './index-DBe_8XW5.cjs';
+
+/**
+ * Harness wiring types (roadmap §9.0).
+ *
+ * Shared types for the reactive collaboration loop: intake, triage, queue,
+ * gate, execute, verify, reflect. These types are intentionally domain-agnostic
+ * — the harness loop is not specific to eval workflows.
+ *
+ * @module
+ */
+
+/** Sources that can produce intake items. */
+type IntakeSource = "eval" | "test" | "human" | "code-change" | "hypothesis" | "parity";
+/** Severity levels for intake items. */
+type Severity = "critical" | "high" | "medium" | "low";
+/** Root cause categories for triage classification. */
+type RootCause = "composition" | "missing-fn" | "bad-docs" | "schema-gap" | "regression" | "unknown";
+/** Intervention types that address root causes. */
+type Intervention = "template" | "catalog-fn" | "docs" | "wrapper" | "schema-change" | "investigate";
+/** Routing destinations after triage. */
+type QueueRoute = "auto-fix" | "needs-decision" | "investigation" | "backlog";
+/** Ordered queue route names for iteration. */
+declare const QUEUE_NAMES: readonly QueueRoute[];
+/**
+ * An item entering the harness loop via the INTAKE stage.
+ *
+ * All intake sources produce this uniform shape — the intake topic
+ * doesn't care where items came from.
+ */
+interface IntakeItem {
+    source: IntakeSource;
+    summary: string;
+    evidence: string;
+    affectsAreas: string[];
+    affectsEvalTasks?: string[];
+    severity?: Severity;
+    relatedTo?: string[];
+    /** Item-carried reingestion count. Incremented on each full-loop reingestion. */
+    _reingestions?: number;
+}
+/** Output of the TRIAGE stage — enriched intake item with classification. */
+interface TriagedItem extends IntakeItem {
+    rootCause: RootCause;
+    intervention: Intervention;
+    route: QueueRoute;
+    priority: number;
+    triageReasoning?: string;
+    /** Item-carried retry count. Incremented on each fast-retry pass. */
+    _retries?: number;
+}
+/** Effectiveness record for a rootCause→intervention pair. */
+interface StrategyEntry {
+    rootCause: RootCause;
+    intervention: Intervention;
+    attempts: number;
+    successes: number;
+    successRate: number;
+}
+/** Key format: `${rootCause}→${intervention}`. */
+type StrategyKey = `${RootCause}→${Intervention}`;
+declare function strategyKey(rootCause: RootCause, intervention: Intervention): StrategyKey;
+/** LLM output shape from the EXECUTE stage (partial — lacks `item`). */
+type ExecuteOutput = {
+    outcome: "success" | "failure" | "partial";
+    detail: string;
+    /**
+     * Optional opaque artifact that a custom executor (e.g. `refineExecutor`)
+     * may attach so downstream verifiers can re-run evaluation against the
+     * thing that was produced. LLM-backed default executors never populate
+     * this — it's an escape hatch for reactive executors carrying structured
+     * output (a refined prompt, a patched spec, a generated template, ...).
+     */
+    artifact?: unknown;
+};
+/** Full execution result assembled downstream (LLM output + context). */
+interface ExecutionResult {
+    item: TriagedItem;
+    outcome: "success" | "failure" | "partial";
+    detail: string;
+    /**
+     * Passthrough of {@link ExecuteOutput.artifact} when the executor emitted
+     * one. Reactive executors like `refineExecutor` populate this; LLM-backed
+     * default executors leave it undefined.
+     */
+    artifact?: unknown;
+}
+/** Whether an error is self-correctable (fast-retry) or structural (full loop). */
+type ErrorClass = "self-correctable" | "structural";
+/** Classifier for fast-retry path. */
+type ErrorClassifier = (result: ExecutionResult) => ErrorClass;
+/** Default error classifier: parse/config errors are self-correctable. */
+declare function defaultErrorClassifier(result: ExecutionResult): ErrorClass;
+/** Result of the VERIFY stage. */
+interface VerifyResult {
+    item: TriagedItem;
+    execution: ExecutionResult;
+    verified: boolean;
+    findings: string[];
+    errorClass?: ErrorClass;
+}
+/**
+ * Verifier output shape — what a custom verifier emits. The harness
+ * assembles this into the full {@link VerifyResult} using the triaged
+ * item + execute output sampled from `executeContextNode`.
+ */
+interface VerifyOutput {
+    verified: boolean;
+    findings: string[];
+    errorClass?: ErrorClass;
+}
+/** Configurable signals for priority scoring. */
+interface PrioritySignals {
+    /** Per-severity base weight (default: critical=100, high=70, medium=40, low=10). */
+    severityWeights?: Partial<Record<Severity, number>>;
+    /** Decay rate per second for attention decay (default ~1.15e-6 ≈ 7-day half-life). */
+    decayRate?: number;
+    /** Strategy model effectiveness boost threshold (default 0.7). */
+    effectivenessThreshold?: number;
+    /** Strategy model effectiveness boost amount (default 15). */
+    effectivenessBoost?: number;
+}
+/** Default severity weights. */
+declare const DEFAULT_SEVERITY_WEIGHTS: Record<Severity, number>;
+/** Default decay rate: ~7-day half-life. */
+declare const DEFAULT_DECAY_RATE: number;
+/** Per-queue configuration in the harness loop. */
+interface QueueConfig {
+    /** Whether this queue is gated (requires human approval). */
+    gated: boolean;
+    /** Maximum pending items in the gate (default Infinity). */
+    maxPending?: number;
+    /** Start the gate in open (auto-approve) mode? */
+    startOpen?: boolean;
+}
+/** Default queue configurations. */
+declare const DEFAULT_QUEUE_CONFIGS: Record<QueueRoute, QueueConfig>;
+/**
+ * Pluggable EXECUTE slot. Given the reactive `executeInput` stream of
+ * triaged items, produce a stream of `ExecuteOutput` decisions.
+ *
+ * **Contract** (see design note in `docs/optimizations.md` / session log):
+ * 1. Emit DATA exactly once per completed execution — not on input arrival.
+ * 2. Cancel in-flight work when a new item supersedes the current one
+ *    (`switchMap` is the idiomatic pattern).
+ * 3. Do not bypass `input.cache` — the harness pairs output with item via
+ *    `withLatestFrom(output, input)`. A side-state mirror of the item can
+ *    desync under nested-drain ordering.
+ * 4. The returned node IS the primary of a subsequent `withLatestFrom`;
+ *    firing on input arrival (rather than result completion) causes verify
+ *    to pair with a stale/null ExecuteOutput.
+ *
+ * `refineExecutor` makes all four rules structurally unreachable.
+ */
+type HarnessExecutor = (input: Node<TriagedItem | null>) => Node<ExecuteOutput | null>;
+/**
+ * Pluggable VERIFY slot. Receives `[executeOutput, triagedItem]` pairs
+ * sampled via `withLatestFrom(executeNode, executeInput)` and produces
+ * `VerifyOutput` decisions.
+ *
+ * Same contract rules 1–3 as {@link HarnessExecutor}. Rule 4 does not
+ * apply (verify output isn't a primary to a further withLatestFrom).
+ *
+ * `evalVerifier` handles the re-evaluation case against affected eval tasks.
+ */
+type HarnessVerifier = (context: Node<[ExecuteOutput | null, TriagedItem | null]>) => Node<VerifyOutput | null>;
+/** Options for {@link harnessLoop}. */
+interface HarnessLoopOptions {
+    /** LLM adapter for promptNode-based stages (triage + any default executor/verifier). */
+    adapter: unknown;
+    /** Custom triage prompt (receives IntakeItem + strategy model as context). */
+    triagePrompt?: string | ((...args: unknown[]) => string);
+    /**
+     * Execute prompt — sugar over the default LLM executor. Ignored when
+     * `executor` is set.
+     */
+    executePrompt?: string | ((...args: unknown[]) => string);
+    /**
+     * Verify prompt — sugar over the default LLM verifier. Ignored when
+     * `verifier` is set.
+     */
+    verifyPrompt?: string | ((...args: unknown[]) => string);
+    /**
+     * Pluggable EXECUTE slot. When omitted, the harness uses a `promptNode`
+     * driven by `adapter` + `executePrompt`. Replace to plug in a
+     * `refineExecutor`, tool-using agent, or any reactive execution pipeline.
+     */
+    executor?: HarnessExecutor;
+    /**
+     * Pluggable VERIFY slot. When omitted, the harness uses a `promptNode`
+     * driven by `adapter` + `verifyPrompt`. Replace to plug in an
+     * `evalVerifier` that re-runs affected eval tasks.
+     */
+    verifier?: HarnessVerifier;
+    /** Per-queue configuration overrides. */
+    queues?: Partial<Record<QueueRoute, QueueConfig>>;
+    /** Priority scoring signals. */
+    priority?: PrioritySignals;
+    /** Error classifier for fast-retry path. */
+    errorClassifier?: ErrorClassifier;
+    /** Max fast-retries per item before routing to full intake (default 2). */
+    maxRetries?: number;
+    /** Global retry cap across all items — circuit breaker (default maxRetries × 10). */
+    maxTotalRetries?: number;
+    /** Max re-ingestions from verify→intake before giving up (default 1). */
+    maxReingestions?: number;
+    /** Global reingestion cap across all items — circuit breaker (default maxReingestions × 10). */
+    maxTotalReingestions?: number;
+    /** Retained limit for topic logs (default 1000). */
+    retainedLimit?: number;
+}
+
+/**
+ * Harness bridge factories (roadmap §9.0).
+ *
+ * Intake bridges, eval source wrapper, before/after comparison,
+ * affected-task filter, code-change bridge, and notification effect.
+ * All are compositions of existing primitives — no new abstractions.
+ *
+ * @module
+ */
+
+/** Options for {@link createIntakeBridge}. */
+interface IntakeBridgeOptions {
+    /** Name for the effect node (default "intake-bridge"). */
+    name?: string;
+}
+/**
+ * Generic source→intake bridge factory.
+ *
+ * Watches a source node for new values, passes each through a user-supplied
+ * `parser` that produces zero or more `IntakeItem`s, and publishes them to
+ * the given intake topic.
+ *
+ * This is the generalized pattern behind {@link evalIntakeBridge}. Use it for
+ * CI results, test failures, Slack messages, monitoring alerts, or any domain
+ * where structured results should flow into a harness loop.
+ *
+ * @param source - Reactive node emitting domain-specific data.
+ * @param intakeTopic - TopicGraph to publish IntakeItem entries to.
+ * @param parser - Converts source data into IntakeItem[]. Return empty array to skip.
+ * @param opts - Optional configuration.
+ * @returns The effect node (for lifecycle management).
+ */
+declare function createIntakeBridge<T>(source: Node<T>, intakeTopic: TopicGraph<IntakeItem>, parser: (value: T) => IntakeItem[], opts?: IntakeBridgeOptions): Node<unknown>;
+/**
+ * Minimal eval result shape accepted by the bridge.
+ *
+ * TS eval runner uses `EvalRun` from `evals/lib/types.ts` which is a superset
+ * of this shape. The bridge only reads what it needs.
+ */
+interface EvalResult {
+    run_id: string;
+    model: string;
+    tasks: EvalTaskResult[];
+}
+interface EvalTaskResult {
+    task_id: string;
+    valid: boolean;
+    judge_scores?: EvalJudgeScore[];
+}
+interface EvalJudgeScore {
+    claim: string;
+    pass: boolean;
+    reasoning: string;
+}
+interface EvalIntakeBridgeOptions {
+    /** Name for the effect node (default "eval-intake-bridge"). */
+    name?: string;
+    /** Minimum severity for eval-sourced items (default "medium"). */
+    defaultSeverity?: Severity;
+}
+/**
+ * Create an effect node that watches an eval results source and publishes
+ * per-criterion findings to an intake topic.
+ *
+ * Each failing judge criterion produces a separate IntakeItem — not one
+ * item per task. This gives the triage stage granular findings to classify.
+ *
+ * @param evalSource - Node emitting EvalResult (or EvalResult[]).
+ * @param intakeTopic - TopicGraph to publish IntakeItem entries to.
+ * @param opts - Optional configuration.
+ * @returns The effect node (for lifecycle management).
+ */
+declare function evalIntakeBridge(evalSource: Node<EvalResult | EvalResult[]>, intakeTopic: TopicGraph<IntakeItem>, opts?: EvalIntakeBridgeOptions): Node<unknown>;
+/**
+ * Wrap any eval runner as a reactive producer node.
+ *
+ * When `trigger` emits, calls `runner()` and emits the result downstream.
+ * Uses `switchMap` + `fromAny` — the async boundary stays in the source
+ * layer (spec §5.10). A new trigger cancels any in-flight run.
+ *
+ * ```ts
+ * const trigger = state(0);         // bump to trigger a new run
+ * const results = evalSource(trigger, () => runEvals(config));
+ * results.subscribe(msgs => { ... });
+ * trigger.emit(1);                   // fires the runner
+ * ```
+ *
+ * @param trigger - Any node; each new DATA emission fires the runner.
+ * @param runner  - Returns an EvalResult (or promise of one).
+ */
+declare function evalSource<T extends EvalResult>(trigger: Node<unknown>, runner: () => T | Promise<T>): Node<T>;
+/** Per-task delta produced by {@link beforeAfterCompare}. */
+interface EvalTaskDelta {
+    taskId: string;
+    before: boolean;
+    after: boolean;
+    /** Score-level diff (after − before), undefined if no scores present. */
+    scoreDiff?: number;
+}
+/** Output of {@link beforeAfterCompare}. */
+interface EvalDelta {
+    /** Task IDs that newly fail in `after` (were passing in `before`). */
+    newFailures: string[];
+    /** Task IDs that now pass in `after` (were failing in `before`). */
+    resolved: string[];
+    /** Full per-task breakdown. */
+    taskDeltas: EvalTaskDelta[];
+    /** True when net resolutions > net failures. */
+    overallImproved: boolean;
+}
+/**
+ * Derived node that computes before/after eval deltas.
+ *
+ * Pure computation: no LLM, no async. Compares per-task validity and
+ * pass counts between two `EvalResult` snapshots.
+ *
+ * @param before - Node holding the baseline eval result.
+ * @param after  - Node holding the new eval result.
+ */
+declare function beforeAfterCompare(before: Node<EvalResult>, after: Node<EvalResult>): Node<EvalDelta>;
+/**
+ * Derived node that selects which eval task IDs to re-run.
+ *
+ * Collects `affectsEvalTasks` from all triaged items, deduplicates, then
+ * optionally intersects with `fullTaskSet`. Returns a sorted array of IDs.
+ *
+ * Use this to avoid re-running the full eval suite after each fix: only the
+ * tasks that the triaged items claim to affect are returned.
+ *
+ * @param issues      - Node holding the current list of triaged items.
+ * @param fullTaskSet - Optional node (or plain array) of all known task IDs.
+ *                      When provided, output is the intersection.
+ */
+declare function affectedTaskFilter(issues: Node<readonly TriagedItem[]>, fullTaskSet?: Node<readonly string[]> | readonly string[]): Node<string[]>;
+/** A single lint error emitted by a CI tool. */
+interface LintError {
+    file: string;
+    line: number;
+    col: number;
+    rule: string;
+    message: string;
+}
+/** A single test failure emitted by a test runner. */
+interface TestFailure {
+    testId: string;
+    file: string;
+    message: string;
+}
+/** Structured code-change / CI event. */
+interface CodeChange {
+    /** Files touched by the change. */
+    files: string[];
+    lintErrors?: LintError[];
+    testFailures?: TestFailure[];
+}
+/** Options for {@link codeChangeBridge}. */
+interface CodeChangeBridgeOptions {
+    /** Name for the effect node (default "code-change-bridge"). */
+    name?: string;
+    /** Default severity for generated IntakeItems (default "high"). */
+    defaultSeverity?: Severity;
+}
+/**
+ * Intake bridge for code-change / CI events.
+ *
+ * Watches a source node for `CodeChange` events and publishes one
+ * `IntakeItem` per lint error and per test failure to the intake topic.
+ * Pass a custom `parser` to override the default mapping.
+ *
+ * @param source      - Node emitting CodeChange events.
+ * @param intakeTopic - TopicGraph to publish IntakeItem entries to.
+ * @param parser      - Optional custom parser (overrides default).
+ * @param opts        - Optional configuration.
+ */
+declare function codeChangeBridge(source: Node<CodeChange>, intakeTopic: TopicGraph<IntakeItem>, parser?: (change: CodeChange) => IntakeItem[], opts?: CodeChangeBridgeOptions): Node<unknown>;
+/** Transport function for {@link notifyEffect}. Sync or async. */
+type NotifyTransport<T> = (item: T) => void | Promise<void>;
+/** Options for {@link notifyEffect}. */
+interface NotifyEffectOptions {
+    /** Name for the effect node (default "notify-effect"). */
+    name?: string;
+}
+/**
+ * Effect node that sends each new topic entry to an external channel.
+ *
+ * The `transport` function is called for every item published to `topic`.
+ * Async transports are bridged via `fromAny` (spec §5.10 compliant).
+ *
+ * Typical use: Slack webhook, GitHub PR comment, email notification, etc.
+ * The factory provides reactive wiring; the transport supplies domain logic.
+ *
+ * ```ts
+ * notifyEffect(alertQueue, async (item) => {
+ *   await fetch(SLACK_WEBHOOK, { method: 'POST', body: JSON.stringify({ text: item.summary }) });
+ * });
+ * ```
+ *
+ * @param topic     - TopicGraph whose latest entry triggers the notification.
+ * @param transport - Called with each new item. May return a Promise.
+ * @param opts      - Optional configuration.
+ */
+declare function notifyEffect<T>(topic: TopicGraph<T>, transport: NotifyTransport<T>, opts?: NotifyEffectOptions): Node<unknown>;
+
+/**
+ * evalVerifier — re-run the affected eval tasks against the execute-stage
+ * artifact instead of asking an LLM to opine on the fix.
+ *
+ * Pairs naturally with {@link refineExecutor}: refineExecutor emits an
+ * `ExecuteOutput.artifact` holding the converged candidate; evalVerifier
+ * pulls it out via `extractArtifact` and feeds a single-candidate batch
+ * into the same `Evaluator<T>` shape that `refineLoop` used. Consistent
+ * scoring between EXECUTE and VERIFY — no "LLM said it looks fine" gap.
+ *
+ * Per-item lifecycle mirrors `refineExecutor`: each new execute-context
+ * pair mounts a fresh eval subgraph inside `switchMap`, so a superseding
+ * item cancels the prior run.
+ *
+ * @module
+ */
+
+/** Summary of the re-eval wave passed to a custom `toOutput` mapper. */
+interface EvalVerifierSummary {
+    readonly scores: readonly EvalResult$1[];
+    readonly meanScore: number;
+    readonly passCount: number;
+    readonly total: number;
+    readonly threshold: number;
+    /**
+     * True when the EXECUTE stage did not produce an artifact (i.e.
+     * `extractArtifact` returned `null` / `undefined`). Downstream mappers
+     * can distinguish this from "evaluator ran but everything scored zero".
+     * When `true`, `scores` / `total` / `passCount` are all zero and
+     * `meanScore` is `-Infinity`.
+     */
+    readonly missingArtifact?: boolean;
+}
+/** Configuration for {@link evalVerifier}. */
+interface EvalVerifierConfig<T> {
+    /**
+     * Pull the artifact that should be re-evaluated out of the execute-stage
+     * output. Default: `(exec) => exec.artifact as T` — works out-of-the-box
+     * with `refineExecutor` (which populates `artifact` by default).
+     *
+     * **Type trust:** the default cast assumes the caller's executor wrote
+     * a `T`-shaped value to `ExecuteOutput.artifact`. A wrong-typed artifact
+     * surfaces as a runtime error inside `evaluator`, not here — supply a
+     * narrowing `extractArtifact` if you need stricter validation.
+     */
+    extractArtifact?: (exec: ExecuteOutput, item: TriagedItem) => T | null | undefined;
+    /**
+     * Reactive evaluator — same contract as `refineLoop`'s `Evaluator<T>`.
+     * Typically this is the SAME evaluator configured inside `refineExecutor`
+     * so EXECUTE and VERIFY scoring stay consistent.
+     */
+    evaluator: Evaluator<T>;
+    /**
+     * Resolve which dataset rows to score this verification against. Use
+     * `affectedTaskFilter` or hand-roll per-item subset logic. Default:
+     * empty array (verifier emits a findings entry explaining this).
+     */
+    datasetFor: (item: TriagedItem) => readonly DatasetItem[];
+    /** Mean score required to pass verification. Default `0.5`. */
+    threshold?: number;
+    /** Optional output mapper — override the default findings / errorClass shape. */
+    toOutput?: (summary: EvalVerifierSummary) => VerifyOutput;
+    /** Node name prefix for introspection. Default `"eval-verifier"`. */
+    name?: string;
+}
+/**
+ * Build a {@link HarnessVerifier} that re-runs the eval suite against the
+ * artifact produced by EXECUTE.
+ *
+ * @example Pair with refineExecutor for end-to-end eval consistency.
+ * ```ts
+ * const evaluator: Evaluator<CatalogEntry> = (cands, ds) => runEval(cands, ds);
+ * const harness = harnessLoop("repair", {
+ *   adapter,
+ *   executor: refineExecutor({ ..., evaluator, ...strategyConfig }),
+ *   verifier: evalVerifier({ evaluator, datasetFor, threshold: 0.8 }),
+ * });
+ * ```
+ */
+declare function evalVerifier<T>(config: EvalVerifierConfig<T>): HarnessVerifier;
+
+/**
+ * Strategy model and priority scoring (roadmap §9.0).
+ *
+ * Pure-computation derived nodes — no LLM, no async.
+ *
+ * @module
+ */
+
+/** Snapshot shape for the strategy model node. */
+type StrategySnapshot = ReadonlyMap<StrategyKey, StrategyEntry>;
+/** Bundle returned by {@link strategyModel}. */
+interface StrategyModelBundle {
+    /** Reactive node — current strategy map. */
+    readonly node: Node<StrategySnapshot>;
+    /** Record a completed issue (success or failure). */
+    record(rootCause: RootCause, intervention: Intervention, success: boolean): void;
+    /** Look up effectiveness for a specific pair. */
+    lookup(rootCause: RootCause, intervention: Intervention): StrategyEntry | undefined;
+    /** Tear down internal keepalive subscriptions. */
+    dispose(): void;
+}
+/**
+ * Create a strategy model that tracks `rootCause × intervention → successRate`
+ * over completed issues. Pure derived computation — no LLM.
+ *
+ * The model feeds back into TRIAGE for routing hints.
+ */
+declare function strategyModel(): StrategyModelBundle;
+/**
+ * Create a priority scoring derived node for a single triaged item.
+ *
+ * Combines severity weight, attention decay, strategy model effectiveness,
+ * and an optional external urgency signal.
+ *
+ * @param item - Node holding the triaged item.
+ * @param strategy - Strategy model node.
+ * @param lastInteractionNs - Node holding the monotonic timestamp (ns) of last human interaction.
+ * @param urgency - Optional external urgency signal node (0–1 scale).
+ * @param signals - Configurable scoring parameters.
+ */
+declare function priorityScore(item: Node<TriagedItem>, strategy: Node<StrategySnapshot>, lastInteractionNs: Node<number>, urgency?: Node<number>, signals?: PrioritySignals): Node<number>;
+
+/**
+ * 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.
+ *
+ * @module
+ */
+
+/**
+ * Build the default EXECUTE slot — a `promptNode` driven by the given
+ * adapter and prompt template. This is the factory behind the harness's
+ * zero-config execute stage.
+ *
+ * Obeys all four rules of the {@link HarnessExecutor} contract: `promptNode`
+ * internally uses `switchMap` + `fromAny` for cancellation (rule 2), emits
+ * once per resolved LLM invocation (rules 1 + 4), and reads the triaged
+ * item exclusively through its `deps` argument (rule 3).
+ *
+ * @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(adapter: LLMAdapter, prompt?: HarnessLoopOptions["executePrompt"]): HarnessExecutor;
+/**
+ * Build the default VERIFY slot — a `promptNode` that reviews the
+ * `[executeOutput, item]` pair from the execute-context.
+ *
+ * @param adapter - LLMAdapter for the verify call.
+ * @param prompt  - Prompt template. Defaults to the harness's built-in
+ *                   verify prompt (receives the full pair, extracts both).
+ */
+declare function defaultLlmVerifier(adapter: LLMAdapter, prompt?: HarnessLoopOptions["verifyPrompt"]): HarnessVerifier;
+/** The graph returned by {@link harnessLoop}. */
+declare class HarnessGraph extends Graph {
+    /** Intake topic — publish items here to enter the loop. */
+    readonly intake: TopicGraph<IntakeItem>;
+    /** Per-route queue topics. */
+    readonly queues: ReadonlyMap<QueueRoute, TopicGraph<TriagedItem>>;
+    /** Per-route gate controllers (only for gated queues). */
+    readonly gates: ReadonlyMap<QueueRoute, GateController<TriagedItem>>;
+    /** Strategy model bundle — record outcomes, lookup effectiveness. */
+    readonly strategy: StrategyModelBundle;
+    /** Verify results topic — subscribe to see verification outcomes. */
+    readonly verifyResults: TopicGraph<VerifyResult>;
+    /** 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>;
+    constructor(name: string, intake: TopicGraph<IntakeItem>, queues: Map<QueueRoute, TopicGraph<TriagedItem>>, gates: Map<QueueRoute, GateController<TriagedItem>>, strategy: StrategyModelBundle, verifyResults: TopicGraph<VerifyResult>, totalRetries: Node<number>, totalReingestions: Node<number>);
+}
+/**
+ * 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** — promptNode or human implements the fix
+ * 6. **VERIFY** — promptNode reviews + optional fast-retry
+ * 7. **REFLECT** — strategy model records outcomes
+ *
+ * @param name - Graph name.
+ * @param opts - Configuration.
+ * @returns HarnessGraph with controller accessors.
+ */
+declare function harnessLoop(name: string, opts: HarnessLoopOptions): HarnessGraph;
+
+/**
+ * Harness-specific graph profiling (roadmap §9.0).
+ *
+ * Extends {@link graphProfile} with harness domain counters:
+ * queue depths, strategy entries, retry/reingestion tracker sizes.
+ *
+ * @module
+ */
+
+/** Harness-specific profile extending the base graph profile. */
+interface HarnessProfileResult extends GraphProfileResult {
+    /** Per-queue retained item counts. */
+    queueDepths: Record<QueueRoute, number>;
+    /** Number of rootCause→intervention entries in the strategy model. */
+    strategyEntries: number;
+    /** Global retry count across all items. */
+    totalRetries: number;
+    /** Global reingestion count across all items. */
+    totalReingestions: number;
+}
+/**
+ * Profile a harness graph with domain-specific counters.
+ *
+ * @param harness - The HarnessGraph to profile.
+ * @param opts - Optional base profile options.
+ * @returns Harness profile with queue depths, strategy stats, and tracker sizes.
+ */
+declare function harnessProfile(harness: HarnessGraph, opts?: GraphProfileOptions): HarnessProfileResult;
+
+/**
+ * refineExecutor — bridge a `refineLoop` into the harness EXECUTE slot.
+ *
+ * Per-item lifecycle (Option A from the design note): on each new triaged
+ * item, a fresh `refineLoop` is mounted via `switchMap`; when the loop
+ * reaches a terminal status (`converged` / `budget` / `errored`), the
+ * executor emits a single `ExecuteOutput`. The switchMap cancels any
+ * in-flight loop when a newer item supersedes it.
+ *
+ * This shape makes all four {@link HarnessExecutor} contract rules
+ * structurally unreachable:
+ *  1. Terminal-status filter guarantees exactly one `ExecuteOutput` per
+ *     completed refinement run.
+ *  2. `switchMap` cancels the prior inner loop when the next item arrives.
+ *  3. The item is captured in the switchMap closure, not mirrored to a
+ *     side-state.
+ *  4. The wrapped `derived([status, best, score], ...)` only returns
+ *     non-null on terminal transitions — it never emits on input arrival.
+ *
+ * **Cross-item learning:** Option A creates a fresh refineLoop per item,
+ * so `errorCritique`-style failure sampling does NOT accumulate across
+ * items sharing a `rootCause`. A persistent-loop + re-seed surface is
+ * tracked in `docs/optimizations.md` as the long-term follow-up.
+ *
+ * @module
+ */
+
+/** Terminal-run snapshot passed to a custom `toOutput` mapper. */
+interface RefineExecutorResult<T> {
+    /** Best candidate the inner loop converged on. `null` if no candidates were scored. */
+    readonly best: T | null;
+    /** Aggregate score at termination. `-Infinity` if the batch was empty. */
+    readonly score: number;
+    /** Reason the loop terminated. */
+    readonly status: RefineStatus;
+}
+/** Configuration for {@link refineExecutor}. */
+interface RefineExecutorConfig<T> {
+    /** Map a triaged item to the seed candidate (e.g. a catalog entry, prompt, patch). */
+    seedFrom: (item: TriagedItem) => T;
+    /** Reactive evaluator — same shape as passed to `refineLoop`. */
+    evaluator: Evaluator<T>;
+    /** Strategy (e.g. `errorCritique(teacher)`). Applied to every item's inner loop. */
+    strategy: RefineStrategy<T>;
+    /** Map a triaged item to the dataset rows the evaluator should score against. */
+    datasetFor: (item: TriagedItem) => readonly DatasetItem[];
+    /**
+     * Optional mapper from the inner loop's terminal snapshot to an
+     * `ExecuteOutput`. Default: converged→success, budget→partial,
+     * errored→failure.
+     */
+    toOutput?: (result: RefineExecutorResult<T>) => ExecuteOutput;
+    /** Convergence / budget options forwarded to each inner `refineLoop`. */
+    refine?: Omit<RefineLoopOptions, "dataset" | "name">;
+    /** Node name prefix for introspection. Default `"refine-executor"`. */
+    name?: string;
+}
+/**
+ * Build a {@link HarnessExecutor} backed by a `refineLoop` per triaged item.
+ *
+ * @example Eval-driven repair loop in the harness EXECUTE slot.
+ * ```ts
+ * const harness = harnessLoop("repair", {
+ *   adapter,
+ *   executor: refineExecutor({
+ *     seedFrom: (item) => initialCatalogEntry(item),
+ *     datasetFor: (item) => pickAffectedTasks(item, allTasks),
+ *     evaluator: (cands, tasks) => runEvalBatch(cands, tasks),
+ *     strategy: errorCritique({ teacher, width: 3 }),
+ *     refine: { maxIterations: 5, minScore: 0.9 },
+ *   }),
+ * });
+ * ```
+ */
+declare function refineExecutor<T>(config: RefineExecutorConfig<T>): HarnessExecutor;
+
+/**
+ * Harness pipeline trace — thin sugar over `graph.observe({ format: "stage-log" })`.
+ *
+ * Since 2026-04-22 (D2), stage-labeled tracing is a first-class observe format
+ * on {@link Graph}. `harnessTrace` wires that format over the 7 pipeline stages
+ * (INTAKE → TRIAGE → QUEUE → GATE → EXECUTE → VERIFY → STRATEGY) with sensible
+ * defaults so harness consumers don't need to restate the stage map.
+ *
+ * For non-harness graphs, call `graph.observe({ format: "stage-log", stageLabels })`
+ * directly — the format is domain-agnostic.
+ *
+ * @module
+ */
+
+/** Event type captured by structured trace. */
+type TraceEventType = "data" | "error" | "complete";
+/** A single structured trace event. */
+interface TraceEvent {
+    /** Elapsed seconds since trace was created. */
+    elapsed: number;
+    /** Pipeline stage label (INTAKE, TRIAGE, QUEUE, GATE, EXECUTE, VERIFY, STRATEGY). */
+    stage: string;
+    /** Event type. */
+    type: TraceEventType;
+    /** Data payload (present for "data" and "error" events). Omitted at "summary" detail. */
+    data?: unknown;
+    /** Human-readable summary of the data. Present at "standard" and "full" detail. */
+    summary?: string;
+}
+/** Detail level for trace output. */
+type TraceDetail = 
+/** Stage + elapsed only. No data preview. Lowest overhead. */
+"summary"
+/** Stage + elapsed + truncated data preview. Default. */
+ | "standard"
+/** Stage + elapsed + full raw data. Use for debugging, not production. */
+ | "full";
+/** Handle returned by {@link harnessTrace}. Call `dispose()` to stop tracing. */
+interface HarnessTraceHandle {
+    /** Stop tracing and detach all observers. Safe to call multiple times. */
+    dispose(): void;
+    /**
+     * Structured trace events collected since creation. Plain array — no
+     * subscription needed (COMPOSITION-GUIDE §1: avoid lazy-activation
+     * friction for inspection tools). Populated reactively via observe().
+     */
+    readonly events: readonly TraceEvent[];
+}
+/** Options for {@link harnessTrace}. */
+interface HarnessTraceOptions {
+    /** Sink for rendered trace lines. Default: `console.log`. Pass `null` for structured-only. */
+    logger?: ((line: string) => void) | null;
+    /** Detail level for both string and structured output. Default: `"summary"`. */
+    detail?: TraceDetail;
+}
+/**
+ * Attach a stage-log trace over the harness pipeline. Delegates to
+ * `harness.observe({ format: "stage-log", ... })` for each stage path —
+ * every event is captured in `handle.events` (structured) AND rendered via
+ * the `logger` (string output).
+ *
+ * **Detail levels:**
+ * - `"summary"` — stage + elapsed only. Minimal overhead.
+ * - `"standard"` (default) — stage + elapsed + truncated data preview.
+ * - `"full"` — stage + elapsed + full raw data object in events.
+ *
+ * Elapsed timestamps are relative to the `harnessTrace()` invocation time,
+ * not the first event.
+ */
+declare function harnessTrace(harness: HarnessGraph, opts?: HarnessTraceOptions): HarnessTraceHandle;
+
+/**
+ * Harness wiring (roadmap §9.0).
+ *
+ * Reactive collaboration loop: static-topology, flowing data.
+ * Composes orchestration (gate), AI (promptNode), reduction (scorer/stratify),
+ * and messaging (TopicGraph/bridge) into a 7-stage loop.
+ *
+ * @module
+ */
+
+type index_CodeChange = CodeChange;
+type index_CodeChangeBridgeOptions = CodeChangeBridgeOptions;
+declare const index_DEFAULT_DECAY_RATE: typeof DEFAULT_DECAY_RATE;
+declare const index_DEFAULT_QUEUE_CONFIGS: typeof DEFAULT_QUEUE_CONFIGS;
+declare const index_DEFAULT_SEVERITY_WEIGHTS: typeof DEFAULT_SEVERITY_WEIGHTS;
+type index_ErrorClass = ErrorClass;
+type index_ErrorClassifier = ErrorClassifier;
+type index_EvalDelta = EvalDelta;
+type index_EvalIntakeBridgeOptions = EvalIntakeBridgeOptions;
+type index_EvalJudgeScore = EvalJudgeScore;
+type index_EvalResult = EvalResult;
+type index_EvalTaskDelta = EvalTaskDelta;
+type index_EvalTaskResult = EvalTaskResult;
+type index_EvalVerifierConfig<T> = EvalVerifierConfig<T>;
+type index_EvalVerifierSummary = EvalVerifierSummary;
+type index_ExecuteOutput = ExecuteOutput;
+type index_ExecutionResult = ExecutionResult;
+type index_HarnessExecutor = HarnessExecutor;
+type index_HarnessGraph = HarnessGraph;
+declare const index_HarnessGraph: typeof HarnessGraph;
+type index_HarnessLoopOptions = HarnessLoopOptions;
+type index_HarnessProfileResult = HarnessProfileResult;
+type index_HarnessTraceHandle = HarnessTraceHandle;
+type index_HarnessTraceOptions = HarnessTraceOptions;
+type index_HarnessVerifier = HarnessVerifier;
+type index_IntakeBridgeOptions = IntakeBridgeOptions;
+type index_IntakeItem = IntakeItem;
+type index_IntakeSource = IntakeSource;
+type index_Intervention = Intervention;
+type index_LintError = LintError;
+type index_NotifyEffectOptions = NotifyEffectOptions;
+type index_NotifyTransport<T> = NotifyTransport<T>;
+type index_PrioritySignals = PrioritySignals;
+declare const index_QUEUE_NAMES: typeof QUEUE_NAMES;
+type index_QueueConfig = QueueConfig;
+type index_QueueRoute = QueueRoute;
+type index_RefineExecutorConfig<T> = RefineExecutorConfig<T>;
+type index_RefineExecutorResult<T> = RefineExecutorResult<T>;
+type index_RootCause = RootCause;
+type index_Severity = Severity;
+type index_StrategyEntry = StrategyEntry;
+type index_StrategyKey = StrategyKey;
+type index_StrategyModelBundle = StrategyModelBundle;
+type index_StrategySnapshot = StrategySnapshot;
+type index_TestFailure = TestFailure;
+type index_TraceDetail = TraceDetail;
+type index_TraceEvent = TraceEvent;
+type index_TraceEventType = TraceEventType;
+type index_TriagedItem = TriagedItem;
+type index_VerifyOutput = VerifyOutput;
+type index_VerifyResult = VerifyResult;
+declare const index_affectedTaskFilter: typeof affectedTaskFilter;
+declare const index_beforeAfterCompare: typeof beforeAfterCompare;
+declare const index_codeChangeBridge: typeof codeChangeBridge;
+declare const index_createIntakeBridge: typeof createIntakeBridge;
+declare const index_defaultErrorClassifier: typeof defaultErrorClassifier;
+declare const index_defaultLlmExecutor: typeof defaultLlmExecutor;
+declare const index_defaultLlmVerifier: typeof defaultLlmVerifier;
+declare const index_evalIntakeBridge: typeof evalIntakeBridge;
+declare const index_evalSource: typeof evalSource;
+declare const index_evalVerifier: typeof evalVerifier;
+declare const index_harnessLoop: typeof harnessLoop;
+declare const index_harnessProfile: typeof harnessProfile;
+declare const index_harnessTrace: typeof harnessTrace;
+declare const index_notifyEffect: typeof notifyEffect;
+declare const index_priorityScore: typeof priorityScore;
+declare const index_refineExecutor: typeof refineExecutor;
+declare const index_strategyKey: typeof strategyKey;
+declare const index_strategyModel: typeof strategyModel;
+declare namespace index {
+  export { type index_CodeChange as CodeChange, type index_CodeChangeBridgeOptions as CodeChangeBridgeOptions, index_DEFAULT_DECAY_RATE as DEFAULT_DECAY_RATE, index_DEFAULT_QUEUE_CONFIGS as DEFAULT_QUEUE_CONFIGS, index_DEFAULT_SEVERITY_WEIGHTS as DEFAULT_SEVERITY_WEIGHTS, type index_ErrorClass as ErrorClass, type index_ErrorClassifier as ErrorClassifier, type index_EvalDelta as EvalDelta, type index_EvalIntakeBridgeOptions as EvalIntakeBridgeOptions, type index_EvalJudgeScore as EvalJudgeScore, type index_EvalResult as EvalResult, type index_EvalTaskDelta as EvalTaskDelta, type index_EvalTaskResult as EvalTaskResult, type index_EvalVerifierConfig as EvalVerifierConfig, type index_EvalVerifierSummary as EvalVerifierSummary, type index_ExecuteOutput as ExecuteOutput, type index_ExecutionResult as ExecutionResult, type index_HarnessExecutor as HarnessExecutor, index_HarnessGraph as HarnessGraph, type index_HarnessLoopOptions as HarnessLoopOptions, type index_HarnessProfileResult as HarnessProfileResult, type index_HarnessTraceHandle as HarnessTraceHandle, type index_HarnessTraceOptions as HarnessTraceOptions, type index_HarnessVerifier as HarnessVerifier, type index_IntakeBridgeOptions as IntakeBridgeOptions, type index_IntakeItem as IntakeItem, type index_IntakeSource as IntakeSource, type index_Intervention as Intervention, type index_LintError as LintError, type index_NotifyEffectOptions as NotifyEffectOptions, type index_NotifyTransport as NotifyTransport, type index_PrioritySignals as PrioritySignals, index_QUEUE_NAMES as QUEUE_NAMES, type index_QueueConfig as QueueConfig, type index_QueueRoute as QueueRoute, type index_RefineExecutorConfig as RefineExecutorConfig, type index_RefineExecutorResult as RefineExecutorResult, type index_RootCause as RootCause, type index_Severity as Severity, type index_StrategyEntry as StrategyEntry, type index_StrategyKey as StrategyKey, type index_StrategyModelBundle as StrategyModelBundle, type index_StrategySnapshot as StrategySnapshot, type index_TestFailure as TestFailure, type index_TraceDetail as TraceDetail, type index_TraceEvent as TraceEvent, type index_TraceEventType as TraceEventType, type index_TriagedItem as TriagedItem, type index_VerifyOutput as VerifyOutput, type index_VerifyResult as VerifyResult, index_affectedTaskFilter as affectedTaskFilter, index_beforeAfterCompare as beforeAfterCompare, index_codeChangeBridge as codeChangeBridge, index_createIntakeBridge as createIntakeBridge, index_defaultErrorClassifier as defaultErrorClassifier, index_defaultLlmExecutor as defaultLlmExecutor, index_defaultLlmVerifier as defaultLlmVerifier, index_evalIntakeBridge as evalIntakeBridge, index_evalSource as evalSource, index_evalVerifier as evalVerifier, index_harnessLoop as harnessLoop, index_harnessProfile as harnessProfile, index_harnessTrace as harnessTrace, index_notifyEffect as notifyEffect, index_priorityScore as priorityScore, index_refineExecutor as refineExecutor, index_strategyKey as strategyKey, index_strategyModel as strategyModel };
+}
+
+export { codeChangeBridge as $, type QueueRoute as A, type RefineExecutorResult as B, type CodeChange as C, DEFAULT_DECAY_RATE as D, type ErrorClass as E, type RootCause as F, type StrategyEntry as G, type HarnessExecutor as H, type IntakeBridgeOptions as I, type StrategyKey as J, type StrategyModelBundle as K, type LintError as L, type StrategySnapshot as M, type NotifyEffectOptions as N, type TraceDetail as O, type PrioritySignals as P, QUEUE_NAMES as Q, type RefineExecutorConfig as R, type Severity as S, type TestFailure as T, type TraceEvent as U, type TraceEventType as V, type TriagedItem as W, type VerifyOutput as X, type VerifyResult as Y, affectedTaskFilter as Z, beforeAfterCompare as _, type CodeChangeBridgeOptions as a, createIntakeBridge as a0, defaultErrorClassifier as a1, defaultLlmExecutor as a2, defaultLlmVerifier as a3, evalIntakeBridge as a4, evalSource as a5, evalVerifier as a6, harnessLoop as a7, harnessProfile as a8, harnessTrace as a9, notifyEffect as aa, priorityScore as ab, refineExecutor as ac, strategyKey as ad, strategyModel as ae, DEFAULT_QUEUE_CONFIGS as b, DEFAULT_SEVERITY_WEIGHTS as c, type ErrorClassifier as d, type EvalDelta as e, type EvalIntakeBridgeOptions as f, type EvalJudgeScore as g, type EvalResult as h, index as i, type EvalTaskDelta as j, type EvalTaskResult as k, type EvalVerifierConfig as l, type EvalVerifierSummary as m, type ExecuteOutput as n, type ExecutionResult as o, HarnessGraph as p, type HarnessLoopOptions as q, type HarnessProfileResult as r, type HarnessTraceHandle as s, type HarnessTraceOptions as t, type HarnessVerifier as u, type IntakeItem as v, type IntakeSource as w, type Intervention as x, type NotifyTransport as y, type QueueConfig as z };