@sanity/ailf 2.7.1 → 2.8.0

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

@@ -0,0 +1,72 @@
+/**
+ * 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.
+ * 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.
+ *
+ * @see docs/decisions/D0032-run-anchored-artifact-store.md
+ * @see docs/design-docs/run-artifact-store.md (§ Move 4 — Artifact Registry)
+ */
+import { z } from "zod";
+import type { RunId } from "./types/branded-ids.js";
+/** Layouts supported by the artifact store. */
+export type ArtifactLayout = "bulk" | "per-entry";
+/** The union of every artifact type known to AILF. */
+export type ArtifactType = "testOutputs" | "renderedPrompts" | "rawResults" | "graderPrompts" | "taskDefinitions" | "evalResults" | "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;
+} | {
+    ok: false;
+    reason: string;
+};
+/**
+ * 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.
+ */
+export interface ArtifactDescriptor<TEntry = unknown> {
+    /** The artifact type identifier (matches the key in ARTIFACT_REGISTRY). */
+    type: ArtifactType;
+    /** Bulk (one object per run) or per-entry (one object per entryKey). */
+    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>;
+    /**
+     * 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`.
+     */
+    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.
+     */
+    parseEntryKey?: (key: string) => ParsedEntryKey;
+}
+/**
+ * The canonical artifact descriptor for every artifact type. Iterate with
+ * `Object.values(ARTIFACT_REGISTRY)` or look up by `ARTIFACT_REGISTRY[type]`.
+ */
+export declare const ARTIFACT_REGISTRY: Record<ArtifactType, ArtifactDescriptor>;
+/** All artifact types in declaration order. */
+export declare const ARTIFACT_TYPES: readonly ArtifactType[];
+/**
+ * Type guard — validates that an arbitrary string is a known artifact type.
+ * Useful at API Gateway boundaries where the type comes from a URL parameter.
+ */
+export declare function isArtifactType(value: string): value is ArtifactType;

package/dist/_vendor/ailf-core/artifact-registry.js

