@sanity/ailf 6.0.0 → 6.1.1

package/config/airbyte/ai_literacy_framework.connector.yaml

@@ -225,6 +225,134 @@ definitions:
         schema:
           $ref: "#/schemas/area_scores"
 
+    # ------------------------------------------------------------------
+    # Stream 3: synthesis_summary — one row per report with synthesis telemetry
+    # ------------------------------------------------------------------
+    # GROQ projection emits cost, parse-failure counts, and rate from the
+    # summary.synthesis.diagnosis path written by the Phase-6 post-run hook.
+    # Rows are gated on defined(summary.synthesis.diagnosis) so reports that
+    # predate Phase 6 produce no rows (incremental cursor still catches them
+    # on re-sync once backfilled).
+    synthesis_summary:
+      type: DeclarativeStream
+      name: synthesis_summary
+      retriever:
+        type: SimpleRetriever
+        decoder:
+          type: JsonDecoder
+        requester:
+          $ref: "#/definitions/base_requester"
+          path: /v2026-03-12/data/query/{{ config['dataset'] }}
+          http_method: GET
+          request_parameters:
+            query: >-
+              *[_type=="ailf.report" && _createdAt > "{{
+              stream_interval.start_time or '1970-01-01T00:00:00Z' }}" &&
+              _createdAt <= "{{ stream_interval.end_time }}" &&
+              defined(summary.synthesis.diagnosis)]|order(_createdAt asc){
+                "report_id": reportId,
+                "completed_at": completedAt,
+                "mode": provenance.mode,
+                "source_name": provenance.source.name,
+                "grader_model": provenance.graderModel,
+                "synthesis_cost": summary.synthesis.diagnosis.cost,
+                "parse_failure_count":
+              summary.synthesis.diagnosis.parseFailureCount,
+                "parse_failure_rate":
+              summary.synthesis.diagnosis.parseFailureRate,
+                _createdAt
+              }
+        record_selector:
+          type: RecordSelector
+          extractor:
+            type: DpathExtractor
+            field_path:
+              - result
+      primary_key:
+        - report_id
+      incremental_sync:
+        type: DatetimeBasedCursor
+        cursor_field: _createdAt
+        cursor_datetime_formats:
+          - "%Y-%m-%dT%H:%M:%S.%fZ"
+          - "%Y-%m-%dT%H:%M:%SZ"
+        datetime_format: "%Y-%m-%dT%H:%M:%SZ"
+        start_datetime:
+          type: MinMaxDatetime
+          datetime: "{{ config.get('start_date', '2026-01-01T00:00:00Z') }}"
+          datetime_format: "%Y-%m-%dT%H:%M:%SZ"
+        step: P30D
+        cursor_granularity: PT1S
+      schema_loader:
+        type: InlineSchemaLoader
+        schema:
+          $ref: "#/schemas/synthesis_summary"
+
+    # ------------------------------------------------------------------
+    # Stream 4: synthesis_per_card — one row per report with per-card array
+    # ------------------------------------------------------------------
+    # GROQ projection emits the nested perCard array. GROQ cannot explode
+    # arrays into flat rows, so the nesting is preserved — BigQuery consumers
+    # should UNNEST(JSON_QUERY_ARRAY(per_card)) to get flat rows per card.
+    # primary_key is report_id only (not compound) for the same reason.
+    synthesis_per_card:
+      type: DeclarativeStream
+      name: synthesis_per_card
+      retriever:
+        type: SimpleRetriever
+        decoder:
+          type: JsonDecoder
+        requester:
+          $ref: "#/definitions/base_requester"
+          path: /v2026-03-12/data/query/{{ config['dataset'] }}
+          http_method: GET
+          request_parameters:
+            query: >-
+              *[_type=="ailf.report" && _createdAt > "{{
+              stream_interval.start_time or '1970-01-01T00:00:00Z' }}" &&
+              _createdAt <= "{{ stream_interval.end_time }}" &&
+              defined(summary.synthesis.diagnosis.perCard)]|order(_createdAt
+              asc){
+                "report_id": reportId,
+                "completed_at": completedAt,
+                "per_card": summary.synthesis.diagnosis.perCard[]{
+                  "card_type": cardType,
+                  "cost": cost,
+                  "parse_failed": parseFailed,
+                  "latency_ms": latencyMs,
+                  "token_input": tokenInput,
+                  "token_output": tokenOutput,
+                  "card_version": cardVersion,
+                  "generated_at": generatedAt
+                },
+                _createdAt
+              }
+        record_selector:
+          type: RecordSelector
+          extractor:
+            type: DpathExtractor
+            field_path:
+              - result
+      primary_key:
+        - report_id
+      incremental_sync:
+        type: DatetimeBasedCursor
+        cursor_field: _createdAt
+        cursor_datetime_formats:
+          - "%Y-%m-%dT%H:%M:%S.%fZ"
+          - "%Y-%m-%dT%H:%M:%SZ"
+        datetime_format: "%Y-%m-%dT%H:%M:%SZ"
+        start_datetime:
+          type: MinMaxDatetime
+          datetime: "{{ config.get('start_date', '2026-01-01T00:00:00Z') }}"
+          datetime_format: "%Y-%m-%dT%H:%M:%SZ"
+        step: P30D
+        cursor_granularity: PT1S
+      schema_loader:
+        type: InlineSchemaLoader
+        schema:
+          $ref: "#/schemas/synthesis_per_card"
+
   base_requester:
     type: HttpRequester
     url_base: https://{{ config['project_id'] }}.api.sanity.io
