modelrig 0.1.0 → 0.2.0

package/dist/adapters/openai.js

@@ -22,6 +22,9 @@ exports.classifyOpenAIFailure = classifyOpenAIFailure;
 exports.buildOpenAIParams = buildOpenAIParams;
 exports.createOpenAIAdapter = createOpenAIAdapter;
 const openai_1 = __importDefault(require("openai"));
+const tool_mapping_1 = require("./tool-mapping");
+const openai_stream_1 = require("./openai-stream");
+const sampling_1 = require("./sampling");
 /** OpenAI's documented flex-eligible allowlist as of 2026-05 (ported).
  * Mini and nano variants are silently downgraded to default tier. */
 const FLEX_ELIGIBLE_PREFIXES = ["gpt-5.4", "gpt-5.2", "gpt-5.1", "gpt-5", "gpt-4.1"];
@@ -44,6 +47,7 @@ function openaiSupports(feature, model) {
         case "grounded_native":
         case "context_cache_explicit":
         case "trace_visible": // reasoning tokens are billed but never exposed
+        case "zero_retention": // never a static adapter attestation — set only from the credential-scoped registry facts (claims.ts)
             return false;
     }
 }
@@ -77,10 +81,11 @@ function buildOpenAIParams(model, req) {
     ];
     return {
         model,
-        max_completion_tokens: req.maxOutputTokens ?? DEFAULT_MAX_COMPLETION_TOKENS,
+        max_completion_tokens: (0, sampling_1.effectiveMaxOutputTokens)(req, DEFAULT_MAX_COMPLETION_TOKENS),
         messages,
         stream: true,
         stream_options: { include_usage: true },
+        ...(0, sampling_1.openAISamplingFields)(req),
         ...(req.requestedTier === "flex"
             ? { service_tier: "flex" }
             : req.requestedTier === "priority"
@@ -105,6 +110,14 @@ function buildOpenAIParams(model, req) {
                 },
             }
             : {}),
