@sanity/ailf 0.5.0 → 1.0.0

package/dist/pipeline/compiler/assertion-mapper.js

@@ -0,0 +1,175 @@
+/**
+ * Assertion type mapper — maps AILF assertion types to Promptfoo assertion types.
+ *
+ * AILF assertions have two flavors:
+ * 1. Templated assertions (`type: "llm-rubric"` with `template` + `criteria`)
+ *    → resolved into Promptfoo's `llm-rubric` with a fully assembled rubric prompt
+ * 2. Value assertions (any other `type` with a `value`)
+ *    → passed through to Promptfoo mostly as-is
+ *
+ * This module handles the mapping for both, validates mode compatibility
+ * (e.g., `tool-called` is only valid for agent-harness/mcp-server modes),
+ * and normalizes weight fields.
+ *
+ * @see docs/design-docs/architecture-overhaul/scoring-rubrics-assertions.md
+ * @see docs/exec-plans/architecture-overhaul/phase-2-config-compiler.md
+ */
+// ---------------------------------------------------------------------------
+// Known assertion types and their mode compatibility
+// ---------------------------------------------------------------------------
+/** Assertion types supported by AILF and their Promptfoo equivalents */
+const ASSERTION_TYPE_MAP = {
+    // Deterministic
+    contains: "contains",
+    "contains-all": "contains-all",
+    "contains-any": "contains-any",
+    "contains-json": "contains-json",
+    cost: "cost",
+    equals: "equals",
+    "is-json": "is-json",
+    "is-valid-openai-function-call": "is-valid-openai-function-call",
+    "is-valid-openai-tools-call": "is-valid-openai-tools-call",
+    latency: "latency",
+    regex: "regex",
+    // Programmatic
+    javascript: "javascript",
+    python: "python",
+    // LLM-graded
+    "g-eval": "g-eval",
+    "llm-rubric": "llm-rubric",
+    "model-graded-closedqa": "model-graded-closedqa",
+    "model-graded-factuality": "model-graded-factuality",
+    similar: "similar",
+    // Tool-use (agent/MCP modes)
+    "skill-used": "javascript", // Custom JS assertion checking tool calls
+    "tool-call-f1": "javascript", // Custom JS assertion computing F1
+    "tool-called": "javascript", // Custom JS assertion checking specific tool
+};
+/** Assertion types restricted to specific modes.
+ * "literacy" is included because the agentic literacy variant uses tool calls. */
+const MODE_RESTRICTED_TYPES = {
+    "skill-used": ["agent-harness", "mcp-server", "literacy"],
+    "tool-call-f1": ["agent-harness", "mcp-server", "literacy"],
+    "tool-called": ["agent-harness", "mcp-server", "literacy"],
+};
+/** Negatable assertion types (Promptfoo supports `not-` prefix) */
+const NEGATABLE_TYPES = new Set([
+    "contains",
+    "contains-all",
+    "contains-any",
+    "equals",
+    "is-json",
+    "regex",
+]);
+/**
+ * Map an array of AILF assertions to Promptfoo assertions.
+ *
+ * @param assertions - AILF assertion definitions
+ * @param options - Mapper options
+ * @returns Mapped Promptfoo assertions and any warnings
+ */
+export function mapAssertions(assertions, options) {
+    const mapped = [];
+    const warnings = [];
+    for (const assertion of assertions) {
+        const result = mapSingleAssertion(assertion, options);
+        if (result.warning) {
+            warnings.push(result.warning);
+        }
+        if (result.assertion) {
+            mapped.push(result.assertion);
+        }
+    }
+    return { mapped, warnings };
+}
+/**
+ * Check if an assertion type is valid.
+ */
+export function isValidAssertionType(type) {
+    const baseType = type.startsWith("not-") ? type.slice(4) : type;
+    return baseType in ASSERTION_TYPE_MAP;
+}
+/**
+ * Check if an assertion type is compatible with a given mode.
+ */
+export function isAssertionCompatibleWithMode(type, mode) {
+    const baseType = type.startsWith("not-") ? type.slice(4) : type;
+    const restrictions = MODE_RESTRICTED_TYPES[baseType];
+    if (!restrictions)
+        return true; // No restrictions
+    return restrictions.includes(mode);
+}
+// ---------------------------------------------------------------------------
+// Internal mapping
+// ---------------------------------------------------------------------------
+function mapSingleAssertion(assertion, options) {
+    const { type } = assertion;
+    // Check mode compatibility
+    if (options?.mode) {
+        if (!isAssertionCompatibleWithMode(type, options.mode)) {
+            return {
+                assertion: null,
+                warning: `Assertion type "${type}" is not compatible with mode "${options.mode}" — skipped`,
+            };
+        }
+    }
+    // Handle negation
+    const isNegated = type.startsWith("not-");
+    const baseType = isNegated ? type.slice(4) : type;
+    if (isNegated && !NEGATABLE_TYPES.has(baseType)) {
+        return {
+            assertion: null,
+            warning: `Assertion type "${type}" does not support negation — skipped`,
+        };
+    }
+    // Templated assertions (llm-rubric with template + criteria)
+    if (isTemplated(assertion)) {
+        return {
+            assertion: mapTemplatedAssertion(assertion, options),
+            warning: null,
+        };
+    }
+    // Value assertions — map type and pass through
+    const promptfooType = ASSERTION_TYPE_MAP[baseType];
+    if (!promptfooType) {
+        // Unknown type — pass through as-is (Promptfoo may support it natively)
+        return {
+            assertion: mapValueAssertion(assertion, type),
+            warning: `Unknown assertion type "${type}" — passed through to Promptfoo as-is`,
+        };
+    }
+    const mappedType = isNegated ? `not-${promptfooType}` : promptfooType;
+    return {
+        assertion: mapValueAssertion(assertion, mappedType),
+        warning: null,
+    };
+}
+function isTemplated(assertion) {
+    return (assertion.type === "llm-rubric" &&
+        "template" in assertion &&
+        "criteria" in assertion);
+}
+function mapTemplatedAssertion(assertion, options) {
+    const result = {
+        type: "llm-rubric",
+        // The rubric prompt will be fully assembled by the PromptfooCompiler
+        // using rubric templates. Here we pass the template ref + criteria
+        // as metadata so the compiler can resolve it.
+        value: `[template:${assertion.template}] ${assertion.criteria.join("; ")}`,
+    };
+    if (assertion.weight !== undefined) {
+        result.weight = assertion.weight;
+    }
+    if (options?.graderProvider) {
+        result.provider = options.graderProvider;
+    }
+    return result;
+}
+function mapValueAssertion(assertion, mappedType) {
+    const { type: _type, ...rest } = assertion;
+    const result = {
+        type: mappedType,
+        ...rest,
+    };
+    return result;
+}