@@ -235,6 +363,8 @@ definitions:
 streams:
   - $ref: "#/definitions/streams/reports"
   - $ref: "#/definitions/streams/area_scores"
+  - $ref: "#/definitions/streams/synthesis_summary"
+  - $ref: "#/definitions/streams/synthesis_per_card"
 
 spec:
   type: Spec
@@ -299,9 +429,25 @@ metadata:
       primaryKeysAreUnique: true
       primaryKeysArePresent: true
       responsesAreSuccessful: true
+    synthesis_summary:
+      hasRecords: true
+      streamHash: null
+      hasResponse: true
+      primaryKeysAreUnique: true
+      primaryKeysArePresent: true
+      responsesAreSuccessful: true
+    synthesis_per_card:
+      hasRecords: true
+      streamHash: null
+      hasResponse: true
+      primaryKeysAreUnique: true
+      primaryKeysArePresent: true
+      responsesAreSuccessful: true
   autoImportSchema:
     reports: false
     area_scores: false
+    synthesis_summary: false
+    synthesis_per_card: false
 
 # ======================================================================
 # Inline schemas — manually defined to match the designed BigQuery tables.
@@ -757,3 +903,133 @@ schemas:
           - "null"
         description: Sanity document creation timestamp (incremental cursor)
     additionalProperties: true