+        ...(req.tools !== undefined && req.tools.length > 0
+            ? {
+                tools: (0, tool_mapping_1.toOpenAITools)(req.tools),
+                ...((0, tool_mapping_1.toOpenAIToolChoice)(req.toolChoice) !== undefined
+                    ? { tool_choice: (0, tool_mapping_1.toOpenAIToolChoice)(req.toolChoice) }
+                    : {}),
+            }
+            : {}),
     };
 }
 /** Ported suspicious-short heuristic: finish_reason 'stop' + <200 visible
@@ -124,6 +137,7 @@ function createOpenAIAdapter(config) {
     return {
         id: "openai",
         supports: openaiSupports,
+        supportsTools: () => true,
         async call(req) {
             const model = req.candidate.model;
             // F1: post-stream failures still billed tokens — attach usage.
@@ -147,9 +161,11 @@ function createOpenAIAdapter(config) {
                 let ttfbMs;
                 let text = "";
                 let refusalText = "";
+                const toolCallAcc = (0, tool_mapping_1.createOpenAIToolCallAccumulator)();
                 let promptTokens = 0;
                 let completionTokens = 0;
                 let cachedTokens = 0;
+                let cacheWriteTokens = 0;
                 let reasoningTokens = 0;
                 let responseTier = null;
                 let finishReason = null;
@@ -165,19 +181,23 @@ function createOpenAIAdapter(config) {
                     if (typeof choice?.delta?.refusal === "string" && choice.delta.refusal.length > 0) {
                         refusalText += choice.delta.refusal;
                     }
+                    toolCallAcc.push(choice?.delta?.tool_calls);
                     if (choice?.finish_reason)
                         finishReason = choice.finish_reason;
                     if (chunk.usage) {
                         promptTokens = chunk.usage.prompt_tokens ?? 0;
                         completionTokens = chunk.usage.completion_tokens ?? 0;
                         cachedTokens = chunk.usage.prompt_tokens_details?.cached_tokens ?? 0;
+                        cacheWriteTokens = chunk.usage.input_tokens_details?.cache_write_tokens ?? 0;
                         reasoningTokens = chunk.usage.completion_tokens_details?.reasoning_tokens ?? 0;
                     }
                 }
+                // prompt_tokens already INCLUDES cached+write → tokensIn is subset-correct.
                 const usage = {
                     tokensIn: promptTokens,
                     tokensOut: completionTokens,
                     tokensCached: cachedTokens,
+                    tokensCacheWrite: cacheWriteTokens,
                     servedTier: mapServedTier(responseTier, req.requestedTier),
                     ...(ttfbMs !== undefined ? { ttfbMs } : {}),
                 };
@@ -186,6 +206,13 @@ function createOpenAIAdapter(config) {
                 if (refusalText.length > 0) {
                     return fail("refusal", `OpenAI refused structured output: ${refusalText.slice(0, 200)}`, undefined, usage);
                 }
+                // Tool-call turn (spec §4.4): the model chose to call a tool. Surface
+                // the normalized calls; text may legitimately be empty — do NOT run the
+                // empty/suspicious-short/validation guards below.
+                const toolCalls = toolCallAcc.finalize();
+                if (toolCalls !== undefined) {
+                    return { ok: true, text, usage, toolCalls };
+                }
                 const visibleCompletionTokens = Math.max(0, completionTokens - reasoningTokens);
                 if (finishReason === "stop" &&
                     completionTokens > 0 &&
@@ -218,5 +245,37 @@ function createOpenAIAdapter(config) {
                 };
             }
         },
+        async *stream(req) {
+            const model = req.candidate.model;
+            try {
+                const client = new openai_1.default({ apiKey: config.apiKey, timeout: req.timeoutMs });
+                const params = buildOpenAIParams(model, req);
+                const dispatchedAt = Date.now();
+                const stream = await client.chat.completions.create(params);
+                yield* (0, openai_stream_1.streamOpenAIDialect)(stream, req, dispatchedAt, {
+                    provider: "openai",
+                    cachedTokenSource: "details",
+                    mapServedTier,
+                });
+            }
+            catch (error) {
+                const message = error instanceof Error ? error.message : String(error);
+                const { cls, fixHint } = classifyOpenAIFailure(message);
+                yield {
+                    kind: "final",
+                    result: {
+                        ok: false,
+                        failure: {
+                            class: cls,
+                            message,
+                            provider: "openai",
+                            model,
+                            cause: error,
+                            ...(fixHint !== undefined ? { fixHint } : {}),
+                        },
+                    },
+                };
+            }
+        },
     };
 }

package/dist/adapters/sampling.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Shared sampling-param mapping for the adapters (CE-6, spec §2/§3). One place
+ * resolves `AdapterRequest.sampling` into wire fields so every adapter honours
+ * the same precedence and the same absent⇒byte-identical pin.
+ *
+ * Two rules, everywhere:
+ *  - max-output-tokens: `sampling.maxOutputTokens` wins, then the existing
+ *    top-level `maxOutputTokens` (the raw lane's channel), then the adapter's
+ *    own default. Absent both ⇒ the default ⇒ identical to pre-CE-6.
+ *  - temperature/top_p: emitted ONLY when the request declares them, so an
+ *    absent block adds NO keys — the OpenAI-dialect and Anthropic adapters keep
+ *    sending nothing (provider defaults win), exactly as before CE-6.
+ */
+import type { AdapterRequest } from "../types/provider";
+/** The sampling-relevant slice of a request (also what the pure `build*Params`
+ * shaping helpers take, so unit tests never need a branded CandidateRef). */
+export type SamplingShapingInput = Pick<AdapterRequest, "sampling" | "maxOutputTokens">;
+/** Effective max-output-tokens: declared sampling wins, then the top-level
+ * (raw-lane) field, then the adapter default. */
+export declare function effectiveMaxOutputTokens(req: SamplingShapingInput, fallback: number): number;
+/** OpenAI-dialect + Anthropic sampling fields — both speak `temperature` and
+ * `top_p`. Returns keys ONLY for declared fields, so spreading it onto the
+ * params object is a no-op when sampling is absent. */
+export declare function openAISamplingFields(req: SamplingShapingInput): {
+    temperature?: number;
+    top_p?: number;
+};
+//# sourceMappingURL=sampling.d.ts.map

