modelrig 0.0.1 → 0.2.0

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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"}

package/dist/artifacts/artifact.js

@@ -0,0 +1,377 @@
+"use strict";
+/**
+ * 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.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createArtifactApi = createArtifactApi;
+const node_crypto_1 = require("node:crypto");
+const fingerprint_1 = require("../registry/fingerprint");
+const run_context_1 = require("./run-context");
+const scrub_1 = require("./scrub");
+/** Map an artifact `type` to a content-type for the object store. */
+function contentTypeFor(type) {
+    const t = type.toLowerCase();
+    if (t === "json")
+        return "application/json";
+    if (t === "text" || t === "txt" || t === "md" || t === "markdown")
+        return "text/plain; charset=utf-8";
+    if (t === "csv")
+        return "text/csv";
+    if (t === "html")
+        return "text/html; charset=utf-8";
+    return "application/octet-stream";
+}
+function idOf(ref) {
+    return typeof ref === "string" ? ref : ref.id;
+}
+function warn(scope, err) {
+    console.warn(`[modelrig artifacts] ${scope} buffer write failed (dropped, run unaffected): ` +
+        `${err instanceof Error ? err.message : String(err)}`);
+}
+/** A disabled/inert namespace — every entry is a no-op (spec §1.4). */
+function inertApi() {
+    return {
+        save: () => null,
+        load: () => { },
+        link: () => { },
+        evaluate: () => { },
+        promoteToEval: () => null,
+        batch: (fn) => fn(),
+        flushContent: () => Promise.resolve(),
+        retryPendingContent: () => Promise.resolve(),
+        coverage: () => ({
+            saves: 0,
+            inferredEdges: 0,
+            skippedZeroRetention: 0,
+            contentUploaded: 0,
+            contentDegraded: 0,
+            contentBlocked: 0,
+            contentPending: 0,
+            scrubFindings: 0,
+        }),
+    };
+}
+/** Bounded post-flush retries for a `pending` (404-until-durable) content upload
+ * before it becomes a counted skip (E4 chunk 0, flag 2). Two retries with the
+ * exporter interval between them is a multi-flush window for the metadata row to
+ * land — long enough for a real export lag, short enough to bound the wait. */
+const CONTENT_RETRY_BUDGET = 2;
+function createArtifactApi(deps) {
+    if (!deps.enabled)
+        return inertApi();
+    const { store, content } = deps;
+    let saves = 0;
+    let inferredEdges = 0;
+    let skippedZeroRetention = 0;
+    let contentUploaded = 0;
+    let contentDegraded = 0;
+    let contentBlocked = 0;
+    let scrubFindings = 0;
+    /** In-flight uploads; flushContent awaits them (graceful shutdown + tests). */
+    const pendingUploads = new Set();
+    /** Uploads that came back `pending` (grant 404 — metadata not yet durable),
+     * awaiting the exporter's post-flush retry hook. `retriesLeft` decrements once
+     * per hook call; at 0 the item becomes a counted skip (E4 chunk 0, flag 2). */
+    const pendingContent = [];
+    /** artifact id → the task it was saved with THIS session (E4 chunk A). Lets
+     * `promoteToEval(ref)` resolve the case's task without the caller re-supplying
+     * it. A promote of an artifact from a prior session must pass `opts.task`. */
+    const savedTasks = new Map();
+    /** Fire one content upload off the hot path. NEVER rejects into caller code —
+     * every outcome updates a counter (or queues a `pending` retry) and resolves. */
+    function fireUpload(input, upload) {
+        const p = upload(input)
+            .then((outcome) => {
+            if (outcome.kind === "uploaded")
+                contentUploaded += 1;
+            // A 404-until-durable race: queue for the post-flush retry rather than
+            // counting a degrade — the row simply has not been exported yet.
+            else if (outcome.kind === "pending") {
+                pendingContent.push({ input, retriesLeft: CONTENT_RETRY_BUDGET });
+            }
+            else
+                contentDegraded += 1; // "degraded" | "blocked"
+        })
+            .catch(() => {
+            contentDegraded += 1;
+        })
+            .finally(() => {
+            pendingUploads.delete(p);
+        });
+        pendingUploads.add(p);
+    }
+    /** Re-attempt every queued `pending` upload exactly once (the exporter's
+     * post-flush hook). Items that stay pending are re-queued with a decremented
+     * budget; at 0 they become a counted skip. Off/empty ⇒ a resolved no-op. */
+    async function retryPendingContent() {
+        if (content === undefined || pendingContent.length === 0)
+            return;
+        // Snapshot then clear: an item that stays pending is re-pushed with a lower
+        // budget, so THIS pass is exactly one retry per currently-queued item.
+        const batch = pendingContent.splice(0, pendingContent.length);
+        for (const item of batch) {
+            let outcome;
+            try {
+                outcome = await content.upload(item.input);
+            }
+            catch {
+                contentDegraded += 1; // an unexpected throw is a counted skip, never rethrown
+                continue;
+            }
+            if (outcome.kind === "uploaded") {
+                contentUploaded += 1;
+            }
+            else if (outcome.kind === "pending") {
+                const retriesLeft = item.retriesLeft - 1;
+                if (retriesLeft > 0) {
+                    pendingContent.push({ input: item.input, retriesLeft });
+                }
+                else {
+                    contentDegraded += 1; // exhausted the bounded retries → metadata-only
+                    console.warn(`[modelrig artifacts] content for artifact ${item.input.artifactId} still not durable ` +
+                        `after ${CONTENT_RETRY_BUDGET} post-flush retries — metadata-only (counted skip).`);
+                }
+            }
+            else {
+                contentDegraded += 1; // degraded | blocked on retry → counted skip
+            }
+        }
+    }
+    return {
+        save(value, opts) {
+            const ctx = (0, run_context_1.getActiveRunContext)();
+            // zeroRetention: refuse fail-closed BEFORE hashing or building any row.
+            if (ctx !== null && ctx.zeroRetention) {
+                skippedZeroRetention += 1;
+                console.warn(`[modelrig artifacts] zeroRetention run — artifact "${opts.name}" NOT recorded ` +
+                    "(fail-closed at the SDK gate; no metadata, no hash persisted).");
+                return null;
+            }
+            // Hash the serialization, then DISCARD the bytes — metadata + hash only.
+            const serialized = typeof value === "string" ? value : JSON.stringify(value ?? null);
+            const bytes = Buffer.byteLength(serialized, "utf8");
+            const contentHash = `sha256:${(0, node_crypto_1.createHash)("sha256").update(serialized).digest("hex")}`;
+            const schema = opts.schema ?? null;
+            const id = (0, node_crypto_1.randomUUID)();
+            const version = opts.supersedes !== undefined ? opts.supersedes.version + 1 : 1;
+            // Custody applies only when a rig content policy exists AND the caller left
+            // the bytes to us (a caller-supplied contentRef = their own store; managed
+            // custody must not double-home it).
+            const custodyApplies = content !== undefined && opts.contentRef === undefined;
+            // Scrub is computed HERE (before the row is written) so its counts-only
+            // summary can ride the immutable artifact row (00039). Only when custody
+            // applies; null otherwise (custody off ⇒ nothing was scanned).
+            const scrubbed = custodyApplies && content !== undefined ? (0, scrub_1.scrubContent)(serialized, content.scrub) : null;
+            const scrubSummary = scrubbed !== null && content !== undefined ? (0, scrub_1.summarizeScrub)(content.scrub, scrubbed) : null;
+            if (scrubbed !== null)
+                scrubFindings += scrubbed.findings.reduce((n, f) => n + f.count, 0);
+            try {
+                store.recordArtifact({
+                    id,
+                    runId: ctx?.runId ?? null,
+                    // E3: step attribution is now an explicit caller-supplied key (see
+                    // ArtifactSaveOptions.stepKey). Absent ⇒ null, exactly as before.
+                    stepKey: opts.stepKey ?? null,
+                    attemptNo: opts.attemptNo ?? null,
+                    task: opts.task ?? null,
+                    name: opts.name,
+                    type: opts.type,
+                    version,
+                    supersedesArtifactId: opts.supersedes?.id ?? null,
+                    declaredSchema: schema,
+                    fingerprintCell: (0, fingerprint_1.fingerprintSchema)(schema)?.cellKey ?? null,
+                    contentRef: opts.contentRef ?? null,
+                    contentHash,
+                    contentBytes: bytes,
+                    dataClassification: opts.classification ?? null,
+                    expiresAt: opts.expiresAt ?? null,
+                    // Per-row scrub findings ride the original (scanned) row (00039).
+                    scrub: scrubSummary,
+                });
+                saves += 1;
+                if (opts.task !== undefined)
+                    savedTasks.set(id, opts.task); // for promoteToEval (chunk A)
+                // Lineage v0: derived_from edges to everything loaded since the last save.
+                if (ctx !== null) {
+                    for (const loadedId of ctx.takeLoadedIds()) {
+                        if (loadedId === id)
+                            continue; // edges_no_self
+                        store.recordArtifactEdge({ fromArtifactId: id, toArtifactId: loadedId, kind: "derived_from" });
+                        inferredEdges += 1;
+                    }
+                }
+            }
+            catch (err) {
+                warn("save", err);
+                return null;
+            }
+            // ── Content custody (E2-C) ──────────────────────────────────────────
+            // Off by default: only when a rig has configured content custody. The
+            // metadata row above is written regardless — content is layered on, never
+            // a precondition. zeroRetention already returned above, so we never reach
+            // here for a zeroRetention run (structural, not re-checked).
+            if (content !== undefined && scrubbed !== null) {
+                if (scrubbed.blocked) {
+                    // `block` mode found PII/PHI → content upload refused (counted). The
+                    // artifact keeps its metadata + hash; it simply stores no content.
+                    contentBlocked += 1;
+                    console.warn(`[modelrig artifacts] scrub blocked content for "${opts.name}" ` +
+                        `(${scrubbed.findings.length} finding type(s)); metadata + hash kept, no content stored.`);
+                }
+                else if (content.scrub === "redact" && scrubbed.findings.length > 0 && scrubbed.text !== null) {
+                    // Redaction is a SUPERSEDING version (immutability): the original row
+                    // keeps its hash and stores NO content; a new version records the
+                    // masked content's hash and uploads the masked bytes.
+                    const maskedSerialized = scrubbed.text;
+                    const maskedBytes = Buffer.byteLength(maskedSerialized, "utf8");
+                    const maskedHash = `sha256:${(0, node_crypto_1.createHash)("sha256").update(maskedSerialized).digest("hex")}`;
+                    const redactedId = (0, node_crypto_1.randomUUID)();
+                    const redactedVersion = version + 1;
+                    try {
+                        store.recordArtifact({
+                            id: redactedId,
+                            runId: ctx?.runId ?? null,
+                            stepKey: opts.stepKey ?? null,
+                            attemptNo: opts.attemptNo ?? null,
+                            task: opts.task ?? null,
+                            name: opts.name,
+                            type: opts.type,
+                            version: redactedVersion,
+                            supersedesArtifactId: id, // supersedes the original (ruling c column)
+                            declaredSchema: schema,
+                            fingerprintCell: (0, fingerprint_1.fingerprintSchema)(schema)?.cellKey ?? null,
+                            contentRef: null,
+                            contentHash: maskedHash,
+                            contentBytes: maskedBytes,
+                            dataClassification: opts.classification ?? null,
+                            expiresAt: opts.expiresAt ?? null,
+                            // Findings ride the original scanned row; the masked version stores
+                            // no PII, so its own scrub is null (avoid double-counting).
+                            scrub: null,
+                        });
+                        saves += 1;
+                        fireUpload({
+                            artifactId: redactedId,
+                            contentType: contentTypeFor(opts.type),
+                            body: Buffer.from(maskedSerialized, "utf8"),
+                            contentHash: maskedHash,
+                        }, content.upload);
+                        // The live version is the redacted one — hand its handle back.
+                        return { id: redactedId, name: opts.name, type: opts.type, version: redactedVersion };
+                    }
+                    catch (err) {
+                        warn("save (redacted version)", err);
+                        // Fall through to returning the original handle (metadata-only).
+                    }
+                }
+                else {
+                    // off / detect / redact-with-no-findings: upload the bytes verbatim.
+                    fireUpload({
+                        artifactId: id,
+                        contentType: contentTypeFor(opts.type),
+                        body: Buffer.from(scrubbed.text ?? serialized, "utf8"),
+                        contentHash,
+                    }, content.upload);
+                }
+            }
+            return { id, name: opts.name, type: opts.type, version };
+        },
+        load(ref) {
+            (0, run_context_1.getActiveRunContext)()?.noteLoad(idOf(ref));
+        },
+        link(from, to, kind) {
+            const fromId = idOf(from);
+            const toId = idOf(to);
+            if (fromId === toId)
+                return; // edges_no_self
+            try {
+                store.recordArtifactEdge({ fromArtifactId: fromId, toArtifactId: toId, kind });
+            }
+            catch (err) {
+                warn("link", err);
+            }
+        },
+        evaluate(ref, opts) {
+            try {
+                store.recordArtifactEvaluation({
+                    id: (0, node_crypto_1.randomUUID)(),
+                    artifactId: idOf(ref),
+                    runId: null,
+                    evaluator: opts.evaluator,
+                    evaluatorKind: opts.kind,
+                    score: opts.score ?? null,
+                    passed: opts.passed ?? null,
+                    label: opts.label ?? null,
+                    explanation: opts.explanation ?? null,
+                    createdBy: null,
+                });
+            }
+            catch (err) {
+                warn("evaluate", err);
+            }
+        },
+        promoteToEval(ref, opts) {
+            const sourceArtifactId = idOf(ref);
+            // Resolve the task: explicit wins, else the task this artifact was saved
+            // with this session. Unresolvable ⇒ a warned no-op (eval_cases needs task).
+            const task = opts?.task ?? savedTasks.get(sourceArtifactId);
+            if (task === undefined) {
+                console.warn(`[modelrig artifacts] promoteToEval("${sourceArtifactId}") skipped: no task known for this ` +
+                    "artifact (it was not saved this session) — pass { task } to promote it.");
+                return null;
+            }
+            const correctedArtifactId = opts?.corrected !== undefined ? idOf(opts.corrected) : null;
+            const origin = opts?.origin ?? (correctedArtifactId !== null ? "human-corrected" : "promoted-failure");
+            const id = (0, node_crypto_1.randomUUID)();
+            try {
+                store.recordEvalCase({
+                    id,
+                    task,
+                    sourceArtifactId,
+                    correctedArtifactId,
+                    origin,
+                    note: opts?.note ?? null,
+                    createdBy: null,
+                });
+            }
+            catch (err) {
+                warn("promoteToEval", err);
+                return null;
+            }
+            return id;
+        },
+        batch(fn) {
+            return store.batch(fn);
+        },
+        async flushContent() {
+            // Settle every in-flight upload. Individual failures already resolve (they
+            // update contentDegraded), so allSettled never throws here.
+            await Promise.allSettled([...pendingUploads]);
+        },
+        retryPendingContent,
+        coverage() {
+            return {
+                saves,
+                inferredEdges,
+                skippedZeroRetention,
+                contentUploaded,
+                contentDegraded,
+                contentBlocked,
+                contentPending: pendingContent.length,
+                scrubFindings,
+            };
+        },
+    };
+}