+
+  # ------------------------------------------------------------------
+  # synthesis_summary schema — flat, one row per report with synthesis telemetry
+  # ------------------------------------------------------------------
+  synthesis_summary:
+    type: object
+    $schema: http://json-schema.org/schema#
+    required:
+      - report_id
+    properties:
+      report_id:
+        type: string
+        description: UUID v7 report identifier (primary key)
+      completed_at:
+        type:
+          - string
+          - "null"
+        description: ISO 8601 timestamp when the evaluation completed
+      mode:
+        type:
+          - string
+          - "null"
+        description: "Evaluation mode: baseline, observed, or agentic"
+      source_name:
+        type:
+          - string
+          - "null"
+        description: Documentation source name (e.g., "production")
+      grader_model:
+        type:
+          - string
+          - "null"
+        description: Model used for LLM grading (context for cost comparison)
+      synthesis_cost:
+        type:
+          - number
+          - "null"
+        description:
+          Total USD cost of the Diagnosis synthesis run (sum of all card costs)
+      parse_failure_count:
+        type:
+          - number
+          - "null"
+        description:
+          Number of cards that failed Zod schema parse during synthesis
+      parse_failure_rate:
+        type:
+          - number
+          - "null"
+        description:
+          Fraction of cards that failed parse (0–1); 0.0 = no failures
+      _createdAt:
+        type:
+          - string
+          - "null"
+        description:
+          Sanity document creation timestamp (used as incremental cursor)
+    additionalProperties: true
+
+  # ------------------------------------------------------------------
+  # synthesis_per_card schema — nested per-card array, one row per report
+  # ------------------------------------------------------------------
+  # BigQuery consumers should UNNEST(JSON_QUERY_ARRAY(per_card)) to get
+  # flat rows per (report × card). See bigquery/views/synthesis_parse_failure_rate_7d.sql
+  synthesis_per_card:
+    type: object
+    $schema: http://json-schema.org/schema#
+    required:
+      - report_id
+    properties:
+      report_id:
+        type: string
+        description: UUID v7 report identifier (primary key)
+      completed_at:
+        type:
+          - string
+          - "null"
+        description: Denormalized timestamp for partitioning
+      per_card:
+        type:
+          - array
+          - "null"
+        description: >-
+          Per-card synthesis metrics array. UNNEST in BigQuery to get one flat
+          row per card. card_type identifies the diagnosis card type (e.g.,
+          "top-recommendations").
+        items:
+          type: object
+          properties:
+            card_type:
+              type: string
+              description: Diagnosis card type identifier (≤25 chars)
+            cost:
+              type:
+                - number
+                - "null"
+              description:
+                USD cost of this card's LLM call (null for deterministic cards)
+            parse_failed:
+              type: boolean
+              description: Whether the card's Zod schema parse failed
+            latency_ms:
+              type:
+                - number
+                - "null"
+              description: LLM call latency in milliseconds
+            token_input:
+              type:
+                - number
+                - "null"
+              description: Input tokens consumed by the LLM call
+            token_output:
+              type:
+                - number
+                - "null"
+              description: Output tokens produced by the LLM call
+            card_version:
+              type: string
+              description:
+                Card implementation version (e.g., "area-summary@0.1.0")
+            generated_at:
+              type: string
+              description: ISO 8601 UTC timestamp when this card was generated
+      _createdAt:
+        type:
+          - string
+          - "null"
+        description:
+          Sanity document creation timestamp (used as incremental cursor)
+    additionalProperties: true

package/config/bigquery/views/synthesis_parse_failure_rate_7d.sql

@@ -0,0 +1,42 @@
+-- ailf.synthesis_parse_failure_rate_7d — per-card parse-failure rate over 7 days
+--
+-- Computes the Zod-schema parse-failure rate per Diagnosis card type over the
+-- previous 7 days, sourced from the synthesis_per_card Airbyte stream. Any row
+-- returned by this view represents a card type that breached the 2% threshold
+-- defined in D6-18 and should trigger a manual investigation per the runbook.
+--
+-- Source: ailf_raw.synthesis_per_card (Airbyte stream: "synthesis_per_card")
+-- Target: ailf.synthesis_parse_failure_rate_7d (this view)
+--
+-- Threshold: failure_rate > 0.02 (2%) over INTERVAL 7 DAY  [D6-18]
+-- To change the threshold, edit the HAVING clause and WHERE clause below;
+-- both are the single edit points per D6-18 (not lifted to config).
+--
+-- Usage:
+--   bq query --use_legacy_sql=false < views/synthesis_parse_failure_rate_7d.sql
+--
+-- @see docs/runbooks/diagnosis-parse-failure-watch.md — operator runbook
+-- @see packages/eval/config/airbyte/ai_literacy_framework.connector.yaml — synthesis_per_card stream
+
+CREATE OR REPLACE VIEW `data-platform-302218.ailf.synthesis_parse_failure_rate_7d` AS
+SELECT
+  JSON_VALUE(card, '$.card_type')                                        AS card_type,
+  COUNT(*)                                                               AS total_runs,
+  COUNTIF(SAFE_CAST(JSON_VALUE(card, '$.parse_failed') AS BOOL))        AS parse_failures,
+  ROUND(SAFE_DIVIDE(
+    COUNTIF(SAFE_CAST(JSON_VALUE(card, '$.parse_failed') AS BOOL)),
+    COUNT(*)
+  ), 4)                                                                  AS failure_rate
+FROM
+  `data-platform-302218.ailf_raw.synthesis_per_card` AS r,
+  UNNEST(JSON_QUERY_ARRAY(r.per_card)) AS card
+WHERE
+  r.completed_at IS NOT NULL
+  AND TIMESTAMP(r.completed_at) >= TIMESTAMP_SUB(CURRENT_TIMESTAMP(), INTERVAL 7 DAY)
+  AND JSON_VALUE(card, '$.card_type') IS NOT NULL
+GROUP BY
+  card_type
+HAVING
+  failure_rate > 0.02
+ORDER BY
+  failure_rate DESC

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

