@tangle-network/agent-eval 0.122.3 → 0.122.4

package/dist/benchmarks/index.js

@@ -16,10 +16,10 @@ import {
   routing_exports,
   runBenchmarkAdapter,
   summarizeBenchmarkCampaign
-} from "../chunk-OZFTLMGS.js";
-import "../chunk-IDC74VDL.js";
-import "../chunk-DHJJACEX.js";
-import "../chunk-N3QPYIVG.js";
+} from "../chunk-GTSVLG2M.js";
+import "../chunk-75OCWDXJ.js";
+import "../chunk-MWN2X7C5.js";
+import "../chunk-4R4GTZBZ.js";
 import "../chunk-EAWKAVID.js";
 import "../chunk-ARU2PZFM.js";
 import "../chunk-NJC7U437.js";

package/dist/campaign/index.d.ts

@@ -2,6 +2,254 @@ import { z } from 'zod';
 import { AxAIService, AxAgentActorTurnCallbackArgs, AxFunction, AxAIArgs } from '@ax-llm/ax';
 import { AgentProfile } from '@tangle-network/agent-interface';
 
+/**
+ * Error taxonomy for `@tangle-network/agent-eval`.
+ *
+ * Every error this package throws as part of its *public contract* extends
+ * `AgentEvalError`. Consumers can pattern-match by `instanceof <Subclass>` or
+ * by the stable string `code` carried on the base class.
+ *
+ * The codes are stable across minor versions; new codes can be added, but
+ * existing codes never change meaning. New subclasses are non-breaking.
+ *
+ * Internal invariant guards (`throw new Error('this should never happen')`)
+ * remain plain `Error`s on purpose — they're programmer-mistake assertions,
+ * not consumer-catchable contract failures.
+ */
+type AgentEvalErrorCode = 'validation' | 'not_found' | 'config' | 'capture_integrity' | 'judge' | 'verification' | 'replay' | 'backend_integrity' | 'profile_matrix';
+/**
+ * Base class for every contract error this package throws — carries the stable
+ * string `code` taxonomy so consumers can `instanceof`-match or switch on `code`.
+ */
+declare class AgentEvalError extends Error {
+    /** Stable string code. Survives minification; safe to switch on. */
+    readonly code: AgentEvalErrorCode;
+    constructor(code: AgentEvalErrorCode, message: string, options?: {
+        cause?: unknown;
+    });
+}
+/** Caller passed invalid arguments (out of range, mutually-exclusive options, bad shape). */
+declare class ValidationError extends AgentEvalError {
+    constructor(message: string, options?: {
+        cause?: unknown;
+    });
+}
+
+type CostChannel = 'agent' | 'judge' | 'verifier' | 'analyst' | 'driver' | (string & {});
+interface CostUsage {
+    inputTokens: number;
+    /** Includes reasoning tokens when the provider bills them as output. */
+    outputTokens: number;
+    /** Reasoning-token subset of outputTokens, when reported. */
+    reasoningTokens?: number;
+    /** Prompt tokens served from a provider cache. */
+    cachedTokens?: number;
+    /** Prompt tokens written into a provider cache. */
+    cacheWriteTokens?: number;
+}
+interface CostCallBase {
+    callId: string;
+    channel: CostChannel;
+    phase: string;
+    actor: string;
+    model: string;
+    maximumCostUsd?: number;
+    tags?: Record<string, string>;
+    timestamp: number;
+}
+interface CostReceipt extends CostCallBase, CostUsage {
+    status: 'settled';
+    costUsd: number;
+    costUnknown: boolean;
+    usageUnknown?: boolean;
+    pricing?: {
+        inputUsdPerThousand: number;
+        outputUsdPerThousand: number;
+    };
+    actualCostUsd?: number;
+    error?: string;
+}
+interface CostReceiptInput extends CostUsage {
+    model: string;
+    actualCostUsd?: number;
+    costUnknown?: boolean;
+    usageUnknown?: boolean;
+}
+type MaximumCharge = {
+    externallyEnforcedMaximumUsd: number;
+} | ({
+    model: string;
+} & CostUsage);
+interface RunPaidCallInput<T> {
+    callId?: string;
+    channel: CostChannel;
+    phase: string;
+    actor: string;
+    /** Used before a provider receipt exists and on failures without one. */
+    model?: string;
+    tags?: Record<string, string>;
+    signal?: AbortSignal;
+    /** Provider-enforced dollar maximum, or maximum priced token usage. Required when capped. */
+    maximumCharge?: MaximumCharge;
+    /** `callId` can be forwarded as the provider's idempotency key. */
+    execute(signal: AbortSignal, callId: string): Promise<T>;
+    receipt(value: T): CostReceiptInput;
+    receiptFromError?(error: Error): CostReceiptInput | undefined;
+}
+type PaidCallResult<T> = {
+    succeeded: true;
+    callId: string;
+    value: T;
+    receipt: CostReceipt;
+} | {
+    succeeded: false;
+    callId?: string;
+    error: Error;
+    receipt?: CostReceipt;
+};
+interface ChannelRollup {
+    channel: CostChannel;
+    calls: number;
+    inputTokens: number;
+    outputTokens: number;
+    reasoningTokens?: number;
+    cachedTokens: number;
+    cacheWriteTokens?: number;
+    costUsd: number;
+    unpricedCalls: number;
+    unknownUsageCalls: number;
+}
+interface CostLedgerSummary {
+    totalCalls: number;
+    pendingCalls: number;
+    unresolvedCalls: number;
+    reservedCostUsd: number;
+    inputTokens: number;
+    outputTokens: number;
+    reasoningTokens?: number;
+    cachedTokens: number;
+    cacheWriteTokens?: number;
+    totalCostUsd: number;
+    byChannel: ChannelRollup[];
+    unpricedModels: string[];
+    fullyPriced: boolean;
+    usageComplete: boolean;
+    accountingComplete: boolean;
+    incompleteReasons: string[];
+}
+interface CostLedgerFilter {
+    channel?: CostChannel;
+    phase?: string;
+    tags?: Record<string, string>;
+}
+interface CostLedgerWaitOptions {
+    /** Maximum time to wait for active provider calls. Default 5 seconds. */
+    timeoutMs?: number;
+}
+/** Append-only storage. `append` must atomically reject stale revisions. */
+interface CostLedgerPersistence {
+    read(): {
+        revision: string;
+        events: string;
+    };
+    append(expectedRevision: string, event: string): string | undefined;
+}
+interface CostLedgerOptions {
+    costCeilingUsd?: number;
+    persistence?: CostLedgerPersistence;
+    /** Import already-settled receipts without admitting new paid work. */
+    receipts?: readonly CostReceipt[];
+}
+/** Run-wide paid-call admission, durable call state, receipts, and summaries. */
+declare class CostLedger {
+    private readonly records;
+    private readonly activeCallIds;
+    private readonly lateCallIds;
+    private readonly idleWaiters;
+    private completedTasks;
+    private revision;
+    private costLimitPersisted;
+    readonly costCeilingUsd?: number;
+    private readonly persistence?;
+    constructor(input?: number | CostLedgerOptions);
+    runPaidCall<T>(input: RunPaidCallInput<T>): Promise<PaidCallResult<T>>;
+    /** Wait until every call started by this ledger has produced a durable outcome. */
+    waitForIdle(options?: CostLedgerWaitOptions): Promise<boolean>;
+    /** Settle a call left pending by a crashed process after reconciling with the provider. */
+    reconcile(callId: string, observed: CostReceiptInput, options?: {
+        error?: string;
+    }): CostReceipt;
+    list(filter?: CostLedgerFilter): CostReceipt[];
+    summary(filter?: CostLedgerFilter): CostLedgerSummary;
+    markCompleted(count?: number): void;
+    costPerCompletedTask(): number | null;
+    private execute;
+    private captureLateOutcome;
+    private releaseActiveCall;
+    private commitOutcome;
+    private captureFailure;
+    private commitReceipt;
+    private resolveMaximum;
+    private hasIncompleteSettledCall;
+    private appendRecord;
+    private ensureCostLimitPersisted;
+    private appendEvent;
+}
+/** Public callback surface for a shared cost ledger.
+ *
+ * Declaration bundles may expose this type through multiple package subpaths.
+ * Keeping callback contracts structural lets those subpaths compose while the
+ * concrete {@link CostLedger} retains its private durable state.
+ */
+type CostLedgerHandle = Pick<CostLedger, Exclude<keyof CostLedger, 'waitForIdle'>> & Partial<Pick<CostLedger, 'waitForIdle'>>;
+
+/**
+ * `CampaignStorage` — the filesystem seam `runCampaign` writes through
+ * (run/cell dirs, the resumability cache, per-cell artifacts, trace spans).
+ *
+ * The default (`fsCampaignStorage`) is the Node filesystem — identical
+ * behavior to the inline `node:fs` calls it replaces, so existing CLI
+ * consumers are unaffected. `inMemoryCampaignStorage` keeps everything in a
+ * `Map`, so the substrate runs in environments WITHOUT a filesystem
+ * (Cloudflare Workers, Deno Deploy, other edge runtimes) — the campaign
+ * still produces its `CampaignResult` (cells + aggregates) in memory;
+ * artifacts/traces simply aren't persisted to disk.
+ *
+ * Paths are opaque keys to the in-memory adapter — it does not parse them,
+ * so the same `join(...)`-built paths work unchanged across both adapters.
+ */
+interface CampaignStorage {
+    /** Ensure a directory exists (recursive). No-op for in-memory. */
+    ensureDir(dir: string): void;
+    /** Does this path exist (as a written file or an ensured dir)? */
+    exists(path: string): boolean;
+    /** Read a UTF-8 file; `undefined` when missing or unreadable. */
+    read(path: string): string | undefined;
+    /** Write a file (string or bytes). Parent dir is assumed ensured. */
+    write(path: string, content: string | Uint8Array): void;
+    /** Append only when the current UTF-8 byte length matches `expectedBytes`.
+     * Returns the new length, or undefined when another writer won. */
+    append?(path: string, content: string, expectedBytes: number): number | undefined;
+}
+/** Node-filesystem storage — the default. Lazily requires `node:fs` so the
+ *  module imports cleanly in non-Node runtimes (where the caller passes
+ *  `inMemoryCampaignStorage` instead and never constructs this).
+ *
+ *  `createRequire(import.meta.url)` is the ESM-native lazy require — a bare
+ *  `require` is a ReferenceError under `"type": "module"`, which is exactly
+ *  the shape this package publishes. */
+declare function fsCampaignStorage(): CampaignStorage;
+/** In-memory storage for filesystem-less runtimes. Artifacts + trace spans
+ *  live in a `Map` for the duration of the run; the `CampaignResult` is
+ *  fully populated, but nothing is persisted to disk. */
+declare function inMemoryCampaignStorage(): CampaignStorage;
+/** Open the durable spend account stored beside a logical run. */
+declare function createRunCostLedger(input: {
+    storage: CampaignStorage;
+    runDir: string;
+    costCeilingUsd?: number;
+}): CostLedger;
+
 /**
  * Lineage DAG — a git-graph of improvement candidates.
  *
@@ -26,6 +274,7 @@ import { AgentProfile } from '@tangle-network/agent-interface';
  * Ids are content+lineage hashes; order is a monotone insertion counter; every
  * query returns nodes in `seq` order. Same inputs ⇒ identical graph.
  */
