@sanity/ailf 4.4.0 → 4.6.0

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

@@ -29,6 +29,44 @@ import type { AssociationAxis, AssociationValues, EntryKey, RunId } from "./type
 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";
+/**
+ * Who is permitted to write the artifact (D0050).
+ *
+ * `"pipeline"` artifacts are written during a pipeline run by a pipeline
+ * step (the legacy default — every pre-D0050 descriptor is implicitly
+ * `"pipeline"`).
+ *
+ * `"post-hoc"` artifacts are written **after** the run is finalized, by
+ * a separate command/action (e.g. `ailf interpret`, a Studio action, an
+ * API endpoint). Post-hoc artifacts may accumulate multiple versions
+ * within a single run prefix; the writer-side guard
+ * (`assertWritePolicyMatches`) prevents pipeline writers from emitting
+ * post-hoc descriptors and vice versa.
+ */
+export type WritePolicy = "pipeline" | "post-hoc";
+/**
+ * Source-of-version for descriptors that opt into the versioning axis
+ * (D0050). The path builder consumes the version segment to produce
+ * `runs/{runId}/{slug}-{version}.{ext}`.
+ *
+ * - `"schemaVersion"` — version tracks the writer's serialized-shape
+ *   schema (e.g. attribution payload schema).
+ * - `"promptVersion"` — version tracks the prompt the artifact was
+ *   produced under (e.g. a regenerated grader prompt).
+ * - `"diagnosisVersion"` — version tracks the diagnosis run that produced
+ *   the artifact (e.g. `ailf interpret`'s versioned output).
+ *
+ * The union is intentionally narrow; D0050 leaves a function-shaped
+ * versioner as a future extension if version semantics get richer.
+ */
+export type VersionedBy = "schemaVersion" | "promptVersion" | "diagnosisVersion";
+/**
+ * Identity of the calling context when invoking the artifact writer.
+ * Mirrors `WritePolicy` but at the writer-instance level (a writer is
+ * either a pipeline writer or a post-hoc writer; descriptors declare
+ * which kind of writer is permitted to emit them).
+ */
+export type WriteSource = WritePolicy;
 /**
  * Behavior when a payload exceeds a descriptor's `capBytes`:
  *   - `"reject"` — drop the write and log a warning (default for bounded entries).
@@ -105,12 +143,29 @@ export interface ArtifactDescriptor<TEntry = unknown, TPreview = unknown> {
      * catalog honest about what is absent vs. failed.
      */
     readonly optional?: boolean;
+    /**
+     * Who writes this artifact (D0050). When unset, defaults to `"pipeline"`
+     * — matching every pre-D0050 descriptor's behavior. `"post-hoc"`
+     * artifacts are emitted by a separate command after the run finalizes
+     * and may accumulate multiple versions per run prefix.
+     */
+    readonly writePolicy?: WritePolicy;
+    /**
+     * Source of the version segment in the path (D0050). When set, the
+     * descriptor's `objectPath` produces a versioned path
+     * (`runs/{runId}/{slug}-{version}.{ext}`) and `version` is required.
+     * When unset, the path is unversioned (legacy behavior).
+     */
+    readonly versionedBy?: VersionedBy;
     /**
      * Build the GCS object path for this artifact.
      * - bulk: returns `runs/{runId}/{slug}.{ext}`; `entryKey` is ignored.
      * - per-entry: requires `entryKey`; returns `runs/{runId}/{slug}/{sanitized}.{ext}`.
+     * - versioned (`versionedBy` set): requires `version`; returns
+     *   `runs/{runId}/{slug}-{version}.{ext}` for bulk-shaped versioned
+     *   descriptors. `entryKey` is ignored on versioned bulk paths.
      */
-    readonly objectPath: (runId: RunId, entryKey?: string) => string;
+    readonly objectPath: (runId: RunId, entryKey?: string, version?: string) => string;
     /**
      * Build a filename-safe entry key from association values. Only meaningful
      * for `layout === "per-entry"` — bulk descriptors omit it.
@@ -130,6 +185,22 @@ export interface ArtifactDescriptor<TEntry = unknown, TPreview = unknown> {
      */
     readonly manifestPreview?: ManifestPreviewDeclaration<TPreview>;
 }
