@sanity/ailf 2.8.0 → 3.0.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

@@ -10,15 +10,24 @@
  *   - Per-entry: GET  {apiBaseUrl}/v1/runs/{runId}/artifacts/{type}/{entryKey}/upload-url
  *   - Manifest:  GET  {apiBaseUrl}/v1/runs/{runId}/artifacts/manifest/upload-url
  *
- * The Gateway routes are wired in Phase 10 (W0047).
+ * ## 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 failure returns null and warns, never throws.
+ * - 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 RunId, type RunManifest } from "../_vendor/ailf-core/index.d.ts";
+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;
@@ -30,9 +39,13 @@ export interface ApiGatewayArtifactWriterOptions {
 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>;
-    writeManifest(runId: RunId, manifest: RunManifest): Promise<ArtifactRef | null>;
     private putJson;
     private putJsonRaw;
     private fetchSignedUrl;

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

@@ -10,20 +10,73 @@
  *   - Per-entry: GET  {apiBaseUrl}/v1/runs/{runId}/artifacts/{type}/{entryKey}/upload-url
  *   - Manifest:  GET  {apiBaseUrl}/v1/runs/{runId}/artifacts/manifest/upload-url
  *
- * The Gateway routes are wired in Phase 10 (W0047).
+ * ## 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 failure returns null and warns, never throws.
+ * - 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, } from "../_vendor/ailf-core/index.js";
+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, {
@@ -31,6 +84,7 @@ export class ApiGatewayArtifactWriter {
             entryCount: entryCountOf(data),
         });
     }
+    /** @deprecated Use `emit()` per entry instead. */
     async writePerEntry(type, runId, entries) {
         const descriptor = ARTIFACT_REGISTRY[type];
         if (!descriptor.parseEntryKey) {
@@ -66,10 +120,7 @@ export class ApiGatewayArtifactWriter {
             entries: uploaded,
         };
     }
-    async writeManifest(runId, manifest) {
-        const uploadUrlPath = `/v1/runs/${encodeURIComponent(runId)}/artifacts/manifest/upload-url`;
-        return this.putJson(uploadUrlPath, manifest, { layout: "bulk" });
-    }
+    // ---- Internals ----------------------------------------------------------
     async putJson(uploadUrlPath, data, meta) {
         const result = await this.putJsonRaw(uploadUrlPath, data);
         if (!result)

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/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;
 }