@sanity/ailf 2.7.1 → 2.9.0

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

@@ -0,0 +1,111 @@
+/**
+ * accumulating-artifact-writer.ts
+ *
+ * Decorator that wraps any `ArtifactWriter` and accumulates every
+ * successful `emit()` / `appendNdjson()` return into a run-scoped
+ * manifest slice. FinalizeRunStep reads the accumulator at the end of
+ * a pipeline and writes a `runs/{runId}/manifest.json` populated with
+ * one entry per produced artifact type.
+ *
+ * Before W0051 revisit: only `calculate-scores-step` registered its
+ * ref (for `testOutputs`) into `state.artifactRefs`; every other
+ * producer discarded the returned ref. The result was empty
+ * `Report.artifactManifest` fields and no per-entry preview lookup
+ * for Studio hooks. Wrapping the writer at the composition-root level
+ * closes that gap without per-producer bookkeeping.
+ *
+ * Merging rules (per type):
+ *   - `bulk`: last-writer-wins. A pipeline that emits the same bulk
+ *     artifact twice overwrites — matches GCS semantics.
+ *   - `per-entry`: entries accumulate into a keyed map. A later emit
+ *     at the same `entries[].key` replaces the earlier one.
+ *
+ * The decorator holds no disk state; the `_resetAccumulated()` hook is
+ * for unit tests that rerun emit sequences within a single writer.
+ *
+ * @see docs/decisions/D0033-unified-run-anchored-artifact-capture.md (§ M5)
+ */
+export class AccumulatingArtifactWriter {
+    /**
+     * Exposed so composition-root tests can assert on the underlying backend
+     * (LocalFilesystemArtifactWriter, FanoutArtifactWriter, etc.) without
+     * plumbing a separate accessor. Treat as read-only.
+     */
+    inner;
+    accumulated = {};
+    constructor(inner) {
+        this.inner = inner;
+    }
+    /** Snapshot of every ref produced this far, keyed by artifact type. */
+    getAccumulatedArtifactRefs() {
+        return { ...this.accumulated };
+    }
+    /** Test-only. Clears accumulated refs without touching the inner writer. */
+    _resetAccumulated() {
+        for (const k of Object.keys(this.accumulated)) {
+            delete this.accumulated[k];
+        }
+    }
+    // ---- ArtifactWriter surface --------------------------------------------
+    async emit(type, association, payload) {
+        const ref = await this.inner.emit(type, association, payload);
+        if (ref)
+            this.mergeRef(type, ref);
+        return ref;
+    }
+    async appendNdjson(type, association, rows) {
+        const ref = await this.inner.appendNdjson(type, association, rows);
+        if (ref)
+            this.mergeRef(type, ref);
+        return ref;
+    }
+    async writeManifest(runId, manifest) {
+        return this.inner.writeManifest(runId, manifest);
+    }
+    /** @deprecated — forwarded to the inner writer without accumulation. */
+    async writeBulk(type, runId, data) {
+        const ref = await this.inner.writeBulk(type, runId, data);
+        if (ref)
+            this.mergeRef(type, ref);
+        return ref;
+    }
+    /** @deprecated — forwarded to the inner writer without accumulation. */
+    async writePerEntry(type, runId, entries) {
+        const ref = await this.inner.writePerEntry(type, runId, entries);
+        if (ref)
+            this.mergeRef(type, ref);
+        return ref;
+    }
+    // ---- Merge rules --------------------------------------------------------
+    mergeRef(type, ref) {
+        const existing = this.accumulated[type];
+        if (!existing) {
+            this.accumulated[type] = ref;
+            return;
+        }
+        // Bulk: last-writer-wins. A step that re-emits a bulk artifact (e.g.
+        // a rerun of calculate-scores) overwrites the earlier body on disk,
+        // so the manifest reflects the latest.
+        if (ref.layout === "bulk") {
+            this.accumulated[type] = ref;
+            return;
+        }
+        // Per-entry: merge entries by key. Duplicate keys replace (last write
+        // wins at that key — matches local/gcs overwrite semantics).
+        const merged = new Map();
+        for (const e of existing.entries ?? [])
+            merged.set(e.key, e);
+        for (const e of ref.entries ?? [])
+            merged.set(e.key, e);
+        const entries = Array.from(merged.values());
+        this.accumulated[type] = {
+            ...existing,
+            layout: "per-entry",
+            entries,
+            entryCount: entries.length,
+            bytes: entries.reduce((sum, e) => sum + (e.bytes ?? 0), 0),
+            // `store`, `bucket`, `path` stay from the first ref — per-entry
+            // paths are descriptor-derived and stable across calls.
+        };
+    }
+}

