@sanity/ailf 3.0.0 → 3.1.1

package/dist/artifact-capture/parallel-emit.d.ts

@@ -0,0 +1,43 @@
+/**
+ * parallel-emit.ts — W0056 prototype A (client-side parallelism).
+ *
+ * Bounded-concurrency helper for fanning out artifact emits. The baseline
+ * measurement (see `docs/design-docs/artifact-upload-throughput.md`) shows
+ * producer loops call `await writer.emit(...)` serially, and per-artifact
+ * wall clock is dominated by GCS response latency. A simple `p-limit(N)`
+ * turns that into a batched-parallel flow against the existing writers.
+ *
+ * Gated on `AILF_PARALLEL_UPLOAD`:
+ *   - unset → use the per-writer default set at composition time.
+ *   - "0" → forced serial (override when default-on is undesirable).
+ *   - "1" → parallel, default concurrency 8.
+ *   - "<N>" (N > 1 integer) → parallel with concurrency N.
+ *
+ * The per-writer default is set by the composition root via
+ * `setDefaultUploadConcurrency`. Writers with measured safe parallelism
+ * (GCS direct) set 8; writers still on serial (API Gateway, until the
+ * batching rollout completes) leave it at the module default of 1.
+ */
+/**
+ * Set the default concurrency used when `AILF_PARALLEL_UPLOAD` is unset.
+ * Composition root calls this once per run based on the selected remote
+ * writer. Tests reset by passing 1.
+ */
+export declare function setDefaultUploadConcurrency(n: number): void;
+/** Exposed for tests — returns the current module default. */
+export declare function getDefaultUploadConcurrency(): number;
+/**
+ * Resolve the configured concurrency. Returns 1 (serial) when parallelism is
+ * explicitly disabled or the env value is invalid; otherwise returns the
+ * per-writer module default when `AILF_PARALLEL_UPLOAD` is unset.
+ */
+export declare function resolveUploadConcurrency(): number;
+/**
+ * Run `fn` against every item with at most `concurrency` active at once.
+ * Preserves input order in the result array. Rejections propagate — callers
+ * with non-blocking semantics should catch inside `fn`.
+ *
+ * When `concurrency <= 1`, runs strictly serially (drop-in equivalent of a
+ * `for … await` loop).
+ */
+export declare function parallelMap<T, R>(items: readonly T[], concurrency: number, fn: (item: T, index: number) => Promise<R>): Promise<R[]>;

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

