@sanity/ailf 6.0.0 → 6.1.1

package/dist/commands/pipeline-action.js

@@ -20,9 +20,13 @@ import { buildAppContext, parseArtifactUploadEnv, } from "../orchestration/build
 import { buildStepSequence } from "../orchestration/build-step-sequence.js";
 import { orchestratePipeline } from "../orchestration/pipeline-orchestrator.js";
 import { load } from "js-yaml";
-import { PLACEHOLDER_OWNER_TEAM } from "../_vendor/ailf-core/index.js";
+import { PLACEHOLDER_OWNER_TEAM, } from "../_vendor/ailf-core/index.js";
 import { parseRepoConfig, } from "../adapters/task-sources/repo-schemas.js";
 import { getCallerCwd, resolveOutputDir } from "./shared/resolve-output-dir.js";
+// Phase 6 / DIAG-06 — single formatter, single visual contract (D6-04).
+// Import statically so bundlers and type-checkers can verify the export
+// exists at build time rather than deferring to runtime dynamic import.
+import { formatCardSummaryLine } from "./interpret.js";
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const ROOT = resolve(__dirname, "..", "..");
 // ---------------------------------------------------------------------------
@@ -250,6 +254,10 @@ export function computeResolvedOptions(opts) {
     const graderReplications = repoConfig?.execution?.graderReplications;
     const borderlineReplications = repoConfig?.execution?.borderlineReplications;
     const gapAnalysisEnabled = repoConfig?.execution?.gapAnalysis ?? true;
+    // Phase 6 / DIAG-06 — post-run diagnosis summary policy from .ailf/config.yaml.
+    // Precedence resolution (CLI flag > env > config > auto) lives in
+    // shouldRunPostSummary(); this only carries the config-file signal.
+    const summaryOnRun = repoConfig?.summary?.onRun;
     // Grader context policy. Cascade: env var > .ailf/config.yaml > unset
     // (defaults to rubric-only at the EvalConfig boundary). The env var is the
     // operational lever for one-shot comparison runs without editing the config file.
@@ -348,6 +356,7 @@ export function computeResolvedOptions(opts) {
             undefined,
         purposeOption: opts.purpose?.trim() || undefined,
         labelOptions: opts.label ?? [],
+        summaryOnRun,
     };
 }
 const PUBLISH_AUTO_VALUES = ["always", "full-runs", "never"];
@@ -373,6 +382,179 @@ function resolvePublishAuto(repoValue) {
     }
     return "full-runs";
 }