@@ -200,6 +200,23 @@ export interface ArtifactDescriptor<TEntry = unknown, TPreview = unknown> {
      *   descriptors. `entryKey` is ignored on versioned bulk paths.
      */
     readonly objectPath: ArtifactObjectPath;
+    /**
+     * Extract the positional args (beyond `runId`) to pass to `objectPath`
+     * when this descriptor needs more than `runId` to build its path.
+     *
+     * The default plain-bulk path is `objectPath(runId)`. The default
+     * per-entry path is `objectPath(runId, entryKey)`. Descriptors whose
+     * path needs additional axes from `association` and/or fields from the
+     * payload (e.g. the bulk-versioned-with-report-axis carve-out used by
+     * the diagnosis descriptor — see `BULK_VERSIONED_WITH_REPORT_AXIS`)
+     * set this function. The writer calls it and spreads the result:
+     *   `objectPath(runId, ...extractPathArgs(association, payload))`.
+     *
+     * Returning `[undefined]` (or any `undefined` element) is fine — the
+     * underlying builder is expected to throw a meaningful error in that
+     * case, which the writer surfaces via its existing try/catch.
+     */
+    readonly extractPathArgs?: (association: AssociationValues, payload: unknown) => readonly (string | undefined)[];
     /**
      * Build a filename-safe entry key from association values. Only meaningful
      * for `layout === "per-entry"` — bulk descriptors omit it.

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

@@ -674,6 +674,7 @@ function buildDescriptor(input) {
         versionedBy: input.versionedBy,
         pathSafetyMarker: input.pathSafetyMarker,
         objectPath,
+        extractPathArgs: input.extractPathArgs,
         formatEntryKey,
         parseEntryKey,
         manifestPreview: input.manifestPreview,
@@ -1185,6 +1186,19 @@ export const ARTIFACT_REGISTRY = {
         writePolicy: "post-hoc",
         versionedBy: "diagnosisVersion",
         objectPath: diagnosisPathBuilder(),
+        // The diagnosis path builder takes (runId, reportId, version). The
+        // reportId comes from association.report; the version is a compound
+        // `diagnosisVersion|cardVersion` synthesized from the payload's
+        // `inputs` field via `encodeDiagnosisPathVersion`. Writers spread
+        // this beyond `runId` when calling `objectPath`.
+        extractPathArgs: (assoc, payload) => {
+            const reportId = typeof assoc.report === "string" ? assoc.report : undefined;
+            const diag = payload;
+            const dv = diag?.inputs?.diagnosisVersion;
+            const cv = diag?.inputs?.cardVersion;
+            const version = dv && cv ? encodeDiagnosisPathVersion(dv, cv) : undefined;
+            return [reportId, version];
+        },
         // Defense-in-depth: this descriptor's axes (`run`, `report`) are both
         // bounded, so the `assertValidArtifactDescriptor` unbounded-axis rule
         // does not fire and the carve-out is never consulted at module load

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

@@ -237,6 +237,14 @@ export interface ResolvedConfig {
      * Sourced from AILF_ARTIFACT_UPLOAD env var or `artifactUpload` in ailf.config.ts.
      */
     artifactUpload?: boolean;
+    /**
+     * Post-run diagnosis summary policy (Phase 6 / DIAG-06). Carried from
+     * `.ailf/config.yaml` summary.onRun via RepoConfigSchema (CLI path) or
+     * EvalConfigSchema (file-config path). Precedence resolution is deferred to
+     * shouldRunPostSummary() at execution time — this field carries only the
+     * config-file signal.
+     */
+    summaryOnRun?: "auto" | "always" | "never";
 }
 /**
  * Application context — the complete dependency carrier.
@@ -331,6 +339,20 @@ export interface ReportStorePort {
     findComparableBaseline(query: unknown): Promise<null | unknown>;
     /** Write a report to the store */
     write(report: unknown): Promise<unknown>;