package/dist/pipeline/compiler/compiler-to-yaml.d.ts

@@ -0,0 +1,51 @@
+/**
+ * compiler-to-yaml.ts — Serialize compiled Promptfoo config to YAML files.
+ *
+ * This is the bridge between the new compiler pipeline (in-memory
+ * CompiledPromptfooConfig) and the existing RunEvalStep which reads
+ * YAML config files from disk.
+ *
+ * The output YAML files are identical in structure to what the legacy
+ * generate-configs.ts produces, so RunEvalStep, CalculateScoresStep,
+ * and all downstream steps work without modification.
+ *
+ * @see packages/eval/src/pipeline/generate-configs.ts — legacy path
+ * @see packages/eval/src/orchestration/steps/run-eval-step.ts — consumer
+ */
+import type { Logger, ModeCompileResult } from "../../_vendor/ailf-core/index.d.ts";
+/** Options for writing compiled config to YAML */
+export interface WriteCompiledConfigOptions {
+    /** Root directory of the eval package */
+    rootDir: string;
+    /** Grader provider ID (e.g., "openai:chat:gpt-5") */
+    graderProvider: string;
+    /** Max concurrency for evaluation */
+    maxConcurrency?: number;
+    /** Logger instance */
+    logger?: Logger;
+}
+/**
+ * Write compiled literacy results to the same YAML files the legacy
+ * path produces, so RunEvalStep can consume them unchanged.
+ *
+ * Writes:
+ *   - tasks/.expanded.yaml (gold + baseline test entries for baseline mode)
+ *   - tasks/.expanded.agentic.yaml (gold-only entries for agentic mode)
+ * Write a single Promptfoo config YAML file for any non-literacy mode.
+ *
+ * This is the generic writer that works with any ModeCompileResult.
+ * Literacy uses its own multi-file writer below.
+ */
+export declare function writeCompiledModeConfig(result: ModeCompileResult, mode: string, options: WriteCompiledConfigOptions): void;
+/**
+ * Write three literacy-specific Promptfoo config YAML files.
+ *
+ *   - promptfooconfig.yaml (baseline config)
+ *   - promptfooconfig.agentic.yaml (agentic config)
+ *   - promptfooconfig.observed.yaml (observed config — same structure as baseline)
+ */
+export declare function writeCompiledLiteracyConfigs(baselineResult: ModeCompileResult, agenticResult: ModeCompileResult, providers: {
+    baseline: Record<string, unknown>[];
+    agentic: Record<string, unknown>[];
+    observed: Record<string, unknown>[];
+}, options: WriteCompiledConfigOptions): void;