@@ -0,0 +1,150 @@
+/**
+ * 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.
+ * 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.
+ *
+ * @see docs/decisions/D0032-run-anchored-artifact-store.md
+ * @see docs/design-docs/run-artifact-store.md (§ Move 4 — Artifact Registry)
+ */
+import { z } from "zod";
+// ---------------------------------------------------------------------------
+// Path + key helpers
+// ---------------------------------------------------------------------------
+function bulkPath(slug) {
+    return (runId) => `runs/${runId}/${slug}.json`;
+}
+function perEntryPath(slug) {
+    return (runId, entryKey) => {
+        if (entryKey === undefined) {
+            throw new Error(`Artifact "${slug}" uses per-entry layout; an entry key is required`);
+        }
+        const sanitized = sanitizeEntryKey(entryKey);
+        return `runs/${runId}/${slug}/${sanitized}.json`;
+    };
+}
+/**
+ * Convert an entry key (wire format, e.g. `{taskId}::{modelId}`) to a
+ * filename-safe component.
+ *
+ * - `::` → `--` so the wire separator doesn't show up in the filename.
+ * - `/` → `_` so task names like "Content Lake with @sanity/client" don't
+ *   create unintended GCS subdirectories (`.../test-outputs/@sanity/client…`)
+ *   and so `ls` against the per-entry directory shows one row per entry.
+ *
+ * Single colons (`:`) are preserved — modelIds like
+ * `anthropic:messages:claude-opus-4-6` are valid GCS object names.
+ *
+ * NOTE: this mapping is not bijective. A taskId containing literal `--`
+ * combined with a modelId could in theory collide with one whose taskId
+ * contains `::`, and `_` collides with `/`. In practice, production
+ * taskIds don't exercise these combinations. If collision-safety becomes a
+ * concern (e.g., user-provided free-form task names), switch to
+ * percent-encoding or a hash-based scheme at the key boundary.
+ */
+function sanitizeEntryKey(key) {
+    return key.replace(/::/g, "--").replace(/\//g, "_");
+}
+/**
+ * Entry-key parser for artifacts keyed by `{taskId}::{modelId}` — testOutputs
+ * today, other per-entry types in future.
+ *
+ * The separator is `::` (double colon). Either segment may contain single
+ * colons: production model ids commonly look like
+ * `anthropic:messages:claude-opus-4-6`. The constraint is that `::` must
+ * appear exactly once and neither segment is empty, so the API Gateway can
+ * return 400 on malformed input.
+ */
+function parseTaskModelKey(key) {
+    const parts = key.split("::");
+    if (parts.length !== 2 || !parts[0] || !parts[1]) {
+        return {
+            ok: false,
+            reason: `Entry key "${key}" must match {taskId}::{modelId} with exactly one "::" separator and non-empty segments`,
+        };
+    }
+    return { ok: true, sanitized: sanitizeEntryKey(key) };
+}
+// ---------------------------------------------------------------------------
+// Entry schemas
+// ---------------------------------------------------------------------------
+const testOutputEntrySchema = z.object({
+    responseOutput: z.string(),
+    responseOutputTruncated: z.boolean(),
+});
+// Aspirational: renderedPrompts / rawResults / traces / etc. currently have
+// loose shapes. Tighten per-type as consumers stabilize.
+const unknownEntry = z.unknown();
+// ---------------------------------------------------------------------------
+// The registry
+// ---------------------------------------------------------------------------
+/**
+ * The canonical artifact descriptor for every artifact type. Iterate with
+ * `Object.values(ARTIFACT_REGISTRY)` or look up by `ARTIFACT_REGISTRY[type]`.
+ */
+export const ARTIFACT_REGISTRY = {
+    testOutputs: {
+        type: "testOutputs",
+        layout: "per-entry",
+        slug: "test-outputs",
+        entrySchema: testOutputEntrySchema,
+        objectPath: perEntryPath("test-outputs"),
+        parseEntryKey: parseTaskModelKey,
+    },
+    renderedPrompts: {
+        type: "renderedPrompts",
+        layout: "bulk",
+        slug: "rendered-prompts",
+        entrySchema: unknownEntry,
+        objectPath: bulkPath("rendered-prompts"),
+    },
+    rawResults: {
+        type: "rawResults",
+        layout: "bulk",
+        slug: "raw-results",
+        entrySchema: unknownEntry,
+        objectPath: bulkPath("raw-results"),
+    },
+    graderPrompts: {
+        type: "graderPrompts",
+        layout: "bulk",
+        slug: "grader-prompts",
+        entrySchema: unknownEntry,
+        objectPath: bulkPath("grader-prompts"),
+    },
+    taskDefinitions: {
+        type: "taskDefinitions",
+        layout: "bulk",
+        slug: "task-definitions",
+        entrySchema: unknownEntry,
+        objectPath: bulkPath("task-definitions"),
+    },
+    evalResults: {
+        type: "evalResults",
+        layout: "bulk",
+        slug: "eval-results",
+        entrySchema: unknownEntry,
+        objectPath: bulkPath("eval-results"),
+    },
+    traces: {
+        type: "traces",
+        layout: "bulk",
+        slug: "traces",
+        entrySchema: unknownEntry,
+        objectPath: bulkPath("traces"),
+    },
+};
+/** All artifact types in declaration order. */
+export const ARTIFACT_TYPES = Object.keys(ARTIFACT_REGISTRY);
+/**
+ * Type guard — validates that an arbitrary string is a known artifact type.
+ * Useful at API Gateway boundaries where the type comes from a URL parameter.
+ */
+export function isArtifactType(value) {
+    return value in ARTIFACT_REGISTRY;
+}

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

@@ -15,8 +15,9 @@ export * from "./schemas/index.js";
 export * from "./ports/index.js";
 export * from "./services/index.js";
 export * from "./examples/index.js";
+export * from "./artifact-registry.js";
 export { defineConfig, defineFeatures, defineModeBase, defineModels, definePricingTable, definePreset, definePrompts, defineRubrics, defineSchedules, defineSinks, defineSources, defineTask, defineThresholds, } from "./config-helpers.js";
 export type { PricingEntry, PromptEntry, SourceEntry, } from "./config-helpers.js";
 export { env } from "./env-helper.js";
 export { NoOpArtifactCollector } from "./artifact-capture/noop-collector.js";
-export { NoOpArtifactUploader } from "./ports/artifact-uploader.js";
+export { NoOpArtifactWriter } from "./ports/artifact-writer.js";

package/dist/_vendor/ailf-core/index.js

@@ -15,10 +15,11 @@ export * from "./schemas/index.js";
 export * from "./ports/index.js";
 export * from "./services/index.js";
 export * from "./examples/index.js";
+export * from "./artifact-registry.js";
 // ---------------------------------------------------------------------------
 // Architecture overhaul — Phase 0 helpers
 // ---------------------------------------------------------------------------
 export { defineConfig, defineFeatures, defineModeBase, defineModels, definePricingTable, definePreset, definePrompts, defineRubrics, defineSchedules, defineSinks, defineSources, defineTask, defineThresholds, } from "./config-helpers.js";
 export { env } from "./env-helper.js";
 export { NoOpArtifactCollector } from "./artifact-capture/noop-collector.js";
-export { NoOpArtifactUploader } from "./ports/artifact-uploader.js";
+export { NoOpArtifactWriter } from "./ports/artifact-writer.js";

package/dist/_vendor/ailf-core/ports/artifact-collector.d.ts

@@ -62,7 +62,7 @@ export interface CaptureFlushResult {
     compressed: boolean;
 }
 /** A single entry in the capture manifest. */
-export interface ArtifactManifestEntry {
+export interface CaptureManifestEntry {
     /** Pipeline step that produced this artifact */
     step: string;
     /** Artifact type identifier */
@@ -79,7 +79,7 @@ export interface ArtifactManifestEntry {
     meta?: Record<string, unknown>;
 }
 /** The manifest.json written to each capture directory. */
-export interface ArtifactManifest {
+export interface CaptureManifest {
     version: 1;
     captureId: string;
     startedAt: string;
@@ -90,5 +90,5 @@ export interface ArtifactManifest {
         source?: string;
         areas?: string[];
     };
-    artifacts: ArtifactManifestEntry[];
+    artifacts: CaptureManifestEntry[];
 }

package/dist/_vendor/ailf-core/ports/artifact-writer.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Port: ArtifactWriter — writes run artifacts + the run manifest to external storage.
+ *
+ * Replaces the older `ArtifactUploader` port from D0030. Differences:
+ *   - Paths anchor to `RunId` (not `ReportId`) via the registry's `objectPath`.
+ *   - Supports both `"bulk"` and `"per-entry"` layouts.
+ *   - A dedicated `writeManifest()` method for the run manifest at
+ *     `runs/{runId}/manifest.json`.
+ *
+ * Producer steps call writer methods directly with the artifact type from
+ * `ARTIFACT_REGISTRY`. Path construction, schema validation, and entry-key
+ * sanitization live in the registry, not the call site.
+ *
+ * @see docs/decisions/D0032-run-anchored-artifact-store.md
+ * @see packages/core/src/artifact-registry.ts
+ */
+import type { ArtifactType } from "../artifact-registry.js";
+import type { RunId } from "../types/branded-ids.js";
+import type { ArtifactRef, RunManifest } from "../types/index.js";
+/**
+ * An entry in a per-entry upload. The `key` is the wire-format identifier
+ * (e.g. `{taskId}::{modelId}` for testOutputs); the writer sanitizes it into
+ * the filename using the registry's `parseEntryKey`.
+ */
+export interface ArtifactEntry<TData = unknown> {
+    key: string;
+    data: TData;
+}
+export interface ArtifactWriter {
+    /**
+     * Write a bulk artifact — one JSON object per (runId, type).
+     *
+     * @returns An `ArtifactRef` pointing at `runs/{runId}/{slug}.json`, or
+     *          `null` when upload is skipped or fails (P5: non-blocking).
+     */
+    writeBulk(type: ArtifactType, runId: RunId, data: unknown): Promise<ArtifactRef | null>;
+    /**
+     * Write a per-entry artifact — one JSON object per entry, all under
+     * `runs/{runId}/{slug}/`.
+     *
+     * The returned `ArtifactRef.entries` inlines the catalog so consumers
+     * can render drill-down state without a second listing call.
+     */
+    writePerEntry(type: ArtifactType, runId: RunId, entries: readonly ArtifactEntry[]): Promise<ArtifactRef | null>;
+    /**
+     * Write the run manifest to `runs/{runId}/manifest.json`. Single-writer
+     * per run; subsequent publishes may rewrite to append `reportIds[]`.
+     */
+    writeManifest(runId: RunId, manifest: RunManifest): Promise<ArtifactRef | null>;
+}
+/** No-op writer — every method returns null. Used when no storage is configured. */
+export declare class NoOpArtifactWriter implements ArtifactWriter {
+    writeBulk(): Promise<null>;
+    writePerEntry(): Promise<null>;
+    writeManifest(): Promise<null>;
+}

package/dist/_vendor/ailf-core/ports/artifact-writer.js

@@ -0,0 +1,28 @@
+/**
+ * Port: ArtifactWriter — writes run artifacts + the run manifest to external storage.
+ *
+ * Replaces the older `ArtifactUploader` port from D0030. Differences:
+ *   - Paths anchor to `RunId` (not `ReportId`) via the registry's `objectPath`.
+ *   - Supports both `"bulk"` and `"per-entry"` layouts.
+ *   - A dedicated `writeManifest()` method for the run manifest at
+ *     `runs/{runId}/manifest.json`.
+ *
+ * Producer steps call writer methods directly with the artifact type from
+ * `ARTIFACT_REGISTRY`. Path construction, schema validation, and entry-key
+ * sanitization live in the registry, not the call site.
+ *
+ * @see docs/decisions/D0032-run-anchored-artifact-store.md
+ * @see packages/core/src/artifact-registry.ts
+ */
+/** No-op writer — every method returns null. Used when no storage is configured. */
+export class NoOpArtifactWriter {
+    async writeBulk() {
+        return null;
+    }
+    async writePerEntry() {
+        return null;
+    }
+    async writeManifest() {
+        return null;
+    }
+}

package/dist/_vendor/ailf-core/ports/context.d.ts

@@ -11,9 +11,10 @@
  * Fields marked optional are transitional — they will become required
  * as downstream consumers are converted to use them.
  */
+import type { RunId } from "../types/branded-ids.js";
 import type { DebugOptions, EvalMode, PluginRegistry } from "../types/index.js";
 import type { ArtifactCollector } from "./artifact-collector.js";
-import type { ArtifactUploader } from "./artifact-uploader.js";
+import type { ArtifactWriter } from "./artifact-writer.js";
 import type { CacheStore } from "./cache-store.js";
 import type { DocFetcher } from "./doc-fetcher.js";
 import type { EvalRunner } from "./eval-runner.js";
@@ -197,8 +198,8 @@ export interface ResolvedConfig {
  * Created per-test by createTestContext().
  */
 export interface AppContext {
-    /** Report artifact uploader — uploads structured files to GCS for Studio (D0030) */
-    readonly artifactUploader?: ArtifactUploader;
+    /** Artifact writer — writes run artifacts + manifest to GCS (D0032) */
+    readonly artifactWriter?: ArtifactWriter;
     /** Evaluation caching (filesystem + optional Content Lake fallback) */
     readonly cache?: CacheStore;
     /** Artifact capture collector (no-op when --capture is not set) */
@@ -220,6 +221,15 @@ export interface AppContext {
      * require this field.
      */
     readonly reportStore?: ReportStorePort;
+    /**
+     * Identity for this pipeline run. Generated once at composition-root
+     * time; every step reads it from the context rather than regenerating.
+     * Artifacts anchor to this id (`gs://…/runs/{runId}/…`) regardless of
+     * whether the run eventually publishes a report.
+     *
+     * @see docs/decisions/D0032-run-anchored-artifact-store.md
+     */
+    readonly runId: RunId;
     /**
      * Report delivery sinks (Slack, BigQuery, webhooks).
      * Empty array when no sinks are configured.

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

@@ -4,9 +4,9 @@
  * Ports define the contracts between the domain kernel and the outside world.
  * Adapters (in packages/eval) implement these interfaces.
  */
-export type { ArtifactCollector, ArtifactManifest, ArtifactManifestEntry, CaptureFlushResult, } from "./artifact-collector.js";
-export type { ArtifactUploader } from "./artifact-uploader.js";
-export { NoOpArtifactUploader } from "./artifact-uploader.js";
+export type { ArtifactCollector, CaptureFlushResult, CaptureManifest, CaptureManifestEntry, } from "./artifact-collector.js";
+export type { ArtifactEntry, ArtifactWriter } from "./artifact-writer.js";
+export { NoOpArtifactWriter } from "./artifact-writer.js";
 export type { ArtifactContentDiff, CaptureDiffReport, ComparisonMode, ComparisonOptions, InventoryDiff, JsonDiffEntry, MetadataComparison, ScoreComparison, SecurityScan, TimingComparison, } from "./capture-comparator.js";
 export type { CacheEntryMetadata, CacheKey, CacheLookupResult, CacheRecordInput, CacheStore, } from "./cache-store.js";
 export type { ConfigSource } from "./config-source.js";

package/dist/_vendor/ailf-core/ports/index.js

@@ -4,5 +4,5 @@
  * Ports define the contracts between the domain kernel and the outside world.
  * Adapters (in packages/eval) implement these interfaces.
  */
-export { NoOpArtifactUploader } from "./artifact-uploader.js";
+export { NoOpArtifactWriter } from "./artifact-writer.js";
 export { canonicalDocRefLabel, isIdRef, isPathRef, isPerspectiveRef, isSlugRef, isTemplatedAssertion, } from "./task-source.js";

package/dist/_vendor/ailf-core/types/branded-ids.d.ts

@@ -104,6 +104,15 @@ export declare function taskId(raw: string): Result<TaskId, IdValidationError>;
  * Valid format: `run_` prefix followed by alphanumeric characters.
  */
 export declare function runId(raw: string): Result<RunId, IdValidationError>;
+/**
+ * Generate a new `RunId` using a time-sortable UUIDv7 payload.
+ *
+ * The `run_` prefix plus the hyphen-stripped UUIDv7 yields 36 characters
+ * that sort lexicographically by creation time — same pattern used for
+ * `ReportId`. One generator call per pipeline invocation; every step
+ * reads the resulting id from `AppContext.runId`.
+ */
+export declare function generateRunId(): RunId;
 /**
  * Parse a raw string into a `SuiteId`.
  *

package/dist/_vendor/ailf-core/types/branded-ids.js

@@ -59,6 +59,27 @@ export function runId(raw) {
     }
     return ok(raw);
 }
+/**
+ * Generate a new `RunId` using a time-sortable UUIDv7 payload.
+ *
+ * The `run_` prefix plus the hyphen-stripped UUIDv7 yields 36 characters
+ * that sort lexicographically by creation time — same pattern used for
+ * `ReportId`. One generator call per pipeline invocation; every step
+ * reads the resulting id from `AppContext.runId`.
+ */
+export function generateRunId() {
+    const now = Date.now();
+    const uuid = crypto.randomUUID();
+    // UUID v7: encode 48-bit timestamp in the first 12 hex chars
+    const hex = now.toString(16).padStart(12, "0");
+    const v7 = hex.slice(0, 8) +
+        hex.slice(8, 12) +
+        "7" +
+        uuid.slice(15, 18) +
+        uuid.slice(19, 23) +
+        uuid.slice(24);
+    return `run_${v7}`;
+}
 /**
  * Parse a raw string into a `SuiteId`.
  *