@sanity/ailf 2.8.0 → 2.9.0

package/dist/_vendor/ailf-core/types/index.d.ts

@@ -10,7 +10,8 @@
  * re-export barrel that preserves backward compatibility.
  */
 import type { DocumentRef as _DocumentRef, EvalMode, RunContext } from "../../ailf-shared/index.d.ts";
-import type { RunId } from "./branded-ids.js";
+import type { ArtifactType } from "../artifact-registry.js";
+import type { AssociationValues, RunId } from "./branded-ids.js";
 export type { ActualScoreEntry, ComponentResult, TestResult, UrlMetadata, } from "./scoring-input.js";
 export type { DocumentRef, RunContext, RunTrigger } from "../../ailf-shared/index.d.ts";
 export type { StoredBaseline, StoredReport, StoredRun, StoredTaskResult, StoredTrace, SchemaVersioned, } from "./storage-schema.js";
@@ -22,7 +23,7 @@ export { evalModeType } from "./eval-mode-config.js";
 export type { DependencyEdge, ResolvedFixture, TaskGraph, TaskNode, } from "./task-graph.js";
 export type { VariableDeclaration, VariableEnvelope, VariableProvenance, VariableSource, } from "./variable-envelope.js";
 export type { EvalTrace, ToolCallCategory, ToolCallRecord, TraceEvent, TraceSpan, TraceTokenUsage, } from "./trace.js";
-export type { ArtifactId, Brand, Err, FixtureId, IdValidationError, NewReportId, Ok, ProviderId, PromptId, Result, ResultId, RubricId, RunFingerprint, RunId, SuiteId, TaskId, TaskSlug, TraceId, } from "./branded-ids.js";
+export type { ArtifactId, AssociationAxis, AssociationValues, Brand, EntryKey, Err, FixtureId, IdValidationError, NewReportId, Ok, ProviderId, PromptId, Result, ResultId, RubricId, RunFingerprint, RunId, SuiteId, TaskId, TaskSlug, TraceId, } from "./branded-ids.js";
 export { err, fixtureId, generateRunId, ok, providerId, resultId, runId, suiteId, taskId, traceId, } from "./branded-ids.js";
 export type { AgentHarnessTaskDefinition, CustomTaskDefinition, GeneralizedAssertionDefinition, GeneralizedDocRef, GeneralizedTaskDefinition, GeneralizedTemplatedAssertion, GeneralizedValueAssertion, IdDocRef, KnowledgeProbeTaskDefinition, LiteracyTaskDefinition, MCPServerTaskDefinition, PathDocRef, PerspectiveDocRef, RubricRef, SlugDocRef, TaskCommonFields, TaskDifficulty, TaskOptions, TaskProviderConfig, TaskStatus, } from "./generalized-task.js";
 type DocumentRef = _DocumentRef;
@@ -901,6 +902,142 @@ export interface ScoreSummary {
     };
     timestamp: string;
 }
