@sanity/ailf 2.7.1 → 2.9.0

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

@@ -0,0 +1,67 @@
+/**
+ * GcsArtifactWriter — writes AILF run artifacts + manifest directly to GCS.
+ *
+ * Uses Application Default Credentials (ADC). Used when the CLI runs in CI or
+ * anywhere ADC is configured — the client talks to GCS without the API Gateway
+ * acting as a middleman.
+ *
+ * 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 { 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>;
+    /**
+     * 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;
+}

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

@@ -0,0 +1,343 @@
+/**
+ * GcsArtifactWriter — writes AILF run artifacts + manifest directly to GCS.
+ *
+ * Uses Application Default Credentials (ADC). Used when the CLI runs in CI or
+ * anywhere ADC is configured — the client talks to GCS without the API Gateway
+ * acting as a middleman.
+ *
+ * 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, 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);
+        const redacted = redactArtifactData(data);
+        return this.putBody(path, serializeForMime(redacted, descriptor.mime), {
+            layout: "bulk",
+            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("${type}"): descriptor has no parseEntryKey`);
+            return null;
+        }
+        const storage = this.getClient();
+        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 path = descriptor.objectPath(runId, entry.key);
+            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(body, { contentType: descriptor.mime });
+                uploaded.push({ key: entry.key, bytes });
+                totalBytes += bytes;
+            }
+            catch (err) {
+                const message = err instanceof Error ? err.message : String(err);
+                console.warn(`  ⚠️  Artifact entry upload failed (non-blocking): ${path} — ${message}`);
+            }
+        }
+        if (uploaded.length === 0)
+            return null;
+        return {
+            store: "gcs",
+            bucket: this.options.bucket,
+            path: `runs/${runId}/${descriptor.slug}`,
+            bytes: totalBytes,
+            entryCount: uploaded.length,
+            layout: "per-entry",
+            entries: uploaded,
+        };
+    }
+    // ---- 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 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(body, { contentType: meta.mime });
+            return {
+                store: "gcs",
+                bucket: this.options.bucket,
+                path,
+                bytes,
+                entryCount: meta.entryCount,
+                layout: meta.layout,
+            };
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            console.warn(`  ⚠️  Artifact upload failed (non-blocking): ${path} — ${message}`);
+            return null;
+        }
+    }
+    getClient() {
+        if (this.client)
+            return this.client;
+        this.client = new Storage();
+        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 &&
+        "entries" in data &&
+        typeof data.entries === "object") {
+        return Object.keys(data.entries)
+            .length;
+    }
+    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;
+}