@deftai/directive-core 0.98.1 → 0.99.0

package/dist/decision/write.d.ts

@@ -0,0 +1,82 @@
+/**
+ * decision:write — create a lightweight structured decision record (#1396).
+ */
+import { type DecisionRecord, slugifyDecision } from "./schema.js";
+export type DecisionWriteOutcome = "written" | "error-bad-args" | "error-config" | "error-io";
+export interface DecisionWriteInput {
+    readonly decision?: string;
+    readonly governingRule?: string | {
+        description: string;
+        path?: string;
+        rfc2119?: string;
+    };
+    readonly alternatives?: readonly (string | {
+        option: string;
+        whyNot?: string;
+    })[];
+    readonly whyWinner?: string;
+    readonly confidence?: string;
+    readonly scope?: string | readonly string[];
+    readonly revisitTrigger?: string;
+    readonly id?: string;
+    readonly timestamp?: string;
+    readonly tags?: readonly string[];
+    readonly relatedIssues?: readonly number[];
+    /** Absolute or project-relative path to a JSON body file (full or partial record). */
+    readonly bodyFile?: string;
+    /** Force standalone under xbrief/decisions/ even when --scope is set (still links). */
+    readonly standalone?: boolean;
+    /** When true, replace an existing decision file at the same path. Default: fail if exists. */
+    readonly force?: boolean;
+    readonly projectRoot?: string | null;
+    readonly dryRun?: boolean;
+    readonly json?: boolean;
+}
+export interface DecisionWriteResult {
+    readonly outcome: DecisionWriteOutcome;
+    readonly exitCode: 0 | 1 | 2;
+    readonly path: string | null;
+    readonly scopePath: string | null;
+    readonly record: DecisionRecord | null;
+    readonly message: string;
+}
+/**
+ * Append a pointer line to plan.narratives.Decisions on a scope xBRIEF without
+ * removing existing narratives (validators accept unknown narrative keys as strings).
+ *
+ * Concurrent writers: read-modify-replace with post-write verify + retry so a
+ * later attach does not silently drop an earlier decision pointer.
+ */
+export declare function appendScopeDecisionPointer(projectRoot: string, scopeRelPath: string, decisionRelPath: string, decisionSummary: string): void;
+/** Write a validated decision record to disk (standalone + optional scope pointer). */
+export declare function runDecisionWrite(options: DecisionWriteInput): DecisionWriteResult;
+export interface DecisionWriteCliArgs {
+    decision?: string;
+    governingRule?: string;
+    governingPath?: string;
+    governingRfc?: string;
+    alternatives?: string[];
+    whyWinner?: string;
+    confidence?: string;
+    scope?: string[];
+    revisitTrigger?: string;
+    id?: string;
+    timestamp?: string;
+    tags?: string[];
+    relatedIssues?: number[];
+    bodyFile?: string;
+    standalone?: boolean;
+    force?: boolean;
+    dryRun?: boolean;
+    json?: boolean;
+    projectRoot?: string;
+    error?: string;
+}
+/** Parse argv for decision:write. */
+export declare function parseDecisionWriteArgs(argv: readonly string[]): DecisionWriteCliArgs;
+/** CLI entry for decision:write. */
+export declare function decisionWriteMain(argv: readonly string[]): number;
+/** Relative path helper for tests. */
+export declare function relativeToProject(projectRoot: string, absPath: string): string;
+export { slugifyDecision };
+//# sourceMappingURL=write.d.ts.map

package/dist/decision/write.js

