modelrig 0.1.0 → 0.3.0

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

package/dist/artifacts/content-uploader.js

@@ -0,0 +1,124 @@
+"use strict";
+/**
+ * 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.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.uploadArtifactContent = uploadArtifactContent;
+/** A 4xx is a deterministic refusal — the request will fail identically forever,
+ * so it must never be retried (the poison lesson) — with ONE exception: 404,
+ * the metadata-not-yet-durable race, handled separately as `pending`. */
+function isDeterministicRefusal(status) {
+    return status >= 400 && status < 500;
+}
+/**
+ * Upload one artifact's content. NEVER throws — every failure resolves to a
+ * `degraded` outcome the caller records as a metadata-only skip.
+ */
+async function uploadArtifactContent(input, config, fetchFn = fetch) {
+    // Client-side ceiling short-circuit: the server would 413 this; skip the trip.
+    if (input.body.byteLength > config.maxBytes) {
+        return {
+            kind: "degraded",
+            reason: `content is ${input.body.byteLength} bytes, over the ${config.maxBytes} ceiling`,
+            status: 413,
+        };
+    }
+    // 1) Request the grant. A 4xx is deterministic → degrade, no retry.
+    let grantRes;
+    try {
+        grantRes = await fetchFn(config.uploadsUrl, {
+            method: "POST",
+            headers: {
+                "content-type": "application/json",
+                authorization: `Bearer ${config.apiKey}`,
+            },
+            body: JSON.stringify({
+                artifact_id: input.artifactId,
+                content_type: input.contentType,
+                bytes: input.body.byteLength,
+                content_hash: input.contentHash,
+            }),
+        });
+    }
+    catch (err) {
+        // Transient (network) — degrade without retry this pass; the next save's
+        // upload is an independent attempt. We do NOT loop here.
+        return { kind: "degraded", reason: `grant request failed: ${errMsg(err)}`, status: null };
+    }
+    if (!grantRes.ok) {
+        // 404 is the metadata-not-yet-durable race (T11), the ONE transient 4xx: the
+        // row reaches the control plane on the exporter's next flush, so we hand back
+        // `pending` for the post-flush hook to re-attempt (bounded). Every other 4xx
+        // is a deterministic refusal and 5xx a server error — both degrade here, no
+        // retry this pass. The distinction is only in the reason we log.
+        if (grantRes.status === 404) {
+            return { kind: "pending", reason: "artifact metadata not yet durable (grant 404)", status: 404 };
+        }
+        const kind = isDeterministicRefusal(grantRes.status) ? "refused" : "unavailable";
+        return { kind: "degraded", reason: `grant ${kind} (status ${grantRes.status})`, status: grantRes.status };
+    }
+    let grant;
+    try {
+        grant = (await grantRes.json());
+    }
+    catch {
+        return { kind: "degraded", reason: "grant response was not JSON", status: grantRes.status };
+    }
+    if (typeof grant.upload_url !== "string" || typeof grant.content_ref !== "string") {
+        return { kind: "degraded", reason: "grant response missing upload_url/content_ref", status: grantRes.status };
+    }
+    const putHeaders = isStringRecord(grant.headers) ? grant.headers : {};
+    // 2) PUT the bytes straight to the store. Non-2xx or network → degrade.
+    let putRes;
+    try {
+        putRes = await fetchFn(grant.upload_url, { method: "PUT", headers: putHeaders, body: input.body });
+    }
+    catch (err) {
+        return { kind: "degraded", reason: `content PUT failed: ${errMsg(err)}`, status: null };
+    }
+    if (!putRes.ok) {
+        return { kind: "degraded", reason: `content PUT rejected (status ${putRes.status})`, status: putRes.status };
+    }
+    return { kind: "uploaded", contentRef: grant.content_ref };
+}
+function errMsg(err) {
+    return err instanceof Error ? err.message : String(err);
+}
+function isStringRecord(v) {
+    return (typeof v === "object" &&
+        v !== null &&
+        !Array.isArray(v) &&
+        Object.values(v).every((x) => typeof x === "string"));
+}

