@sanity/ailf 2.8.0 → 3.0.0

package/dist/_vendor/ailf-core/artifact-capture/association.d.ts

@@ -0,0 +1,35 @@
+/**
+ * assoc() — collapses the `{ run: ctx.runId, …axisValues }` boilerplate
+ * every producer would otherwise write at each `ctx.artifactWriter.emit()`
+ * call site.
+ *
+ * Instead of:
+ *   ctx.artifactWriter.emit("testOutputs", { run: ctx.runId, mode, task, model }, payload)
+ *
+ * Producers write:
+ *   ctx.artifactWriter.emit("testOutputs", assoc(ctx, { mode, task, model }), payload)
+ *
+ * The `run` axis is always present because it's derivable from context;
+ * every other axis is whatever the producer's local loop variables are.
+ * See `docs/work-items/W0050-...json` (Q1 decision) and `tasks/plan.md § Q1`.
+ */
+import type { AssociationValues, RunId } from "../types/branded-ids.js";
+/**
+ * Structural subset of `AppContext` needed by `assoc()`. Producers pass
+ * their full `ctx` here; tests (and agents writing toy fixtures) can pass
+ * a plain `{ runId }` object.
+ */
+export interface AssocContext {
+    readonly runId: RunId;
+}
+/**
+ * Build an `AssociationValues` object with `run` pinned from context and
+ * the rest of the axes supplied by the caller.
+ *
+ * Intentionally does NOT validate that the caller supplied all axes the
+ * descriptor requires — that would couple the helper to a specific type
+ * and defeat the point. Invalid associations surface at `descriptor.
+ * formatEntryKey()` time with a clear error, which is where the contract
+ * boundary actually lives.
+ */
+export declare function assoc(ctx: AssocContext, partial?: Omit<AssociationValues, "run">): AssociationValues;

package/dist/_vendor/ailf-core/artifact-capture/association.js

@@ -0,0 +1,28 @@
+/**
+ * assoc() — collapses the `{ run: ctx.runId, …axisValues }` boilerplate
+ * every producer would otherwise write at each `ctx.artifactWriter.emit()`
+ * call site.
+ *
+ * Instead of:
+ *   ctx.artifactWriter.emit("testOutputs", { run: ctx.runId, mode, task, model }, payload)
+ *
+ * Producers write:
+ *   ctx.artifactWriter.emit("testOutputs", assoc(ctx, { mode, task, model }), payload)
+ *
+ * The `run` axis is always present because it's derivable from context;
+ * every other axis is whatever the producer's local loop variables are.
+ * See `docs/work-items/W0050-...json` (Q1 decision) and `tasks/plan.md § Q1`.
+ */
+/**
+ * Build an `AssociationValues` object with `run` pinned from context and
+ * the rest of the axes supplied by the caller.
+ *
+ * Intentionally does NOT validate that the caller supplied all axes the
+ * descriptor requires — that would couple the helper to a specific type
+ * and defeat the point. Invalid associations surface at `descriptor.
+ * formatEntryKey()` time with a clear error, which is where the contract
+ * boundary actually lives.
+ */
+export function assoc(ctx, partial = {}) {
+    return { run: ctx.runId, ...partial };
+}

package/dist/_vendor/ailf-core/artifact-registry.d.ts

@@ -1,68 +1,147 @@
 /**
  * Artifact registry — single source of truth for AILF's external artifact types.
  *
- * Every artifact that lives in GCS declares itself here exactly once:
- * layout, path builder, entry schema, and (for per-entry layouts) key parser.
+ * Every artifact that lives in GCS (or on the local filesystem after W0050)
+ * declares itself here exactly once: association axes, layout, path builder,
+ * entry schema, mime, cap, and (for per-entry layouts) format/parse helpers.
  * Eval writers, the API Gateway's signing endpoint, and the Studio hook all
  * consume this same record.
  *
  * Adding a new artifact type = one entry here. No call-site changes needed in
  * the generic writer / signer / hook — they all iterate the registry.
  *
+ * ## Association axes (D0033 / W0049)
+ *
+ * Each descriptor declares the pipeline dimensions it is evidence about. At
+ * module load a structural invariant rejects descriptors that declare an
+ * unbounded axis (`task`, `model`, `trial`) but a `"bulk"` layout — such a
+ * shape would serialize as a single JSON array that blows past the object-
+ * size cap at scale. The invariant converts that class of mistake into a
+ * process-won't-start error rather than a silent data bug.
+ *
  * @see docs/decisions/D0032-run-anchored-artifact-store.md
- * @see docs/design-docs/run-artifact-store.md (§ Move 4 — Artifact Registry)
+ * @see docs/decisions/D0033-unified-run-anchored-artifact-capture.md
+ * @see docs/design-docs/unified-run-artifacts.md (§ M1, § M5)
  */
 import { z } from "zod";