+// ---------------------------------------------------------------------------
+// Phase 6 / DIAG-06 — post-run diagnosis summary helpers
+// ---------------------------------------------------------------------------
+/**
+ * Determine whether the post-run diagnosis summary hook should fire.
+ *
+ * 4-level precedence chain (D6-20):
+ *   Level 1 — CLI flag (absolute): if `cliOpts.summary` is boolean, use it.
+ *   Level 2 — AILF_INTERPRET_ON_RUN env var (absolute): strict "1"/"0" parse;
+ *             anything else falls through (T-06-11 spoofing mitigation).
+ *   Level 3 — config `summary.onRun` (absolute): "always" → true; "never" → false;
+ *             "auto" or absent falls through to level 4.
+ *   Level 4 — default auto: TTY && !CI (SC1 default-off in CI).
+ */
+export function shouldRunPostSummary(cliOpts, resolvedOnRun) {
+    // Level 1: CLI flag wins absolutely
+    if (cliOpts.summary === true)
+        return true;
+    if (cliOpts.summary === false)
+        return false;
+    // Level 2: AILF_INTERPRET_ON_RUN env var (strict parse)
+    const envVal = process.env.AILF_INTERPRET_ON_RUN;
+    if (envVal === "1")
+        return true;
+    if (envVal === "0")
+        return false;
+    // Anything else (garbage, unset) falls through
+    // Level 3: config summary.onRun
+    if (resolvedOnRun === "always")
+        return true;
+    if (resolvedOnRun === "never")
+        return false;
+    // "auto" or undefined falls through
+    // Level 4: default auto — fire only when stdout is interactive and not in CI
+    return Boolean(process.stdout.isTTY) && process.env.CI !== "true";
+}
+/**
+ * Build a SynthesisCostTelemetry payload from a completed Diagnosis.
+ *
+ * Aggregates:
+ *   - cost: sum of meta.cost across all cards (undefined treated as 0)
+ *   - parseFailureCount: cards where status==="degraded" (parse failures)
+ *   - parseFailureRate: parseFailureCount / total-cards (max 8 per D6-09)
+ *   - perCard: per-card row with safe-extracted structured metadata
+ *
+ * Deliberately does NOT read card.body — only structured meta fields are
+ * persisted (T-06-14 PII guard per threat model).
+ */
+// D6-09: denominator is always the fixed card-registry size, not cards.length.
+// Using cards.length would allow parseFailureRate > 1.0 when the registry is
+// a subset (e.g. test registries), violating the SynthesisCostTelemetrySchema
+// min(0).max(1) constraint. Single edit point if the registry ever grows.
+const CARD_REGISTRY_SIZE = 8;
+export function buildSynthesisTelemetry(diagnosis) {
+    const cards = diagnosis.cards;
+    let totalCost = 0;
+    let parseFailureCount = 0;
+    const perCard = cards.map((card) => {
+        // "missing" cards have no `meta` — narrow with status guard
+        const meta = card.status !== "missing" ? card.meta : undefined;
+        const cost = meta?.cost ?? 0;
+        totalCost += cost;
+        // Parse failures produce status="degraded" (not "missing") in the current
+        // runner (diagnosis-runner.ts). A "missing" card is absence, not failure.
+        // If a future code path can produce status="missing" from a parse failure,
+        // this line must be updated and the parseFailed contract re-evaluated.
+        const parseFailed = card.status === "degraded";
+        if (parseFailed)
+            parseFailureCount++;
+        const row = {
+            cardType: card.cardType,
+            parseFailed,
+            cardVersion: meta?.cardVersion ?? "unknown",
+            generatedAt: meta?.generatedAt ?? new Date().toISOString(),
+        };
+        if (cost > 0)
+            row.cost = cost;
+        if (meta?.latencyMs !== undefined)
+            row.latencyMs = meta.latencyMs;
+        if (meta?.tokenUsage?.input !== undefined)
+            row.tokenInput = meta.tokenUsage.input;
+        if (meta?.tokenUsage?.output !== undefined)
+            row.tokenOutput = meta.tokenUsage.output;
+        return row;
+    });
+    return {
+        cost: totalCost,
+        parseFailureCount,
+        parseFailureRate: parseFailureCount / CARD_REGISTRY_SIZE,
+        perCard,
+    };
+}
+/**
+ * Run post-pipeline hooks after the pipeline completes.
+ *
+ * Fires after orchestratePipeline() + writePipelineResult() (D6-02).
+ * Hook failure prints to stderr but does NOT change exit code (D6-03).
+ * CI default-off: fires only when shouldRunPostSummary returns true (D6-20).
+ *
+ * @param ctx - App context (composition root wiring)
+ * @param result - Pipeline result (includes reportId when published)
+ * @param args - Hook options (cliOpts, summaryOnRun from config, optional runnerFactory for tests)
+ */
+export async function runPostPipelineHooks(ctx, result, args) {
+    if (!shouldRunPostSummary(args.cliOpts, args.summaryOnRun))
+        return;
+    if (!result.reportId) {
+        process.stderr.write("ℹ️ No report published — skipping post-summary.\n");
+        return;
+    }
+    const reportId = result.reportId;
+    try {
+        // Build the runner — use injected factory (tests) or composition root (production)
+        let runner;
+        if (args.runnerFactory) {
+            runner = args.runnerFactory(ctx);
+        }
+        else {
+            const { getDiagnosisRunner } = await import("../composition-root.js");
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            runner = getDiagnosisRunner(ctx);
+        }
+        // Read the stored report — needed by the runner for version metadata
+        const report = await ctx.reportStore?.read(reportId);
+        if (!report) {
+            process.stderr.write(`ℹ️ Report not found: ${reportId} — skipping post-summary.\n`);
+            return;
+        }
+        // Derive version metadata from the stored report (same approach as interpret.ts)
+        const rec = report;
+        const summary = rec.summary;
+        const versions = summary?.versions;
+        const versionedInputs = {
+            graderJudgmentsVersion: typeof versions?.graderJudgmentsVersion === "string"
+                ? versions.graderJudgmentsVersion
+                : "unknown",
+            ensembleVersion: typeof versions?.ensembleVersion === "string"
+                ? versions.ensembleVersion
+                : "unknown",
+            diagnosisVersion: typeof versions?.diagnosisVersion === "string"
+                ? versions.diagnosisVersion
+                : "unknown",
+            cardVersion: typeof versions?.cardVersion === "string"
+                ? versions.cardVersion
+                : "unknown",
+        };
+        // Run the diagnosis
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const diagnosis = await runner.run({
+            report: report,
+            versions: versionedInputs,
+            refresh: false,
+        });
+        // Print per-card summary lines to stdout (D6-04 single formatter)
+        for (const card of diagnosis.cards) {
+            process.stdout.write(`${formatCardSummaryLine(card)}\n`);
+        }
+        // Build and write synthesis telemetry back to the report doc (D6-08)
+        // patchSynthesis is now part of ReportStorePort (CR-01) — guard on store
+        // presence only; absent store means no report store is configured (expected).
+        if (ctx.reportStore) {
+            const telemetry = buildSynthesisTelemetry(diagnosis);
+            await ctx.reportStore.patchSynthesis(reportId, telemetry);
+        }
+        else {
+            process.stderr.write("ℹ️ No reportStore configured — synthesis telemetry not written to Sanity.\n");
+        }
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        process.stderr.write(`⚠️ Diagnosis failed: ${msg}. Run \`ailf interpret ${reportId}\` to retry.\n`);
+    }
+}
 /** Resolve and validate the --task-source flag value. */
 function resolveTaskSourceType(raw) {
     if (!raw || raw === "content-lake")
@@ -471,6 +653,11 @@ export async function executePipeline(cliOpts) {
         const steps = buildStepSequence(ctx, pipelineStart);
         const result = await orchestratePipeline(ctx, steps);
         writePipelineResult(result, config.outputDir);
+        // Phase 6 / DIAG-06: post-run hook fires after artifacts are written (D6-02)
+        await runPostPipelineHooks(ctx, result, {
+            cliOpts,
+            summaryOnRun: config.summaryOnRun,
+        });
         process.exit(result.success ? 0 : 1);
     }
     const o = resolveOptions(cliOpts);
@@ -510,6 +697,11 @@ export async function executePipeline(cliOpts) {
     const steps = buildStepSequence(ctx, pipelineStart);
     const result = await orchestratePipeline(ctx, steps);
     writePipelineResult(result, o.outputDir);
+    // Phase 6 / DIAG-06: post-run hook fires after artifacts are written (D6-02)
+    await runPostPipelineHooks(ctx, result, {
+        cliOpts,
+        summaryOnRun: o.summaryOnRun,
+    });
     process.exit(result.success ? 0 : 1);
 }
 // ---------------------------------------------------------------------------

package/dist/commands/run.d.ts

@@ -47,6 +47,8 @@ export interface PipelineCliOptions {
     publish?: boolean;
     publishTag?: string;
     remoteCache?: boolean;
+    /** Phase 6 / DIAG-06: post-run diagnosis summary toggle. Undefined when neither flag is passed. */
+    summary?: boolean;
     sanityDocument: string[];
     sanityPerspective?: string;
     search?: string;

package/dist/commands/run.js

@@ -43,6 +43,8 @@ export function createRunCommand() {
         .option("-p, --publish", "Write report to Sanity + fan out to sinks (auto-enabled for full runs when report store is configured)")
         .option("--no-publish", "Suppress auto-publishing")
         .option("--publish-tag <tag>", "Label for published report")
+        .option("--summary", "Force post-run diagnosis summary (overrides config and CI default-off)")
+        .option("--no-summary", "Suppress post-run diagnosis summary")
         .option("--config <path>", "Load pipeline config from a TS/JS/YAML/JSON file (overrides most CLI flags)")
         .option("-o, --output <path>", "Write PR comment markdown to file")
         .option("--promptfoo-url <url>", "Promptfoo share URL for report")

package/dist/composition-root.d.ts

@@ -15,7 +15,7 @@
  * @see packages/core/src/ports/context.ts — AppContext interface
  * @see docs/archive/exec-plans/ports-and-adapters/phase-7-composition-root.md
  */
-import { type AppContext, type ArtifactWriter, type ArtifactWriterProgressOptions, type AssertionRegistration, type CardRegistry, type DiagnosisRunner, type Logger, type ResolvedConfig } from "./_vendor/ailf-core/index.d.ts";
+import { type AppContext, type ArtifactWriter, type ArtifactWriterProgressOptions, type AssertionRegistration, type CardRegistry, type DiagnosisRunner, type Logger, type ResolvedConfig, type WriteSource } from "./_vendor/ailf-core/index.d.ts";
 export type { LLMClientKeys } from "./_vendor/ailf-core/index.d.ts";
 import { type BorderlineConsensusOptions, type BorderlineConsensusResult } from "./pipeline/borderline-consensus-runner.js";
 import { CompositeTaskSource, ContentLakeTaskSource, RepoTaskSource } from "./adapters/task-sources/index.js";
@@ -44,7 +44,7 @@ export declare function createAppContext(config: ResolvedConfig): AppContext;
  *
  * Exported for unit-test access; not part of the public package API.
  */
-export declare function createArtifactWriter(config: ResolvedConfig, logger: Logger, progress?: ArtifactWriterProgressOptions): ArtifactWriter;
+export declare function createArtifactWriter(config: ResolvedConfig, logger: Logger, progress?: ArtifactWriterProgressOptions, writerSource?: WriteSource): ArtifactWriter;
 /**
  * Build the `TaskSource` adapter wired by the composition root for a
  * given `ResolvedConfig`. Exported for test access — composition-root
@@ -110,10 +110,27 @@ export declare function buildDiagnosisRegistry(): CardRegistry;
  *
  * Wires the full 8-card registry, `loadAttributions` bound to the local
  * filesystem (Phase-4 per-entry attribution objects at
- * `{artifactsDir}/runs/{runId}/attribution/*.json`), and no-op cache
- * reader/writer (Plan-06 CLI command will wire the real cache seam).
+ * `{artifactsDir}/runs/{runId}/attribution/*.json`), and the real
+ * `diagnosisWriter` that emits the Diagnosis through a post-hoc-flagged
+ * artifact writer AND patches the report doc's
+ * `summary.artifactManifest.diagnosis` slot. Two steps because `ailf interpret`
+ * runs after the report doc has already been published — the pipeline path's
+ * publish-report-step.ts:187 lifts the in-memory run manifest into the doc at
+ * end-of-run, but that step never fires for a deferred command.
+ *
+ * The post-hoc writer is built with `writerSource: "post-hoc"` so the D0050
+ * guard accepts the diagnosis descriptor (`writePolicy: "post-hoc"`). Without
+ * this, every emit would be rejected at runtime.
+ *
+ * `diagnosisReader` is still a no-op shim: the Studio data path uses the
+ * artifact-manifest entry (populated by the writer + patch) plus a signed-URL
+ * fetch, so reader-side cache wiring is deferred to a follow-up W-item.
+ * Without the reader, `ailf interpret --refresh` cache hits are not yet served
+ * from GCS — they recompute.
  *
  * Plan-06 API/CLI consumers import this function from the composition root
  * and pass `ctx` from `createAppContext(config)`.
  */
-export declare function getDiagnosisRunner(ctx: AppContext): DiagnosisRunner;
+export declare function getDiagnosisRunner(ctx: AppContext, opts?: {
+    artifactWriter?: ArtifactWriter;
+}): DiagnosisRunner;

package/dist/composition-root.js

@@ -192,7 +192,7 @@ const DEFAULT_LOCAL_ARTIFACTS_DIR = ".ailf/results/captures";
  *
  * Exported for unit-test access; not part of the public package API.
  */
-export function createArtifactWriter(config, logger, progress) {
+export function createArtifactWriter(config, logger, progress, writerSource = "pipeline") {
     // Legacy `artifactUpload: false` still disables — treat as an alias for
     // the canonical `artifactsDisabled: true` until W0052 removes it.
     if (config.artifactsDisabled === true || config.artifactUpload === false) {
@@ -214,10 +214,11 @@ export function createArtifactWriter(config, logger, progress) {
     // W0053: progress attaches to the OUTERMOST of (local-only | fanout). When
     // fanout is wired, the delegates stay silent so we don't double-count the
     // same caller-visible write across two backends.
-    const remote = createRemoteArtifactWriter(config, logger, metrics);
+    const remote = createRemoteArtifactWriter(config, logger, metrics, writerSource);
     const local = new LocalFilesystemArtifactWriter({
         rootDir,
         exclude,
+        writerSource,
         ...(remote ? {} : { progress }),
     });
     // W0064 — when a remote backend is wired, list it first so its ArtifactRef
@@ -267,7 +268,7 @@ function resolveExcludeList(raw, logger) {
  * the sole backend for that run, which is the D0033 M4 default for laptops
  * and CI without GCS creds.
  */
-function createRemoteArtifactWriter(config, logger, metrics) {
+function createRemoteArtifactWriter(config, logger, metrics, writerSource = "pipeline") {
     const bucket = config.artifactGcsBucket ?? DEFAULT_ARTIFACT_BUCKET;
     const hasGcsCredentials = Boolean(process.env.GOOGLE_APPLICATION_CREDENTIALS || process.env.GCLOUD_PROJECT);
     if (hasGcsCredentials) {
@@ -279,6 +280,7 @@ function createRemoteArtifactWriter(config, logger, metrics) {
         logger.debug(`Artifact remote backend: GcsArtifactWriter (ADC, bucket=${bucket}, defaultConcurrency=8)`);
         return new GcsArtifactWriter({
             bucket,
+            writerSource,
             ...(metrics ? { metrics } : {}),
         });
     }
@@ -306,6 +308,7 @@ function createRemoteArtifactWriter(config, logger, metrics) {
                 apiKey: config.apiKey,
                 bucket,
                 putConcurrency: concurrency,
+                writerSource,
                 ...(metrics ? { metrics } : {}),
             });
         }
@@ -314,6 +317,7 @@ function createRemoteArtifactWriter(config, logger, metrics) {
             apiBaseUrl: config.apiUrl,
             apiKey: config.apiKey,
             bucket,
+            writerSource,
             ...(metrics ? { metrics } : {}),
         });
     }
@@ -585,17 +589,83 @@ async function loadAttributionsFromLocalFs(runId, artifactsDir, logger) {
  *
  * Wires the full 8-card registry, `loadAttributions` bound to the local
  * filesystem (Phase-4 per-entry attribution objects at
- * `{artifactsDir}/runs/{runId}/attribution/*.json`), and no-op cache
- * reader/writer (Plan-06 CLI command will wire the real cache seam).
+ * `{artifactsDir}/runs/{runId}/attribution/*.json`), and the real
+ * `diagnosisWriter` that emits the Diagnosis through a post-hoc-flagged
+ * artifact writer AND patches the report doc's
+ * `summary.artifactManifest.diagnosis` slot. Two steps because `ailf interpret`
+ * runs after the report doc has already been published — the pipeline path's
+ * publish-report-step.ts:187 lifts the in-memory run manifest into the doc at
+ * end-of-run, but that step never fires for a deferred command.
+ *
+ * The post-hoc writer is built with `writerSource: "post-hoc"` so the D0050
+ * guard accepts the diagnosis descriptor (`writePolicy: "post-hoc"`). Without
+ * this, every emit would be rejected at runtime.
+ *
+ * `diagnosisReader` is still a no-op shim: the Studio data path uses the
+ * artifact-manifest entry (populated by the writer + patch) plus a signed-URL
+ * fetch, so reader-side cache wiring is deferred to a follow-up W-item.
+ * Without the reader, `ailf interpret --refresh` cache hits are not yet served
+ * from GCS — they recompute.
  *
  * Plan-06 API/CLI consumers import this function from the composition root
  * and pass `ctx` from `createAppContext(config)`.
  */
-export function getDiagnosisRunner(ctx) {
+export function getDiagnosisRunner(ctx, opts) {
     const artifactsDir = ctx.config.artifactsDir ?? DIAGNOSIS_LOCAL_ARTIFACTS_DIR;
-    // No-op cache shims — Plan 06 wires the real cache.
+    // Post-hoc artifact writer — built with the same fanout/remote/local layering
+    // as the pipeline writer but flagged so the D0050 guard accepts post-hoc
+    // descriptors. Construction is per-runner so the AccumulatingArtifactWriter's
+    // internal manifest doesn't carry state between unrelated interpret runs.
+    // Tests inject their own writer via opts.artifactWriter; the production
+    // CLI / pipeline callers never pass it.
+    const postHocArtifactWriter = opts?.artifactWriter ??
+        createArtifactWriter(ctx.config, ctx.logger, undefined, "post-hoc");
+    // No-op reader — see JSDoc above. The Studio data path is manifest-driven,
+    // not reader-driven, so the writer + patch alone unblock Phase 7.
     const diagnosisReader = async (_path) => null;
-    const diagnosisWriter = async (_path, _diagnosis) => { };
+    // Real writer — two-step persistence:
+    //  1. Emit the diagnosis payload through the post-hoc writer; the descriptor's
+    //     `objectPath: diagnosisPathBuilder()` derives the storage path from
+    //     `{runId, reportId, compoundVersion}`.
+    //  2. Patch the published report doc's `summary.artifactManifest.diagnosis`
+    //     slot with the returned ArtifactRef, so Studio's slim-shape GROQ
+    //     projection surfaces the entry. (The pipeline path runs this lift via
+    //     publish-report-step.ts; that step never fires for a deferred command,
+    //     hence the explicit patch here.)
+    //
+    // Errors are caught and logged rather than thrown — the diagnosis runner
+    // separates "compute" from "persist". Failed persistence should not panic
+    // the runner; the computed cards still surface to API/CLI callers in-memory.
+    // ReportStore.patchArtifactManifest is itself non-fatal on Sanity failure,
+    // so it does not need its own try/catch.
+    const diagnosisWriter = async (_descriptorPath, diagnosis) => {
+        let ref;
+        try {
+            // Anchor the diagnosis to the REPORT's run, not the post-hoc CLI's
+            // session run. `ctx.runId` is freshly generated per interpret
+            // invocation; the report doc's `provenance.runId` is what Studio
+            // and the signing endpoint look up. Using `assoc(ctx, ...)` would
+            // bind `run` to ctx.runId — the path would be writeable but
+            // unreachable from the Studio side.
+            ref = await postHocArtifactWriter.emit("diagnosis", { run: diagnosis.runId, report: diagnosis.reportId }, diagnosis);
+        }
+        catch (error) {
+            ctx.logger.warn("diagnosis-emit-failed", {
+                reportId: diagnosis.reportId,
+                error: error instanceof Error ? error.message : String(error),
+            });
+            return;
+        }
+        if (!ref)
+            return;
+        if (!ctx.reportStore) {
+            ctx.logger.warn("diagnosis-emit: no reportStore on context", {
+                reportId: diagnosis.reportId,
+            });
+            return;
+        }
+        await ctx.reportStore.patchArtifactManifest(diagnosis.reportId, "diagnosis", ref);
+    };
     return createDiagnosisRunner({
         llm: ctx.llmClient,
         model: modelId("anthropic:claude-opus-4-6"),

package/dist/orchestration/pipeline-orchestrator.js

@@ -275,6 +275,9 @@ export async function orchestratePipeline(ctx, steps) {
         belowCritical: state.belowCritical,
         durationMs,
         promptfooUrls: state.promptfooUrls,
+        // Phase 6 / DIAG-06 — thread reportId from state so the post-run hook in
+        // pipeline-action.ts can target the published Content Lake document.
+        reportId: state.reportId,
         steps: results,
         success: true,
         testSummary: state.testSummary,

package/dist/orchestration/steps/gap-analysis-step.js

@@ -215,7 +215,6 @@ export class GapAnalysisStep {
                 ...(documentManifest !== undefined && { documentManifest }),
                 failureModes: failureModeReport,
                 lowScoringJudgments,
-                recommendations: gapReport,
                 scores: enrichedScores,
                 ...(testResults !== undefined && { testResults }),
             };

package/dist/report-store.d.ts

@@ -15,6 +15,7 @@
  * @see docs/design-docs/report-store/domain-model.md
  */
 import type { SanityClient } from "@sanity/client";
+import type { ArtifactRef, ArtifactType, SynthesisCostTelemetry } from "./_vendor/ailf-core/index.d.ts";
 import type { ComparisonReport, ISOTimestamp, LineageQuery, Report, ReportId, ReportProvenance, ScoreSummary } from "./pipeline/types.js";
 /**
  * Result of an auto-comparison, bundling the ComparisonReport with the
@@ -89,6 +90,22 @@ export declare class ReportStore {
      * @see docs/design-docs/report-store/architecture.md — Auto-comparison
      */
     findComparableBaseline(query: LineageQuery): Promise<null | Report>;
+    /**
+     * Fetch the most recent report from the Content Lake.
+     *
+     * Mirrors the API gateway's `ReportStoreApi.latest()` signature
+     * (`packages/api/src/lib/sanity.ts`). Used by `ailf interpret latest`
+     * when no explicit report ID is supplied.
+     *
+     * @param query Optional narrowing by `mode` and/or `source.name`.
+     * @returns The most recent matching report, or null if none exist
+     *   or on API failure. Schema-validation errors are advisory (logged
+     *   and null-returned) per the same rationale as `findByFingerprint`.
+     */
+    latest(query?: {
+        mode?: string;
+        source?: string;
+    }): Promise<null | Report>;
     /**
      * Read a report by its ID.
      *
@@ -108,6 +125,29 @@ export declare class ReportStore {
      *   runtime schema gate. Schema drift is a bug, not an outage.
      */
     write(report: Report): Promise<null | ReportId>;
+    /**
+     * Patch synthesis telemetry onto a published report (Phase 6 / DIAG-06).
+     * Non-fatal on Sanity failure — the on-disk reportSnapshot artifact
+     * remains the source of truth. Mirrors `write()` (L379–411) for
+     * error handling.
+     *
+     * Document _id is `report-${reportId}` (see `toSanityReportDoc` L559).
+     */
+    patchSynthesis(reportId: ReportId, telemetry: SynthesisCostTelemetry): Promise<void>;
+    /**
+     * Patch a single artifact-manifest entry onto a published report.
+     *
+     * Used by deferred commands like `ailf interpret` whose post-hoc writer
+     * produces a new ArtifactRef *after* the report doc was published. The
+     * pipeline path lifts the full manifest into the doc at publish time
+     * (publish-report-step.ts:187); this method is the post-hoc equivalent
+     * for a single slot.
+     *
+     * Non-fatal on Sanity failure — mirrors `patchSynthesis` (L423).
+     *
+     * Document _id is `report-${reportId}` (see `toSanityReportDoc` L559).
+     */
+    patchArtifactManifest(reportId: ReportId, slot: ArtifactType, ref: ArtifactRef): Promise<void>;
     /**
      * Query error arrays from the last N reports for chronic failure detection.
      *

package/dist/report-store.js

@@ -207,6 +207,50 @@ export class ReportStore {
             return null;
         }
     }
+    /**
+     * Fetch the most recent report from the Content Lake.
+     *
+     * Mirrors the API gateway's `ReportStoreApi.latest()` signature
+     * (`packages/api/src/lib/sanity.ts`). Used by `ailf interpret latest`
+     * when no explicit report ID is supplied.
+     *
+     * @param query Optional narrowing by `mode` and/or `source.name`.
+     * @returns The most recent matching report, or null if none exist
+     *   or on API failure. Schema-validation errors are advisory (logged
+     *   and null-returned) per the same rationale as `findByFingerprint`.
+     */
+    async latest(query) {
+        try {
+            let groq = `*[_type == $type`;
+            const params = { type: REPORT_TYPE };
+            if (query?.mode) {
+                groq += ` && provenance.mode == $mode`;
+                params.mode = query.mode;
+            }
+            if (query?.source) {
+                groq += ` && provenance.source.name == $source`;
+                params.source = query.source;
+            }
+            groq += `] | order(completedAt desc) [0]`;
+            const doc = await this.client.fetch(groq, params);
+            return doc ? toReport(doc) : null;
+        }
+        catch (error) {
+            // Advisory lookup — a malformed prior doc must not break a read-only
+            // CLI invocation. Log and return null so the caller surfaces a
+            // user-friendly "no report found" error instead of a Zod stack trace.
+            if (error instanceof ReportSchemaValidationError) {
+                logAdvisoryQuerySchemaFailure({
+                    query: "latest",
+                    context: { mode: query?.mode, sourceName: query?.source },
+                    error,
+                });
+                return null;
+            }
+            console.warn(`  ⚠️  Failed to fetch latest report from Sanity: ${error instanceof Error ? error.message : String(error)}`);
+            return null;
+        }
+    }
     /**
      * Read a report by its ID.
      *
@@ -264,6 +308,50 @@ export class ReportStore {
             return null;
         }
     }
+    /**
+     * Patch synthesis telemetry onto a published report (Phase 6 / DIAG-06).
+     * Non-fatal on Sanity failure — the on-disk reportSnapshot artifact
+     * remains the source of truth. Mirrors `write()` (L379–411) for
+     * error handling.
+     *
+     * Document _id is `report-${reportId}` (see `toSanityReportDoc` L559).
+     */
+    async patchSynthesis(reportId, telemetry) {
+        try {
+            await this.client
+                .patch(`report-${reportId}`)
+                .set({ "summary.synthesis": { diagnosis: telemetry } })
+                .commit();
+        }
+        catch (error) {
+            console.warn(`  ⚠️  Failed to patch synthesis telemetry on report ${reportId}: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    /**
+     * Patch a single artifact-manifest entry onto a published report.
+     *
+     * Used by deferred commands like `ailf interpret` whose post-hoc writer
+     * produces a new ArtifactRef *after* the report doc was published. The
+     * pipeline path lifts the full manifest into the doc at publish time
+     * (publish-report-step.ts:187); this method is the post-hoc equivalent
+     * for a single slot.
+     *
+     * Non-fatal on Sanity failure — mirrors `patchSynthesis` (L423).
+     *
+     * Document _id is `report-${reportId}` (see `toSanityReportDoc` L559).
+     */
+    async patchArtifactManifest(reportId, slot, ref) {
+        try {
+            await this.client
+                .patch(`report-${reportId}`)
+                .setIfMissing({ "summary.artifactManifest": {} })
+                .set({ [`summary.artifactManifest.${slot}`]: ref })
+                .commit();
+        }
+        catch (error) {
+            console.warn(`  ⚠️  Failed to patch artifactManifest.${slot} on report ${reportId}: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
     /**
      * Query error arrays from the last N reports for chronic failure detection.
      *

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sanity/ailf",
-  "version": "6.0.0",
+  "version": "6.1.1",
   "private": false,
   "publishConfig": {
     "access": "public"