@sanity/ailf 1.0.0 → 2.0.0

package/dist/_vendor/ailf-core/types/plugin-registry.js

@@ -1,12 +1,12 @@
 /**
  * Plugin registry — typed extension points for AILF evaluation capabilities.
  *
- * Twelve extension points: evaluation modes, providers, assertions,
- * rubric templates, fixture resolvers, report sinks, dashboard renderers,
- * prompt templates, scoring profiles, doc fetcher factory, source defs,
- * and feature defs.
- *
- * Presets bundle multiple extensions into a single installable unit.
+ * Three-tier architecture:
+ * - **Mode bases** define evaluation methodology (rubrics, scoring, prompts)
+ * - **Domain presets** target a mode base and add domain config (sources,
+ *   features, doc fetcher)
+ * - **Framework assertions** are generic evaluation primitives available to
+ *   all modes
  *
  * @see docs/design-docs/architecture-overhaul/extensibility-plugins.md
  */
@@ -19,6 +19,7 @@ export class InMemoryPluginRegistry {
     rubricTemplates_ = new Map();
     fixtureResolvers_ = new Map();
     reportSinks_ = new Map();
+    modeBases_ = new Map();
     presets_ = new Map();
     promptTemplates_ = {};
     scoringProfiles_ = {};
@@ -26,19 +27,56 @@ export class InMemoryPluginRegistry {
     sourceDefs_ = [];
     featureDefs_;
     registerPreset(preset) {
+        // Skip archived presets entirely
+        if (preset.status === "archived")
+            return;
+        // Store draft/paused presets in the map (for later activation via
+        // --preset flag) but skip all side-effect registrations. This prevents
+        // a draft preset from silently overwriting the doc fetcher, merging
+        // scoring profiles, etc.
         this.presets_.set(preset.name, preset);
-        if (preset.modes) {
-            for (const mode of preset.modes)
-                this.registerMode(mode);
+        if (preset.status === "draft" || preset.status === "paused")
+            return;
+        // Resolve mode base defaults
+        const base = this.modeBases_.get(preset.mode);
+        if (!base) {
+            throw new Error(`Preset "${preset.name}" targets mode "${preset.mode}" ` +
+                `but no mode base is registered for it. ` +
+                `Available mode bases: ${[...this.modeBases_.keys()].join(", ") || "(none)"}`);
+        }
+        // Mode is already registered by registerModeBase() — no need to re-register.
+        // Merge rubric templates: base defaults + preset overrides (by ID)
+        const baseRubrics = new Map((base.rubricTemplates ?? []).map((r) => [r.id, r]));
+        for (const r of preset.rubricTemplates ?? []) {
+            baseRubrics.set(r.id, r);
+        }
+        for (const r of baseRubrics.values()) {
+            this.registerRubricTemplate(r);
+        }
+        // Merge scoring profiles: base defaults + preset overrides (by name)
+        const profiles = {
+            ...base.scoringProfiles,
+            ...preset.scoringProfiles,
+        };
+        if (Object.keys(profiles).length > 0) {
+            this.registerScoringProfiles(profiles);
         }
+        // Merge prompt templates: base defaults + preset overrides (by name)
+        const prompts = {
+            ...base.promptTemplates,
+            ...preset.promptTemplates,
+        };
+        if (Object.keys(prompts).length > 0) {
+            this.registerPromptTemplates(prompts);
+        }
+        // Merge assertions: base + preset (preset overrides by type)
+        for (const a of base.assertions ?? [])
+            this.registerAssertion(a);
         if (preset.assertions) {
             for (const a of preset.assertions)
                 this.registerAssertion(a);
         }
-        if (preset.rubricTemplates) {
-            for (const t of preset.rubricTemplates)
-                this.registerRubricTemplate(t);
-        }
+        // Register domain-specific fields
         if (preset.fixtureResolvers) {
             for (const r of preset.fixtureResolvers)
                 this.registerFixtureResolver(r);
@@ -47,12 +85,6 @@ export class InMemoryPluginRegistry {
             for (const s of preset.reportSinks)
                 this.registerReportSink(s);
         }
-        if (preset.promptTemplates) {
-            this.registerPromptTemplates(preset.promptTemplates);
-        }
-        if (preset.scoringProfiles) {
-            this.registerScoringProfiles(preset.scoringProfiles);
-        }
         if (preset.docFetcher) {
             this.registerDocFetcherFactory(preset.docFetcher);
         }
@@ -124,9 +156,30 @@ export class InMemoryPluginRegistry {
         return this.sourceDefs_;
     }
     registerFeatureDefs(features) {
-        this.featureDefs_ = features;
+        if (!this.featureDefs_) {
+            this.featureDefs_ = features;
+            return;
+        }
+        // Merge by feature ID: new features override existing on ID collision,
+        // existing features not in new set are preserved.
+        const merged = new Map(this.featureDefs_.features.map((f) => [f.id, f]));
+        for (const f of features.features) {
+            merged.set(f.id, f);
+        }
+        this.featureDefs_ = { features: [...merged.values()] };
     }
     getFeatureDefs() {
         return this.featureDefs_;
     }
+    registerModeBase(base) {
+        this.modeBases_.set(base.mode.id, base);
+        // Also register the mode itself so getMode() works
+        this.registerMode(base.mode);
+    }
+    getModeBase(modeId) {
+        return this.modeBases_.get(modeId);
+    }
+    getModeBases() {
+        return [...this.modeBases_.values()];
+    }
 }

package/dist/adapters/config-sources/file-config-adapter.js

@@ -121,5 +121,6 @@ function mapEvalConfigToResolvedConfig(config, rootDir) {
         concurrency: config.concurrency,
         remote: false,
         apiUrl: "https://ailf-api.sanity.build",
+        presets: config.presets,
     };
 }

package/dist/adapters/config-sources/ts-config-loader.js

@@ -13,21 +13,29 @@
  * @see docs/design-docs/architecture-overhaul/typescript-configuration.md
  */
 import { existsSync } from "fs";
+import { pathToFileURL } from "node:url";
 import { createJiti } from "jiti";
 // ---------------------------------------------------------------------------
-// Singleton jiti instance — reused across all loads for caching
+// jiti instance factory — resolves imports relative to the loaded file
 // ---------------------------------------------------------------------------
-let _jiti = null;
-function getJiti() {
-    if (!_jiti) {
-        _jiti = createJiti(import.meta.url, {
-            // Interop: handle both `export default` and `module.exports`
-            interopDefault: true,
-            // Don't require file extensions in imports
-            requireCache: true,
-        });
-    }
-    return _jiti;
+/**
+ * Create a jiti instance that resolves bare-specifier imports relative to
+ * the given file path, not relative to this loader module.
+ *
+ * This is critical for pnpm workspaces: a task file at `.ailf/tasks/foo.task.ts`
+ * importing `@sanity/ailf` must resolve through the dependency graph
+ * visible from the task file's directory, not from deep inside packages/eval/.
+ *
+ * We pass a `file://` URL (not a bare path) so jiti uses ESM resolution,
+ * which matches the `"import"` condition in package.json exports maps.
+ */
+function createJitiForFile(filePath) {
+    return createJiti(pathToFileURL(filePath).href, {
+        // Interop: handle both `export default` and `module.exports`
+        interopDefault: true,
+        // Don't require file extensions in imports
+        requireCache: true,
+    });
 }
 /**
  * Load a TypeScript or JavaScript config file and return its default export.
@@ -43,7 +51,7 @@ export async function loadTsConfig(filePath) {
         return { ok: false, error: `File not found: ${filePath}`, path: filePath };
     }
     try {
-        const jiti = getJiti();
+        const jiti = createJitiForFile(filePath);
         const mod = await jiti.import(filePath);
         const value = extractDefault(mod);
         if (value === undefined || value === null) {

package/dist/adapters/task-sources/content-lake-task-source.js

@@ -20,8 +20,8 @@
  * mapping to LiteracyTaskDefinition.
  *
  * Key projections:
- * - featureArea reference → dereferenced areaId string
- * - canonicalDocs[] → dereferenced article slugs with reason
+ * - area reference → dereferenced areaId string
+ * - contextDocs[] → dereferenced article slugs with reason
  * - referenceSolution → title (for identification, not full content)
  *
  * Filter parameters:
@@ -30,7 +30,7 @@
  */
 const TASKS_QUERY = /* groq */ `
 *[_type == "ailf.task"
-  && (!defined($areas) || featureArea->areaId.current in $areas)
+  && (!defined($areas) || area->areaId.current in $areas)
   && (!defined($taskIds) || id.current in $taskIds)
   && (
     // Status-based filtering (unified — replaces execution.enabled)
@@ -41,13 +41,13 @@ const TASKS_QUERY = /* groq */ `
     || (defined($taskIds) && status != "archived")
   )
   && (!defined($tags) || count((tags)[@ in $tags]) > 0)
-] | order(featureArea->areaId.current asc, id.current asc) {
+] | order(area->areaId.current asc, id.current asc) {
   "taskId": id.current,
-  description,
-  "featureAreaId": featureArea->areaId.current,
-  taskPrompt,
+  title,
+  "areaId": area->areaId.current,
+  promptText,
   docCoverage,
-  "canonicalDocs": canonicalDocs[] {
+  "contextDocs": contextDocs[] {
     refType,
     "slug": doc->slug.current,
     "docRefId": doc->_id,
@@ -57,7 +57,7 @@ const TASKS_QUERY = /* groq */ `
     perspective,
     reason
   },
-  assert,
+  assertions,
   rawAssert,
   baseline,
   tags,
@@ -112,22 +112,19 @@ function buildGroqParams(filter) {
  * Map a Content Lake ailf.task document directly to a LiteracyTaskDefinition.
  *
  * Returns null if the document is missing required fields (taskId,
- * description, featureAreaId, taskPrompt). These are required by the
+ * title, areaId, promptText). These are required by the
  * Studio schema, but defensive coding handles edge cases (drafts,
  * partially-created documents, etc.).
  */
 function mapToLiteracyTask(raw) {
     // Required fields — skip malformed documents
-    if (!raw.taskId ||
-        !raw.description ||
-        !raw.featureAreaId ||
-        !raw.taskPrompt) {
+    if (!raw.taskId || !raw.title || !raw.areaId || !raw.promptText) {
         return null;
     }
-    const docs = (raw.canonicalDocs ?? [])
+    const docs = (raw.contextDocs ?? [])
         .map(mapCanonicalDocRef)
         .filter((d) => d !== null);
-    const assertions = mapAssertions(raw.assert ?? []);
+    const assertions = mapAssertions(raw.assertions ?? []);
     // Append raw pass-through assertions (escape hatch for arbitrary Promptfoo
     // assertion types that aren't in the curated list). These bypass template
     // resolution and flow directly into the expanded Promptfoo test case as
@@ -158,9 +155,9 @@ function mapToLiteracyTask(raw) {
     return {
         mode: "literacy",
         id: raw.taskId,
-        title: raw.description,
-        area: raw.featureAreaId,
-        prompt: { text: raw.taskPrompt },
+        title: raw.title,
+        area: raw.areaId,
+        prompt: { text: raw.promptText },
         context: { docs },
         assertions: allAssertions,
         docCoverage: raw.docCoverage ?? false,
@@ -172,7 +169,7 @@ function mapToLiteracyTask(raw) {
     };
 }
 /**
- * Map a Content Lake canonical doc entry to the polymorphic CanonicalDocRef.
+ * Map a Content Lake context doc entry to the polymorphic CanonicalDocRef.
  *
  * Uses `refType` to determine which value field to read. Falls back to
  * slug-based resolution for backward compatibility (documents created

package/dist/adapters/task-sources/index.d.ts

@@ -1,8 +1,8 @@
 export { CompositeTaskSource } from "./composite-task-source.js";
 export { ContentLakeTaskSource } from "./content-lake-task-source.js";
-export { parseRepoConfig, parseRepoTaskFile, RepoConfigSchema, RepoTaskSchema, CURATED_ASSERTION_TYPES, RUBRIC_TEMPLATE_NAMES, type RepoConfig, type RepoTask, } from "./repo-schemas.js";
+export { CanonicalTaskFileSchema, CanonicalTaskSchema, CURATED_ASSERTION_TYPES, detectLegacyFieldNames, parseCanonicalTaskFile, parseRepoConfig, RepoConfigSchema, RUBRIC_TEMPLATE_NAMES, type CanonicalTask, type CuratedAssertionType, type RepoConfig, type RubricTemplateName, } from "./repo-schemas.js";
 export { RepoTaskSource } from "./repo-task-source.js";
 export { detectTriggerContext, resolveTrigger, type ResolvedTrigger, type TriggerContext, } from "./repo-trigger.js";
-export { formatValidationResult, validateRepoTasks, type ValidationMessage, type ValidationResult, } from "./repo-validation.js";
+export { formatValidationResult, validateCanonicalTasks, type ValidationMessage, type ValidationResult, } from "./repo-validation.js";
 export { discoverTsTaskFiles, loadAllTsTaskFiles, loadTsTaskFile, } from "./task-file-loader.js";
 export { YamlTaskSource } from "./yaml-task-source.js";

package/dist/adapters/task-sources/index.js

@@ -1,8 +1,8 @@
 export { CompositeTaskSource } from "./composite-task-source.js";
 export { ContentLakeTaskSource } from "./content-lake-task-source.js";
-export { parseRepoConfig, parseRepoTaskFile, RepoConfigSchema, RepoTaskSchema, CURATED_ASSERTION_TYPES, RUBRIC_TEMPLATE_NAMES, } from "./repo-schemas.js";
+export { CanonicalTaskFileSchema, CanonicalTaskSchema, CURATED_ASSERTION_TYPES, detectLegacyFieldNames, parseCanonicalTaskFile, parseRepoConfig, RepoConfigSchema, RUBRIC_TEMPLATE_NAMES, } from "./repo-schemas.js";
 export { RepoTaskSource } from "./repo-task-source.js";
 export { detectTriggerContext, resolveTrigger, } from "./repo-trigger.js";
-export { formatValidationResult, validateRepoTasks, } from "./repo-validation.js";
+export { formatValidationResult, validateCanonicalTasks, } from "./repo-validation.js";
 export { discoverTsTaskFiles, loadAllTsTaskFiles, loadTsTaskFile, } from "./task-file-loader.js";
 export { YamlTaskSource } from "./yaml-task-source.js";

package/dist/adapters/task-sources/repo-schemas.d.ts

@@ -1,29 +1,231 @@
 /**
- * repo-schemas.ts — Re-exports task schemas + defines config schemas.
+ * repo-schemas.ts — Canonical Zod schemas for task and config validation.
  *
- * Task schemas (RepoTaskSchema, assertions, etc.) are the single source
- * of truth in @sanity/ailf-tasks. This file re-exports them so existing
- * importers within the eval package don't need to change their paths.
+ * Task schemas validate .ailf/tasks/*.yaml and .task.ts files against the
+ * canonical GeneralizedTaskDefinition shape. Field names match the internal
+ * domain model: `area` (not featureArea), `assertions` (not assert),
+ * `context.docs` (not canonicalDocs), `prompt.text` (not vars.task).
  *
- * Config schemas (RepoConfigSchema, trigger config, etc.) remain here
- * because they are specific to the eval pipeline and not needed by
- * external tools that only validate task YAML.
+ * Previously this file re-exported from @sanity/ailf-tasks. That package
+ * has been eliminated — all schema logic now lives here.
  *
- * @see packages/tasks/src/schemas.ts — task schema source of truth
+ * Config schemas (RepoConfigSchema, trigger config) are eval-pipeline-
+ * specific and remain here unchanged.
+ *
+ * @see packages/core/src/types/generalized-task.ts — canonical TypeScript types
  * @see docs/exec-plans/tasks-as-content/phase-4-repo-based-tasks.md
  */
-import { RepoTaskFileSchema as _Schema } from "../../_vendor/ailf-tasks/index.d.ts";
 import { z } from "zod";
-export { CURATED_ASSERTION_TYPES, RepoTaskFileSchema, RepoTaskSchema, RUBRIC_TEMPLATE_NAMES, type CuratedAssertionType, type RepoTask, type RubricTemplateName, } from "../../_vendor/ailf-tasks/index.d.ts";
-export { loadTaskDir, parseTaskFile } from "../../_vendor/ailf-tasks/index.d.ts";
 /**
- * Parse and validate a repo task file's content. Returns typed tasks or throws
- * with a user-friendly Zod error message.
+ * The set of assertion types allowed in task files.
+ *
+ * This is a curated subset of Promptfoo assertion types — we expose only the
+ * types that are stable, well-documented, and useful for external authors.
+ */
+export declare const CURATED_ASSERTION_TYPES: readonly ["llm-rubric", "contains", "contains-any", "contains-all", "not-contains", "icontains", "icontains-any", "regex", "javascript", "similar", "cost", "latency"];
+export type CuratedAssertionType = (typeof CURATED_ASSERTION_TYPES)[number];
+/**
+ * Valid rubric template names — must match keys in config/rubrics.yaml.
+ */
+export declare const RUBRIC_TEMPLATE_NAMES: readonly ["task-completion", "code-correctness", "doc-coverage"];
+export type RubricTemplateName = (typeof RUBRIC_TEMPLATE_NAMES)[number];
+/**
+ * Zod schema for a single task definition using canonical field names.
+ *
+ * Uses .passthrough() to allow mode-specific fields (serverConfig, sandbox,
+ * handler, etc.) without listing every possible field. Mode-specific
+ * validation is deferred to the pipeline's mode handlers.
+ */
+export declare const CanonicalTaskSchema: z.ZodObject<{
+    id: z.ZodString;
+    mode: z.ZodDefault<z.ZodString>;
+    title: z.ZodString;
+    description: z.ZodOptional<z.ZodString>;
+    area: z.ZodOptional<z.ZodString>;
+    difficulty: z.ZodOptional<z.ZodEnum<{
+        basic: "basic";
+        intermediate: "intermediate";
+        advanced: "advanced";
+    }>>;
+    status: z.ZodDefault<z.ZodOptional<z.ZodEnum<{
+        active: "active";
+        draft: "draft";
+        paused: "paused";
+        archived: "archived";
+    }>>>;
+    tags: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    prompt: z.ZodOptional<z.ZodObject<{
+        template: z.ZodOptional<z.ZodString>;
+        text: z.ZodOptional<z.ZodString>;
+        systemMessage: z.ZodOptional<z.ZodString>;
+        vars: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    }, z.core.$strip>>;
+    context: z.ZodOptional<z.ZodObject<{
+        docs: z.ZodOptional<z.ZodArray<z.ZodUnion<readonly [z.ZodObject<{
+            id: z.ZodString;
+            reason: z.ZodDefault<z.ZodOptional<z.ZodString>>;
+            slug: z.ZodOptional<z.ZodString>;
+            path: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>, z.ZodObject<{
+            slug: z.ZodString;
+            reason: z.ZodDefault<z.ZodOptional<z.ZodString>>;
+        }, z.core.$strip>, z.ZodObject<{
+            path: z.ZodString;
+            reason: z.ZodDefault<z.ZodOptional<z.ZodString>>;
+        }, z.core.$strip>, z.ZodObject<{
+            perspective: z.ZodString;
+            reason: z.ZodDefault<z.ZodOptional<z.ZodString>>;
+        }, z.core.$strip>]>>>;
+        fixtures: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    }, z.core.$strip>>;
+    assertions: z.ZodOptional<z.ZodArray<z.ZodUnion<readonly [z.ZodObject<{
+        type: z.ZodLiteral<"llm-rubric">;
+        template: z.ZodEnum<{
+            "task-completion": "task-completion";
+            "code-correctness": "code-correctness";
+            "doc-coverage": "doc-coverage";
+        }>;
+        criteria: z.ZodArray<z.ZodString>;
+        weight: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>, z.ZodObject<{
+        type: z.ZodEnum<{
+            "llm-rubric": "llm-rubric";
+            contains: "contains";
+            "contains-any": "contains-any";
+            "contains-all": "contains-all";
+            "not-contains": "not-contains";
+            icontains: "icontains";
+            "icontains-any": "icontains-any";
+            regex: "regex";
+            javascript: "javascript";
+            similar: "similar";
+            cost: "cost";
+            latency: "latency";
+        }>;
+        value: z.ZodOptional<z.ZodUnknown>;
+        threshold: z.ZodOptional<z.ZodNumber>;
+        weight: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$loose>]>>>;
+    referenceSolution: z.ZodOptional<z.ZodString>;
+    docCoverage: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
+    baseline: z.ZodOptional<z.ZodObject<{
+        enabled: z.ZodOptional<z.ZodBoolean>;
+        rubric: z.ZodOptional<z.ZodEnum<{
+            full: "full";
+            abbreviated: "abbreviated";
+            none: "none";
+        }>>;
+    }, z.core.$strip>>;
+    rubric: z.ZodOptional<z.ZodUnknown>;
+    providers: z.ZodOptional<z.ZodArray<z.ZodUnknown>>;
+    options: z.ZodOptional<z.ZodUnknown>;
+    metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, z.core.$loose>;
+export type CanonicalTask = z.infer<typeof CanonicalTaskSchema>;
+/**
+ * Schema for an array of canonical tasks — what a single .ailf/tasks/*.yaml
+ * file contains. Each file must define at least one task.
+ */
+export declare const CanonicalTaskFileSchema: z.ZodArray<z.ZodObject<{
+    id: z.ZodString;
+    mode: z.ZodDefault<z.ZodString>;
+    title: z.ZodString;
+    description: z.ZodOptional<z.ZodString>;
+    area: z.ZodOptional<z.ZodString>;
+    difficulty: z.ZodOptional<z.ZodEnum<{
+        basic: "basic";
+        intermediate: "intermediate";
+        advanced: "advanced";
+    }>>;
+    status: z.ZodDefault<z.ZodOptional<z.ZodEnum<{
+        active: "active";
+        draft: "draft";
+        paused: "paused";
+        archived: "archived";
+    }>>>;
+    tags: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    prompt: z.ZodOptional<z.ZodObject<{
+        template: z.ZodOptional<z.ZodString>;
+        text: z.ZodOptional<z.ZodString>;
+        systemMessage: z.ZodOptional<z.ZodString>;
+        vars: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    }, z.core.$strip>>;
+    context: z.ZodOptional<z.ZodObject<{
+        docs: z.ZodOptional<z.ZodArray<z.ZodUnion<readonly [z.ZodObject<{
+            id: z.ZodString;
+            reason: z.ZodDefault<z.ZodOptional<z.ZodString>>;
+            slug: z.ZodOptional<z.ZodString>;
+            path: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>, z.ZodObject<{
+            slug: z.ZodString;
+            reason: z.ZodDefault<z.ZodOptional<z.ZodString>>;
+        }, z.core.$strip>, z.ZodObject<{
+            path: z.ZodString;
+            reason: z.ZodDefault<z.ZodOptional<z.ZodString>>;
+        }, z.core.$strip>, z.ZodObject<{
+            perspective: z.ZodString;
+            reason: z.ZodDefault<z.ZodOptional<z.ZodString>>;
+        }, z.core.$strip>]>>>;
+        fixtures: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    }, z.core.$strip>>;
+    assertions: z.ZodOptional<z.ZodArray<z.ZodUnion<readonly [z.ZodObject<{
+        type: z.ZodLiteral<"llm-rubric">;
+        template: z.ZodEnum<{
+            "task-completion": "task-completion";
+            "code-correctness": "code-correctness";
+            "doc-coverage": "doc-coverage";
+        }>;
+        criteria: z.ZodArray<z.ZodString>;
+        weight: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>, z.ZodObject<{
+        type: z.ZodEnum<{
+            "llm-rubric": "llm-rubric";
+            contains: "contains";
+            "contains-any": "contains-any";
+            "contains-all": "contains-all";
+            "not-contains": "not-contains";
+            icontains: "icontains";
+            "icontains-any": "icontains-any";
+            regex: "regex";
+            javascript: "javascript";
+            similar: "similar";
+            cost: "cost";
+            latency: "latency";
+        }>;
+        value: z.ZodOptional<z.ZodUnknown>;
+        threshold: z.ZodOptional<z.ZodNumber>;
+        weight: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$loose>]>>>;
+    referenceSolution: z.ZodOptional<z.ZodString>;
+    docCoverage: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
+    baseline: z.ZodOptional<z.ZodObject<{
+        enabled: z.ZodOptional<z.ZodBoolean>;
+        rubric: z.ZodOptional<z.ZodEnum<{
+            full: "full";
+            abbreviated: "abbreviated";
+            none: "none";
+        }>>;
+    }, z.core.$strip>>;
+    rubric: z.ZodOptional<z.ZodUnknown>;
+    providers: z.ZodOptional<z.ZodArray<z.ZodUnknown>>;
+    options: z.ZodOptional<z.ZodUnknown>;
+    metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, z.core.$loose>>;
+/**
+ * Parse and validate a task file's content against the canonical schema.
+ * Returns typed tasks or throws with a user-friendly Zod error message.
+ *
+ * Accepts pre-parsed YAML data (unknown), not a raw string.
+ */
+export declare function parseCanonicalTaskFile(raw: unknown, filename: string): CanonicalTask[];
+/**
+ * Detect legacy field names in raw task data and return helpful messages.
  *
- * NOTE: This accepts pre-parsed YAML data (unknown), not a raw string.
- * For raw YAML strings, use `parseTaskFile()` from @sanity/ailf-tasks.
+ * Runs BEFORE Zod parsing to catch the most common migration mistake —
+ * using old field names from @sanity/ailf-tasks instead of the canonical
+ * GeneralizedTaskDefinition shape.
  */
-export declare function parseRepoTaskFile(raw: unknown, filename: string): z.infer<typeof _Schema>;
+export declare function detectLegacyFieldNames(raw: unknown, filename: string): string[];
 /**
  * Zod schema for .ailf/config.yaml — controls documentation source,
  * report destination, and trigger behavior for evaluations from an