package/dist/adapters/sampling.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sampling.d.ts","sourceRoot":"","sources":["../../src/adapters/sampling.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAExD;6EAC6E;AAC7E,MAAM,MAAM,oBAAoB,GAAG,IAAI,CAAC,cAAc,EAAE,UAAU,GAAG,iBAAiB,CAAC,CAAC;AAExF;iDACiD;AACjD,wBAAgB,wBAAwB,CAAC,GAAG,EAAE,oBAAoB,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAE5F;AAED;;uDAEuD;AACvD,wBAAgB,oBAAoB,CAClC,GAAG,EAAE,oBAAoB,GACxB;IAAE,WAAW,CAAC,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,CAO1C"}

package/dist/adapters/sampling.js

@@ -0,0 +1,34 @@
+"use strict";
+/**
+ * Shared sampling-param mapping for the adapters (CE-6, spec §2/§3). One place
+ * resolves `AdapterRequest.sampling` into wire fields so every adapter honours
+ * the same precedence and the same absent⇒byte-identical pin.
+ *
+ * Two rules, everywhere:
+ *  - max-output-tokens: `sampling.maxOutputTokens` wins, then the existing
+ *    top-level `maxOutputTokens` (the raw lane's channel), then the adapter's
+ *    own default. Absent both ⇒ the default ⇒ identical to pre-CE-6.
+ *  - temperature/top_p: emitted ONLY when the request declares them, so an
+ *    absent block adds NO keys — the OpenAI-dialect and Anthropic adapters keep
+ *    sending nothing (provider defaults win), exactly as before CE-6.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.effectiveMaxOutputTokens = effectiveMaxOutputTokens;
+exports.openAISamplingFields = openAISamplingFields;
+/** Effective max-output-tokens: declared sampling wins, then the top-level
+ * (raw-lane) field, then the adapter default. */
+function effectiveMaxOutputTokens(req, fallback) {
+    return req.sampling?.maxOutputTokens ?? req.maxOutputTokens ?? fallback;
+}
+/** OpenAI-dialect + Anthropic sampling fields — both speak `temperature` and
+ * `top_p`. Returns keys ONLY for declared fields, so spreading it onto the
+ * params object is a no-op when sampling is absent. */
+function openAISamplingFields(req) {
+    const s = req.sampling;
+    if (s === undefined)
+        return {};
+    return {
+        ...(s.temperature !== undefined ? { temperature: s.temperature } : {}),
+        ...(s.topP !== undefined ? { top_p: s.topP } : {}),
+    };
+}

package/dist/adapters/tool-mapping.d.ts