package/dist/artifact-capture/api-gateway-artifact-writer.d.ts

@@ -0,0 +1,52 @@
+/**
+ * ApiGatewayArtifactWriter — uploads AILF run artifacts via the API Gateway.
+ *
+ * Used when the CLI runs locally without GCS credentials. The Gateway signs a
+ * PUT URL (scoped to a single GCS object) and the writer PUTs JSON directly
+ * to GCS so Vercel stays out of the data path.
+ *
+ * Endpoints:
+ *   - Bulk:      GET  {apiBaseUrl}/v1/runs/{runId}/artifacts/{type}/upload-url
+ *   - Per-entry: GET  {apiBaseUrl}/v1/runs/{runId}/artifacts/{type}/{entryKey}/upload-url
+ *   - Manifest:  GET  {apiBaseUrl}/v1/runs/{runId}/artifacts/manifest/upload-url
+ *
+ * ## W0049 API surface
+ *
+ * - `emit(type, association, payload)` — canonical single-shot write. Uses
+ *   the registry to resolve `layout` and the signing endpoint.
+ * - `appendNdjson` — NOT IMPLEMENTED. The API Gateway has no batch-signing
+ *   endpoint yet (W0052), and per-object signing would issue one sign call
+ *   per row, which blows the Vercel Function budget. Throws
+ *   `NotImplementedError` so the gap is explicit rather than a silent no-op.
+ * - `writeBulk` / `writePerEntry` — @deprecated legacy surface; removal in W0052.
+ *
+ * Design principles:
+ * - P5: Non-blocking — any non-structural failure returns null and warns.
+ * - Stateless — no client state between calls.
+ *
+ * @see docs/decisions/D0032-run-anchored-artifact-store.md
+ * @see docs/decisions/D0033-unified-run-anchored-artifact-capture.md
+ */
+import { type ArtifactEntry, type ArtifactRef, type ArtifactType, type ArtifactWriter, type AssociationValues, type RunId, type RunManifest } from "../_vendor/ailf-core/index.d.ts";
+export interface ApiGatewayArtifactWriterOptions {
+    /** Base URL of the API gateway (e.g., "https://ailf-api.sanity.build"). */
+    apiBaseUrl: string;
+    /** AILF API key with the `artifact:write` scope. */
+    apiKey: string;
+    /** GCS bucket name — included in the returned ArtifactRef. */
+    bucket: string;
+}
+export declare class ApiGatewayArtifactWriter implements ArtifactWriter {
+    private readonly options;
+    constructor(options: ApiGatewayArtifactWriterOptions);
+    emit<T extends ArtifactType>(type: T, association: AssociationValues, payload: unknown): Promise<ArtifactRef | null>;
+    appendNdjson(): 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 putJson;
+    private putJsonRaw;
+    private fetchSignedUrl;
+}

package/dist/artifact-capture/api-gateway-artifact-writer.js