@@ -0,0 +1,84 @@
+/**
+ * parallel-emit.ts — W0056 prototype A (client-side parallelism).
+ *
+ * Bounded-concurrency helper for fanning out artifact emits. The baseline
+ * measurement (see `docs/design-docs/artifact-upload-throughput.md`) shows
+ * producer loops call `await writer.emit(...)` serially, and per-artifact
+ * wall clock is dominated by GCS response latency. A simple `p-limit(N)`
+ * turns that into a batched-parallel flow against the existing writers.
+ *
+ * Gated on `AILF_PARALLEL_UPLOAD`:
+ *   - unset → use the per-writer default set at composition time.
+ *   - "0" → forced serial (override when default-on is undesirable).
+ *   - "1" → parallel, default concurrency 8.
+ *   - "<N>" (N > 1 integer) → parallel with concurrency N.
+ *
+ * The per-writer default is set by the composition root via
+ * `setDefaultUploadConcurrency`. Writers with measured safe parallelism
+ * (GCS direct) set 8; writers still on serial (API Gateway, until the
+ * batching rollout completes) leave it at the module default of 1.
+ */
+const DEFAULT_CONCURRENCY = 8;
+let moduleDefault = 1;
+/**
+ * Set the default concurrency used when `AILF_PARALLEL_UPLOAD` is unset.
+ * Composition root calls this once per run based on the selected remote
+ * writer. Tests reset by passing 1.
+ */
+export function setDefaultUploadConcurrency(n) {
+    moduleDefault = n >= 1 ? n : 1;
+}
+/** Exposed for tests — returns the current module default. */
+export function getDefaultUploadConcurrency() {
+    return moduleDefault;
+}
+/**
+ * Resolve the configured concurrency. Returns 1 (serial) when parallelism is
+ * explicitly disabled or the env value is invalid; otherwise returns the
+ * per-writer module default when `AILF_PARALLEL_UPLOAD` is unset.
+ */
+export function resolveUploadConcurrency() {
+    const raw = process.env.AILF_PARALLEL_UPLOAD ?? "";
+    if (raw === "0")
+        return 1;
+    if (raw === "")
+        return moduleDefault;
+    if (raw === "1")
+        return DEFAULT_CONCURRENCY;
+    const parsed = Number.parseInt(raw, 10);
+    if (Number.isFinite(parsed) && parsed > 1)
+        return parsed;
+    return moduleDefault;
+}
+/**
+ * Run `fn` against every item with at most `concurrency` active at once.
+ * Preserves input order in the result array. Rejections propagate — callers
+ * with non-blocking semantics should catch inside `fn`.
+ *
+ * When `concurrency <= 1`, runs strictly serially (drop-in equivalent of a
+ * `for … await` loop).
+ */
+export async function parallelMap(items, concurrency, fn) {
+    if (items.length === 0)
+        return [];
+    if (concurrency <= 1) {
+        const out = [];
+        for (let i = 0; i < items.length; i++) {
+            out.push(await fn(items[i], i));
+        }
+        return out;
+    }
+    const results = new Array(items.length);
+    let cursor = 0;
+    async function worker() {
+        while (true) {
+            const i = cursor++;
+            if (i >= items.length)
+                return;
+            results[i] = await fn(items[i], i);
+        }
+    }
+    const width = Math.min(concurrency, items.length);
+    await Promise.all(Array.from({ length: width }, () => worker()));
+    return results;
+}

package/dist/artifact-capture/upload-metrics.d.ts

@@ -0,0 +1,62 @@
+/**
+ * UploadMetrics — spike instrumentation for W0056 (faster artifact upload).
+ *
+ * Captures per-operation timing on the artifact-upload path so the spike has
+ * a measured baseline: artifact count, total bytes, wall-clock, and the
+ * sign-RTT vs. PUT split. Gated on `AILF_UPLOAD_METRICS=1` in the composition
+ * root — a no-op when off.
+ *
+ * Design:
+ * - `UploadMetricsSink` is the narrow interface that writers depend on.
+ * - `UploadMetrics` is the in-process implementation that buffers events
+ *   and emits both a stderr summary table and an NDJSON detail file.
+ * - `summarize()` is called by `InstrumentedArtifactWriter` once, after
+ *   `writeManifest` succeeds (the natural end-of-run signal).
+ *
+ * This file is a spike deliverable — the API is intentionally ad hoc and
+ * may be promoted to `packages/core/src/ports/` if we ship anything.
+ */
+import type { Logger } from "../_vendor/ailf-core/index.d.ts";
+export type UploadPhase = "sign" | "put" | "compose" | "emit" | "ndjson-part" | "manifest";
+export interface UploadMetricEvent {
+    /** ISO timestamp the event was recorded. */
+    ts: string;
+    /** Phase being measured — writers record `sign`/`put`/`compose` at the call site; the decorator records `emit`/`ndjson-part`/`manifest` end-to-end. */
+    phase: UploadPhase;
+    /** Writer class that produced the event (e.g. "ApiGatewayArtifactWriter"). */
+    writer: string;
+    /** Artifact type (or `"manifest"`). */
+    type: string;
+    /** Wall-clock for the phase, in milliseconds. */
+    ms: number;
+    /** Body size in bytes, when applicable. */
+    bytes?: number;
+    /** True when the underlying call resolved without throwing / without a non-2xx response. */
+    success: boolean;
+}
+export interface UploadMetricsSink {
+    record(event: Omit<UploadMetricEvent, "ts">): void;
+}
+/**
+ * No-op sink — writers default to this when metrics are off, so the
+ * instrumentation call sites remain uniform whether or not the collector is
+ * active.
+ */
+export declare const NO_OP_UPLOAD_METRICS: UploadMetricsSink;
+export interface UploadMetricsOptions {
+    /** Logger used for the summary table. */
+    logger: Logger;
+    /** Absolute path where the NDJSON detail file is written. Skipped when undefined. */
+    detailFile?: string;
+}
+export declare class UploadMetrics implements UploadMetricsSink {
+    private readonly options;
+    private readonly events;
+    private summarized;
+    constructor(options: UploadMetricsOptions);
+    record(event: Omit<UploadMetricEvent, "ts">): void;
+    summarize(): Promise<void>;
+    /** Exposed for tests — returns a copy. */
+    snapshot(): readonly UploadMetricEvent[];
+}
+export declare function buildSummaryTable(events: readonly UploadMetricEvent[]): string;

