@sanity/ailf 0.1.0

package/dist/pipeline/validate.js

@@ -0,0 +1,406 @@
+/**
+ * pipeline/validate.ts
+ *
+ * Configuration validation for the evaluation pipeline. Checks that all YAML
+ * config files are consistent: every task has a canonical mapping, every
+ * mapping has a reference solution file, required files exist, etc.
+ *
+ * All individual validators are exported so they can be tested independently.
+ */
+import fs from "fs";
+import path from "path";
+import { load } from "js-yaml";
+import { resolveMappings } from "./resolve-mappings.js";
+import { FeatureRegistrySchema, formatZodErrors, RubricConfigSchema, TaskFileSchema, ThresholdConfigSchema, } from "./schemas.js";
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+/**
+ * Run all validation checks and return a combined result.
+ * `valid` is true only if there are zero error-severity issues.
+ */
+export function validateConfiguration(rootDir) {
+    const resolvedDir = path.resolve(rootDir);
+    const issues = [
+        ...validateModelsYaml(resolvedDir),
+        ...validateRubricsYaml(resolvedDir),
+        ...validateFeaturesYaml(resolvedDir),
+        ...validateThresholdsYaml(resolvedDir),
+        ...validateTaskFiles(resolvedDir),
+        ...validateReferenceSolutions(resolvedDir),
+        ...validateContexts(resolvedDir),
+    ];
+    const valid = issues.every((issue) => issue.severity !== "error");
+    return { issues, valid };
+}
+/**
+ * Check that canonical context files exist. These are the per-task
+ * gold-retrieval contexts actually referenced by task definitions.
+ *
+ * Contexts are generated by fetch-docs and may not exist yet —
+ * returns warnings, not errors.
+ */
+export function validateContexts(rootDir) {
+    const source = "validateContexts";
+    const issues = [];
+    const canonicalDir = path.join(rootDir, "contexts", "canonical");
+    if (!fs.existsSync(canonicalDir)) {
+        issues.push(warning(source, "contexts/canonical/ directory not found — run 'pnpm fetch-docs' to generate", canonicalDir));
+        return issues;
+    }
+    const mappings = resolveMappings(rootDir);
+    for (const [, areaConfig] of Object.entries(mappings.feature_areas)) {
+        if (!areaConfig?.tasks)
+            continue;
+        for (const task of areaConfig.tasks) {
+            if (!task.id)
+                continue;
+            const contextFile = path.join(canonicalDir, `${task.id}.md`);
+            if (!fs.existsSync(contextFile)) {
+                issues.push(warning(source, `Missing canonical context for task '${task.id}' — run 'pnpm fetch-docs' to generate`, contextFile));
+            }
+        }
+    }
+    return issues;
+}
+/**
+ * Check that config/features.yaml exists, parses, and conforms to the Zod schema.
+ * Also cross-references covered features against actual task files for consistency.
+ *
+ * Returns warnings (not errors) if the file is missing — the feature registry
+ * is optional and doesn't block evaluation.
+ */
+export function validateFeaturesYaml(rootDir) {
+    const source = "validateFeaturesYaml";
+    const issues = [];
+    const filePath = path.join(rootDir, "config", "features.yaml");
+    if (!fs.existsSync(filePath)) {
+        // Feature registry is optional — warn, don't error
+        issues.push(warning(source, "config/features.yaml not found — coverage audit unavailable", filePath));
+        return issues;
+    }
+    const result = parseYamlFile(filePath, source);
+    if (!result.ok)
+        return [result.issue];
+    const zodResult = FeatureRegistrySchema.safeParse(result.data);
+    if (!zodResult.success) {
+        const lines = formatZodErrors(zodResult.error);
+        for (const line of lines) {
+            issues.push(error(source, `config/features.yaml: ${line.trim()}`, filePath));
+        }
+        return issues;
+    }
+    // Cross-reference: warn if a "covered" feature has no matching task file
+    const tasksDir = path.join(rootDir, "tasks");
+    if (fs.existsSync(tasksDir)) {
+        const taskFiles = new Set(fs
+            .readdirSync(tasksDir)
+            .filter((f) => f.endsWith(".yaml") || f.endsWith(".yml"))
+            .map((f) => f.replace(/\.(yaml|yml)$/, "")));
+        for (const feature of zodResult.data.features) {
+            if (feature.status === "covered" && feature.area) {
+                if (!taskFiles.has(feature.area)) {
+                    issues.push(warning(source, `Feature '${feature.id}' is status: covered with area: '${feature.area}', but tasks/${feature.area}.yaml does not exist`, filePath));
+                }
+            }
+            // Warn if an "uncovered" feature has a matching task file
+            if (feature.status === "uncovered" && feature.area) {
+                if (taskFiles.has(feature.area)) {
+                    issues.push(warning(source, `Feature '${feature.id}' is status: uncovered but tasks/${feature.area}.yaml exists — consider updating status to 'covered'`, filePath));
+                }
+            }
+        }
+        // Check for duplicate feature IDs
+        const ids = new Set();
+        for (const feature of zodResult.data.features) {
+            if (ids.has(feature.id)) {
+                issues.push(error(source, `Duplicate feature id '${feature.id}' in config/features.yaml`, filePath));
+            }
+            ids.add(feature.id);
+        }
+    }
+    return issues;
+}
+/**
+ * Check that config/models.yaml exists, parses, has at least one model with an id
+ * and label, and has a grader defined.
+ */
+export function validateModelsYaml(rootDir) {
+    const source = "validateModelsYaml";
+    const issues = [];
+    const filePath = path.join(rootDir, "config", "models.yaml");
+    const result = parseYamlFile(filePath, source);
+    if (!result.ok)
+        return [result.issue];
+    const { data } = result;
+    if (!data || typeof data !== "object") {
+        issues.push(error(source, "config/models.yaml did not parse to an object", filePath));
+        return issues;
+    }
+    // Check models array
+    if (!Array.isArray(data.models)) {
+        issues.push(error(source, "config/models.yaml is missing a 'models' array", filePath));
+    }
+    else if (data.models.length === 0) {
+        issues.push(error(source, "config/models.yaml has an empty 'models' array", filePath));
+    }
+    else {
+        for (const [i, model] of data.models.entries()) {
+            if (!model.id) {
+                issues.push(error(source, `models[${i}] is missing 'id'`, filePath));
+            }
+            if (!model.label) {
+                issues.push(error(source, `models[${i}] is missing 'label'`, filePath));
+            }
+        }
+    }
+    // Check grader
+    if (!data.grader) {
+        issues.push(error(source, "config/models.yaml is missing a 'grader' section", filePath));
+    }
+    else if (!data.grader.id) {
+        issues.push(error(source, "config/models.yaml grader is missing 'id'", filePath));
+    }
+    return issues;
+}
+// ---------------------------------------------------------------------------
+// Validators
+// ---------------------------------------------------------------------------
+/**
+ * Check that reference solution files exist on disk for every task
+ * that declares a reference_solution path. Reads from inline task
+ * definitions via resolveMappings.
+ *
+ * NOTE: When tasks come from the Content Lake, reference solutions also
+ * live there (as ailf.referenceSolution documents). This validator only
+ * applies to YAML-based tasks with local file paths.
+ */
+export function validateReferenceSolutions(rootDir) {
+    const source = "validateReferenceSolutions";
+    const issues = [];
+    const canonicalDir = path.join(rootDir, "canonical");
+    const mappings = resolveMappings(rootDir);
+    for (const [area, areaConfig] of Object.entries(mappings.feature_areas)) {
+        if (!areaConfig?.tasks)
+            continue;
+        for (const task of areaConfig.tasks) {
+            const taskLabel = `${area}/${task.id}`;
+            if (!task.reference_solution) {
+                issues.push(error(source, `${taskLabel} is missing 'reference_solution'`));
+                continue;
+            }
+            const solutionPath = path.join(canonicalDir, task.reference_solution);
+            if (!fs.existsSync(solutionPath)) {
+                issues.push(error(source, `${taskLabel} reference_solution not found: ${task.reference_solution}`, solutionPath));
+            }
+        }
+    }
+    return issues;
+}
+/**
+ * Check that config/rubrics.yaml exists, parses, and conforms to the Zod schema.
+ * Returns the set of valid template keys for cross-referencing by task
+ * validation.
+ */
+export function validateRubricsYaml(rootDir) {
+    const source = "validateRubricsYaml";
+    const issues = [];
+    const filePath = path.join(rootDir, "config", "rubrics.yaml");
+    const result = parseYamlFile(filePath, source);
+    if (!result.ok)
+        return [result.issue];
+    const zodResult = RubricConfigSchema.safeParse(result.data);
+    if (!zodResult.success) {
+        const lines = formatZodErrors(zodResult.error);
+        for (const line of lines) {
+            issues.push(error(source, `config/rubrics.yaml: ${line.trim()}`, filePath));
+        }
+    }
+    return issues;
+}
+/**
+ * Check that tasks/*.yaml files exist, parse, and conform to the Zod schema.
+ * Validates both the new single-definition format (with `id`) and the legacy
+ * paired format. Uses `TaskFileSchema` from schemas.ts for structural
+ * validation, plus cross-entry checks (duplicate IDs, docs path consistency).
+ */
+export function validateTaskFiles(rootDir) {
+    const source = "validateTaskFiles";
+    const issues = [];
+    const tasksDir = path.join(rootDir, "tasks");
+    if (!fs.existsSync(tasksDir)) {
+        issues.push(warning(source, "tasks/ directory not found (using Content Lake tasks?)", tasksDir));
+        return issues;
+    }
+    const yamlFiles = fs
+        .readdirSync(tasksDir)
+        .filter((f) => (f.endsWith(".yaml") || f.endsWith(".yml")) && !f.startsWith("."));
+    if (yamlFiles.length === 0) {
+        issues.push(warning(source, "No task YAML files found in tasks/ (using Content Lake tasks?)", tasksDir));
+        return issues;
+    }
+    const allIds = new Map(); // id → source file
+    const templateKeys = loadTemplateKeys(rootDir);
+    for (const file of yamlFiles) {
+        const filePath = path.join(tasksDir, file);
+        // Step 1: Parse YAML
+        const result = parseYamlFile(filePath, source);
+        if (!result.ok) {
+            issues.push(result.issue);
+            continue;
+        }
+        const { data } = result;
+        if (!Array.isArray(data)) {
+            issues.push(error(source, `${file} did not parse to an array of tasks`, filePath));
+            continue;
+        }
+        // Step 2: Validate each entry with Zod schema
+        const zodResult = TaskFileSchema.safeParse(data);
+        if (!zodResult.success) {
+            const lines = formatZodErrors(zodResult.error);
+            for (const line of lines) {
+                issues.push(error(source, `${file}: ${line.trim()}`, filePath));
+            }
+            continue;
+        }
+        // Step 3: Cross-entry validation (duplicate IDs, docs path consistency)
+        for (const entry of zodResult.data) {
+            if ("id" in entry && typeof entry.id === "string") {
+                // Check for duplicate IDs across all files
+                if (allIds.has(entry.id)) {
+                    issues.push(error(source, `${file}: duplicate id '${entry.id}' (also in ${allIds.get(entry.id)})`, filePath));
+                }
+                else {
+                    allIds.set(entry.id, file);
+                }
+                // Check docs path matches task id
+                const vars = entry.vars;
+                if (vars.docs && typeof vars.docs === "string") {
+                    const expectedPath = `file://contexts/canonical/${entry.id}.md`;
+                    if (vars.docs !== expectedPath) {
+                        issues.push(warning(source, `${file}: id is '${entry.id}' but docs path is '${vars.docs}' (expected '${expectedPath}')`, filePath));
+                    }
+                }
+                // Check that llm-rubric template references exist in config/rubrics.yaml
+                const asserts = entry.assert;
+                if (Array.isArray(asserts) && templateKeys.size > 0) {
+                    for (const a of asserts) {
+                        const assertion = a;
+                        if (assertion.type === "llm-rubric" &&
+                            typeof assertion.template === "string") {
+                            if (!templateKeys.has(assertion.template)) {
+                                issues.push(error(source, `${file}: task '${entry.id}' references unknown rubric template '${assertion.template}' (available: ${[...templateKeys].join(", ")})`, filePath));
+                            }
+                        }
+                    }
+                }
+            }
+        }
+    }
+    return issues;
+}
+/**
+ * Check that config/thresholds.yaml exists, parses, and conforms to the Zod schema.
+ *
+ * Returns warnings (not errors) if the file is missing — thresholds are
+ * optional and don't block evaluation. They only activate when
+ * `--readiness` or severity-aware sink routing is used.
+ */
+export function validateThresholdsYaml(rootDir) {
+    const source = "validateThresholdsYaml";
+    const issues = [];
+    const filePath = path.join(rootDir, "config", "thresholds.yaml");
+    if (!fs.existsSync(filePath)) {
+        // Thresholds are optional — warn, don't error
+        issues.push(warning(source, "config/thresholds.yaml not found — readiness gates and threshold alerts unavailable", filePath));
+        return issues;
+    }
+    const result = parseYamlFile(filePath, source);
+    if (!result.ok)
+        return [result.issue];
+    const zodResult = ThresholdConfigSchema.safeParse(result.data);
+    if (!zodResult.success) {
+        const lines = formatZodErrors(zodResult.error);
+        for (const line of lines) {
+            issues.push(error(source, `config/thresholds.yaml: ${line.trim()}`, filePath));
+        }
+        return issues;
+    }
+    // Cross-reference: warn if an area override references an area with no task file
+    if (zodResult.data.areas) {
+        const tasksDir = path.join(rootDir, "tasks");
+        if (fs.existsSync(tasksDir)) {
+            const taskFiles = new Set(fs
+                .readdirSync(tasksDir)
+                .filter((f) => f.endsWith(".yaml") || f.endsWith(".yml"))
+                .map((f) => f.replace(/\.(yaml|yml)$/, "")));
+            for (const areaName of Object.keys(zodResult.data.areas)) {
+                if (!taskFiles.has(areaName)) {
+                    issues.push(warning(source, `config/thresholds.yaml: area override '${areaName}' has no matching tasks/${areaName}.yaml`, filePath));
+                }
+            }
+        }
+    }
+    return issues;
+}
+function error(source, message, filePath) {
+    return {
+        message,
+        severity: "error",
+        source,
+        ...(filePath && { path: filePath }),
+    };
+}
+/**
+ * Load the set of valid rubric template keys from config/rubrics.yaml.
+ * Returns an empty set if the file is missing or invalid.
+ */
+function loadTemplateKeys(rootDir) {
+    const filePath = path.join(rootDir, "config", "rubrics.yaml");
+    if (!fs.existsSync(filePath))
+        return new Set();
+    try {
+        const raw = fs.readFileSync(filePath, "utf-8");
+        const parsed = load(raw);
+        const templates = parsed?.templates;
+        if (templates && typeof templates === "object") {
+            return new Set(Object.keys(templates));
+        }
+    }
+    catch {
+        // Ignore — structural errors are caught by validateRubricsYaml
+    }
+    return new Set();
+}
+/** Safely parse a YAML file, returning the parsed value or a validation issue. */
+function parseYamlFile(filePath, source) {
+    if (!fs.existsSync(filePath)) {
+        return {
+            issue: error(source, `File not found: ${filePath}`, filePath),
+            ok: false,
+        };
+    }
+    try {
+        const raw = fs.readFileSync(filePath, "utf-8");
+        const data = load(raw);
+        return { data, ok: true };
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : "Unknown YAML parse error";
+        return {
+            issue: error(source, `Failed to parse YAML: ${message}`, filePath),
+            ok: false,
+        };
+    }
+}
+// ---------------------------------------------------------------------------
+// Main entry point
+// ---------------------------------------------------------------------------
+function warning(source, message, filePath) {
+    return {
+        message,
+        severity: "warning",
+        source,
+        ...(filePath && { path: filePath }),
+    };
+}