package/dist/artifacts/content-uploader.d.ts

@@ -0,0 +1,87 @@
+/**
+ * Managed content upload path — E2-C chunk A (spec §2.4).
+ *
+ * When a rig has opted a route into content custody, `save` records the metadata
+ * row (as always) and THEN hands the serialized bytes here. This module talks to
+ * modelrig-server's grant endpoint, receives a short-lived presigned PUT, and
+ * uploads the bytes straight to the object store — the bytes NEVER touch our
+ * control-plane database, only the customer-designated store.
+ *
+ * ── THE POISON LESSON, APPLIED ────────────────────────────────────────────
+ * A deterministic refusal (403 posture-off, 409 already has content, 413 too
+ * big, 422 malformed) is NOT retried — it will fail identically forever, and
+ * retrying a poison request is how a fail-closed refusal turns into a hot loop.
+ * Every refusal DEGRADES to metadata-only: the artifact still exists (its row
+ * was written before we were called), it simply has no stored content.
+ * Degradation is counted and warned, never thrown — this runs off the
+ * customer's hot path and must never surface as a failed run.
+ *
+ * ── THE 404-UNTIL-DURABLE RACE (E4 chunk 0, flag 2) ───────────────────────
+ * A 404 is the ONE 4xx that is NOT deterministic. The grant endpoint verifies
+ * the artifact metadata row exists (and belongs to the org — T11) before
+ * issuing a URL, but that row reaches the control plane on the exporter's NEXT
+ * flush — so a content upload fired during `save` races ahead of its own
+ * metadata and 404s until the row lands. TRANSIENT by nature: it clears once
+ * the metadata is durable. So a 404 returns a distinct `pending` outcome that
+ * the exporter's post-flush hook re-attempts (bounded: 2 retries, then a
+ * counted skip). A genuinely foreign/missing artifact 404s the same way and
+ * simply exhausts those retries into the metadata-only end state — delayed, but
+ * never a hot loop.
+ *
+ * ── C2 ────────────────────────────────────────────────────────────────────
+ * The api key rides in an Authorization header, never a URL. The presigned URL
+ * and the content hash are NEVER logged. Warnings name the artifact + a status,
+ * nothing else.
+ */
+export type ContentUploadOutcome = 
+/** Bytes are in the store; `contentRef` is the server's canonical pointer. */
+{
+    readonly kind: "uploaded";
+    readonly contentRef: string;
+}
+/** Metadata-only fallback (deterministic refusal or transient failure). The
+ * `status` is the grant HTTP status when there was one, else null. */
+ | {
+    readonly kind: "degraded";
+    readonly reason: string;
+    readonly status: number | null;
+}
+/** The artifact metadata row is not yet durable in the control plane — a 404
+ * from the grant endpoint (which verifies the row before issuing a URL, T11).
+ * TRANSIENT: it clears once the exporter flushes the metadata. NOT counted as
+ * a degrade; the caller queues it for the post-flush hook to re-attempt
+ * (bounded 2 retries, then a counted skip). E4 chunk 0, flag 2. */
+ | {
+    readonly kind: "pending";
+    readonly reason: string;
+    readonly status: 404;
+}
+/** The scrub layer BLOCKED upload (chunk B). Distinct from degraded: this is a
+ * policy refusal, not a failure. */
+ | {
+    readonly kind: "blocked";
+    readonly reason: string;
+};
+export interface ContentUploadConfig {
+    /** Full grant endpoint, e.g. https://server/v1/artifacts/uploads. */
+    readonly uploadsUrl: string;
+    /** `rig_sk_` key carrying the `artifact-write` scope. Header only (C2). */
+    readonly apiKey: string;
+    /** Client-side ceiling — a short-circuit before the round trip; the server
+     * enforces the authoritative one. */
+    readonly maxBytes: number;
+}
+export interface ContentUploadInput {
+    readonly artifactId: string;
+    readonly contentType: string;
+    /** Serialized bytes to upload — already scrubbed by the caller (chunk B). */
+    readonly body: Buffer;
+    /** `sha256:<hex>` of `body`. */
+    readonly contentHash: string;
+}
+/**
+ * Upload one artifact's content. NEVER throws — every failure resolves to a
+ * `degraded` outcome the caller records as a metadata-only skip.
+ */
+export declare function uploadArtifactContent(input: ContentUploadInput, config: ContentUploadConfig, fetchFn?: typeof fetch): Promise<ContentUploadOutcome>;
+//# sourceMappingURL=content-uploader.d.ts.map

package/dist/artifacts/content-uploader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"content-uploader.d.ts","sourceRoot":"","sources":["../../src/artifacts/content-uploader.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AAEH,MAAM,MAAM,oBAAoB;AAC9B,8EAA8E;AAC5E;IAAE,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC;IAAC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;CAAE;AAC5D;sEACsE;GACpE;IAAE,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE;AACxF;;;;mEAImE;GACjE;IAAE,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,GAAG,CAAA;CAAE;AAC7E;oCACoC;GAClC;IAAE,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAE1D,MAAM,WAAW,mBAAmB;IAClC,qEAAqE;IACrE,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,2EAA2E;IAC3E,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB;yCACqC;IACrC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;CAC3B;AAED,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,6EAA6E;IAC7E,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,gCAAgC;IAChC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;CAC9B;AAeD;;;GAGG;AACH,wBAAsB,qBAAqB,CACzC,KAAK,EAAE,kBAAkB,EACzB,MAAM,EAAE,mBAAmB,EAC3B,OAAO,GAAE,OAAO,KAAa,GAC5B,OAAO,CAAC,oBAAoB,CAAC,CAoE/B"}