+    /** Read a report by its ID (used by the post-run diagnosis hook). */
+    read(id: string): Promise<null | unknown>;
+    /** Patch synthesis telemetry onto a published report (Phase 6 / DIAG-06). */
+    patchSynthesis(id: string, telemetry: unknown): Promise<void>;
+    /**
+     * Patch a single artifact-manifest entry onto a published report.
+     *
+     * Used by deferred commands (e.g. `ailf interpret`) whose post-hoc writer
+     * produces a new ArtifactRef after the doc was already published. The
+     * pipeline path lifts the full manifest at publish time
+     * (publish-report-step); this is the post-hoc equivalent for one slot.
+     * Non-fatal on Sanity failure — mirrors `patchSynthesis`.
+     */
+    patchArtifactManifest(id: string, slot: string, ref: unknown): Promise<void>;
 }
 /**
  * Minimal report sink interface used by AppContext.

package/dist/_vendor/ailf-core/schemas/eval-config.d.ts

@@ -88,6 +88,13 @@ export declare const EvalConfigSchema: z.ZodObject<{
     skipEval: z.ZodOptional<z.ZodBoolean>;
     skipFetch: z.ZodOptional<z.ZodBoolean>;
     source: z.ZodOptional<z.ZodString>;
+    summary: z.ZodOptional<z.ZodObject<{
+        onRun: z.ZodOptional<z.ZodEnum<{
+            never: "never";
+            always: "always";
+            auto: "auto";
+        }>>;
+    }, z.core.$strip>>;
     tasks: z.ZodOptional<z.ZodArray<z.ZodString>>;
     urls: z.ZodOptional<z.ZodArray<z.ZodString>>;
     presets: z.ZodOptional<z.ZodArray<z.ZodString>>;

package/dist/_vendor/ailf-core/schemas/eval-config.js

@@ -175,6 +175,14 @@ export const EvalConfigSchema = z
     skipFetch: z.boolean().optional(),
     /** Documentation source name */
     source: z.string().optional(),
+    /**
+     * Post-run diagnosis summary policy (Phase 6 / DIAG-06). Mirrors
+     * `RepoConfigSchema`'s `summary` block for `--config <path>` parity.
+     * Precedence resolved at the CLI layer by `shouldRunPostSummary()`.
+     */
+    summary: z
+        .object({ onRun: z.enum(["auto", "always", "never"]).optional() })
+        .optional(),
     /** Task ID filter */
     tasks: z.array(z.string()).optional(),
     /** Doc source URL overrides */

package/dist/_vendor/ailf-core/services/diagnosis/cards/__tests__/failure-mode-summary.test.js

@@ -169,3 +169,62 @@ describe("generateFailureModeSummary — empty failure modes (Test 9)", () => {
         }
     });
 });