package/dist/pipeline/webhook-server.d.ts

@@ -0,0 +1,37 @@
+/**
+ * webhook-server.ts
+ *
+ * Local development server for testing the webhook handler.
+ *
+ * Starts an HTTP server that receives Sanity webhook payloads, processes
+ * them through the WebhookHandler, and logs results. Useful for local
+ * development and testing the full event-driven trigger flow.
+ *
+ * Migrated from lib/webhook-server.ts — accepts rootDir and port as parameters.
+ *
+ * @see docs/design-docs/report-store/visibility-workflows.md
+ */
+import { createServer } from "http";
+import { WebhookHandler } from "../webhook/handler.js";
+export interface WebhookServerOptions {
+    /** Root directory of the eval package */
+    rootDir: string;
+    /** Server port (default: 3333) */
+    port?: number;
+    /** GitHub token for dispatching workflow runs (omit for dry-run) */
+    githubToken?: string;
+    /** Daily dispatch budget */
+    dailyBudget?: number;
+    /** Debounce interval in ms */
+    debounceMs?: number;
+}
+/**
+ * Start the webhook development server.
+ *
+ * This function blocks and keeps the process alive.
+ * Returns the HTTP server instance for graceful shutdown in tests.
+ */
+export declare function startWebhookServer(options: WebhookServerOptions): {
+    server: ReturnType<typeof createServer>;
+    handler: WebhookHandler;
+};