+/**
+ * Bulk-shaped path builder with a `{version}` segment appended to the
+ * filename stem (D0050). Used by descriptors that opt into the versioning
+ * axis via `versionedBy`. Multiple versions coexist under the same run
+ * prefix as siblings:
+ *
+ *   `runs/{runId}/{slug}-v1.{ext}`
+ *   `runs/{runId}/{slug}-v2.{ext}`
+ *
+ * The version segment is sanitized via `sanitizeEntryKey` so versions
+ * containing `/` or wire separators don't accidentally nest into
+ * subdirectories. Empty / whitespace-only versions are rejected — a
+ * versioned descriptor with no version is a programmer error, not silently
+ * collapsed to an unversioned path.
+ */
+export declare function versionedPathBuilder(slug: string, mime: ArtifactMime): (runId: RunId, _entryKey?: string, version?: string) => string;
 /** Test-only reset for the legacy-key warning flag. Not exported publicly. */
 export declare function __resetLegacyTestOutputsWarning(): void;
 /**
@@ -154,6 +225,72 @@ export declare function isArtifactType(value: string): value is ArtifactType;
  * tests can construct an invalid descriptor inline and assert the throw.
  */
 export declare function assertValidArtifactDescriptor(desc: ArtifactDescriptor): void;
+/**
+ * Thrown when a writer's identity (`writeSource`) doesn't match a
+ * descriptor's `writePolicy`. Pipeline writers can't emit `"post-hoc"`
+ * descriptors (the post-hoc artifact would land mid-run, before the run
+ * finalizes); post-hoc writers can't emit `"pipeline"` descriptors
+ * (those should have been written by the pipeline itself).
+ *
+ * The error type is intentionally distinct from `Error` so CI can match
+ * on the class and surface mismatches clearly in failure logs.
+ */
+export declare class WritePolicyMismatchError extends Error {
+    readonly code: "WRITE_POLICY_MISMATCH";
+    readonly artifactType: ArtifactType;
+    readonly descriptorPolicy: WritePolicy;
+    readonly writerSource: WriteSource;
+    constructor(opts: {
+        artifactType: ArtifactType;
+        descriptorPolicy: WritePolicy;
+        writerSource: WriteSource;
+    });
+}
+/**
+ * Resolve a descriptor's effective write policy. Defaults to `"pipeline"`
+ * when unset — preserves backward compatibility with every pre-D0050
+ * descriptor that doesn't declare the field.
+ */
+export declare function resolveWritePolicy(desc: ArtifactDescriptor): WritePolicy;
+/**
+ * Writer-side guard. Call at the top of `emit()` / `appendNdjson()` in
+ * every artifact writer that physically writes bytes (the in-memory test
+ * doubles don't need it). Throws `WritePolicyMismatchError` on
+ * mismatch; returns silently on a match. Pure function — no I/O, safe
+ * to invoke from any layer.
+ */
+export declare function assertWritePolicyMatches(writerSource: WriteSource, descriptor: ArtifactDescriptor): void;
+/**
+ * Slim-shape preview for `"post-hoc"` descriptors. Replaces the
+ * fixed-path semantics that pipeline-written artifacts use (a single
+ * known path per descriptor) with `present: boolean` plus an optional
+ * `latestVersion: string` — necessary because:
+ *
+ *   - A post-hoc artifact may have zero versions (never written) or
+ *     multiple versions (regenerated). A fixed `path` cannot encode
+ *     either.
+ *   - Slim-shape consumers (Studio rollups) want to know "is there a
+ *     diagnosis for this run?" without enumerating versioned siblings.
+ *
+ * Post-hoc writers populate `latestVersion` after a successful write
+ * (last-write-wins per-version semantics, per D0050 open-question
+ * resolution). The full versioned payload is fetched via the
+ * descriptor's `objectPath(runId, undefined, latestVersion)`.
+ */
+export declare const postHocSlimPreviewSchema: z.ZodObject<{
+    present: z.ZodBoolean;
+    latestVersion: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type PostHocSlimPreview = z.infer<typeof postHocSlimPreviewSchema>;
+/**
+ * Build a post-hoc slim-shape preview. `latestVersion` is omitted when
+ * absent rather than emitted as `undefined`, matching the optional-field
+ * convention used elsewhere in the registry.
+ */
+export declare function buildPostHocSlimPreview(opts: {
+    present: boolean;
+    latestVersion?: string;
+}): PostHocSlimPreview;
 /**
  * Build the inline preview for a manifest entry at write time. Returns
  * `undefined` when the descriptor has no `manifestPreview` declaration,

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

@@ -59,6 +59,34 @@ function perEntryPathBuilder(slug, mime) {
         return `runs/${runId}/${slug}/${sanitized}.${ext}`;
     };
 }
+/**
+ * Bulk-shaped path builder with a `{version}` segment appended to the
+ * filename stem (D0050). Used by descriptors that opt into the versioning
+ * axis via `versionedBy`. Multiple versions coexist under the same run
+ * prefix as siblings:
+ *
+ *   `runs/{runId}/{slug}-v1.{ext}`
+ *   `runs/{runId}/{slug}-v2.{ext}`
+ *
+ * The version segment is sanitized via `sanitizeEntryKey` so versions
+ * containing `/` or wire separators don't accidentally nest into
+ * subdirectories. Empty / whitespace-only versions are rejected — a
+ * versioned descriptor with no version is a programmer error, not silently
+ * collapsed to an unversioned path.
+ */
+export function versionedPathBuilder(slug, mime) {
+    const ext = mimeExtension(mime);
+    return (runId, _entryKey, version) => {
+        if (version === undefined || version.trim() === "") {
+            throw new Error(`Artifact "${slug}" uses versioned layout; a non-empty version is required`);
+        }
+        if (hasControlChars(version)) {
+            throw new Error(`Artifact "${slug}" version must not contain control characters`);
+        }
+        const sanitized = sanitizeEntryKey(version);
+        return `runs/${runId}/${slug}-${sanitized}.${ext}`;
+    };
+}
 /**
  * Convert an entry key (wire format, e.g. `{taskId}::{modelId}`) to a
  * filename-safe component.
@@ -415,9 +443,11 @@ function titleCaseCategory(id) {
         .join(" ");
 }
 function buildDescriptor(input) {
-    const objectPath = input.layout === "bulk"
-        ? bulkPathBuilder(input.slug, input.mime)
-        : perEntryPathBuilder(input.slug, input.mime);
+    const objectPath = input.versionedBy
+        ? versionedPathBuilder(input.slug, input.mime)
+        : input.layout === "bulk"
+            ? bulkPathBuilder(input.slug, input.mime)
+            : perEntryPathBuilder(input.slug, input.mime);
     const formatEntryKey = input.layout === "per-entry" ? formatKeyFromAxes(input.axes) : undefined;
     const parseEntryKey = input.layout === "per-entry"
         ? (input.parseEntryKey ?? parseKeyByAxes(input.type, input.axes))
@@ -432,6 +462,8 @@ function buildDescriptor(input) {
         capBytes: input.capBytes,
         truncation: input.truncation,
         optional: input.optional,
+        writePolicy: input.writePolicy,
+        versionedBy: input.versionedBy,
         objectPath,
         formatEntryKey,
         parseEntryKey,
@@ -943,12 +975,21 @@ export function isArtifactType(value) {
     return value in ARTIFACT_REGISTRY;
 }
 // ---------------------------------------------------------------------------
-// Module-load invariant (D0033 / W0049)
+// Module-load invariant (D0033 / W0049 / D0050)
 // ---------------------------------------------------------------------------
 /**
  * Unbounded axes — dimensions whose cardinality grows with a run. A bulk
  * artifact fanning across these cannot bound its payload; the registry
  * forbids that shape at import time.
+ *
+ * **Layout rule (D0050).** Bulk descriptors must declare *only* bounded
+ * axes — fanning a single JSON across an unbounded axis (`task`, `model`,
+ * `trial`) violates the size cap at scale. Per-entry descriptors *may*
+ * declare unbounded axes; the per-entry layout naturally produces one
+ * object per axis tuple, so unboundedness becomes the file count, not
+ * the file size. The existing `testOutputs` per-entry descriptor has
+ * carried unbounded `task`+`model` axes since W0048 and is the precedent
+ * D0050 formalizes for attribution.
  */
 const UNBOUNDED_AXES = [
     "task",
@@ -972,6 +1013,12 @@ export function assertValidArtifactDescriptor(desc) {
     if (desc.layout === "per-entry" && !desc.formatEntryKey) {
         throw new Error(`Artifact ${desc.type}: per-entry descriptors must declare formatEntryKey`);
     }
+    // D0050 — versioned descriptors are bulk-shaped only in v0; per-entry +
+    // versioned is a future extension and rejected at module load so a
+    // half-wired descriptor doesn't ship by accident.
+    if (desc.versionedBy && desc.layout !== "bulk") {
+        throw new Error(`Artifact ${desc.type}: versionedBy is only supported on bulk descriptors (got layout "${desc.layout}")`);
+    }
 }
 // Fire the invariant at import time — a bad descriptor kills the process
 // before any producer can silently serialize an oversized JSON array.
@@ -979,6 +1026,92 @@ for (const desc of Object.values(ARTIFACT_REGISTRY)) {
     assertValidArtifactDescriptor(desc);
 }
 // ---------------------------------------------------------------------------
+// Write-policy guard (D0050)
+// ---------------------------------------------------------------------------
+/**
+ * Thrown when a writer's identity (`writeSource`) doesn't match a
+ * descriptor's `writePolicy`. Pipeline writers can't emit `"post-hoc"`
+ * descriptors (the post-hoc artifact would land mid-run, before the run
+ * finalizes); post-hoc writers can't emit `"pipeline"` descriptors
+ * (those should have been written by the pipeline itself).
+ *
+ * The error type is intentionally distinct from `Error` so CI can match
+ * on the class and surface mismatches clearly in failure logs.
+ */
+export class WritePolicyMismatchError extends Error {
+    code = "WRITE_POLICY_MISMATCH";
+    artifactType;
+    descriptorPolicy;
+    writerSource;
+    constructor(opts) {
+        super(`Artifact "${opts.artifactType}" has writePolicy="${opts.descriptorPolicy}" but writer is "${opts.writerSource}". ` +
+            `Pipeline writers cannot emit post-hoc descriptors and post-hoc writers cannot emit pipeline descriptors.`);
+        this.name = "WritePolicyMismatchError";
+        this.artifactType = opts.artifactType;
+        this.descriptorPolicy = opts.descriptorPolicy;
+        this.writerSource = opts.writerSource;
+    }
+}
+/**
+ * Resolve a descriptor's effective write policy. Defaults to `"pipeline"`
+ * when unset — preserves backward compatibility with every pre-D0050
+ * descriptor that doesn't declare the field.
+ */
+export function resolveWritePolicy(desc) {
+    return desc.writePolicy ?? "pipeline";
+}
+/**
+ * Writer-side guard. Call at the top of `emit()` / `appendNdjson()` in
+ * every artifact writer that physically writes bytes (the in-memory test
+ * doubles don't need it). Throws `WritePolicyMismatchError` on
+ * mismatch; returns silently on a match. Pure function — no I/O, safe
+ * to invoke from any layer.
+ */
+export function assertWritePolicyMatches(writerSource, descriptor) {
+    const descriptorPolicy = resolveWritePolicy(descriptor);
+    if (descriptorPolicy !== writerSource) {
+        throw new WritePolicyMismatchError({
+            artifactType: descriptor.type,
+            descriptorPolicy,
+            writerSource,
+        });
+    }
+}
+// ---------------------------------------------------------------------------
+// Slim-shape preview for post-hoc artifacts (D0050)
+// ---------------------------------------------------------------------------
+/**
+ * Slim-shape preview for `"post-hoc"` descriptors. Replaces the
+ * fixed-path semantics that pipeline-written artifacts use (a single
+ * known path per descriptor) with `present: boolean` plus an optional
+ * `latestVersion: string` — necessary because:
+ *
+ *   - A post-hoc artifact may have zero versions (never written) or
+ *     multiple versions (regenerated). A fixed `path` cannot encode
+ *     either.
+ *   - Slim-shape consumers (Studio rollups) want to know "is there a
+ *     diagnosis for this run?" without enumerating versioned siblings.
+ *
+ * Post-hoc writers populate `latestVersion` after a successful write
+ * (last-write-wins per-version semantics, per D0050 open-question
+ * resolution). The full versioned payload is fetched via the
+ * descriptor's `objectPath(runId, undefined, latestVersion)`.
+ */
+export const postHocSlimPreviewSchema = z.object({
+    present: z.boolean(),
+    latestVersion: z.string().optional(),
+});
+/**
+ * Build a post-hoc slim-shape preview. `latestVersion` is omitted when
+ * absent rather than emitted as `undefined`, matching the optional-field
+ * convention used elsewhere in the registry.
+ */
+export function buildPostHocSlimPreview(opts) {
+    return opts.latestVersion === undefined
+        ? { present: opts.present }
+        : { present: opts.present, latestVersion: opts.latestVersion };
+}
+// ---------------------------------------------------------------------------
 // Manifest preview helper (W0051 / D0033 M7)
 // ---------------------------------------------------------------------------
 /**

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

@@ -18,6 +18,7 @@ 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";
+import type { LLMClient } from "./llm-client.js";
 import type { Logger } from "./logger.js";
 import type { PackageSurfaceResolver } from "./package-surface-resolver.js";
 import type { ProgressReporter } from "./progress-reporter.js";
@@ -207,6 +208,16 @@ export interface ResolvedConfig {
      * reconfiguring the gateway as well (D0030).
      */
     artifactGcsBucket?: string;
+    /**
+     * Selects the `LLMClient` adapter wired by the composition root (D0051).
+     *
+     * - `undefined` (default): auto — use Anthropic when `ANTHROPIC_API_KEY` is
+     *   present, otherwise OpenAI when `OPENAI_API_KEY` is present, otherwise
+     *   leave `llmClient` unset.
+     * - `"anthropic" | "openai"`: explicit selection. The composition root still
+     *   reads the corresponding env var; if it's missing, `llmClient` is unset.
+     */
+    llmProvider?: "anthropic" | "openai";
     /**
      * Controls whether the ArtifactUploader is constructed.
      *
@@ -247,6 +258,13 @@ export interface AppContext {
     readonly docFetcher?: DocFetcher;
     /** LLM evaluation runner (Promptfoo adapter) */
     readonly evalRunner: EvalRunner;
+    /**
+     * LLM access for non-grader features (D0051). Optional during rollout —
+     * the composition root wires it when an OpenAI or Anthropic API key is
+     * available. Consumers (diagnosis cards, meta-eval) assert presence at
+     * their own call sites.
+     */
+    readonly llmClient?: LLMClient;
     /** Structured logger */
     readonly logger: Logger;
     /**

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

@@ -11,6 +11,8 @@ export type { ConfigSource } from "./config-source.js";
 export type { AppContext, ReportSinkPort, ReportStorePort, ResolvedConfig, } from "./context.js";
 export type { DocContext, DocFetcher, DocSourceConfig, DocumentManifestEntry, DocumentOverlaySummary, FetchMetadata, FetchResult, ReleaseImpact, SymbolIndexManifestEntry, UrlFetchEntry, UrlFetchSummary, } from "./doc-fetcher.js";
 export type { EvalRunConfig, EvalRunner } from "./eval-runner.js";
+export type { LLMCallContext, LLMClient, LLMCompleteArgs, LLMCompleteStructuredArgs, LLMCompletion, LLMStructuredCompletion, LLMUsage, ModelId, ModelProvider, ParsedModelId, } from "./llm-client.js";
+export { modelId, parseModelId, splitModelId } from "./llm-client.js";
 export type { CompilationContext, CompileResultAssertion, CompileResultPrompt, CompileResultProvider, CompileResultTestCase, ModeCompileResult, ModeHandler, ModeProviderEntry, ModeRubricConfig, PromptTemplate, } from "./mode-handler.js";
 export type { Logger } from "./logger.js";
 export type { PackageSurface, PackageSurfaceResolver, PackageSurfaceSymbol, PackageSurfaceUnresolvedReason, } from "./package-surface-resolver.js";

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

@@ -5,6 +5,7 @@
  * Adapters (in packages/eval) implement these interfaces.
  */
 export { NoOpArtifactWriter } from "./artifact-writer.js";
+export { modelId, parseModelId, splitModelId } from "./llm-client.js";
 export { PackageSurfaceResolverError } from "./package-surface-resolver.js";
 export { ARTIFACT_EXPORT_PHASE_ID, NoOpProgressReporter, } from "./progress-reporter.js";
 export { canonicalDocRefLabel, isIdRef, isPathRef, isPerspectiveRef, isSlugRef, isTemplatedAssertion, } from "./task-source.js";

package/dist/_vendor/ailf-core/ports/llm-client.d.ts

@@ -0,0 +1,112 @@
+/**
+ * Port: LLM access for non-grader features.
+ *
+ * Adapters wrap a vendor REST API and centralize retry, rate-limit handling,
+ * cost calculation, and observability. Features call this port instead of
+ * importing the grader's internals or a vendor SDK directly.
+ *
+ * The grader path (`packages/eval/src/pipeline/grader-api.ts`) is intentionally
+ * NOT migrated here — D0051 defers grader migration as a follow-up.
+ *
+ * @see docs/decisions/D0051-llm-client-port.md
+ */
+import type { ZodType } from "zod";
+import { type Brand, type IdValidationError, type Result } from "../types/branded-ids.js";
+/**
+ * A canonical LLM model identifier.
+ *
+ * Grammar: `<provider>:<segment>...:<modelName>` (e.g.
+ * `"openai:chat:gpt-5.2"`, `"anthropic:messages:claude-opus-4-6"`,
+ * `"anthropic:claude-sonnet-4-6"`). Branded so adapters can trust the
+ * grammar and consumers can't accidentally pass an arbitrary string.
+ */
+export type ModelId = Brand<string, "ModelId">;
+/** The supported provider prefixes for `ModelId`. */
+export type ModelProvider = "anthropic" | "openai";
+/** Result of parsing a `ModelId` — provider plus the bare model name. */
+export interface ParsedModelId {
+    readonly id: ModelId;
+    readonly provider: ModelProvider;
+    /** Bare vendor model name with provider segments stripped. */
+    readonly modelName: string;
+}
+/**
+ * Parse a raw string into a `ParsedModelId`. Returns `Result` — never throws.
+ *
+ * Recognized prefixes:
+ * - `openai:<modelName>` or `openai:<sub>:<modelName>` (e.g. `"openai:chat:gpt-5"`)
+ * - `anthropic:<modelName>` or `anthropic:messages:<modelName>`
+ */
+export declare function parseModelId(raw: string): Result<ParsedModelId, IdValidationError>;
+/**
+ * Throwing constructor — convenient for known-good inputs (config files,
+ * tests). Throws if the id is malformed; use `parseModelId` for untrusted
+ * input.
+ */
+export declare function modelId(raw: string): ModelId;
+/**
+ * Extract `provider` + `modelName` from an already-branded `ModelId`. Assumes
+ * the id was produced by `parseModelId` / `modelId` and is therefore valid;
+ * if it isn't, the caller's bug surfaces as a thrown `Error`.
+ */
+export declare function splitModelId(id: ModelId): ParsedModelId;
+/**
+ * Per-call telemetry tag. Carried through usage / cost records so billing can
+ * roll up by feature, run, or card.
+ */
+export interface LLMCallContext {
+    /** Logical feature name (e.g. "diagnosis", "meta-eval"). */
+    feature: string;
+    /** Optional pipeline run id when the call happens inside a run. */
+    runId?: string;
+    /** Optional originating card id (for diagnosis-style features). */
+    cardId?: string;
+}
+/** Token usage reported by the vendor for a single call. */
+export interface LLMUsage {
+    promptTokens: number;
+    completionTokens: number;
+}
+/** Result of a free-text completion. */
+export interface LLMCompletion {
+    text: string;
+    usage: LLMUsage;
+    /** End-to-end USD cost for the call. */
+    cost: number;
+    /** Echo of the canonical model id used. */
+    model: ModelId;
+}
+/** Result of a structured-output completion. `value` is parsed via the supplied schema. */
+export interface LLMStructuredCompletion<T> {
+    value: T;
+    usage: LLMUsage;
+    cost: number;
+    model: ModelId;
+}
+export interface LLMCompleteArgs {
+    /** Canonical model id — produced by `modelId` / `parseModelId`. */
+    model: ModelId;
+    /** Raw prompt text — adapters wrap it in the vendor message envelope. */
+    prompt: string;
+    temperature?: number;
+    maxTokens?: number;
+    stop?: string[];
+    context?: LLMCallContext;
+}
+export interface LLMCompleteStructuredArgs<T> {
+    model: ModelId;
+    prompt: string;
+    /** Runtime contract — the adapter parses the model's response through this. */
+    schema: ZodType<T>;
+    temperature?: number;
+    maxTokens?: number;
+    context?: LLMCallContext;
+}
+/**
+ * Synthesis-side LLM port. v0 is single-call only — streaming and batching are
+ * deferred per D0051 until a consumer needs them.
+ */
+export interface LLMClient {
+    complete(args: LLMCompleteArgs): Promise<LLMCompletion>;
+    completeStructured<T>(args: LLMCompleteStructuredArgs<T>): Promise<LLMStructuredCompletion<T>>;
+}

package/dist/_vendor/ailf-core/ports/llm-client.js

@@ -0,0 +1,68 @@
+/**
+ * Port: LLM access for non-grader features.
+ *
+ * Adapters wrap a vendor REST API and centralize retry, rate-limit handling,
+ * cost calculation, and observability. Features call this port instead of
+ * importing the grader's internals or a vendor SDK directly.
+ *
+ * The grader path (`packages/eval/src/pipeline/grader-api.ts`) is intentionally
+ * NOT migrated here — D0051 defers grader migration as a follow-up.
+ *
+ * @see docs/decisions/D0051-llm-client-port.md
+ */
+import { err, ok, } from "../types/branded-ids.js";
+/**
+ * Parse a raw string into a `ParsedModelId`. Returns `Result` — never throws.
+ *
+ * Recognized prefixes:
+ * - `openai:<modelName>` or `openai:<sub>:<modelName>` (e.g. `"openai:chat:gpt-5"`)
+ * - `anthropic:<modelName>` or `anthropic:messages:<modelName>`
+ */
+export function parseModelId(raw) {
+    const parts = raw.split(":");
+    if (parts.length < 2 || parts[0] === "" || parts.some((p) => p === "")) {
+        return err({
+            code: "INVALID_MODEL_ID",
+            raw,
+            message: `Invalid ModelId "${raw}": expected "<provider>:<modelName>" with non-empty segments`,
+        });
+    }
+    const provider = parts[0];
+    if (provider === "openai") {
+        const modelName = parts.length >= 3 ? parts.slice(2).join(":") : parts.slice(1).join(":");
+        return ok({ id: raw, provider, modelName });
+    }
+    if (provider === "anthropic") {
+        const modelName = parts.length >= 3 && parts[1] === "messages"
+            ? parts.slice(2).join(":")
+            : parts.slice(1).join(":");
+        return ok({ id: raw, provider, modelName });
+    }
+    return err({
+        code: "INVALID_MODEL_ID",
+        raw,
+        message: `Invalid ModelId "${raw}": unknown provider "${provider}". Supported: openai, anthropic.`,
+    });
+}
+/**
+ * Throwing constructor — convenient for known-good inputs (config files,
+ * tests). Throws if the id is malformed; use `parseModelId` for untrusted
+ * input.
+ */
+export function modelId(raw) {
+    const result = parseModelId(raw);
+    if (!result.ok)
+        throw new Error(result.error.message);
+    return result.value.id;
+}
+/**
+ * Extract `provider` + `modelName` from an already-branded `ModelId`. Assumes
+ * the id was produced by `parseModelId` / `modelId` and is therefore valid;
+ * if it isn't, the caller's bug surfaces as a thrown `Error`.
+ */
+export function splitModelId(id) {
+    const result = parseModelId(id);
+    if (!result.ok)
+        throw new Error(result.error.message);
+    return result.value;
+}

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

@@ -0,0 +1,68 @@
+/**
+ * Shared confidence contract for actionability-ladder emitters (D0049).
+ *
+ * Every confidence-emitting site in the actionability-ladder design set
+ * (per-document attribution ensemble, structured grader judgments,
+ * diagnosis cards, regression detection) emits the same abstract triple
+ * so consumers can reason about confidence uniformly across emitters.
+ *
+ * Bucket thresholds and the formula behind `level` are emitter-specific;
+ * the externally comparable behavior is the `level` enum. Consumers that
+ * need the underlying mechanic read `derivation` and can branch.
+ */
+/**
+ * Conventional `derivation` identifiers for the seed set of emitters
+ * named in D0049. Re-exported as a typed tuple so consumers and tests can
+ * reference one source of truth instead of redeclaring the literals.
+ *
+ * Adding a new emitter does not require editing this list — `derivation`
+ * is an open tag (see `ConfidenceDerivation`). The list is the
+ * recommended starting set, not the universe.
+ */
+export declare const CONVENTIONAL_DERIVATIONS: readonly ["ensemble-stdev", "ceiling-cross-check", "regression-gate", "card-type-specific"];
+/**
+ * Tag identifying the formula used to derive `Confidence.level`.
+ *
+ * Members of `CONVENTIONAL_DERIVATIONS` are surfaced as literal variants
+ * so IDEs autocomplete the recommended set, while the trailing
+ * `(string & {})` keeps the type open — emitters that need a new
+ * identifier (per-card-type tags, future mechanics) can mint their own
+ * without editing `@sanity/ailf-core`. D0049 picked the open shape so
+ * feature work isn't coupled to core's release cycle.
+ */
+export type ConfidenceDerivation = (typeof CONVENTIONAL_DERIVATIONS)[number] | (string & {});
+/**
+ * The shared confidence triple. Every emitter populates all three fields.
+ *
+ * - `level` is bucketed (not numeric) — chosen over a 0..1 score so every
+ *   consumer doesn't have to pick its own UI buckets. Emitters may keep a
+ *   numeric internal representation and bucket at the edge.
+ * - `signalsPresent` lets consumers distinguish "1 of 1 signal said high"
+ *   from "5 of 6 signals said high" without re-deriving the underlying
+ *   mechanic.
+ * - `derivation` is a short identifier for the formula used to derive
+ *   `level`, so consumers can interpret the mechanic without
+ *   re-implementing it. Conventional values: `"ensemble-stdev"`,
+ *   `"ceiling-cross-check"`, `"regression-gate"`, `"card-type-specific"`.
+ *   Emitters may emit any non-empty string; new conventional identifiers
+ *   land as new emitters arrive.
+ */
+export type Confidence = {
+    /** Bucketed level. Comparable across emitters at this granularity. */
+    level: "high" | "medium" | "low";
+    /** Number of signals contributing to the score. Lets consumers
+     *  distinguish "1 of 1 signal said high" from "5 of 6 signals said high." */
+    signalsPresent: number;
+    /** Short identifier for the formula used to derive `level`. Lets
+     *  consumers interpret the mechanic without re-implementing it.
+     *  Conventional values: "ensemble-stdev", "ceiling-cross-check",
+     *  "regression-gate", "card-type-specific". */
+    derivation: ConfidenceDerivation;
+};
+/**
+ * Structural type guard for `Confidence`. Verifies the runtime shape
+ * matches the contract — useful at trust boundaries that can't depend on
+ * a Zod schema (the schema lives at the consuming site since each emitter
+ * picks its own `level` thresholds, but the shape is shared).
+ */
+export declare function isConfidence(value: unknown): value is Confidence;