package/dist/artifact-capture/upload-metrics.js

@@ -0,0 +1,125 @@
+/**
+ * UploadMetrics — spike instrumentation for W0056 (faster artifact upload).
+ *
+ * Captures per-operation timing on the artifact-upload path so the spike has
+ * a measured baseline: artifact count, total bytes, wall-clock, and the
+ * sign-RTT vs. PUT split. Gated on `AILF_UPLOAD_METRICS=1` in the composition
+ * root — a no-op when off.
+ *
+ * Design:
+ * - `UploadMetricsSink` is the narrow interface that writers depend on.
+ * - `UploadMetrics` is the in-process implementation that buffers events
+ *   and emits both a stderr summary table and an NDJSON detail file.
+ * - `summarize()` is called by `InstrumentedArtifactWriter` once, after
+ *   `writeManifest` succeeds (the natural end-of-run signal).
+ *
+ * This file is a spike deliverable — the API is intentionally ad hoc and
+ * may be promoted to `packages/core/src/ports/` if we ship anything.
+ */
+import { mkdir, writeFile } from "node:fs/promises";
+import { dirname } from "node:path";
+// ---------------------------------------------------------------------------
+// Implementation
+// ---------------------------------------------------------------------------
+/**
+ * No-op sink — writers default to this when metrics are off, so the
+ * instrumentation call sites remain uniform whether or not the collector is
+ * active.
+ */
+export const NO_OP_UPLOAD_METRICS = {
+    record() { },
+};
+export class UploadMetrics {
+    options;
+    events = [];
+    summarized = false;
+    constructor(options) {
+        this.options = options;
+    }
+    record(event) {
+        this.events.push({ ...event, ts: new Date().toISOString() });
+    }
+    async summarize() {
+        if (this.summarized)
+            return;
+        this.summarized = true;
+        const { logger, detailFile } = this.options;
+        if (this.events.length === 0) {
+            logger.info("[upload-metrics] no events recorded");
+            return;
+        }
+        const table = buildSummaryTable(this.events);
+        logger.info(`[upload-metrics] ${this.events.length} events recorded\n${table}`);
+        if (detailFile) {
+            try {
+                await mkdir(dirname(detailFile), { recursive: true });
+                const body = this.events.map((e) => JSON.stringify(e)).join("\n") + "\n";
+                await writeFile(detailFile, body, "utf-8");
+                logger.info(`[upload-metrics] detail written to ${detailFile}`);
+            }
+            catch (err) {
+                const message = err instanceof Error ? err.message : String(err);
+                logger.warn(`[upload-metrics] failed to write detail file "${detailFile}": ${message}`);
+            }
+        }
+    }
+    /** Exposed for tests — returns a copy. */
+    snapshot() {
+        return [...this.events];
+    }
+}
+export function buildSummaryTable(events) {
+    const byKey = new Map();
+    for (const ev of events) {
+        const key = `${ev.phase}\t${ev.writer}`;
+        let bucket = byKey.get(key);
+        if (!bucket) {
+            bucket = [];
+            byKey.set(key, bucket);
+        }
+        bucket.push(ev);
+    }
+    const rows = [];
+    for (const [key, bucket] of byKey) {
+        const phase = key.split("\t").join(" · ");
+        const durations = bucket.map((e) => e.ms).sort((a, b) => a - b);
+        const totalMs = durations.reduce((sum, ms) => sum + ms, 0);
+        const totalBytes = bucket.reduce((sum, e) => sum + (e.bytes ?? 0), 0);
+        const failures = bucket.filter((e) => !e.success).length;
+        rows.push({
+            phase,
+            count: bucket.length,
+            failures,
+            totalMs,
+            totalBytes,
+            p50: percentile(durations, 0.5),
+            p95: percentile(durations, 0.95),
+            max: durations[durations.length - 1] ?? 0,
+        });
+    }
+    rows.sort((a, b) => b.totalMs - a.totalMs);
+    const header = "phase                                          |  n  | fail |  bytes      | total ms | p50 | p95 | max";
+    const sep = "-----------------------------------------------+-----+------+-------------+----------+-----+-----+-----";
+    const body = rows
+        .map((r) => `${pad(r.phase, 47)}| ${pad(String(r.count), 4)}| ${pad(String(r.failures), 5)}| ${pad(formatBytes(r.totalBytes), 12)}| ${pad(String(Math.round(r.totalMs)), 9)}| ${pad(String(Math.round(r.p50)), 4)}| ${pad(String(Math.round(r.p95)), 4)}| ${Math.round(r.max)}`)
+        .join("\n");
+    return `${header}\n${sep}\n${body}`;
+}
+function percentile(sorted, p) {
+    if (sorted.length === 0)
+        return 0;
+    const idx = Math.min(sorted.length - 1, Math.max(0, Math.ceil(sorted.length * p) - 1));
+    return sorted[idx] ?? 0;
+}
+function pad(s, width) {
+    return s.length >= width ? `${s} ` : s + " ".repeat(width - s.length);
+}
+function formatBytes(n) {
+    if (n < 1024)
+        return `${n} B`;
+    if (n < 1024 * 1024)
+        return `${(n / 1024).toFixed(1)} KB`;
+    if (n < 1024 * 1024 * 1024)
+        return `${(n / 1024 / 1024).toFixed(1)} MB`;
+    return `${(n / 1024 / 1024 / 1024).toFixed(2)} GB`;
+}

