modelrig 0.9.0 → 0.11.0

package/dist/adapters/responses-api.js

@@ -0,0 +1,124 @@
+"use strict";
+/**
+ * Responses-API dispatch path (Native Web Search lane, spec N1–N2) — the SHARED
+ * request/response mapping for providers whose native `web_search` tool lives only
+ * on `/v1/responses` (OpenAI + xAI/Grok today; same shape). This is a NEW dispatch
+ * path, NOT an extension of the Chat Completions `tools` block — see research §2.
+ *
+ * DOCTRINE (inherited from CE-9):
+ *  - ABSENT ⇒ BYTE-IDENTICAL. This path is entered ONLY for a grounded request
+ *    (`req.grounding === true`). A non-grounded request stays on the adapter's
+ *    existing `chat.completions.create` call, unchanged. The per-adapter branch
+ *    lives in openai.ts / grok.ts (Step 2); this module owns only the Responses shape.
+ *  - FORWARD-VERBATIM + CLASSIFY-TEACHABLY: forward the web_search tool + sampling/
+ *    reasoning under their Responses-dialect names; let the provider enforce; map a
+ *    rejection onto an EXISTING FailureClass with a teaching fixHint (no new class).
+ *  - CITATIONS: map `response` citations onto the `url_citation` shape already used
+ *    by the inject rung (src/run/grounding.ts) — do NOT invent a second type.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildResponsesParams = buildResponsesParams;
+exports.mapResponsesResult = mapResponsesResult;
+const sampling_1 = require("./sampling");
+const raw_support_1 = require("../run/raw-support");
+/** Parity with the Chat Completions default output cap (openai.ts / grok.ts). */
+const DEFAULT_MAX_OUTPUT_TOKENS = 32000;
+/**
+ * Build the `responses.create` params for a grounded request. Appends the
+ * `web_search` tool; forwards sampling/reasoning. Callers MUST only invoke this when
+ * `req.grounding === true` (the guard already enforced provider support pre-dispatch).
+ *
+ * Reasoning maps 1:1 for OpenAI (`level` → `reasoning.effort`); for grok the neutral
+ * four-level `level` is coarsened to xAI's `low|high` via `coarsenGrokReasoningEffort`
+ * (the SAME disclosed mapping the Chat Completions path uses — never a silent drop).
+ */
+function buildResponsesParams(req) {
+    const input = [
+        ...(req.systemPrompt !== "" ? [{ role: "system", content: req.systemPrompt }] : []),
+        { role: "user", content: req.userPrompt },
+    ];
+    const reasoning = req.reasoning !== undefined
+        ? {
+            reasoning: {
+                effort: req.candidate.provider === "grok"
+                    ? (0, raw_support_1.coarsenGrokReasoningEffort)(req.reasoning.level)
+                    : req.reasoning.level,
+            },
+        }
+        : {};
+    return {
+        model: req.candidate.model,
+        input,
+        // Native web-search server tool, left at defaults. As of openai@7.x the
+        // `web_search` tool type also accepts `filters`, `external_web_access`, and
+        // `search_context_size` (a token/context-budget knob) — NOT wired here on
+        // purpose (they need product knobs); available for a follow-up mission.
+        tools: [{ type: "web_search" }],
+        max_output_tokens: (0, sampling_1.effectiveMaxOutputTokens)(req, DEFAULT_MAX_OUTPUT_TOKENS),
+        // temperature / top_p share the Chat Completions dialect names on the
+        // Responses API — reuse the one sampling mapper (absent ⇒ no keys added).
+        ...(0, sampling_1.openAISamplingFields)(req),
+        ...reasoning,
+    };
+}
+/**
+ * Map a raw `responses.create` result onto ModelRig's normalized shape: output text,
+ * AdapterUsage (cache-read is a SUBSET of `tokensIn`, per the WS-A invariant), and
+ * citations in the `url_citation` shape. A zero-citation grounded response is
+ * SURFACED (empty array), never thrown (spec N2).
+ */
+function mapResponsesResult(response) {
+    const r = (typeof response === "object" && response !== null ? response : {});
+    const items = Array.isArray(r.output) ? r.output : [];
+    // Text: prefer the SDK convenience aggregate, else concatenate output_text parts.
+    const aggregate = typeof r.output_text === "string" ? r.output_text : "";
+    const text = aggregate !== ""
+        ? aggregate
+        : items
+            .filter((it) => it.type === "message")
+            .flatMap((it) => it.content ?? [])
+            .filter((c) => c.type === "output_text" && typeof c.text === "string")
+            .map((c) => c.text)
+            .join("");
+    // Citations: url_citation annotations on output_text parts, deduped by URL,
+    // first-seen title wins. Reuses the inject rung's UrlCitation shape.
+    const seen = new Set();
+    const citations = [];
+    for (const it of items) {
+        if (it.type !== "message")
+            continue;
+        for (const part of it.content ?? []) {
+            if (part.type !== "output_text")
+                continue;
+            for (const ann of part.annotations ?? []) {
+                if (ann.type !== "url_citation" || typeof ann.url !== "string" || ann.url === "")
+                    continue;
+                if (seen.has(ann.url))
+                    continue;
+                seen.add(ann.url);
+                citations.push({
+                    type: "url_citation",
+                    url: ann.url,
+                    ...(typeof ann.title === "string" && ann.title !== "" ? { title: ann.title } : {}),
+                });
+            }
+        }
+    }
+    // usage: input_tokens already INCLUDES cached_tokens → tokensIn is subset-correct
+    // (WS-A). The Responses API reports no cache-write on these providers ⇒ 0/omit.
+    const usage = {
+        tokensIn: r.usage?.input_tokens ?? 0,
+        tokensOut: r.usage?.output_tokens ?? 0,
+        tokensCached: r.usage?.input_tokens_details?.cached_tokens ?? 0,
+        servedTier: "standard",
+    };
+    // searchCalls: count the web_search_call output items (spec N3). None ⇒ undefined
+    // (the raw success path assumes 1, disclosed).
+    const searchCalls = items.filter((it) => it.type === "web_search_call").length;
+    return {
+        text,
+        usage,
+        citations,
+        ...(searchCalls > 0 ? { searchCalls } : {}),
+    };
+}