package/dist/pipeline/compiler/compiler-to-yaml.js

@@ -0,0 +1,222 @@
+/**
+ * compiler-to-yaml.ts — Serialize compiled Promptfoo config to YAML files.
+ *
+ * This is the bridge between the new compiler pipeline (in-memory
+ * CompiledPromptfooConfig) and the existing RunEvalStep which reads
+ * YAML config files from disk.
+ *
+ * The output YAML files are identical in structure to what the legacy
+ * generate-configs.ts produces, so RunEvalStep, CalculateScoresStep,
+ * and all downstream steps work without modification.
+ *
+ * @see packages/eval/src/pipeline/generate-configs.ts — legacy path
+ * @see packages/eval/src/orchestration/steps/run-eval-step.ts — consumer
+ */
+import { existsSync, mkdirSync, writeFileSync } from "fs";
+import { resolve } from "path";
+import { dump } from "js-yaml";
+/**
+ * URL extraction assertion — advisory (weight: 0).
+ * Extracts all URLs from the output for telemetry.
+ * Matches legacy generate-configs.ts behavior.
+ */
+const URL_EXTRACTION_ASSERT = {
+    type: "javascript",
+    value: `const urlPattern = /https?:\\/\\/[^\\s\\)\\"\\'\\\`>]+/g;
+const urls = [...new Set((output.match(urlPattern) || []))];
+const sanityUrls = urls.filter(u => u.includes('sanity.io'));
+return {
+  pass: true,
+  score: 1,
+  reason: JSON.stringify({
+    sanityUrls,
+    otherUrls: urls.filter(u => !u.includes('sanity.io')),
+    totalUrlCount: urls.length,
+    sanityUrlCount: sanityUrls.length
+  })
+};`,
+    weight: 0,
+};
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+/**
+ * Write compiled literacy results to the same YAML files the legacy
+ * path produces, so RunEvalStep can consume them unchanged.
+ *
+ * Writes:
+ *   - tasks/.expanded.yaml (gold + baseline test entries for baseline mode)
+ *   - tasks/.expanded.agentic.yaml (gold-only entries for agentic mode)
+ * Write a single Promptfoo config YAML file for any non-literacy mode.
+ *
+ * This is the generic writer that works with any ModeCompileResult.
+ * Literacy uses its own multi-file writer below.
+ */
+export function writeCompiledModeConfig(result, mode, options) {
+    const filename = `promptfooconfig.${mode}.yaml`;
+    const outputPath = `results/latest/eval-results-${mode}.json`;
+    // Ensure results directory exists
+    const resultsDir = resolve(options.rootDir, "results/latest");
+    if (!existsSync(resultsDir)) {
+        mkdirSync(resultsDir, { recursive: true });
+    }
+    // Write expanded test entries to a JSON file
+    const testsFilename = `results/latest/${mode}-tests.json`;
+    const testsPath = resolve(options.rootDir, testsFilename);
+    const expandedTests = testsToExpandedEntries(result.tests);
+    writeFileSync(testsPath, JSON.stringify(expandedTests, null, 2), "utf-8");
+    // Build grader options
+    const graderOpts = {};
+    if (options.graderProvider) {
+        graderOpts.provider = options.graderProvider;
+    }
+    // Build provider entries
+    const providerEntries = result.providers.map((p) => {
+        if (p.config)
+            return { id: p.id, label: p.label, config: p.config };
+        return p.label ? { id: p.id, label: p.label } : p.id;
+    });
+    // Build prompt entries
+    const prompts = result.prompts.map((p) => ({
+        id: p.id,
+        label: p.label,
+        raw: p.raw,
+    }));
+    // Assemble and write
+    const config = assembleConfig({
+        description: `AILF ${mode} evaluation`,
+        graderOpts,
+        maxConcurrency: options.maxConcurrency,
+        outputPath,
+        prompts,
+        providers: providerEntries,
+        tests: [testsFilename],
+    });
+    // Include extensions if present (agent-harness mode)
+    if (result.extras?.extensions) {
+        ;
+        config.extensions =
+            result.extras.extensions;
+    }
+    writeConfig(options.rootDir, filename, config, options.logger);
+}
+/**
+ * Write three literacy-specific Promptfoo config YAML files.
+ *
+ *   - promptfooconfig.yaml (baseline config)
+ *   - promptfooconfig.agentic.yaml (agentic config)
+ *   - promptfooconfig.observed.yaml (observed config — same structure as baseline)
+ */
+export function writeCompiledLiteracyConfigs(baselineResult, agenticResult, providers, options) {
+    const { rootDir, graderProvider, logger: log } = options;
+    // Ensure tasks/ directory exists
+    const tasksDir = resolve(rootDir, "tasks");
+    if (!existsSync(tasksDir)) {
+        mkdirSync(tasksDir, { recursive: true });
+    }
+    // Write expanded test entries (same format as expand-tasks.ts output)
+    const baselineEntries = testsToExpandedEntries(baselineResult.tests);
+    const agenticEntries = testsToExpandedEntries(agenticResult.tests);
+    writeYaml(resolve(rootDir, "tasks", ".expanded.yaml"), baselineEntries, "# .expanded.yaml\n#\n# AUTO-GENERATED by compiler pipeline — do not edit directly.\n# Run: npx @sanity/ailf generate-configs\n");
+    log?.info(`  ✓ tasks/.expanded.yaml (${baselineEntries.length} entries)`);
+    writeYaml(resolve(rootDir, "tasks", ".expanded.agentic.yaml"), agenticEntries, "# .expanded.agentic.yaml\n#\n# AUTO-GENERATED by compiler pipeline — do not edit directly.\n# Gold entries only (no baseline) for agentic evaluation mode.\n# Run: npx @sanity/ailf generate-configs\n");
+    log?.info(`  ✓ tasks/.expanded.agentic.yaml (${agenticEntries.length} entries)`);
+    const taskFiles = ["file://tasks/.expanded.yaml"];
+    const agenticTaskFiles = ["file://tasks/.expanded.agentic.yaml"];
+    // Assemble and write promptfoo config files
+    const graderOpts = {
+        provider: graderProvider,
+        rubricProvider: graderProvider,
+    };
+    const maxConc = options.maxConcurrency;
+    // Baseline config
+    const baselineConfig = assembleConfig({
+        description: "Sanity AI Literacy Evaluation — Baseline",
+        prompts: baselineResult.prompts,
+        providers: providers.baseline,
+        tests: taskFiles,
+        outputPath: "results/latest/eval-results.json",
+        graderOpts,
+        maxConcurrency: maxConc,
+    });
+    writeConfig(rootDir, "promptfooconfig.yaml", baselineConfig, log);
+    // Observed config (same structure as baseline, different providers)
+    const observedConfig = assembleConfig({
+        description: "Sanity AI Literacy Evaluation — Observed",
+        prompts: baselineResult.prompts,
+        providers: providers.observed,
+        tests: taskFiles,
+        outputPath: "results/latest/eval-results-observed.json",
+        graderOpts,
+        maxConcurrency: maxConc,
+    });
+    writeConfig(rootDir, "promptfooconfig.observed.yaml", observedConfig, log);
+    // Agentic config
+    const agenticConfig = assembleConfig({
+        description: "Sanity AI Literacy Evaluation — Agentic (naive vs optimized)",
+        prompts: agenticResult.prompts,
+        providers: providers.agentic,
+        tests: agenticTaskFiles,
+        outputPath: "results/latest/eval-results-agentic.json",
+        graderOpts,
+        maxConcurrency: maxConc,
+    });
+    writeConfig(rootDir, "promptfooconfig.agentic.yaml", agenticConfig, log);
+    log?.info("\nDone! Configs are ready (via compiler pipeline).");
+}
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+/** Convert compiler test cases to expanded entry format (matching legacy YAML) */
+function testsToExpandedEntries(tests) {
+    return tests.map((test) => {
+        const entry = {};
+        if (test.description)
+            entry.description = test.description;
+        if (test.vars)
+            entry.vars = test.vars;
+        if (test.assert && test.assert.length > 0)
+            entry.assert = test.assert;
+        if (test.prompts)
+            entry.prompts = test.prompts;
+        return entry;
+    });
+}
+function assembleConfig(opts) {
+    return {
+        commandLineOptions: { table: false },
+        defaultTest: {
+            assert: [URL_EXTRACTION_ASSERT],
+            options: opts.graderOpts,
+        },
+        description: opts.description,
+        ...(opts.maxConcurrency
+            ? { evaluateOptions: { maxConcurrency: opts.maxConcurrency } }
+            : {}),
+        outputPath: opts.outputPath,
+        prompts: opts.prompts,
+        providers: opts.providers,
+        tests: opts.tests,
+    };
+}
+function writeConfig(rootDir, filename, config, log) {
+    const yamlStr = dump(config, {
+        forceQuotes: false,
+        lineWidth: 120,
+        noRefs: true,
+        quotingType: "'",
+    });
+    const header = `# ${filename}\n#\n# AUTO-GENERATED by compiler pipeline — do not edit directly.\n# Run: npx @sanity/ailf generate-configs\n`;
+    const outPath = resolve(rootDir, filename);
+    writeFileSync(outPath, `${header}\n${yamlStr}`, "utf-8");
+    log?.info(`  ✓ ${filename}`);
+}
+function writeYaml(path, data, header) {
+    const yamlStr = dump(data, {
+        forceQuotes: false,
+        lineWidth: 120,
+        noRefs: true,
+        quotingType: "'",
+    });
+    writeFileSync(path, `${header}\n${yamlStr}`, "utf-8");
+}