+describe("generateFailureModeSummary — cross-cutting mode resolution", () => {
+    // `missing-docs` appears in both LITERACY_FAILURE_MODES and MCP_FAILURE_MODES.
+    // Before the per-EvalMode preference table, linear scan of CANONICAL_DIMENSIONS
+    // always resolved it to task-completion, mislabelling MCP-only runs.
+    function withMode(report, mode) {
+        return {
+            ...report,
+            provenance: { ...report.provenance, mode },
+        };
+    }
+    it("resolves 'missing-docs' to mcp-behavior on an mcp-server report", async () => {
+        const base = makeReport({
+            counts: { "mcp-behavior": 7 },
+            topTitles: [
+                {
+                    id: "mcp-behavior::missing-docs",
+                    category: "missing-docs",
+                    severity: "high",
+                    title: "missing-docs",
+                    count: 7,
+                },
+            ],
+            totalJudgments: 20,
+            classificationRate: 0.35,
+        });
+        const report = withMode(base, "mcp-server");
+        const card = await generateFailureModeSummary(report, makeCtx());
+        expect(card.status).toBe("ready");
+        if (card.status === "ready") {
+            const body = card.body;
+            expect(body.dimension).toBe("mcp-behavior");
+            expect(body.failureMode).toBe("missing-docs");
+        }
+    });
+    it("resolves 'missing-docs' to task-completion on a literacy report", async () => {
+        const base = makeReport({
+            counts: { "task-completion": 7 },
+            topTitles: [
+                {
+                    id: "task-completion::missing-docs",
+                    category: "missing-docs",
+                    severity: "high",
+                    title: "missing-docs",
+                    count: 7,
+                },
+            ],
+            totalJudgments: 20,
+            classificationRate: 0.35,
+        });
+        const report = withMode(base, "literacy");
+        const card = await generateFailureModeSummary(report, makeCtx());
+        expect(card.status).toBe("ready");
+        if (card.status === "ready") {
+            const body = card.body;
+            expect(body.dimension).toBe("task-completion");
+            expect(body.failureMode).toBe("missing-docs");
+        }
+    });
+});

package/dist/_vendor/ailf-core/services/diagnosis/cards/doc-attribution-spotlight.js

@@ -79,7 +79,9 @@ export const generateDocAttributionSpotlight = async (report, ctx) => {
             .max(5),
     });
     const prompt = buildDocAttributionSpotlightPrompt(report, ctx.judgmentAttributions);