package/dist/artifacts/artifact.d.ts

@@ -18,6 +18,7 @@ import type { EvalCaseOrigin } from "../types/telemetry";
 import { type ScrubMode } from "./scrub";
 import { type TaskSettingsResolver } from "../settings/task-settings";
 import type { ContentUploadInput, ContentUploadOutcome } from "./content-uploader";
+import { type Manifest } from "../prompts/manifest";
 /** 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>;
@@ -64,6 +65,15 @@ export interface ArtifactSaveOptions {
     readonly supersedes?: ArtifactHandle;
     readonly expiresAt?: string;
 }
+/** Options for {@link ArtifactApi.saveManifest} — the grouping keys the manifest
+ * artifact inherits from its prompt (task/step), mirroring a normal save. */
+export interface ArtifactManifestOptions {
+    /** Artifact name; defaults to `<prompt name>.manifest` / `"manifest"`. */
+    readonly name?: string;
+    readonly task?: string;
+    readonly stepKey?: string;
+    readonly attemptNo?: number;
+}
 export interface ArtifactPromoteOptions {
     readonly note?: string;
     /** The route/task this case belongs to. Falls back to the task the source
@@ -81,6 +91,16 @@ export interface ArtifactApi {
      * a handle. Returns null when the namespace is disabled or a zeroRetention run
      * refuses it (fail-closed). */
     save(value: unknown, opts: ArtifactSaveOptions): ArtifactHandle | null;
+    /** PSR-1: attach a **structure-only** assembly manifest (spec §2.1) to a
+     * `prompt` artifact. Validates the manifest, saves it as a linked free-text
+     * `type: "manifest"` artifact (ZERO-DDL — the `type` column is open), and
+     * links `prompt → manifest` with a `derived_from` edge so the manifest joins
+     * the existing prompt lineage and stays addressable for PSR-2 ingest. Returns
+     * the manifest handle, or null when the manifest is invalid (a counted,
+     * teaching warn — never throws) or custody/zeroRetention refuses the save.
+     * A no-op unless explicitly called, so `save` stays byte-identical (the emit
+     * is inert without a manifest). */
+    saveManifest(prompt: ArtifactHandle | string, manifest: Manifest, opts?: ArtifactManifestOptions): 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. */

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

@@ -1 +1 @@
-{"version":3,"file":"artifact.d.ts","sourceRoot":"","sources":["../../src/artifacts/artifact.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAGH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,6BAA6B,CAAC;AACjE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AAGzD,OAAO,EAAgC,KAAK,SAAS,EAAE,MAAM,SAAS,CAAC;AAEvE,OAAO,EAAsB,KAAK,oBAAoB,EAAE,MAAM,2BAA2B,CAAC;AAC1F,OAAO,KAAK,EAAE,kBAAkB,EAAE,oBAAoB,EAAE,MAAM,oBAAoB,CAAC;AAEnF;4DAC4D;AAC5D,MAAM,MAAM,uBAAuB,GAAG,CAAC,KAAK,EAAE,kBAAkB,KAAK,OAAO,CAAC,oBAAoB,CAAC,CAAC;AAEnG;8CAC8C;AAC9C,MAAM,WAAW,mBAAmB;IAClC;;;;iCAI6B;IAC7B,QAAQ,CAAC,QAAQ,EAAE,oBAAoB,GAAG,IAAI,CAAC;IAC/C;6BACyB;IACzB,QAAQ,CAAC,YAAY,EAAE,SAAS,CAAC;IACjC,QAAQ,CAAC,MAAM,EAAE,uBAAuB,CAAC;CAC1C;AAuBD,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAED,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB;;;;;iFAK6E;IAC7E,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B;gFAC4E;IAC5E,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;IACjC,yFAAyF;IACzF,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,kFAAkF;IAClF,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC,gFAAgF;IAChF,QAAQ,CAAC,UAAU,CAAC,EAAE,cAAc,CAAC;IACrC,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;CAC7B;AAED,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB;;gDAE4C;IAC5C,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,qEAAqE;IACrE,QAAQ,CAAC,SAAS,CAAC,EAAE,cAAc,GAAG,MAAM,CAAC;IAC7C;uCACmC;IACnC,QAAQ,CAAC,MAAM,CAAC,EAAE,cAAc,CAAC;CAClC;AAED,MAAM,WAAW,WAAW;IAC1B;;mCAE+B;IAC/B,IAAI,CAAC,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,mBAAmB,GAAG,cAAc,GAAG,IAAI,CAAC;IACvE,iFAAiF;IACjF,IAAI,CAAC,GAAG,EAAE,cAAc,GAAG,MAAM,GAAG,IAAI,CAAC;IACzC,sDAAsD;IACtD,IAAI,CAAC,IAAI,EAAE,cAAc,GAAG,MAAM,EAAE,EAAE,EAAE,cAAc,GAAG,MAAM,EAAE,IAAI,EAAE,UAAU,GAAG,cAAc,GAAG,IAAI,CAAC;IAC1G;;;;;6CAKyC;IACzC,aAAa,CAAC,GAAG,EAAE,cAAc,GAAG,MAAM,EAAE,IAAI,CAAC,EAAE,sBAAsB,GAAG,MAAM,GAAG,IAAI,CAAC;IAC1F;;iFAE6E;IAC7E,KAAK,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,CAAC,GAAG,CAAC,CAAC;IACzB;;kFAE8E;IAC9E,YAAY,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAC9B;;;;;;0DAMsD;IACtD,mBAAmB,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACrC;8EAC0E;IAC1E,QAAQ,IAAI;QACV,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;QACvB,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;QAC/B,QAAQ,CAAC,oBAAoB,EAAE,MAAM,CAAC;QACtC,8CAA8C;QAC9C,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;QACjC,6EAA6E;QAC7E,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;QACjC,yDAAyD;QACzD,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;QAChC;;0EAEkE;QAClE,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;QAChC,oEAAoE;QACpE,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;KAChC,CAAC;CACH;AA0CD,wBAAgB,iBAAiB,CAAC,IAAI,EAAE;IACtC,QAAQ,CAAC,KAAK,EAAE,aAAa,CAAC;IAC9B,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,oEAAoE;IACpE,QAAQ,CAAC,OAAO,CAAC,EAAE,mBAAmB,CAAC;CACxC,GAAG,WAAW,CA4Ud"}
+{"version":3,"file":"artifact.d.ts","sourceRoot":"","sources":["../../src/artifacts/artifact.ts"],"names":[],"mappings":"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"}

package/dist/artifacts/artifact.js

@@ -22,6 +22,7 @@ const run_context_1 = require("./run-context");
 const scrub_1 = require("./scrub");
 const classification_1 = require("./classification");
 const task_settings_1 = require("../settings/task-settings");
+const manifest_1 = require("../prompts/manifest");
 /** The configured scrub mode for one artifact save (BEFORE the S8-c PII/PHI
  * floor). Resolved EXACTLY as capture-write.ts / samples.ts do: a configured
  * control plane WINS (`resolver.get(task).scrub`), else the rig's default. A
@@ -43,6 +44,9 @@ function contentTypeFor(type) {
         return "text/csv";
     if (t === "html")
         return "text/html; charset=utf-8";
+    // PSR-1: a structure-only assembly manifest is stored as a linked JSON artifact.
+    if (t === "manifest")
+        return "application/json";
     return "application/octet-stream";
 }
 function idOf(ref) {
@@ -56,6 +60,7 @@ function warn(scope, err) {
 function inertApi() {
     return {
         save: () => null,
+        saveManifest: () => null,
         load: () => { },
         link: () => { },
         promoteToEval: () => null,
@@ -160,188 +165,219 @@ function createArtifactApi(deps) {
             }
         }
     }
-    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;
-            // G1 (spec §3): an explicit stepKey wins; absent, the artifact lands in the
-            // AMBIENT step — the most recent auto-step in this run context — so
-            // `artifact.save` and the run/@step graph compose. Null outside a step (or
-            // outside a run context), exactly as before.
-            const stepKey = opts.stepKey ?? ctx?.currentStepKey() ?? null;
-            // S8-b: validate data_classification against the shared enum. A bad value
-            // would fail the DB CHECK (00058) and drop the row at ingest, so catch it
-            // here with a teaching warning and drop the LABEL (the artifact still
-            // saves — a metadata typo must not lose the artifact). Normalize first so
-            // "PHI"/" pii " keep their meaning (and their scrub floor) rather than
-            // silently dropping.
-            let classification = (0, classification_1.normalizeClassification)(opts.classification);
-            if (opts.classification !== undefined && classification !== null && !(0, classification_1.isDataClassification)(classification)) {
-                console.warn(`[modelrig artifacts] artifact "${opts.name}" has an unknown data_classification ` +
-                    `${JSON.stringify(opts.classification)} — label dropped (artifact still saved). ` +
-                    `fix_hint: use one of ${classification_1.DATA_CLASSIFICATIONS.join(", ")}.`);
-                classification = null;
-            }
-            // 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). The
-            // configured mode comes from the per-task/account control-plane setting
-            // (P15 CP-3b — resolver wins; `content.defaultScrub` fallback local/direct).
-            // S8-c: a `pii`/`phi` artifact forces the scrub mode to a floor of
-            // `redact`, so PII/PHI content is never uploaded verbatim even when the
-            // task's configured mode is `off`/`detect`. A stronger `block` stays.
-            const effScrub = content !== undefined
-                ? (0, task_settings_1.effectiveScrubMode)(resolveContentScrubMode(content, opts.task), classification)
-                : null;
-            const scrubbed = custodyApplies && content !== undefined && effScrub !== null ? (0, scrub_1.scrubContent)(serialized, effScrub) : null;
-            const scrubSummary = scrubbed !== null && effScrub !== null ? (0, scrub_1.summarizeScrub)(effScrub, 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 an explicit caller-supplied key; G1 adds the
-                    // ambient-step fallback (resolved above) so a save with no stepKey joins
-                    // the current run/@step. Absent both ⇒ null, exactly as before.
-                    stepKey,
-                    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: classification,
-                    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;
-                    }
+    // Extracted so `saveManifest` (PSR-1) can compose them without re-implementing
+    // the custody/lineage save path or the edges_no_self link. The bodies are the
+    // original `save`/`link` verbatim — the returned object references these.
+    const 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;
+        // G1 (spec §3): an explicit stepKey wins; absent, the artifact lands in the
+        // AMBIENT step — the most recent auto-step in this run context — so
+        // `artifact.save` and the run/@step graph compose. Null outside a step (or
+        // outside a run context), exactly as before.
+        const stepKey = opts.stepKey ?? ctx?.currentStepKey() ?? null;
+        // S8-b: validate data_classification against the shared enum. A bad value
+        // would fail the DB CHECK (00058) and drop the row at ingest, so catch it
+        // here with a teaching warning and drop the LABEL (the artifact still
+        // saves — a metadata typo must not lose the artifact). Normalize first so
+        // "PHI"/" pii " keep their meaning (and their scrub floor) rather than
+        // silently dropping.
+        let classification = (0, classification_1.normalizeClassification)(opts.classification);
+        if (opts.classification !== undefined && classification !== null && !(0, classification_1.isDataClassification)(classification)) {
+            console.warn(`[modelrig artifacts] artifact "${opts.name}" has an unknown data_classification ` +
+                `${JSON.stringify(opts.classification)} — label dropped (artifact still saved). ` +
+                `fix_hint: use one of ${classification_1.DATA_CLASSIFICATIONS.join(", ")}.`);
+            classification = null;
+        }
+        // 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). The
+        // configured mode comes from the per-task/account control-plane setting
+        // (P15 CP-3b — resolver wins; `content.defaultScrub` fallback local/direct).
+        // S8-c: a `pii`/`phi` artifact forces the scrub mode to a floor of
+        // `redact`, so PII/PHI content is never uploaded verbatim even when the
+        // task's configured mode is `off`/`detect`. A stronger `block` stays.
+        const effScrub = content !== undefined
+            ? (0, task_settings_1.effectiveScrubMode)(resolveContentScrubMode(content, opts.task), classification)
+            : null;
+        const scrubbed = custodyApplies && content !== undefined && effScrub !== null ? (0, scrub_1.scrubContent)(serialized, effScrub) : null;
+        const scrubSummary = scrubbed !== null && effScrub !== null ? (0, scrub_1.summarizeScrub)(effScrub, 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 an explicit caller-supplied key; G1 adds the
+                // ambient-step fallback (resolved above) so a save with no stepKey joins
+                // the current run/@step. Absent both ⇒ null, exactly as before.
+                stepKey,
+                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: classification,
+                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;
+        }
+        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.`);
             }
-            // ── 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 (effScrub === "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,
-                            // Same ambient-step resolution as the original row it supersedes.
-                            stepKey,
-                            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: classification,
-                            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.
+            else if (effScrub === "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,
+                        // Same ambient-step resolution as the original row it supersedes.
+                        stepKey,
+                        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: classification,
+                        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: id,
+                        artifactId: redactedId,
                         contentType: contentTypeFor(opts.type),
-                        body: Buffer.from(scrubbed.text ?? serialized, "utf8"),
-                        contentHash,
+                        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).
                 }
             }
-            return { id, name: opts.name, type: opts.type, version };
-        },
+            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 };
+    };
+    const 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);
+        }
+    };
+    // PSR-1: validate a structure-only manifest, save it as a linked `manifest`
+    // artifact (ZERO-DDL free-text type), and chain `prompt → manifest` via
+    // derived_from. Never throws; an invalid manifest is a counted, teaching warn.
+    const saveManifest = (prompt, manifest, opts) => {
+        const result = (0, manifest_1.validateManifest)(manifest);
+        if (!result.ok) {
+            console.warn(`[modelrig artifacts] manifest for prompt "${idOf(prompt)}" is invalid — not emitted: ` +
+                `${result.errors.join("; ")}`);
+            return null;
+        }
+        const promptName = typeof prompt === "string" ? undefined : prompt.name;
+        const name = opts?.name ?? (promptName !== undefined ? `${promptName}.manifest` : "manifest");
+        const handle = save(JSON.stringify(result.manifest), {
+            name,
+            type: "manifest",
+            ...(opts?.task !== undefined ? { task: opts.task } : {}),
+            ...(opts?.stepKey !== undefined ? { stepKey: opts.stepKey } : {}),
+            ...(opts?.attemptNo !== undefined ? { attemptNo: opts.attemptNo } : {}),
+        });
+        if (handle === null)
+            return null; // custody/zeroRetention refused — no edge.
+        // Chain prompt → manifest: the prompt is assembled per this manifest recipe.
+        link(prompt, handle, "derived_from");
+        return handle;
+    };
+    return {
+        save,
+        saveManifest,
         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);
-            }
-        },
+        link,
         promoteToEval(ref, opts) {
             const sourceArtifactId = idOf(ref);
             // Resolve the task: explicit wins, else the task this artifact was saved

package/dist/artifacts/index.d.ts

@@ -16,7 +16,9 @@ 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, ArtifactPromoteOptions, ArtifactContentDeps, ArtifactContentUploader, } from "./artifact";
+export type { ArtifactApi, ArtifactHandle, ArtifactSaveOptions, ArtifactManifestOptions, ArtifactPromoteOptions, ArtifactContentDeps, ArtifactContentUploader, } from "./artifact";
+export { validateManifest, assertValidManifest, parseAuthoringDoc } from "../prompts/manifest";
+export type { Slot, SlotKind, Manifest, DynamicSource, DynamicSourceKind, CachePolicy, StaticFrom, ManifestValidation, AuthoringDoc, } from "../prompts/manifest";
 export { uploadArtifactContent } from "./content-uploader";
 export type { ContentUploadConfig, ContentUploadInput, ContentUploadOutcome, } from "./content-uploader";
 export { scrubContent, luhnValid, detectSpans, scrubDetectors } from "./scrub";