@@ -0,0 +1,199 @@
+/**
+ * ApiGatewayArtifactWriter — uploads AILF run artifacts via the API Gateway.
+ *
+ * Used when the CLI runs locally without GCS credentials. The Gateway signs a
+ * PUT URL (scoped to a single GCS object) and the writer PUTs JSON directly
+ * to GCS so Vercel stays out of the data path.
+ *
+ * Endpoints:
+ *   - Bulk:      GET  {apiBaseUrl}/v1/runs/{runId}/artifacts/{type}/upload-url
+ *   - Per-entry: GET  {apiBaseUrl}/v1/runs/{runId}/artifacts/{type}/{entryKey}/upload-url
+ *   - Manifest:  GET  {apiBaseUrl}/v1/runs/{runId}/artifacts/manifest/upload-url
+ *
+ * ## W0049 API surface
+ *
+ * - `emit(type, association, payload)` — canonical single-shot write. Uses
+ *   the registry to resolve `layout` and the signing endpoint.
+ * - `appendNdjson` — NOT IMPLEMENTED. The API Gateway has no batch-signing
+ *   endpoint yet (W0052), and per-object signing would issue one sign call
+ *   per row, which blows the Vercel Function budget. Throws
+ *   `NotImplementedError` so the gap is explicit rather than a silent no-op.
+ * - `writeBulk` / `writePerEntry` — @deprecated legacy surface; removal in W0052.
+ *
+ * Design principles:
+ * - P5: Non-blocking — any non-structural failure returns null and warns.
+ * - Stateless — no client state between calls.
+ *
+ * @see docs/decisions/D0032-run-anchored-artifact-store.md
+ * @see docs/decisions/D0033-unified-run-anchored-artifact-capture.md
+ */
+import { ARTIFACT_REGISTRY, NotImplementedError, } from "../_vendor/ailf-core/index.js";
+export class ApiGatewayArtifactWriter {
+    options;
+    constructor(options) {
+        this.options = options;
+    }
+    // ---- 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;
+        }
+        if (descriptor.layout === "bulk") {
+            const uploadUrlPath = `/v1/runs/${encodeURIComponent(runId)}/artifacts/${encodeURIComponent(type)}/upload-url`;
+            return this.putJson(uploadUrlPath, payload, {
+                layout: "bulk",
+                entryCount: entryCountOf(payload),
+            });
+        }
+        // per-entry
+        const entryKey = descriptor.formatEntryKey(association);
+        const uploadUrlPath = `/v1/runs/${encodeURIComponent(runId)}/artifacts/${encodeURIComponent(type)}/${encodeURIComponent(entryKey)}/upload-url`;
+        const result = await this.putJsonRaw(uploadUrlPath, payload);
+        if (!result)
+            return null;
+        return {
+            store: "gcs",
+            bucket: result.bucket,
+            path: `runs/${runId}/${descriptor.slug}`,
+            bytes: result.bytes,
+            entryCount: 1,
+            layout: "per-entry",
+            entries: [{ key: entryKey, bytes: result.bytes, association }],
+        };
+    }
+    async appendNdjson() {
+        throw new NotImplementedError("ApiGatewayArtifactWriter.appendNdjson is not supported. " +
+            "NDJSON streaming for traces requires the batch signing endpoint " +
+            "(W0052). Producers should use GcsArtifactWriter directly when " +
+            "running locally, or defer traces emission until the gateway lands " +
+            "the batch route.");
+    }
+    async writeManifest(runId, manifest) {
+        const uploadUrlPath = `/v1/runs/${encodeURIComponent(runId)}/artifacts/manifest/upload-url`;
+        return this.putJson(uploadUrlPath, manifest, { layout: "bulk" });
+    }
+    // ---- Deprecated legacy surface (W0052) ----------------------------------
+    /** @deprecated Use `emit()` instead. */
+    async writeBulk(type, runId, data) {
+        const uploadUrlPath = `/v1/runs/${encodeURIComponent(runId)}/artifacts/${encodeURIComponent(type)}/upload-url`;
+        return this.putJson(uploadUrlPath, data, {
+            layout: "bulk",
+            entryCount: entryCountOf(data),
+        });
+    }
+    /** @deprecated Use `emit()` per entry instead. */
+    async writePerEntry(type, runId, entries) {
+        const descriptor = ARTIFACT_REGISTRY[type];
+        if (!descriptor.parseEntryKey) {
+            console.warn(`  ⚠️  writePerEntry called for "${type}" but the registry has no parseEntryKey`);
+            return null;
+        }
+        const uploaded = [];
+        let totalBytes = 0;
+        let bucket = this.options.bucket;
+        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 uploadUrlPath = `/v1/runs/${encodeURIComponent(runId)}/artifacts/${encodeURIComponent(type)}/${encodeURIComponent(entry.key)}/upload-url`;
+            const result = await this.putJsonRaw(uploadUrlPath, entry.data);
+            if (!result)
+                continue;
+            bucket = result.bucket;
+            uploaded.push({ key: entry.key, bytes: result.bytes });
+            totalBytes += result.bytes;
+        }
+        if (uploaded.length === 0)
+            return null;
+        return {
+            store: "gcs",
+            bucket,
+            path: `runs/${runId}/${descriptor.slug}`,
+            bytes: totalBytes,
+            entryCount: uploaded.length,
+            layout: "per-entry",
+            entries: uploaded,
+        };
+    }
+    // ---- Internals ----------------------------------------------------------
+    async putJson(uploadUrlPath, data, meta) {
+        const result = await this.putJsonRaw(uploadUrlPath, data);
+        if (!result)
+            return null;
+        return {
+            store: "gcs",
+            bucket: result.bucket,
+            path: result.path,
+            bytes: result.bytes,
+            entryCount: meta.entryCount,
+            layout: meta.layout,
+        };
+    }
+    async putJsonRaw(uploadUrlPath, data) {
+        const json = JSON.stringify(data);
+        const bytes = Buffer.byteLength(json, "utf-8");
+        try {
+            const signed = await this.fetchSignedUrl(uploadUrlPath);
+            if (!signed)
+                return null;
+            const putRes = await fetch(signed.url, {
+                body: json,
+                headers: signed.requiredHeaders,
+                method: "PUT",
+            });
+            if (!putRes.ok) {
+                console.warn(`  ⚠️  Artifact upload failed (non-blocking): ${signed.path} — GCS PUT ${putRes.status} ${putRes.statusText}`);
+                return null;
+            }
+            return { bucket: signed.bucket, path: signed.path, bytes };
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            console.warn(`  ⚠️  Artifact upload failed (non-blocking): ${uploadUrlPath} — ${message}`);
+            return null;
+        }
+    }
+    async fetchSignedUrl(uploadUrlPath) {
+        const url = `${this.options.apiBaseUrl.replace(/\/$/, "")}${uploadUrlPath}`;
+        const res = await fetch(url, {
+            headers: { Authorization: `Bearer ${this.options.apiKey}` },
+            method: "GET",
+        });
+        if (!res.ok) {
+            console.warn(`  ⚠️  Signed-URL request failed: ${res.status} ${res.statusText}`);
+            return null;
+        }
+        const body = (await res.json());
+        if (body.object !== "signed_upload_url" ||
+            typeof body.url !== "string" ||
+            typeof body.path !== "string" ||
+            typeof body.bucket !== "string" ||
+            !body.requiredHeaders) {
+            console.warn(`  ⚠️  Signed-URL response was malformed`);
+            return null;
+        }
+        return {
+            bucket: body.bucket,
+            method: "PUT",
+            object: "signed_upload_url",
+            path: body.path,
+            requiredHeaders: body.requiredHeaders,
+            url: body.url,
+        };
+    }
+}
+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/artifact-capture/emit-file.d.ts

