@sanity/ailf 0.5.0 → 1.0.0

package/dist/pipeline/compiler/fixture-resolver.js

@@ -0,0 +1,113 @@
+/**
+ * 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 { existsSync, readFileSync } from "fs";
+import { resolve } from "path";
+import { simpleHash } from "./hash.js";
+/**
+ * Resolve fixtures for a task definition.
+ *
+ * Reads `vars.docs` and canonical doc references, resolves them to
+ * content, and updates the variable envelope.
+ */
+export function resolveTaskFixtures(task, currentVars, options) {
+    const fixtures = new Map();
+    const warnings = [];
+    const updatedValues = { ...currentVars.values };
+    const updatedProvenance = { ...currentVars.provenance };
+    // Resolve file:// references in vars
+    for (const [key, value] of Object.entries(updatedValues)) {
+        if (typeof value === "string" && value.startsWith("file://")) {
+            const resolved = resolveFileRef(value, options.rootDir);
+            if (resolved.ok) {
+                updatedValues[key] = resolved.content;
+                updatedProvenance[key] = {
+                    hash: simpleHash(resolved.content),
+                    resolvedAt: new Date().toISOString(),
+                    source: { fixtureId: value, type: "fixture" },
+                };
+                fixtures.set(value, {
+                    content: resolved.content,
+                    contentHash: simpleHash(resolved.content),
+                    id: value,
+                    name: value.replace("file://", ""),
+                    type: "fetched",
+                });
+            }
+            else {
+                warnings.push(resolved.error);
+            }
+        }
+    }
+    // Resolve canonical doc context if any — extract docs from the mode-specific
+    // context field (context.docs exists on literacy, mcp-server, agent-harness,
+    // and knowledge-probe variants)
+    const contextDocs = "context" in task && task.context?.docs ? task.context.docs : [];
+    if (contextDocs.length > 0) {
+        const docFixtureId = `canonical-docs:${task.id}`;
+        // Canonical docs are resolved at runtime by the DocFetcher port.
+        // At compile time, we create a placeholder fixture that signals
+        // the compiler to inject doc context at eval time.
+        fixtures.set(docFixtureId, {
+            content: null, // Deferred — resolved at eval time
+            id: docFixtureId,
+            name: `Canonical docs for ${task.id}`,
+            type: "fetched",
+        });
+    }
+    return {
+        fixtures,
+        updatedVars: {
+            declarations: currentVars.declarations,
+            provenance: updatedProvenance,
+            values: updatedValues,
+        },
+        warnings,
+    };
+}
+/**
+ * Resolve a `file://` reference to file content.
+ */
+function resolveFileRef(fileRef, rootDir) {
+    const relativePath = fileRef.replace("file://", "");
+    const absolutePath = resolve(rootDir, relativePath);
+    // Path containment: prevent file://../../etc/passwd from reading outside rootDir
+    const normalizedBase = resolve(rootDir) + "/";
+    if (!absolutePath.startsWith(normalizedBase) &&
+        absolutePath !== resolve(rootDir)) {
+        return {
+            ok: false,
+            error: `Path traversal detected: "${fileRef}" resolves outside rootDir "${rootDir}"`,
+        };
+    }
+    if (!existsSync(absolutePath)) {
+        return {
+            ok: false,
+            error: `Fixture file not found: ${absolutePath} (referenced as ${fileRef})`,
+        };
+    }
+    try {
+        const content = readFileSync(absolutePath, "utf-8");
+        return { ok: true, content };
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        return { ok: false, error: `Failed to read fixture ${fileRef}: ${msg}` };
+    }
+}

package/dist/pipeline/compiler/hash.d.ts

@@ -0,0 +1,11 @@
+/**
+ * FNV-1a 32-bit hash — fast, non-cryptographic content hash.
+ *
+ * Used for cache keys, content fingerprinting, and provenance tracking.
+ * Returns an 8-character zero-padded hex string.
+ *
+ * Shared across fixture-resolver, variable-resolver, and trace-store
+ * to ensure consistent hash behavior. Uses unsigned right shift (`>>> 0`)
+ * to keep the hash in unsigned 32-bit integer range.
+ */
+export declare function simpleHash(content: string): string;

package/dist/pipeline/compiler/hash.js

