@axlsdk/axl 0.23.3 → 0.24.1

package/dist/index.d.cts

@@ -120,6 +120,237 @@ declare function inputText(input: ModelInput): string;
 /** Safe representation for context summarizers; never includes locators or data. */
 declare function summarizeModelInput(input: ModelInput): string;
 
+/**
+ * Core accounting — one authoritative record of what a workload spent.
+ *
+ * This module owns the *measurement* rail. It is deliberately independent of
+ * the trace/event rail (`event-utils.ts`): trace retention, trace level,
+ * redaction and capture change diagnostics, never the numbers here. Both rails
+ * are fed by the same settlement producer (the scoped provider facade and the
+ * instrumented tool / memory / transcription boundaries), so turning tracing
+ * off cannot change `Accounting`.
+ *
+ * The three concepts:
+ *
+ * - **Operation** — one logical paid unit of work (a chat call, a stream, an
+ *   embedding, a transcription, a tool invocation attempt, a declared external
+ *   call). It has a stable id and a lifecycle: `admitted` → `dispatched` →
+ *   `settled` | `denied` | `abandoned`. Transport retries are subordinate to
+ *   the operation; they never mint a second one.
+ * - **Scope** — an `AsyncLocalStorage` frame opened by
+ *   `AxlRuntime.trackOutcome()`. Scopes nest; an operation settled in a child
+ *   is recorded exactly once in every open ancestor (deduped by operation id),
+ *   so a parent total is the sum of disjoint operations and never a double
+ *   charge.
+ * - **Admission** — a synchronous known-spend threshold ({@link
+ *   AdmissionController}) attached to a scope. It is a threshold, not a
+ *   reservation system: work already dispatched settles and is counted.
+ *
+ * Zero is never confused with unknown. A known $0 settles `complete`; anything
+ * dispatched whose charge we could not establish settles `unknown` with a
+ * {@link AccountingReason}, which makes the scope `incomplete` and makes
+ * `knownCost` an explicit lower bound.
+ */
+/**
+ * How much of the declared/instrumented scope the numbers actually cover.
+ *
+ * This is coverage of Axl-observable operations, NOT invoice reconciliation.
+ *
+ * - `'complete'` — every operation in the scope reached a terminal state with a
+ *   usable charge (including known $0).
+ * - `'incomplete'` — at least one operation lacked a usable charge, or the
+ *   scope detected work from an incompatible loaded copy; `knownCost` is a
+ *   lower bound and `reasons` says why.
+ * - `'unverified'` — reserved for READERS of artifacts that carry no
+ *   accounting at all (legacy eval results). A live scope never produces it.
+ */
+type AccountingCompleteness = 'complete' | 'incomplete' | 'unverified';
+/** Where a settled USD figure came from. Keys of `Accounting.provenance`. */
+type CostProvenance = 
+/** The vendor supplied the USD figure itself (e.g. OpenRouter `usage.cost`). */
+'provider_reported'
+/** An Axl/adapter price table was applied to reported usage. */
+ | 'price_table_estimate'
+/** An adapter supplied a cost without declaring its basis. */
+ | 'adapter_reported'
+/** `withExternalOperation` / tool / legacy caller value. */
+ | 'caller_reported';
+/** Why an operation could not contribute a usable charge. */
+type AccountingReason = 
+/** Usage was reported but no usable cost was (undefined / NaN / negative / ∞). */
+'unpriced_model'
+/** Dispatched, but the terminal outcome carried no usage (failure/abort/stall). */
+ | 'usage_missing'
+/** Dispatched and never settled before its scope finalized. */
+ | 'abandoned'
+/** An external operation finished without calling `report.setCost()`. */
+ | 'external_unreported'
+/**
+ * A consumer ran work with no accounting scope available, or another loaded
+ * copy attempted work under a scope whose accounting protocol it cannot join.
+ */
+ | 'uninstrumented';
+/** The instrumented boundaries that can open an operation. */
+type OperationKind = 'chat' | 'stream' | 'embedding' | 'transcription' | 'tool' | 'external';
+/** Whether a scope's operations are generating an answer or judging one. */
+type OperationPurpose = 'generation' | 'judging';
+/**
+ * Usage folded across a scope's settled operations.
+ *
+ * `reasoningTokens` / `cachedTokens` / `cacheWriteTokens` are counted ONCE in
+ * their own bucket. `inputTokens` is the provider's already-folded
+ * `prompt_tokens` — cached tokens are not re-added to it.
+ */
+type AccountingUsage = {
+    inputTokens: number;
+    outputTokens: number;
+    reasoningTokens: number;
+    cachedTokens: number;
+    cacheWriteTokens: number;
+    audioSeconds: number;
+};
+/** The authoritative accounting record for one tracked scope. */
+type Accounting = {
+    version: 1;
+    currency: 'USD';
+    /** Sum of settled, usable, disjoint charges. Never includes caller aggregates. */
+    knownCost: number;
+    completeness: AccountingCompleteness;
+    /** Reason → count of unresolved operations or coverage failures. */
+    reasons: Partial<Record<AccountingReason, number>>;
+    usage: AccountingUsage;
+    operations: {
+        /**
+         * Operations admitted and opened in this scope (or a descendant). An
+         * operation later refused at the dispatch check is retracted from this
+         * count and appears under `denied` instead, so
+         * `total === settled + unknown` always holds.
+         */
+        total: number;
+        /** Terminal with a usable cost, including a known $0. */
+        settled: number;
+        /** Terminal or abandoned without a usable cost. Coverage failures can also make `incomplete`. */
+        unknown: number;
+        /** Refused admission — never dispatched, contributes nothing anywhere. */
+        denied: number;
+        /** `total` split by kind. Denied operations are not included. */
+        byKind: Partial<Record<OperationKind, number>>;
+    };
+    /** `knownCost` split. `external` is kind `'external'`; the rest by scope purpose. */
+    breakdown: {
+        generation: number;
+        judging: number;
+        external: number;
+    };
+    /** `knownCost` split by provenance. Keys sum to `knownCost`. */
+    provenance: Partial<Record<CostProvenance, number>>;
+};
+/**
+ * The dispatch-level admission hook.
+ *
+ * `fetchWithRetry` calls `beforeDispatch` after acquiring a rate-governor
+ * permit and immediately before EVERY `fetch` attempt, outside the
+ * network-error catch. Throwing an {@link AdmissionDeniedError} from it stops
+ * the request before it leaves the process; the permit is still released.
+ *
+ * A third-party adapter that ignores this hook still gets the
+ * operation-open check, but a request already queued behind a governor or
+ * sleeping in its own backoff cannot be stopped. See `docs/providers.md`.
+ */
+type DispatchAdmission = {
+    /** @param attempt 1-indexed transport attempt. Throws to refuse the dispatch. */
+    beforeDispatch(attempt: number): void;
+};
+/** Reports a declared external charge for one `withExternalOperation` call. */
+type ExternalOperationReport = {
+    /**
+     * Record a finite, non-negative, DISJOINT USD charge for this operation.
+     * Explicit `0` means known-free. Nested Axl calls account for themselves and
+     * must be excluded.
+     *
+     * @throws AxlError `INVALID_COST_REPORT` on a non-finite/negative amount or a
+     *   second call.
+     */
+    setCost(amountUsd: number, usage?: Partial<AccountingUsage>): void;
+};
+/** Descriptor for `withExternalOperation` / {@link externalOperation}. */
+type ExternalOperationDescriptor = {
+    name: string;
+};
+/**
+ * @internal The settlement channel into a controller.
+ *
+ * `Symbol.for`, NOT `Symbol()`: this package legitimately loads twice in one
+ * process — an ESM consumer whose `runtime.eval()` dynamically imports
+ * `@axlsdk/eval`, which resolves its own copy of `@axlsdk/axl`, is the ordinary
+ * case, not a pathology. A module-private symbol would make the controller
+ * built by copy A invisible to the settlement walk in copy B, and spend would
+ * silently stop reaching the budget. The registry symbol is shared across
+ * realms, so both copies agree.
+ */
+declare const RECORD_SPEND: unique symbol;
+/**
+ * A synchronous known-spend threshold for one invocation.
+ *
+ * Attach it to a scope via `runtime.trackOutcome(fn, { admission })`. Every
+ * instrumented operation checks it when it opens, and every built-in transport
+ * checks it again immediately before each dispatch.
+ *
+ * It is a **threshold, not a reservation**: a call admitted before a sibling
+ * settles may push known spend past `limit`. `knownOvershoot` reports how far.
+ * Never share one controller across unrelated invocations.
+ */
+declare class AdmissionController {
+    /** The configured USD threshold. Admission closes at `knownSpend >= limit`. */
+    readonly limit: number;
+    private spend;
+    constructor(options: {
+        limit: number;
+    });
+    /** USD settled so far under this controller. Unknown spend is NOT included. */
+    get knownSpend(): number;
+    /** `true` once `knownSpend >= limit`. A `limit` of 0 is closed from the start. */
+    get closed(): boolean;
+    get status(): 'open' | 'closed';
+    /** `max(0, knownSpend - limit)`, unconditionally — necessarily 0 while open. */
+    get knownOvershoot(): number;
+    /** Synchronous admission decision. No await between the check and the answer. */
+    admit(): {
+        admitted: true;
+    } | {
+        admitted: false;
+        limit: number;
+        knownSpend: number;
+    };
+    snapshot(): {
+        limit: number;
+        status: 'open' | 'closed';
+        knownSpend: number;
+        knownOvershoot: number;
+    };
+    /** @internal Applied synchronously at settlement, in the tick it is observed. */
+    [RECORD_SPEND](amountUsd: number): void;
+}
+/**
+ * Declare a paid unit of work Axl cannot observe — a third-party API call
+ * inside a tool, a custom scorer's own model call — so it joins the scope's
+ * accounting as an `'external'` operation.
+ *
+ * Admission is checked BEFORE `fn` runs. The operation finalizes on return,
+ * throw or abort; a cost reported before a later throw is kept. Not calling
+ * `report.setCost()` makes the scope `incomplete` with reason
+ * `'external_unreported'` — never free.
+ *
+ * The reported amount must be DISJOINT: nested `ctx.ask` / provider calls
+ * account for themselves and must be excluded, or the scope double-charges.
+ *
+ * Outside any accounting scope `fn` still runs, with a report that validates
+ * its argument but records nothing.
+ *
+ * @throws AdmissionDeniedError when the enclosing budget has closed.
+ */
+declare function externalOperation<T>(descriptor: ExternalOperationDescriptor, fn: (report: ExternalOperationReport) => Promise<T>): Promise<T>;
+
 type InputModalitySupport = {
     image?: {
         sources: readonly InputMediaSource['type'][];
@@ -198,6 +429,14 @@ type ChatOptions = {
     responseFormat?: ResponseFormat;
     stop?: string[];
     signal?: AbortSignal;
+    /**
+     * @internal Runtime admission hook. Set by the scoped provider facade when an
+     * accounting scope with a budget is active. Built-in adapters forward it to
+     * `fetchWithRetry`, which calls it immediately before EVERY fetch attempt so a
+     * request queued behind the rate governor or sleeping in retry backoff is not
+     * dispatched after the budget closes. It is never sent to the vendor.
+     */
+    dispatchAdmission?: DispatchAdmission;
     /** @internal Runtime observer for the actual adapter transport lifecycle. */
     requestLifecycle?: {
         /** The request was actually dispatched, after limiter queue and retry backoff. */
@@ -281,6 +520,8 @@ type StreamChunk = {
     };
     /** Estimated cost in USD for this call, computed the same way as ProviderResponse.cost. */
     cost?: number;
+    /** How `cost` was derived. Field parity with `ProviderResponse.costProvenance`. */
+    costProvenance?: 'provider_reported' | 'price_table_estimate';
     /** Provider-specific opaque metadata (e.g. raw Gemini parts with thought signatures). */
     providerMetadata?: Record<string, unknown>;
     /**
@@ -1708,17 +1949,31 @@ type ToolCallMessage = {
  */
 type CallTiming = {
     /**
-     * Time parked in Axl's own opt-in `RateLimiter` (concurrency cap plus
-     * `minIntervalMs` spacing) before the request was allowed out. `0` when the
-     * provider has no `rateLimit` configured. This is self-imposed wait, not
-     * provider latency.
+     * Every wait Axl imposed on itself: the first permit (concurrency cap),
+     * `minIntervalMs` spacing, adaptive pacing after a rate-limit 429, a
+     * rate-limit pause on the scope, and the re-acquire after a rate-limit 429.
+     * `0` when nothing waited. This is
+     * self-imposed wait, not provider latency.
      */
     queuedMs: number;
-    /** `fetch` attempts made for this call, including the final one (≥ 1). */
+    /**
+     * Requests actually sent for this call, including the final one (≥ 1). A call
+     * held back by a rate-limit pause before sending is not an attempt.
+     */
     attempts: number;
     /**
-     * First attempt's dispatch → final attempt's dispatch, i.e. everything spent
-     * on failed attempts and their backoff sleeps. `0` for a single attempt.
+     * Rate-limit 429s this call received and retried: how often the provider
+     * throttled it. A 429 that is returned instead (a spend cap, or the last one
+     * once the retry budget is spent) is not counted, nor are 503/529/network
+     * retries. Built-in adapters always set it (`0` when none); optional so a
+     * custom `Provider` may omit it.
+     */
+    rateLimitRetries?: number;
+    /**
+     * First attempt's dispatch → final attempt's dispatch, minus the
+     * self-imposed waits inside that span (which are in `queuedMs`): failed
+     * attempts and their 503/529/network backoff sleeps. Disjoint from
+     * `queuedMs`. `0` for a single attempt.
      */
     retryMs: number;
     /** Final dispatch → response headers. Time to first byte. */
@@ -1763,6 +2018,14 @@ type ProviderResponse = {
         audio_output_tokens?: number;
     };
     cost?: number;
+    /**
+     * How `cost` was derived, when the adapter can say. `'provider_reported'`
+     * means the vendor supplied the USD figure itself; `'price_table_estimate'`
+     * means the adapter priced reported usage from a table. Built-in adapters set
+     * it whenever they return a `cost`; a cost with no provenance is recorded as
+     * `'adapter_reported'`.
+     */
+    costProvenance?: 'provider_reported' | 'price_table_estimate';
     /** Provider-specific opaque metadata that needs to round-trip through conversation history. */
     providerMetadata?: Record<string, unknown>;
     /** Per-call latency breakdown. Absent on providers that don't instrument it. */
@@ -1922,6 +2185,54 @@ declare class BudgetExceededError extends AxlError {
     readonly policy: string;
     constructor(limit: number, spent: number, policy: string);
 }
+/**
+ * Thrown when an `AdmissionController` refuses to admit a paid operation
+ * because known spend has reached its limit.
+ *
+ * This is a *stop*, not a failure of the provider: it is never wrapped in a
+ * `ProviderError`, never auto-retried by the transport, and never treated as
+ * an abort. It is raised either when the operation opens or at the transport's
+ * pre-dispatch check — in both cases before the request leaves the process, so
+ * it never accompanies a charge.
+ *
+ * Distinct from `BudgetExceededError`, which is `ctx.budget()`'s own
+ * workflow-scoped policy and keeps its existing semantics.
+ */
+declare class AdmissionDeniedError extends AxlError {
+    /** The controller's configured USD threshold. */
+    readonly limit: number;
+    /** Known settled spend at the moment of refusal. Unknown spend is excluded. */
+    readonly knownSpend: number;
+    /** What was refused. */
+    readonly operation: {
+        kind: string;
+        model?: string;
+    };
+    constructor(options: {
+        limit: number;
+        knownSpend: number;
+        operation: {
+            kind: string;
+            model?: string;
+        };
+    });
+}
+/**
+ * Is this an admission denial, regardless of which copy of `@axlsdk/axl` threw it?
+ *
+ * `instanceof AdmissionDeniedError` is the natural check and it is the WRONG one
+ * across a module boundary: `runtime.eval()` dynamically imports `@axlsdk/eval`,
+ * which resolves its own `@axlsdk/axl`, and a dual ESM/CJS consumer can hold two
+ * copies at once. The classes are then structurally identical and referentially
+ * distinct, so `instanceof` returns false and a budget stop gets misreported as
+ * an ordinary workflow failure — the item reads `failed` instead of
+ * `budget_interrupted`, which is a lie about why the run stopped.
+ *
+ * Duck-typing on the stable public identity (`code` + `name`) is realm-proof.
+ * Prefer this over `instanceof` in any consumer that can be loaded separately
+ * from the runtime that threw.
+ */
+declare function isAdmissionDeniedError(error: unknown): error is AdmissionDeniedError;
 /** Thrown when an agent exceeds its maximum number of tool-calling turns */
 declare class MaxTurnsError extends AxlError {
     readonly maxTurns: number;
@@ -2393,7 +2704,253 @@ declare class AxlEventBus implements AsyncIterable<AxlEvent> {
 }
 
 /**
- * Opt-in client-side rate governor for provider HTTP calls.
+ * Diagnostic artifact storage — the durable side of opt-in request capture.
+ *
+ * Captured request records are far too large to live inside an eval result, so
+ * they live beside it as an **artifact**: an opaque id owned by an eval history
+ * entry, holding a JSONL stream of records plus a small manifest describing
+ * what the capture actually managed to record.
+ *
+ * The lifecycle is deliberately two-phase, because the artifact and the history
+ * row are written to different stores and either write can fail:
+ *
+ * ```
+ *   stage(owner)  →  append(...)*  →  finalize(status)  →  [save history]  →  commit(expiresAt)
+ *                                                       ↘ (save threw)  →  rollback()
+ * ```
+ *
+ * A `staged` artifact is never served and is reclaimed once its lease expires,
+ * so a process that dies mid-run leaves recoverable bytes rather than a
+ * permanent orphan. Only a `committed` artifact whose owner still exists and
+ * whose logical expiry has not passed is readable.
+ *
+ * Deletion is also two-phase: `markDeletePending` records the intent, then
+ * `delete` removes the bytes. A failure between the two leaves the intent
+ * behind, so a later `reconcile` finishes the job without the caller having to
+ * re-supply anything.
+ *
+ * The interface is the extension point: a host running Redis history (whose
+ * server-side TTL cannot notify a local filesystem) supplies its own
+ * implementation. {@link FileDiagnosticArtifactStore} is the only built-in
+ * backend, and Axl never silently falls back to a process temp folder.
+ */
+/** Who an artifact belongs to. Today only an eval history entry can own one. */
+type ArtifactOwner = {
+    kind: 'eval';
+    /** The eval history entry id (`EvalHistoryEntry.id`). */
+    id: string;
+};
+/** How completely a capture managed to record what it was asked to record. */
+type ArtifactStatus = 
+/** Every record the run produced was written. */
+'complete'
+/** A byte/queue bound stopped capture partway; `reason` says which. */
+ | 'truncated'
+/** The writer never finalized (process death). Bytes are readable but partial. */
+ | 'interrupted'
+/** The sink failed; there may be no usable bytes at all. `reason` says why. */
+ | 'unavailable';
+/** The versioned descriptor written beside every artifact's records. */
+type ArtifactManifest = {
+    version: 1;
+    artifactId: string;
+    owner: ArtifactOwner;
+    state: 'staged' | 'committed' | 'delete_pending';
+    /** Records actually written (including truncation stubs). */
+    records: number;
+    /** UTF-8 bytes of the written record lines. */
+    bytes: number;
+    status: ArtifactStatus;
+    reason?: string;
+    /** What the captured requests represent. Never provider wire bytes. */
+    fidelity: 'runtime_request';
+    redaction: 'applied' | 'none';
+    createdAt: number;
+    committedAt?: number;
+    /** Absolute logical expiry, mirrored from the owning history row's retention. */
+    expiresAt?: number;
+    /** While `staged`: the deadline after which an abandoned writer is reclaimed. */
+    leaseUntil?: number;
+    /** Provenance when a rescore copied this artifact from another run's. */
+    copiedFrom?: {
+        artifactId: string;
+        ownerId: string;
+    };
+};
+/** A staged artifact, held open by a renewable lease while its writer runs. */
+type StagedArtifact = {
+    artifactId: string;
+    /** Push the lease deadline out. Call periodically from a long-running writer. */
+    renewLease(): Promise<void>;
+};
+/** An opened artifact: its manifest plus a lazily-read stream of JSONL lines. */
+type OpenedArtifact = {
+    manifest: ArtifactManifest;
+    lines: AsyncIterable<string>;
+};
+/**
+ * The outcome of a manifest write that can legitimately find nothing to write.
+ *
+ * `commit`, `markDeletePending` and `refreshExpiry` all name an artifact that a
+ * sweep, an operator, or a crashed sibling process may have already removed.
+ * Returning success in that case is how a history row gets published pointing
+ * at bytes that are not there, still claiming `status: 'complete'` — so the
+ * absence is reported instead of swallowed.
+ */
+type ArtifactWriteResult = {
+    ok: true;
+    manifest: ArtifactManifest;
+} | {
+    ok: false;
+    reason: 'missing';
+};
+/**
+ * The storage contract for diagnostic artifacts.
+ *
+ * Every method is idempotent where that is meaningful: deleting an unknown id
+ * succeeds, marking delete-pending twice succeeds, and rolling back an
+ * already-gone artifact succeeds. Keys are opaque ids the store mints — a
+ * caller never supplies a path or a URL, which is what keeps an imported
+ * artifact reference from naming an arbitrary file.
+ */
+interface DiagnosticArtifactStore {
+    /** Reserve a new artifact id for `owner`, held by a lease of `leaseMs`. */
+    stage(owner: ArtifactOwner, opts: {
+        leaseMs: number;
+    }): Promise<StagedArtifact>;
+    /** Append one already-encoded JSONL record. The caller pre-bounds its size. */
+    append(artifactId: string, line: string): Promise<void>;
+    /**
+     * Seal the record stream and record how complete it is.
+     *
+     * `redaction` is what the WRITER applied. The store cannot infer it — the
+     * records arrive already scrubbed — and a manifest that says `'none'` over
+     * redacted bytes is the kind of quiet dishonesty a compliance reader acts on.
+     */
+    finalize(artifactId: string, status: ArtifactStatus, reason?: string, redaction?: 'applied' | 'none'): Promise<ArtifactManifest>;
+    /** Promote a finalized artifact to `committed` once its owner row exists. */
+    commit(artifactId: string, opts: {
+        expiresAt?: number;
+    }): Promise<ArtifactWriteResult>;
+    /** Discard a staged artifact entirely (its owner row was never written). */
+    rollback(artifactId: string): Promise<void>;
+    /** Read a committed (or interrupted) artifact, or `undefined` if absent. */
+    open(artifactId: string): Promise<OpenedArtifact | undefined>;
+    /**
+     * Copy `sourceId`'s records under a new id owned by `owner`, bounded by bytes.
+     *
+     * The result is a STAGED artifact, exactly as `stage` returns one: a copy is
+     * the beginning of the new owner's capture, not the end of it — a rescore
+     * goes on writing its own judge calls into the same artifact. It therefore
+     * carries `renewLease` too, since a copy whose lease nobody holds is swept
+     * out from under the run still filling it.
+     */
+    copy(sourceId: string, owner: ArtifactOwner, opts: {
+        maxBytes: number;
+        leaseMs: number;
+    }): Promise<(StagedArtifact & {
+        truncated: boolean;
+        bytes: number;
+        /** What the SOURCE said about the bytes just copied. Never inferred. */
+        redaction: 'applied' | 'none';
+    }) | undefined>;
+    /** Record an idempotent deletion intent. Reports an artifact already gone. */
+    markDeletePending(artifactId: string): Promise<ArtifactWriteResult>;
+    /** Physically remove an artifact. Idempotent. */
+    delete(artifactId: string): Promise<void>;
+    /** Every manifest the store holds. */
+    list(): Promise<ArtifactManifest[]>;
+    /** Rewrite an artifact's logical expiry (its owner row was re-saved). */
+    refreshExpiry(artifactId: string, expiresAt: number | undefined): Promise<ArtifactWriteResult>;
+}
+/**
+ * The built-in filesystem backend: one directory per artifact under `root`,
+ * holding `manifest.json` and `records.jsonl`.
+ *
+ * Manifest writes go through a temp file and a rename, so a crash mid-write
+ * leaves either the previous manifest or the new one — never a half-parsed
+ * JSON document that would make the artifact unreadable and unreclaimable.
+ * Record appends are serialized per artifact through a promise chain so
+ * concurrent writers cannot interleave partial lines.
+ */
+declare class FileDiagnosticArtifactStore implements DiagnosticArtifactStore {
+    private readonly root;
+    /** Per-artifact serialization chain for appends. */
+    private readonly writeChains;
+    /** Live byte/record counters, folded into the manifest at finalize. */
+    private readonly counters;
+    /**
+     * The most recently deleted ids, newest last.
+     *
+     * Ids are minted, never reused, so a write for one of these is always a
+     * caller bug rather than a legitimate resurrection. Remembering them is what
+     * stops such a write from recreating a directory holding records with no
+     * manifest — a shape `list()` skips and reconciliation therefore never
+     * reclaims.
+     *
+     * Bounded, because a long-lived Studio server deletes an artifact for every
+     * eval it ever expires and an unbounded set would hold every id for the life
+     * of the process. The window that matters is short: a dropped write is one
+     * already in flight when the delete landed, i.e. queued behind it on the same
+     * serializer. Keeping the last {@link DELETED_MEMORY} ids covers that window
+     * by orders of magnitude. Past it the append does not recreate anything —
+     * `appendFile` does not create parent directories, so it fails `ENOENT` — it
+     * degrades that run's capture, which the guard exists to avoid: the channel
+     * reads a rejected write as a dead sink and stops capturing the rest of the
+     * run.
+     */
+    private readonly deleted;
+    constructor(options: {
+        root: string;
+    });
+    private dir;
+    private readManifest;
+    /** Atomic manifest replacement: write a sibling temp file, then rename over. */
+    private writeManifest;
+    /**
+     * Run `work` after everything already queued for this artifact.
+     *
+     * EVERY write to an artifact goes through here — record appends and manifest
+     * mutations alike — because a manifest mutation is a read-modify-write and
+     * two of them interleave badly. The concrete race: the lease renewal reads a
+     * pre-finalize manifest, `finalize` writes `complete/137 records`, and the
+     * renewal's rename lands last and restores `interrupted/0`. `finalize`
+     * returned its in-memory object, so the result would claim 137 records while
+     * the artifact on disk claimed none.
+     */
+    private serialize;
+    private mutate;
+    stage(owner: ArtifactOwner, opts: {
+        leaseMs: number;
+    }): Promise<StagedArtifact>;
+    append(artifactId: string, line: string): Promise<void>;
+    finalize(artifactId: string, status: ArtifactStatus, reason?: string, redaction?: 'applied' | 'none'): Promise<ArtifactManifest>;
+    commit(artifactId: string, opts: {
+        expiresAt?: number;
+    }): Promise<ArtifactWriteResult>;
+    rollback(artifactId: string): Promise<void>;
+    open(artifactId: string): Promise<OpenedArtifact | undefined>;
+    copy(sourceId: string, owner: ArtifactOwner, opts: {
+        maxBytes: number;
+        leaseMs: number;
+    }): Promise<(StagedArtifact & {
+        truncated: boolean;
+        bytes: number;
+        redaction: 'applied' | 'none';
+    }) | undefined>;
+    markDeletePending(artifactId: string): Promise<ArtifactWriteResult>;
+    delete(artifactId: string): Promise<void>;
+    /** Record a deletion, evicting the oldest id once the window is full. */
+    private rememberDeleted;
+    list(): Promise<ArtifactManifest[]>;
+    refreshExpiry(artifactId: string, expiresAt: number | undefined): Promise<ArtifactWriteResult>;
+}
+
+/**
+ * Client-side rate governor for provider HTTP calls: the plain, non-adaptive
+ * base. Constructed directly (custom adapters, transcription) it applies only
+ * the configured static caps. The built-in chat adapters use its pooled,
+ * default-on adaptive subclass, `ScopeGovernor` (`governor-pool.ts`).
  *
  * Wraps the single `fetchWithRetry` chokepoint (see `retry.ts`) so a configured
  * provider can bound how many requests it has *in flight* at once and, optionally,
@@ -2412,10 +2969,13 @@ declare class AxlEventBus implements AsyncIterable<AxlEvent> {
  *   its whole lifetime. Non-streaming calls still hold it across generation in
  *   practice, because a provider sends no headers until the completion is
  *   finished. Neither bounds tokens/min.
- * - **Per provider instance.** Providers are singletons per (runtime, provider
- *   type), so one governor governs all calls through that adapter — but NOT
- *   embedder calls (the embedder is constructed outside the registry) and NOT
- *   other processes/runtimes sharing the same API key.
+ * - **One governor per scope, per runtime.** The built-in chat adapters don't
+ *   construct this class directly: they resolve a governor per call from the
+ *   runtime's `GovernorPool` (`governor-pool.ts`), one per provider family +
+ *   base-URL origin + credential source + model. A directly constructed
+ *   `RateLimiter` (custom adapters) governs exactly the calls it is passed to.
+ *   Neither covers embedder calls (constructed outside the registry) nor other
+ *   processes.
  * - **`minIntervalMs` is global spacing, not a burst bucket.** A single
  *   last-grant timestamp gates every grant: a permit may be free yet a grant
  *   still waits out the interval. There is no accumulated burst allowance.
@@ -2423,8 +2983,9 @@ declare class AxlEventBus implements AsyncIterable<AxlEvent> {
  *   never across a nested `ctx.ask`, so an agent-as-tool chain on the same
  *   provider under `maxConcurrent: 1` still completes — permits don't stack.
  *
- * `observe(res)` is a no-op seam in v1 for a future adaptive (header-driven)
- * pacing follow-up.
+ * `observe(res)` is a no-op here. The per-scope governor in `governor-pool.ts`
+ * overrides it (quota-header hint) and adds the rate-limit brake; a directly
+ * constructed `RateLimiter` is never adaptive.
  */
 /** Configuration for a provider's {@link RateLimiter}. All fields optional. */
 type RateLimitConfig = {
@@ -2446,23 +3007,67 @@ type RateLimitConfig = {
      * If set, `acquire()` rejects (fail loud) when a caller has queued longer than
      * this many ms, instead of waiting indefinitely — surfaces a misconfigured
      * cap rather than silently hanging the run.
+     *
+     * Bounds only a call's FIRST wait for a permit. On a scope that adapts (see
+     * `adaptive`), a call first waits out any active rate-limit brake and only
+     * then starts this clock; a call already queued when a brake begins keeps
+     * its clock running through it. A retry's re-acquire after a rate-limit 429
+     * is exempt: it is bounded by `maxRateLimitRetries` and the ask's `timeout`.
      */
     acquireTimeoutMs?: number;
+    /**
+     * Feedback-driven pacing on every built-in chat provider. Default `true`.
+     * When on, a rate-limit 429 brakes every call on the scope for the
+     * exponential backoff, lengthened (never shortened) by a longer
+     * `Retry-After` / `retry-after-ms` and clamped at 60 s, and
+     * the call retries on its own budget (`maxRateLimitRetries`), and the scope
+     * then paces its grants adaptively (a rate seeded from recent demand,
+     * recovered linearly on success, dropped once traffic stays well below it;
+     * tuning is internal) until it reopens. Nothing waits before the first 429.
+     *
+     * Only first-party OpenAI (`openai:`, `openai-responses:`) and Anthropic at
+     * the vendor's default endpoint origin read the 429 body: there a spend-cap
+     * 429 fails fast, and a low quota header holds recovery. Everywhere else
+     * (Gemini, OpenAI-compatible presets, a proxy or gateway `baseUrl`) every
+     * 429 is a rate limit, so a spend-cap or daily-quota 429 fails only once
+     * `maxRateLimitRetries` is spent.
+     *
+     * `false` restores the plain behavior: a 429 shares the transient retry
+     * budget, holds up no other call, and nothing is paced. Ignored by a
+     * directly constructed `RateLimiter`, which is never adaptive.
+     */
+    adaptive?: boolean;
+    /**
+     * Retries after a rate-limit 429 on an adaptive scope, separate from the
+     * transient (503/529/network) budget. Default `8`. A non-negative integer;
+     * `0` still brakes the scope but returns the 429. Ignored where
+     * `adaptive` has no effect.
+     */
+    maxRateLimitRetries?: number;
 };
 /**
  * Counting semaphore + FIFO waiter queue. Dependency-free. Not shared across
  * processes — purely an in-process pacing aid.
  */
 declare class RateLimiter {
-    private readonly maxConcurrent;
-    private readonly minIntervalMs;
-    private readonly acquireTimeoutMs?;
+    protected maxConcurrent: number;
+    protected minIntervalMs: number;
+    protected acquireTimeoutMs?: number;
     private active;
     private lastGrantAt;
     private readonly queue;
     private spacingTimer?;
     private warnedQueued;
     constructor(config?: RateLimitConfig);
+    /**
+     * Apply already-sanitized limits (see {@link sanitizeRateLimitConfig}). An
+     * absent field means "no limit". Takes effect for the next grant; a waiter
+     * already queued keeps the `acquireTimeoutMs` timer it was armed with.
+     *
+     * @internal Extension point for Axl's own per-scope governor; not a supported
+     * public contract and may change without notice.
+     */
+    protected applyLimits(limits: RateLimitConfig): void;
     /**
      * Acquire a permit. Resolves when one is granted (respecting `maxConcurrent`
      * and `minIntervalMs`). The caller MUST pair every resolved `acquire()` with
@@ -2477,18 +3082,282 @@ declare class RateLimiter {
      * With `acquireTimeoutMs`, a waiter that sits in the queue too long rejects.
      */
     acquire(signal?: AbortSignal): Promise<void>;
+    /**
+     * Queue for a permit. A `priority` waiter goes ahead of every non-priority
+     * waiter (FIFO among priority waiters) and never warns about queueing;
+     * `timeoutMs` arms the fail-loud queue timeout (`undefined`: none).
+     *
+     * @internal Extension point for Axl's own per-scope governor (a retry's
+     * re-acquire); not a supported public contract and may change without notice.
+     */
+    protected enqueue(signal: AbortSignal | undefined, options: {
+        priority: boolean;
+        timeoutMs: number | undefined;
+    }): Promise<void>;
+    /**
+     * Take a permit synchronously if one is free right now — nobody queued,
+     * capacity available and spacing satisfied — exactly when `acquire()` would
+     * grant without waiting. Returns whether it took one; the caller pairs a
+     * `true` with one {@link release}.
+     *
+     * @internal Extension point for Axl's own per-scope governor.
+     */
+    protected tryGrant(): boolean;
+    /**
+     * The minimum gap between two grants, in ms. Every grant path (the queue
+     * pump, priority waiters and {@link tryGrant}) spaces by it.
+     *
+     * @internal Extension point for Axl's own per-scope governor, which widens it
+     * while adaptively paced; not a supported public contract.
+     */
+    protected grantIntervalMs(): number;
+    /**
+     * Called on every grant, with its timestamp.
+     *
+     * @internal Extension point for Axl's own per-scope governor.
+     */
+    protected onGrant(_at: number): void;
+    /** How long the next grant must wait for spacing; `<= 0` means it may go now. */
+    private spacingWaitMs;
+    /**
+     * Whether a CONFIGURED cap is what stops a grant right now: the concurrency
+     * cap is full, or the configured spacing has not elapsed. Queueing for any
+     * other reason (a brake, adaptive spacing) is not a cap the user can raise,
+     * so it never triggers the queued warning.
+     */
+    private staticCapBinding;
+    /**
+     * Whether any caller is queued for a permit.
+     *
+     * @internal Extension point for Axl's own per-scope governor.
+     */
+    protected hasWaiters(): boolean;
     /** Release a previously acquired permit and wake the next waiter. */
     release(): void;
-    /** v1 no-op seam for a future adaptive (rate-limit-header-driven) pacing follow-up. */
+    /** No-op; the per-scope governor overrides it to read quota headers. */
     observe(_res: Response): void;
-    /** Drain the queue: grant head waiters while a permit is free and spacing allows. */
-    private pump;
+    /**
+     * Drain the queue: grant head waiters while a permit is free and spacing allows.
+     * Protected so the internal per-scope governor can gate grants on its own
+     * state (for example a brake) by overriding it.
+     *
+     * @internal Extension point for Axl's own per-scope governor; not a supported
+     * public contract and may change without notice.
+     */
+    protected pump(): void;
     private grant;
     /** Reject a still-queued waiter (abort or timeout) and remove it cleanly. */
     private settleWaiter;
     private clearWaiterTimers;
 }
 
+/**
+ * Why a 429 was returned. `'unknown'` means the body did not identify either
+ * cause; the transport treats it as a rate limit, as it does every 429 on a
+ * scope with no dialect.
+ */
+type QuotaClass = 'rate_limit' | 'spend_cap' | 'unknown';
+type QuotaDialect = {
+    /**
+     * Minimum `remaining / limit` over the dialect's lanes, in `[0, 1]`, or
+     * `undefined` when no lane is usable. Meant for 2xx responses.
+     *
+     * Total over header *values*. A `Headers` object whose `get` itself throws
+     * is a broken input rather than provider data, so that throw propagates for
+     * the governor's warn-once containment instead of being hidden here.
+     */
+    hint(headers: Headers): number | undefined;
+    /**
+     * Classify a 429 without consuming the original body. Never rejects:
+     * a non-429, a response without `clone()` or a body, a failing read, or a
+     * non-JSON body all yield `'unknown'`.
+     */
+    classify429(res: Response): Promise<QuotaClass>;
+};
+
+/**
+ * Per-runtime pool of rate governors, one per **scope**.
+ *
+ * A provider's rate limits belong to the account and model, not to an adapter
+ * instance. Before this pool, every built-in adapter built its own
+ * `RateLimiter`, so `openai:` and `openai-responses:` on one key got two
+ * independent caps (effective concurrency = the sum), and one cap covered every
+ * model the adapter served. Here a scope is
+ *
+ *   provider family + base-URL origin + credential source + model
+ *
+ * - **Family**: `openai` for both OpenAI adapters (Chat Completions and
+ *   Responses share an account's limits); otherwise the adapter or preset name.
+ * - **Origin**: `new URL(baseUrl).origin`, so a proxy or a self-hosted endpoint
+ *   is a different account. The origin carries no userinfo, path or query.
+ * - **Credential source**: a callback `apiKey` by *identity* (a rotating token
+ *   callback is one scope), a string by *value* (two tenants' keys never
+ *   share). Each source maps to an opaque in-process number; the key itself is
+ *   never part of a map key that is logged, never in a warning, never in an
+ *   error.
+ * - **Model**: the effective wire model of the call. There is no model-family
+ *   table; models that share a vendor bucket are separate scopes.
+ *
+ * Ownership: the runtime's `ProviderRegistry` holds one pool and hands it to the
+ * built-in factories, which join the adapter they construct to it at
+ * construction ({@link bindGovernorPool}). An adapter constructed directly
+ * joins a private pool on its first call, so one instance registered in two runtimes shares its
+ * governors (the documented explicit cross-runtime sharing path). Sharing is
+ * never inferred from equal keys across runtimes.
+ *
+ * Config merge: only when two provider blocks reach one account (for example
+ * `providers.openai` and `providers['openai-responses']` with the same key and
+ * origin). Each explicit field takes the strictest value and the conflict is
+ * warned about once per account. Merging only ever tightens, so a live
+ * governor can adopt the merged limits in place.
+ *
+ * Internal: nothing here is barrel-exported.
+ */
+
+/**
+ * The governor for one scope. A {@link RateLimiter} whose limits can be
+ * tightened in place when a second provider block reaches the same account.
+ *
+ * Unless `adaptive` is `false` ({@link ScopeGovernor.adapts}), it is also the
+ * scope's **fleet brake**: `fetchWithRetry` calls {@link brake} after a
+ * rate-limit 429, and from then until `brakeUntil` no call on the scope is
+ * granted a permit or dispatches. `braked()`, `awaitClear()` and `pump()`
+ * share one predicate, `Date.now() < brakeUntil`. A scope that does not adapt
+ * never brakes, so it behaves exactly as a plain `RateLimiter`.
+ *
+ * Adapting needs no quota dialect. A dialect (first-party OpenAI and Anthropic
+ * at the vendor origin, see `quota.ts`) adds only two vendor-specific extras:
+ * spend-cap classification of a 429 body, and the 2xx quota hint that holds
+ * recovery. Without one, every 429 is treated as a rate limit and the hint is
+ * never read, so recovery and reopening proceed as if the account were healthy.
+ */
+declare class ScopeGovernor extends RateLimiter {
+    readonly dialect?: QuotaDialect | undefined;
+    private readonly family;
+    private brakeUntil?;
+    private brakeEndTimer?;
+    private brakeEndAt?;
+    private adaptive;
+    private rateLimitRetries;
+    private warnedHint;
+    private warnedEngaged;
+    /** The last 2xx quota hint (`remaining / limit`, see `quota.ts`); a low one holds growth. */
+    lastHint: number | undefined;
+    /**
+     * Grants per second, or `undefined` while the scope is fully open (its state
+     * until the first rate-limit 429, and again after it reopens). Enforced as a
+     * minimum gap of `1000 / rate` ms between grants, never below `minIntervalMs`.
+     */
+    private rate;
+    /** The rate the last cut set; recovery adds `max(rateAtLastCut, ALPHA_FLOOR_RATE) / R` per second. */
+    private rateAtLastCut;
+    /** When the last cut happened. A 429 cuts only if its request left after this. */
+    private lastCutAt;
+    /**
+     * Recovery accrues from here. Advanced by each 2xx and pushed to the end of
+     * any brake, so braked time never accrues.
+     */
+    private lastProgressAt;
+    /** Since when the reopen condition has held on every 2xx; `undefined` while it doesn't. */
+    private reopenSince;
+    /** Grant timestamps within `WINDOW_MS`, oldest first, from `grantsHead` on. */
+    private grants;
+    private grantsHead;
+    /** Braked spans overlapping the window, oldest first, non-overlapping. */
+    private brakeSpans;
+    /**
+     * @param limits already sanitized (see `sanitizeRateLimitConfig`).
+     * @param dialect the scope's quota dialect, or `undefined` when the vendor
+     *   has none (no spend-cap classification, no quota hint).
+     * @param family the provider family, only to name the scope in a warning.
+     */
+    constructor(limits: RateLimitConfig, dialect?: QuotaDialect | undefined, family?: string);
+    /** Adopt the account's merged limits. Merges only tighten (see {@link STRICTEST}). */
+    reconfigure(limits: RateLimitConfig): void;
+    /** Whether this scope brakes and retries rate-limit 429s on their own budget. */
+    get adapts(): boolean;
+    /** The rate-limit retry budget (`maxRateLimitRetries`). */
+    get maxRateLimitRetries(): number;
+    /** The brake predicate shared by `awaitClear`, `pump` and `fetchWithRetry`. */
+    braked(): boolean;
+    /**
+     * On a rate-limit 429: brake every call on the scope for `ms` (already
+     * clamped by the caller to the transport's backoff ceiling), and cut the
+     * adaptive rate. Extends, never shortens, an active brake. `dispatchedAt` is
+     * when the 429'd request left.
+     *
+     * The cut happens at most once per congestion epoch: only when the 429'd
+     * request left after the last cut. The rest of a wave that was already in
+     * flight extends the brake without cutting again.
+     */
+    brake(ms: number, dispatchedAt: number): void;
+    /** The adaptive rate in grants per second; `undefined` while fully open. @internal */
+    get currentRate(): number | undefined;
+    /**
+     * `rate = BETA × min(rate ?? ∞, demand)`, floored at `MIN_RATE`, where demand
+     * is grants in the window over its unbraked elapsed time (floored at 1 s).
+     * Demand is used only when it can be trusted: when no brake overlaps the
+     * window (a burst from a cold scope reads its true count), or once the window
+     * holds `MIN_DEMAND_SPAN_MS` of unbraked time. Right after a long brake the
+     * window holds only a few spaced grants, so the cut uses the current rate.
+     */
+    private cut;
+    /** Advance recovery on a 2xx, then check whether the scope can reopen (plan §4.4, Q11). */
+    private recover;
+    /**
+     * Whether `rate` exceeds `REOPEN_FACTOR ×` the window's peak one-second grant
+     * count. The peak is at least the window's per-second average, so a scope
+     * paced near its demand (the common case, with the largest window) is
+     * answered without the O(window) scan.
+     */
+    private farAbovePeakDemand;
+    /** The most grants in any one-second span of the window (two pointers, O(window)). */
+    private peakOneSecondGrants;
+    /** Total braked time inside `[from, to)`. */
+    private brakedOverlap;
+    private recordBrakeSpan;
+    /** Drop grants and braked spans older than the window; memory stays bounded by it. */
+    private pruneWindow;
+    protected onGrant(at: number): void;
+    /** Adaptive spacing on top of the configured `minIntervalMs`, never below it (RQ5). */
+    protected grantIntervalMs(): number;
+    /**
+     * Resolve once the scope is not braked. Rejects with `signal.reason` if the
+     * signal is already aborted (even when not braked) or aborts while waiting.
+     */
+    awaitClear(signal?: AbortSignal): Promise<void>;
+    /**
+     * Re-acquire a permit for a call that already dispatched (after a
+     * rate-limit 429, or a transient backoff that woke into a brake): queued
+     * ahead of first-time callers and exempt from `acquireTimeoutMs`.
+     */
+    reacquire(signal?: AbortSignal): Promise<void>;
+    /**
+     * Take a permit without waiting, if `acquire()` / `reacquire()` would grant
+     * one at once: not braked and a permit free. Lets the transport skip timing a
+     * wait that never happened, so an unqueued call reports `queuedMs` exactly 0.
+     */
+    tryAcquire(): boolean;
+    /**
+     * On a 2xx: read the quota hint (if the scope has a dialect), then advance
+     * recovery. Total: a throwing dialect warns once and is ignored (the hint is
+     * then treated as healthy). Without a dialect `lastHint` stays `undefined`.
+     */
+    observe(res: Response): void;
+    /**
+     * Grants nothing while braked; re-pumps at the brake's end if anyone is
+     * queued. The brake-end timer lives only as long as its waiters: when the
+     * last one leaves (abort or timeout, both of which re-pump) it is cleared, so
+     * a long brake never holds the event loop open with nothing to wake. It is
+     * deliberately not `unref`'d — while a waiter exists, that timer is the only
+     * thing that will resume its call.
+     */
+    protected pump(): void;
+    private clearBrakeEnd;
+    private armBrakeEnd;
+    private sleepUntilBrakeEnd;
+}
+
 /**
  * Input modalities a profile declares for the OpenAI-compatible wire format.
  * Declaring a modality is the ONLY way a profile opts in: the engine derives
@@ -2744,8 +3613,20 @@ declare class OpenAICompatibleProvider implements Provider {
     /** A key string, or a resolver invoked per request (expiring tokens). */
     protected readonly apiKeySource: ApiKeySource;
     protected readonly authHeader?: AuthHeader;
-    protected readonly governor?: RateLimiter;
+    /**
+     * Namespaced so it cannot collide with a member a downstream subclass
+     * declares. A plain property (not `#private` or a WeakMap keyed by `this`)
+     * so a caller's own Proxy around the adapter still reaches it.
+     */
+    private readonly axlRateGovernors;
     constructor(options: OpenAICompatibleOptions);
+    /**
+     * The rate governor for one call to `model` (the effective wire model), from
+     * the runtime's per-scope pool. Every scope has one (with no `rateLimit` it
+     * caps nothing until a rate-limit 429). Subclasses that issue their own
+     * `fetchWithRetry` pass this as `governor`.
+     */
+    protected governorFor(model: string): ScopeGovernor;
     /** Resolve the API key for one request, validating against allowMissingApiKey. */
     protected resolveKey(): Promise<string>;
     chat(messages: ChatMessage[], options: ChatOptions): Promise<ProviderResponse>;
@@ -2767,6 +3648,13 @@ declare class OpenAICompatibleProvider implements Provider {
         response?: OpenAIModelResponse;
     }): number | undefined;
     protected parseResponse(json: OpenAIChatResponse, model: string, request?: Record<string, unknown>): ProviderResponse;
+    /**
+     * How this profile's `computeCost` derived its figure. `'from-response'`
+     * profiles (OpenRouter, xAI) echo a vendor-supplied USD amount and are
+     * authoritative; table and zero pricing are Axl estimates. Native subclasses
+     * that override `computeCost` override this alongside it.
+     */
+    protected costProvenance(cost: number | undefined): ProviderResponse['costProvenance'];
     private roundTripMetadata;
     /**
      * PRIVATE, and deliberately not an extension point. It was `protected`, but
@@ -2957,12 +3845,53 @@ interface StateStore {
      * deleting an unknown id returns `false` without throwing.
      */
     deleteExecution?(executionId: string): Promise<boolean>;
-    /** Save an eval result to history. */
+    /** Save an eval result to history. Creates the row, or replaces it. */
     saveEvalResult?(entry: EvalHistoryEntry): Promise<void>;
+    /**
+     * Replace an eval history row that ALREADY EXISTS, leaving its retention
+     * exactly as it was. Returns `true` iff a row was there and was updated;
+     * **never creates one**.
+     *
+     * This is how the runtime writes a CORRECTION — a diagnostics sweep rewriting
+     * a row whose artifact it just reclaimed, a commit failure downgrading one.
+     * Such a write has no business creating anything: the row may have been
+     * deleted (a right-to-be-forgotten request) or expired between the moment the
+     * correction was computed and the moment it lands, and `saveEvalResult` would
+     * bring it back — permanently on a store with no expiry. Checking first and
+     * then saving does not close that window; only the store can, so the
+     * condition lives here.
+     *
+     * Implement it conditionally and atomically: `SET ... XX KEEPTTL` on Redis,
+     * `UPDATE ... WHERE id = ?` on SQL, a presence check on an in-process map.
+     * A store that does not implement it gets no correction written at all.
+     */
+    updateEvalResult?(entry: EvalHistoryEntry): Promise<boolean>;
     /** List eval history entries (most recent first). */
     listEvalResults?(limit?: number): Promise<EvalHistoryEntry[]>;
     /** Delete an eval history entry by id. Returns true if an entry was deleted. */
     deleteEvalResult?(id: string): Promise<boolean>;
+    /**
+     * Retention capability: does this eval history row still exist, and when does
+     * the store itself expire it?
+     *
+     * Diagnostic artifacts (opt-in captured requests) live OUTSIDE the state store
+     * — typically on a filesystem — and their lifetime must follow the history row
+     * that owns them. A store with server-side expiry (Redis `PTTL`) cannot notify
+     * that filesystem when a key ages out, so the runtime mirrors the absolute
+     * `expiresAt` onto the artifact manifest at commit time and sweeps expired
+     * bytes on a timer and at startup. Physical deletion is therefore EVENTUAL,
+     * not synchronous with the store's expiry.
+     *
+     * Built-ins implement it: `MemoryStore` and `SqliteStore` never expire, so
+     * `expiresAt` is `undefined`; `RedisStore` reports existence and any live TTL.
+     * A custom store WITHOUT this method cannot host managed artifact capture —
+     * `AxlRuntime` rejects that configuration when it is constructed rather than
+     * after a run has spent money.
+     */
+    getEvalRetention?(id: string): Promise<{
+        exists: boolean;
+        expiresAt?: number;
+    }>;
     /** List all session IDs (used by Studio session browser). */
     listSessions?(): Promise<string[]>;
     /**
@@ -3134,12 +4063,18 @@ type ProviderConfig = {
     /** OpenAI-compatible presets only: override the profile auth header shape. */
     authHeader?: AuthHeader;
     /**
-     * Opt-in client-side rate governor for this provider's HTTP calls (see
-     * {@link RateLimitConfig}). Bounds in-flight request concurrency (and,
-     * optionally, request spacing) through the shared `fetchWithRetry` chokepoint.
-     * Omitted ⇒ no governor (behavior unchanged). Caveat: governs **chat** calls
-     * through this provider instance only — NOT memory-embedder calls (constructed
-     * outside the registry) and NOT other processes sharing the same API key.
+     * Client-side rate governor for this provider's chat calls (see
+     * {@link RateLimitConfig}), through the shared `fetchWithRetry` chokepoint.
+     * Omitted ⇒ no static caps (no concurrency bound, no spacing), but the
+     * adaptive brake and pacing still apply after a rate-limit 429; turn them
+     * off with `{ adaptive: false }`. Governors are pooled per runtime, one per
+     * scope: provider family (`openai` covers `openai-responses`) + base-URL
+     * origin + credential source + model. Two blocks reaching one scope use the
+     * strictest value per field. Caveats: the pooled, adaptive governor covers
+     * **chat** calls only. Transcription providers apply the same static caps
+     * through their own per-instance, non-adaptive limiter; memory-embedder
+     * calls, other runtimes (unless they share a provider instance) and other
+     * processes are not governed.
      */
     rateLimit?: RateLimitConfig;
 };
@@ -3247,6 +4182,49 @@ type DiagnosticsConfig = {
      * `AXL_DIAGNOSTICS_SILENT=true`.
      */
     silent?: boolean;
+    /**
+     * Where opt-in captured-request artifacts are stored, and how their lifecycle
+     * is reclaimed. Managed capture (`runEval({ captureRequests: true })`) is
+     * UNAVAILABLE until this is configured — Axl never silently writes captured
+     * prompts to a process temp folder.
+     *
+     * Supply exactly one of `root` (use the built-in
+     * {@link DiagnosticArtifactStore} filesystem backend) or `store` (your own
+     * backend — required when eval history lives in Redis, whose server-side TTL
+     * cannot notify a local filesystem).
+     *
+     * The configured `StateStore` must implement `getEvalRetention` so an
+     * artifact's logical expiry can follow its owning history row; a custom store
+     * without it is rejected when the runtime is constructed, not after a run has
+     * already spent money.
+     */
+    artifacts?: DiagnosticArtifactsConfig;
+};
+/** Artifact storage + reclamation settings. See {@link DiagnosticsConfig.artifacts}. */
+type DiagnosticArtifactsConfig = {
+    /** A host-supplied backend. Takes precedence over `root`. */
+    store?: DiagnosticArtifactStore;
+    /** Directory for the built-in filesystem backend. Ignored when `store` is set. */
+    root?: string;
+    /** Reconciliation sweep period in ms. Default `60_000`. The timer is unref'd
+     *  and cleared by `runtime.shutdown()`. */
+    sweepIntervalMs?: number;
+    /** How long a staged (actively written) artifact is protected from the
+     *  sweeper before it counts as abandoned. Default `300_000`. */
+    leaseMs?: number;
+    /**
+     * Longest a single artifact's lease is renewed before the runtime lets go.
+     * Default `86_400_000` (24 h).
+     *
+     * The lease renewal is a timer, and a caller that never finalizes or rolls
+     * back its artifact would otherwise pin it forever — a leak with no
+     * self-healing path, because the sweeper only reclaims a lease that expired.
+     * Past this bound the runtime stops renewing, the lease runs out, and the
+     * artifact is reclaimed on the next sweep like any abandoned writer's. Set it
+     * above the longest run you expect; a run that outlives it keeps working and
+     * only loses its captured requests.
+     */
+    maxHoldMs?: number;
 };
 
 /** Full Axl configuration */
@@ -3279,6 +4257,7 @@ type ResolvedProvider = {
     provider: Provider;
     model: string;
 };
+/** A user factory registered with {@link ProviderRegistry.register}. */
 type ProviderFactory = (config: AxlConfig) => Provider;
 /**
  * Registry for LLM providers. Holds cached provider instances and supports
@@ -3294,6 +4273,11 @@ declare class ProviderRegistry {
     private instances;
     /** Factory functions, keyed by provider name */
     private factories;
+    /**
+     * Rate governors for the adapters built-in factories construct, one per
+     * scope. Per registry, so per runtime: the state dies with the runtime.
+     */
+    private governors;
     /** Fallback provider returned when no factory or instance matches */
     private fallbackInstance?;
     constructor();
@@ -3339,6 +4323,9 @@ declare class ProviderRegistry {
     resolve(uri: string | undefined, config?: AxlConfig): ResolvedProvider;
     /**
      * Clear all cached provider instances. Useful for testing or reconfiguration.
+     * Also starts a fresh governor pool, so adapters rebuilt from a changed
+     * `rateLimit` are not merged with the discarded ones. A call already in
+     * flight finishes on the governor it holds.
      */
     clearCache(): void;
     /**
@@ -3476,11 +4463,6 @@ type RecallResult = {
     data: unknown | VectorResult[] | null;
     usage?: EmbedUsage;
 };
-/**
- * Coordinates key-value memory and vector store for semantic search.
- * All key-value operations delegate to the StateStore.
- * Vector operations use the configured VectorStore + Embedder.
- */
 declare class MemoryManager {
     private vectorStore?;
     private embedder?;
@@ -3591,6 +4573,18 @@ type WorkflowContextInit = {
     metadata?: Record<string, unknown>;
     config: AxlConfig;
     providerRegistry: ProviderRegistry;
+    /**
+     * Internal: resolve a `provider:model` URI to the runtime's SCOPED provider
+     * facade, so every model call the context makes joins the active accounting
+     * scope and honors its budget. Supplied by `AxlRuntime`; when omitted the
+     * context wraps the registry's raw adapter itself, so a directly constructed
+     * context is instrumented too. The registry stays available for everything
+     * else that needs it.
+     */
+    resolveProvider?: (uri: string) => {
+        provider: Provider;
+        model: string;
+    };
     transcriptionProviderRegistry?: TranscriptionProviderRegistry;
     sessionHistory?: ChatMessage[];
     onTrace?: (event: AxlEvent) => void;
@@ -3696,6 +4690,9 @@ declare class WorkflowContext<TInput = unknown> {
     get totalCost(): number;
     private config;
     private providerRegistry;
+    private readonly resolveProviderUri;
+    /** Fallback facade cache, used only when no runtime resolver was supplied. */
+    private readonly ownScopedProviders;
     private transcriptionProviderRegistry?;
     private sessionHistory;
     private onTrace?;
@@ -4081,6 +5078,29 @@ declare class WorkflowContext<TInput = unknown> {
      * @param options - Optional: schema, routerModel, metadata, retries
      */
     delegate<T = string>(agents: Agent[], prompt: ModelInput, options?: DelegateOptions<T>): Promise<T>;
+    /**
+     * Declare a paid unit of work Axl cannot observe — a third-party API called
+     * from a tool, a vendor SDK, a scraper with per-request billing — so it joins
+     * the run's accounting and its budget.
+     *
+     * Admission is checked BEFORE `fn` runs, so a closed budget refuses the call
+     * with an `AdmissionDeniedError` instead of spending. The operation finalizes
+     * on return, throw or abort; a cost reported before a later throw is kept.
+     * Not reporting a cost marks the run's accounting `incomplete` with reason
+     * `'external_unreported'` — silence is never read as free.
+     *
+     * The amount must be DISJOINT: nested `ctx.ask` and other Axl operations
+     * account for themselves, so including them double-charges.
+     *
+     * ```ts
+     * const rows = await ctx.withExternalOperation({ name: 'vendor-search' }, async (report) => {
+     *   const res = await vendor.search(query);
+     *   report.setCost(res.billedUsd);
+     *   return res.rows;
+     * });
+     * ```
+     */
+    withExternalOperation<T>(descriptor: ExternalOperationDescriptor, fn: (report: ExternalOperationReport) => Promise<T>): Promise<T>;
     /** Transcribe recorded audio through the dedicated transcription registry.
      * This operation never enters the chat history or chat-provider path. */
     transcribe(request: TranscriptionRequest): Promise<Transcript>;
@@ -4395,13 +5415,282 @@ declare class Session {
     }): Promise<Session>;
 }
 
+/**
+ * Opt-in request capture — "what did we actually submit on the turn after the
+ * model's output was rejected?"
+ *
+ * Capture is a **diagnostics** rail, strictly subordinate to the accounting
+ * rail in `accounting.ts`. Nothing here may change what a run costs, whether it
+ * succeeds, or how long a provider call takes:
+ *
+ * - Records are built at the scoped provider facade, by value, BEFORE the
+ *   adapter can mutate the request. A caller mutating its own `messages` array
+ *   afterwards cannot change what was recorded.
+ * - Every sink write is fire-and-forget into a byte-bounded queue. A sink that
+ *   blocks forever exhausts the queue and capture stops; the provider call is
+ *   never awaited on it.
+ * - Any failure — a throwing sink, an exhausted bound, an unserializable
+ *   payload — degrades the manifest's `status`/`reason` and nothing else.
+ *
+ * Privacy is enforced by projection, not by filtering: only an allowlist of
+ * request options is serialized, `providerOptions` contributes its KEYS only,
+ * and rich media parts become bounded descriptors. Signals, functions and
+ * credentials never enter a record in the first place. When redaction is
+ * configured the projected record additionally passes through
+ * `redactCapturedRequest()` before it reaches the sink.
+ */
+
+/** One conversation message as captured: text kept, rich media described. */
+type CapturedMessage = {
+    role: string;
+    /** Text content verbatim, or `null` when the message carried only rich parts. */
+    content: string | null;
+    /** Bounded descriptor for the non-text parts, when there were any. */
+    input?: ModelInputDescriptor;
+    name?: string;
+    tool_calls?: ToolCallMessage[];
+    tool_call_id?: string;
+};
+/** The provider-neutral request, snapshotted by value at invocation. */
+type CapturedRequest = {
+    messages: CapturedMessage[];
+    /** Tool definitions as the model sees them: names + JSON-Schema parameters. */
+    tools?: Array<{
+        name: string;
+        description?: string;
+        parameters: unknown;
+    }>;
+    responseFormat?: ResponseFormat;
+    /** Allowlisted call options only. Never signals, functions or credentials. */
+    options: {
+        model: string;
+        temperature?: number;
+        maxTokens?: number;
+        effort?: string;
+        thinkingBudget?: number;
+        includeThoughts?: boolean;
+        toolChoice?: unknown;
+        stop?: string[];
+        promptCache?: boolean;
+    };
+    /** `providerOptions` KEYS only — the values can carry credentials. */
+    providerOptionKeys?: string[];
+};
+/** What came back, projected to the fields that explain a turn. */
+type CapturedResponse = {
+    content: string;
+    tool_calls?: ToolCallMessage[];
+    usage?: ProviderResponse['usage'];
+    cost?: number;
+    costProvenance?: string;
+    timing?: ProviderResponse['timing'];
+};
+/** What went wrong, projected to identity rather than a serialized error. */
+type CapturedError = {
+    name?: string;
+    message: string;
+    code?: string;
+    status?: number;
+};
+/** The gate that rejected the previous turn and the correction fed back in. */
+type CapturedCorrection = {
+    stage: 'schema' | 'validate' | 'guardrail';
+    reason?: string;
+    /** The exact text appended to the conversation for the next turn. */
+    feedbackMessage: string;
+};
+/** Which part of an operation's life a record describes. */
+type CapturedPhase = 'start' | 'attempt' | 'end';
+/**
+ * One JSONL line. `v: 1` is the codec version; `@axlsdk/eval` re-exports this
+ * as `RequestRecord` and owns the bundle/import validation around it.
+ *
+ * A `start` record carries the request; `attempt` records mark additional
+ * transport attempts for the SAME logical operation (a 429 retry is not an
+ * output repair); an `end` record carries the response or the error. An
+ * operation that never returns therefore leaves a start record with no end —
+ * which is exactly the call you most want to inspect.
+ */
+type CapturedRequestRecord = {
+    v: 1;
+    phase: CapturedPhase;
+    operationId: string;
+    kind: 'chat' | 'stream';
+    caseIndex?: number;
+    scorer?: string;
+    executionId?: string;
+    askId?: string;
+    parentAskId?: string;
+    turn?: number;
+    retryReason?: 'schema' | 'validate' | 'guardrail';
+    /** 1-indexed transport attempt this record describes. */
+    transportAttempts: number;
+    provider: string;
+    model: string;
+    request?: CapturedRequest;
+    response?: CapturedResponse;
+    error?: CapturedError;
+    /**
+     * Why an operation ended without a response, when it ended deliberately.
+     *
+     * A stream closed by a stall timeout, a consumer `break`, or an adapter that
+     * simply stopped yielding is NOT a call that never came back. Without this
+     * the two are indistinguishable, and `start_only` — the status reserved for a
+     * genuinely hung call — stops discriminating.
+     */
+    termination?: string;
+    correction?: CapturedCorrection;
+    captured: {
+        fidelity: 'runtime_request';
+        redacted: boolean;
+        /** `true` when the record was replaced by a stub over `maxRecordBytes`. */
+        truncated: boolean;
+        /** What could not be represented, e.g. `['media']`. */
+        omitted: string[];
+        /**
+         * Why this record is a stub, when it is one.
+         *
+         * A stub has two causes and a reader has to be able to tell them apart:
+         * the record exceeded `maxRecordBytes` (its size is on `bytes`), or the
+         * request/response could not be projected at all — a `json_schema.schema`
+         * holding a function, a content part no adapter names. Both keep the
+         * operation's identity; neither is a call that failed.
+         */
+        reason?: string;
+    };
+    /** Encoded size of the record this stub replaced. Present only on stubs. */
+    bytes?: number;
+};
+/** A pointer from an eval item / scorer to one captured operation. */
+type CapturedOperationRef = {
+    operationId: string;
+    kind: 'chat' | 'stream';
+    turn?: number;
+    attempt?: number;
+    status: 'recorded' | 'start_only' | 'truncated' | 'omitted';
+};
+/** Where encoded record lines go. One call per JSONL line, already bounded. */
+type RequestCaptureSink = {
+    append(line: string): Promise<void>;
+};
+/** Per-run capture bounds. All finite positive byte counts. */
+type RequestCaptureOptions = {
+    sink: RequestCaptureSink;
+    /** Encoded bytes above which a record is replaced by a stub. Default 256 KiB. */
+    maxRecordBytes?: number;
+    /** Encoded bytes above which capture stops for the run. Default 16 MiB. */
+    maxRunBytes?: number;
+    /** Pending unflushed bytes above which capture stops. Default 1 MiB. */
+    maxQueueBytes?: number;
+    /** Apply `redactCapturedRequest` before every write. */
+    redact?: boolean;
+    /** Bounded wait for the queue to drain at close. Default 5s. */
+    flushTimeoutMs?: number;
+    /**
+     * Bytes the artifact this channel writes into ALREADY holds.
+     *
+     * A rescore opens its channel over an artifact seeded with its source run's
+     * copied records. `maxRunBytes` is a promise about how large the artifact
+     * gets, not about this channel's share of it, so the carried bytes count
+     * against the same bound.
+     */
+    carriedBytes?: number;
+};
+/** Eval-side correlation stamped onto every record produced inside a scope. */
+type CaptureCorrelation = {
+    caseIndex?: number;
+    scorer?: string;
+};
+/** What a finished capture channel has to say about itself. */
+type RequestCaptureStatus = {
+    status: 'complete' | 'truncated' | 'unavailable';
+    reason?: string;
+    records: number;
+    bytes: number;
+    redaction: 'applied' | 'none';
+};
+declare const DEFAULT_MAX_RECORD_BYTES: number;
+declare const DEFAULT_MAX_RUN_BYTES: number;
+declare const DEFAULT_MAX_QUEUE_BYTES: number;
+/**
+ * The bounded, non-blocking pipeline between the facade and a sink.
+ *
+ * One channel per capturing run. It owns the run's byte budget, the pending
+ * queue, and the ledger of which operations produced which records — the
+ * ledger is what lets an eval item point at its own operations without the
+ * runner having to parse the JSONL back.
+ */
+declare class RequestCaptureChannel {
+    private readonly sink;
+    private readonly maxRecordBytes;
+    private readonly maxRunBytes;
+    private readonly maxQueueBytes;
+    private readonly flushTimeoutMs;
+    readonly redact: boolean;
+    private runBytes;
+    private queueBytes;
+    private records;
+    private stopped;
+    private status;
+    private reason;
+    private drain;
+    private stoppedSignal;
+    private readonly stoppedPromise;
+    /** operationId → the ref an eval item/scorer will point at. */
+    private readonly refs;
+    constructor(options: RequestCaptureOptions);
+    /**
+     * Report a CHANNEL-WIDE capture failure from outside the channel.
+     *
+     * Terminal for the run, so it is reserved for a loss that really is
+     * run-wide: a sink that cannot be written to, a host producer that has lost
+     * its ability to record anything further. A single record that could not be
+     * projected — a `json_schema.schema` holding a function, a content part no
+     * adapter names — is NOT this: it is the truncation case, and the provider
+     * path stubs that one record and keeps capturing. Calling `fail()` for it
+     * would throw away every later record in the run.
+     */
+    fail(reason: string): void;
+    /** Stop capturing for the rest of the run and remember why. */
+    private stop;
+    /**
+     * Enqueue one record. Synchronous and total: it returns immediately whatever
+     * the sink is doing, and it never throws into the provider call path.
+     */
+    write(record: CapturedRequestRecord): void;
+    /** Register (or upgrade) the ref an eval item will point at. */
+    noteOperation(ref: CapturedOperationRef & {
+        caseIndex?: number;
+        scorer?: string;
+    }): void;
+    /** Every operation this run captured, with the correlation it was seen under. */
+    operations(): Array<CapturedOperationRef & {
+        caseIndex?: number;
+        scorer?: string;
+    }>;
+    /**
+     * Wait for the queue to drain (bounded) and report the run's capture status.
+     *
+     * Called after the tracked function has already returned, so it can never
+     * delay a provider call. It is additionally bounded three ways: a stopped
+     * channel abandons its queue immediately, the queue itself is byte-bounded,
+     * and a flush timeout is the final backstop against a sink that never
+     * settles.
+     */
+    close(): Promise<RequestCaptureStatus>;
+}
+
 /**
  * Function exported from an eval module that overrides the default
  * `runtime.execute(workflow, input)` behavior. The runtime injects itself as
  * the second argument so user code can call `runtime.createContext()` etc.
  *
- * Returns `{ output, cost?, metadata? }` — cost and metadata are optional and
- * fall back to values derived from `runtime.trackExecution()` when omitted.
+ * Returns `{ output, cost?, metadata? }`. Both extras are optional and purely
+ * informational: since 0.24 the eval runner MEASURES spend on the accounting
+ * rail, so a `cost` reported here is recorded as a caller claim
+ * (`EvalItem.callerReport`) and never becomes a run total. Reserved diagnostic
+ * metadata keys (`models`, `tokens`, …) are likewise kept apart from the
+ * runtime's own.
  *
  * Single source of truth for the eval-execution contract; consumed by
  * `registerEval`, `getRegisteredEval`, the `axl-eval` CLI, and
@@ -4466,6 +5755,8 @@ type RuntimeEvalConfigShape = {
     scorerConcurrency?: number;
     budget?: string;
     failOnScorerErrorRate?: number;
+    /** Mirrors `EvalConfig.failOnItemErrorRate` (default `0.05`; `1` disables the gate). */
+    failOnItemErrorRate?: number;
     metadata?: Record<string, unknown>;
 };
 type CreateContextOptions = {
@@ -4483,6 +5774,143 @@ type CreateContextOptions = {
      *  'drop-oldest-non-terminal'`. */
     events?: EventStreamOptions;
 };
+/**
+ * Event-derived execution metadata returned by {@link AxlRuntime.trackExecution}
+ * and {@link AxlRuntime.trackOutcome}.
+ *
+ * Derived from trace events, so it follows trace configuration — unlike
+ * `Accounting`, which is independent of it.
+ */
+type TrackExecutionMetadata = {
+    /** Unique effective model URIs observed, in first-seen order. */
+    models: string[];
+    modelCallCounts?: Record<string, number>;
+    /**
+     * Agent token totals only — embedder tokens from semantic memory are a
+     * different category and are excluded. Read `Accounting.usage` for the
+     * folded, category-separated totals.
+     */
+    tokens: {
+        input: number;
+        output: number;
+        reasoning: number;
+    };
+    agentCalls: number;
+    /**
+     * Unique workflow names observed during execution, ordered by first
+     * appearance (outermost first for nested calls). Captured automatically
+     * from `workflow_start` trace events — callers don't need to declare
+     * anything. Parallel mechanism to `models`.
+     */
+    workflows: string[];
+    /** Call counts per workflow, if workflows.length > 0. */
+    workflowCallCounts?: Record<string, number>;
+};
+/**
+ * Per-model sums of `agent_call_end.timing`, keyed by the same effective
+ * model URI as `TrackExecutionMetadata.modelCallCounts`. Present only when at
+ * least one tracked call reported timing, so absence means "nothing was
+ * instrumented" rather than "everything took zero ms".
+ *
+ * `calls` counts the SUCCESSFUL timed calls only — it can be lower than the
+ * same model's `modelCallCounts` entry when a provider omits `timing` or a
+ * call failed. Divide a sum by `calls`, never by `modelCallCounts`.
+ *
+ * Failed calls are excluded even though they now report timing: a non-2xx
+ * response is a measured round trip, but a rollup blending answers with
+ * failures describes neither, and a fast 429 would improve a model's
+ * apparent latency. The failures stay on the events themselves.
+ *
+ * `firstTokenMs` is streaming-only and is summed across the calls that
+ * reported it; it is omitted entirely when no call did, so a non-streaming
+ * model never reports a misleading `0`. Its denominator is `firstTokenCalls`,
+ * NOT `calls` — the two travel together and are present or absent together,
+ * so a mixed streaming/non-streaming model still yields an exact mean.
+ *
+ * Sums are per-call totals, so `wireMs` across concurrent calls can exceed
+ * the wall clock of the tracked function — that is expected under fan-out and
+ * is why nothing in the core sums timing at the ask level.
+ */
+type ModelTimingRollup = Record<string, {
+    calls: number;
+    queuedMs: number;
+    retryMs: number;
+    wireMs: number;
+    firstTokenMs?: number;
+    /** Timed calls that reported a `firstTokenMs` — the denominator for it. */
+    firstTokenCalls?: number;
+    /**
+     * The per-call blocks the sums were built from, in event order.
+     * `length === calls`. Present only under `captureTimingSamples`, because
+     * retaining it is O(calls) in memory and the sums alone are O(models) — a
+     * caller that needs a real DISTRIBUTION (percentiles, min/max) cannot
+     * recover one from sums, and everyone else should not pay for it.
+     */
+    samples?: CallTiming[];
+}>;
+/** Options for {@link AxlRuntime.trackOutcome}. */
+type TrackOutcomeOptions = {
+    /**
+     * How this scope's operations are classified in `Accounting.breakdown`.
+     * Defaults to the enclosing scope's purpose, else `'generation'`.
+     */
+    purpose?: OperationPurpose;
+    /** Stop admitting new paid operations once known spend reaches its limit. */
+    admission?: AdmissionController;
+    /** Collect the raw `AxlEvent[]` observed during the call. */
+    captureTraces?: boolean;
+    /** Retain the per-call `CallTiming` blocks behind the `modelTiming` sums. */
+    captureTimingSamples?: boolean;
+    /**
+     * Opt in to bounded, redaction-aware capture of the provider-neutral REQUESTS
+     * this scope submits, written into `sink` as JSONL.
+     *
+     * Diagnostics only: capture can be truncated, fail outright, or be turned off
+     * entirely and `accounting` is byte-identical either way. The sink is never
+     * awaited by a provider call. Nested scopes inherit the enclosing channel, so
+     * declare it once at the outermost scope of a run.
+     *
+     * The CALLER owns the channel because the caller is the one that has to
+     * `close()` it and read back its operation ledger after the run.
+     */
+    capture?: RequestCaptureChannel;
+    /**
+     * Stamp consumer-side identity onto every record captured inside this scope
+     * (an eval's `caseIndex`, a judge's `scorer` name). Merged over the enclosing
+     * scope's correlation, so a scorer scope keeps its item's case index.
+     */
+    captureCorrelation?: CaptureCorrelation;
+};
+/** The result of {@link AxlRuntime.trackOutcome} — never a rejection. */
+type TrackedOutcome<T> = ({
+    status: 'fulfilled';
+    value: T;
+}
+/** The ORIGINAL thrown value: primitives and frozen objects are untouched. */
+ | {
+    status: 'rejected';
+    error: unknown;
+}) & {
+    /** Authoritative spend. Independent of trace level, capture and redaction. */
+    accounting: Accounting;
+    metadata: TrackExecutionMetadata;
+    modelTiming?: ModelTimingRollup;
+    traces?: AxlEvent[];
+};
+/** The result of {@link AxlRuntime.trackExecution}. */
+type TrackExecutionResult<T> = {
+    result: T;
+    /** Compatibility view of `accounting.knownCost`. */
+    cost: number;
+    /** Compatibility view of `accounting.completeness !== 'complete'`. When true,
+     *  `cost` is a LOWER BOUND. */
+    unpriced: boolean;
+    /** The authoritative record `cost` and `unpriced` are derived from. */
+    accounting: Accounting;
+    modelTiming?: ModelTimingRollup;
+    traces?: AxlEvent[];
+    metadata: TrackExecutionMetadata;
+};
 /**
  * The main entry point for executing Axl workflows.
  * Manages workflow registration, provider resolution, state storage, tracing, MCP servers,
@@ -4495,6 +5923,9 @@ declare class AxlRuntime extends EventEmitter {
     private tools;
     private agents;
     private providerRegistry;
+    /** Raw adapter → its scoped facade. Keyed weakly so a registry that drops an
+     *  adapter does not pin it here. */
+    private scopedProviders;
     private transcriptionProviderRegistry;
     private stateStore;
     private executions;
@@ -4547,7 +5978,181 @@ declare class AxlRuntime extends EventEmitter {
      *  The Set is mutated by the chain's own `.finally` so entries clear as
      *  soon as the work settles. */
     private persistInflight;
+    /** Resolved diagnostic artifact backend, when `diagnostics.artifacts` is set. */
+    private artifactStore?;
+    private artifactLeaseMs;
+    private artifactMaxHoldMs;
+    private artifactSweepTimer?;
+    /**
+     * Eval history ids this process has established are gone.
+     *
+     * Two jobs. It makes a delete started here beat a correction already in
+     * flight, which no store-side condition can do while the delete has not
+     * landed yet. And it keeps the lazy first load from merging a row back in
+     * from a snapshot taken before the eviction. Ids are minted per result and
+     * never reused, so an entry can only ever be right.
+     *
+     * Bounded like the artifact store's deleted-id window, and for the same
+     * reason: a long-lived server with TTL churn would otherwise grow it for the
+     * life of the process. Both jobs are windows measured in the length of one
+     * in-flight write or one lazy first load, so the oldest ids are the ones with
+     * nothing left to protect. Past the window the row is simply re-read from the
+     * store, which by then is the authority anyway.
+     */
+    private readonly deletedEvalIds;
+    /** Lease-renewal timers for artifacts currently being written, by id. */
+    private readonly artifactRenewals;
     constructor(config?: AxlConfig);
+    /**
+     * Resolve the artifact backend and arm reclamation.
+     *
+     * Two configuration errors are raised HERE rather than at capture time,
+     * because both mean "this deployment can never host managed capture" and the
+     * alternative is discovering it after an eval has already spent money:
+     * a `diagnostics.artifacts` block with neither `store` nor `root`, and a
+     * custom `StateStore` that cannot report eval retention.
+     */
+    private setUpDiagnosticArtifacts;
+    /** The configured artifact backend, or `undefined` when capture is off. */
+    getDiagnosticArtifactStore(): DiagnosticArtifactStore | undefined;
+    private requireArtifactStore;
+    /**
+     * Reserve an artifact for `owner` and hand back a sink to write records into.
+     *
+     * Throws `AxlError('DIAGNOSTICS_UNAVAILABLE')` BEFORE any work when capture is
+     * not configured, which is why `runEval` calls it ahead of loading the
+     * dataset. The returned sink renews the staging lease as it writes, so a long
+     * run is never swept out from under itself, while a run that dies leaves a
+     * lease that expires and is reclaimed.
+     */
+    stageDiagnosticArtifact(owner: ArtifactOwner): Promise<{
+        artifactId: string;
+        sink: RequestCaptureSink;
+    }>;
+    /**
+     * Hold a staged artifact's lease for as long as its writer lives, and hand
+     * back the sink that writer appends through.
+     *
+     * The lease belongs to the WRITER's lifetime, not to its write rate. Renewing
+     * from inside `append` looks equivalent and is not: a run that exhausts
+     * `maxRunBytes` at minute two stops appending forever, and a run waiting on a
+     * tool or a human approval may not call a provider for longer than a lease.
+     * Either way the sweeper would delete a live run's evidence, and the run
+     * would then fail to finalize the artifact it had been filling.
+     */
+    private holdStagedArtifact;
+    /** Stop renewing a lease once the writer is done with the artifact. */
+    private stopArtifactRenewal;
+    /** Seal a staged artifact's manifest. Called before the history row is saved. */
+    finalizeDiagnosticArtifact(artifactId: string, status: ArtifactStatus, reason?: string, redaction?: 'applied' | 'none'): Promise<ArtifactManifest>;
+    /** Discard a staged artifact whose owner will never be written. */
+    rollbackDiagnosticArtifact(artifactId: string): Promise<void>;
+    /**
+     * Copy a source run's artifact into a new owner (rescore provenance).
+     *
+     * Bounded by `maxBytes`; a partial copy reports `truncated` so the caller can
+     * finalize the new manifest honestly. Returns `undefined` when the source is
+     * gone — a rescore of a run whose artifact was deleted still produces numbers,
+     * it just reports its diagnostics as `unavailable`.
+     *
+     * The copy comes back STAGED and lease-held, with a sink: the new owner
+     * carries the source records forward AND keeps writing its own calls into the
+     * same artifact, which is what makes one rescore result hold both halves of
+     * its evidence.
+     */
+    copyDiagnosticArtifact(sourceId: string, owner: ArtifactOwner, opts: {
+        maxBytes: number;
+    }): Promise<{
+        artifactId: string;
+        truncated: boolean;
+        bytes: number;
+        /** What the SOURCE manifest said about the copied bytes. Never inferred. */
+        redaction: 'applied' | 'none';
+        sink: RequestCaptureSink;
+    } | undefined>;
+    /**
+     * Read a committed artifact's records, or `undefined`.
+     *
+     * Two logical checks stand between a caller and the bytes, because the bytes
+     * outlive the store that governs them: the owning history row must still
+     * exist, and the mirrored `expiresAt` must not have passed. A Redis row that
+     * aged out while this process was offline therefore reads as unavailable the
+     * moment it is asked for, not whenever the sweeper next runs.
+     */
+    openDiagnosticArtifact(artifactId: string): Promise<OpenedArtifact | undefined>;
+    /**
+     * Reclaim artifacts nothing can legitimately read any more.
+     *
+     * Removed: everything marked `delete_pending` (a delete that did not finish),
+     * every `committed` artifact whose owner row is gone or whose expiry has
+     * passed, and every `staged` artifact whose lease ran out. A staged artifact
+     * with a LIVE lease is never touched — that is an active writer, and sweeping
+     * it would race a run that is still producing evidence.
+     */
+    reconcileDiagnosticArtifacts(): Promise<{
+        removed: string[];
+    }>;
+    /**
+     * Rewrite the history row that owned an artifact the sweep has just removed.
+     *
+     * Best effort by design: reclaiming the bytes is the operation that had to
+     * succeed, and a state store that cannot take the correction must not turn a
+     * routine sweep into a throwing one. The next `saveEvalResult` or artifact
+     * read corrects the row anyway, because both already downgrade a dangling id.
+     */
+    private downgradeReclaimedOwner;
+    /**
+     * Write back a history row this process corrected in memory — but ONLY while
+     * the store still holds it.
+     *
+     * The history cache is process-global, loaded once and evicted only by
+     * `deleteEvalResult`. It therefore outlives whatever the STORE decided: a
+     * Redis TTL that elapsed, a delete by another process, a
+     * right-to-be-forgotten request. A blind `saveEvalResult` of a cached row
+     * resurrects all of it — item inputs, outputs and scores — and on Redis
+     * re-SETs it with a fresh full TTL window, silently extending the retention
+     * the operator configured. Correcting a row must never be able to un-delete
+     * one, so the store is asked first and the stale cache entry is dropped when
+     * the answer is no.
+     *
+     * A store with no retention view cannot answer, and a blind write is exactly
+     * what this exists to prevent, so nothing is written: the cache is corrected
+     * and the store keeps what it decided. In practice the question does not
+     * arise, because configuring artifacts at all requires `getEvalRetention`.
+     */
+    private persistCorrectedRow;
+    /**
+     * Drop a row from the history cache and refuse to re-add it.
+     *
+     * The cache is process-global and loaded once, so a row the STORE has
+     * dropped — expired, deleted here or elsewhere — would otherwise be served
+     * for the life of the process, and an in-flight first load whose snapshot
+     * predates the eviction would merge it straight back in.
+     */
+    private forgetEvalRow;
+    /** The artifact id an eval result carries, when it carries one. */
+    private artifactIdOf;
+    /**
+     * Rewrite an entry's diagnostics to say plainly that its evidence is gone.
+     *
+     * Mutates the entry in place on purpose: the caller usually holds the same
+     * `EvalResult` object it is about to return to a user, and a result that
+     * claims `complete` while storage has nothing is the failure being fixed.
+     * The dangling id is cleared too — `''` is the sentinel every lifecycle path
+     * already skips.
+     */
+    private downgradeDiagnostics;
+    /**
+     * The artifact id `ownerId` actually owns, or `undefined`.
+     *
+     * `diagnostics.artifactId` is data on a result object, and a result can carry
+     * an id that belongs to a DIFFERENT run — a rescore that degraded while
+     * naming its source, or an imported blob. Committing or deleting on the
+     * strength of that field alone lets one entry rewrite or destroy another
+     * entry's evidence, so ownership is confirmed against the manifest before
+     * any lifecycle write.
+     */
+    private ownedArtifactId;
     /**
      * Whether `config.trace.redact` is enabled on this runtime. A narrow
      * boolean getter is preferred over exposing the full config because:
@@ -4663,12 +6268,22 @@ declare class AxlRuntime extends EventEmitter {
         signal?: AbortSignal;
         /**
          * When `true`, populate `EvalItem.traces` on every item (success + failure
-         * paths). Forwards to `runEval({ captureTraces: true })`, which wraps each
-         * item's execution in `runtime.trackExecution({ captureTraces: true })`.
+         * paths). Forwards to `runEval({ captureTraces: true })`, which opens each
+         * item's accounting scope with `trackOutcome({ captureTraces: true })`.
          * Verbose-mode `agent_call_start.data.messages` snapshots are stripped from
          * captured traces to keep memory bounded.
          */
         captureTraces?: boolean;
+        /**
+         * Forwarded to `runEval({ captureRequests })`. Requires
+         * `config.diagnostics.artifacts`; without it the run fails fast with
+         * `AxlError('DIAGNOSTICS_UNAVAILABLE')` before any provider call.
+         */
+        captureRequests?: boolean | {
+            maxRecordBytes?: number;
+            maxRunBytes?: number;
+            maxQueueBytes?: number;
+        };
     }): Promise<unknown>;
     /** Get all execution info (running + completed + historical). */
     /** Normalize an execution loaded from a `StateStore` so the
@@ -4690,11 +6305,26 @@ declare class AxlRuntime extends EventEmitter {
     registerProvider(name: string, provider: Provider): void;
     /** Register a dedicated transcription adapter. It is never used for chat. */
     registerTranscriptionProvider(name: string, provider: TranscriptionProvider): void;
-    /** Resolve a provider:model URI to a Provider instance and model name. */
+    /**
+     * Resolve a `provider:model` URI to a provider and model name.
+     *
+     * **The returned provider is a scoped FACADE, not the registered instance.**
+     * It forwards everything to the adapter — custom properties and accessors,
+     * class private-field methods, property writes, capability methods, ordinary
+     * `instanceof` — while routing `chat`/`stream` through accounting and budget
+     * admission whenever a `trackOutcome` scope is active. Outside a scope it
+     * delegates verbatim.
+     *
+     * Identity is stable per runtime per adapter (repeated calls return the same
+     * facade), but `resolveProvider(uri).provider === registeredInstance` is now
+     * `false`. See `docs/migration/eval-accounting.md`.
+     */
     resolveProvider(uri: string): {
         provider: Provider;
         model: string;
     };
+    /** One facade per raw adapter per runtime, so repeated resolution is stable. */
+    private scopedProvider;
     /** Execute a workflow and return the result. */
     execute(name: string, input: unknown, options?: ExecuteOptions): Promise<unknown>;
     /** Execute a workflow and return a stream. */
@@ -4797,6 +6427,28 @@ declare class AxlRuntime extends EventEmitter {
     deleteEvalResult(id: string): Promise<boolean>;
     /** Get eval result history (most recent first). */
     getEvalHistory(): Promise<EvalHistoryEntry[]>;
+    /**
+     * One eval history entry by id, or `undefined`.
+     *
+     * A read that wants one entry should not have to materialize the whole
+     * history to find it. Studio's diagnostics routes resolve an artifact through
+     * a history id on every request, and `getEvalHistory()` copies the entire
+     * array — every result's full `data` blob — before the caller discards all
+     * but one of them.
+     *
+     * The lazy first load is still whole-history (that is how the cache is
+     * populated); what this avoids is paying for a copy of it per request.
+     *
+     * The row is confirmed against the store's retention view before it is
+     * served, and dropped when the store says it is gone. The cache outlives
+     * whatever the store decided — a Redis TTL that elapsed, a delete elsewhere —
+     * and this is the read a rescore resolves its SOURCE through, copying that
+     * row's items into a brand-new result with a brand-new retention window. An
+     * expired run could otherwise be republished indefinitely, one rescore at a
+     * time. `getEvalHistory()` is still served from the cache unconfirmed; the
+     * per-row check is affordable here because it is one row.
+     */
+    getEvalResult(id: string): Promise<EvalHistoryEntry | undefined>;
     /** List pending human decisions. */
     getPendingDecisions(): Promise<PendingDecision[]>;
     /** Resolve a pending human decision. */
@@ -4818,6 +6470,13 @@ declare class AxlRuntime extends EventEmitter {
         onProgress?: (event: EvalProgressEventShape) => void;
         signal?: AbortSignal;
         captureTraces?: boolean;
+        /** Forwarded to `runEval({ captureRequests })`. See
+         *  {@link AxlRuntime.runRegisteredEval}. */
+        captureRequests?: boolean | {
+            maxRecordBytes?: number;
+            maxRunBytes?: number;
+            maxQueueBytes?: number;
+        };
     }): Promise<unknown>;
     /**
      * Compare two evaluation results to detect regressions and improvements.
@@ -4839,26 +6498,55 @@ declare class AxlRuntime extends EventEmitter {
         unpriced: boolean;
     }>;
     /**
-     * Track cost and execution metadata across any runtime operations within the given function.
-     * Uses AsyncLocalStorage to scope attribution to specific execution IDs,
-     * making it correct with concurrent calls.
+     * Run `fn` and ALWAYS return its outcome plus the authoritative
+     * {@link Accounting} for everything paid that happened inside it.
+     *
+     * This is the accounting entry point. Unlike {@link trackExecution} it does
+     * not throw on failure — a workflow that threw after a paid call still
+     * returns that call's charge, which is what makes "what did the failed run
+     * cost?" answerable. The thrown value is handed back verbatim in `error`:
+     * primitives, frozen objects, `AbortError`, `ProviderError` and
+     * `BudgetExceededError` all come back `===` what was thrown.
+     *
+     * Scopes nest. An operation settled inside a child `trackOutcome` is counted
+     * exactly once in every enclosing scope, so a parent total is the sum of
+     * disjoint operations. Concurrent `trackOutcome` calls on one runtime are
+     * isolated: neither sees the other's operations, budget closure or spend.
+     *
+     * Pass `{ admission: new AdmissionController({ limit }) }` to stop admitting
+     * new paid operations once known spend reaches the limit. Already-dispatched
+     * work still settles and is still counted.
+     *
+     * `metadata`, `modelTiming` and `traces` remain EVENT-derived and therefore
+     * depend on trace configuration; `accounting` never does.
+     */
+    trackOutcome<T>(fn: () => Promise<T>, options?: TrackOutcomeOptions): Promise<TrackedOutcome<T>>;
+    /**
+     * Throwing compatibility wrapper over {@link trackOutcome}.
+     *
+     * Returns the same shape it always has, now derived from the accounting rail
+     * rather than summed from trace events: `cost` is `accounting.knownCost` and
+     * `unpriced` is `accounting.completeness !== 'complete'`. For instrumented
+     * paths the numbers are identical; they differ only where the trace rail used
+     * to lose a charge (notably a leaf that never settled). `accounting` is
+     * exposed alongside them so callers can migrate incrementally.
      *
-     * Returns cost (same as `trackCost`) plus metadata extracted from trace events:
-     * models (unique URIs), tokens (input/output/reasoning sums), and agent call count.
+     * On failure it rethrows the ORIGINAL error and, under `captureTraces`,
+     * attaches the non-enumerable `axlCapturedTraces` side channel — prefer
+     * {@link trackOutcome}, which returns the accounting for a failed run too.
      *
      * ## Cost vs tokens semantics
      *
-     * - `cost` is the full aggregate across EVERY event with a top-level
-     *   `event.cost` set: agent calls, tool calls, semantic memory ops, etc.
-     *   This is the number to reconcile against your provider bill.
+     * - `cost` covers EVERY settled operation: agent calls, tool calls, semantic
+     *   memory embeddings, transcriptions, declared external work. This is the
+     *   number to reconcile against your provider bill.
      *
      * - `metadata.tokens` is narrowly scoped to **agent** prompt/completion/
      *   reasoning tokens. Embedder tokens from semantic `ctx.remember({embed:true})`
      *   / `ctx.recall({query})` are deliberately NOT summed here — they're a
      *   different category (input-only, different pricing, different model).
-     *   Conflating them would make "prompt tokens" misleading in the UI. If you
-     *   need embedder token counts, subscribe to `runtime.on('trace', ...)` and
-     *   read `data.usage.tokens` on `memory_remember` / `memory_recall` events.
+     *   Conflating them would make "prompt tokens" misleading in the UI. Read
+     *   `accounting.usage` for the folded, category-separated totals.
      *
      * Pass `{ captureTraces: true }` to also collect the raw `AxlEvent[]` observed
      * during `fn()`. This is opt-in because it keeps every event in memory for the
@@ -4873,86 +6561,7 @@ declare class AxlRuntime extends EventEmitter {
     trackExecution<T>(fn: () => Promise<T>, options?: {
         captureTraces?: boolean;
         captureTimingSamples?: boolean;
-    }): Promise<{
-        result: T;
-        cost: number;
-        /** True when any tracked call was unpriced — `cost` is then a LOWER BOUND.
-         *  Aggregate counterpart of `ExecutionInfo.unpriced`, via `isUnpricedLeaf`. */
-        unpriced: boolean;
-        /**
-         * Per-model sums of `agent_call_end.timing`, keyed by the same effective
-         * model URI as `metadata.modelCallCounts`. Present only when at least one
-         * tracked call reported timing, so absence means "nothing was instrumented"
-         * rather than "everything took zero ms".
-         *
-         * `calls` counts the SUCCESSFUL timed calls only — it can be lower than the
-         * same model's `modelCallCounts` entry when a provider omits `timing` or a
-         * call failed. Divide a sum by `calls`, never by `modelCallCounts`.
-         *
-         * Failed calls are excluded even though they now report timing: a non-2xx
-         * response is a measured round trip, but a rollup blending answers with
-         * failures describes neither, and a fast 429 would improve a model's
-         * apparent latency. The failures stay on the events themselves.
-         *
-         * `firstTokenMs` is streaming-only and is summed across the calls that
-         * reported it; it is omitted entirely when no call did, so a non-streaming
-         * model never reports a misleading `0`. Its denominator is `firstTokenCalls`,
-         * NOT `calls` — the two travel together and are present or absent together,
-         * so a mixed streaming/non-streaming model still yields an exact mean.
-         *
-         * Sums are per-call totals, so `wireMs` across concurrent calls can exceed
-         * the wall clock of `fn` — that is expected under fan-out and is why
-         * nothing in the core sums timing at the ask level.
-         *
-         * `samples` carries the raw per-call `CallTiming` blocks behind the sums, in
-         * `agent_call_end` order, so a caller that needs a DISTRIBUTION (percentiles,
-         * min/max) rather than a mean can compute one over real per-call values. It
-         * is the same data the sums were built from — `samples.length === calls` —
-         * and is deliberately not something callers should persist per item: the
-         * sums are the compact form, `samples` is the working form.
-         *
-         * It is **opt-in** via `captureTimingSamples` and the key is absent
-         * otherwise. Retaining it is O(calls) in memory for the lifetime of `fn`,
-         * which no caller should pay for a figure it never reads — the sums alone
-         * are O(models).
-         */
-        modelTiming?: Record<string, {
-            calls: number;
-            queuedMs: number;
-            retryMs: number;
-            wireMs: number;
-            firstTokenMs?: number;
-            /** Timed calls that reported a `firstTokenMs` — the denominator for it. */
-            firstTokenCalls?: number;
-            /** The per-call blocks the sums were built from, in event order.
-             *  `length === calls`. Present only under `captureTimingSamples`. */
-            samples?: CallTiming[];
-        }>;
-        traces?: AxlEvent[];
-        metadata: {
-            models: string[];
-            modelCallCounts?: Record<string, number>;
-            /**
-             * Agent token totals only — does not include embedder tokens from
-             * semantic memory operations. See the method-level JSDoc above.
-             */
-            tokens: {
-                input: number;
-                output: number;
-                reasoning: number;
-            };
-            agentCalls: number;
-            /**
-             * Unique workflow names observed during execution, ordered by first
-             * appearance (outermost first for nested calls). Captured automatically
-             * from `workflow_start` trace events — callers don't need to declare
-             * anything. Parallel mechanism to `models`.
-             */
-            workflows: string[];
-            /** Call counts per workflow, if workflows.length > 0. */
-            workflowCallCounts?: Record<string, number>;
-        };
-    }>;
+    }): Promise<TrackExecutionResult<T>>;
     /** Register an execution ID with the active cost scope for trackCost() attribution. */
     private registerWithCostScope;
     /**
@@ -5583,6 +7192,26 @@ declare const REDACTION_RULES: {
 declare function redactEvent(event: AxlEvent): AxlEvent;
 /** Redact either persisted schema without reinterpreting its lifecycle. */
 declare function redactHistoricalEvent(event: HistoricalAxlEvent): HistoricalAxlEvent;
+/**
+ * Scrub a captured request record before it reaches a diagnostics sink.
+ *
+ * The same policy `agent_call_start` / `agent_call_end` / the gate events
+ * already apply, expressed over the capture record's shape: prompts, responses,
+ * gate reasons and correction text are user/LLM content and become
+ * `[redacted]`; roles, tool NAMES, JSON-Schema parameters, option scalars,
+ * usage, cost, timing and the `providerOptions` key list are structural and
+ * survive, because a compliance-mode reader still has to be able to tell a
+ * tool-choice bug from a token-budget bug.
+ *
+ * Rich media never had bytes in the record to begin with (the projection in
+ * `diagnostics/capture.ts` replaces them with descriptors), but a descriptor's
+ * `locator` and `label` can name a file or a URL, so they are scrubbed here
+ * exactly as `redactInputDescriptor` scrubs them on the trace rail.
+ *
+ * Pure, like every other rule in this file: the caller decides whether
+ * redaction is on, and this function unconditionally scrubs when called.
+ */
+declare function redactCapturedRequest(record: CapturedRequestRecord): CapturedRequestRecord;
 
 /**
  * Typed provider errors + shared HTTP-failure classification.
@@ -5734,13 +7363,20 @@ declare class OpenAIResponsesProvider implements Provider {
     nativeStructuredOutputSupport(): 'schema';
     private baseUrl;
     private apiKeySource;
-    private governor?;
+    /**
+     * Namespaced so it cannot collide with a member a downstream subclass
+     * declares. A plain property (not `#private` or a WeakMap keyed by `this`)
+     * so a caller's own Proxy around the adapter still reaches it.
+     */
+    private readonly axlRateGovernors;
     constructor(options?: {
         apiKey?: ApiKeySource;
         baseUrl?: string;
         dangerouslyAllowInsecureHttp?: boolean;
         rateLimit?: RateLimitConfig;
     });
+    /** The rate governor for one call to `model`, from the runtime's per-scope pool. */
+    protected governorFor(model: string): ScopeGovernor;
     /** Resolve the API key for one request (supports an expiring-token callback). */
     private resolveKey;
     /** Build request headers from a resolved key (used by both chat and stream). */
@@ -5802,13 +7438,20 @@ declare class AnthropicProvider implements Provider {
     nativeStructuredOutputSupport(): 'unsupported';
     private baseUrl;
     private apiKeySource;
-    private governor?;
+    /**
+     * Namespaced so it cannot collide with a member a downstream subclass
+     * declares. A plain property (not `#private` or a WeakMap keyed by `this`)
+     * so a caller's own Proxy around the adapter still reaches it.
+     */
+    private readonly axlRateGovernors;
     constructor(options?: {
         apiKey?: ApiKeySource;
         baseUrl?: string;
         dangerouslyAllowInsecureHttp?: boolean;
         rateLimit?: RateLimitConfig;
     });
+    /** The rate governor for one call to `model`, from the runtime's per-scope pool. */
+    protected governorFor(model: string): ScopeGovernor;
     /** Resolve the API key for one request (supports an expiring-token callback). */
     private resolveKey;
     chat(messages: ChatMessage[], options: ChatOptions): Promise<ProviderResponse>;
@@ -5882,13 +7525,20 @@ declare class GeminiProvider implements Provider {
     private baseUrl;
     private apiKeySource;
     private callCounter;
-    private governor?;
+    /**
+     * Namespaced so it cannot collide with a member a downstream subclass
+     * declares. A plain property (not `#private` or a WeakMap keyed by `this`)
+     * so a caller's own Proxy around the adapter still reaches it.
+     */
+    private readonly axlRateGovernors;
     constructor(options?: {
         apiKey?: ApiKeySource;
         baseUrl?: string;
         dangerouslyAllowInsecureHttp?: boolean;
         rateLimit?: RateLimitConfig;
     });
+    /** The rate governor for one call to `model`, from the runtime's per-scope pool. */
+    protected governorFor(model: string): ScopeGovernor;
     /** Resolve the API key for one request (supports an expiring-token callback). */
     private resolveKey;
     chat(messages: ChatMessage[], options: ChatOptions): Promise<ProviderResponse>;
@@ -6187,8 +7837,15 @@ declare class MemoryStore implements StateStore {
     listExecutions(limit?: number): Promise<HistoricalExecutionInfo[]>;
     deleteExecution(executionId: string): Promise<boolean>;
     saveEvalResult(entry: EvalHistoryEntry): Promise<void>;
+    /** Update-only write: see `StateStore.updateEvalResult`. */
+    updateEvalResult(entry: EvalHistoryEntry): Promise<boolean>;
     listEvalResults(limit?: number): Promise<EvalHistoryEntry[]>;
     deleteEvalResult(id: string): Promise<boolean>;
+    /** In-memory history never expires on its own — only existence is meaningful. */
+    getEvalRetention(id: string): Promise<{
+        exists: boolean;
+        expiresAt?: number;
+    }>;
     listSessions(): Promise<string[]>;
     private streamingEvents;
     appendStreamingEvents(executionId: string, events: AxlEvent[]): Promise<void>;
@@ -6275,8 +7932,20 @@ declare class SQLiteStore implements StateStore {
     listExecutions(limit?: number): Promise<HistoricalExecutionInfo[]>;
     deleteExecution(executionId: string): Promise<boolean>;
     saveEvalResult(entry: EvalHistoryEntry): Promise<void>;
+    /**
+     * Update-only write: see `StateStore.updateEvalResult`. `UPDATE ... WHERE id`
+     * touches nothing when the row is gone, where `INSERT OR REPLACE` would
+     * resurrect it — and SQLite history has no expiry, so a resurrection here is
+     * permanent.
+     */
+    updateEvalResult(entry: EvalHistoryEntry): Promise<boolean>;
     listEvalResults(limit?: number): Promise<EvalHistoryEntry[]>;
     deleteEvalResult(id: string): Promise<boolean>;
+    /** SQLite history has no automatic expiry — only existence is meaningful. */
+    getEvalRetention(id: string): Promise<{
+        exists: boolean;
+        expiresAt?: number;
+    }>;
     listSessions(): Promise<string[]>;
     saveMemory(scope: string, key: string, value: unknown): Promise<void>;
     getMemory(scope: string, key: string): Promise<unknown | null>;
@@ -6505,9 +8174,70 @@ declare class RedisStore implements StateStore {
     getExecution(executionId: string): Promise<HistoricalExecutionInfo | null>;
     listExecutions(limit?: number): Promise<HistoricalExecutionInfo[]>;
     deleteExecution(executionId: string): Promise<boolean>;
+    /**
+     * Write an eval history row.
+     *
+     * **Re-saving an existing eval result never extends its retention.** Only a
+     * genuinely new key gets the configured window; an existing one keeps the
+     * time it had left. A result is re-saved by corrections that have nothing to
+     * do with the operator's retention policy — the diagnostics sweep rewriting a
+     * row whose artifact it just reclaimed, a commit failure downgrading one —
+     * and a plain `SET ... EX` would renew a full window on every one of them,
+     * silently keeping item inputs, outputs and scores alive indefinitely on a
+     * server that corrects rows often enough.
+     *
+     * The remaining window is read with `PTTL` and re-applied as `PX` rather than
+     * using `KEEPTTL`. Both need an existence check the SET cannot share a
+     * transaction with, so both race a key expiring in between — but the failure
+     * modes differ, and only one is safe: `KEEPTTL` on a key that expired in the
+     * gap recreates it with NO expiry at all, an immortal row holding exactly the
+     * data retention exists to age out. Every `PX` branch leaves a bounded
+     * lifetime, so the race costs at most one window's length, never the window
+     * itself. It also carries no Redis version floor, where `KEEPTTL` needs 6.0.
+     *
+     * The index entries carry no TTL and age out lazily, as with `saveExecution`.
+     */
     saveEvalResult(entry: EvalHistoryEntry): Promise<void>;
+    /**
+     * Update-only write: see `StateStore.updateEvalResult`.
+     *
+     * One `SET key value XX KEEPTTL`, which is atomic and therefore has no
+     * check-then-write window at all: `XX` refuses a key that is not there, so a
+     * delete or an expiry racing the correction wins, and `KEEPTTL` leaves the
+     * remaining lifetime untouched, so the correction carries no retention
+     * decision of its own.
+     *
+     * **Requires Redis 6.0 or newer** (`KEEPTTL`). An older server rejects the
+     * option with a syntax error, which is translated into a
+     * `REDIS_VERSION_UNSUPPORTED` {@link AxlError} naming the floor — a
+     * misconfiguration, not a failed write, and the one thing in `RedisStore`
+     * that needs 6.0. Silently resetting the retention window instead is the one
+     * outcome this write exists to rule out.
+     *
+     * The index members are deliberately not re-added: the row already exists, so
+     * they are already there, and writing them for a key that vanished is exactly
+     * the resurrection this avoids.
+     */
+    updateEvalResult(entry: EvalHistoryEntry): Promise<boolean>;
     listEvalResults(limit?: number): Promise<EvalHistoryEntry[]>;
     deleteEvalResult(id: string): Promise<boolean>;
+    /**
+     * Existence + absolute expiry for one eval history row.
+     *
+     * `PTTL` is the authority here rather than the configured `ttls.evalHistory`:
+     * the row may have been written under a different configuration, re-saved, or
+     * had its TTL cleared out of band, and an artifact swept on a stale
+     * assumption is deleted diagnostic evidence the user still owns.
+     *
+     * Redis expires the row server-side without telling anyone, so the absolute
+     * `expiresAt` returned here is mirrored onto the artifact manifest and the
+     * physical bytes are reclaimed by the next sweep (or by startup reconciliation
+     * if the process was down when the key aged out) — eventual, not synchronous.
+     */
+    getEvalRetention(id: string): Promise<{
+        exists: boolean;
+        expiresAt?: number;
+    }>;
     /**
      * Shared list-by-sorted-set implementation. Uses ZREVRANGEBYSCORE +
      * MGET when the ZSET is populated (post-migration). Falls back to the
@@ -6521,7 +8251,15 @@ declare class RedisStore implements StateStore {
     finalizeStreamingEvents(executionId: string): Promise<void>;
     listStreamingExecutions(): Promise<string[]>;
     getStreamingEvents(executionId: string): Promise<HistoricalAxlEvent[]>;
-    /** Close the Redis connection. */
+    /**
+     * Close the Redis connection.
+     *
+     * Idempotent: `runtime.shutdown()` closes the state store it was handed, so
+     * a caller that also closes its own store is doing the ordinary thing and
+     * must not get a rejected promise for it. `MemoryStore.close()` and
+     * better-sqlite3's `close()` are both no-ops the second time; node-redis
+     * instead rejects with "The client is closed", so absorb that here.
+     */
     close(): Promise<void>;
     deleteCheckpoints(executionId: string): Promise<void>;
 }
@@ -6593,4 +8331,4 @@ declare class NoopSpanManager implements SpanManager {
  */
 declare function createSpanManager(config?: TelemetryConfig): Promise<SpanManager>;
 
-export { AXL_EVENT_TYPES, AXL_EVENT_TYPES_V2, AXL_TOOL_LIFECYCLE_TYPES_V2, AZURE_PROFILE, type Agent, type AgentCallEndData, type AgentCallInfo, type AgentCallParams, type AgentCallStartData, type AgentConfig, AnthropicProvider, type AnyWorkflow, type ApiKeySource, type AskOptions, type AskScoped, type AuthHeader, type AwaitHumanData, type AwaitHumanOptions, type AwaitHumanResolvedData, type AxlConfig, AxlError, type AxlEvent, type AxlEventBase, AxlEventBus, type AxlEventOf, type AxlEventType, type AxlEventV2, type AxlEventV2Of, AxlRuntime, AxlStream, BEDROCK_PROFILE, BUILTIN_PROFILES, BudgetExceededError, type BudgetOptions, type BudgetResult, CONFIG_CANDIDATES, COST_BEARING_LEAF_TYPES, type CallTiming, type CapabilityFlags, type ChatMessage, type ChatOptions, type CheckpointEventData, type CoalescedPartialObject, type CreateContextOptions, DEEPSEEK_PROFILE, type DecisionCleanupFailedEvent, type DelegateData, type DelegateOptions, type Effort, type EffortResolution, type EmbedResult, type EmbedUsage, type Embedder, type EvalExecuteWorkflow, type EvalHistoryEntry, type EventStreamOptions, EventStreamOverflowError, type ExecuteOptions, type ExecutionInfo, type ExecutionInfoV1, type ExecutionInfoV2, type ExecutionState, GROQ_PROFILE, GeminiProvider, GeminiTranscriptionProvider, type GuardrailBlockHandler, type GuardrailData, GuardrailError, type GuardrailResult, type GuardrailsConfig, type HandoffDescriptor, type HandoffRecord, type HandoffReturnData, type HandoffStartData, type HistoricalAxlEvent, type HistoricalExecutionInfo, type HumanDecision, InMemoryVectorStore, type InputAudioPart, type InputContentPart, type InputGuardrail, type InputImagePart, type InputMediaSource, type InputModalitySupport, type InputTextPart, InvalidModelInputError, InvalidTranscriptionInputError, LLAMACPP_PROFILE, LMSTUDIO_PROFILE, type LegacyAxlEventV1, type LegacyExecutionInfoV1, MAX_INLINE_MODEL_INPUT_BYTES, MAX_INLINE_TRANSCRIPTION_BYTES, MISTRAL_PROFILE, type MapOptions, MaxTurnsError, McpManager, type McpServer, type McpServerConfig, type McpToolDefinition, type McpToolResult, type MemoryConfig, type MemoryEventData, MemoryManager, MemoryStore, type ModelInput, type ModelInputDescriptor, NoConsensus, NoopSpanManager, OLLAMA_PROFILE, OPENAI_PRICING, OPENAI_PROFILE, OPENROUTER_PROFILE, type ObservationStatus, type OpenAICompatibleOptions, OpenAICompatibleProvider, OpenAIEmbedder, OpenAIProvider, OpenAIResponsesProvider, OpenAITranscriptionProvider, OpenRouterTranscriptionProvider, type OutputGuardrail, type OutputValidator, type PendingDecision, type PerModel, type PricingSource, type PricingTable, type ProfileInputModalities, type Provider, type ProviderAdapter, type ProviderDiagnosticData, ProviderError, type ProviderInputValidationRequest, type ProviderInputValidationResult, type ProviderProfile, ProviderRegistry, type ProviderResponse, QuorumNotMet, REDACTED, REDACTION_RULES, type RaceOptions, type RateLimitConfig, RateLimiter, type ReasoningCapture, type ReasoningEmit, type ReasoningProfile, type ReasoningRoundTrip, type RecallOptions, type RecallResult, type RecordedAudioSource, RedisStore, type RememberOptions, type RememberResult, type ResolvedThinkingOptions, type Result, type RetryFeedbackHook, type RetryFeedbackInfo, type RetryFeedbackResult, type RetryPolicy, SGLANG_PROFILE, SQLiteStore, type SchemaCheckData, type SchemaDiagnosticData, type SchemaPromptOption, Session, type SessionOptions, type SpanHandle, type SpanManager, type SpawnOptions, SqliteVectorStore, StallTimeoutError, type StateStore, type StreamChunk, type StringDeltaData, type StringStreamEvent, type StringStreamFilter, type TelemetryConfig, ThinkTagScanner, type TimeoutBreakdown, TimeoutError, type Tool, type ToolApprovalData, type ToolArgumentIssue, type ToolCallCancellation, type ToolCallData, type ToolCallEndData, type ToolCallFailure, type ToolCallMessage, type ToolCallOutcome, type ToolCallRejectedData, type ToolCallRejectedEvent, type ToolCallStartData, type ToolCallStartDataV2, type ToolChoice, type ToolConfig, type ToolDeniedData, type ToolEventError, ToolFailure, type ToolFailureConstructor, type ToolFailureOptions, type ToolHooks, type ToolLifecycleEventV2, type ToolModelOutput, ToolModelOutputError, type Transcript, type TranscriptionCapabilities, TranscriptionOperationError, type TranscriptionProvider, TranscriptionProviderRegistry, type TranscriptionProviderRequest, type TranscriptionProviderResult, type TranscriptionRequest, UnsupportedEventSchemaVersionError, UnsupportedModelInputError, UnsupportedTranscriptionInputError, VLLM_PROFILE, type ValidateData, type ValidateResult, ValidationError, type VectorEntry, type VectorResult, type VectorStore, type VerifyData, VerifyError, type VerifyOptions, type VerifyRetry, type VoteOptions, type Workflow, type WorkflowConfig, WorkflowContext, type WorkflowContextInit, type WorkflowEndData, type WorkflowStartData, XAI_PROFILE, agent, createSpanManager, defineConfig, estimateOpenAICost, eventCostContribution, expandGlob, extractJson, extractThinkTags, findConfig, getEventSchemaVersion, getExecutionEventSchemaVersion, hasPositiveBillableWork, hasPositiveTokens, importModule, inputText, isCostBearingLeaf, isRetryableStatus, isRootLevel, isUnpricedLeaf, isUsableCost, needsTsxLoader, normalizeStoredExecution, openaiReasoningEmit, parsePartialJson, pickDefault, pickExport, priceFromTable, reasoningEffortEmit, reasoningObjectEmit, redactEvent, redactHistoricalEvent, registerConditions, resolveApiKey, resolvePerModel, resolveRuntime, resolveThinkingOptions, stringStreamFromEvents, summarizeModelInput, tool, workflow, zodToJsonSchema };
+export { AXL_EVENT_TYPES, AXL_EVENT_TYPES_V2, AXL_TOOL_LIFECYCLE_TYPES_V2, AZURE_PROFILE, type Accounting, type AccountingCompleteness, type AccountingReason, type AccountingUsage, AdmissionController, AdmissionDeniedError, type Agent, type AgentCallEndData, type AgentCallInfo, type AgentCallParams, type AgentCallStartData, type AgentConfig, AnthropicProvider, type AnyWorkflow, type ApiKeySource, type ArtifactManifest, type ArtifactOwner, type ArtifactStatus, type ArtifactWriteResult, type AskOptions, type AskScoped, type AuthHeader, type AwaitHumanData, type AwaitHumanOptions, type AwaitHumanResolvedData, type AxlConfig, AxlError, type AxlEvent, type AxlEventBase, AxlEventBus, type AxlEventOf, type AxlEventType, type AxlEventV2, type AxlEventV2Of, AxlRuntime, AxlStream, BEDROCK_PROFILE, BUILTIN_PROFILES, BudgetExceededError, type BudgetOptions, type BudgetResult, CONFIG_CANDIDATES, COST_BEARING_LEAF_TYPES, type CallTiming, type CapabilityFlags, type CaptureCorrelation, type CapturedCorrection, type CapturedError, type CapturedMessage, type CapturedOperationRef, type CapturedPhase, type CapturedRequest, type CapturedRequestRecord, type CapturedResponse, type ChatMessage, type ChatOptions, type CheckpointEventData, type CoalescedPartialObject, type CostProvenance, type CreateContextOptions, DEEPSEEK_PROFILE, DEFAULT_MAX_QUEUE_BYTES, DEFAULT_MAX_RECORD_BYTES, DEFAULT_MAX_RUN_BYTES, type DecisionCleanupFailedEvent, type DelegateData, type DelegateOptions, type DiagnosticArtifactStore, type DiagnosticArtifactsConfig, type DiagnosticsConfig, type DispatchAdmission, type Effort, type EffortResolution, type EmbedResult, type EmbedUsage, type Embedder, type EvalExecuteWorkflow, type EvalHistoryEntry, type EvalProgressEventShape, type EventStreamOptions, EventStreamOverflowError, type ExecuteOptions, type ExecutionInfo, type ExecutionInfoV1, type ExecutionInfoV2, type ExecutionState, type ExternalOperationDescriptor, type ExternalOperationReport, FileDiagnosticArtifactStore, GROQ_PROFILE, GeminiProvider, GeminiTranscriptionProvider, type GuardrailBlockHandler, type GuardrailData, GuardrailError, type GuardrailResult, type GuardrailsConfig, type HandoffDescriptor, type HandoffRecord, type HandoffReturnData, type HandoffStartData, type HistoricalAxlEvent, type HistoricalExecutionInfo, type HumanDecision, InMemoryVectorStore, type InputAudioPart, type InputContentPart, type InputGuardrail, type InputImagePart, type InputMediaSource, type InputModalitySupport, type InputTextPart, InvalidModelInputError, InvalidTranscriptionInputError, LLAMACPP_PROFILE, LMSTUDIO_PROFILE, type LegacyAxlEventV1, type LegacyExecutionInfoV1, MAX_INLINE_MODEL_INPUT_BYTES, MAX_INLINE_TRANSCRIPTION_BYTES, MISTRAL_PROFILE, type MapOptions, MaxTurnsError, McpManager, type McpServer, type McpServerConfig, type McpToolDefinition, type McpToolResult, type MemoryConfig, type MemoryEventData, MemoryManager, MemoryStore, type ModelInput, type ModelInputDescriptor, type ModelTimingRollup, NoConsensus, NoopSpanManager, OLLAMA_PROFILE, OPENAI_PRICING, OPENAI_PROFILE, OPENROUTER_PROFILE, type ObservationStatus, type OpenAICompatibleOptions, OpenAICompatibleProvider, OpenAIEmbedder, OpenAIProvider, OpenAIResponsesProvider, OpenAITranscriptionProvider, OpenRouterTranscriptionProvider, type OpenedArtifact, type OperationKind, type OperationPurpose, type OutputGuardrail, type OutputValidator, type PendingDecision, type PerModel, type PricingSource, type PricingTable, type ProfileInputModalities, type Provider, type ProviderAdapter, type ProviderDiagnosticData, ProviderError, type ProviderInputValidationRequest, type ProviderInputValidationResult, type ProviderProfile, ProviderRegistry, type ProviderResponse, QuorumNotMet, REDACTED, REDACTION_RULES, type RaceOptions, type RateLimitConfig, RateLimiter, type ReasoningCapture, type ReasoningEmit, type ReasoningProfile, type ReasoningRoundTrip, type RecallOptions, type RecallResult, type RecordedAudioSource, RedisStore, type RememberOptions, type RememberResult, RequestCaptureChannel, type RequestCaptureOptions, type RequestCaptureSink, type RequestCaptureStatus, type ResolvedThinkingOptions, type Result, type RetryFeedbackHook, type RetryFeedbackInfo, type RetryFeedbackResult, type RetryPolicy, type RuntimeEvalConfigShape, SGLANG_PROFILE, SQLiteStore, type SchemaCheckData, type SchemaDiagnosticData, type SchemaPromptOption, Session, type SessionOptions, type SpanHandle, type SpanManager, type SpawnOptions, SqliteVectorStore, type StagedArtifact, StallTimeoutError, type StateStore, type StreamChunk, type StringDeltaData, type StringStreamEvent, type StringStreamFilter, type TelemetryConfig, ThinkTagScanner, type TimeoutBreakdown, TimeoutError, type Tool, type ToolApprovalData, type ToolArgumentIssue, type ToolCallCancellation, type ToolCallData, type ToolCallEndData, type ToolCallFailure, type ToolCallMessage, type ToolCallOutcome, type ToolCallRejectedData, type ToolCallRejectedEvent, type ToolCallStartData, type ToolCallStartDataV2, type ToolChoice, type ToolConfig, type ToolDeniedData, type ToolEventError, ToolFailure, type ToolFailureConstructor, type ToolFailureOptions, type ToolHooks, type ToolLifecycleEventV2, type ToolModelOutput, ToolModelOutputError, type TrackExecutionMetadata, type TrackExecutionResult, type TrackOutcomeOptions, type TrackedOutcome, type Transcript, type TranscriptionCapabilities, TranscriptionOperationError, type TranscriptionProvider, TranscriptionProviderRegistry, type TranscriptionProviderRequest, type TranscriptionProviderResult, type TranscriptionRequest, UnsupportedEventSchemaVersionError, UnsupportedModelInputError, UnsupportedTranscriptionInputError, VLLM_PROFILE, type ValidateData, type ValidateResult, ValidationError, type VectorEntry, type VectorResult, type VectorStore, type VerifyData, VerifyError, type VerifyOptions, type VerifyRetry, type VoteOptions, type Workflow, type WorkflowConfig, WorkflowContext, type WorkflowContextInit, type WorkflowEndData, type WorkflowStartData, XAI_PROFILE, agent, createSpanManager, defineConfig, estimateOpenAICost, eventCostContribution, expandGlob, externalOperation, extractJson, extractThinkTags, findConfig, getEventSchemaVersion, getExecutionEventSchemaVersion, hasPositiveBillableWork, hasPositiveTokens, importModule, inputText, isAdmissionDeniedError, isCostBearingLeaf, isRetryableStatus, isRootLevel, isUnpricedLeaf, isUsableCost, needsTsxLoader, normalizeStoredExecution, openaiReasoningEmit, parsePartialJson, pickDefault, pickExport, priceFromTable, reasoningEffortEmit, reasoningObjectEmit, redactCapturedRequest, redactEvent, redactHistoricalEvent, registerConditions, resolveApiKey, resolvePerModel, resolveRuntime, resolveThinkingOptions, stringStreamFromEvents, summarizeModelInput, tool, workflow, zodToJsonSchema };