package/dist/pipeline/compiler/config-loader.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Unified config file loader — resolves TS/JS/YAML/JSON with format priority.
+ *
+ * Provides a single `loadConfigFile()` function that replaces the scattered
+ * `readFileSync + load(raw)` pattern throughout the pipeline. Checks for
+ * TypeScript/JavaScript config files first (via jiti), falling back to YAML
+ * and JSON — matching the resolution order established in Phase 1.
+ *
+ * Priority: `.ts` > `.js` > `.yaml` > `.yml` > `.json`
+ *
+ * Usage:
+ * ```ts
+ * // Before (scattered pattern):
+ * const raw = readFileSync(resolve(rootDir, "config", "models config"), "utf-8")
+ * const config = load(raw) as ModelsConfig
+ *
+ * // After:
+ * const config = loadConfigFile<ModelsConfig>("models", rootDir)
+ * ```
+ *
+ * @see packages/eval/src/adapters/config-sources/ts-config-loader.ts — jiti loader
+ * @see docs/design-docs/architecture-overhaul/typescript-configuration.md
+ */
+export interface ConfigLoadResult<T> {
+    /** The parsed configuration data */
+    data: T;
+    /** The file that was loaded */
+    filePath: string;
+    /** The format that was used */
+    format: "ts" | "js" | "yaml" | "json";
+}
+/**
+ * Load a config file by name, searching for TS/JS/YAML/JSON variants.
+ *
+ * @param name - Config name without extension (e.g., "models", "rubrics")
+ * @param rootDir - Package root directory containing `config/`
+ * @param options - Optional: subdirectory (default "config"), required flag
+ * @returns The parsed config data
+ * @throws If the file is not found (when required) or fails to parse
+ */
+export declare function loadConfigFile<T>(name: string, rootDir: string, options?: {
+    subdir?: string;
+}): ConfigLoadResult<T>;
+/**
+ * Try to load a config file, returning null if not found.
+ * Equivalent to loadConfigFile with required: false but with a cleaner API.
+ */
+export declare function tryLoadConfigFile<T>(name: string, rootDir: string, options?: {
+    subdir?: string;
+}): ConfigLoadResult<T> | null;
+/** Sentinel error for config-not-found (distinct from parse errors) */
+export declare class ConfigNotFoundError extends Error {
+    readonly configName: string;
+    readonly searchDir: string;
+    constructor(configName: string, searchDir: string);
+}