@@ -0,0 +1,18 @@
+/**
+ * FNV-1a 32-bit hash — fast, non-cryptographic content hash.
+ *
+ * Used for cache keys, content fingerprinting, and provenance tracking.
+ * Returns an 8-character zero-padded hex string.
+ *
+ * Shared across fixture-resolver, variable-resolver, and trace-store
+ * to ensure consistent hash behavior. Uses unsigned right shift (`>>> 0`)
+ * to keep the hash in unsigned 32-bit integer range.
+ */
+export function simpleHash(content) {
+    let hash = 0x811c9dc5; // FNV-1a offset basis
+    for (let i = 0; i < content.length; i++) {
+        hash ^= content.charCodeAt(i);
+        hash = (hash * 0x01000193) >>> 0; // FNV prime, unsigned 32-bit
+    }
+    return hash.toString(16).padStart(8, "0");
+}

package/dist/pipeline/compiler/ignore-fields.d.ts

@@ -0,0 +1,53 @@
+/**
+ * ignoreFields — strips non-deterministic fields before assertion comparison.
+ *
+ * For tool outputs that contain timestamps, UUIDs, temp paths, or other
+ * non-deterministic values, assertions need a way to exclude specific
+ * fields from comparison. This module provides field stripping using
+ * dot-notation paths.
+ *
+ * Usage in task definitions:
+ * ```typescript
+ * assertions: [
+ *   {
+ *     type: "tool-output-matches",
+ *     value: { title: "Hello" },
+ *     ignoreFields: ["metadata.createdAt", "result.id", "_rev"],
+ *   },
+ * ]
+ * ```
+ *
+ * @see docs/exec-plans/architecture-overhaul/phase-4-agent-harness.md
+ */
+/**
+ * Strip specified fields from an object using dot-notation paths.
+ *
+ * @param obj - The object to strip fields from (not mutated)
+ * @param fields - Dot-notation field paths to remove
+ * @returns A new object with the specified fields removed
+ *
+ * @example
+ * ```typescript
+ * stripFields(
+ *   { title: "Hello", metadata: { createdAt: "2024-01-01", author: "Alice" } },
+ *   ["metadata.createdAt"]
+ * )
+ * // => { title: "Hello", metadata: { author: "Alice" } }
+ * ```
+ */
+export declare function stripFields(obj: unknown, fields: string[]): unknown;
+/**
+ * Strip specified fields from both actual and expected values,
+ * then compare them.
+ *
+ * @returns true if the objects are equal after stripping
+ */
+export declare function compareWithIgnoredFields(actual: unknown, expected: unknown, ignoreFields: string[]): boolean;
+/**
+ * Generate a Promptfoo-compatible JavaScript assertion that applies
+ * ignoreFields stripping before comparison.
+ *
+ * This wraps a comparison assertion with field stripping logic,
+ * producing a self-contained JS assertion string.
+ */
+export declare function buildIgnoreFieldsWrapper(comparisonCode: string, ignoreFields: string[]): string;

package/dist/pipeline/compiler/ignore-fields.js