package/dist/pipeline/webhook-server.js

@@ -0,0 +1,133 @@
+/**
+ * webhook-server.ts
+ *
+ * Local development server for testing the webhook handler.
+ *
+ * Starts an HTTP server that receives Sanity webhook payloads, processes
+ * them through the WebhookHandler, and logs results. Useful for local
+ * development and testing the full event-driven trigger flow.
+ *
+ * Migrated from lib/webhook-server.ts — accepts rootDir and port as parameters.
+ *
+ * @see docs/design-docs/report-store/visibility-workflows.md
+ */
+import { createServer } from "http";
+import { allTrackedSlugs, buildReverseMapping } from "./reverse-mapping.js";
+import { WebhookHandler } from "../webhook/handler.js";
+// ---------------------------------------------------------------------------
+// Server
+// ---------------------------------------------------------------------------
+/**
+ * Start the webhook development server.
+ *
+ * This function blocks and keeps the process alive.
+ * Returns the HTTP server instance for graceful shutdown in tests.
+ */
+export function startWebhookServer(options) {
+    const { rootDir, port = 3333, githubToken = "", dailyBudget = 20, debounceMs = 10000, } = options;
+    const DRY_RUN = !githubToken;
+    const handler = new WebhookHandler({
+        dailyBudget,
+        debounceMs,
+        githubToken,
+        rootDir,
+    });
+    const server = createServer((req, res) => {
+        void handleRequest(req, res, { handler, rootDir, port, DRY_RUN });
+    });
+    server.listen(port, () => {
+        const reverseMapping = buildReverseMapping(rootDir);
+        const slugCount = allTrackedSlugs(reverseMapping).length;
+        console.log();
+        console.log("=== AILF Webhook Server ===");
+        console.log();
+        console.log(`  Port:           ${port}`);
+        console.log(`  Mode:           ${DRY_RUN ? "DRY RUN (set GITHUB_TOKEN to dispatch)" : "LIVE"}`);
+        console.log(`  Tracked slugs:  ${slugCount}`);
+        console.log(`  Debounce:       ${handler.diagnostics().pendingSlugs}`);
+        console.log();
+        console.log("  Endpoints:");
+        console.log(`    POST http://localhost:${port}/webhook   — handle webhook`);
+        console.log(`    GET  http://localhost:${port}/health    — diagnostics`);
+        console.log(`    GET  http://localhost:${port}/mappings  — slug → area map`);
+        console.log();
+    });
+    // Graceful shutdown
+    process.on("SIGINT", () => {
+        console.log("\n  Shutting down — flushing debounce window...");
+        void handler.shutdown().then(() => {
+            server.close();
+            process.exit(0);
+        });
+    });
+    return { server, handler };
+}
+// ---------------------------------------------------------------------------
+// Request handler
+// ---------------------------------------------------------------------------
+async function handleRequest(req, res, ctx) {
+    const url = new URL(req.url ?? "/", `http://localhost:${ctx.port}`);
+    // CORS headers for local dev
+    res.setHeader("Access-Control-Allow-Origin", "*");
+    res.setHeader("Access-Control-Allow-Methods", "GET, POST, OPTIONS");
+    res.setHeader("Access-Control-Allow-Headers", "Content-Type");
+    if (req.method === "OPTIONS") {
+        res.writeHead(200);
+        res.end();
+        return;
+    }
+    // Health check
+    if (url.pathname === "/health" && req.method === "GET") {
+        const diagnostics = ctx.handler.diagnostics();
+        res.writeHead(200, { "Content-Type": "application/json" });
+        res.end(JSON.stringify({ dryRun: ctx.DRY_RUN, ...diagnostics }, null, 2));
+        return;
+    }
+    // Mappings
+    if (url.pathname === "/mappings" && req.method === "GET") {
+        const reverseMapping = buildReverseMapping(ctx.rootDir);
+        const slugs = allTrackedSlugs(reverseMapping);
+        const mappings = Object.fromEntries(slugs.map((slug) => [slug, reverseMapping.get(slug)]));
+        res.writeHead(200, { "Content-Type": "application/json" });
+        res.end(JSON.stringify({ mappings, slugCount: slugs.length }, null, 2));
+        return;
+    }
+    // Webhook handler
+    if (url.pathname === "/webhook" && req.method === "POST") {
+        const body = await readBody(req);
+        let payload;
+        try {
+            payload = JSON.parse(body);
+        }
+        catch {
+            res.writeHead(400, { "Content-Type": "application/json" });
+            res.end(JSON.stringify({ error: "Invalid JSON" }));
+            return;
+        }
+        if (ctx.DRY_RUN) {
+            console.log("\n  🔶 DRY RUN — would dispatch (no GITHUB_TOKEN set)");
+        }
+        const result = ctx.handler.handle(payload);
+        console.log(`  → ${result.status}:`, JSON.stringify(result));
+        res.writeHead(200, { "Content-Type": "application/json" });
+        res.end(JSON.stringify(result, null, 2));
+        return;
+    }
+    // 404
+    res.writeHead(404, { "Content-Type": "application/json" });
+    res.end(JSON.stringify({
+        endpoints: ["POST /webhook", "GET /health", "GET /mappings"],
+        error: "Not found",
+    }));
+}
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+function readBody(req) {
+    return new Promise((resolve, reject) => {
+        const chunks = [];
+        req.on("data", (chunk) => chunks.push(chunk));
+        req.on("end", () => resolve(Buffer.concat(chunks).toString()));
+        req.on("error", reject);
+    });
+}