@@ -0,0 +1,28 @@
+/**
+ * emitFileContents() — reads a file from disk and hands its contents to
+ * the writer's `emit()`. Shim for the legacy `captureFile(path)` pattern
+ * now that the port takes in-memory payloads.
+ *
+ * Covers the ~13 producer sites that write a file for user-facing output
+ * (e.g. promptfoo writes YAML configs and JSON results) and then need to
+ * also capture them as artifacts. Reading at emit-time is uniform, keeps
+ * the port narrow, and costs nothing at the sizes in play (all descriptors
+ * cap ≤10 MB; most are ≤256 KB).
+ *
+ * Failures are non-blocking per P5 — a missing file or unparseable JSON
+ * returns null + warns rather than throwing, so the pipeline keeps moving
+ * even if the user-facing file wasn't produced.
+ *
+ * See `tasks/plan.md § Q2` for the design rationale.
+ */
+import { type ArtifactRef, type ArtifactType, type ArtifactWriter, type AssociationValues } from "../_vendor/ailf-core/index.d.ts";
+/**
+ * Read a file from disk, parse it per the descriptor's mime, and emit it.
+ *
+ * - JSON mime: file contents are `JSON.parse`d into an object before `emit()`.
+ * - Markdown / YAML mime: file contents are passed to `emit()` as a string.
+ * - NDJSON: not supported by `emit()` — use `appendNdjson()` directly instead.
+ *
+ * Returns null (with a warn) on any error. Never throws.
+ */
+export declare function emitFileContents<T extends ArtifactType>(writer: ArtifactWriter, type: T, association: AssociationValues, filePath: string): Promise<ArtifactRef | null>;

package/dist/artifact-capture/emit-file.js