package/dist/composition-root.d.ts

@@ -15,7 +15,7 @@
  * @see packages/core/src/ports/context.ts — AppContext interface
  * @see docs/archive/exec-plans/ports-and-adapters/phase-7-composition-root.md
  */
-import { type AppContext, type ArtifactWriter, type AssertionRegistration, type Logger, type ResolvedConfig } from "./_vendor/ailf-core/index.d.ts";
+import { type AppContext, type ArtifactWriter, type ArtifactWriterProgressOptions, type AssertionRegistration, type Logger, type ResolvedConfig } from "./_vendor/ailf-core/index.d.ts";
 /**
  * Create a fully wired AppContext from resolved configuration.
  *
@@ -41,7 +41,7 @@ export declare function createAppContext(config: ResolvedConfig): AppContext;
  *
  * Exported for unit-test access; not part of the public package API.
  */
-export declare function createArtifactWriter(config: ResolvedConfig, logger: Logger): ArtifactWriter;
+export declare function createArtifactWriter(config: ResolvedConfig, logger: Logger, progress?: ArtifactWriterProgressOptions): ArtifactWriter;
 /**
  * Generic Promptfoo assertion types available to all evaluation modes.
  *

package/dist/composition-root.js

@@ -15,17 +15,22 @@
  * @see packages/core/src/ports/context.ts — AppContext interface
  * @see docs/archive/exec-plans/ports-and-adapters/phase-7-composition-root.md
  */
-import { InMemoryPluginRegistry, NoOpArtifactWriter, generateRunId, isArtifactType, } from "./_vendor/ailf-core/index.js";
+import { ARTIFACT_EXPORT_PHASE_ID, InMemoryPluginRegistry, NoOpArtifactWriter, NoOpProgressReporter, generateRunId, isArtifactType, } from "./_vendor/ailf-core/index.js";
 import { AccumulatingArtifactWriter } from "./artifact-capture/accumulating-artifact-writer.js";
 import { ApiGatewayArtifactWriter } from "./artifact-capture/api-gateway-artifact-writer.js";