@@ -0,0 +1,427 @@
+/**
+ * decision:write — create a lightweight structured decision record (#1396).
+ */
+import { existsSync, mkdirSync, readFileSync } from "node:fs";
+import { dirname, join, relative, resolve } from "node:path";
+import { ContainedWriteError, containedWrite } from "../fs/contained-write.js";
+import { ProjectionContainmentError } from "../fs/projection-containment.js";
+import { resolveProjectRoot } from "../scope/project-context.js";
+import { DECISIONS_DIR_REL, decisionFilename, formatDecisionValidationErrors, normalizeTimestamp, slugifyDecision, validateDecisionRecord, } from "./schema.js";
+function loadBodyFile(bodyFile, projectRoot) {
+    const abs = resolve(bodyFile.startsWith(".") ? join(projectRoot, bodyFile) : bodyFile);
+    const text = readFileSync(abs, "utf8");
+    const parsed = JSON.parse(text);
+    if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+        throw new Error("body file must contain a JSON object");
+    }
+    return parsed;
+}
+function mergeInput(options, projectRoot) {
+    let base = {};
+    if (options.bodyFile !== undefined && options.bodyFile.trim().length > 0) {
+        base = loadBodyFile(options.bodyFile.trim(), projectRoot);
+    }
+    const out = { ...base };
+    if (options.decision !== undefined)
+        out.decision = options.decision;
+    if (options.governingRule !== undefined)
+        out.governingRule = options.governingRule;
+    if (options.alternatives !== undefined)
+        out.alternativesConsidered = options.alternatives;
+    if (options.whyWinner !== undefined)
+        out.whyWinner = options.whyWinner;
+    if (options.confidence !== undefined)
+        out.confidence = options.confidence;
+    if (options.revisitTrigger !== undefined)
+        out.revisitTrigger = options.revisitTrigger;
+    if (options.id !== undefined)
+        out.id = options.id;
+    if (options.timestamp !== undefined)
+        out.timestamp = options.timestamp;
+    if (options.tags !== undefined)
+        out.tags = options.tags;
+    if (options.relatedIssues !== undefined)
+        out.relatedIssues = options.relatedIssues;
+    if (options.scope !== undefined) {
+        const scopes = Array.isArray(options.scope) ? options.scope : [options.scope];
+        out.activeScopeRefs = scopes.map((s) => s.replace(/\\/g, "/"));
+    }
+    return out;
+}
+/**
+ * Append a pointer line to plan.narratives.Decisions on a scope xBRIEF without
+ * removing existing narratives (validators accept unknown narrative keys as strings).
+ *
+ * Concurrent writers: read-modify-replace with post-write verify + retry so a
+ * later attach does not silently drop an earlier decision pointer.
+ */
+export function appendScopeDecisionPointer(projectRoot, scopeRelPath, decisionRelPath, decisionSummary) {
+    const scopeAbs = resolve(projectRoot, scopeRelPath);
+    if (!existsSync(scopeAbs)) {
+        throw new Error(`scope xBRIEF not found: ${scopeRelPath}`);
+    }
+    const pointerNeedle = decisionRelPath;
+    const maxAttempts = 4;
+    for (let attempt = 0; attempt < maxAttempts; attempt += 1) {
+        const raw = readFileSync(scopeAbs, "utf8");
+        const doc = JSON.parse(raw);
+        if (doc === null || typeof doc !== "object" || Array.isArray(doc)) {
+            throw new Error(`invalid scope xBRIEF JSON: ${scopeRelPath}`);
+        }
+        const plan = doc.plan;
+        if (plan === null || typeof plan !== "object" || Array.isArray(plan)) {
+            throw new Error(`scope xBRIEF missing plan: ${scopeRelPath}`);
+        }
+        const narrativesRaw = plan.narratives;
+        const narratives = narrativesRaw !== null && typeof narrativesRaw === "object" && !Array.isArray(narrativesRaw)
+            ? { ...narrativesRaw }
+            : {};
+        const pointer = `- ${decisionRelPath} — ${decisionSummary}`;
+        const existing = typeof narratives.Decisions === "string" ? narratives.Decisions.trim() : "";
+        if (existing.includes(pointerNeedle)) {
+            return;
+        }
+        narratives.Decisions = existing.length > 0 ? `${existing}\n${pointer}` : pointer;
+        plan.narratives = narratives;
+        const data = `${JSON.stringify(doc, null, 2)}\n`;
+        containedWrite({
+            root: resolve(projectRoot),
+            target: scopeAbs,
+            data,
+            mode: "replace",
+        });
+        // Verify pointer survived concurrent replace.
+        try {
+            const verifyRaw = readFileSync(scopeAbs, "utf8");
+            const verifyDoc = JSON.parse(verifyRaw);
+            const vPlan = verifyDoc?.plan;
+            const vNarr = vPlan?.narratives;
+            const vDec = typeof vNarr?.Decisions === "string" ? vNarr.Decisions : "";
+            if (vDec.includes(pointerNeedle)) {
+                return;
+            }
+        }
+        catch {
+            // retry
+        }
+    }
+    throw new Error(`failed to attach decision pointer to ${scopeRelPath} after ${maxAttempts} attempts ` +
+        `(concurrent writers may be contending on plan.narratives.Decisions)`);
+}
+/** Write a validated decision record to disk (standalone + optional scope pointer). */
+export function runDecisionWrite(options) {
+    const projectRootRaw = resolveProjectRoot(options.projectRoot ?? undefined);
+    if (projectRootRaw === null) {
+        return {
+            outcome: "error-config",
+            exitCode: 2,
+            path: null,
+            scopePath: null,
+            record: null,
+            message: "Error: could not resolve project root. Pass --project-root or run from a directive repo.\n",
+        };
+    }
+    const projectRoot = resolve(projectRootRaw);
+    let merged;
+    try {
+        merged = mergeInput(options, projectRoot);
+    }
+    catch (err) {
+        return {
+            outcome: "error-bad-args",
+            exitCode: 2,
+            path: null,
+            scopePath: null,
+            record: null,
+            message: `Error: failed to load body file: ${err instanceof Error ? err.message : String(err)}\n`,
+        };
+    }
+    const validated = validateDecisionRecord(merged);
+    if (!validated.ok || validated.record === undefined) {
+        return {
+            outcome: "error-bad-args",
+            exitCode: 2,
+            path: null,
+            scopePath: null,
+            record: null,
+            message: `Error: invalid decision record:\n${formatDecisionValidationErrors(validated.errors)}\n`,
+        };
+    }
+    const record = validated.record;
+    const filename = decisionFilename(record.id, record.timestamp);
+    const relPath = join(DECISIONS_DIR_REL, filename).replace(/\\/g, "/");
+    const absPath = resolve(projectRoot, relPath);
+    const recordOut = {
+        ...record,
+        path: relPath,
+    };
+    if (options.dryRun) {
+        return {
+            outcome: "written",
+            exitCode: 0,
+            path: relPath,
+            scopePath: record.activeScopeRefs[0] ?? null,
+            record: recordOut,
+            message: `[dry-run] would write ${relPath}\n`,
+        };
+    }
+    try {
+        mkdirSync(dirname(absPath), { recursive: true });
+        if (existsSync(absPath) && options.force !== true) {
+            return {
+                outcome: "error-io",
+                exitCode: 2,
+                path: relPath,
+                scopePath: null,
+                record: recordOut,
+                message: `Error: decision file already exists: ${relPath}\n` +
+                    "  Refusing to overwrite (would destroy prior rationale). " +
+                    "Pass --force to replace, or use a distinct --id / decision text.\n",
+            };
+        }
+        const data = `${JSON.stringify({
+            schemaVersion: recordOut.schemaVersion,
+            id: recordOut.id,
+            decision: recordOut.decision,
+            governingRule: recordOut.governingRule,
+            alternativesConsidered: recordOut.alternativesConsidered,
+            whyWinner: recordOut.whyWinner,
+            confidence: recordOut.confidence,
+            activeScopeRefs: recordOut.activeScopeRefs,
+            timestamp: recordOut.timestamp,
+            revisitTrigger: recordOut.revisitTrigger,
+            ...(recordOut.tags !== undefined ? { tags: recordOut.tags } : {}),
+            ...(recordOut.relatedIssues !== undefined
+                ? { relatedIssues: recordOut.relatedIssues }
+                : {}),
+        }, null, 2)}\n`;
+        // Prefer exclusive create unless --force. Concurrent writers that both
+        // pass the pre-check still fail closed via create/EXISTS instead of replace.
+        containedWrite({
+            root: projectRoot,
+            target: absPath,
+            data,
+            mode: options.force === true ? "replace" : "create",
+        });
+        let scopePath = null;
+        if (record.activeScopeRefs.length > 0 && options.standalone !== true) {
+            const scopeRel = record.activeScopeRefs[0];
+            try {
+                appendScopeDecisionPointer(projectRoot, scopeRel, relPath, record.decision);
+                scopePath = scopeRel;
+            }
+            catch (err) {
+                return {
+                    outcome: "error-io",
+                    exitCode: 2,
+                    path: relPath,
+                    scopePath: null,
+                    record: recordOut,
+                    message: `[deft decision] Wrote ${relPath} but failed to attach scope pointer: ` +
+                        `${err instanceof Error ? err.message : String(err)}\n`,
+                };
+            }
+        }
+        const scopeNote = scopePath !== null ? ` (linked from ${scopePath})` : "";
+        return {
+            outcome: "written",
+            exitCode: 0,
+            path: relPath,
+            scopePath,
+            record: recordOut,
+            message: `[deft decision] Wrote ${relPath}${scopeNote}\n`,
+        };
+    }
+    catch (err) {
+        if (err instanceof ContainedWriteError || err instanceof ProjectionContainmentError) {
+            return {
+                outcome: "error-io",
+                exitCode: 2,
+                path: null,
+                scopePath: null,
+                record: recordOut,
+                message: `Error: contained write refused: ${err.message}\n`,
+            };
+        }
+        return {
+            outcome: "error-io",
+            exitCode: 2,
+            path: null,
+            scopePath: null,
+            record: recordOut,
+            message: `Error: write failed: ${err instanceof Error ? err.message : String(err)}\n`,
+        };
+    }
+}
+/** Parse argv for decision:write. */
+export function parseDecisionWriteArgs(argv) {
+    const out = {};
+    const positionals = [];
+    const takeValue = (i, flag, eqPrefix) => {
+        const arg = argv[i];
+        if (arg === flag) {
+            return [argv[i + 1], i + 1];
+        }
+        if (arg.startsWith(eqPrefix)) {
+            return [arg.slice(eqPrefix.length), i];
+        }
+        return [undefined, i];
+    };
+    for (let i = 0; i < argv.length; i += 1) {
+        const arg = argv[i];
+        if (arg === "--dry-run")
+            out.dryRun = true;
+        else if (arg === "--json")
+            out.json = true;
+        else if (arg === "--standalone")
+            out.standalone = true;
+        else if (arg === "--force")
+            out.force = true;
+        else if (arg === "--decision" || arg.startsWith("--decision=")) {
+            const [v, ni] = takeValue(i, "--decision", "--decision=");
+            out.decision = v;
+            i = ni;
+        }
+        else if (arg === "--governing-rule" || arg.startsWith("--governing-rule=")) {
+            const [v, ni] = takeValue(i, "--governing-rule", "--governing-rule=");
+            out.governingRule = v;
+            i = ni;
+        }
+        else if (arg === "--governing-path" || arg.startsWith("--governing-path=")) {
+            const [v, ni] = takeValue(i, "--governing-path", "--governing-path=");
+            out.governingPath = v;
+            i = ni;
+        }
+        else if (arg === "--governing-rfc" || arg.startsWith("--governing-rfc=")) {
+            const [v, ni] = takeValue(i, "--governing-rfc", "--governing-rfc=");
+            out.governingRfc = v;
+            i = ni;
+        }
+        else if (arg === "--alternative" || arg.startsWith("--alternative=")) {
+            const [v, ni] = takeValue(i, "--alternative", "--alternative=");
+            if (v !== undefined) {
+                out.alternatives = [...(out.alternatives ?? []), v];
+            }
+            i = ni;
+        }
+        else if (arg === "--why-winner" || arg.startsWith("--why-winner=")) {
+            const [v, ni] = takeValue(i, "--why-winner", "--why-winner=");
+            out.whyWinner = v;
+            i = ni;
+        }
+        else if (arg === "--confidence" || arg.startsWith("--confidence=")) {
+            const [v, ni] = takeValue(i, "--confidence", "--confidence=");
+            out.confidence = v;
+            i = ni;
+        }
+        else if (arg === "--scope" || arg.startsWith("--scope=")) {
+            const [v, ni] = takeValue(i, "--scope", "--scope=");
+            if (v !== undefined) {
+                out.scope = [...(out.scope ?? []), v];
+            }
+            i = ni;
+        }
+        else if (arg === "--revisit-trigger" || arg.startsWith("--revisit-trigger=")) {
+            const [v, ni] = takeValue(i, "--revisit-trigger", "--revisit-trigger=");
+            out.revisitTrigger = v;
+            i = ni;
+        }
+        else if (arg === "--id" || arg.startsWith("--id=")) {
+            const [v, ni] = takeValue(i, "--id", "--id=");
+            out.id = v;
+            i = ni;
+        }
+        else if (arg === "--timestamp" || arg.startsWith("--timestamp=")) {
+            const [v, ni] = takeValue(i, "--timestamp", "--timestamp=");
+            out.timestamp = v;
+            i = ni;
+        }
+        else if (arg === "--tag" || arg.startsWith("--tag=")) {
+            const [v, ni] = takeValue(i, "--tag", "--tag=");
+            if (v !== undefined)
+                out.tags = [...(out.tags ?? []), v];
+            i = ni;
+        }
+        else if (arg === "--related-issue" || arg.startsWith("--related-issue=")) {
+            const [v, ni] = takeValue(i, "--related-issue", "--related-issue=");
+            if (v !== undefined && /^\d+$/.test(v.trim())) {
+                out.relatedIssues = [...(out.relatedIssues ?? []), Number(v.trim())];
+            }
+            i = ni;
+        }
+        else if (arg === "--body-file" || arg.startsWith("--body-file=")) {
+            const [v, ni] = takeValue(i, "--body-file", "--body-file=");
+            out.bodyFile = v;
+            i = ni;
+        }
+        else if (arg === "--project-root" || arg.startsWith("--project-root=")) {
+            const [v, ni] = takeValue(i, "--project-root", "--project-root=");
+            out.projectRoot = v;
+            i = ni;
+        }
+        else if (arg.startsWith("-")) {
+            return { ...out, error: `unrecognized argument: ${arg}` };
+        }
+        else {
+            positionals.push(arg);
+        }
+    }
+    if ((out.decision === undefined || out.decision.trim().length === 0) && positionals.length > 0) {
+        out.decision = positionals.join(" ");
+    }
+    return out;
+}
+/** CLI entry for decision:write. */
+export function decisionWriteMain(argv) {
+    const args = parseDecisionWriteArgs(argv);
+    if (args.error !== undefined) {
+        process.stderr.write(`decision:write: ${args.error}\n`);
+        return 2;
+    }
+    const governingRule = args.governingRule !== undefined
+        ? {
+            description: args.governingRule,
+            path: args.governingPath,
+            rfc2119: args.governingRfc,
+        }
+        : undefined;
+    const result = runDecisionWrite({
+        decision: args.decision,
+        governingRule,
+        alternatives: args.alternatives,
+        whyWinner: args.whyWinner,
+        confidence: args.confidence,
+        scope: args.scope,
+        revisitTrigger: args.revisitTrigger,
+        id: args.id,
+        timestamp: args.timestamp ?? normalizeTimestamp(),
+        tags: args.tags,
+        relatedIssues: args.relatedIssues,
+        bodyFile: args.bodyFile,
+        standalone: args.standalone,
+        force: args.force,
+        dryRun: args.dryRun,
+        json: args.json,
+        projectRoot: args.projectRoot,
+    });
+    if (args.json) {
+        process.stdout.write(`${JSON.stringify({
+            outcome: result.outcome,
+            exit_code: result.exitCode,
+            path: result.path,
+            scope_path: result.scopePath,
+            record: result.record,
+            message: result.message.trim(),
+        }, null, 2)}\n`);
+    }
+    else {
+        process.stdout.write(result.message);
+    }
+    return result.exitCode;
+}
+/** Relative path helper for tests. */
+export function relativeToProject(projectRoot, absPath) {
+    return relative(projectRoot, absPath).replace(/\\/g, "/");
+}
+export { slugifyDecision };
+//# sourceMappingURL=write.js.map