-import type { RunId } from "./types/branded-ids.js";
+import type { AssociationAxis, AssociationValues, EntryKey, RunId } from "./types/branded-ids.js";
 /** Layouts supported by the artifact store. */
 export type ArtifactLayout = "bulk" | "per-entry";
+/** MIME types the registry knows how to place on disk. */
+export type ArtifactMime = "application/json" | "application/x-ndjson" | "text/markdown" | "application/yaml";
+/**
+ * Behavior when a payload exceeds a descriptor's `capBytes`:
+ *   - `"reject"` — drop the write and log a warning (default for bounded entries).
+ *   - `"trailing-truncate"` — serialize up to the cap, mark the entry truncated.
+ *   - `"fielded-truncate"` — a descriptor-specific truncator trims the largest
+ *     fields first (used by richly-nested payloads whose trailing bytes aren't
+ *     the right thing to drop).
+ *   - `"trial-oversize"` (traces only) — drop overflow rows for the current
+ *     trial, keep the rest of the trial's artifacts intact.
+ */
+export type ArtifactTruncationPolicy = "reject" | "trailing-truncate" | "fielded-truncate" | "trial-oversize";
 /** The union of every artifact type known to AILF. */
-export type ArtifactType = "testOutputs" | "renderedPrompts" | "rawResults" | "graderPrompts" | "taskDefinitions" | "evalResults" | "traces";
+export type ArtifactType = "runManifest" | "scoreSummary" | "pipelineResult" | "pipelineContext" | "documentManifest" | "prComment" | "readinessReport" | "reportSnapshot" | "autoComparison" | "gapReport" | "sinkResults" | "callbackRequest" | "callbackResponse" | "configSnapshot" | "evalConfigGenerated" | "comparisonReport" | "discoveryReport" | "failureModes" | "taskDefinitions" | "renderedPrompts" | "rawResults" | "testOutputs" | "graderPrompts" | "graderJudgments" | "traces";
 /**
  * Result of parsing a per-entry key into a sanitized filename component.
  * Success carries the sanitized value; failure carries a reason for 4xx responses.
  */
 export type ParsedEntryKey = {
     ok: true;
-    sanitized: string;
+    sanitized: EntryKey;
 } | {
     ok: false;
     reason: string;
 };
+/**
+ * Declaration of which pipeline axes an artifact is evidence about. Axis order
+ * drives both the entry-key layout (join order) and the invariant check
+ * (unbounded axis ⇒ per-entry).
+ */
+export interface AssociationDeclaration {
+    readonly axes: readonly AssociationAxis[];
+}
+/**
+ * Optional inline preview declaration. When present, the writer extracts a
+ * small summary shape at write time and attaches it to the manifest entry so
+ * Studio list views can render without fetching the external payload.
+ *
+ * Schema-only in W0049 — the write-time `extract()` wiring lands in W0051.
+ * `extract` takes `unknown` here so the registry can store heterogeneously
+ * typed descriptors without variance issues; W0051 tightens the parameter
+ * type to the owning descriptor's `TEntry` at the concrete-descriptor level.
+ */
+export interface ManifestPreviewDeclaration<TPreview = unknown> {
+    readonly schema: z.ZodType<TPreview>;
+    readonly extract: (entry: unknown) => TPreview;
+    readonly capBytes: number;
+}
 /**
  * Per-type declaration consumed by writers, signers, and readers.
  *
- * @typeParam TEntry - The shape of a single entry. For bulk layouts this is
- *                     the shape of each value in the bulk object's index; for
- *                     per-entry layouts it's the shape of a single GCS object.
+ * @typeParam TEntry   - Shape of a single entry payload.
+ * @typeParam TPreview - Shape of the optional manifest preview (W0051).
  */
