@sanity/ailf 2.8.0 → 2.9.0

package/dist/artifact-capture/gcs-artifact-writer.js

@@ -7,32 +7,181 @@
  *
  * Paths come from `ARTIFACT_REGISTRY` so writers, signers, and readers agree.
  *
+ * ## W0049 API surface
+ *
+ * - `emit(type, association, payload)` — the canonical single-shot write.
+ *   Dispatch on `descriptor.layout` is internal; callers pass axis values
+ *   and the writer resolves the path.
+ * - `appendNdjson(type, association, rows)` — streaming-append for `traces`.
+ *   Each call writes a numbered part object (`.ndjson.part-NNNN`); the
+ *   parts are composed into the final object lazily at `writeManifest` time
+ *   via GCS object compose. When a stream accumulates > 32 parts the writer
+ *   rolls up parts into intermediate composites to stay under the GCS
+ *   compose cap.
+ * - `writeBulk` / `writePerEntry` — @deprecated legacy surface. Removal in W0052.
+ *
  * Design principles:
  * - P5: Non-blocking — upload failure returns null, never throws.
  * - Lazy client — Storage created on first write.
  *
  * @see docs/decisions/D0032-run-anchored-artifact-store.md
+ * @see docs/decisions/D0033-unified-run-anchored-artifact-capture.md
  */
 import { Storage } from "@google-cloud/storage";