@@ -0,0 +1,92 @@
+/**
+ * Unified tool-calling — native ↔ normalized mapping (G-1/G-5 Phase A,
+ * http-gateway spec §4.4).
+ *
+ * ModelRig speaks ONE tool vocabulary to callers: the OpenAI `tools` /
+ * `tool_calls` shape (`types/provider.ts`). This module is the single place
+ * each provider dialect is translated to and from it. Adapters stay thin: they
+ * call a `to<Provider>Tools` on the way out and a `<provider>…ToToolCalls` on
+ * the way back. Pure functions, no I/O — every branch is unit-tested here so an
+ * adapter integration test never has to reconstruct a provider's tool wire.
+ *
+ * We normalize the PROTOCOL only. Executing a tool and feeding the result back
+ * is the caller's job (spec §4.4).
+ */
+import type { ToolCall, ToolChoice, ToolDefinition } from "../types/provider";
+export interface OpenAIWireTool {
+    readonly type: "function";
+    readonly function: {
+        readonly name: string;
+        readonly description?: string;
+        readonly parameters?: object;
+    };
+}
+export type OpenAIWireToolChoice = "auto" | "none" | "required" | {
+    readonly type: "function";
+    readonly function: {
+        readonly name: string;
+    };
+};
+export declare function toOpenAITools(tools: readonly ToolDefinition[]): OpenAIWireTool[];
+export declare function toOpenAIToolChoice(choice: ToolChoice | undefined): OpenAIWireToolChoice | undefined;
+/** One streamed `tool_calls` delta fragment (OpenAI). `arguments` arrives in
+ * pieces keyed by `index`; `id`/`name` land on the first fragment. */
+export interface OpenAIToolCallDelta {
+    readonly index: number;
+    readonly id?: string;
+    readonly type?: "function";
+    readonly function?: {
+        readonly name?: string;
+        readonly arguments?: string;
+    };
+}
+/** Accumulates streamed OpenAI tool-call deltas (and absorbs a non-streamed
+ * `tool_calls` array — a single fragment each) into normalized `ToolCall`s. */
+export declare function createOpenAIToolCallAccumulator(): {
+    push(deltas: readonly OpenAIToolCallDelta[] | undefined): void;
+    finalize(): ToolCall[] | undefined;
+};
+export interface AnthropicWireTool {
+    readonly name: string;
+    readonly description?: string;
+    readonly input_schema: object;
+}
+export type AnthropicWireToolChoice = {
+    readonly type: "auto";
+} | {
+    readonly type: "any";
+} | {
+    readonly type: "tool";
+    readonly name: string;
+};
+export declare function toAnthropicTools(tools: readonly ToolDefinition[]): AnthropicWireTool[];
+export declare function toAnthropicToolChoice(choice: ToolChoice | undefined): AnthropicWireToolChoice | undefined;
+/** A completed Anthropic `tool_use` content block. */
+export interface AnthropicToolUseBlock {
+    readonly id: string;
+    readonly name: string;
+    readonly input: unknown;
+}
+export declare function anthropicToolUseToToolCalls(blocks: readonly AnthropicToolUseBlock[]): ToolCall[] | undefined;
+export interface GeminiWireTool {
+    readonly functionDeclarations: ReadonlyArray<{
+        readonly name: string;
+        readonly description?: string;
+        readonly parameters?: object;
+    }>;
+}
+export type GeminiWireToolConfig = {
+    readonly functionCallingConfig: {
+        readonly mode: "AUTO" | "ANY" | "NONE";
+        readonly allowedFunctionNames?: readonly string[];
+    };
+};
+export declare function toGeminiTools(tools: readonly ToolDefinition[]): GeminiWireTool[];
+export declare function toGeminiToolConfig(choice: ToolChoice | undefined): GeminiWireToolConfig | undefined;
+/** A Gemini response `functionCall` part. */
+export interface GeminiFunctionCall {
+    readonly name: string;
+    readonly args?: unknown;
+}
+export declare function geminiFunctionCallsToToolCalls(calls: readonly GeminiFunctionCall[]): ToolCall[] | undefined;
+//# sourceMappingURL=tool-mapping.d.ts.map

package/dist/adapters/tool-mapping.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-mapping.d.ts","sourceRoot":"","sources":["../../src/adapters/tool-mapping.ts"],"names":[],"mappings":"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"}

package/dist/adapters/tool-mapping.js