package/dist/eval/report.d.ts

@@ -1,4 +1,5 @@
 import { type GoldenRunRecord } from "./run.js";
+import { type CellVersionPurity, type MixedVersionPolicy } from "./version-pin.js";
 export declare const REPORT_SCHEMA_VERSION: 1;
 /** Metric delta with a simple two-proportion significance test (#896). */
 export interface MetricDelta {
@@ -17,6 +18,15 @@ export interface HoldoutTripwire {
     readonly primaryDelta: number;
     readonly holdoutDelta: number;
 }
+/** Version purity evidence for report consumers (#3215). */
+export interface VersionPurityEvidence {
+    readonly pure: boolean;
+    readonly summary: string;
+    readonly cells: readonly CellVersionPurity[];
+    readonly championCellAllowed: boolean;
+    readonly challengerCellAllowed: boolean;
+    readonly policy: MixedVersionPolicy;
+}
 /** Version-diff report between champion and challenger golden runs. */
 export interface GoldenEvalReport {
     readonly schemaVersion: typeof REPORT_SCHEMA_VERSION;
@@ -27,12 +37,19 @@ export interface GoldenEvalReport {
     readonly challengerRunId: string;
     readonly deltas: readonly MetricDelta[];
     readonly holdoutTripwire: HoldoutTripwire;
+    /** Cell-level framework version purity for the reported model (#3215). */
+    readonly versionPurity: VersionPurityEvidence;
 }
 export interface ReportGoldenEvalOptions {
     readonly projectRoot?: string;
     readonly championVersion: string;
     readonly challengerVersion: string;
     readonly model: string;
+    /**
+     * Mixed-version cell policy (#3215). Default `refuse` fails the report when
+     * ledger runs for this model disagree on framework version within a treatment.
+     */
+    readonly mixedVersionPolicy?: MixedVersionPolicy;
 }
 export interface ReportGoldenEvalResult {
     readonly code: 0 | 1 | 2;
@@ -48,6 +65,18 @@ export declare function twoProportionZTest(passedA: number, totalA: number, pass
 };
 /** Detect holdout tripwire: primary improves while holdout regresses (#1703). */
 export declare function evaluateHoldoutTripwire(champion: GoldenRunRecord, challenger: GoldenRunRecord): HoldoutTripwire;
+/**
+ * Map a golden-run ledger row to the #3215 versioned-run identity.
+ * Treatment is model@harness@version so cross-version champion/challenger
+ * comparisons stay distinct cells; pin disagreements under one version refuse.
+ */
+export declare function goldenRunToVersionedRun(record: GoldenRunRecord): {
+    frameworkVersion: string;
+    treatment: string;
+    model: string;
+    harness: string;
+    runId: string;
+};
 /** Diff two directive versions with metric deltas and significance (#1703 Tier 2). */
 export declare function reportGoldenEval(options: ReportGoldenEvalOptions): ReportGoldenEvalResult;
 //# sourceMappingURL=report.d.ts.map

package/dist/eval/report.js

@@ -1,6 +1,7 @@
 import { existsSync, readFileSync } from "node:fs";
 import { resolveEvalPath } from "../layout/resolve.js";
 import { GOLDEN_RUNS_HISTORY_REL } from "./run.js";
+import { aggregateCellWithVersionPurity, evaluateLedgerVersionPurity, } from "./version-pin.js";
 export const REPORT_SCHEMA_VERSION = 1;
 function readGoldenRuns(projectRoot) {
     const path = resolveEvalPath(projectRoot, GOLDEN_RUNS_HISTORY_REL);
@@ -89,6 +90,21 @@ export function evaluateHoldoutTripwire(champion, challenger) {
 function formatPercent(value) {
     return `${(value * 100).toFixed(1)}%`;
 }
+/**
+ * Map a golden-run ledger row to the #3215 versioned-run identity.
+ * Treatment is model@harness@version so cross-version champion/challenger
+ * comparisons stay distinct cells; pin disagreements under one version refuse.
+ */
+export function goldenRunToVersionedRun(record) {
+    const pin = record.frameworkVersionPin?.frameworkVersion ?? record.directiveVersion;
+    return {
+        frameworkVersion: pin,
+        treatment: `${record.model}@${record.harness}@${record.directiveVersion}`,
+        model: record.model,
+        harness: record.harness,
+        runId: record.runId,
+    };
+}
 /** Diff two directive versions with metric deltas and significance (#1703 Tier 2). */
 export function reportGoldenEval(options) {
     if (!options.championVersion.trim() || !options.challengerVersion.trim()) {
@@ -102,7 +118,48 @@ export function reportGoldenEval(options) {
         return { code: 2, report: null, message: "eval:report: --model is required" };
     }
     const projectRoot = options.projectRoot ?? process.cwd();
+    const policy = options.mixedVersionPolicy ?? "refuse";
     const records = readGoldenRuns(projectRoot);
+    const modelRecords = records.filter((r) => r.model === options.model);
+    // Within each version×model×harness cell, refuse/flag if pins disagree (#3215).
+    // Cross-version champion vs challenger is intentional and uses distinct cells.
+    const championCellRuns = modelRecords
+        .filter((r) => r.directiveVersion === options.championVersion)
+        .map(goldenRunToVersionedRun);
+    const challengerCellRuns = modelRecords
+        .filter((r) => r.directiveVersion === options.challengerVersion)
+        .map(goldenRunToVersionedRun);
+    const championAgg = aggregateCellWithVersionPurity({
+        runs: championCellRuns,
+        treatment: `champion@${options.model}@${options.championVersion}`,
+        policy,
+    });
+    const challengerAgg = aggregateCellWithVersionPurity({
+        runs: challengerCellRuns,
+        treatment: `challenger@${options.model}@${options.challengerVersion}`,
+        policy,
+    });
+    const ledgerPurity = evaluateLedgerVersionPurity(modelRecords.map(goldenRunToVersionedRun));
+    if (!championAgg.allowed || !challengerAgg.allowed) {
+        const versionPurity = {
+            pure: false,
+            summary: [
+                !championAgg.allowed ? championAgg.purity.message : null,
+                !challengerAgg.allowed ? challengerAgg.purity.message : null,
+            ]
+                .filter((line) => line !== null)
+                .join(" "),
+            cells: [championAgg.purity, challengerAgg.purity],
+            championCellAllowed: championAgg.allowed,
+            challengerCellAllowed: challengerAgg.allowed,
+            policy,
+        };
+        return {
+            code: 1,
+            report: null,
+            message: `eval:report: mixed framework versions in treatment cell(s) — aggregation refused (#3215)\n  ${versionPurity.summary}`,
+        };
+    }
     const champion = findLatestGoldenRun(records, options.championVersion, options.model);
     const challenger = findLatestGoldenRun(records, options.challengerVersion, options.model);
     if (champion === null) {
@@ -133,6 +190,14 @@ export function reportGoldenEval(options) {
         metricDelta("overallPassRate", champion.summary.passRate, challenger.summary.passRate, countPasses(champion.results).passed, countPasses(champion.results).total, countPasses(challenger.results).passed, countPasses(challenger.results).total),
     ];
     const holdoutTripwire = evaluateHoldoutTripwire(champion, challenger);
+    const versionPurity = {
+        pure: championAgg.purity.pure && challengerAgg.purity.pure && ledgerPurity.pure,
+        summary: `${championAgg.purity.message} ${challengerAgg.purity.message}`,
+        cells: [championAgg.purity, challengerAgg.purity, ...ledgerPurity.cells],
+        championCellAllowed: championAgg.allowed,
+        challengerCellAllowed: challengerAgg.allowed,
+        policy,
+    };
     const report = {
         schemaVersion: REPORT_SCHEMA_VERSION,
         championVersion: options.championVersion,
@@ -142,6 +207,7 @@ export function reportGoldenEval(options) {
         challengerRunId: challenger.runId,
         deltas,
         holdoutTripwire,
+        versionPurity,
     };
     const lines = [
         `eval:report champion=v${options.championVersion} challenger=v${options.challengerVersion} model=${options.model}`,
@@ -154,6 +220,9 @@ export function reportGoldenEval(options) {
             return `  ${d.metric}: ${formatPercent(d.champion)} -> ${formatPercent(d.challenger)} (delta ${(d.delta * 100).toFixed(1)}pp, ${sig})`;
         }),
         `  ${holdoutTripwire.summary}`,
+        `  version purity: ${versionPurity.pure ? "ok" : "mixed"} — ${versionPurity.summary}`,
+        `  champion cell pin: v${champion.frameworkVersionPin?.frameworkVersion ?? champion.directiveVersion}`,
+        `  challenger cell pin: v${challenger.frameworkVersionPin?.frameworkVersion ?? challenger.directiveVersion}`,
     ];
     const code = holdoutTripwire.triggered ? 1 : 0;
     return { code, report, message: lines.join("\n") };