@@ -0,0 +1,113 @@
+/**
+ * ignoreFields — strips non-deterministic fields before assertion comparison.
+ *
+ * For tool outputs that contain timestamps, UUIDs, temp paths, or other
+ * non-deterministic values, assertions need a way to exclude specific
+ * fields from comparison. This module provides field stripping using
+ * dot-notation paths.
+ *
+ * Usage in task definitions:
+ * ```typescript
+ * assertions: [
+ *   {
+ *     type: "tool-output-matches",
+ *     value: { title: "Hello" },
+ *     ignoreFields: ["metadata.createdAt", "result.id", "_rev"],
+ *   },
+ * ]
+ * ```
+ *
+ * @see docs/exec-plans/architecture-overhaul/phase-4-agent-harness.md
+ */
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+/**
+ * Strip specified fields from an object using dot-notation paths.
+ *
+ * @param obj - The object to strip fields from (not mutated)
+ * @param fields - Dot-notation field paths to remove
+ * @returns A new object with the specified fields removed
+ *
+ * @example
+ * ```typescript
+ * stripFields(
+ *   { title: "Hello", metadata: { createdAt: "2024-01-01", author: "Alice" } },
+ *   ["metadata.createdAt"]
+ * )
+ * // => { title: "Hello", metadata: { author: "Alice" } }
+ * ```
+ */
+export function stripFields(obj, fields) {
+    if (!fields || fields.length === 0)
+        return obj;
+    if (obj === null || obj === undefined)
+        return obj;
+    if (typeof obj !== "object")
+        return obj;
+    // Deep clone to avoid mutation
+    const clone = JSON.parse(JSON.stringify(obj));
+    for (const field of fields) {
+        removeFieldByPath(clone, field.split("."));
+    }
+    return clone;
+}
+/**
+ * Strip specified fields from both actual and expected values,
+ * then compare them.
+ *
+ * @returns true if the objects are equal after stripping
+ */
+export function compareWithIgnoredFields(actual, expected, ignoreFields) {
+    const strippedActual = stripFields(actual, ignoreFields);
+    const strippedExpected = stripFields(expected, ignoreFields);
+    return JSON.stringify(strippedActual) === JSON.stringify(strippedExpected);
+}
+/**
+ * Generate a Promptfoo-compatible JavaScript assertion that applies
+ * ignoreFields stripping before comparison.
+ *
+ * This wraps a comparison assertion with field stripping logic,
+ * producing a self-contained JS assertion string.
+ */
+export function buildIgnoreFieldsWrapper(comparisonCode, ignoreFields) {
+    if (ignoreFields.length === 0)
+        return comparisonCode;
+    const stripFn = `function stripFields(obj, fields) {\n` +
+        `  if (!obj || typeof obj !== 'object') return obj;\n` +
+        `  const clone = JSON.parse(JSON.stringify(obj));\n` +
+        `  for (const field of fields) {\n` +
+        `    const parts = field.split('.');\n` +
+        `    let current = clone;\n` +
+        `    for (let i = 0; i < parts.length - 1; i++) {\n` +
+        `      if (!current || typeof current !== 'object') break;\n` +
+        `      current = current[parts[i]];\n` +
+        `    }\n` +
+        `    if (current && typeof current === 'object') {\n` +
+        `      delete current[parts[parts.length - 1]];\n` +
+        `    }\n` +
+        `  }\n` +
+        `  return clone;\n` +
+        `}\n`;
+    return (`${stripFn}\n` +
+        `const __ignoreFields = ${JSON.stringify(ignoreFields)};\n` +
+        `${comparisonCode}`);
+}
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+function removeFieldByPath(obj, path) {
+    if (path.length === 0)
+        return;
+    const [head, ...rest] = path;
+    if (rest.length === 0) {
+        // Base case: delete the field
+        delete obj[head];
+        return;
+    }
+    // Recursive case: traverse into nested object
+    const child = obj[head];
+    if (child !== null && child !== undefined && typeof child === "object") {
+        removeFieldByPath(child, rest);
+    }
+}