@@ -0,0 +1,143 @@
+"use strict";
+/**
+ * Unified tool-calling — native ↔ normalized mapping (G-1/G-5 Phase A,
+ * http-gateway spec §4.4).
+ *
+ * ModelRig speaks ONE tool vocabulary to callers: the OpenAI `tools` /
+ * `tool_calls` shape (`types/provider.ts`). This module is the single place
+ * each provider dialect is translated to and from it. Adapters stay thin: they
+ * call a `to<Provider>Tools` on the way out and a `<provider>…ToToolCalls` on
+ * the way back. Pure functions, no I/O — every branch is unit-tested here so an
+ * adapter integration test never has to reconstruct a provider's tool wire.
+ *
+ * We normalize the PROTOCOL only. Executing a tool and feeding the result back
+ * is the caller's job (spec §4.4).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.toOpenAITools = toOpenAITools;
+exports.toOpenAIToolChoice = toOpenAIToolChoice;
+exports.createOpenAIToolCallAccumulator = createOpenAIToolCallAccumulator;
+exports.toAnthropicTools = toAnthropicTools;
+exports.toAnthropicToolChoice = toAnthropicToolChoice;
+exports.anthropicToolUseToToolCalls = anthropicToolUseToToolCalls;
+exports.toGeminiTools = toGeminiTools;
+exports.toGeminiToolConfig = toGeminiToolConfig;
+exports.geminiFunctionCallsToToolCalls = geminiFunctionCallsToToolCalls;
+function toOpenAITools(tools) {
+    return tools.map((t) => ({
+        type: "function",
+        function: {
+            name: t.function.name,
+            ...(t.function.description !== undefined ? { description: t.function.description } : {}),
+            ...(t.function.parameters !== undefined ? { parameters: t.function.parameters } : {}),
+        },
+    }));
+}
+function toOpenAIToolChoice(choice) {
+    if (choice === undefined)
+        return undefined;
+    return choice; // the normalized shape IS the OpenAI shape.
+}
+/** Accumulates streamed OpenAI tool-call deltas (and absorbs a non-streamed
+ * `tool_calls` array — a single fragment each) into normalized `ToolCall`s. */
+function createOpenAIToolCallAccumulator() {
+    const byIndex = new Map();
+    const order = [];
+    return {
+        push(deltas) {
+            if (deltas === undefined)
+                return;
+            for (const d of deltas) {
+                let entry = byIndex.get(d.index);
+                if (entry === undefined) {
+                    entry = { id: "", name: "", args: "" };
+                    byIndex.set(d.index, entry);
+                    order.push(d.index);
+                }
+                if (d.id !== undefined)
+                    entry.id = d.id;
+                if (d.function?.name !== undefined)
+                    entry.name = d.function.name;
+                if (d.function?.arguments !== undefined)
+                    entry.args += d.function.arguments;
+            }
+        },
+        finalize() {
+            if (order.length === 0)
+                return undefined;
+            return order.map((idx, i) => {
+                const e = byIndex.get(idx);
+                return {
+                    // Some hosts omit an id in the stream — synthesize a stable one.
+                    id: e.id !== "" ? e.id : `call_${i}`,
+                    type: "function",
+                    function: { name: e.name, arguments: e.args === "" ? "{}" : e.args },
+                };
+            });
+        },
+    };
+}
+const EMPTY_INPUT_SCHEMA = { type: "object", properties: {} };
+function toAnthropicTools(tools) {
+    return tools.map((t) => ({
+        name: t.function.name,
+        ...(t.function.description !== undefined ? { description: t.function.description } : {}),
+        // Anthropic requires an input_schema; default to an open object when the
+        // caller declared a parameterless tool.
+        input_schema: (t.function.parameters ?? EMPTY_INPUT_SCHEMA),
+    }));
+}
+function toAnthropicToolChoice(choice) {
+    if (choice === undefined || choice === "auto")
+        return undefined; // auto is Anthropic's default
+    if (choice === "none")
+        return undefined; // Anthropic omits tools to force no call; caller-handled
+    if (choice === "required")
+        return { type: "any" };
+    return { type: "tool", name: choice.function.name };
+}
+function anthropicToolUseToToolCalls(blocks) {
+    if (blocks.length === 0)
+        return undefined;
+    return blocks.map((b) => ({
+        id: b.id,
+        type: "function",
+        // Anthropic hands back a parsed object; the normalized shape is the raw
+        // JSON string (OpenAI parity), so re-stringify.
+        function: { name: b.name, arguments: JSON.stringify(b.input ?? {}) },
+    }));
+}
+function toGeminiTools(tools) {
+    return [
+        {
+            functionDeclarations: tools.map((t) => ({
+                name: t.function.name,
+                ...(t.function.description !== undefined ? { description: t.function.description } : {}),
+                ...(t.function.parameters !== undefined ? { parameters: t.function.parameters } : {}),
+            })),
+        },
+    ];
+}
+function toGeminiToolConfig(choice) {
+    if (choice === undefined)
+        return undefined;
+    if (choice === "auto")
+        return { functionCallingConfig: { mode: "AUTO" } };
+    if (choice === "none")
+        return { functionCallingConfig: { mode: "NONE" } };
+    if (choice === "required")
+        return { functionCallingConfig: { mode: "ANY" } };
+    return {
+        functionCallingConfig: { mode: "ANY", allowedFunctionNames: [choice.function.name] },
+    };
+}
+function geminiFunctionCallsToToolCalls(calls) {
+    if (calls.length === 0)
+        return undefined;
+    return calls.map((c, i) => ({
+        // Gemini function calls carry no id — synthesize a stable one.
+        id: `call_${i}`,
+        type: "function",
+        function: { name: c.name, arguments: JSON.stringify(c.args ?? {}) },
+    }));
+}