@@ -0,0 +1,56 @@
+/**
+ * emitFileContents() — reads a file from disk and hands its contents to
+ * the writer's `emit()`. Shim for the legacy `captureFile(path)` pattern
+ * now that the port takes in-memory payloads.
+ *
+ * Covers the ~13 producer sites that write a file for user-facing output
+ * (e.g. promptfoo writes YAML configs and JSON results) and then need to
+ * also capture them as artifacts. Reading at emit-time is uniform, keeps
+ * the port narrow, and costs nothing at the sizes in play (all descriptors
+ * cap ≤10 MB; most are ≤256 KB).
+ *
+ * Failures are non-blocking per P5 — a missing file or unparseable JSON
+ * returns null + warns rather than throwing, so the pipeline keeps moving
+ * even if the user-facing file wasn't produced.
+ *
+ * See `tasks/plan.md § Q2` for the design rationale.
+ */
+import { promises as fs } from "node:fs";
+import { ARTIFACT_REGISTRY, } from "../_vendor/ailf-core/index.js";
+/**
+ * Read a file from disk, parse it per the descriptor's mime, and emit it.
+ *
+ * - JSON mime: file contents are `JSON.parse`d into an object before `emit()`.
+ * - Markdown / YAML mime: file contents are passed to `emit()` as a string.
+ * - NDJSON: not supported by `emit()` — use `appendNdjson()` directly instead.
+ *
+ * Returns null (with a warn) on any error. Never throws.
+ */
+export async function emitFileContents(writer, type, association, filePath) {
+    const descriptor = ARTIFACT_REGISTRY[type];
+    if (descriptor.mime === "application/x-ndjson") {
+        console.warn(`  ⚠️  emitFileContents("${type}", ${filePath}): NDJSON types require appendNdjson(), not emit() — skipping`);
+        return null;
+    }
+    let contents;
+    try {
+        contents = await fs.readFile(filePath, "utf-8");
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        console.warn(`  ⚠️  emitFileContents read failed (non-blocking): ${filePath} — ${message}`);
+        return null;
+    }
+    let payload = contents;
+    if (descriptor.mime === "application/json") {
+        try {
+            payload = JSON.parse(contents);
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            console.warn(`  ⚠️  emitFileContents parse failed (non-blocking): ${filePath} — ${message}`);
+            return null;
+        }
+    }
+    return writer.emit(type, association, payload);
+}

package/dist/artifact-capture/fanout-artifact-writer.d.ts

@@ -0,0 +1,39 @@
+/**
+ * FanoutArtifactWriter — layers multiple writers so each `emit()` fans out
+ * to every configured backend.
+ *
+ * D0033 M4 default wiring:
+ *   `FanoutArtifactWriter([ LocalFilesystemArtifactWriter, GcsArtifactWriter ])`
+ *
+ * Semantics:
+ * - Fan out in declaration order. Every writer runs, even if earlier ones fail.
+ * - Return the **first non-null ArtifactRef**. Local is listed first, so a
+ *   local success + GCS failure still produces a non-null ref pointing at
+ *   local — the pipeline succeeds and Studio retrieval works against the
+ *   local tree with a warning logged for the GCS leg.
+ * - Failures on individual writers warn (via their own P5 paths) but do
+ *   not propagate. The fanout never throws.
+ *
+ * This writer is a composition primitive — it adds no I/O of its own.
+ * Tests verify the fanout semantics against `NoOpArtifactWriter` instances
+ * plus a recording test double.
+ *
+ * @see docs/decisions/D0033-unified-run-anchored-artifact-capture.md (§ M4)
+ */
+import type { ArtifactEntry, ArtifactRef, ArtifactType, ArtifactWriter, AssociationValues, RunId, RunManifest } from "../_vendor/ailf-core/index.d.ts";
+export declare class FanoutArtifactWriter implements ArtifactWriter {
+    private readonly writers;
+    constructor(writers: readonly ArtifactWriter[]);
+    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>;
+    /**
+     * Run `op` against every delegate writer. Any individual writer's rejected
+     * promise is caught and logged; the fanout itself never rejects.
+     */
+    private runAll;
+}

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