-import { ARTIFACT_REGISTRY, } from "../_vendor/ailf-core/index.js";
+import { ARTIFACT_REGISTRY, buildManifestPreview, } from "../_vendor/ailf-core/index.js";
+import { redactArtifactData } from "./redact-artifact.js";
+/**
+ * GCS's object compose operation accepts at most 32 source objects per call
+ * ([docs](https://cloud.google.com/storage/docs/composite-objects)). When an
+ * NDJSON stream accumulates more than 32 parts the writer rolls up groups of
+ * 32 into intermediate composites and composes those — one extra round trip
+ * per 32 additional parts.
+ */
+const GCS_COMPOSE_MAX = 32;
 export class GcsArtifactWriter {
     client = null;
     options;
+    ndjsonStreams = new Map();
     constructor(options) {
         this.options = options;
+        if (options.storage) {
+            this.client = options.storage;
+        }
+    }
+    // ---- Canonical W0049 API ------------------------------------------------
+    async emit(type, association, payload) {
+        const descriptor = ARTIFACT_REGISTRY[type];
+        const runId = association.run;
+        if (!runId) {
+            console.warn(`  ⚠️  emit("${type}"): association.run is required, skipping`);
+            return null;
+        }
+        // AC10 — redact at the writer boundary so secrets never reach GCS.
+        const redacted = redactArtifactData(payload);
+        // Preview reads the pre-redaction payload (same as local writer — the
+        // preview carries a descriptor-controlled summary bounded by capBytes,
+        // not the raw entry bytes).
+        const preview = buildManifestPreview(descriptor, payload);
+        if (descriptor.layout === "bulk") {
+            const path = descriptor.objectPath(runId);
+            const ref = await this.putBody(path, serializeForMime(redacted, descriptor.mime), {
+                layout: "bulk",
+                mime: descriptor.mime,
+                entryCount: entryCountOf(redacted),
+            });
+            if (!ref)
+                return null;
+            return preview === undefined ? ref : { ...ref, preview };
+        }
+        // per-entry
+        const entryKey = descriptor.formatEntryKey(association);
+        const path = descriptor.objectPath(runId, entryKey);
+        const ref = await this.putBody(path, serializeForMime(redacted, descriptor.mime), { layout: "per-entry", mime: descriptor.mime });
+        if (!ref)
+            return null;
+        return {
+            ...ref,
+            path: `runs/${runId}/${descriptor.slug}`,
+            entryCount: 1,
+            entries: [
+                {
+                    key: entryKey,
+                    bytes: ref.bytes ?? 0,
+                    association,
+                    ...(preview === undefined ? {} : { preview }),
+                },
+            ],
+        };
+    }
+    async appendNdjson(type, association, rows) {
+        const descriptor = ARTIFACT_REGISTRY[type];
+        if (descriptor.mime !== "application/x-ndjson") {
+            console.warn(`  ⚠️  appendNdjson("${type}"): descriptor mime is ${descriptor.mime}, not application/x-ndjson — skipping`);
+            return null;
+        }
+        const runId = association.run;
+        if (!runId) {
+            console.warn(`  ⚠️  appendNdjson("${type}"): association.run is required, skipping`);
+            return null;
+        }
+        if (rows.length === 0)
+            return null;
+        const entryKey = descriptor.formatEntryKey(association);
+        const finalPath = descriptor.objectPath(runId, entryKey);
+        const streamKey = `${type}::${entryKey}`;
+        let state = this.ndjsonStreams.get(streamKey);
+        if (!state) {
+            state = { finalPath, partCount: 0, totalBytes: 0 };
+            this.ndjsonStreams.set(streamKey, state);
+        }
+        const partPath = `${finalPath}.part-${String(state.partCount).padStart(4, "0")}`;
+        // AC10 — redact per row before serializing the NDJSON batch.
+        const redactedRows = rows.map((r) => redactArtifactData(r));
+        const body = redactedRows.map((r) => JSON.stringify(r)).join("\n") + "\n";
+        const bytes = Buffer.byteLength(body, "utf-8");
+        try {
+            const storage = this.getClient();
+            await storage
+                .bucket(this.options.bucket)
+                .file(partPath)
+                .save(body, { contentType: "application/x-ndjson" });
+            state.partCount++;
+            state.totalBytes += bytes;
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            console.warn(`  ⚠️  NDJSON part upload failed (non-blocking): ${partPath} — ${message}`);
+            return null;
+        }
+        return {
+            store: "gcs",
+            bucket: this.options.bucket,
+            path: `runs/${runId}/${descriptor.slug}`,
+            bytes: state.totalBytes,
+            entryCount: 1,
+            layout: "per-entry",
+            entries: [
+                {
+                    key: entryKey,
+                    bytes: state.totalBytes,
+                    association,
+                },
+            ],
+        };
+    }
+    async writeManifest(runId, manifest) {
+        await this.finalizeNdjsonStreams();
+        const path = `runs/${runId}/manifest.json`;
+        return this.putBody(path, JSON.stringify(manifest), {
+            layout: "bulk",
+            mime: "application/json",
+        });
     }
+    // ---- Deprecated legacy surface (W0052) ----------------------------------
+    /** @deprecated Use `emit()` instead. Routes through the same GCS I/O. */
     async writeBulk(type, runId, data) {
         const descriptor = ARTIFACT_REGISTRY[type];
+        if (descriptor.layout !== "bulk") {
+            console.warn(`  ⚠️  writeBulk("${type}"): descriptor layout is "${descriptor.layout}", not "bulk" — skipping`);
+            return null;
+        }
         const path = descriptor.objectPath(runId);
-        return this.putJson(path, data, {
+        const redacted = redactArtifactData(data);
+        return this.putBody(path, serializeForMime(redacted, descriptor.mime), {
             layout: "bulk",
-            entryCount: entryCountOf(data),
+            mime: descriptor.mime,
+            entryCount: entryCountOf(redacted),
         });
     }
+    /** @deprecated Use `emit()` per entry instead. */
     async writePerEntry(type, runId, entries) {
         const descriptor = ARTIFACT_REGISTRY[type];
+        if (descriptor.layout !== "per-entry") {
+            console.warn(`  ⚠️  writePerEntry("${type}"): descriptor layout is "${descriptor.layout}", not "per-entry" — skipping`);
+            return null;
+        }
         if (!descriptor.parseEntryKey) {
-            console.warn(`  ⚠️  writePerEntry called for "${type}" but the registry has no parseEntryKey`);
+            console.warn(`  ⚠️  writePerEntry("${type}"): descriptor has no parseEntryKey`);
             return null;
         }
         const storage = this.getClient();
@@ -45,13 +194,14 @@ export class GcsArtifactWriter {
                 continue;
             }
             const path = descriptor.objectPath(runId, entry.key);
-            const json = JSON.stringify(entry.data);
-            const bytes = Buffer.byteLength(json, "utf-8");
+            const redacted = redactArtifactData(entry.data);
+            const body = serializeForMime(redacted, descriptor.mime);
+            const bytes = Buffer.byteLength(body, "utf-8");
             try {
                 await storage
                     .bucket(this.options.bucket)
                     .file(path)
-                    .save(json, { contentType: "application/json" });
+                    .save(body, { contentType: descriptor.mime });
                 uploaded.push({ key: entry.key, bytes });
                 totalBytes += bytes;
             }
@@ -72,19 +222,45 @@ export class GcsArtifactWriter {
             entries: uploaded,
         };
     }
-    async writeManifest(runId, manifest) {
-        const path = `runs/${runId}/manifest.json`;
-        return this.putJson(path, manifest, { layout: "bulk" });
+    // ---- Internals ----------------------------------------------------------
+    /**
+     * Compose all buffered NDJSON streams into their final objects. Called
+     * from `writeManifest` so the manifest is the single sync point for
+     * NDJSON finalization.
+     *
+     * When `partCount > GCS_COMPOSE_MAX`, parts are rolled up in groups of
+     * `GCS_COMPOSE_MAX` into intermediate composites, then composed. This
+     * stays under the per-call source cap at the cost of one extra round
+     * trip per 32 additional parts.
+     */
+    async finalizeNdjsonStreams() {
+        for (const state of this.ndjsonStreams.values()) {
+            if (state.partCount === 0)
+                continue;
+            const storage = this.getClient();
+            const bucket = storage.bucket(this.options.bucket);
+            const partPaths = Array.from({ length: state.partCount }, (_, i) => `${state.finalPath}.part-${String(i).padStart(4, "0")}`);
+            try {
+                const finalPath = await composeInGroups(bucket, partPaths, state.finalPath);
+                if (finalPath !== state.finalPath) {
+                    console.warn(`  ⚠️  NDJSON compose produced "${finalPath}" (expected "${state.finalPath}")`);
+                }
+            }
+            catch (err) {
+                const message = err instanceof Error ? err.message : String(err);
+                console.warn(`  ⚠️  NDJSON compose failed (non-blocking): ${state.finalPath} — ${message}`);
+            }
+        }
+        this.ndjsonStreams.clear();
     }
-    async putJson(path, data, meta) {
-        const json = JSON.stringify(data);
-        const bytes = Buffer.byteLength(json, "utf-8");
+    async putBody(path, body, meta) {
+        const bytes = Buffer.byteLength(body, "utf-8");
         try {
             const storage = this.getClient();
             await storage
                 .bucket(this.options.bucket)
                 .file(path)
-                .save(json, { contentType: "application/json" });
+                .save(body, { contentType: meta.mime });
             return {
                 store: "gcs",
                 bucket: this.options.bucket,
@@ -107,6 +283,17 @@ export class GcsArtifactWriter {
         return this.client;
     }
 }
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+function serializeForMime(payload, mime) {
+    if (mime === "text/markdown" || mime === "application/yaml") {
+        if (typeof payload === "string")
+            return payload;
+        return String(payload ?? "");
+    }
+    return JSON.stringify(payload);
+}
 function entryCountOf(data) {
     if (typeof data === "object" &&
         data !== null &&
@@ -117,3 +304,40 @@ function entryCountOf(data) {
     }
     return undefined;
 }
+/**
+ * Compose a list of GCS parts into a destination object. When the part count
+ * exceeds `GCS_COMPOSE_MAX`, roll up groups into intermediate composites and
+ * recurse until a single compose call suffices.
+ *
+ * Returns the destination path on success. Intermediate composites are
+ * written to `{dest}.roll-{n}` and left in place — they are cheap, and
+ * keeping them simplifies failure recovery.
+ */
+async function composeInGroups(bucket, partPaths, destPath) {
+    if (partPaths.length === 0) {
+        throw new Error(`composeInGroups: no parts to compose for ${destPath}`);
+    }
+    if (partPaths.length === 1) {
+        // Single part — server-side copy into place. Avoids streaming the
+        // object through this process (unlike download + re-upload) and
+        // preserves the source object's Content-Type / metadata on the
+        // destination (W0049 review finding C2).
+        await bucket.file(partPaths[0]).copy(bucket.file(destPath));
+        return destPath;
+    }
+    if (partPaths.length <= GCS_COMPOSE_MAX) {
+        const sources = partPaths.map((p) => bucket.file(p));
+        await bucket.combine(sources, bucket.file(destPath));
+        return destPath;
+    }
+    // >32 parts: roll up in groups of GCS_COMPOSE_MAX and recurse.
+    const rollups = [];
+    for (let i = 0; i < partPaths.length; i += GCS_COMPOSE_MAX) {
+        const group = partPaths.slice(i, i + GCS_COMPOSE_MAX);
+        const rollupPath = `${destPath}.roll-${String(i / GCS_COMPOSE_MAX).padStart(4, "0")}`;
+        const sources = group.map((p) => bucket.file(p));
+        await bucket.combine(sources, bucket.file(rollupPath));
+        rollups.push(rollupPath);
+    }
+    return composeInGroups(bucket, rollups, destPath);
+}

package/dist/artifact-capture/local-fs-artifact-writer.d.ts

@@ -0,0 +1,71 @@
+/**
+ * LocalFilesystemArtifactWriter — writes AILF run artifacts to the local
+ * filesystem under `{rootDir}/runs/{runId}/…`.
+ *
+ * D0033 M4 inverts D0032's "GCS default, local fallback" stance: the local
+ * writer is **always** attached, and GCS layers on top via a fanout writer
+ * when credentials are present. The result — every run produces a usable
+ * artifact bundle on disk even on airplanes, laptops, and CI without GCS
+ * creds. Studio retrieval works uniformly; only `ArtifactRef.store`
+ * differentiates.
+ *
+ * ## Path layout
+ *
+ * Paths mirror the GCS tree exactly, so the same descriptor's `objectPath`
+ * is used verbatim:
+ *   - bulk: `{rootDir}/runs/{runId}/{slug}.{ext}`
+ *   - per-entry: `{rootDir}/runs/{runId}/{slug}/{sanitizedKey}.{ext}`
+ *   - manifest: `{rootDir}/runs/{runId}/manifest.json`
+ *
+ * This keeps the L6 cross-reader contract test simple — a byte-compare of
+ * every object at every path, modulo timestamped manifest fields.
+ *
+ * ## Design choices
+ *
+ * - **Redaction at emit boundary (AC10).** `redactArtifactData` runs per
+ *   write, not post-hoc on a tarball. Same rules as the legacy collector.
+ * - **Exclude list gating (Q3).** `--capture-exclude=LIST` passes through
+ *   to the constructor; `emit()` returns null for excluded types before
+ *   touching disk.
+ * - **NDJSON uses plain `fs.appendFile`.** No compose rollover needed —
+ *   unlike GCS, local fs appends are atomic and unbounded. A crash mid-
+ *   append leaves a partial row visible; acceptable for dev runs.
+ * - **Non-blocking per P5.** Any fs error returns null + warns, never
+ *   throws. The pipeline must not fail because local disk is full.
+ *
+ * @see docs/decisions/D0033-unified-run-anchored-artifact-capture.md (§ M4)
+ * @see packages/eval/src/artifact-capture/gcs-artifact-writer.ts (mirror)
+ */
+import { type ArtifactEntry, type ArtifactRef, type ArtifactType, type ArtifactWriter, type AssociationValues, type RunId, type RunManifest } from "../_vendor/ailf-core/index.d.ts";
+export interface LocalFilesystemArtifactWriterOptions {
+    /**
+     * Absolute or cwd-relative root directory under which `runs/{runId}/…`
+     * is written. Defaults to `.ailf/results/captures/` at the composition
+     * root; tests inject their own temp dirs.
+     */
+    rootDir: string;
+    /**
+     * Artifact types to skip. When `emit()` is called for an excluded
+     * type, it returns null without touching disk. Driven by
+     * `--capture-exclude=LIST` in W0050 Slice 4.
+     */
+    exclude?: readonly ArtifactType[];
+}
+export declare class LocalFilesystemArtifactWriter implements ArtifactWriter {
+    private readonly options;
+    private readonly excludeSet;
+    constructor(options: LocalFilesystemArtifactWriterOptions);
+    emit<T extends ArtifactType>(type: T, association: AssociationValues, payload: unknown): Promise<ArtifactRef | null>;
+    appendNdjson<T extends ArtifactType>(type: T, association: AssociationValues, rows: readonly unknown[]): Promise<ArtifactRef | null>;
+    writeManifest(runId: RunId, manifest: RunManifest): Promise<ArtifactRef | null>;
+    /** @deprecated Use `emit()` instead. */
+    writeBulk(type: ArtifactType, runId: RunId, data: unknown): Promise<ArtifactRef | null>;
+    /** @deprecated Use `emit()` per entry instead. */
+    writePerEntry(type: ArtifactType, runId: RunId, entries: readonly ArtifactEntry[]): Promise<ArtifactRef | null>;
+    private resolve;
+    /**
+     * Write the body to `absPath`, creating parent dirs as needed. Returns
+     * false + warns on any fs error (P5 non-blocking).
+     */
+    private writeAtomic;
+}

package/dist/artifact-capture/local-fs-artifact-writer.js

@@ -0,0 +1,273 @@
+/**
+ * LocalFilesystemArtifactWriter — writes AILF run artifacts to the local
+ * filesystem under `{rootDir}/runs/{runId}/…`.
+ *
+ * D0033 M4 inverts D0032's "GCS default, local fallback" stance: the local
+ * writer is **always** attached, and GCS layers on top via a fanout writer
+ * when credentials are present. The result — every run produces a usable
+ * artifact bundle on disk even on airplanes, laptops, and CI without GCS
+ * creds. Studio retrieval works uniformly; only `ArtifactRef.store`
+ * differentiates.
+ *
+ * ## Path layout
+ *
+ * Paths mirror the GCS tree exactly, so the same descriptor's `objectPath`
+ * is used verbatim:
+ *   - bulk: `{rootDir}/runs/{runId}/{slug}.{ext}`
+ *   - per-entry: `{rootDir}/runs/{runId}/{slug}/{sanitizedKey}.{ext}`
+ *   - manifest: `{rootDir}/runs/{runId}/manifest.json`
+ *
+ * This keeps the L6 cross-reader contract test simple — a byte-compare of
+ * every object at every path, modulo timestamped manifest fields.
+ *
+ * ## Design choices
+ *
+ * - **Redaction at emit boundary (AC10).** `redactArtifactData` runs per
+ *   write, not post-hoc on a tarball. Same rules as the legacy collector.
+ * - **Exclude list gating (Q3).** `--capture-exclude=LIST` passes through
+ *   to the constructor; `emit()` returns null for excluded types before
+ *   touching disk.
+ * - **NDJSON uses plain `fs.appendFile`.** No compose rollover needed —
+ *   unlike GCS, local fs appends are atomic and unbounded. A crash mid-
+ *   append leaves a partial row visible; acceptable for dev runs.
+ * - **Non-blocking per P5.** Any fs error returns null + warns, never
+ *   throws. The pipeline must not fail because local disk is full.
+ *
+ * @see docs/decisions/D0033-unified-run-anchored-artifact-capture.md (§ M4)
+ * @see packages/eval/src/artifact-capture/gcs-artifact-writer.ts (mirror)
+ */
+import { promises as fs } from "node:fs";
+import path from "node:path";
+import { ARTIFACT_REGISTRY, buildManifestPreview, } from "../_vendor/ailf-core/index.js";
+import { redactArtifactData } from "./redact-artifact.js";
+// ---------------------------------------------------------------------------
+// Implementation
+// ---------------------------------------------------------------------------
+export class LocalFilesystemArtifactWriter {
+    options;
+    excludeSet;
+    constructor(options) {
+        this.options = options;
+        this.excludeSet = new Set(options.exclude ?? []);
+    }
+    // ---- Canonical W0049 API ------------------------------------------------
+    async emit(type, association, payload) {
+        if (this.excludeSet.has(type))
+            return null;
+        const descriptor = ARTIFACT_REGISTRY[type];
+        const runId = association.run;
+        if (!runId) {
+            console.warn(`  ⚠️  emit("${type}"): association.run is required, skipping`);
+            return null;
+        }
+        const redacted = redactArtifactData(payload);
+        const body = serializeForMime(redacted, descriptor.mime);
+        const bytes = Buffer.byteLength(body, "utf-8");
+        // Preview is built from the pre-redaction payload so the extract sees
+        // the same shape the producer handed us. The full entry is still redacted
+        // on disk; the preview lives only on the manifest and is bounded by the
+        // descriptor's capBytes.
+        const preview = buildManifestPreview(descriptor, payload);
+        if (descriptor.layout === "bulk") {
+            const relPath = descriptor.objectPath(runId);
+            const absPath = this.resolve(relPath);
+            const wrote = await this.writeAtomic(absPath, body);
+            if (!wrote)
+                return null;
+            return {
+                store: "local",
+                bucket: this.options.rootDir,
+                path: relPath,
+                bytes,
+                entryCount: entryCountOf(redacted),
+                layout: "bulk",
+                ...(preview === undefined ? {} : { preview }),
+            };
+        }
+        // per-entry
+        const entryKey = descriptor.formatEntryKey(association);
+        const relPath = descriptor.objectPath(runId, entryKey);
+        const absPath = this.resolve(relPath);
+        const wrote = await this.writeAtomic(absPath, body);
+        if (!wrote)
+            return null;
+        return {
+            store: "local",
+            bucket: this.options.rootDir,
+            path: `runs/${runId}/${descriptor.slug}`,
+            bytes,
+            entryCount: 1,
+            layout: "per-entry",
+            entries: [
+                {
+                    key: entryKey,
+                    bytes,
+                    association,
+                    ...(preview === undefined ? {} : { preview }),
+                },
+            ],
+        };
+    }
+    async appendNdjson(type, association, rows) {
+        if (this.excludeSet.has(type))
+            return null;
+        const descriptor = ARTIFACT_REGISTRY[type];
+        if (descriptor.mime !== "application/x-ndjson") {
+            console.warn(`  ⚠️  appendNdjson("${type}"): descriptor mime is ${descriptor.mime}, not application/x-ndjson — skipping`);
+            return null;
+        }
+        const runId = association.run;
+        if (!runId) {
+            console.warn(`  ⚠️  appendNdjson("${type}"): association.run is required, skipping`);
+            return null;
+        }
+        if (rows.length === 0)
+            return null;
+        const entryKey = descriptor.formatEntryKey(association);
+        const relPath = descriptor.objectPath(runId, entryKey);
+        const absPath = this.resolve(relPath);
+        const redactedRows = rows.map((r) => redactArtifactData(r));
+        const body = redactedRows.map((r) => JSON.stringify(r)).join("\n") + "\n";
+        const bytes = Buffer.byteLength(body, "utf-8");
+        try {
+            await fs.mkdir(path.dirname(absPath), { recursive: true });
+            await fs.appendFile(absPath, body, "utf-8");
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            console.warn(`  ⚠️  NDJSON append failed (non-blocking): ${absPath} — ${message}`);
+            return null;
+        }
+        // Local fs appendFile keeps no part state, so the returned ref always
+        // reports the *cumulative* size on disk — same semantic as the GCS
+        // writer's `state.totalBytes`, just computed differently.
+        let cumulative = bytes;
+        try {
+            const stat = await fs.stat(absPath);
+            cumulative = stat.size;
+        }
+        catch {
+            // If stat fails we still have the current batch's bytes — acceptable.
+        }
+        return {
+            store: "local",
+            bucket: this.options.rootDir,
+            path: `runs/${runId}/${descriptor.slug}`,
+            bytes: cumulative,
+            entryCount: 1,
+            layout: "per-entry",
+            entries: [{ key: entryKey, bytes: cumulative, association }],
+        };
+    }
+    async writeManifest(runId, manifest) {
+        const relPath = `runs/${runId}/manifest.json`;
+        const absPath = this.resolve(relPath);
+        const body = JSON.stringify(manifest);
+        const wrote = await this.writeAtomic(absPath, body);
+        if (!wrote)
+            return null;
+        return {
+            store: "local",
+            bucket: this.options.rootDir,
+            path: relPath,
+            bytes: Buffer.byteLength(body, "utf-8"),
+            layout: "bulk",
+        };
+    }
+    // ---- Deprecated legacy surface (W0052) ----------------------------------
+    /** @deprecated Use `emit()` instead. */
+    async writeBulk(type, runId, data) {
+        const descriptor = ARTIFACT_REGISTRY[type];
+        if (descriptor.layout !== "bulk") {
+            console.warn(`  ⚠️  writeBulk("${type}"): descriptor layout is "${descriptor.layout}", not "bulk" — skipping`);
+            return null;
+        }
+        return this.emit(type, { run: runId }, data);
+    }
+    /** @deprecated Use `emit()` per entry instead. */
+    async writePerEntry(type, runId, entries) {
+        const descriptor = ARTIFACT_REGISTRY[type];
+        if (descriptor.layout !== "per-entry") {
+            console.warn(`  ⚠️  writePerEntry("${type}"): descriptor layout is "${descriptor.layout}", not "per-entry" — skipping`);
+            return null;
+        }
+        if (!descriptor.parseEntryKey) {
+            console.warn(`  ⚠️  writePerEntry("${type}"): descriptor has no parseEntryKey`);
+            return null;
+        }
+        // Legacy shim: write each entry directly by its raw key, bypassing
+        // formatEntryKey. Preserves byte-equivalence with pre-W0050 paths
+        // for producers still on the legacy call surface.
+        const uploaded = [];
+        let totalBytes = 0;
+        for (const entry of entries) {
+            const parsed = descriptor.parseEntryKey(entry.key);
+            if (!parsed.ok) {
+                console.warn(`  ⚠️  Skipping entry with invalid key "${entry.key}": ${parsed.reason}`);
+                continue;
+            }
+            const redacted = redactArtifactData(entry.data);
+            const body = serializeForMime(redacted, descriptor.mime);
+            const bytes = Buffer.byteLength(body, "utf-8");
+            const relPath = descriptor.objectPath(runId, entry.key);
+            const absPath = this.resolve(relPath);
+            const wrote = await this.writeAtomic(absPath, body);
+            if (!wrote)
+                continue;
+            uploaded.push({ key: entry.key, bytes });
+            totalBytes += bytes;
+        }
+        if (uploaded.length === 0)
+            return null;
+        return {
+            store: "local",
+            bucket: this.options.rootDir,
+            path: `runs/${runId}/${descriptor.slug}`,
+            bytes: totalBytes,
+            entryCount: uploaded.length,
+            layout: "per-entry",
+            entries: uploaded,
+        };
+    }
+    // ---- Internals ----------------------------------------------------------
+    resolve(relPath) {
+        return path.resolve(this.options.rootDir, relPath);
+    }
+    /**
+     * Write the body to `absPath`, creating parent dirs as needed. Returns
+     * false + warns on any fs error (P5 non-blocking).
+     */
+    async writeAtomic(absPath, body) {
+        try {
+            await fs.mkdir(path.dirname(absPath), { recursive: true });
+            await fs.writeFile(absPath, body, "utf-8");
+            return true;
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            console.warn(`  ⚠️  Artifact write failed (non-blocking): ${absPath} — ${message}`);
+            return false;
+        }
+    }
+}
+// ---------------------------------------------------------------------------
+// Helpers (shared shape with GcsArtifactWriter)
+// ---------------------------------------------------------------------------
+function serializeForMime(payload, mime) {
+    if (mime === "text/markdown" || mime === "application/yaml") {
+        if (typeof payload === "string")
+            return payload;
+        return String(payload ?? "");
+    }
+    return JSON.stringify(payload);
+}
+function entryCountOf(data) {
+    if (typeof data === "object" &&
+        data !== null &&
+        "entries" in data &&
+        typeof data.entries === "object") {
+        return Object.keys(data.entries)
+            .length;
+    }
+    return undefined;
+}

package/dist/commands/explain-handler.js

@@ -727,6 +727,10 @@ async function buildPipelineExplainPlan(actionCommand, rootDir) {
         captureCompress: raw.captureCompress ?? true,
         captureExtras: raw.captureExtras ?? true,
         captureDir: raw.captureDir,
+        artifacts: raw.artifacts ?? true,
+        artifactsDir: raw.artifactsDir,
+        artifactsDryRun: raw.artifactsDryRun ?? false,
+        captureExclude: raw.captureExclude,
     };
     const resolved = computeResolvedOptions(withDefaults);
     const planOpts = {

package/dist/commands/pipeline-action.d.ts

@@ -67,6 +67,11 @@ export interface ResolvedOptions {
     captureDir?: string;
     captureCompress: boolean;
     captureExtras: boolean;
+    /** D0033 / W0049 — unified artifact surface (W0050 wires it into writer). */
+    artifactsDisabled: boolean;
+    artifactsDir?: string;
+    artifactsDryRun: boolean;
+    artifactsExclude?: readonly string[];
 }
 /**
  * Pure option resolution — computes ResolvedOptions from CLI flags without