@sanity/ailf 2.8.0 → 2.9.0

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 {

package/dist/artifact-capture/filesystem-collector.js

@@ -1,17 +1,34 @@
 /**
- * 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 { execFileSync } from "node:child_process";
-import { copyFileSync, mkdirSync, readFileSync, rmSync, statSync, writeFileSync, } from "node:fs";
+import { copyFileSync, mkdirSync, readFileSync, statSync, writeFileSync, } from "node:fs";
 import path from "node:path";
 import { redactArtifactData } from "./redact-artifact.js";
 // ---------------------------------------------------------------------------
@@ -69,6 +86,17 @@ function fileExtension(format) {
 // ---------------------------------------------------------------------------
 // Collector
 // ---------------------------------------------------------------------------
+/**
+ * Module-level flag so the W0050 deprecation warning fires exactly once
+ * per process even when multiple collectors are constructed.
+ */
+let warnedLegacyCollector = false;
+function warnLegacyCollectorOnce() {
+    if (warnedLegacyCollector)
+        return;
+    warnedLegacyCollector = true;
+    console.warn("FilesystemArtifactCollector is deprecated (W0050). Producers should migrate to ctx.artifactWriter.emit(); this class will be removed in W0052.");
+}
 export class FilesystemArtifactCollector {
     enabled = true;
     extrasEnabled;
@@ -89,6 +117,7 @@ export class FilesystemArtifactCollector {
         this.outputDir = path.join(options.captureDir, `${options.mode}-${timestamp}-${shortId}`);
     }
     capture(step, type, data, meta) {
+        warnLegacyCollectorOnce();
         try {
             this.entries.push({
                 step,
@@ -103,6 +132,7 @@ export class FilesystemArtifactCollector {
         }
     }
     captureFile(step, type, filePath, meta) {
+        warnLegacyCollectorOnce();
         try {
             this.entries.push({
                 step,
@@ -208,24 +238,12 @@ export class FilesystemArtifactCollector {
         };
         const manifestContent = JSON.stringify(manifest, null, 2);
         writeFileSync(path.join(this.outputDir, "manifest.json"), manifestContent, "utf-8");
-        // Compress to tar.gz if configured
+        // W0050 Slice 5 — compression disabled unconditionally. The legacy
+        // .tar.gz archive is no longer produced (D0033 AC8 "no new capture
+        // tarballs"); callers that asked for it get the loose directory plus
+        // a one-time warning.
         if (this.options.compress) {
-            try {
-                const archivePath = `${this.outputDir}.tar.gz`;
-                const parentDir = path.dirname(this.outputDir);
-                const dirName = path.basename(this.outputDir);
-                execFileSync("tar", ["-czf", archivePath, "-C", parentDir, dirName]);
-                rmSync(this.outputDir, { recursive: true });
-                return {
-                    artifactCount: manifestEntries.length,
-                    destination: archivePath,
-                    totalBytes,
-                    compressed: true,
-                };
-            }
-            catch {
-                // Non-blocking: compression failed, keep the raw directory
-            }
+            warnTarballSuppressedOnce();
         }
         return {
             artifactCount: manifestEntries.length,
@@ -235,3 +253,10 @@ export class FilesystemArtifactCollector {
         };
     }
 }
+let warnedTarballSuppressed = false;
+function warnTarballSuppressedOnce() {
+    if (warnedTarballSuppressed)
+        return;
+    warnedTarballSuppressed = true;
+    console.warn("capture.compress is deprecated (W0050); tarball output is no longer produced. The loose directory at <captureDir>/<run>-<ts>-<id>/ contains the same files.");
+}

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

@@ -7,24 +7,61 @@
  *
  * 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 { type ArtifactEntry, type ArtifactRef, type ArtifactType, type ArtifactWriter, type RunId, type RunManifest } from "../_vendor/ailf-core/index.d.ts";
+import { Storage } from "@google-cloud/storage";
+import { type ArtifactEntry, type ArtifactRef, type ArtifactType, type ArtifactWriter, type AssociationValues, type RunId, type RunManifest } from "../_vendor/ailf-core/index.d.ts";
 export interface GcsArtifactWriterOptions {
     /** GCS bucket name (e.g., "ailf-artifacts") */
     bucket: string;
+    /**
+     * Optional pre-constructed Storage client. When omitted the writer
+     * constructs one lazily from Application Default Credentials. Test code
+     * supplies a fake here to avoid real network calls.
+     */
+    storage?: Storage;
 }
 export declare class GcsArtifactWriter implements ArtifactWriter {
     private client;
     private readonly options;
+    private readonly ndjsonStreams;
     constructor(options: GcsArtifactWriterOptions);
+    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. Routes through the same GCS I/O. */
     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>;
-    writeManifest(runId: RunId, manifest: RunManifest): Promise<ArtifactRef | null>;
-    private putJson;
+    /**
+     * 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.
+     */
+    private finalizeNdjsonStreams;
+    private putBody;
     private getClient;
 }