@sanity/ailf 4.0.7 → 4.2.0

package/dist/report-store.d.ts

@@ -83,6 +83,9 @@ export declare class ReportStore {
     findComparableBaseline(query: LineageQuery): Promise<null | Report>;
     /**
      * Read a report by its ID.
+     *
+     * @throws {ReportSchemaValidationError} if the stored document fails the
+     *   W0191 runtime schema gate. Sanity API failures still return null.
      */
     read(id: ReportId): Promise<null | Report>;
     /**
@@ -91,7 +94,10 @@ export declare class ReportStore {
      * 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)
+     * @returns The report ID on success, null on Sanity API failure (logged,
+     *   not thrown — P5 local-first).
+     * @throws {ReportSchemaValidationError} if the report fails the W0191
+     *   runtime schema gate. Schema drift is a bug, not an outage.
      */
     write(report: Report): Promise<null | ReportId>;
     /**
@@ -121,3 +127,59 @@ export declare class ReportStore {
  * Uses crypto.randomUUID() as a base and overwrites the timestamp portion.
  */
 export declare function generateReportId(): ReportId;
+/**
+ * Tagged error thrown by `toReport` and `ReportStore.write` when a Content
+ * Lake document fails the W0191 runtime schema gate. Read paths
+ * (`read`, `findByFingerprint`, `findComparableBaseline`) re-throw this
+ * error rather than swallowing it via the P5 log-and-continue try/catch
+ * — schema drift is a bug to be surfaced, not an outage to be tolerated.
+ */
+export declare class ReportSchemaValidationError extends Error {
+    constructor(message: string);
+}
+/**
+ * Build the Sanity `ailf.report` document shape for a domain `Report`.
+ *
+ * Inverse of `toReport`. Strips the baseline + experiment ScoreSummary
+ * bulk from any nested comparison (they duplicate `report.summary` and the
+ * `comparedAgainst` lineage), and lifts `artifactManifest` into the
+ * `summary.artifactManifest` slot where the D0032 GROQ projection expects
+ * it.
+ *
+ * Pure: takes a `Report`, returns a Sanity-shaped object literal. No I/O.
+ * Used by `ReportStore.write` (production) and round-trip contract tests
+ * (W0188) which need a deterministic forward-and-back mapping.
+ */
+export interface SanityReportDoc {
+    _id: string;
+    _type: string;
+    comparison: null | Omit<ComparisonReport, "baseline" | "experiment">;
+    completedAt: string;
+    durationMs: number;
+    provenance: Report["provenance"];
+    reportId: ReportId;
+    summary: Report["summary"] & {
+        artifactManifest?: Report["artifactManifest"];
+    };
+    tag: null | string;
+    title: null | string;
+}
+export declare function toSanityReportDoc(report: Report): SanityReportDoc;
+/**
+ * Convert a raw Sanity document to a typed Report.
+ *
+ * The Sanity document shape mirrors the Report type but includes Sanity
+ * metadata (_id, _type, _rev, etc.) that we strip.
+ */
+export declare function toReport(doc: Record<string, unknown>): Report;
+/**
+ * Remove the `baseline` and `experiment` ScoreSummary objects from a
+ * ComparisonReport, producing a slim copy suitable for persistence.
+ *
+ * These fields are redundant in the stored document:
+ * - `experiment` is byte-for-byte identical to `report.summary`
+ * - `baseline` is fetchable via `provenance.lineage.comparedAgainst`
+ *
+ * Everything else (deltas, areas, classifications) is preserved.
+ */
+export declare function stripComparisonBulk(comparison: ComparisonReport): Omit<ComparisonReport, "baseline" | "experiment">;

package/dist/report-store.js

@@ -14,7 +14,8 @@
  * @see docs/design-docs/report-store/architecture.md
  * @see docs/design-docs/report-store/domain-model.md
  */
-import { getSanityClient } from "./sanity/client.js";
+import { ReportSchema } from "./_vendor/ailf-core/index.js";
+import { getAilfSanityClient } from "./sanity/client.js";
 import { compare } from "./pipeline/compare.js";
 // ---------------------------------------------------------------------------
 // Constants
@@ -30,7 +31,7 @@ export class ReportStore {
             this.client = options.client;
         }
         else {
-            this.client = getSanityClient({
+            this.client = getAilfSanityClient({
                 ...(options.dataset ? { dataset: options.dataset } : {}),
                 ...(options.projectId ? { projectId: options.projectId } : {}),
                 ...(options.token ? { token: options.token } : {}),
@@ -130,6 +131,9 @@ export class ReportStore {
             return doc ? toReport(doc) : null;
         }
         catch (error) {
+            // W0191: schema-validation errors are bugs, not outages — surface them.
+            if (error instanceof ReportSchemaValidationError)
+                throw error;
             console.warn(`  ⚠️  Failed to query cached report by fingerprint: ${error instanceof Error ? error.message : String(error)}`);
             return null;
         }
@@ -166,12 +170,18 @@ export class ReportStore {
             return doc ? toReport(doc) : null;
         }
         catch (error) {
+            // W0191: schema-validation errors are bugs, not outages — surface them.
+            if (error instanceof ReportSchemaValidationError)
+                throw error;
             console.warn(`  ⚠️  Failed to query comparable baseline: ${error instanceof Error ? error.message : String(error)}`);
             return null;
         }
     }
     /**
      * Read a report by its ID.
+     *
+     * @throws {ReportSchemaValidationError} if the stored document fails the
+     *   W0191 runtime schema gate. Sanity API failures still return null.
      */
     async read(id) {
         try {
@@ -179,6 +189,9 @@ export class ReportStore {
             return doc ? toReport(doc) : null;
         }
         catch (error) {
+            // W0191: schema-validation errors are bugs, not outages — surface them.
+            if (error instanceof ReportSchemaValidationError)
+                throw error;
             console.warn(`  ⚠️  Failed to read report from Sanity: ${error instanceof Error ? error.message : String(error)}`);
             return null;
         }
@@ -189,36 +202,30 @@ export class ReportStore {
      * 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)
+     * @returns The report ID on success, null on Sanity API failure (logged,
+     *   not thrown — P5 local-first).
+     * @throws {ReportSchemaValidationError} if the report fails the W0191
+     *   runtime schema gate. Schema drift is a bug, not an outage.
      */
     async write(report) {
+        // W0191 runtime gate — parse the wire payload before sending it to the
+        // Content Lake so producer-side drift surfaces here rather than as
+        // silent undefined-propagation in Studio. Mirrors the W0073 gate in
+        // ContentLakeTaskSource. ZodErrors throw; network/auth failures
+        // continue to use the P5 log-and-continue path below.
+        //
+        // The schema validates the wire shape (top-level `id`, not Sanity's
+        // `_id`/`reportId`), so we hand it the SanityReportDoc with `id` added.
+        // ReportSchema is `.passthrough()` at the top level — the Sanity-only
+        // fields (`_id`, `_type`, `reportId`) ride through harmlessly.
+        const sanityDoc = toSanityReportDoc(report);
+        const parsed = ReportSchema.safeParse({ ...sanityDoc, id: report.id });
+        if (!parsed.success) {
+            throw new ReportSchemaValidationError(`ReportStore.write: ailf.report "${report.id}" failed schema validation:\n` +
+                formatReportZodIssues(parsed.error));
+        }
         try {
-            // Strip baseline and experiment ScoreSummary objects from comparison
-            // before persisting — they duplicate report.summary (experiment) and
-            // are fetchable by ID via provenance.lineage.comparedAgainst (baseline).
-            // This reduces document size by ~50-65% for full-mode reports.
-            const comparison = report.comparison
-                ? stripComparisonBulk(report.comparison)
-                : null;
-            await this.client.create({
-                _id: `report-${report.id}`,
-                _type: REPORT_TYPE,
-                comparison,
-                completedAt: report.completedAt,
-                durationMs: report.durationMs,
-                provenance: report.provenance,
-                reportId: report.id,
-                summary: {
-                    ...report.summary,
-                    // Artifact references live inside summary in Sanity so they're
-                    // projected automatically by the reportDetailQuery (D0032)
-                    ...(report.artifactManifest
-                        ? { artifactManifest: report.artifactManifest }
-                        : {}),
-                },
-                tag: report.tag ?? null,
-                title: report.title ?? null,
-            });
+            await this.client.create(sanityDoc);
             return report.id;
         }
         catch (error) {
@@ -279,13 +286,71 @@ export function generateReportId() {
 // ---------------------------------------------------------------------------
 // Sanity document → Report mapping
 // ---------------------------------------------------------------------------
+/**
+ * Tagged error thrown by `toReport` and `ReportStore.write` when a Content
+ * Lake document fails the W0191 runtime schema gate. Read paths
+ * (`read`, `findByFingerprint`, `findComparableBaseline`) re-throw this
+ * error rather than swallowing it via the P5 log-and-continue try/catch
+ * — schema drift is a bug to be surfaced, not an outage to be tolerated.
+ */
+export class ReportSchemaValidationError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "ReportSchemaValidationError";
+    }
+}
+export function toSanityReportDoc(report) {
+    const comparison = report.comparison
+        ? stripComparisonBulk(report.comparison)
+        : null;
+    return {
+        _id: `report-${report.id}`,
+        _type: REPORT_TYPE,
+        comparison,
+        completedAt: report.completedAt,
+        durationMs: report.durationMs,
+        provenance: report.provenance,
+        reportId: report.id,
+        summary: {
+            ...report.summary,
+            // Artifact references live inside summary in Sanity so they're
+            // projected automatically by the reportDetailQuery (D0032)
+            ...(report.artifactManifest
+                ? { artifactManifest: report.artifactManifest }
+                : {}),
+        },
+        tag: report.tag ?? null,
+        title: report.title ?? null,
+    };
+}
 /**
  * Convert a raw Sanity document to a typed Report.
  *
  * The Sanity document shape mirrors the Report type but includes Sanity
  * metadata (_id, _type, _rev, etc.) that we strip.
  */
-function toReport(doc) {
+export function toReport(doc) {
+    // W0191 runtime gate — parse the raw Sanity document before constructing
+    // the typed Report. The schema has `id` at the top level (matching the
+    // wire shape used on write); the stored document carries the same value
+    // under `reportId`, so build the parse candidate from `reportId` and
+    // surface the document `_id` (or `reportId`) on parse failures so
+    // operators can locate the malformed record.
+    const reportIdRaw = doc.reportId;
+    const candidate = {
+        ...doc,
+        id: reportIdRaw,
+    };
+    const parsed = ReportSchema.safeParse(candidate);
+    if (!parsed.success) {
+        const docKey = typeof doc._id === "string" && doc._id.length > 0
+            ? doc._id
+            : typeof reportIdRaw === "string" && reportIdRaw.length > 0
+                ? reportIdRaw
+                : "<unknown>";
+        throw new ReportSchemaValidationError(`ReportStore.toReport: ailf.report "${docKey}" failed schema ` +
+            `validation:\n${formatReportZodIssues(parsed.error)}`);
+    }
     const summary = doc.summary;
     const artifactManifest = summary?.artifactManifest;
     return {
@@ -300,6 +365,21 @@ function toReport(doc) {
         title: doc.title,
     };
 }
+/**
+ * Format the first 5 ZodError issues for human-readable error output.
+ * Mirrors the W0073 ContentLakeTaskSource formatter so the two Content
+ * Lake gates produce comparable error shapes.
+ */
+function formatReportZodIssues(error) {
+    const issues = error.issues
+        .slice(0, 5)
+        .map((i) => `  [${i.path.join(".")}]: ${i.message}`)
+        .join("\n");
+    const more = error.issues.length > 5
+        ? `\n  …and ${error.issues.length - 5} more issue(s)`
+        : "";
+    return `${issues}${more}`;
+}
 /**
  * Remove the `baseline` and `experiment` ScoreSummary objects from a
  * ComparisonReport, producing a slim copy suitable for persistence.
@@ -310,7 +390,7 @@ function toReport(doc) {
  *
  * Everything else (deltas, areas, classifications) is preserved.
  */
-function stripComparisonBulk(comparison) {
+export function stripComparisonBulk(comparison) {
     const { baseline: _, experiment: __, ...slim } = comparison;
     return slim;
 }

package/dist/sanity/client.d.ts

@@ -36,3 +36,61 @@ export declare function createPublishedClient(source?: ResolvedSourceConfig): Sa
  * passed as a stacked array: [perspectiveId, "published"].
  */
 export declare function getSanityClient(overrides?: Partial<SanityConfig>, source?: ResolvedSourceConfig): SanityClient;
+/**
+ * Get a Sanity client targeting the AILF private dataset.
+ *
+ * Use this for reads and writes against `ailf.*` document types. The
+ * returned client is cached when called without overrides.
+ *
+ * @param overrides - Per-call config overrides (e.g., explicit token, dataset).
+ */
+export declare function getAilfSanityClient(overrides?: Partial<SanityConfig>): SanityClient;
+/**
+ * Reset the cached AILF client. Test-only — call from `beforeEach` when
+ * mutating env vars between tests so the cached client doesn't leak.
+ */
+export declare function resetAilfSanityClientCache(): void;
+/**
+ * The write shape for a Cross Dataset Reference. Sanity's Mutation API
+ * requires `_projectId` even when the target dataset lives in the same
+ * project (spike Finding 13). `_weak: true` keeps the AILF source doc
+ * publishable when the editorial target is retired (Finding 16).
+ *
+ * The literal `_type: "crossDatasetReference"` matches the receiving
+ * Studio schema field type and the validated migration script
+ * (`packages/studio/scripts/poc-migrate-to-private.ts`).
+ *
+ * @see docs/decisions/D0043-private-dataset-with-cdrs.md
+ */
+export interface EditorialReference {
+    _type: "crossDatasetReference";
+    _projectId: string;
+    _dataset: string;
+    _ref: string;
+    _weak?: boolean;
+}
+export interface BuildEditorialReferenceOptions {
+    /** Override the editorial-side project ID. Defaults to AILF project. */
+    projectId?: string;
+    /** Override the editorial dataset. Defaults to `AILF_EDITORIAL_DATASET`. */
+    dataset?: string;
+    /**
+     * Mark the reference as weak. Strongly recommended for any AILF→editorial
+     * link — keeps the AILF doc publishable when the target is deleted.
+     * Defaults to `true`.
+     */
+    weak?: boolean;
+}
+/**
+ * Build a Cross Dataset Reference from an AILF document into editorial content.
+ *
+ * Use this for any reference field on an `ailf.*` document that points at an
+ * editorial type (`article`, `docPage`, …). The schema-side counterpart is a
+ * `crossDatasetReference` field with matching `dataset` and `weak: true`.
+ *
+ * @example
+ *   const docRef = buildEditorialReference(articleId)
+ *   // → { _type: "reference", _projectId: "3do82whm",
+ *   //     _dataset: "next", _ref: articleId, _weak: true }
+ */
+export declare function buildEditorialReference(refId: string, options?: BuildEditorialReferenceOptions): EditorialReference;

package/dist/sanity/client.js

@@ -1,4 +1,14 @@
 import { createClient } from "@sanity/client";
+// Transitional default for AILF operational documents while D0043 rollout
+// is in progress. Code paths route through `getAilfSanityClient()` so the
+// default flip to `ailf-prod-private` is a single-line change after the
+// migration script (D0043 rollout step 5) ships and runs. Until then the
+// default mirrors the editorial dataset to avoid silent dual-write across
+// the cutover boundary.
+const AILF_DATASET_DEFAULT = "next";
+// Default editorial dataset that AILF cross-dataset references point at.
+// Used by `buildEditorialReference()` and by Studio's CDR field config.
+const EDITORIAL_DATASET_DEFAULT = "next";
 /**
  * Build the default Sanity client config by reading process.env at call time.
  *
@@ -84,3 +94,99 @@ export function getSanityClient(overrides, source) {
     _client = createClient(config);
     return _client;
 }
+// ---------------------------------------------------------------------------
+// AILF private-dataset client (D0043)
+// ---------------------------------------------------------------------------
+/**
+ * Build the default config for clients that read/write AILF documents
+ * (ailf.report, ailf.task, ailf.job, ailf.featureArea, ailf.evalRequest).
+ *
+ * Dataset precedence: explicit `AILF_REPORT_DATASET` overrides; otherwise
+ * fall back to `SANITY_DATASET` so existing CI workflows that pin a
+ * test/staging dataset (e.g. Tier 2 with `SANITY_DATASET=ailf-test`)
+ * continue to work without a new env var. The hard-coded fallback is
+ * the editorial dataset name during the D0043 cutover window — the flip
+ * to `ailf-prod-private` happens after the migration script runs.
+ *
+ * Token resolution prefers the AILF-scoped token, falling back to
+ * the shared `SANITY_API_TOKEN`.
+ */
+function getAilfDefaultConfig() {
+    return {
+        apiVersion: new Date().toISOString().split("T")[0],
+        dataset: 
+        // oxlint-disable-next-line @typescript-eslint/prefer-nullish-coalescing -- empty string env var should fall back
+        process.env.AILF_REPORT_DATASET ||
+            // oxlint-disable-next-line @typescript-eslint/prefer-nullish-coalescing -- empty string env var should fall back
+            process.env.SANITY_DATASET ||
+            AILF_DATASET_DEFAULT,
+        projectId: 
+        // oxlint-disable-next-line @typescript-eslint/prefer-nullish-coalescing -- empty string env var should fall back
+        process.env.AILF_REPORT_PROJECT_ID ||
+            // oxlint-disable-next-line @typescript-eslint/prefer-nullish-coalescing -- empty string env var should fall back
+            process.env.SANITY_PROJECT_ID ||
+            "3do82whm",
+        token: process.env.AILF_REPORT_SANITY_API_TOKEN ?? process.env.SANITY_API_TOKEN,
+        useCdn: false,
+    };
+}
+let _ailfClient = null;
+/**
+ * Get a Sanity client targeting the AILF private dataset.
+ *
+ * Use this for reads and writes against `ailf.*` document types. The
+ * returned client is cached when called without overrides.
+ *
+ * @param overrides - Per-call config overrides (e.g., explicit token, dataset).
+ */
+export function getAilfSanityClient(overrides) {
+    if (_ailfClient && !overrides) {
+        return _ailfClient;
+    }
+    const config = { ...getAilfDefaultConfig(), ...overrides };
+    const client = createClient(config);
+    if (!overrides)
+        _ailfClient = client;
+    return client;
+}
+/**
+ * Reset the cached AILF client. Test-only — call from `beforeEach` when
+ * mutating env vars between tests so the cached client doesn't leak.
+ */
+export function resetAilfSanityClientCache() {
+    _ailfClient = null;
+}
+/**
+ * Build a Cross Dataset Reference from an AILF document into editorial content.
+ *
+ * Use this for any reference field on an `ailf.*` document that points at an
+ * editorial type (`article`, `docPage`, …). The schema-side counterpart is a
+ * `crossDatasetReference` field with matching `dataset` and `weak: true`.
+ *
+ * @example
+ *   const docRef = buildEditorialReference(articleId)
+ *   // → { _type: "reference", _projectId: "3do82whm",
+ *   //     _dataset: "next", _ref: articleId, _weak: true }
+ */
+export function buildEditorialReference(refId, options = {}) {
+    if (!refId) {
+        throw new Error("buildEditorialReference: refId is required");
+    }
+    // oxlint-disable-next-line @typescript-eslint/prefer-nullish-coalescing -- empty string env var should fall back
+    const envProjectId = process.env.AILF_REPORT_PROJECT_ID || process.env.SANITY_PROJECT_ID;
+    // Editorial dataset precedence: explicit AILF_EDITORIAL_DATASET overrides;
+    // otherwise reuse SANITY_DATASET (which CI workflows already pin to the
+    // correct editorial dataset); fall back to "next" only when nothing is set.
+    // oxlint-disable-next-line @typescript-eslint/prefer-nullish-coalescing -- empty string env var should fall back
+    const envDataset = process.env.AILF_EDITORIAL_DATASET || process.env.SANITY_DATASET;
+    const projectId = options.projectId ?? envProjectId ?? "3do82whm";
+    const dataset = options.dataset ?? envDataset ?? EDITORIAL_DATASET_DEFAULT;
+    const weak = options.weak ?? true;
+    return {
+        _type: "crossDatasetReference",
+        _projectId: projectId,
+        _dataset: dataset,
+        _ref: refId,
+        ...(weak ? { _weak: true } : {}),
+    };
+}

package/dist/sanity/document-renderers.d.ts

@@ -0,0 +1,68 @@
+/**
+ * document-renderers.ts
+ *
+ * Renderer registry that turns a Sanity document fetched by `_id` into
+ * Markdown for inclusion in a literacy task's grader context.
+ *
+ * The resolver fetches docs without an `_type` filter and dispatches here.
+ * Two tiers of fidelity:
+ *
+ *   1. Registered renderers (high fidelity) — `article`, `typesReference`.
+ *      Hand-written for the document shapes we care about most.
+ *   2. Default renderer (best effort) — walks the doc, flattens portable-text
+ *      fields, surfaces top-level scalars, follows references one level deep,
+ *      skips framework-internal fields. Lets pinning a `marketingPage`,
+ *      `glossaryEntry`, etc. work without AILF code changes.
+ *
+ * Adding a new high-fidelity renderer: implement a `DocumentRenderer` and
+ * register it in `BUILT_IN_RENDERERS` keyed by `_type`.
+ */
+/**
+ * A Sanity document plus any references we've already resolved for it.
+ * The resolver fetches the doc once and may include common deref payloads
+ * (e.g. `latestVersion->{...}` for typesReference) so renderers don't need
+ * to issue additional client.fetch calls themselves.
+ */
+export interface DocumentForRender {
+    _id: string;
+    _type: string;
+    [key: string]: unknown;
+}
+export interface RenderContext {
+    /**
+     * Async URL fetcher for renderers that need to follow `sanity.fileAsset`
+     * URLs (e.g. typedoc JSON for `typesReference` docs). Returns the raw
+     * body text or `null` on failure.
+     */
+    fetchUrl?: (url: string) => Promise<string | null>;
+    /**
+     * Soft cap on rendered content length, in bytes. Renderers should respect
+     * this and append a truncation notice rather than blow up grader context.
+     */
+    maxBytes?: number;
+}
+export interface RenderResult {
+    /** The rendered Markdown. Empty string is permitted but produces a warn. */
+    content: string;
+    /**
+     * The fidelity tier used. Resolvers can log differently based on this:
+     *   - "high"    — a registered renderer ran
+     *   - "default" — fell through to the generic walker (info log)
+     */
+    fidelity: "high" | "default";
+    /**
+     * Stable display slug for this document. Articles use `slug.current`;
+     * other types fall back to a `<_type>:<_id>` form when no slug exists.
+     * Surfaces in `DocContext.slugs` for retrieval-metric attribution.
+     */
+    slug: string;
+}
+export type DocumentRenderer = (doc: DocumentForRender, ctx: RenderContext) => Promise<RenderResult> | RenderResult;
+/**
+ * Render a document using the registered renderer for its `_type`, falling
+ * back to the default walker. The returned `fidelity` flag tells callers
+ * whether to emit the "info: dedicated renderer would help" log.
+ */
+export declare function renderDocument(doc: DocumentForRender, ctx?: RenderContext): Promise<RenderResult>;
+/** Exported for tests and consumers that want the registered set. */
+export declare const REGISTERED_RENDERER_TYPES: string[];