-    const { value, usage } = await ctx.llm.completeStructured({
+    // Destructure `cost` and `model` from the LLMClient return —
+    // already provided per llm-client.ts:139-144, previously discarded.
+    const { value, usage, cost, model } = await ctx.llm.completeStructured({
         model: CARD_MODEL,
         prompt: `${prompt.system}\n\n${prompt.user}`,
         schema: PerCallSchema,
@@ -99,6 +101,8 @@ export const generateDocAttributionSpotlight = async (report, ctx) => {
             cardVersion: "doc-attribution-spotlight@0.1.0",
             tokenUsage: { input: usage.promptTokens, output: usage.completionTokens },
             generatedAt: new Date().toISOString(),
+            cost,
+            model,
         },
     };
 };

package/dist/_vendor/ailf-core/services/diagnosis/cards/failure-mode-summary.js

@@ -38,10 +38,54 @@ export const FailureModeSummaryBodySchema = z
 // Private helper — find the dimension a failure mode belongs to
 // ---------------------------------------------------------------------------
 /**
- * Find the first canonical dimension whose taxonomy includes `mode`.
+ * Per-family dimension preference order.
+ *
+ * Some failure modes (e.g., `missing-docs`) appear in multiple dimension
+ * families. When we know the report's eval mode, we should resolve the mode
+ * to a dimension in the matching family first, falling back to the linear
+ * scan only when the mode-preferred family doesn't carry the failure mode.
+ */
+const MODE_TO_PREFERRED_DIMENSIONS = {
+    literacy: ["task-completion", "code-correctness", "doc-coverage"],
+    "mcp-server": [
+        "mcp-behavior",
+        "input-validation",
+        "output-correctness",
+        "error-handling",
+        "security",
+    ],
+    "knowledge-probe": [
+        "knowledge-probe",
+        "factual-correctness",
+        "completeness",
+        "currency",
+    ],
+    "agent-harness": [
+        "agent-harness",
+        "process-quality",
+        "agent-output",
+        "tool-usage",
+    ],
+    custom: [],
+};
+/**
+ * Find a canonical dimension whose taxonomy includes `mode`. When a
+ * `preferredEvalMode` is supplied, prefer dimensions in the eval mode's
+ * family — e.g. a mode appearing in both literacy and MCP resolves to MCP on
+ * an MCP-only run. Falls back to the linear scan of CANONICAL_DIMENSIONS so
+ * cross-cutting modes (and modes from unknown eval modes) still resolve.
+ *
  * Returns `undefined` if the mode is not in any dimension's taxonomy.
  */
-function findDimensionForMode(mode) {
+function findDimensionForMode(mode, preferredEvalMode) {
+    if (preferredEvalMode) {
+        const preferred = MODE_TO_PREFERRED_DIMENSIONS[preferredEvalMode] ?? [];
+        for (const dim of preferred) {
+            if (failureModesForDimension(dim).includes(mode)) {
+                return dim;
+            }
+        }
+    }
     for (const dim of CANONICAL_DIMENSIONS) {
         if (failureModesForDimension(dim).includes(mode)) {
             return dim;
@@ -67,7 +111,7 @@ export const generateFailureModeSummary = async (report) => {
     // Find the top entry — topTitles is already sorted by count descending
     const topEntry = slimFm.topTitles.reduce((best, entry) => (entry.count > best.count ? entry : best), slimFm.topTitles[0]);
     const failureMode = topEntry.category;
-    const dimension = findDimensionForMode(failureMode);
+    const dimension = findDimensionForMode(failureMode, report.provenance?.mode);
     if (!dimension) {
         return {
             status: "missing",

package/dist/_vendor/ailf-core/services/diagnosis/cards/index.d.ts

@@ -25,6 +25,16 @@ import { generateDocAttributionSpotlight } from "./doc-attribution-spotlight.js"
 import { generateRegressionVsBaseline } from "./regression-vs-baseline.js";
 import type { CardGenerator } from "../../diagnosis-runner.js";
 import type { CardType } from "../../../types/diagnosis.js";
+/**
+ * Canonical version of the card-registry surface — bumped whenever any card
+ * generator or body schema in this barrel changes. Used as the `cardVersion`
+ * fallback in version-resolver helpers (CLI `interpret`, API
+ * `versionsFromRecord`) so the four-version cache invalidation envelope stays
+ * in sync with the actual registry.
+ *
+ * Mirrors the pattern of `diagnosisVersion` exported from `diagnosis-runner.ts`.
+ */
+export declare const CARD_REGISTRY_VERSION = "0.1.0";
 /**
  * The canonical card-generator registry for the diagnosis engine.
  *

package/dist/_vendor/ailf-core/services/diagnosis/cards/index.js

@@ -24,6 +24,19 @@ import { generateLowConfidenceAttribution } from "./low-confidence-attribution.j
 import { generateDocAttributionSpotlight } from "./doc-attribution-spotlight.js";
 import { generateRegressionVsBaseline } from "./regression-vs-baseline.js";
 // ---------------------------------------------------------------------------
+// Card registry version (cache invalidation segment)
+// ---------------------------------------------------------------------------
+/**
+ * Canonical version of the card-registry surface — bumped whenever any card
+ * generator or body schema in this barrel changes. Used as the `cardVersion`
+ * fallback in version-resolver helpers (CLI `interpret`, API
+ * `versionsFromRecord`) so the four-version cache invalidation envelope stays
+ * in sync with the actual registry.
+ *
+ * Mirrors the pattern of `diagnosisVersion` exported from `diagnosis-runner.ts`.
+ */
+export const CARD_REGISTRY_VERSION = "0.1.0";
+// ---------------------------------------------------------------------------
 // DIAGNOSIS_CARD_GENERATORS — full 8-card registry literal
 // ---------------------------------------------------------------------------
 /**