+/**
+ * The subset of `ScoreSummary` the `compare()` primitive reads and the
+ * only fields consumers of `ComparisonReport.baseline` / `.experiment`
+ * access at runtime. Both the full pipeline `ScoreSummary` and the slim
+ * `ReportSummary` (W0051) carry these fields unchanged, so stored Reports
+ * can participate in auto-compare without re-hydrating prose fields.
+ */
+export type ComparableSummary = Pick<ScoreSummary, "overall" | "perModel" | "scores">;
+/**
+ * Slim pointer to a single low-scoring grader judgment. Replaces the full
+ * `StoredJudgment` inlined on pre-W0051 reports. The `id` field IS the
+ * `graderJudgments` manifest entry key — Studio looks up `reasonPreview`
+ * there for list rendering and hydrates the full reason on drill-down.
+ *
+ * `reasonPreview` is ALSO carried inline as a graceful-degradation fallback
+ * for runs whose `artifactManifest` is empty (offline dev, failed GCS
+ * upload, cache-skip before manifest aggregation lands). At ~280 chars per
+ * judgment × the 50-judgment cap ≈ 14 KB on the Report — tiny against the
+ * 500 KB budget. Studio's dispatch prefers the manifest-entry preview when
+ * present so GCS drill-down still renders the hydrated-on-demand copy.
+ *
+ * `graderId` replaces the historical `dimension` field at the slim-shape
+ * boundary to match D0033 axis naming; runtime value is identical.
+ */
+export interface SlimJudgmentRef {
+    /** Manifest entry key = `formatEntryKey({mode, task, model, grader})` for `graderJudgments`. */
+    id: string;
+    taskId: string;
+    modelId: string;
+    /** Rubric dimension name at runtime (what `GraderJudgment.dimension` carries). */
+    graderId: string;
+    /**
+     * Alias of `graderId` — carried for pre-W0051 Studio readers that still
+     * access `.dimension` (JudgmentList, judgment-formatting, et al). Remove
+     * in Slice 6 when those consumers migrate to `graderId`. Identical
+     * runtime value; no additional ambiguity.
+     */
+    dimension: string;
+    /** Normalized 0–100 score. */
+    score: number;
+    /**
+     * Truncated grader reason (≤280 chars). Inline fallback used when the
+     * manifest entry's preview is unavailable; the authoritative full reason
+     * lives in the `graderJudgments` external artifact.
+     */
+    reasonPreview?: string;
+    /**
+     * Alias of `reasonPreview` — legacy Studio renderers read `.reason`;
+     * expose the same truncated text under both names for the compat window.
+     * Remove alongside `dimension` in Slice 6.
+     */
+    reason?: string;
+}
+/**
+ * Slim failure-mode entry on the Report summary. One per classified
+ * `FailureModeType` bucket; `id` is the `failureModes` manifest entry key
+ * so drill-down can fetch the full category payload.
+ */
+export interface SlimFailureModeTopTitle {
+    /** Manifest entry key = `formatEntryKey({mode, category})` for `failureModes`. */
+    id: string;
+    category: string;
+    severity: "low" | "medium" | "high" | "critical";
+    title: string;
+    count: number;
+}
+/** Counts + top-N per-category summary on the Report. */
+export interface SlimFailureModesSummary {
+    /** Count by FailureModeType-ish id. */
+    counts: Record<string, number>;
+    /** Top-N categories by count, descending. */
+    topTitles: SlimFailureModeTopTitle[];
+    /** Total classified judgments across all categories. */
+    totalJudgments: number;
+    /** Percentage of judgments that landed in a non-unclassified bucket. */
+    classificationRate: number;
+}
+/**
+ * Slim gap pointer. The `gapReport` artifact is bulk (axes: `{run}`) so
+ * there is no per-gap manifest entry to point at — `id` is a stable
+ * synthetic composite so the UI can deduplicate and deep-link. Drill-down
+ * reads the full `gapReport` artifact and filters by id.
+ */
+export interface SlimRecommendationGap {
+    /** Synthetic id: `${area}--${failureMode}`, kebab-safe. */
+    id: string;
+    area: string;
+    title: string;
+    /** Priority bucketing for triage UI ordering. */
+    priority: number;
+}
+/** Counts + top-3 summary on the Report. */
+export interface SlimRecommendations {
+    /** Count of gaps by area. */
+    counts: Record<string, number>;
+    /** Top-3 gaps by priority, descending. */
+    top3: SlimRecommendationGap[];
+    /** Total actionable gaps identified (sum of counts). */
+    totalGaps: number;
+    /** Aggregate estimated lift (matches `GapAnalysisReport.totalPotentialLift`). */
+    totalPotentialLift: number;
+}
+/**
+ * Slim per-feature agent-behavior summary. Full `searchQueries` and
+ * `docSlugsVisited` arrays move to `traces` NDJSON; the Report keeps only
+ * counts + first-N samples for triage preview. The `firstN` cap is the
+ * producer's choice (we default to 5).
+ */
+export interface SlimAgentBehaviorFeature {
+    feature: string;
+    avgDocPagesVisited: number;
+    avgNetworkTimeMs: number;
+    avgSearchesPerformed: number;
+    tasksWithBehaviorData: number;
+    externalDomains: string[];
+    /** Distinct count of unique search queries across tasks in this feature. */
+    searchQueriesCount: number;
+    /** First-N unique search queries (bounded samples). */
+    searchQueriesSample: string[];
+    /** Distinct count of unique doc slugs visited. */
+    docSlugsVisitedCount: number;
+    /** First-N unique doc slugs (bounded samples). */
+    docSlugsVisitedSample: string[];
+}
+/**
+ * Slim `summary` field on a published `Report`. Structurally
+ * `Omit<ScoreSummary, slimmed-fields> & slim-replacements` — every
+ * pipeline-produced field survives except the four prose/array fields
+ * W0051 moves to external artifacts.
+ */
+export type ReportSummary = Omit<ScoreSummary, "agentBehavior" | "failureModes" | "lowScoringJudgments" | "recommendations"> & {
+    agentBehavior?: SlimAgentBehaviorFeature[];
+    failureModes?: SlimFailureModesSummary;
+    lowScoringJudgments?: SlimJudgmentRef[];
+    recommendations?: SlimRecommendations;
+};
 /** Result of a single pipeline step */
 export type StepResult = {
     status: "failed";
@@ -1074,8 +1211,8 @@ export interface ComparisonReport {
     areas: AreaDelta[];
     /** Per-document attribution (when changed docs are known) */
     attribution?: AttributionReport;
-    /** The "before" or "control" summary */
-    baseline: ScoreSummary;
+    /** The "before" or "control" summary (narrowed in W0051 so slim Reports compare) */
+    baseline: ComparableSummary;
     /** Aggregate deltas */
     deltas: {
         /** Overall score delta (experiment.avgScore − baseline.avgScore) */
@@ -1094,8 +1231,8 @@ export interface ComparisonReport {
             modelId: string;
         }[];
     };
-    /** The "after" or "treatment" summary */
-    experiment: ScoreSummary;
+    /** The "after" or "treatment" summary (narrowed in W0051 so slim Reports compare) */
+    experiment: ComparableSummary;
     /** When this comparison was generated */
     generatedAt: string;
     /** Areas that improved beyond the noise threshold */
@@ -1177,7 +1314,37 @@ export interface PublishResult {
     }[];
 }
 /**
- * Reference to an artifact in external object storage (GCS). See D0032.
+ * A single per-entry row in `ArtifactRef.entries`. Carries enough metadata for
+ * Studio list/triage views to render without fetching the external payload.
+ *
+ * D0033/W0049 extensions:
+ *   - `association` — the axis values that identify this entry (`{task, model}`
+ *     for testOutputs, etc.). Present only on manifests written by
+ *     `emit()`; legacy manifests omit it and readers treat absence as `{}`.
+ *   - `truncated` — whether the entry payload was capped by the descriptor's
+ *     `capBytes`. Readers treat absence as `false` (pre-W0049 manifests were
+ *     never truncated because no caps were enforced).
+ *   - `preview` — an inline summary produced by the descriptor's
+ *     `manifestPreview.extract()`. Typed via the descriptor's preview schema;
+ *     omitted when the descriptor has no `manifestPreview`. Wiring lands in
+ *     W0051; the field is reserved here so manifests written now parse there.
+ */
+export interface ArtifactRefEntry {
+    key: string;
+    bytes: number;
+    association?: AssociationValues;
+    truncated?: boolean;
+    preview?: unknown;
+}
+/**
+ * Reference to an artifact in external object storage.
+ *
+ * `store` discriminates the backend: `"gcs"` uses `bucket` as the bucket
+ * name (D0032); `"local"` uses `bucket` as the absolute rootDir path
+ * under which `path` resolves to a file on disk (D0033 / W0050 M4).
+ * Consumers (Studio retrieval, contract tests) branch on `store` only
+ * when constructing the fetch URL — the `path` is store-relative and
+ * identical across backends for the same logical artifact.
  *
  * `layout` determines the on-disk shape:
  *   - `"bulk"` — a single object at `path`. `entries` is absent.
@@ -1185,34 +1352,40 @@ export interface PublishResult {
  *     separate object at `{path}/{sanitizedKey}.json`. `entries` inlines
  *     the catalog so consumers can render drill-down states without a
  *     second list call.
+ *
+ * D0033/W0049 extensions (optional — legacy manifests parse without them):
+ *   - `truncated` on the bulk row indicates the single-object body was capped.
+ *   - `preview` on the bulk row carries a descriptor-typed summary for list
+ *     views; wiring lands in W0051.
  */
 export interface ArtifactRef {
-    store: "gcs";
+    store: "gcs" | "local";
+    /**
+     * GCS bucket name for `store: "gcs"`; absolute rootDir path for
+     * `store: "local"`. Kept as a single field so callers iterating
+     * manifest entries don't need to branch on `store` just to read the
+     * storage container.
+     */
     bucket: string;
     path: string;
     bytes?: number;
     entryCount?: number;
     layout: "bulk" | "per-entry";
-    entries?: {
-        key: string;
-        bytes: number;
-    }[];
+    entries?: ArtifactRefEntry[];
+    truncated?: boolean;
+    preview?: unknown;
 }
 /**
  * Catalog of artifact refs produced by a single pipeline run.
  *
  * Lives on `RunManifest.artifacts` (source of truth in GCS) and is
  * snapshotted onto `Report.artifactManifest` at publish time.
+ *
+ * Derived from `ArtifactType` so adding a descriptor to the registry
+ * automatically admits it to the manifest catalog — drift between the
+ * two becomes a compile error (W0049 review finding C1).
  */
-export interface ArtifactManifest {
-    testOutputs?: ArtifactRef;
-    renderedPrompts?: ArtifactRef;
-    rawResults?: ArtifactRef;
-    graderPrompts?: ArtifactRef;
-    taskDefinitions?: ArtifactRef;
-    evalResults?: ArtifactRef;
-    traces?: ArtifactRef;
-}
+export type ArtifactManifest = Partial<Record<ArtifactType, ArtifactRef>>;
 /** A published evaluation report — the atomic unit of the report store */
 export interface Report {
     /**
@@ -1232,8 +1405,14 @@ export interface Report {
     id: ReportId;
     /** What produced this report */
     provenance: ReportProvenance;
-    /** The full score summary */
-    summary: ScoreSummary;
+    /**
+     * The slim published summary. Inlined prose fields (grader reasons, full
+     * failure-mode text, gap prose, agent-behavior arrays) moved to external
+     * artifacts in W0051; see `ReportSummary` for the retained shape and
+     * `docs/decisions/D0033-unified-run-anchored-artifact-capture.md` §§ M7 for
+     * the full migration table.
+     */
+    summary: ReportSummary;
     /** Optional human-supplied label */
     tag?: string;
     /** Auto-generated descriptive title for discoverability and sharing */

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

@@ -0,0 +1,50 @@
+/**
+ * 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)
+ */
+import type { ArtifactEntry, ArtifactManifest, ArtifactRef, ArtifactType, ArtifactWriter, AssociationValues, RunId, RunManifest } from "../_vendor/ailf-core/index.d.ts";
+export declare class AccumulatingArtifactWriter implements ArtifactWriter {
+    /**
+     * Exposed so composition-root tests can assert on the underlying backend
+     * (LocalFilesystemArtifactWriter, FanoutArtifactWriter, etc.) without
+     * plumbing a separate accessor. Treat as read-only.
+     */
+    readonly inner: ArtifactWriter;
+    private readonly accumulated;
+    constructor(inner: ArtifactWriter);
+    /** Snapshot of every ref produced this far, keyed by artifact type. */
+    getAccumulatedArtifactRefs(): ArtifactManifest;
+    /** Test-only. Clears accumulated refs without touching the inner writer. */
+    _resetAccumulated(): void;
+    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 — forwarded to the inner writer without accumulation. */
+    writeBulk(type: ArtifactType, runId: RunId, data: unknown): Promise<ArtifactRef | null>;
+    /** @deprecated — forwarded to the inner writer without accumulation. */
+    writePerEntry(type: ArtifactType, runId: RunId, entries: readonly ArtifactEntry[]): Promise<ArtifactRef | null>;
+    private mergeRef;
+}

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