package/dist/pipeline/compiler/index.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Config compiler — the heart of the new architecture.
+ *
+ * Converts task definitions from any source into a TaskGraph IR,
+ * then compiles the graph into Promptfoo YAML configuration.
+ *
+ * This module coexists with the existing `generate-configs.ts` path.
+ * Phase 7 will migrate callers to use the compiler exclusively.
+ *
+ * @see docs/exec-plans/architecture-overhaul/phase-2-config-compiler.md
+ */
+export { buildTaskGraph, detectCycle, type TaskGraphBuildOptions, type TaskGraphBuildResult, } from "./task-graph-builder.js";
+export { compileToPromptfoo, type CompilationResult, type CompiledPromptfooConfig, type PromptfooCompilerOptions, type PromptfooPrompt, type PromptfooProvider, type PromptfooTestCase, } from "./promptfoo-compiler.js";
+export { isAssertionCompatibleWithMode, isValidAssertionType, mapAssertions, type AssertionMapperOptions, type PromptfooAssertion, } from "./assertion-mapper.js";
+export { resolveTaskFixtures, type FixtureResolutionResult, type FixtureResolverOptions, } from "./fixture-resolver.js";
+export { createEnvelope, resolveVariables, type VariableResolutionResult, type VariableResolverOptions, } from "./variable-resolver.js";
+export { buildMCPAssertions, compileAgentHarnessTask, compileLiteracyTask, compileKnowledgeProbeTask, compileMCPTask, validateAgentHarnessTask, validateLiteracyTask, validateKnowledgeProbeTask, validateMCPTask, type AgentHarnessCompileOptions, type AgentHarnessCompileResult, type AgentHarnessValidationError, type LiteracyCompileOptions, type LiteracyCompileResult, type LiteracyValidationError, type KnowledgeProbeCompileOptions, type KnowledgeProbeCompileResult, type KnowledgeProbeMetadata, type KnowledgeProbeValidationError, type MCPAssertionContext, type MCPCompileOptions, type MCPCompileResult, type MCPValidationError, type PromptfooExtension, type SandboxConfigMeta, } from "./mode-handlers/index.js";
+export { createSandboxStrategy, DockerSandboxStrategy, GitWorktreeSandboxStrategy, selectSandboxStrategy, TempDirSandboxStrategy, type SandboxArtifacts, type SandboxInfo, type SandboxProvisionOptions, type SandboxSelectionResult, type SandboxStrategy, type SandboxType, } from "./sandbox/index.js";
+export { provisionFixtures, type FixtureRef, type FixtureTransform, type ProvisionedFixture, type ProvisioningOptions, type ProvisioningResult, } from "./sandbox/fixture-provisioner.js";
+export { loadModelsAndProviders, type AssembledProviders, type LiteracyVariantProviders, type ModelsAndProviders, } from "./provider-assembler.js";
+export { writeCompiledLiteracyConfigs, type WriteCompiledConfigOptions, } from "./compiler-to-yaml.js";
+export { compileLiteracyTasks, compareCompilerOutputs, type ComparisonDiscrepancy, type ComparisonResult, type LegacyEntry, type LiteracyBridgeOptions, type LiteracyBridgeResult, } from "./literacy-bridge.js";
+export { checkBudget, classifyToolCall, classifyToolCalls, collectTrace, computeCost, createRedactionConfig, DEFAULT_REDACTION_RULES, estimateRunCost, extractTraceSummary, LocalTraceStore, lookupPricing, mergeTraces, redactTrace, type ActualCost, type BudgetCheckResult, type BudgetConfig, type CostEstimate, type ModelPricing, type ProviderResponse, type RawToolCall, type RedactionConfig, type RedactionResult, type RedactionRule, type TraceCollectorOptions, type TraceStore, type TraceStoreResult, type TraceSummary, } from "./telemetry/index.js";
+export { registerSanityLiteracyPreset, sanityLiteracyPreset, } from "./presets/index.js";
+export { buildIgnoreFieldsWrapper, compareWithIgnoredFields, stripFields, } from "./ignore-fields.js";
+export { simpleHash } from "./hash.js";
+export { scoreTestGroup, type BridgedScoreResult } from "./scoring-bridge.js";
+export { ConfigNotFoundError, loadConfigFile, tryLoadConfigFile, } from "./config-loader.js";
+export type { ConfigLoadResult } from "./config-loader.js";

package/dist/pipeline/compiler/index.js

@@ -0,0 +1,45 @@
+/**
+ * Config compiler — the heart of the new architecture.
+ *
+ * Converts task definitions from any source into a TaskGraph IR,
+ * then compiles the graph into Promptfoo YAML configuration.
+ *
+ * This module coexists with the existing `generate-configs.ts` path.
+ * Phase 7 will migrate callers to use the compiler exclusively.
+ *
+ * @see docs/exec-plans/architecture-overhaul/phase-2-config-compiler.md
+ */
+// TaskGraph builder
+export { buildTaskGraph, detectCycle, } from "./task-graph-builder.js";
+// Promptfoo compiler
+export { compileToPromptfoo, } from "./promptfoo-compiler.js";
+// Assertion mapper
+export { isAssertionCompatibleWithMode, isValidAssertionType, mapAssertions, } from "./assertion-mapper.js";
+// Fixture resolver
+export { resolveTaskFixtures, } from "./fixture-resolver.js";
+// Variable resolver
+export { createEnvelope, resolveVariables, } from "./variable-resolver.js";
+// Mode handlers
+export { buildMCPAssertions, compileAgentHarnessTask, compileLiteracyTask, compileKnowledgeProbeTask, compileMCPTask, validateAgentHarnessTask, validateLiteracyTask, validateKnowledgeProbeTask, validateMCPTask, } from "./mode-handlers/index.js";
+// Sandbox infrastructure
+export { createSandboxStrategy, DockerSandboxStrategy, GitWorktreeSandboxStrategy, selectSandboxStrategy, TempDirSandboxStrategy, } from "./sandbox/index.js";
+// Fixture provisioning
+export { provisionFixtures, } from "./sandbox/fixture-provisioner.js";
+// Provider assembler — builds per-variant provider arrays from models config
+export { loadModelsAndProviders, } from "./provider-assembler.js";
+// Compiler-to-YAML — serializes compiled config to Promptfoo YAML files
+export { writeCompiledLiteracyConfigs, } from "./compiler-to-yaml.js";
+// Literacy bridge — LiteracyTaskDefinition → new compiler
+export { compileLiteracyTasks, compareCompilerOutputs, } from "./literacy-bridge.js";
+// Telemetry — observability & tracing
+export { checkBudget, classifyToolCall, classifyToolCalls, collectTrace, computeCost, createRedactionConfig, DEFAULT_REDACTION_RULES, estimateRunCost, extractTraceSummary, LocalTraceStore, lookupPricing, mergeTraces, redactTrace, } from "./telemetry/index.js";
+// Presets — bundled evaluation capabilities
+export { registerSanityLiteracyPreset, sanityLiteracyPreset, } from "./presets/index.js";
+// Field stripping for non-deterministic outputs
+export { buildIgnoreFieldsWrapper, compareWithIgnoredFields, stripFields, } from "./ignore-fields.js";
+// Hash utility
+export { simpleHash } from "./hash.js";
+// Scoring bridge — 4-tier engine integration
+export { scoreTestGroup } from "./scoring-bridge.js";
+// Unified config loader
+export { ConfigNotFoundError, loadConfigFile, tryLoadConfigFile, } from "./config-loader.js";

