@graphrefly/graphrefly 0.45.0 → 0.46.0

package/dist/types-CJWIMJiZ.d.ts

@@ -0,0 +1,548 @@
+import { Node } from '@graphrefly/pure-ts/core';
+import { NodeInput } from '@graphrefly/pure-ts/extra';
+import { L as LLMAdapter } from './types-BB5Lw-pB.js';
+import { JobEnvelope } from './utils/job-queue/index.js';
+import { Graph, GraphOptions } from '@graphrefly/pure-ts/graph';
+
+/**
+ * `auditedSuccessTracker` — domain-agnostic per-key success-rate tracker.
+ *
+ * Reactive `key → { attempts, successes, successRate }` map mounted as a
+ * Graph subclass. Reusable substrate for any domain that needs to track
+ * outcomes per identifier (routing strategy effectiveness, A/B-test arms,
+ * cache-policy tuning, retry-strategy selection, etc.).
+ *
+ * Replaces the prior `effectivenessTracker` and `strategyModel` factories
+ * (Class B audit Alt E collapse, 2026-04-30). Composite-key callers (e.g.
+ * `rootCause × intervention`) convert to a string key at the call site.
+ *
+ * @module
+ */
+
+/** A single success-rate record for one key. */
+interface AuditedSuccessEntry<TKey extends string = string> {
+    readonly key: TKey;
+    readonly attempts: number;
+    readonly successes: number;
+    readonly successRate: number;
+}
+/** Snapshot shape — fresh `ReadonlyMap` on every mutation. */
+type AuditedSuccessSnapshot<TKey extends string = string, TEntry extends AuditedSuccessEntry<TKey> = AuditedSuccessEntry<TKey>> = ReadonlyMap<TKey, TEntry>;
+/** Options for {@link auditedSuccessTracker}. */
+interface AuditedSuccessTrackerOptions {
+    /** Optional graph identity (passed to the underlying Graph constructor). */
+    graph?: GraphOptions;
+    /** Name of the tracker subgraph. Default `"audited-success-tracker"`. */
+    name?: string;
+}
+/**
+ * Reactive success-rate tracker mounted as a Graph subclass.
+ *
+ * `key → AuditedSuccessEntry` with `record(key, success, extra?)` /
+ * `lookup(key)` methods. The {@link entries} field is a
+ * `Node<ReadonlyMap<TKey, TEntry>>` suitable for graph composition —
+ * exposed under name `"entries"` for `describe()` / `explain()`.
+ *
+ * Backed by the {@link reactiveMap} substrate; each successful `record(...)`
+ * fires a DATA emission carrying the post-mutation map.
+ *
+ * **Field name.** This Graph subclass uses `entries` (not `snapshot`) for
+ * the public-face Node because `Graph.prototype.snapshot()` is the
+ * built-in persistence-snapshot method on the parent class — using
+ * `snapshot` here would shadow it and break DTS generation.
+ *
+ * @typeParam TKey - String-typed key shape. Composite-key domains (e.g.
+ *   `rootCause × intervention`) convert to a string at the call site.
+ * @typeParam TEntry - Entry shape; defaults to {@link AuditedSuccessEntry}.
+ *   Domains that need extra fields (e.g. `rootCause`/`intervention`) extend
+ *   this interface and pass the extra fields via `record(...)`'s `extra` arg.
+ */
+declare class AuditedSuccessTrackerGraph<TKey extends string = string, TEntry extends AuditedSuccessEntry<TKey> = AuditedSuccessEntry<TKey>> extends Graph {
+    /** Reactive entries — `Node<ReadonlyMap<TKey, TEntry>>`, fresh map per mutation. */
+    readonly entries: Node<AuditedSuccessSnapshot<TKey, TEntry>>;
+    private readonly _map;
+    constructor(opts?: AuditedSuccessTrackerOptions);
+    /**
+     * Record a completed attempt. `extra` fields are merged into the stored
+     * entry — use for domain-specific decoration (e.g. `{ rootCause,
+     * intervention }` on the strategy-model collapse path).
+     *
+     * **Caller contract for typed `TEntry`.** When `TEntry` extends
+     * {@link AuditedSuccessEntry} with required fields beyond
+     * `key`/`attempts`/`successes`/`successRate`, the caller must supply
+     * those required fields in `extra` on the **first** `record(key, ...)`
+     * for that key. The internal `as TEntry` cast trusts this. Subsequent
+     * `record(key, ...)` calls inherit the prior entry's fields, so `extra`
+     * may be omitted or partial. Forgetting required fields on the first
+     * record produces an entry whose typed-required fields are `undefined`
+     * at runtime — TS won't catch it. Strategy callers always pass
+     * `{ rootCause, intervention }`, so the StrategyEntry case is safe.
+     */
+    record(key: TKey, success: boolean, extra?: Partial<Omit<TEntry, "key" | "attempts" | "successes" | "successRate">>): void;
+    /**
+     * Look up the entry for a key.
+     *
+     * Pure read: this tracker doesn't configure a TTL on the underlying
+     * `reactiveMap`, so `_map.get(key)` never triggers TTL-expiry pruning
+     * (which would otherwise be an observable side effect emitting a fresh
+     * `entries` snapshot). If `AuditedSuccessTrackerOptions` ever gains a
+     * `mapOptions` carve-out exposing TTL, revisit this contract.
+     */
+    lookup(key: TKey): TEntry | undefined;
+}
+
+/**
+ * Strategy model and priority scoring (roadmap §9.0).
+ *
+ * `strategyModel` returns a typed alias of {@link AuditedSuccessTrackerGraph}
+ * keyed by `StrategyKey` (the composite `rootCause→intervention` string).
+ * The shared substrate (Class B audit Alt E collapse, 2026-04-30) replaces
+ * the prior bespoke bundle shape; composite-key callers use {@link strategyKey}
+ * to compute the key and pass `{ rootCause, intervention }` as record decoration.
+ *
+ * @module
+ */
+
+/** Snapshot shape for the strategy-model `entries` node. */
+type StrategySnapshot = ReadonlyMap<StrategyKey, StrategyEntry>;
+/** Strategy-model graph: a typed alias of {@link AuditedSuccessTrackerGraph}. */
+type StrategyModelGraph = AuditedSuccessTrackerGraph<StrategyKey, StrategyEntry>;
+/**
+ * Create a strategy model that tracks
+ * `presetId × rootCause × intervention → successRate` over completed
+ * issues (presetId axis added in Phase 13.I, 2026-05-01). Returns an
+ * {@link AuditedSuccessTrackerGraph} keyed by {@link StrategyKey}.
+ *
+ * The reactive `entries` field is a `Node<StrategySnapshot>` suitable for
+ * `describe()` / `withLatestFrom` composition.
+ *
+ * Composite-key conversion happens at the call site:
+ * ```ts
+ * const strategy = strategyModel();
+ * strategy.record(strategyKey(presetId, rootCause, intervention), success, {
+ *   presetId,
+ *   rootCause,
+ *   intervention,
+ * });
+ * strategy.lookup(strategyKey(presetId, rootCause, intervention));
+ * ```
+ *
+ * Pass {@link DEFAULT_PRESET_ID} (`"default"`) for the presetId axis when
+ * no preset registry is wired (single-agent harness).
+ *
+ * The model feeds back into TRIAGE for routing hints.
+ */
+declare function strategyModel(): StrategyModelGraph;
+/**
+ * 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.
+ *
+ * **Age sampling caveat.** The `ageSeconds` term is computed as
+ * `monotonicNs() - lastInteractionNs.cache` at *each reactive update*. If
+ * nothing upstream settles, the score node does not recompute — so a
+ * long-idle queue may show a stale score. Pass a `fromTimer(...)`-driven
+ * node as a dep (or re-emit on `lastInteractionNs`) when live age decay
+ * matters.
+ *
+ * **Not the same as `TriagedItem.priority`.** The LLM-emitted
+ * `priority: 0..100` field on each triaged item is decorative today — the
+ * queue consumption order ignores it (tracked in `docs/optimizations.md`
+ * as a priority-ordered queue enhancement). This function computes an
+ * orthogonal reactive score; it does NOT override the LLM's per-item
+ * priority, nor does it drive queue ordering. Wire it to
+ * `HarnessGraph.priorityScores` to surface per-route pressure.
+ *
+ * @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>;
+
+/**
+ * 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.
+ *
+ * Runtime constants and helpers live in `./defaults.ts`. The harness barrel
+ * (`./index.ts`) re-exports both so external consumers see a single surface.
+ *
+ * @module
+ */
+
+/** Known intake source tags. */
+type KnownIntakeSource = "eval" | "test" | "human" | "code-change" | "hypothesis" | "parity";
+/**
+ * Sources that can produce intake items. Open union — the known tags
+ * retain IDE autocomplete while user-supplied strings (e.g. `"schema"`,
+ * `"slack"`) pass through without a type change.
+ */
+type IntakeSource = KnownIntakeSource | (string & {});
+/** 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. Closed union — iterated via `QUEUE_NAMES`. */
+type QueueRoute = "auto-fix" | "needs-decision" | "investigation" | "backlog";
+/**
+ * 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.
+ *
+ * `$`-prefix keys (`$reingestions`, `$retries` on {@link TriagedItem}) are
+ * framework-only — an LLM round-tripping the serialized item is far less
+ * likely to echo back a `$`-prefixed key than an `_`-prefixed one, which
+ * neutralizes the field-collision class that surfaced earlier in the
+ * router's spread order.
+ */
+interface IntakeItem {
+    source: IntakeSource;
+    summary: string;
+    evidence: string;
+    affectsAreas: string[];
+    affectsEvalTasks?: string[];
+    severity?: Severity;
+    /**
+     * Identity-preservation key for retried / reingested items.
+     *
+     * `relatedTo[0]` MUST carry the original tracking key for retry /
+     * reingest items so the harness's `routeJobIds` map preserves
+     * identity across decorated retry summaries (per qa D1, 2026-04-29).
+     * First-time publishes leave this `undefined`; the tracking key
+     * falls back to `summary` via {@link trackingKey}.
+     *
+     * **Collision contract (DS-13.5.D.3, locked 2026-05-01).** Items
+     * lacking `relatedTo[0]` and producing colliding `trackingKey()`
+     * derivations overwrite the prior `routeJobIds` entry —
+     * **last-write-wins**. Framework-enforced uniqueness was rejected
+     * because it would break legitimate retry / reingest patterns where
+     * an explicit `relatedTo[0]` carries the original key forward.
+     *
+     * **Single-threaded contract.** Ack runs before reingest publishes
+     * (harness flow invariant) — under the standard single-threaded JS
+     * pump this collapses the only practical race window. Multi-publisher
+     * concurrency or batched intake of two first-time items with identical
+     * `summary` can still race at boundaries; callers carrying their own
+     * stable id should set `relatedTo[0]`.
+     *
+     * See {@link trackingKey} JSDoc in `patterns/_internal/index.ts` for
+     * the uniqueness caller contract.
+     *
+     * Spec: docs/implementation-plan.md DS-13.5.D.3
+     */
+    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;
+}
+/**
+ * Preset / persona / skill identifier. Open string set; conventionally
+ * matches keys used in {@link presetRegistry} (Phase 13.H). Use
+ * {@link DEFAULT_PRESET_ID} ("default") when no preset registry is wired.
+ */
+type PresetId = string;
+/** Default presetId used when no preset registry is wired (back-compat for 2-axis callers). */
+declare const DEFAULT_PRESET_ID: PresetId;
+/**
+ * Key format: `${presetId}|${rootCause}→${intervention}`.
+ *
+ * **Phase 13.I axis extension (DS-13.I, 2026-05-01).** Widened from the
+ * pre-multi-agent 2-axis `${rootCause}→${intervention}` to a 3-axis key
+ * carrying the presetId of the agent that ran. Pre-1.0 breaking change;
+ * existing callsites pass {@link DEFAULT_PRESET_ID} for the new axis when
+ * they don't have a preset registry wired. The strategy-model storage
+ * (`auditedSuccessTracker<StrategyKey, StrategyEntry>`) is unchanged
+ * structurally — the key shape change cascades through the existing
+ * tracker without surface refactor.
+ */
+type StrategyKey = `${PresetId}|${RootCause}→${Intervention}`;
+/**
+ * Effectiveness record for a `(presetId, rootCause, intervention)` triple.
+ * Stored under `auditedSuccessTracker<StrategyKey, StrategyEntry>` (Class B
+ * audit Alt E collapse, 2026-04-30; presetId axis added Phase 13.I,
+ * 2026-05-01) — `key` is the composite `strategyKey(presetId, rc, intv)`
+ * computed at the call site; `presetId` / `rootCause` / `intervention` are
+ * decoration carried via `record(...)` so consumers can read them without
+ * re-parsing the key.
+ */
+interface StrategyEntry {
+    key: StrategyKey;
+    presetId: PresetId;
+    rootCause: RootCause;
+    intervention: Intervention;
+    attempts: number;
+    successes: number;
+    successRate: number;
+}
+/**
+ * LLM output shape from the EXECUTE stage (partial — lacks `item`).
+ *
+ * Generic over the artifact type `A` so typed executors like
+ * `refineExecutor<T>` can flow `T` through to an `evalVerifier<T>` without
+ * the caller casting `artifact` at the boundary. Defaults to `unknown`
+ * for escape-hatch executors that carry opaque state.
+ */
+type ExecuteOutput<A = unknown> = {
+    /**
+     * Execution outcome classification:
+     *
+     * - `"success"`: execution completed cleanly and the artifact (if any) is
+     *   ready for verification. The verifier should proceed with a full
+     *   evaluation pass.
+     * - `"failure"`: execution did not produce a usable artifact — the actuator
+     *   threw, a prompt parse failed, or `shouldApply` skipped the item. The
+     *   verifier should treat this as a non-result and route accordingly.
+     * - `"partial"`: execution produced a candidate that converged but did not
+     *   fully meet verification criteria. Used by `refineExecutor` when the
+     *   iteration cap is reached without full convergence; the artifact holds
+     *   the best candidate achieved.
+     */
+    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?: A;
+};
+/** Full execution result assembled downstream (LLM output + context). */
+interface ExecutionResult<A = unknown> {
+    item: TriagedItem;
+    /**
+     * Execution outcome classification. Same semantics as
+     * {@link ExecuteOutput.outcome}:
+     *
+     * - `"success"`: execution completed cleanly; artifact is ready for
+     *   verification.
+     * - `"failure"`: no usable artifact was produced.
+     * - `"partial"`: best candidate produced but convergence criteria not met
+     *   (iteration cap reached in `refineExecutor`).
+     */
+    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?: A;
+}
+/** 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;
+/** Result of the VERIFY stage. */
+interface VerifyResult<A = unknown> {
+    item: TriagedItem;
+    execution: ExecutionResult<A>;
+    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;
+}
+
+/** 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? Only meaningful when `gated: true`. */
+    startOpen?: boolean;
+}
+/**
+ * Accumulating per-job payload threaded through the harness's
+ * `executeFlow` ({@link harnessLoop} Tier 6.5 C2 lock). Each stage's work fn
+ * receives the prior payload and returns a new one with its own field
+ * filled in:
+ *
+ * - The `enqueueEffect` seeds with `{ item }` only.
+ * - The execute work fn fills `execution`.
+ * - The verify work fn fills `verify`.
+ *
+ * The post-completed dispatch effect reads `verify.verified` /
+ * `verify.errorClass` to route the item to `verifyResults` /
+ * `retryTopic.publish(...)` / `intake.publish(...)` (3-way verdict).
+ *
+ * Carrying `item` through stage payloads (rather than re-pairing via a
+ * separate `withLatestFrom` node) is the C2 deviation from today's
+ * `executeContextNode` design: each `JobEnvelope` is self-contained, so the
+ * verify pump can run multiple in-flight jobs in parallel without an
+ * external pairing node.
+ */
+interface HarnessJobPayload<A = unknown> {
+    /** The triaged item flowing through execute → verify → dispatch. */
+    item: TriagedItem;
+    /** Filled by the execute work fn. Verify reads this; dispatch routes. */
+    execution?: ExecutionResult<A>;
+    /** Filled by the verify work fn. Dispatch reads `verified` / `errorClass`. */
+    verify?: VerifyOutput;
+}
+/**
+ * Pluggable EXECUTE work fn — receives a {@link JobEnvelope} carrying a
+ * {@link HarnessJobPayload} (with `item` set, `execution` / `verify`
+ * unset), returns a {@link NodeInput} that emits the same payload with
+ * `execution` filled.
+ *
+ * **C2 contract (Tier 6.5 lock, 2026-04-28):**
+ * 1. Emit DATA exactly once per claimed job. The JobFlow pump subscribes
+ *    once, takes the first DATA, then unsubscribes. Subsequent emissions
+ *    are ignored.
+ * 2. Errors must be caught and surfaced as a `failure` outcome inside the
+ *    payload — never throw / return ERROR. A pump nack would drop the
+ *    item from JobFlow before the dispatch effect could route it.
+ * 3. The work fn runs once per claim — no internal `switchMap` needed.
+ *    Per-item subgraphs (e.g. a fresh `refineLoop` per claim) are
+ *    instantiated inside the work fn body.
+ *
+ * `defaultLlmExecutor` (in `defaults.ts`) is a thin `adapter.invoke()`
+ * wrapper. `refineExecutor` builds a per-claim `refineLoop`.
+ * `actuatorExecutor` runs a side-effecting `apply(item, signal)`.
+ */
+type HarnessExecutor<A = unknown> = (job: JobEnvelope<HarnessJobPayload<A>>, opts?: {
+    signal: AbortSignal;
+}) => NodeInput<HarnessJobPayload<A>>;
+/**
+ * Pluggable VERIFY work fn — receives a {@link JobEnvelope} whose payload
+ * has `item` + `execution` populated, returns a {@link NodeInput} that
+ * emits the same payload with `verify` filled.
+ *
+ * Same C2 contract rules 1–3 as {@link HarnessExecutor}. The dispatch
+ * effect downstream reads `verify.verified` (success → ack +
+ * verifyResults publish), `verify.errorClass === "self-correctable"`
+ * (retry → republish to retry topic with `$retries` bumped), or anything
+ * else (structural → reingest to intake if budget remains).
+ *
+ * Verify-LLM-call failures (parse error, adapter throw, timeout) MUST be
+ * caught and surfaced as a structural-failure `verify` payload (`{
+ * verified: false, findings: [...], errorClass: "structural" }`) so the
+ * dispatch effect can route the item rather than silently drop it.
+ */
+type HarnessVerifier<A = unknown> = (job: JobEnvelope<HarnessJobPayload<A>>, opts?: {
+    signal: AbortSignal;
+}) => NodeInput<HarnessJobPayload<A>>;
+/** Triage prompt callable shape — pair of `[intake item, strategy snapshot]`. */
+type TriagePromptFn = (pair: readonly [IntakeItem, StrategySnapshot]) => string;
+/** Execute prompt callable shape. */
+type ExecutePromptFn = (item: TriagedItem) => string;
+/** Verify prompt callable shape — pair of `[execute output, triaged item]`. */
+type VerifyPromptFn<A = unknown> = (pair: readonly [ExecuteOutput<A> | null, TriagedItem | null]) => string;
+/** Options for {@link harnessLoop}. */
+interface HarnessLoopOptions<A = unknown> {
+    /** LLM adapter for promptNode-based stages (triage + any default executor/verifier). */
+    adapter: LLMAdapter;
+    /** Custom triage prompt (receives IntakeItem + strategy snapshot as a tuple). */
+    triagePrompt?: string | TriagePromptFn;
+    /**
+     * Execute prompt — sugar over the default LLM executor. Ignored when
+     * `executor` is set.
+     */
+    executePrompt?: string | ExecutePromptFn;
+    /**
+     * Verify prompt — sugar over the default LLM verifier. Ignored when
+     * `verifier` is set.
+     */
+    verifyPrompt?: string | VerifyPromptFn<A>;
+    /**
+     * 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<A>;
+    /**
+     * 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<A>;
+    /** Per-queue configuration overrides. */
+    queues?: Partial<Record<QueueRoute, QueueConfig>>;
+    /** Priority scoring signals. */
+    priority?: PrioritySignals;
+    /**
+     * Reactive last-human-interaction timestamp (monotonic ns). Drives the
+     * priority score age-decay term for `HarnessGraph.priorityScores`.
+     *
+     * **Required when `opts.priority` is set.** Priority score nodes only
+     * re-derive when `topic.latest`, `strategy.snapshot`, or this tick settles —
+     * an idle queue would freeze its age at construction time if we
+     * auto-defaulted. Typical sources:
+     *  - `fromTimer(60_000)` — steady tick, uniform decay.
+     *  - `state(monotonicNs())` — bumped from a human-interaction handler.
+     *  - A reactive view over a DB column / external metrics source.
+     */
+    lastInteractionNs?: Node<number>;
+    /** 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;
+    /**
+     * Per-pump-tick claim cap on the internal `executeFlow` JobFlow's `execute`
+     * stage (Tier 6.5 C2). Default `Number.MAX_SAFE_INTEGER` — every pending
+     * claim is processed in one tick (matches today's unbounded `merge()`
+     * parallelism). Lower this to bound LLM cost spikes on bursty intake.
+     *
+     * **Caveat.** This caps **claims per pump tick**, not total concurrent
+     * inflight. Bounded-inflight is a separate primitive concern — see
+     * `docs/optimizations.md` "Tier 6.5 follow-up — bounded concurrent inflight
+     * on JobFlow stages".
+     */
+    executeMaxPerPump?: number;
+    /**
+     * Per-pump-tick claim cap on the internal `executeFlow` JobFlow's
+     * `verify` stage. Default `Number.MAX_SAFE_INTEGER`. Same caveat as
+     * {@link HarnessLoopOptions.executeMaxPerPump}. Honored independently
+     * of the execute cap via `StageDef.maxPerPump` (Tier 6.5 D1).
+     */
+    verifyMaxPerPump?: number;
+}
+
+export { DEFAULT_PRESET_ID as D, type ErrorClass as E, type HarnessExecutor as H, type IntakeItem as I, type KnownIntakeSource as K, type PresetId as P, type QueueConfig as Q, type RootCause as R, type Severity as S, type TriagePromptFn as T, type VerifyOutput as V, type ErrorClassifier as a, type ExecuteOutput as b, type ExecutePromptFn as c, type ExecutionResult as d, type HarnessJobPayload as e, type HarnessLoopOptions as f, type HarnessVerifier as g, type IntakeSource as h, type Intervention as i, type PrioritySignals as j, type QueueRoute as k, type StrategyEntry as l, type StrategyKey as m, type StrategyModelGraph as n, type StrategySnapshot as o, type TriagedItem as p, type VerifyPromptFn as q, type VerifyResult as r, priorityScore as s, strategyModel as t };