+import { BatchingApiGatewayArtifactWriter } from "./artifact-capture/batching-api-gateway-artifact-writer.js";
 import { FanoutArtifactWriter } from "./artifact-capture/fanout-artifact-writer.js";
 import { GcsArtifactWriter } from "./artifact-capture/gcs-artifact-writer.js";
+import { InstrumentedArtifactWriter } from "./artifact-capture/instrumented-artifact-writer.js";
 import { LocalFilesystemArtifactWriter } from "./artifact-capture/local-fs-artifact-writer.js";
+import { resolveUploadConcurrency, setDefaultUploadConcurrency, } from "./artifact-capture/parallel-emit.js";
+import { UploadMetrics } from "./artifact-capture/upload-metrics.js";
 import { ContentLakeCacheAdapter } from "./adapters/cache/content-lake-cache.js";
 import { loadExternalPresets } from "./pipeline/compiler/preset-loader.js";
 import { FilesystemCache } from "./adapters/cache/filesystem-cache.js";
 import { PromptfooEvalAdapter } from "./adapters/eval-runners/promptfoo-eval-adapter.js";
 import { ConsoleLogger, JsonLogger, QuietLogger, } from "./adapters/loggers/index.js";
+import { ConsoleProgressReporter } from "./adapters/progress/console-progress-reporter.js";
 import { CompositeTaskSource, ContentLakeTaskSource, RepoTaskSource, } from "./adapters/task-sources/index.js";
 import { createAgentHarnessBase, createKnowledgeProbeBase, createLiteracyModeBase, createMcpServerModeBase, } from "./pipeline/compiler/mode-bases/index.js";
 import { createSanityLiteracyPreset } from "./pipeline/compiler/presets/index.js";