@@ -0,0 +1,76 @@
+/**
+ * FanoutArtifactWriter — layers multiple writers so each `emit()` fans out
+ * to every configured backend.
+ *
+ * D0033 M4 default wiring:
+ *   `FanoutArtifactWriter([ LocalFilesystemArtifactWriter, GcsArtifactWriter ])`
+ *
+ * Semantics:
+ * - Fan out in declaration order. Every writer runs, even if earlier ones fail.
+ * - Return the **first non-null ArtifactRef**. Local is listed first, so a
+ *   local success + GCS failure still produces a non-null ref pointing at
+ *   local — the pipeline succeeds and Studio retrieval works against the
+ *   local tree with a warning logged for the GCS leg.
+ * - Failures on individual writers warn (via their own P5 paths) but do
+ *   not propagate. The fanout never throws.
+ *
+ * This writer is a composition primitive — it adds no I/O of its own.
+ * Tests verify the fanout semantics against `NoOpArtifactWriter` instances
+ * plus a recording test double.
+ *
+ * @see docs/decisions/D0033-unified-run-anchored-artifact-capture.md (§ M4)
+ */
+export class FanoutArtifactWriter {
+    writers;
+    constructor(writers) {
+        if (writers.length === 0) {
+            throw new Error("FanoutArtifactWriter requires at least one delegate writer");
+        }
+        this.writers = writers;
+    }
+    async emit(type, association, payload) {
+        const refs = await this.runAll((w) => w.emit(type, association, payload));
+        return firstNonNull(refs);
+    }
+    async appendNdjson(type, association, rows) {
+        const refs = await this.runAll((w) => w.appendNdjson(type, association, rows));
+        return firstNonNull(refs);
+    }
+    async writeManifest(runId, manifest) {
+        const refs = await this.runAll((w) => w.writeManifest(runId, manifest));
+        return firstNonNull(refs);
+    }
+    /** @deprecated Use `emit()` instead. */
+    async writeBulk(type, runId, data) {
+        const refs = await this.runAll((w) => w.writeBulk(type, runId, data));
+        return firstNonNull(refs);
+    }
+    /** @deprecated Use `emit()` per entry instead. */
+    async writePerEntry(type, runId, entries) {
+        const refs = await this.runAll((w) => w.writePerEntry(type, runId, entries));
+        return firstNonNull(refs);
+    }
+    /**
+     * Run `op` against every delegate writer. Any individual writer's rejected
+     * promise is caught and logged; the fanout itself never rejects.
+     */
+    async runAll(op) {
+        return Promise.all(this.writers.map(async (writer) => {
+            try {
+                return await op(writer);
+            }
+            catch (err) {
+                const message = err instanceof Error ? err.message : String(err);
+                console.warn(`  ⚠️  Fanout delegate threw (non-blocking): ${writer.constructor.name} — ${message}`);
+                return null;
+            }
+        }));
+    }
+}
+function firstNonNull(refs) {
+    for (const ref of refs) {
+        if (ref !== null)
+            return ref;
+    }
+    return null;
+}

package/dist/artifact-capture/filesystem-collector.d.ts

@@ -1,14 +1,32 @@
 /**
- * FilesystemArtifactCollector — writes captured artifacts to a local directory.
+ * FilesystemArtifactCollector — DEPRECATED legacy capture path.
  *
- * Accumulates artifact entries in memory during pipeline execution.
- * On flush(), creates a structured directory with one subdirectory per
- * step, writes all artifacts, and generates a manifest.json.
+ * W0050 Slice 5: the unified artifact writer (`ctx.artifactWriter.emit()`)
+ * owns artifact production starting this release. This class is retained
+ * for one release cycle so producer steps that haven't migrated yet still
+ * have a surface to call against; W0052 deletes the class + port.
+ *
+ * Behavioral changes vs. pre-W0050:
+ *
+ * - **No tarball.** The `compress` option is ignored; flush() always writes
+ *   a loose directory tree. The legacy `.tar.gz` artifact archive is no
+ *   longer produced (D0033 AC8 — "no new capture tarballs").
+ * - **First-call deprecation warning.** The first invocation of capture()
+ *   or captureFile() on any instance emits a one-time-per-process warning
+ *   pointing callers at `ctx.artifactWriter.emit()`.
+ *
+ * Everything else (in-memory accumulation, redaction, loose-file output at
+ * flush time) is unchanged — existing tests continue to pass. This is the
+ * **minimum** pass-through posture. Full delegation to
+ * `LocalFilesystemArtifactWriter` is W0052 scope, at which point the port
+ * and this class are both deleted.
  *
  * Design principles:
  * - capture() and captureFile() are synchronous (no I/O during step execution)
  * - flush() does all I/O at pipeline end
  * - Failures in capture/captureFile are swallowed (P5: non-blocking)
+ *
+ * @deprecated Use `ctx.artifactWriter.emit()` instead; removal scheduled for W0052.
  */
 import type { ArtifactCollector, CaptureFlushResult } from "../_vendor/ailf-core/index.d.ts";
 export interface FilesystemCollectorOptions {