package/dist/pipeline/compiler/literacy-bridge.d.ts

@@ -0,0 +1,102 @@
+/**
+ * Literacy bridge — maps LiteracyTaskDefinition to the new compiler pipeline.
+ *
+ * This module bridges the task loading system (TaskSource →
+ * GeneralizedTaskDefinition) and the compiler (TaskGraph →
+ * PromptfooCompiler). It allows literacy tasks to run through
+ * the compiler.
+ *
+ * Pipeline: LiteracyTaskDefinition[] → TaskGraphBuilder → topological order →
+ *           LiteracyModeHandler (per task) → LiteracyBridgeResult
+ *
+ * Key behaviors:
+ * - Tasks without explicit mode get mode: "literacy" (backward compat)
+ * - LiteracyTaskDefinition fields map to compiler input fields
+ * - Rubric config is loaded from config/rubrics
+ * - Prompts from config/prompts are integrated
+ * - TaskGraphBuilder validates the DAG, deduplicates, and orders tasks
+ *
+ * @see docs/exec-plans/architecture-overhaul/phase-7-migrate-literacy.md
+ */
+import type { LiteracyTaskDefinition } from "../../_vendor/ailf-core/index.d.ts";
+import { type LiteracyCompileResult } from "./mode-handlers/literacy-handler.js";
+import { type LiteracyEvalSubMode } from "../normalize-mode.js";
+/** Options for compiling all literacy tasks via the new compiler */
+export interface LiteracyBridgeOptions {
+    /** Root directory of the eval package */
+    rootDir: string;
+    /** Eval mode to compile for */
+    evalMode?: LiteracyEvalSubMode;
+    /** Grader provider ID */
+    graderProvider?: string;
+    /** Model providers */
+    models?: {
+        id: string;
+        label: string;
+        config?: Record<string, unknown>;
+    }[];
+}
+/** Result of compiling all literacy tasks */
+export interface LiteracyBridgeResult {
+    /** Per-task compilation results */
+    tasks: {
+        taskId: string;
+        result: LiteracyCompileResult;
+    }[];
+    /** All warnings across tasks */
+    warnings: string[];
+    /** Total test cases generated */
+    totalTests: number;
+}
+/**
+ * Compile an array of LiteracyTaskDefinition through the literacy handler.
+ *
+ * This is the primary entry point for Phase 7 migration. It takes
+ * LiteracyTaskDefinition[] and routes them through the compiler pipeline:
+ *
+ *   LiteracyTaskDefinition[] → TaskGraphBuilder → topological order →
+ *   LiteracyModeHandler (per task) → LiteracyBridgeResult
+ *
+ * The TaskGraphBuilder provides:
+ * - Duplicate task ID detection (warns on collisions)
+ * - Status-based filtering (archived/paused/draft)
+ * - Dependency edge discovery and DAG cycle validation
+ * - Topological priority assignment (tasks with deps run in order)
+ *
+ * Note: The incoming tasks are typically pre-filtered by the pipeline
+ * step (area/tag/taskId filters + release auto-scope). The graph
+ * builder's own filtering is intentionally invoked WITHOUT a filter
+ * argument to avoid double-filtering — it still applies status-based
+ * rules (e.g., rejecting archived tasks that slipped through).
+ */
+export declare function compileLiteracyTasks(tasks: LiteracyTaskDefinition[], options: LiteracyBridgeOptions): LiteracyBridgeResult;
+/**
+ * Compare old-style expanded entries with new-style compiled entries.
+ *
+ * This is the parallel comparison gate (task 7b). For each task, it
+ * checks that the new compiler produces structurally equivalent output
+ * to the legacy expand-tasks path.
+ */
+export declare function compareCompilerOutputs(legacyEntries: LegacyEntry[], newResult: LiteracyBridgeResult): ComparisonResult;
+/** Minimal legacy entry shape (from expand-tasks) */
+export interface LegacyEntry {
+    description?: string;
+    vars?: Record<string, unknown>;
+    assert?: {
+        type: string;
+        value?: unknown;
+    }[];
+    prompts?: string[];
+}
+export interface ComparisonDiscrepancy {
+    taskId: string;
+    field: string;
+    legacy: unknown;
+    new_: unknown;
+    message: string;
+}
+export interface ComparisonResult {
+    passed: boolean;
+    discrepancies: ComparisonDiscrepancy[];
+    summary: string;
+}

