@graphrefly/graphrefly 0.45.0 → 0.47.0

package/dist/presets/harness/index.d.cts

@@ -0,0 +1,566 @@
+import { Node, NodeGuard } from '@graphrefly/pure-ts/core';
+import { ReactiveLogBundle, OwnershipChange, NodeInput } from '@graphrefly/pure-ts/extra';
+import { Graph, GraphProfileResult, GraphProfileOptions } from '@graphrefly/pure-ts/graph';
+import { R as RenderedEntry, b as ContextEntry, c as ContextView, e as TaggedContextPoolBundle } from '../../index-DLAxYaN5.cjs';
+import { b as ExecuteOutput, p as TriagedItem, V as VerifyOutput, g as HarnessVerifier, H as HarnessExecutor, k as QueueRoute } from '../../types-vCq7ShIm.cjs';
+import { f as Evaluator, D as DatasetItem, d as EvalResult, i as RefineStrategy, g as RefineLoopOptions, H as HarnessGraph, h as RefineStatus } from '../../spawnable-5mDY501F.cjs';
+export { A as AnalyzeEvent, B as BlindVariationContext, a as BlindVariationOptions, C as ConvergenceOptions, b as DecideEvent, E as ErrorCritiqueContext, c as ErrorCritiqueOptions, e as EvaluateEvent, F as Feedback, G as GenerateEvent, I as Iteration, R as RefineLoopGraph, S as SpawnPayload, j as SpawnRejection, k as SpawnableBundle, l as SpawnableGraph, m as SpawnableOpts, n as blindVariation, o as defaultLlmExecutor, p as defaultLlmVerifier, q as errorCritique, r as harnessLoop, s as refineLoop, t as spawnable } from '../../spawnable-5mDY501F.cjs';
+import { TopicGraph } from '../../utils/messaging/index.cjs';
+import '../../types-BB5Lw-pB.cjs';
+import '../../utils/job-queue/index.cjs';
+import '../../base/mutation/index.cjs';
+import '../../pipeline-graph-Ce47CB6Y.cjs';
+import '../../agents-C0Ji9ldU.cjs';
+import '../../memory-composers-BryDrRBX.cjs';
+import '../../distill-De6Rnn15.cjs';
+import '../../utils/memory/index.cjs';
+import '../../_internal-B23BagFd.cjs';
+
+/**
+ * DS-14.6.A U-B — `actorPool()` (Phase 14.5).
+ *
+ * The dynamic-track complement to `spawnable()` (SESSION-DS-14.6-A L7/L8 +
+ * 9Q walk). An actor is **identity + cursor + tool closure, NOT a subgraph**
+ * (D-B1): no per-actor mount, so `describe()` shows only the pool / todo /
+ * context-hub collections and the actor count drifts inside a single
+ * reactive `active` map node. `depthCap` is enforced via the depth carried
+ * on the attach request (D-B2); `release()` cascades teardown to the
+ * actor's context view + todo cursor subscriptions (§3i — free).
+ *
+ * Contrast `spawnable()`: agent IS a subgraph, topology reflects the agent
+ * set, `describe()`-visible — use it when agent identities are pre-known.
+ * Use `actorPool()` for runtime recursive fan-out where agent count drifts.
+ *
+ * @module
+ */
+
+type ActorId = string;
+interface Todo {
+    readonly id: string;
+    readonly assignee?: ActorId;
+    readonly payload: unknown;
+}
+type ActorStatus = "idle" | "running" | "blocked" | "done";
+interface ActorState {
+    readonly id: ActorId;
+    readonly depth: number;
+    readonly status: ActorStatus;
+}
+interface ActorSpec<T> {
+    readonly id?: ActorId;
+    /** Recursion depth — gated against `depthCap` (D-B2). Default 0 (root). */
+    readonly depth?: number;
+    /** Per-actor compression view over the shared context pool. */
+    readonly view: Omit<ContextView<T>, "pressure"> & {
+        readonly pressure: Node<number>;
+    };
+}
+interface ActorHandle<T> {
+    readonly id: ActorId;
+    /** This actor's compressed context slice. */
+    readonly context: Node<readonly RenderedEntry<T>[]>;
+    /** Todos currently assigned to this actor (or unassigned). */
+    readonly todoCursor: Node<readonly Todo[]>;
+    /** Write an entry into the shared pool, stamped with this actor's id tag. */
+    publish(entry: Omit<ContextEntry<T>, "id" | "t_ns"> & {
+        id?: string;
+    }): string;
+    enqueueTodo(t: Todo): void;
+    readonly status: Node<ActorStatus>;
+    setStatus(s: ActorStatus): void;
+    /** Idempotent. Tears the actor's subscriptions + removes it from `active`. */
+    release(): void;
+}
+interface ActorPoolOptions<T> {
+    readonly name?: string;
+    /** Max recursion depth; `attachActor` with `depth > depthCap` throws. */
+    readonly depthCap?: number;
+    /** Forwarded to the backing context pool. */
+    readonly contextTopic?: string;
+    readonly llmCompress?: TaggedContextPoolBundle<T>["_opts"]["llmCompress"];
+}
+interface ActorPoolBundle<T> {
+    attachActor(spec: ActorSpec<T>): ActorHandle<T>;
+    readonly contextPool: TaggedContextPoolBundle<T>;
+    readonly todos: ReactiveLogBundle<Todo>;
+    /** Single reactive map of live actors — `describe()`-coherent (D-B1). */
+    readonly active: Node<ReadonlyMap<ActorId, ActorState>>;
+    readonly graph: Graph;
+    dispose(): void;
+}
+declare function actorPool<T = unknown>(parent: Graph, opts?: ActorPoolOptions<T>): ActorPoolBundle<T>;
+
+/**
+ * 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<T>.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.
+ *
+ * **C2 lifecycle (Tier 6.5).** The work fn is invoked once per claimed
+ * verify-stage job. A fresh single-candidate eval subgraph is mounted
+ * inside the work fn and tears down when the JobFlow pump ack/unsubs.
+ *
+ * @module
+ */
+
+/** Summary of the re-eval wave passed to a custom `toOutput` mapper. */
+interface EvalVerifierSummary {
+    readonly scores: readonly EvalResult[];
+    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".
+     */
+    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).
+     */
+    extractArtifact?: (exec: ExecuteOutput<T>, item: TriagedItem) => T | null | undefined;
+    /**
+     * Reactive evaluator — same contract as `refineLoop`'s `Evaluator<T>`.
+     */
+    evaluator: Evaluator<T>;
+    /**
+     * Resolve which dataset rows to score this verification against.
+     */
+    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. */
+    name?: string;
+    /**
+     * Optional parent graph on which per-claim eval subgraphs mount at
+     * `eval/${claimId}` (DS-13.5.D.4, locked 2026-05-01). When provided,
+     * each claim creates a fresh `Graph(\`eval_${claimId}\`)` subgraph
+     * carrying `candidates` / `dataset` / `output` and mounts it at
+     * `eval/${claimId}` on this parent — `describe()` walks the parent
+     * see the per-claim topology while the claim is in flight, and the
+     * subgraph is removed via `parent.remove("eval/${claimId}")` on the
+     * output node's `deactivate` cleanup (fires when JobFlow's pump
+     * unsubscribes after ack/nack).
+     *
+     * **claimId source.** `JobEnvelope.id` (assigned at enqueue time);
+     * unique within a JobFlow lifetime — uniqueness within a single pump
+     * cycle is the JobFlow's contract.
+     *
+     * When omitted, internal nodes float (pre-DS-13.5.D.4 behavior).
+     */
+    graph?: Graph;
+}
+/**
+ * Build a {@link HarnessVerifier} that re-runs the eval suite against the
+ * artifact produced by EXECUTE.
+ *
+ * Reads `job.payload.execution` (filled by the upstream execute work fn)
+ * and runs the evaluator against `extractArtifact(execution, item)`.
+ * Returns the same payload with `verify` filled in.
+ *
+ * @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<T>;
+/**
+ * Config for {@link harnessEvalPair} — the typed bundle that produces a
+ * matched `refineExecutor<T>` + `evalVerifier<T>` pair sharing one
+ * {@link Evaluator} and one `datasetFor` resolver.
+ */
+interface HarnessEvalPairConfig<T> {
+    /** Map a triaged item to the seed candidate. */
+    seedFrom: (item: TriagedItem) => T;
+    /** The reactive evaluator used by BOTH executor and verifier. */
+    evaluator: Evaluator<T>;
+    /** The refinement strategy (e.g. `errorCritique(teacher)`). */
+    strategy: RefineStrategy<T>;
+    /** Resolve dataset rows per triaged item. */
+    datasetFor: (item: TriagedItem) => readonly DatasetItem[];
+    /** Pass-threshold for the verifier. Default `0.5`. */
+    threshold?: number;
+    /** Convergence / budget options forwarded to each inner `refineLoop`. */
+    refine?: Omit<RefineLoopOptions, "dataset" | "name">;
+    /**
+     * Shared node-name prefix — the executor becomes `${name}-exec` and the
+     * verifier `${name}-verify` for distinct but related describe() paths.
+     * Default `"harness-pair"`.
+     */
+    name?: string;
+}
+/**
+ * Typed factory that returns a matched `{ executor, verifier }` pair.
+ *
+ * Prevents the "executor wrote `A`, verifier expected `B`" class of runtime
+ * cast errors — `T` is threaded through both sides, so mixing up the
+ * configuration is a compile error instead of a silent `as T` in
+ * `extractArtifact`. Shares the evaluator so EXECUTE and VERIFY score with
+ * identical semantics (the whole point of `evalVerifier`).
+ */
+declare function harnessEvalPair<T>(config: HarnessEvalPairConfig<T>): {
+    executor: HarnessExecutor<T>;
+    verifier: HarnessVerifier<T>;
+};
+
+/**
+ * `ownershipController()` — multi-agent subgraph ownership preset
+ * (DS-14.5.A delta #8; L5/L6 + Q1–Q10).
+ *
+ * **Placement (documented choice).** Lives in `presets/harness/` alongside
+ * the other multi-agent coordination presets (`spawnable()`, `actorPool()`).
+ * Per the 4-layer rubric this is a ≥3-utils composition (messaging `topic` +
+ * `derived` arbitration + Guard ABAC) wiring multi-agent coordination — the
+ * same charter as `harness/`'s existing `spawnable`/`actorPool`. A separate
+ * `presets/multi-agent/` directory was rejected to avoid fragmenting the
+ * multi-agent presets across two folders for a single factory (L6: "recipe +
+ * preset, NO new primitive").
+ *
+ * **What it is.** A `Graph` that owns a shared ownership `topic` (Q3 — one
+ * topic carries claim / release / override; subscribers narrow by `kind`),
+ * a reactive `current` derivation that folds the ownership log applying the
+ * L0–L3 staircase, and a `guard` (`policyAllowing` — the Q7 reactive-options
+ * Guard widening) the caller mounts on the owned subgraph. It **consumes the
+ * existing DS-14 {@link OwnershipChange}** envelope — it does NOT redefine it.
+ *
+ * **Staircase (Q10 — `level` is a priority axis, NOT a mechanism enum):**
+ * - **L1 TTL** — a `claim` carries a level; the controller's `ttl` (ms)
+ *   bounds the live window. L1 honors TTL strictly (Q4): a crash inside the
+ *   window does NOT early-release; recommend `ttl ≤ 60s`.
+ * - **L2 heartbeat** — `heartbeat?: NodeInput<unknown>` (Q2). Any reactive
+ *   trigger Node; each emission resets the countdown ("max tolerance since
+ *   last sign of life", unified across L1/L2). No library timer is shipped
+ *   and no `claim.heartbeat()` method exists (`feedback_no_imperative` +
+ *   `feedback_no_imperative_wrap_as_primitive`).
+ * - **L3 supervisor** — a `kind:"override"` change wins by `level` priority
+ *   regardless of expiry/heartbeat (priority axis independent of the expiry
+ *   axis). Supervisor publishes to the SAME topic (Q3).
+ *
+ * **No polling / no timer (spec §5.8/§5.9/§5.10).** Expiry is evaluated
+ * reactively: `current` recomputes whenever the ownership topic OR the
+ * heartbeat OR the optional `clock` trigger emits, folding the whole log
+ * from scratch (idempotent — no carried mutable cursor). Auto-release on
+ * wall-clock TTL requires the caller to wire a reactive `clock` tick
+ * (`fromTimer({ ms })` or an activity-derived Node) — the library does not
+ * own a timer (L6 / Q2). Without `clock`, expiry still resolves at the next
+ * topic/heartbeat emission and on any read that recomputes the derivation.
+ *
+ * @module
+ */
+
+/** Ownership level — priority axis (Q10). Higher rank = higher priority. */
+declare const LEVEL_RANK: {
+    readonly L0: 0;
+    readonly L1: 1;
+    readonly L2: 2;
+    readonly L3: 3;
+};
+type OwnershipLevel = keyof typeof LEVEL_RANK;
+/** Options for {@link ownershipController}. */
+type OwnershipControllerOptions = {
+    /**
+     * TTL (milliseconds) bounding the live window of a claim. Honored
+     * strictly (Q4) — a crash inside the window does not early-release.
+     * Recommend ≤ 60_000 for L1 holds; wire `heartbeat` (L2) for longer.
+     */
+    readonly ttl: number;
+    /**
+     * L2 heartbeat (Q2). Any reactive trigger Node — each emission resets the
+     * TTL countdown. Simple: `fromTimer({ ms: ttl / 3 })`. Activity-based:
+     * `derived([toolCalls.events], …)`. Omitted → pure L1 TTL semantics.
+     */
+    readonly heartbeat?: NodeInput<unknown>;
+    /**
+     * L3 supervisor id. A `kind:"override"` change whose `actor` equals this
+     * id wins by `level` priority regardless of expiry/heartbeat. Override
+     * delivery is the shared topic with the `kind:"override"` discriminant
+     * (Q3) — not a separate priority topic.
+     */
+    readonly supervisor?: string;
+    /**
+     * Optional reactive clock trigger used ONLY to re-evaluate TTL expiry
+     * (e.g. `fromTimer({ ms: 1_000 })`). The library ships no timer (L6/Q2);
+     * wire this for wall-clock-driven auto-release without an intervening
+     * claim/heartbeat. Without it, expiry resolves lazily on the next
+     * topic/heartbeat emission.
+     */
+    readonly clock?: NodeInput<unknown>;
+    /** Bounded retention for the ownership topic (default 256). */
+    readonly retainedLimit?: number;
+};
+/**
+ * Resolved ownership state emitted by {@link OwnershipControllerGraph.current}.
+ * `owner` is `null` when unclaimed or the live claim has expired.
+ */
+type OwnershipState = {
+    readonly owner: string | null;
+    readonly level: OwnershipLevel | null;
+    /** Allow-set fed to the Guard. `[]` (deny-all) when `owner === null`. */
+    readonly allowed: readonly string[];
+    /**
+     * Internal (F3/F4) — last sign-of-life (wall-clock ns) for the *current*
+     * claim: `max(claim.sinceNs, last in-window heartbeat)`. Carried in the
+     * derivation's OWN emitted state (read back via `ctx.prevData`) so the
+     * fold is pure — same (folded log, beat-this-wave, now, prevState) →
+     * same output. NEVER an instance field. `null` when unclaimed. Scoped to
+     * the active claim: a value older than the active claim's `sinceNs` (a
+     * prior owner's beat) is discarded so it cannot extend a new owner.
+     */
+    readonly signOfLifeNs: number | null;
+};
+/**
+ * Multi-agent subgraph ownership controller. See module docs.
+ *
+ * Public surface:
+ * - `topic` — the shared ownership `TopicGraph<OwnershipChange>` (Q3).
+ *   Agents publish claim/release/override here (use the `claim`/`release`/
+ *   `override` helpers — thin reactive wrappers over `topic.publish`, i.e.
+ *   message flow, NOT imperative triggers).
+ * - `current` — `Node<OwnershipState>`: the reactively-resolved owner after
+ *   applying L1 TTL + L2 heartbeat + L3 supervisor arbitration.
+ * - `allowed` — `Node<readonly string[]>`: the Guard allow-set (derived from
+ *   `current`); re-points on claim/release/override with no rewire.
+ * - `guard` — `NodeGuard` from `policyAllowing(this.allowed)`. Mount on the
+ *   owned subgraph's nodes (`node({ guard })`) for the Q7 hard-block.
+ */
+declare class OwnershipControllerGraph extends Graph {
+    readonly topic: TopicGraph<OwnershipChange>;
+    readonly current: Node<OwnershipState>;
+    readonly allowed: Node<readonly string[]>;
+    readonly guard: NodeGuard;
+    private readonly _ttlNs;
+    private readonly _supervisor;
+    /**
+     * Whether a heartbeat `NodeInput` was supplied at construction (F14 —
+     * `claim()`'s `level` default is `"L2"` when wired, else `"L1"`). NOT a
+     * mutable accumulator — set once in the constructor, read-only after.
+     */
+    private readonly _hasHeartbeat;
+    constructor(name: string, opts: OwnershipControllerOptions);
+    /**
+     * Publish a `claim`. Thin reactive wrapper over `topic.publish` (message
+     * flow per §29 — NOT an imperative trigger). `level` defaults to `"L2"`
+     * when this controller has a heartbeat wired, else `"L1"`.
+     */
+    claim(actor: string, level?: OwnershipLevel): void;
+    /** Publish a `release`. Clears ownership iff `actor` is the current owner. */
+    release(actor: string): void;
+    /**
+     * Publish a supervisor `override` (L3). Wins by `level` priority
+     * regardless of expiry (Q10). `actor` should be this controller's
+     * `supervisor` id for the override to take precedence.
+     */
+    override(actor: string, previousActor: string, reason: string): void;
+}
+/**
+ * Create a multi-agent subgraph ownership controller (DS-14.5.A #8).
+ *
+ * @example
+ * ```ts
+ * const oc = ownershipController("payments", { ttl: 30_000, supervisor: "lead" });
+ * // Mount the Guard on the owned subgraph:
+ * const n = node([], { initial: 0, guard: oc.guard });
+ * oc.claim("agent-a");                 // agent-a now owns; non-owner writes throw
+ * oc.override("lead", "agent-a", "rebalance"); // supervisor takes over
+ * ```
+ */
+declare function ownershipController(name: string, opts: OwnershipControllerOptions): OwnershipControllerGraph;
+
+/**
+ * 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.
+ *
+ * **Snapshot caveat (Unit 22 B).** Reads `.cache` values from the
+ * strategy / retry / reingestion nodes + each queue topic's `.retained()`
+ * view. These are point-in-time reads and are not transactional — if you
+ * invoke this during an in-flight reactive wave the values may reflect
+ * a partially-settled frame. For end-of-wave accuracy, call from outside
+ * any batch boundary.
+ *
+ * @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 work fn.
+ *
+ * Each claimed job mounts a fresh `refineLoop`; when the loop reaches a
+ * terminal status (`converged` / `budget` / `errored`), the work fn emits a
+ * single {@link HarnessJobPayload} with `execution` filled in. The JobFlow
+ * pump subscribes once, takes the first DATA, then unsubscribes — so the
+ * inner loop tears down cleanly when the harness acks the job.
+ *
+ * **C2 lifecycle (Tier 6.5).** The work fn is invoked once per claim, so
+ * no internal `switchMap` is needed (the prior pre-C2 shape used switchMap
+ * to handle a stream of items). The pump owns the per-claim lifecycle:
+ * activation when the work fn returns, teardown when the result Node is
+ * unsubscribed.
+ *
+ * **Cross-item learning:** a fresh refineLoop per item means
+ * `errorCritique`-style failure sampling does NOT accumulate across items
+ * sharing a `rootCause`. A persistent-loop + re-seed surface is filed in
+ * `docs/optimizations.md` as a 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<T>`. Default: converged→success, budget→partial,
+     * errored→failure.
+     */
+    toOutput?: (result: RefineExecutorResult<T>) => ExecuteOutput<T>;
+    /** 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 claimed
+ * job.
+ *
+ * @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<T>;
+
+/**
+ * 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;
+
+export { type ActorHandle, type ActorId, type ActorPoolBundle, type ActorPoolOptions, type ActorSpec, type ActorState, type ActorStatus, DatasetItem, EvalResult, type EvalVerifierConfig, type EvalVerifierSummary, Evaluator, type HarnessEvalPairConfig, HarnessGraph, type HarnessProfileResult, type HarnessTraceHandle, type HarnessTraceOptions, OwnershipControllerGraph, type OwnershipControllerOptions, type OwnershipState, type RefineExecutorConfig, type RefineExecutorResult, RefineLoopOptions, RefineStatus, RefineStrategy, type Todo, type TraceDetail, type TraceEvent, type TraceEventType, actorPool, evalVerifier, harnessEvalPair, harnessProfile, harnessTrace, ownershipController, refineExecutor };