-export interface ArtifactDescriptor<TEntry = unknown> {
+export interface ArtifactDescriptor<TEntry = unknown, TPreview = unknown> {
     /** The artifact type identifier (matches the key in ARTIFACT_REGISTRY). */
-    type: ArtifactType;
+    readonly type: ArtifactType;
     /** Bulk (one object per run) or per-entry (one object per entryKey). */
-    layout: ArtifactLayout;
+    readonly layout: ArtifactLayout;
     /** Kebab-case filename stem. Used by both bulk paths and per-entry dir names. */
-    slug: string;
-    /** Zod schema for validating a single entry. */
-    entrySchema: z.ZodType<TEntry>;
+    readonly slug: string;
+    /** Pipeline axes this artifact is evidence about (D0033). */
+    readonly association: AssociationDeclaration;
+    /** Zod schema for validating a single entry payload. */
+    readonly entrySchema: z.ZodType<TEntry>;
+    /** Wire-level content type (drives filename extension + upload Content-Type). */
+    readonly mime: ArtifactMime;
+    /** Upper bound on serialized entry bytes. Enforced by the writer. */
+    readonly capBytes: number;
+    /** Behavior when a payload exceeds `capBytes`. Defaults to `"reject"`. */
+    readonly truncation?: ArtifactTruncationPolicy;
+    /**
+     * Some artifacts are expected not to fire every run (e.g. `prComment` only
+     * fires on PR-context runs). Marking them `optional` keeps the manifest
+     * catalog honest about what is absent vs. failed.
+     */
+    readonly optional?: boolean;
     /**
      * Build the GCS object path for this artifact.
-     * - bulk: returns `runs/{runId}/{slug}.json`; `entryKey` is ignored.
-     * - per-entry: requires `entryKey`; returns `runs/{runId}/{slug}/{sanitized}.json`.
+     * - bulk: returns `runs/{runId}/{slug}.{ext}`; `entryKey` is ignored.
+     * - per-entry: requires `entryKey`; returns `runs/{runId}/{slug}/{sanitized}.{ext}`.
      */
-    objectPath: (runId: RunId, entryKey?: string) => string;
+    readonly objectPath: (runId: RunId, entryKey?: string) => string;
     /**
-     * Validate a per-entry key and return its sanitized filename component.
-     * Only meaningful for `layout === "per-entry"` — unused when layout is bulk,
-     * but may be pre-declared so a future layout flip is a one-line change.
+     * Build a filename-safe entry key from association values. Only meaningful
+     * for `layout === "per-entry"` — bulk descriptors omit it.
      */
-    parseEntryKey?: (key: string) => ParsedEntryKey;
+    readonly formatEntryKey?: (assoc: AssociationValues) => EntryKey;
+    /**
+     * Validate a per-entry key received on the wire (URL param, etc.) and
+     * return its sanitized filename component. Only meaningful for
+     * `layout === "per-entry"`; bulk descriptors omit it.
+     */
+    readonly parseEntryKey?: (key: string) => ParsedEntryKey;
+    /**
+     * Optional inline preview for triage-friendly list views. Populated at
+     * write time in W0051 — in this phase the field is schema-only and is
+     * carried on the descriptor so downstream tooling can see what the
+     * preview shape will be.
+     */
+    readonly manifestPreview?: ManifestPreviewDeclaration<TPreview>;
 }
+/** Test-only reset for the legacy-key warning flag. Not exported publicly. */
+export declare function __resetLegacyTestOutputsWarning(): void;
 /**
  * The canonical artifact descriptor for every artifact type. Iterate with
  * `Object.values(ARTIFACT_REGISTRY)` or look up by `ARTIFACT_REGISTRY[type]`.
+ *
+ * Axes, layout, and caps come from docs/design-docs/unified-run-artifacts.md
+ * § M5. The mapping is verified by the L1 contract tests.
  */
-export declare const ARTIFACT_REGISTRY: Record<ArtifactType, ArtifactDescriptor>;
+export declare const ARTIFACT_REGISTRY: {
+    readonly [T in ArtifactType]: ArtifactDescriptor;
+};
 /** All artifact types in declaration order. */
 export declare const ARTIFACT_TYPES: readonly ArtifactType[];
 /**
@@ -70,3 +149,25 @@ export declare const ARTIFACT_TYPES: readonly ArtifactType[];
  * Useful at API Gateway boundaries where the type comes from a URL parameter.
  */
 export declare function isArtifactType(value: string): value is ArtifactType;
+/**
+ * Structural check run against a single descriptor. Exported so L1 contract
+ * tests can construct an invalid descriptor inline and assert the throw.
+ */
+export declare function assertValidArtifactDescriptor(desc: ArtifactDescriptor): void;
+/**
+ * Build the inline preview for a manifest entry at write time. Returns
+ * `undefined` when the descriptor has no `manifestPreview` declaration,
+ * when extraction throws, when the schema rejects the extracted shape, or
+ * when cap-enforcement cannot bring the serialized preview under the
+ * descriptor's `capBytes` budget.
+ *
+ * Failure is non-fatal: preview is triage metadata, never critical-path data.
+ * The full payload still lands in the external artifact regardless.
+ *
+ * Cap enforcement (hard truncation) iteratively shortens the longest string
+ * field on the preview object by ~10% per pass until the JSON-serialized
+ * form fits under `capBytes` or no string remains to trim. Nested objects
+ * are not recursed — previews are intentionally shallow (a handful of
+ * top-level fields).
+ */
+export declare function buildManifestPreview<TPreview = unknown>(descriptor: ArtifactDescriptor<unknown, TPreview>, payload: unknown): TPreview | undefined;