package/dist/artifacts/artifact.d.ts

@@ -0,0 +1,137 @@
+/**
+ * Artifact namespace — Expansion E2 chunk B (spec §2.2, §9).
+ *
+ * `save/load/link/evaluate` over a durable work product's METADATA. The
+ * serialized value is hashed (sha256, node:crypto — no new dep) and the bytes
+ * are DISCARDED; nothing but the metadata row is persisted (the 00030
+ * counter-annotation). Lineage v0: artifacts saved within a run get
+ * `derived_from` edges to artifacts `load`ed since the last save (coverage
+ * measured, never promised). Instrumentation never throws into customer code.
+ *
+ * ── zeroRetention (ratified invariant, named test) ────────────────────────
+ * A run with `zeroRetention: true` emits NO artifact rows of any kind: `save`
+ * refuses fail-closed at THIS gate (before any row is built) with a counted,
+ * logged skip. Structural, not policy-checked at the server.
+ */
+import type { ArtifactStore } from "../telemetry/artifact-store";
+import type { EvalCaseOrigin } from "../types/telemetry";
+import { type ScrubMode } from "./scrub";
+import type { ContentUploadInput, ContentUploadOutcome } from "./content-uploader";
+/** The upload transport `save` fires content through — injected so the SDK's
+ * networked implementation and the tests share one seam. */
+export type ArtifactContentUploader = (input: ContentUploadInput) => Promise<ContentUploadOutcome>;
+/** Per-rig content-custody wiring passed to the artifact api (E2-C). Absent =
+ * metadata + hash only, today's behaviour. */
+export interface ArtifactContentDeps {
+    readonly scrub: ScrubMode;
+    readonly upload: ArtifactContentUploader;
+}
+export interface ArtifactHandle {
+    readonly id: string;
+    readonly name: string;
+    readonly type: string;
+    readonly version: number;
+}
+export interface ArtifactSaveOptions {
+    readonly name: string;
+    readonly type: string;
+    readonly task?: string;
+    /** The pipeline step this artifact belongs to — the semantic grouping key the
+     * console's chain view orders on (E3 spec §2.1). E2 deferred step attribution
+     * ("refined when @step scopes persist, E3"); an EXPLICIT key set by the caller
+     * is the E3 refinement — safe under parallel step waves where an ambient
+     * mutable current-step would cross-attribute. Null (absent) ⇒ ungrouped. */
+    readonly stepKey?: string;
+    /** The step attempt this artifact came from (mirrors steps.attempt_no). Only
+     * meaningful alongside stepKey; null for artifacts saved outside a step. */
+    readonly attemptNo?: number;
+    readonly classification?: string;
+    /** OPAQUE customer URI (their bucket). We store the string + our hash, never content. */
+    readonly contentRef?: string;
+    /** Declared JSON Schema (fingerprinted with the same pure fn the loader uses). */
+    readonly schema?: object | null;
+    /** The artifact this one supersedes (immutable versioning; ruling c column). */
+    readonly supersedes?: ArtifactHandle;
+    readonly expiresAt?: string;
+}
+export interface ArtifactEvaluateOptions {
+    readonly evaluator: string;
+    readonly kind: "deterministic" | "model-judge" | "human";
+    readonly score?: number;
+    readonly passed?: boolean;
+    readonly label?: string;
+    readonly explanation?: string;
+}
+export interface ArtifactPromoteOptions {
+    readonly note?: string;
+    /** The route/task this case belongs to. Falls back to the task the source
+     * artifact was saved with this session; required (explicitly or via fallback)
+     * because an eval case is keyed by task. */
+    readonly task?: string;
+    /** The corrected/golden artifact — set ⇒ a golden-corrected pair. */
+    readonly corrected?: ArtifactHandle | string;
+    /** How it entered the suite. Default: `human-corrected` when `corrected` is
+     * set, else `promoted-failure`. */
+    readonly origin?: EvalCaseOrigin;
+}
+export interface ArtifactApi {
+    /** Hash the value's serialization, record metadata + inferred lineage, return
+     * a handle. Returns null when the namespace is disabled or a zeroRetention run
+     * refuses it (fail-closed). */
+    save(value: unknown, opts: ArtifactSaveOptions): ArtifactHandle | null;
+    /** Mark an artifact consumed by the current run (feeds derived_from lineage). */
+    load(ref: ArtifactHandle | string): void;
+    /** Explicit lineage edge the runtime cannot infer. */
+    link(from: ArtifactHandle | string, to: ArtifactHandle | string, kind: "consumed" | "derived_from"): void;
+    /** Record an evaluation against an artifact. */
+    evaluate(ref: ArtifactHandle | string, opts: ArtifactEvaluateOptions): void;
+    /** Promote an artifact into the org's durable eval suite (E4 chunk A) — a
+     * regression case replayable via `bakeoff --from-eval-cases`. `corrected` set
+     * ⇒ a golden-corrected pair; absent ⇒ a failure-case. The `task` binds the
+     * case to a route: taken from opts, else the task the artifact was saved with
+     * this session; unresolvable ⇒ a warned no-op (returns null, never throws).
+     * Returns the new case id on success. */
+    promoteToEval(ref: ArtifactHandle | string, opts?: ArtifactPromoteOptions): string | null;
+    /** Run `fn` inside a single store transaction and return its value (H8), so a
+     * step's several save/link/evaluate writes commit with ONE fsync. On a
+     * disabled/inert namespace `fn` runs directly (no store, no transaction). */
+    batch<T>(fn: () => T): T;
+    /** Await every in-flight content upload (E2-C). Content upload is fire-and-
+     * forget off the customer's hot path; a graceful shutdown (and the tests)
+     * call this so a process does not exit mid-PUT. No-op when custody is off. */
+    flushContent(): Promise<void>;
+    /** Re-attempt content uploads that came back `pending` — a 404 from the grant
+     * endpoint because the artifact metadata row had not yet been exported when
+     * the upload first fired (the 404-until-durable race, E4 chunk 0). The
+     * exporter calls this AFTER a confirmed flush of the artifacts stream, so by
+     * now the row is durable and the grant succeeds. Each call is exactly ONE
+     * retry per queued item (bounded 2 total, then a counted skip). NEVER throws.
+     * No-op when custody is off or the queue is empty. */
+    retryPendingContent(): Promise<void>;
+    /** Inferred-lineage + content-custody coverage counters (measured, never
+     * promised). Content counters update asynchronously as uploads settle. */
+    coverage(): {
+        readonly saves: number;
+        readonly inferredEdges: number;
+        readonly skippedZeroRetention: number;
+        /** Content uploads that reached the store. */
+        readonly contentUploaded: number;
+        /** Content uploads that degraded to metadata-only (refusal or transient). */
+        readonly contentDegraded: number;
+        /** Content uploads refused by the scrub `block` mode. */
+        readonly contentBlocked: number;
+        /** Content uploads awaiting the metadata-durable retry (E4 chunk 0). Drains
+         * to 0 as the exporter's post-flush hook re-attempts them; a still-pending
+         * item that exhausts its 2 retries moves to `contentDegraded`. */
+        readonly contentPending: number;
+        /** Total scrub findings (counts across types) seen this session. */
+        readonly scrubFindings: number;
+    };
+}
+export declare function createArtifactApi(deps: {
+    readonly store: ArtifactStore;
+    readonly enabled: boolean;
+    /** Content custody wiring (E2-C). Absent = metadata + hash only. */
+    readonly content?: ArtifactContentDeps;
+}): ArtifactApi;
+//# sourceMappingURL=artifact.d.ts.map

package/dist/artifacts/artifact.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"artifact.d.ts","sourceRoot":"","sources":["../../src/artifacts/artifact.ts"],"names":[],"mappings":"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"}