@@ -41,6 +46,9 @@ import { loadSinks } from "./sinks/index.js";
 export function createAppContext(config) {
     // Logger — selected by env var preferences
     const logger = createLogger();
+    // Progress reporter — console-backed for the default logger; no-op for
+    // JSON/quiet modes and tests where interactive output is inappropriate.
+    const progress = createProgressReporter();
     // Cache — filesystem, optionally decorated with Content Lake fallback
     const cache = config.noCache ? undefined : createCache(config);
     // Task source — selected by config.taskSourceType
@@ -64,7 +72,12 @@ export function createAppContext(config) {
     // `runs/{runId}/…` paths (D0032). Auto-detects the right adapter from
     // available credentials; defaults bucket to "ailf-artifacts". Set
     // artifactUpload: false to opt out entirely.
-    const artifactWriter = createArtifactWriter(config, logger);
+    // W0053 — writers receive a progress reporter scoped to a single
+    // `artifact-export` phase so the CLI can render per-batch updates.
+    const artifactWriter = createArtifactWriter(config, logger, {
+        reporter: progress,
+        phaseId: ARTIFACT_EXPORT_PHASE_ID,
+    });
     // Generate the pipeline's RunId once; every downstream step reads it
     // from the context (D0032).
     const runId = generateRunId();
@@ -76,6 +89,7 @@ export function createAppContext(config) {
         docFetcher,
         evalRunner,
         logger,
+        progress,
         registry,
         reportStore,
         runId,
@@ -98,6 +112,23 @@ function createLogger() {
             process.env.AILF_VERBOSE === "1",
     });
 }
+/**
+ * Select a ProgressReporter adapter. Matches the logger environment — JSON
+ * and quiet loggers get a no-op reporter so machine-readable output stays
+ * clean; interactive sessions get the console adapter with verbose mirroring.
+ */
+function createProgressReporter() {
+    if (process.env.AILF_LOG_FORMAT === "json")
+        return new NoOpProgressReporter();
+    if (process.env.AILF_LOG_LEVEL === "quiet" ||
+        process.env.AILF_QUIET === "1") {
+        return new NoOpProgressReporter();
+    }
+    return new ConsoleProgressReporter({
+        verbose: process.env.AILF_LOG_LEVEL === "verbose" ||
+            process.env.AILF_VERBOSE === "1",
+    });
+}
 /**
  * Shared GCS bucket for report artifacts. Matches the gateway default at
  * packages/api/src/routes/artifacts.ts — both sides assume ailf-artifacts
@@ -129,7 +160,7 @@ const DEFAULT_LOCAL_ARTIFACTS_DIR = ".ailf/results/captures";
  *
  * Exported for unit-test access; not part of the public package API.
  */
-export function createArtifactWriter(config, logger) {
+export function createArtifactWriter(config, logger, progress) {
     // Legacy `artifactUpload: false` still disables — treat as an alias for
     // the canonical `artifactsDisabled: true` until W0052 removes it.
     if (config.artifactsDisabled === true || config.artifactUpload === false) {
@@ -138,10 +169,27 @@ export function createArtifactWriter(config, logger) {
     }
     const exclude = resolveExcludeList(config.artifactsExclude, logger);
     const rootDir = config.artifactsDir ?? DEFAULT_LOCAL_ARTIFACTS_DIR;
-    const local = new LocalFilesystemArtifactWriter({ rootDir, exclude });
-    const remote = createRemoteArtifactWriter(config, logger);
+    // W0056 — opt-in measurement of the upload path. The collector is passed
+    // to the remote writer (where sign/PUT/compose phases live) AND wraps the
+    // final writer to record caller-observed `emit`/`writeManifest` totals.
+    // `summarize()` fires from the decorator's `writeManifest` hook.
+    const metrics = process.env.AILF_UPLOAD_METRICS === "1"
+        ? new UploadMetrics({
+            logger,
+            detailFile: `${rootDir}/upload-metrics/run-${Date.now()}.ndjson`,
+        })
+        : null;
+    // W0053: progress attaches to the OUTERMOST of (local-only | fanout). When
+    // fanout is wired, the delegates stay silent so we don't double-count the
+    // same caller-visible write across two backends.
+    const remote = createRemoteArtifactWriter(config, logger, metrics);
+    const local = new LocalFilesystemArtifactWriter({
+        rootDir,
+        exclude,
+        ...(remote ? {} : { progress }),
+    });
     const base = remote
-        ? new FanoutArtifactWriter([local, remote])
+        ? new FanoutArtifactWriter([local, remote], { progress })
         : local;
     if (!remote) {
         logger.debug(`Artifact writer: LocalFilesystemArtifactWriter only (rootDir=${rootDir})`);
@@ -153,7 +201,10 @@ export function createArtifactWriter(config, logger) {
     // RunManifest without each producer bookkeeping its own ArtifactRefs
     // (W0051 Slice 3 revisit — Option B of the "manifest empty on real runs"
     // fix).
-    return new AccumulatingArtifactWriter(base);
+    const accumulating = new AccumulatingArtifactWriter(base);
+    return metrics
+        ? new InstrumentedArtifactWriter(accumulating, metrics)
+        : accumulating;
 }
 /**
  * Validate the exclude list against the registry. Unknown types are dropped
@@ -179,19 +230,54 @@ function resolveExcludeList(raw, logger) {
  * the sole backend for that run, which is the D0033 M4 default for laptops
  * and CI without GCS creds.
  */
-function createRemoteArtifactWriter(config, logger) {
+function createRemoteArtifactWriter(config, logger, metrics) {
     const bucket = config.artifactGcsBucket ?? DEFAULT_ARTIFACT_BUCKET;
     const hasGcsCredentials = Boolean(process.env.GOOGLE_APPLICATION_CREDENTIALS || process.env.GCLOUD_PROJECT);
     if (hasGcsCredentials) {
-        logger.debug(`Artifact remote backend: GcsArtifactWriter (ADC, bucket=${bucket})`);
-        return new GcsArtifactWriter({ bucket });
+        // W0056 Phase 1: the GCS-direct path measured 0 failures at
+        // concurrency 8 with a 60 % pipeline-time reduction. Flip parallelism
+        // on by default on this path. `AILF_PARALLEL_UPLOAD=0` still forces
+        // serial as an escape hatch.
+        setDefaultUploadConcurrency(8);
+        logger.debug(`Artifact remote backend: GcsArtifactWriter (ADC, bucket=${bucket}, defaultConcurrency=8)`);
+        return new GcsArtifactWriter({
+            bucket,
+            ...(metrics ? { metrics } : {}),
+        });
     }
     if (config.apiKey && config.apiUrl) {
-        logger.debug(`Artifact remote backend: ApiGatewayArtifactWriter (via ${config.apiUrl}, bucket=${bucket})`);
+        // W0058 Phase 2: batching writer is the default on the API Gateway path.
+        // Prototype B (W0056) showed batch signing + client-side parallelism
+        // eliminates the 429 storm that single-URL parallelism triggered on the
+        // Vercel signing endpoint, at parity with the GCS-direct parallel path
+        // once the sign+PUT overlap optimization lands. Flip the default to 8
+        // concurrency; `AILF_PARALLEL_UPLOAD=0` forces serial as a rollback
+        // escape hatch and auto-selects the legacy single-URL writer.
+        setDefaultUploadConcurrency(8);
+        const concurrency = resolveUploadConcurrency();
+        if (concurrency > 1) {
+            logger.debug(`Artifact remote backend: BatchingApiGatewayArtifactWriter (via ${config.apiUrl}, bucket=${bucket}, putConcurrency=${concurrency})`);
+            // D0034: neither API Gateway writer supports NDJSON `appendNdjson`.
+            // Traces that flow through `appendNdjson` are dropped on this path.
+            // Surface the gap once at startup instead of ambushing users with a
+            // silent null ref at emit time.
+            logger.warn("Artifacts: API Gateway path selected without GCS ADC — " +
+                "trace (NDJSON) artifacts will be skipped (D0034). Set " +
+                "GOOGLE_APPLICATION_CREDENTIALS or GCLOUD_PROJECT to capture traces.");
+            return new BatchingApiGatewayArtifactWriter({
+                apiBaseUrl: config.apiUrl,
+                apiKey: config.apiKey,
+                bucket,
+                putConcurrency: concurrency,
+                ...(metrics ? { metrics } : {}),
+            });
+        }
+        logger.debug(`Artifact remote backend: ApiGatewayArtifactWriter (via ${config.apiUrl}, bucket=${bucket}, serial — AILF_PARALLEL_UPLOAD=0 override)`);
         return new ApiGatewayArtifactWriter({
             apiBaseUrl: config.apiUrl,
             apiKey: config.apiKey,
             bucket,
+            ...(metrics ? { metrics } : {}),
         });
     }
     return null;

package/dist/orchestration/pipeline-orchestrator.js

@@ -11,7 +11,7 @@
  * each step completes. This enables the GET /v1/jobs/:jobId polling
  * endpoint to show real-time progress.
  */
-import { assoc, } from "../_vendor/ailf-core/index.js";
+import { ARTIFACT_EXPORT_PHASE_ID, assoc, } from "../_vendor/ailf-core/index.js";
 import { runStep } from "./step-runner.js";
 // ---------------------------------------------------------------------------
 // Job progress reporter
@@ -142,10 +142,16 @@ export async function orchestratePipeline(ctx, steps) {
     if (hasJob) {
         await reportJobProgress(ctx, steps[0]?.name ?? "init", 0, steps.length, "running", undefined, jobUpdates);
     }
+    // W0053 — artifact export phase. Opens the first time a non-`run-eval`
+    // step starts, signalling the user that promptfoo's progress bar is done
+    // and the (previously silent) GCS export/upload window is now active.
+    // Closed in a finally after the step loop, regardless of pipeline outcome.
+    const exportPhase = createExportPhaseGate(ctx);
     for (let i = 0; i < steps.length; i++) {
         const step = steps[i];
         ctx.logger.debug(`Starting step ${i + 1}/${steps.length}: ${step.name}`);
         ctx.logger.section(step.name);
+        exportPhase.maybeOpen(step.name);
         // Report current step progress
         if (hasJob) {
             await reportJobProgress(ctx, step.name, i, steps.length, "running", undefined, jobUpdates);
@@ -171,6 +177,7 @@ export async function orchestratePipeline(ctx, steps) {
             // observability-only capture not tied to a registered artifact type;
             // dropped in W0050. Use the JobStore path for job telemetry.
             await capturePipelineContext(ctx, state, results);
+            exportPhase.close();
             return {
                 belowCritical: state.belowCritical,
                 durationMs: Date.now() - pipelineStart,
@@ -227,6 +234,7 @@ export async function orchestratePipeline(ctx, steps) {
     // Capture pipeline context. `job-updates` observability captures were
     // dropped in Slice 6.1 — JobStore is the supported telemetry path.
     await capturePipelineContext(ctx, state, results);
+    exportPhase.close();
     return {
         belowCritical: state.belowCritical,
         durationMs,
@@ -237,3 +245,91 @@ export async function orchestratePipeline(ctx, steps) {
         validation,
     };
 }
+// ---------------------------------------------------------------------------
+// Artifact export phase gate (W0053)
+// ---------------------------------------------------------------------------
+/**
+ * Returns a lazy gate that opens the `artifact-export` progress phase on the
+ * first step after `run-eval` and closes it on pipeline completion. The gate
+ * tolerates repeated opens / closes — each is a no-op after the first.
+ *
+ * The phase is keyed on step names rather than timestamps so the header lands
+ * exactly when the user sees promptfoo's `Evaluating` bar hit 100% and the
+ * next pipeline step takes over. `run-eval` produces artifacts too, but its
+ * own progress is owned by promptfoo; opening the phase before run-eval would
+ * produce a duplicate progress channel for the same window.
+ */
+function createExportPhaseGate(ctx) {
+    let opened = false;
+    let closed = false;
+    let startedAt = 0;
+    // Step names that run BEFORE the artifact-heavy post-eval section. The
+    // phase opens on the first step whose name is not in this set — typically
+    // `calculate-scores` once promptfoo has handed back control.
+    const preExportSteps = new Set([
+        "validate",
+        "mirror-repo-tasks",
+        "fetch-docs",
+        "generate-configs",
+        "grader-consistency",
+    ]);
+    const { label, detail } = describeExportPhase(ctx);
+    return {
+        maybeOpen(stepName) {
+            if (opened)
+                return;
+            if (stepName.startsWith("run-eval"))
+                return;
+            if (preExportSteps.has(stepName))
+                return;
+            opened = true;
+            startedAt = Date.now();
+            ctx.progress.phaseStart({
+                phaseId: ARTIFACT_EXPORT_PHASE_ID,
+                label,
+                detail,
+                startedAt,
+            });
+        },
+        close() {
+            if (!opened || closed)
+                return;
+            closed = true;
+            // Cumulative counts live inside the reporter adapter (it accumulates
+            // each phaseProgress event). The orchestrator does not track the
+            // running total — it only knows when the phase is over. Adapters that
+            // render a final summary use their own state; NoOp / JSON adapters
+            // ignore the event.
+            ctx.progress.phaseComplete({
+                phaseId: ARTIFACT_EXPORT_PHASE_ID,
+                itemsCompleted: 0,
+                bytesCompleted: 0,
+                durationMs: Date.now() - startedAt,
+            });
+        },
+    };
+}
+/**
+ * Build the user-facing phase label by peeking at the wired writer chain.
+ * `AccumulatingArtifactWriter` wraps a `FanoutArtifactWriter([local, remote])`
+ * when remote credentials are present, or a bare `LocalFilesystemArtifactWriter`
+ * otherwise — naming the destination in the label keeps every progress line
+ * self-describing.
+ */
+function describeExportPhase(ctx) {
+    const writer = ctx.artifactWriter;
+    const inner = writer.inner?.constructor.name ?? writer.constructor.name;
+    if (inner === "FanoutArtifactWriter") {
+        return { label: "Exporting run artifacts", detail: "local + GCS" };
+    }
+    if (inner === "GcsArtifactWriter") {
+        return { label: "Exporting run artifacts", detail: "GCS" };
+    }
+    if (inner === "ApiGatewayArtifactWriter") {
+        return { label: "Exporting run artifacts", detail: "API gateway" };
+    }
+    if (inner === "NoOpArtifactWriter") {
+        return { label: "Finalizing run" };
+    }
+    return { label: "Exporting run artifacts", detail: "local" };
+}