package/dist/artifacts/index.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Artifact / execution-graph namespace (Expansion E2) — the public barrel.
+ *
+ * Lives here (not spread through `index.ts`) so the SDK entrypoint stays under
+ * the LOC cap and the run/artifact surface has one home. Chunk A ships the run
+ * lifecycle + `@step`; chunk B adds the artifact primitives (save/load/evaluate).
+ */
+import type { ArtifactBuffer, RunNamespace } from "./run-context";
+import type { ArtifactApi, ArtifactContentDeps } from "./artifact";
+import type { ArtifactContentConfig, ArtifactsConfig } from "../config";
+import type { ArtifactStore } from "../telemetry/artifact-store";
+export { getActiveRunContext, createRunNamespace } from "./run-context";
+export type { RunNamespace, RunHandle, RunStartOptions, RunEvaluateOptions, RunStatus, ActiveRunContext, ArtifactBuffer, GroundTruthStepInput, } from "./run-context";
+export { step } from "./step";
+export { createArtifactApi } from "./artifact";
+export { openArtifactStore } from "../telemetry/artifact-store";
+export type { ArtifactStore } from "../telemetry/artifact-store";
+export type { ArtifactApi, ArtifactHandle, ArtifactSaveOptions, ArtifactEvaluateOptions, ArtifactPromoteOptions, ArtifactContentDeps, ArtifactContentUploader, } from "./artifact";
+export { uploadArtifactContent } from "./content-uploader";
+export type { ContentUploadConfig, ContentUploadInput, ContentUploadOutcome, } from "./content-uploader";
+export { scrubContent, luhnValid } from "./scrub";
+export type { ScrubMode, ScrubFinding, ScrubResult, ScrubDetectorType } from "./scrub";
+export { computeDownstreamClosure, TAINT_DEFAULT_MAX_DEPTH, TAINT_DEFAULT_CAP, } from "./taint";
+export type { TaintEdge, Supersession, TaintNode, TaintClosure, TaintOptions, } from "./taint";
+export type { RunRow, StepRow, ArtifactRow, ArtifactEdgeRow, ArtifactEvaluationRow, EvalCaseRow, EvalCaseOrigin, } from "../types/telemetry";
+/** The rig-bound artifact surface exposed as `rig.artifacts`: the run lifecycle
+ * (chunk A) + the artifact primitives (chunk B). */
+export interface ArtifactNamespace {
+    readonly run: RunNamespace;
+    readonly artifact: ArtifactApi;
+}
+/** Build the rig-bound artifact namespace AND the exporter's post-flush retry
+ * hook from resolved config (E4 chunk 0, flag 2). Lives here so the SDK
+ * entrypoint stays under the LOC cap. The hook is present only when content
+ * custody is configured; otherwise it would be a no-op. */
+export declare function wireRigArtifacts(deps: {
+    readonly buffer: ArtifactBuffer;
+    readonly enabled: boolean;
+    readonly artifactStore: ArtifactStore | null;
+    readonly artifacts?: ArtifactsConfig;
+}): {
+    readonly namespace: ArtifactNamespace;
+    readonly onArtifactsFlushed?: () => Promise<void>;
+};
+/**
+ * Build the content-custody deps (E2-C) from resolved config, or undefined when
+ * custody is off. Kept here (not in the SDK entrypoint) so index.ts stays under
+ * the LOC cap (P1) and the content wiring lives beside the namespace it feeds.
+ */
+export declare function buildArtifactContentDeps(content: ArtifactContentConfig | undefined): ArtifactContentDeps | undefined;
+/** Build the rig-bound artifact namespace. Disabled ⇒ every entry is inert
+ * (run.start is a no-op, save returns null, no rows written) — spec §1.4. The
+ * artifact store is present only when enabled (index.ts opens it then). */
+export declare function createArtifactNamespace(deps: {
+    readonly buffer: ArtifactBuffer;
+    readonly artifactStore?: ArtifactStore;
+    readonly enabled: boolean;
+    /** Content-custody config (E2-C). Absent = metadata + hash only; the upload
+     * deps are built here (buildArtifactContentDeps) so the SDK entrypoint stays
+     * under the LOC cap. */
+    readonly content?: ArtifactContentConfig;
+}): ArtifactNamespace;
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/artifacts/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAElE,OAAO,KAAK,EAAE,WAAW,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC;AAGnE,OAAO,KAAK,EAAE,qBAAqB,EAAE,eAAe,EAAE,MAAM,WAAW,CAAC;AACxE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,6BAA6B,CAAC;AAEjE,OAAO,EAAE,mBAAmB,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAC;AACxE,YAAY,EACV,YAAY,EACZ,SAAS,EACT,eAAe,EACf,kBAAkB,EAClB,SAAS,EACT,gBAAgB,EAChB,cAAc,EACd,oBAAoB,GACrB,MAAM,eAAe,CAAC;AACvB,OAAO,EAAE,IAAI,EAAE,MAAM,QAAQ,CAAC;AAC9B,OAAO,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAC/C,OAAO,EAAE,iBAAiB,EAAE,MAAM,6BAA6B,CAAC;AAChE,YAAY,EAAE,aAAa,EAAE,MAAM,6BAA6B,CAAC;AACjE,YAAY,EACV,WAAW,EACX,cAAc,EACd,mBAAmB,EACnB,uBAAuB,EACvB,sBAAsB,EACtB,mBAAmB,EACnB,uBAAuB,GACxB,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,qBAAqB,EAAE,MAAM,oBAAoB,CAAC;AAC3D,YAAY,EACV,mBAAmB,EACnB,kBAAkB,EAClB,oBAAoB,GACrB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,YAAY,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AAClD,YAAY,EAAE,SAAS,EAAE,YAAY,EAAE,WAAW,EAAE,iBAAiB,EAAE,MAAM,SAAS,CAAC;AACvF,OAAO,EACL,wBAAwB,EACxB,uBAAuB,EACvB,iBAAiB,GAClB,MAAM,SAAS,CAAC;AACjB,YAAY,EACV,SAAS,EACT,YAAY,EACZ,SAAS,EACT,YAAY,EACZ,YAAY,GACb,MAAM,SAAS,CAAC;AACjB,YAAY,EACV,MAAM,EACN,OAAO,EACP,WAAW,EACX,eAAe,EACf,qBAAqB,EACrB,WAAW,EACX,cAAc,GACf,MAAM,oBAAoB,CAAC;AAE5B;oDACoD;AACpD,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,GAAG,EAAE,YAAY,CAAC;IAC3B,QAAQ,CAAC,QAAQ,EAAE,WAAW,CAAC;CAChC;AAED;;;2DAG2D;AAC3D,wBAAgB,gBAAgB,CAAC,IAAI,EAAE;IACrC,QAAQ,CAAC,MAAM,EAAE,cAAc,CAAC;IAChC,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,aAAa,EAAE,aAAa,GAAG,IAAI,CAAC;IAC7C,QAAQ,CAAC,SAAS,CAAC,EAAE,eAAe,CAAC;CACtC,GAAG;IAAE,QAAQ,CAAC,SAAS,EAAE,iBAAiB,CAAC;IAAC,QAAQ,CAAC,kBAAkB,CAAC,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAA;CAAE,CAY/F;AAED;;;;GAIG;AACH,wBAAgB,wBAAwB,CACtC,OAAO,EAAE,qBAAqB,GAAG,SAAS,GACzC,mBAAmB,GAAG,SAAS,CAWjC;AAED;;2EAE2E;AAC3E,wBAAgB,uBAAuB,CAAC,IAAI,EAAE;IAC5C,QAAQ,CAAC,MAAM,EAAE,cAAc,CAAC;IAChC,QAAQ,CAAC,aAAa,CAAC,EAAE,aAAa,CAAC;IACvC,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B;;4BAEwB;IACxB,QAAQ,CAAC,OAAO,CAAC,EAAE,qBAAqB,CAAC;CAC1C,GAAG,iBAAiB,CAYpB"}