package/dist/report-store.d.ts

@@ -0,0 +1,84 @@
+/**
+ * report-store.ts
+ *
+ * Persistent report store backed by the Sanity Content Lake.
+ * Provides write, read, and lineage-query operations for evaluation reports.
+ *
+ * The Sanity Content Lake is the system of record (P1: immutable events).
+ * Reports are stored as typed documents in the shared dataset, enabling
+ * GROQ queries, Studio dashboards, and webhook-driven notifications.
+ *
+ * If Sanity is unreachable, the store logs a warning and returns gracefully
+ * (P5: local-first — the pipeline never fails because of a store write).
+ *
+ * @see docs/design-docs/report-store/architecture.md
+ * @see docs/design-docs/report-store/domain-model.md
+ */
+import type { SanityClient } from "@sanity/client";
+import type { ComparisonReport, ISOTimestamp, LineageQuery, Report, ReportId, ReportProvenance, ScoreSummary } from "./pipeline/types.js";
+export interface ReportStoreOptions {
+    /** Override the Sanity client (for testing) */
+    client?: SanityClient;
+    /** Sanity dataset name */
+    dataset?: string;
+    /** Sanity project ID */
+    projectId?: string;
+    /** Sanity API token (required for writes) */
+    token?: string;
+}
+export declare class ReportStore {
+    private readonly client;
+    constructor(options?: ReportStoreOptions);
+    /**
+     * Auto-compare: find the most recent comparable report and compute
+     * a ComparisonReport using the existing compare() primitive.
+     *
+     * @returns The comparison report, or null if no baseline found or on error
+     */
+    autoCompare(currentSummary: ScoreSummary, provenance: ReportProvenance, completedAt: ISOTimestamp): Promise<ComparisonReport | null>;
+    /**
+     * Find a report by its evaluation fingerprint (cross-environment cache lookup).
+     *
+     * Returns the most recent non-debug report whose provenance contains a
+     * matching `evalFingerprint`. Used by the pipeline to skip the expensive
+     * eval step when identical inputs have already been evaluated.
+     *
+     * @returns The cached report, or null if no match or on error
+     * @see docs/design-docs/content-lake-eval-caching.md
+     */
+    findByFingerprint(fingerprint: string): Promise<null | Report>;
+    /**
+     * Find the most recent comparable report for auto-comparison.
+     *
+     * Uses GROQ to match on key provenance dimensions (mode, source name)
+     * and returns the most recent report before the given timestamp.
+     *
+     * "Comparable" means: same evaluation mode + same source name.
+     * More granular matching (areas, models) can be added as needed.
+     *
+     * @see docs/design-docs/report-store/architecture.md — Auto-comparison
+     */
+    findComparableBaseline(query: LineageQuery): Promise<null | Report>;
+    /**
+     * Read a report by its ID.
+     */
+    read(id: ReportId): Promise<null | Report>;
+    /**
+     * Write a report to the Sanity Content Lake.
+     *
+     * Creates an immutable `ailf.report` document. The document _id is
+     * prefixed with `report-` for easy GROQ filtering.
+     *
+     * @returns The report ID on success, null on failure (logged, not thrown)
+     */
+    write(report: Report): Promise<null | ReportId>;
+}
+/**
+ * Generate a UUID v7 (time-sortable) for report identification.
+ *
+ * UUID v7 encodes the current timestamp in the high bits, making reports
+ * naturally sort by creation time in both GROQ and string comparisons.
+ *
+ * Uses crypto.randomUUID() as a base and overwrites the timestamp portion.
+ */
+export declare function generateReportId(): ReportId;