package/dist/pipeline/compiler/config-loader.js

@@ -0,0 +1,111 @@
+/**
+ * Unified config file loader — resolves TS/JS/YAML/JSON with format priority.
+ *
+ * Provides a single `loadConfigFile()` function that replaces the scattered
+ * `readFileSync + load(raw)` pattern throughout the pipeline. Checks for
+ * TypeScript/JavaScript config files first (via jiti), falling back to YAML
+ * and JSON — matching the resolution order established in Phase 1.
+ *
+ * Priority: `.ts` > `.js` > `.yaml` > `.yml` > `.json`
+ *
+ * Usage:
+ * ```ts
+ * // Before (scattered pattern):
+ * const raw = readFileSync(resolve(rootDir, "config", "models config"), "utf-8")
+ * const config = load(raw) as ModelsConfig
+ *
+ * // After:
+ * const config = loadConfigFile<ModelsConfig>("models", rootDir)
+ * ```
+ *
+ * @see packages/eval/src/adapters/config-sources/ts-config-loader.ts — jiti loader
+ * @see docs/design-docs/architecture-overhaul/typescript-configuration.md
+ */
+import { createRequire } from "module";
+import { existsSync, readFileSync } from "fs";
+import { load } from "js-yaml";
+import { resolve } from "path";
+/**
+ * Load a config file by name, searching for TS/JS/YAML/JSON variants.
+ *
+ * @param name - Config name without extension (e.g., "models", "rubrics")
+ * @param rootDir - Package root directory containing `config/`
+ * @param options - Optional: subdirectory (default "config"), required flag
+ * @returns The parsed config data
+ * @throws If the file is not found (when required) or fails to parse
+ */
+export function loadConfigFile(name, rootDir, options) {
+    const subdir = options?.subdir ?? "config";
+    const basePath = resolve(rootDir, subdir, name);
+    // Priority chain: .ts > .js > .yaml > .yml > .json
+    const candidates = [
+        { ext: ".ts", format: "ts" },
+        { ext: ".js", format: "js" },
+        { ext: ".yaml", format: "yaml" },
+        { ext: ".yml", format: "yaml" },
+        { ext: ".json", format: "json" },
+    ];
+    for (const { ext, format } of candidates) {
+        const filePath = basePath + ext;
+        if (!existsSync(filePath))
+            continue;
+        if (format === "ts" || format === "js") {
+            return loadTsFile(filePath, format);
+        }
+        if (format === "yaml") {
+            return loadYamlFile(filePath);
+        }
+        if (format === "json") {
+            return loadJsonFile(filePath);
+        }
+    }
+    // Always throw ConfigNotFoundError so tryLoadConfigFile can catch it
+    throw new ConfigNotFoundError(name, resolve(rootDir, subdir));
+}
+/**
+ * Try to load a config file, returning null if not found.
+ * Equivalent to loadConfigFile with required: false but with a cleaner API.
+ */
+export function tryLoadConfigFile(name, rootDir, options) {
+    try {
+        return loadConfigFile(name, rootDir, options);
+    }
+    catch (err) {
+        if (err instanceof ConfigNotFoundError)
+            return null;
+        throw err;
+    }
+}
+/** Sentinel error for config-not-found (distinct from parse errors) */
+export class ConfigNotFoundError extends Error {
+    configName;
+    searchDir;
+    constructor(configName, searchDir) {
+        super(`Config "${configName}" not found in ${searchDir}`);
+        this.configName = configName;
+        this.searchDir = searchDir;
+        this.name = "ConfigNotFoundError";
+    }
+}
+// ---------------------------------------------------------------------------
+// Format-specific loaders
+// ---------------------------------------------------------------------------
+function loadTsFile(filePath, format) {
+    // jiti supports sync loading. Use createRequire for ESM compatibility.
+    const esmRequire = createRequire(import.meta.url);
+    const { createJiti } = esmRequire("jiti");
+    const jiti = createJiti(filePath, { interopDefault: true });
+    const mod = jiti(filePath);
+    const data = (mod?.default ?? mod);
+    return { data, filePath, format };
+}
+function loadYamlFile(filePath) {
+    const raw = readFileSync(filePath, "utf-8");
+    const data = load(raw);
+    return { data, filePath, format: "yaml" };
+}
+function loadJsonFile(filePath) {
+    const raw = readFileSync(filePath, "utf-8");
+    const data = JSON.parse(raw);
+    return { data, filePath, format: "json" };
+}