package/dist/pipeline/compiler/literacy-bridge.js

@@ -0,0 +1,172 @@
+/**
+ * Literacy bridge — maps LiteracyTaskDefinition to the new compiler pipeline.
+ *
+ * This module bridges the task loading system (TaskSource →
+ * GeneralizedTaskDefinition) and the compiler (TaskGraph →
+ * PromptfooCompiler). It allows literacy tasks to run through
+ * the compiler.
+ *
+ * Pipeline: LiteracyTaskDefinition[] → TaskGraphBuilder → topological order →
+ *           LiteracyModeHandler (per task) → LiteracyBridgeResult
+ *
+ * Key behaviors:
+ * - Tasks without explicit mode get mode: "literacy" (backward compat)
+ * - LiteracyTaskDefinition fields map to compiler input fields
+ * - Rubric config is loaded from config/rubrics
+ * - Prompts from config/prompts are integrated
+ * - TaskGraphBuilder validates the DAG, deduplicates, and orders tasks
+ *
+ * @see docs/exec-plans/architecture-overhaul/phase-7-migrate-literacy.md
+ */
+import { compileLiteracyTask, } from "./mode-handlers/literacy-handler.js";
+import { tryLoadConfigFile } from "./config-loader.js";
+import { buildTaskGraph } from "./task-graph-builder.js";
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+/**
+ * Compile an array of LiteracyTaskDefinition through the literacy handler.
+ *
+ * This is the primary entry point for Phase 7 migration. It takes
+ * LiteracyTaskDefinition[] and routes them through the compiler pipeline:
+ *
+ *   LiteracyTaskDefinition[] → TaskGraphBuilder → topological order →
+ *   LiteracyModeHandler (per task) → LiteracyBridgeResult
+ *
+ * The TaskGraphBuilder provides:
+ * - Duplicate task ID detection (warns on collisions)
+ * - Status-based filtering (archived/paused/draft)
+ * - Dependency edge discovery and DAG cycle validation
+ * - Topological priority assignment (tasks with deps run in order)
+ *
+ * Note: The incoming tasks are typically pre-filtered by the pipeline
+ * step (area/tag/taskId filters + release auto-scope). The graph
+ * builder's own filtering is intentionally invoked WITHOUT a filter
+ * argument to avoid double-filtering — it still applies status-based
+ * rules (e.g., rejecting archived tasks that slipped through).
+ */
+export function compileLiteracyTasks(tasks, options) {
+    const rubricConfig = loadRubricConfig(options.rootDir);
+    const warnings = [];
+    const results = [];
+    let totalTests = 0;
+    // Build the task graph — validates DAG, deduplicates, assigns priority.
+    // No filter passed: tasks are already pre-filtered by the pipeline step.
+    const graphResult = buildTaskGraph({ tasks });
+    warnings.push(...graphResult.warnings);
+    if (graphResult.filteredOut.length > 0) {
+        warnings.push(`TaskGraphBuilder filtered out ${graphResult.filteredOut.length} task(s) ` +
+            `by status: ${graphResult.filteredOut.join(", ")}`);
+    }
+    // If all tasks were filtered out, return empty result
+    if (!graphResult.graph) {
+        return { tasks: [], warnings, totalTests: 0 };
+    }
+    // Extract tasks in topological order from the graph.
+    // The graph nodes are keyed by taskId; we sort by priority (lower = first)
+    // and look up the original LiteracyTaskDefinition for each node.
+    const taskMap = new Map(tasks.map((t) => [t.id, t]));
+    const orderedNodes = [...graphResult.graph.nodes.values()].sort((a, b) => a.priority - b.priority);
+    const compileOptions = {
+        graderProvider: options.graderProvider,
+        rootDir: options.rootDir,
+        evalMode: options.evalMode,
+        models: options.models,
+        rubricConfig,
+    };
+    for (const node of orderedNodes) {
+        const task = taskMap.get(node.taskId);
+        if (!task) {
+            warnings.push(`TaskGraphBuilder produced node "${node.taskId}" with no matching LiteracyTaskDefinition — skipped`);
+            continue;
+        }
+        const result = compileLiteracyTask(task, compileOptions);
+        results.push({ taskId: task.id, result });
+        warnings.push(...result.warnings);
+        totalTests += result.tests.length;
+    }
+    return { tasks: results, warnings, totalTests };
+}
+/**
+ * Compare old-style expanded entries with new-style compiled entries.
+ *
+ * This is the parallel comparison gate (task 7b). For each task, it
+ * checks that the new compiler produces structurally equivalent output
+ * to the legacy expand-tasks path.
+ */
+export function compareCompilerOutputs(legacyEntries, newResult) {
+    const discrepancies = [];
+    for (const { taskId, result } of newResult.tasks) {
+        // Find matching legacy entries by task description
+        const legacyForTask = legacyEntries.filter((e) => e.description?.includes(taskId) ||
+            e.description?.includes("(gold)") ||
+            e.description?.includes("(baseline)"));
+        // Check test count matches
+        const newTestCount = result.tests.length;
+        const legacyGold = legacyForTask.filter((e) => e.description?.includes("(gold)"));
+        const legacyBaseline = legacyForTask.filter((e) => e.description?.includes("(baseline)"));
+        const legacyCount = legacyGold.length + legacyBaseline.length;
+        if (legacyCount > 0 && newTestCount !== legacyCount) {
+            discrepancies.push({
+                taskId,
+                field: "testCount",
+                legacy: legacyCount,
+                new_: newTestCount,
+                message: `Test count mismatch: legacy=${legacyCount}, new=${newTestCount}`,
+            });
+        }
+        // Check assertion count on gold entries
+        for (const test of result.tests) {
+            if (test.description.includes("(gold)")) {
+                const assertCount = test.assert?.length ?? 0;
+                const matchingLegacy = legacyGold[0];
+                if (matchingLegacy?.assert) {
+                    const legacyAssertCount = matchingLegacy.assert.length;
+                    if (assertCount !== legacyAssertCount) {
+                        discrepancies.push({
+                            taskId,
+                            field: "assertionCount",
+                            legacy: legacyAssertCount,
+                            new_: assertCount,
+                            message: `Gold assertion count mismatch: legacy=${legacyAssertCount}, new=${assertCount}`,
+                        });
+                    }
+                }
+            }
+        }
+    }
+    return {
+        passed: discrepancies.length === 0,
+        discrepancies,
+        summary: discrepancies.length === 0
+            ? "All tasks produce structurally equivalent output"
+            : `${discrepancies.length} discrepancy(ies) found`,
+    };
+}
+// ---------------------------------------------------------------------------
+// Rubric config loading
+// ---------------------------------------------------------------------------
+function loadRubricConfig(rootDir) {
+    const result = tryLoadConfigFile("rubrics", rootDir);
+    if (!result)
+        return undefined;
+    try {
+        const parsed = result.data;
+        if (!parsed?.templates)
+            return undefined;
+        const templates = {};
+        for (const [key, val] of Object.entries(parsed.templates)) {
+            const t = val;
+            templates[key] = {
+                header: String(t.header ?? ""),
+                scale: t.scale ?? [],
+                dimension: t.dimension ? String(t.dimension) : undefined,
+                criteria_label: t.criteria_label ? String(t.criteria_label) : undefined,
+            };
+        }
+        return { templates };
+    }
+    catch {
+        return undefined;
+    }
+}