+
 interface LineageNode {
     /** Deterministic content+lineage hash (see {@link lineageNodeId}). */
     id: string;
@@ -138,13 +387,23 @@ declare class Lineage {
 interface LineageStore {
     /** Load the persisted lineage (an empty `Lineage` when nothing is stored). */
     load(): Promise<Lineage>;
-    /** Append one node durably. */
+    /** Persist one node durably and idempotently; conflicting content must throw. */
     append(node: LineageNode): Promise<void>;
     /** Overwrite with a full snapshot. */
     save(lineage: Lineage): Promise<void>;
 }
-/** JSONL-file store: append-only durability, snapshot via rewrite, `load` parses
- *  through {@link Lineage.fromJSONL}. */
+declare class LineageStoreConflictError extends Error {
+    readonly name = "LineageStoreConflictError";
+}
+/**
+ * Store a lineage through CampaignStorage. Appends use its compare-and-append
+ * primitive, so retries are idempotent and a second controller fails instead
+ * of assigning the same sequence number to different nodes.
+ */
+declare function campaignLineageStore(storage: CampaignStorage, path: string, options?: {
+    maxAppendAttempts?: number;
+}): LineageStore;
+/** Filesystem convenience over the conflict-safe CampaignStorage implementation. */
 declare function fsLineageStore(path: string): LineageStore;
 /** In-memory store (default; for tests and ephemeral runs). */
 declare function memLineageStore(): LineageStore;
@@ -223,7 +482,10 @@ interface RunLineageOptions {
     }) => Promise<Omit<RunLineageStepResult, 'gate'>>;
     governor: Governor;
     budget: {
+        /** Maximum controller operations in this invocation. */
         maxSteps: number;
+        /** Optional maximum persisted nodes across every resumed invocation. */
+        maxNodes?: number;
     };
     store?: LineageStore;
     log?: (msg: string, fields?: Record<string, unknown>) => void;
@@ -239,39 +501,6 @@ interface RunLineageResult {
  *  every node. Honors `prune`: a pruned track is never extended or branched again. */
 declare function runLineage(opts: RunLineageOptions): Promise<RunLineageResult>;
 
-/**
- * Error taxonomy for `@tangle-network/agent-eval`.
- *
- * Every error this package throws as part of its *public contract* extends
- * `AgentEvalError`. Consumers can pattern-match by `instanceof <Subclass>` or
- * by the stable string `code` carried on the base class.
- *
- * The codes are stable across minor versions; new codes can be added, but
- * existing codes never change meaning. New subclasses are non-breaking.
- *
- * Internal invariant guards (`throw new Error('this should never happen')`)
- * remain plain `Error`s on purpose — they're programmer-mistake assertions,
- * not consumer-catchable contract failures.
- */
-type AgentEvalErrorCode = 'validation' | 'not_found' | 'config' | 'capture_integrity' | 'judge' | 'verification' | 'replay' | 'backend_integrity' | 'profile_matrix';
-/**
- * Base class for every contract error this package throws — carries the stable
- * string `code` taxonomy so consumers can `instanceof`-match or switch on `code`.
- */
-declare class AgentEvalError extends Error {
-    /** Stable string code. Survives minification; safe to switch on. */
-    readonly code: AgentEvalErrorCode;
-    constructor(code: AgentEvalErrorCode, message: string, options?: {
-        cause?: unknown;
-    });
-}
-/** Caller passed invalid arguments (out of range, mutually-exclusive options, bad shape). */
-declare class ValidationError extends AgentEvalError {
-    constructor(message: string, options?: {
-        cause?: unknown;
-    });
-}
-
 type AgentProfileCellSchemaVersion = 'agent-profile-cell/v1';
 type AgentProfileJson = string | number | boolean | null | AgentProfileJson[] | {
     [key: string]: AgentProfileJson;
@@ -299,174 +528,6 @@ interface AgentProfileCell {
     dimensions?: Record<string, AgentProfileDimensionValue>;
 }
 
-type CostChannel = 'agent' | 'judge' | 'verifier' | 'analyst' | 'driver' | (string & {});
-interface CostUsage {
-    inputTokens: number;
-    /** Includes reasoning tokens when the provider bills them as output. */
-    outputTokens: number;
-    /** Reasoning-token subset of outputTokens, when reported. */
-    reasoningTokens?: number;
-    /** Prompt tokens served from a provider cache. */
-    cachedTokens?: number;
-    /** Prompt tokens written into a provider cache. */
-    cacheWriteTokens?: number;
-}
-interface CostCallBase {
-    callId: string;
-    channel: CostChannel;
-    phase: string;
-    actor: string;
-    model: string;
-    maximumCostUsd?: number;
-    tags?: Record<string, string>;
-    timestamp: number;
-}
-interface CostReceipt extends CostCallBase, CostUsage {
-    status: 'settled';
-    costUsd: number;
-    costUnknown: boolean;
-    usageUnknown?: boolean;
-    pricing?: {
-        inputUsdPerThousand: number;
-        outputUsdPerThousand: number;
-    };
-    actualCostUsd?: number;
-    error?: string;
-}
-interface CostReceiptInput extends CostUsage {
-    model: string;
-    actualCostUsd?: number;
-    costUnknown?: boolean;
-    usageUnknown?: boolean;
-}
-type MaximumCharge = {
-    externallyEnforcedMaximumUsd: number;
-} | ({
-    model: string;
-} & CostUsage);
-interface RunPaidCallInput<T> {
-    callId?: string;
-    channel: CostChannel;
-    phase: string;
-    actor: string;
-    /** Used before a provider receipt exists and on failures without one. */
-    model?: string;
-    tags?: Record<string, string>;
-    signal?: AbortSignal;
-    /** Provider-enforced dollar maximum, or maximum priced token usage. Required when capped. */
-    maximumCharge?: MaximumCharge;
-    /** `callId` can be forwarded as the provider's idempotency key. */
-    execute(signal: AbortSignal, callId: string): Promise<T>;
-    receipt(value: T): CostReceiptInput;
-    receiptFromError?(error: Error): CostReceiptInput | undefined;
-}
-type PaidCallResult<T> = {
-    succeeded: true;
-    callId: string;
-    value: T;
-    receipt: CostReceipt;
-} | {
-    succeeded: false;
-    callId?: string;
-    error: Error;
-    receipt?: CostReceipt;
-};
-interface ChannelRollup {
-    channel: CostChannel;
-    calls: number;
-    inputTokens: number;
-    outputTokens: number;
-    reasoningTokens?: number;
-    cachedTokens: number;
-    cacheWriteTokens?: number;
-    costUsd: number;
-    unpricedCalls: number;
-    unknownUsageCalls: number;
-}
-interface CostLedgerSummary {
-    totalCalls: number;
-    pendingCalls: number;
-    unresolvedCalls: number;
-    reservedCostUsd: number;
-    inputTokens: number;
-    outputTokens: number;
-    reasoningTokens?: number;
-    cachedTokens: number;
-    cacheWriteTokens?: number;
-    totalCostUsd: number;
-    byChannel: ChannelRollup[];
-    unpricedModels: string[];
-    fullyPriced: boolean;
-    usageComplete: boolean;
-    accountingComplete: boolean;
-    incompleteReasons: string[];
-}
-interface CostLedgerFilter {
-    channel?: CostChannel;
-    phase?: string;
-    tags?: Record<string, string>;
-}
-interface CostLedgerWaitOptions {
-    /** Maximum time to wait for active provider calls. Default 5 seconds. */
-    timeoutMs?: number;
-}
-/** Append-only storage. `append` must atomically reject stale revisions. */
-interface CostLedgerPersistence {
-    read(): {
-        revision: string;
-        events: string;
-    };
-    append(expectedRevision: string, event: string): string | undefined;
-}
-interface CostLedgerOptions {
-    costCeilingUsd?: number;
-    persistence?: CostLedgerPersistence;
-    /** Import already-settled receipts without admitting new paid work. */
-    receipts?: readonly CostReceipt[];
-}
-/** Run-wide paid-call admission, durable call state, receipts, and summaries. */
-declare class CostLedger {
-    private readonly records;
-    private readonly activeCallIds;
-    private readonly lateCallIds;
-    private readonly idleWaiters;
-    private completedTasks;
-    private revision;
-    private costLimitPersisted;
-    readonly costCeilingUsd?: number;
-    private readonly persistence?;
-    constructor(input?: number | CostLedgerOptions);
-    runPaidCall<T>(input: RunPaidCallInput<T>): Promise<PaidCallResult<T>>;
-    /** Wait until every call started by this ledger has produced a durable outcome. */
-    waitForIdle(options?: CostLedgerWaitOptions): Promise<boolean>;
-    /** Settle a call left pending by a crashed process after reconciling with the provider. */
-    reconcile(callId: string, observed: CostReceiptInput, options?: {
-        error?: string;
-    }): CostReceipt;
-    list(filter?: CostLedgerFilter): CostReceipt[];
-    summary(filter?: CostLedgerFilter): CostLedgerSummary;
-    markCompleted(count?: number): void;
-    costPerCompletedTask(): number | null;
-    private execute;
-    private captureLateOutcome;
-    private releaseActiveCall;
-    private commitOutcome;
-    private captureFailure;
-    private commitReceipt;
-    private resolveMaximum;
-    private hasIncompleteSettledCall;
-    private appendRecord;
-    private ensureCostLimitPersisted;
-    private appendEvent;
-}
-/** Public callback surface for a shared cost ledger.
- *
- * Declaration bundles may expose this type through multiple package subpaths.
- * Keeping callback contracts structural lets those subpaths compose while the
- * concrete {@link CostLedger} retains its private durable state.
- */
-type CostLedgerHandle = Pick<CostLedger, Exclude<keyof CostLedger, 'waitForIdle'>> & Partial<Pick<CostLedger, 'waitForIdle'>>;
-
 type FailureClass = 'success' | 'reasoning_error' | 'tool_selection_error' | 'tool_argument_error' | 'tool_recovery_failure' | 'hallucination' | 'instruction_following' | 'safety_refusal_miss' | 'policy_violation' | 'budget_exceeded' | 'format_drift' | 'permission_escalation' | 'pii_leak' | 'cost_overrun' | 'timeout' | 'sandbox_failure' | 'missing_user_data' | 'missing_domain_data' | 'missing_codebase_context' | 'missing_runtime_context' | 'missing_credentials' | 'missing_integration_connection' | 'missing_integration_scope' | 'integration_approval_required' | 'integration_auth_expired' | 'integration_provider_failure' | 'bad_integration_manifest' | 'unsafe_integration_write_denied' | 'stale_external_data' | 'bad_retrieval' | 'insufficient_evidence' | 'contradictory_evidence' | 'ambiguous_user_intent' | 'knowledge_readiness_blocked' | 'unknown';
 
 /**
@@ -2838,53 +2899,6 @@ interface CrossSurfaceInteractionReport<TRow extends CrossSurfaceTaskRow = Cross
  */
 declare function analyzeCrossSurfaceInteractions<TRow extends CrossSurfaceTaskRow>(input: AnalyzeCrossSurfaceInteractionsInput<TRow>): CrossSurfaceInteractionReport<TRow>;
 
-/**
- * `CampaignStorage` — the filesystem seam `runCampaign` writes through
- * (run/cell dirs, the resumability cache, per-cell artifacts, trace spans).
- *
- * The default (`fsCampaignStorage`) is the Node filesystem — identical
- * behavior to the inline `node:fs` calls it replaces, so existing CLI
- * consumers are unaffected. `inMemoryCampaignStorage` keeps everything in a
- * `Map`, so the substrate runs in environments WITHOUT a filesystem
- * (Cloudflare Workers, Deno Deploy, other edge runtimes) — the campaign
- * still produces its `CampaignResult` (cells + aggregates) in memory;
- * artifacts/traces simply aren't persisted to disk.
- *
- * Paths are opaque keys to the in-memory adapter — it does not parse them,
- * so the same `join(...)`-built paths work unchanged across both adapters.
- */
-interface CampaignStorage {
-    /** Ensure a directory exists (recursive). No-op for in-memory. */
-    ensureDir(dir: string): void;
-    /** Does this path exist (as a written file or an ensured dir)? */
-    exists(path: string): boolean;
-    /** Read a UTF-8 file; `undefined` when missing or unreadable. */
-    read(path: string): string | undefined;
-    /** Write a file (string or bytes). Parent dir is assumed ensured. */
-    write(path: string, content: string | Uint8Array): void;
-    /** Append only when the current UTF-8 byte length matches `expectedBytes`.
-     * Returns the new length, or undefined when another writer won. */
-    append?(path: string, content: string, expectedBytes: number): number | undefined;
-}
-/** Node-filesystem storage — the default. Lazily requires `node:fs` so the
- *  module imports cleanly in non-Node runtimes (where the caller passes
- *  `inMemoryCampaignStorage` instead and never constructs this).
- *
- *  `createRequire(import.meta.url)` is the ESM-native lazy require — a bare
- *  `require` is a ReferenceError under `"type": "module"`, which is exactly
- *  the shape this package publishes. */
-declare function fsCampaignStorage(): CampaignStorage;
-/** In-memory storage for filesystem-less runtimes. Artifacts + trace spans
- *  live in a `Map` for the duration of the run; the `CampaignResult` is
- *  fully populated, but nothing is persisted to disk. */
-declare function inMemoryCampaignStorage(): CampaignStorage;
-/** Open the durable spend account stored beside a logical run. */
-declare function createRunCostLedger(input: {
-    storage: CampaignStorage;
-    runDir: string;
-    costCeilingUsd?: number;
-}): CostLedger;
-
 /**
  * `runCampaign` — Pass A substrate primitive. ONE function that orchestrates
  * scenarios → dispatch → artifacts → judges → aggregates, with full
@@ -5083,6 +5097,7 @@ interface RunLineageLoopOptions<TScenario extends Scenario, TArtifact> {
     governor?: Governor;
     budget: {
         maxSteps: number;
+        maxNodes?: number;
     };
     store?: LineageStore;
     /** Override the per-step proposer. Default {@link gepaProposer}. Inject a
@@ -7486,4 +7501,4 @@ declare function verifyCodeSurface(surface: CodeSurface, worktreeDir?: string):
  *  identity against the checkout at `worktreeRef`. */
 declare function resolveWorktreePath(surface: CodeSurface, worktreeDir?: string): string;
 
-export { type AcceptedEdit, type AceProposerOptions, type AnalystArtifact, type AnalystScenario, type AnalyzeCrossSurfaceInteractionsInput, type ApplySkillPatchResult, type AxisEvidence, type AxisVerdict, type BuildAnalystSurfaceDispatchOptions, type BuildEvidenceVectorOptions, type BuildLoopProvenanceArgs, type CampaignAggregates, type CampaignArtifactWriter, type CampaignBreakdown, type CampaignCellResult, type CampaignCostMeter, type CampaignResult, type CampaignRunPlan, type CampaignRunPlanCell, type CampaignScenarioIdentity, type CampaignStorage, type CampaignTokenUsage, type CampaignTraceWriter, type CodeSurface, type CodeSurfaceVerification, type CompareProposersOptions, type CompositeProposerOptions, type CostLedgerHandle, type CrossSurfaceAdditionDecision, type CrossSurfaceAdditionRejectionReason, type CrossSurfaceAttemptCompleteness, type CrossSurfaceBestSingleSelection, type CrossSurfaceBootstrapPolicy, type CrossSurfaceCandidate, type CrossSurfaceCandidateComparison, type CrossSurfaceCandidateEvidence, type CrossSurfaceCandidateOutcome, type CrossSurfaceCandidateSummary, type CrossSurfaceComponent, type CrossSurfaceComponentEvidence, type CrossSurfaceCompositionStep, type CrossSurfaceDistribution, type CrossSurfaceEligibility, type CrossSurfaceEvidenceBreakdown, type CrossSurfaceIneligibilityReason, type CrossSurfaceInteractionAwareSelection, type CrossSurfaceInteractionEffect, type CrossSurfaceInteractionPath, type CrossSurfaceInteractionReport, type CrossSurfaceInteractionTask, type CrossSurfaceNaiveStackSelection, type CrossSurfacePairCompatibility, type CrossSurfacePairEvidence, type CrossSurfacePairIncompatibilityReason, type CrossSurfacePairwiseEntry, type CrossSurfaceRankedSingle, type CrossSurfaceRelativeCost, type CrossSurfaceSelectionPolicy, type CrossSurfaceSelections, type CrossSurfaceTaskRow, DEFAULT_POLICY_EDIT_HISTORY_LIMITS, type DefaultProductionGateOptions, type DimensionRegression, type DiscriminationScore, type DispatchContext, type DispatchFn, type EmitLoopProvenanceArgs, type EmitLoopProvenanceResult, type EvalFixture, type EvalFixtureFile, type EvalFixtureLoadOptions, type EvalFixtureRunPlan, type EvalFixtureScenario, type EvalFixtureValidationMode, type EvidenceVector, type EvolutionaryProposerOptions, type FailureModeRecallJudgeOptions, type FapoAttributionSignals, type FapoEntryConfig, type FapoFailureCluster, type FapoOptimizationLevel, type FapoProposerOptions, type FapoReviewInput, type FapoReviewIssue, type FapoReviewResult, type FapoScopeContract, FileSearchLedger, FsLabeledScenarioStore, type FsLabeledScenarioStoreOptions, type Gate, type GateContext, type GateDecision, type GateResult, type GenerationCandidate, type GenerationRecord, type GepaProposerConstraints, type GepaProposerOptions, type GitWorktreeAdapterOptions, type Governor, type GovernorContext, type GovernorOp, type HaloProposerOptions, type HeldOutGateOptions, type HeldoutSignificance, type HeldoutSignificanceOptions, type HeuristicGovernorOptions, type JsonPolicyEditTargetSurface, type JsonPrimitive, type JsonValue, type JudgeAggregate, type JudgeConfig, type JudgeDimension, type JudgeScore, type LabelTrust, type LabeledScenarioRecord, type LabeledScenarioSampleArgs, type LabeledScenarioSource, type LabeledScenarioStore, LabeledScenarioStoreError, type LabeledScenarioWrite, Lineage, type LineageEdge, type LineageGraph, type LineageNode, type LineageNodeInput, type LineageStore, type LlmJudgeDimension, type LlmJudgeOptions, type LlmPolicyEditProposerOptions, type LoadEvalFixtureScenariosOptions, type LoopProvenanceArgsFromResult, type LoopProvenanceBackend, type LoopProvenanceCandidate, type LoopProvenanceEvidence, type LoopProvenanceRecord, type MemoryCurationProposerOptions, type MutableSurface, type Mutator, type NeutralizationGateOptions, type ObjectiveSource, type OpenAutoPrOptions, type OpenAutoPrResult, type OpenSearchLedgerOptions, type OptimizationProposer, type OptimizerConfig, type OptimizerEntryConfig, POLICY_EDIT_CANDIDATE_RECORD_SCHEMA, type PairedHoldout, type ParameterCandidate, type ParameterChange, type ParameterSweepProposerOptions, type ParetoParent, type ParetoSignificanceGateOptions, type PlanCampaignRunOptions, type PlanEvalFixtureRunOptions, type PlaybackContext, type PlaybackDriver, type PlaybackStep, type PolicyEditAuthorScenarioRow, type PolicyEditCandidateRecord, type PolicyEditCandidateSummary, type PolicyEditFindingInput, type PolicyEditFindingSource, type PolicyEditHistoryCandidateContext, type PolicyEditHistoryGenerationContext, type PolicyEditHistoryProjectionOptions, type PolicyEditObjective, type PolicyEditOutcomeContext, type PolicyEditProposerOptions, type PowerPreflight, type PowerPreflightOptions, type PremeasuredOptimizationBaseline, type ProfileDispatchFn, ProfileMatrixError, type ProfileSummary, type PromotionObjective, type PromotionPolicy, type ProposeContext, type ProposePatchesArgs, type ProposedCandidate, type ProposerComparison, type ProposerEntry, type ProposerPairwise, type ProposerScore, type RedactionStatus, type ReferenceEquivalenceJudgeOptions, type ReferenceEquivalenceScenario, type RejectedEdit, type RolloutArgumentDiff, type RolloutArgumentDiffOptions, type RolloutCall, type RunCampaignOptions, type RunEvalOptions, type RunImprovementLoopOptions, type RunImprovementLoopResult, type RunLineageLoopOptions, type RunLineageLoopResult, type RunLineageLoopSeed, type RunLineageOptions, type RunLineageResult, type RunLineageSeed, type RunLineageStepResult, type RunOptimizationOptions, type RunOptimizationResult, type RunProfileMatrixOptions, type RunProfileMatrixResult, type RunSkillOptOptions, type RunSkillOptResult, SEARCH_LEDGER_SCHEMA, type Scenario, type ScenarioAggregate, type ScenarioRollup, type ScenarioSignal, type ScoreboardRenderOptions, type ScoreboardRow, type ScoreboardSummary, type ScoredRollout, type ScoredSurfaceOutcome, type SearchAccountingAudit, type SearchArtifactRef, type SearchAttemptAccounting, type SearchCandidateDecidedEvent, type SearchCandidateLineage, type SearchCandidateRegisteredEvent, type SearchCandidateSlot, type SearchCandidateSlotClosedEvent, type SearchCandidateSurface, type SearchCompletedEvent, type SearchCostAccounting, type SearchFailureReason, type SearchLedger, type SearchLedgerAppendResult, SearchLedgerConflictError, type SearchLedgerEntry, SearchLedgerError, type SearchLedgerEvent, type SearchLedgerHash, SearchLedgerIntegrityError, type SearchLedgerReplay, type SearchModelIdentity, type SearchOperationKind, type SearchOperationRecordedEvent, type SearchPlan, type SearchPlannedEvent, type SearchPlannedOperation, type SearchPlannedTask, type SearchSourceRef, type SearchSurfaceEffect, type SearchSurfaceEvidence, type SearchSurfaceKind, type SearchTaskAttemptedEvent, type SearchTaskOutcome, type SearchTokenAccounting, type SelectPolicyEditAuthorRowsOptions, type SequentialDecideFn, type SequentialDecideOptions, type SequentialDecision, type SequentialObservation, type SequentialPairedGate, type SequentialPairedGateOptions, type SerializedJsonBudget, type SessionScript, type SingleRunLock, type SingleRunLockOptions, type SkillOptEpochRecord, type SkillOptEvidence, type SkillOptProposer, type SkillOptProposerOptions, type SkillPatch, type SkillPatchOp, SkillPatchParseError, type SkillPatchRejection, type SurfaceProposer, type SurfaceScore, type TraceAnalystProposerOptions, type TraceSpan, type TransientFailureOptions, type UngroundedLiteralReport, type UserStory, type UserStoryVerdict, type Worktree, type WorktreeAdapter, WorktreeAdapterError, aceProposer, acquireSingleRunLock, analyzeCrossSurfaceInteractions, applySkillPatch, assertCampaignDesign, assertCampaignSplitIdentity, assertCodeSurfaceIdentity, assertPolicyEditAuthorContextBudget, buildAnalystSurfaceDispatch, buildEvidenceVector, buildLoopProvenanceRecord, callbackGovernor, campaignBreakdown, campaignMeanComposite, campaignMeasurementDigest, campaignScenarioIdentity, campaignSplitDigest, campaignSplitDigestFromIdentities, canonicalDigest, classifyUngroundedLiterals, codeSurfaceIdentityMaterial, compareProposers, composeGate, compositeProposer, countSentenceEdits, createReferenceEquivalenceJudge, createRunCostLedger, defaultProductionGate, detectScale, dimensionRegressions, discoverEvalFixtures, emitLoopProvenance, evolutionaryProposer, extractFapoAttributionSignals, extractH2Sections, failureModeRecallJudge, fapoEscalationEntry, fapoProposer, fsCampaignStorage, fsLineageStore, gepaParetoEntry, gepaProposer, gepaReflectionEntry, gitWorktreeAdapter, haloProposer, heldOutGate, heldoutSignificance, heuristicGovernor, inMemoryCampaignStorage, isProposedCandidate, isTransientTransportFailure, labelTrustRank, lineageNodeId, llmJudge, llmPolicyEditProposer, loadEvalFixture, loadEvalFixtureScenarios, loopProvenanceArgsFromResult, loopProvenanceSpans, makePlaybackDispatch, memLineageStore, memoryCurationProposer, neutralizationGate, neutralizeText, openAutoPr, openSearchLedger, pairHoldout, parameterSweepProposer, paretoPolicy, paretoSignificanceGate, parseSkillPatchResponse, patchEditCount, planCampaignRun, planEvalFixtureRun, policyEditProposer, powerPreflight, projectPolicyEditHistory, provenanceRecordPath, provenanceSpansPath, renderScoreboardMarkdown, renderSurfaceDiff, resolveRunDir, resolveWorktreePath, rolloutArgumentDiff, runCampaign, runEval, runImprovementLoop, runLineage, runLineageLoop, runOptimization, runProfileMatrix, runSkillOpt, scoreDiscrimination, scoreUserStory, scoreboardSummary, selectDiscriminative, selectPolicyEditAuthorRows, sequentialDecide, sequentialPairedGate, skillOptEntry, skillOptProposer, surfaceContentHash, surfaceHash, tangleTracesRoot, traceAnalystProposer, userStoryScoreboard, validatePolicyEditCandidateRecord, validateSearchLedgerEvent, verifyCodeSurface, verifyLoopProvenanceRecord };
+export { type AcceptedEdit, type AceProposerOptions, type AnalystArtifact, type AnalystScenario, type AnalyzeCrossSurfaceInteractionsInput, type ApplySkillPatchResult, type AxisEvidence, type AxisVerdict, type BuildAnalystSurfaceDispatchOptions, type BuildEvidenceVectorOptions, type BuildLoopProvenanceArgs, type CampaignAggregates, type CampaignArtifactWriter, type CampaignBreakdown, type CampaignCellResult, type CampaignCostMeter, type CampaignResult, type CampaignRunPlan, type CampaignRunPlanCell, type CampaignScenarioIdentity, type CampaignStorage, type CampaignTokenUsage, type CampaignTraceWriter, type CodeSurface, type CodeSurfaceVerification, type CompareProposersOptions, type CompositeProposerOptions, type CostLedgerHandle, type CrossSurfaceAdditionDecision, type CrossSurfaceAdditionRejectionReason, type CrossSurfaceAttemptCompleteness, type CrossSurfaceBestSingleSelection, type CrossSurfaceBootstrapPolicy, type CrossSurfaceCandidate, type CrossSurfaceCandidateComparison, type CrossSurfaceCandidateEvidence, type CrossSurfaceCandidateOutcome, type CrossSurfaceCandidateSummary, type CrossSurfaceComponent, type CrossSurfaceComponentEvidence, type CrossSurfaceCompositionStep, type CrossSurfaceDistribution, type CrossSurfaceEligibility, type CrossSurfaceEvidenceBreakdown, type CrossSurfaceIneligibilityReason, type CrossSurfaceInteractionAwareSelection, type CrossSurfaceInteractionEffect, type CrossSurfaceInteractionPath, type CrossSurfaceInteractionReport, type CrossSurfaceInteractionTask, type CrossSurfaceNaiveStackSelection, type CrossSurfacePairCompatibility, type CrossSurfacePairEvidence, type CrossSurfacePairIncompatibilityReason, type CrossSurfacePairwiseEntry, type CrossSurfaceRankedSingle, type CrossSurfaceRelativeCost, type CrossSurfaceSelectionPolicy, type CrossSurfaceSelections, type CrossSurfaceTaskRow, DEFAULT_POLICY_EDIT_HISTORY_LIMITS, type DefaultProductionGateOptions, type DimensionRegression, type DiscriminationScore, type DispatchContext, type DispatchFn, type EmitLoopProvenanceArgs, type EmitLoopProvenanceResult, type EvalFixture, type EvalFixtureFile, type EvalFixtureLoadOptions, type EvalFixtureRunPlan, type EvalFixtureScenario, type EvalFixtureValidationMode, type EvidenceVector, type EvolutionaryProposerOptions, type FailureModeRecallJudgeOptions, type FapoAttributionSignals, type FapoEntryConfig, type FapoFailureCluster, type FapoOptimizationLevel, type FapoProposerOptions, type FapoReviewInput, type FapoReviewIssue, type FapoReviewResult, type FapoScopeContract, FileSearchLedger, FsLabeledScenarioStore, type FsLabeledScenarioStoreOptions, type Gate, type GateContext, type GateDecision, type GateResult, type GenerationCandidate, type GenerationRecord, type GepaProposerConstraints, type GepaProposerOptions, type GitWorktreeAdapterOptions, type Governor, type GovernorContext, type GovernorOp, type HaloProposerOptions, type HeldOutGateOptions, type HeldoutSignificance, type HeldoutSignificanceOptions, type HeuristicGovernorOptions, type JsonPolicyEditTargetSurface, type JsonPrimitive, type JsonValue, type JudgeAggregate, type JudgeConfig, type JudgeDimension, type JudgeScore, type LabelTrust, type LabeledScenarioRecord, type LabeledScenarioSampleArgs, type LabeledScenarioSource, type LabeledScenarioStore, LabeledScenarioStoreError, type LabeledScenarioWrite, Lineage, type LineageEdge, type LineageGraph, type LineageNode, type LineageNodeInput, type LineageStore, LineageStoreConflictError, type LlmJudgeDimension, type LlmJudgeOptions, type LlmPolicyEditProposerOptions, type LoadEvalFixtureScenariosOptions, type LoopProvenanceArgsFromResult, type LoopProvenanceBackend, type LoopProvenanceCandidate, type LoopProvenanceEvidence, type LoopProvenanceRecord, type MemoryCurationProposerOptions, type MutableSurface, type Mutator, type NeutralizationGateOptions, type ObjectiveSource, type OpenAutoPrOptions, type OpenAutoPrResult, type OpenSearchLedgerOptions, type OptimizationProposer, type OptimizerConfig, type OptimizerEntryConfig, POLICY_EDIT_CANDIDATE_RECORD_SCHEMA, type PairedHoldout, type ParameterCandidate, type ParameterChange, type ParameterSweepProposerOptions, type ParetoParent, type ParetoSignificanceGateOptions, type PlanCampaignRunOptions, type PlanEvalFixtureRunOptions, type PlaybackContext, type PlaybackDriver, type PlaybackStep, type PolicyEditAuthorScenarioRow, type PolicyEditCandidateRecord, type PolicyEditCandidateSummary, type PolicyEditFindingInput, type PolicyEditFindingSource, type PolicyEditHistoryCandidateContext, type PolicyEditHistoryGenerationContext, type PolicyEditHistoryProjectionOptions, type PolicyEditObjective, type PolicyEditOutcomeContext, type PolicyEditProposerOptions, type PowerPreflight, type PowerPreflightOptions, type PremeasuredOptimizationBaseline, type ProfileDispatchFn, ProfileMatrixError, type ProfileSummary, type PromotionObjective, type PromotionPolicy, type ProposeContext, type ProposePatchesArgs, type ProposedCandidate, type ProposerComparison, type ProposerEntry, type ProposerPairwise, type ProposerScore, type RedactionStatus, type ReferenceEquivalenceJudgeOptions, type ReferenceEquivalenceScenario, type RejectedEdit, type RolloutArgumentDiff, type RolloutArgumentDiffOptions, type RolloutCall, type RunCampaignOptions, type RunEvalOptions, type RunImprovementLoopOptions, type RunImprovementLoopResult, type RunLineageLoopOptions, type RunLineageLoopResult, type RunLineageLoopSeed, type RunLineageOptions, type RunLineageResult, type RunLineageSeed, type RunLineageStepResult, type RunOptimizationOptions, type RunOptimizationResult, type RunProfileMatrixOptions, type RunProfileMatrixResult, type RunSkillOptOptions, type RunSkillOptResult, SEARCH_LEDGER_SCHEMA, type Scenario, type ScenarioAggregate, type ScenarioRollup, type ScenarioSignal, type ScoreboardRenderOptions, type ScoreboardRow, type ScoreboardSummary, type ScoredRollout, type ScoredSurfaceOutcome, type SearchAccountingAudit, type SearchArtifactRef, type SearchAttemptAccounting, type SearchCandidateDecidedEvent, type SearchCandidateLineage, type SearchCandidateRegisteredEvent, type SearchCandidateSlot, type SearchCandidateSlotClosedEvent, type SearchCandidateSurface, type SearchCompletedEvent, type SearchCostAccounting, type SearchFailureReason, type SearchLedger, type SearchLedgerAppendResult, SearchLedgerConflictError, type SearchLedgerEntry, SearchLedgerError, type SearchLedgerEvent, type SearchLedgerHash, SearchLedgerIntegrityError, type SearchLedgerReplay, type SearchModelIdentity, type SearchOperationKind, type SearchOperationRecordedEvent, type SearchPlan, type SearchPlannedEvent, type SearchPlannedOperation, type SearchPlannedTask, type SearchSourceRef, type SearchSurfaceEffect, type SearchSurfaceEvidence, type SearchSurfaceKind, type SearchTaskAttemptedEvent, type SearchTaskOutcome, type SearchTokenAccounting, type SelectPolicyEditAuthorRowsOptions, type SequentialDecideFn, type SequentialDecideOptions, type SequentialDecision, type SequentialObservation, type SequentialPairedGate, type SequentialPairedGateOptions, type SerializedJsonBudget, type SessionScript, type SingleRunLock, type SingleRunLockOptions, type SkillOptEpochRecord, type SkillOptEvidence, type SkillOptProposer, type SkillOptProposerOptions, type SkillPatch, type SkillPatchOp, SkillPatchParseError, type SkillPatchRejection, type SurfaceProposer, type SurfaceScore, type TraceAnalystProposerOptions, type TraceSpan, type TransientFailureOptions, type UngroundedLiteralReport, type UserStory, type UserStoryVerdict, type Worktree, type WorktreeAdapter, WorktreeAdapterError, aceProposer, acquireSingleRunLock, analyzeCrossSurfaceInteractions, applySkillPatch, assertCampaignDesign, assertCampaignSplitIdentity, assertCodeSurfaceIdentity, assertPolicyEditAuthorContextBudget, buildAnalystSurfaceDispatch, buildEvidenceVector, buildLoopProvenanceRecord, callbackGovernor, campaignBreakdown, campaignLineageStore, campaignMeanComposite, campaignMeasurementDigest, campaignScenarioIdentity, campaignSplitDigest, campaignSplitDigestFromIdentities, canonicalDigest, classifyUngroundedLiterals, codeSurfaceIdentityMaterial, compareProposers, composeGate, compositeProposer, countSentenceEdits, createReferenceEquivalenceJudge, createRunCostLedger, defaultProductionGate, detectScale, dimensionRegressions, discoverEvalFixtures, emitLoopProvenance, evolutionaryProposer, extractFapoAttributionSignals, extractH2Sections, failureModeRecallJudge, fapoEscalationEntry, fapoProposer, fsCampaignStorage, fsLineageStore, gepaParetoEntry, gepaProposer, gepaReflectionEntry, gitWorktreeAdapter, haloProposer, heldOutGate, heldoutSignificance, heuristicGovernor, inMemoryCampaignStorage, isProposedCandidate, isTransientTransportFailure, labelTrustRank, lineageNodeId, llmJudge, llmPolicyEditProposer, loadEvalFixture, loadEvalFixtureScenarios, loopProvenanceArgsFromResult, loopProvenanceSpans, makePlaybackDispatch, memLineageStore, memoryCurationProposer, neutralizationGate, neutralizeText, openAutoPr, openSearchLedger, pairHoldout, parameterSweepProposer, paretoPolicy, paretoSignificanceGate, parseSkillPatchResponse, patchEditCount, planCampaignRun, planEvalFixtureRun, policyEditProposer, powerPreflight, projectPolicyEditHistory, provenanceRecordPath, provenanceSpansPath, renderScoreboardMarkdown, renderSurfaceDiff, resolveRunDir, resolveWorktreePath, rolloutArgumentDiff, runCampaign, runEval, runImprovementLoop, runLineage, runLineageLoop, runOptimization, runProfileMatrix, runSkillOpt, scoreDiscrimination, scoreUserStory, scoreboardSummary, selectDiscriminative, selectPolicyEditAuthorRows, sequentialDecide, sequentialPairedGate, skillOptEntry, skillOptProposer, surfaceContentHash, surfaceHash, tangleTracesRoot, traceAnalystProposer, userStoryScoreboard, validatePolicyEditCandidateRecord, validateSearchLedgerEvent, verifyCodeSurface, verifyLoopProvenanceRecord };