package/dist/pipeline/compiler/fixture-resolver.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Fixture resolver — resolves fixture references into content for compilation.
+ *
+ * Handles document fixtures (fetched from Sanity or local files),
+ * file fixtures (read from disk), and inline fixtures (embedded in
+ * task definitions). Resolved content is injected into the TaskNode's
+ * VariableEnvelope for the compiler to use.
+ *
+ * Currently supports the existing fixture patterns:
+ * - `file://contexts/canonical/<id>.md` → read from local fs
+ * - Inline `vars.docs` strings → used as-is
+ * - Canonical doc references → resolved by DocFetcher port
+ *
+ * Future phases will add URI scheme resolution (repo://, sanity://, etc.)
+ * as described in the fixtures-artifacts design doc.
+ *
+ * @see docs/design-docs/architecture-overhaul/fixtures-artifacts.md
+ * @see docs/exec-plans/architecture-overhaul/phase-2-config-compiler.md
+ */
+import type { GeneralizedTaskDefinition, ResolvedFixture, VariableEnvelope } from "../../_vendor/ailf-core/index.d.ts";
+/** Options for fixture resolution */
+export interface FixtureResolverOptions {
+    /** Root directory for resolving relative paths */
+    rootDir: string;
+}
+/** Result of resolving fixtures for a task */
+export interface FixtureResolutionResult {
+    /** Resolved fixture content, keyed by fixture ID */
+    fixtures: Map<string, ResolvedFixture>;
+    /** Updated variable envelope with resolved doc content */
+    updatedVars: VariableEnvelope;
+    /** Warnings from resolution (non-fatal issues) */
+    warnings: string[];
+}
+/**
+ * Resolve fixtures for a task definition.
+ *
+ * Reads `vars.docs` and canonical doc references, resolves them to
+ * content, and updates the variable envelope.
+ */
+export declare function resolveTaskFixtures(task: GeneralizedTaskDefinition, currentVars: VariableEnvelope, options: FixtureResolverOptions): FixtureResolutionResult;