niceeval 0.11.4-canary.21 → 0.12.0

package/dist/report/model/aggregate.js

@@ -50,6 +50,30 @@ export function evalIdOf(item) {
 export function historicalOf(item) {
     return item.attempt.carried || item.run.startedAt < item.watermark.startedAt;
 }
+/** 一个 ISO 时刻距渲染时刻(`Date.now()`)的毫秒数,恒不小于 0。 */
+export function msSince(iso) {
+    return Math.max(0, Date.now() - Date.parse(iso));
+}
+/**
+ * 覆盖缺口 / 对照矩阵缺席格的「过期结论」参考(docs/feature/reports/components/summaries/
+ * experiment-table.md「覆盖缺口的两档占位行」、show/compare.md 同一套口径):候选已经是与
+ * 当前基准 configHash 不可比的那些,取其中最近一条;两个消费方(entity-lists 的占位行、
+ * DeltaTable 的缺席格)共用同一份「取最新」判据,不各自实现一遍。
+ */
+export function staleReferenceOf(candidates) {
+    if (candidates.length === 0)
+        return undefined;
+    const newest = candidates.reduce((a, b) => ((a.result.startedAt ?? "") >= (b.result.startedAt ?? "") ? a : b));
+    const startedAt = newest.result.startedAt;
+    if (!startedAt)
+        return undefined; // 无时刻的 legacy 落盘算不出时距,不伪造参考
+    return {
+        locator: newest.locator ??
+            encodeAttemptLocator({ runId: newest.run.runId, evalId: newest.evalId, attempt: newest.result.attempt }),
+        verdict: newest.result.verdict,
+        staleSinceMs: msSince(startedAt),
+    };
+}
 /** 快照键:"<experimentId> @ <startedAt>"("run" 维度与手挑快照数组的对比用)。 */
 export function snapshotKeyOf(run) {
     return `${run.experimentId} @ ${run.startedAt}`;

package/dist/report/model/locale.d.ts

@@ -60,7 +60,6 @@ declare const en: {
     readonly "experimentList.cost": "Cost";
     readonly "experimentList.result": "Record";
     readonly "experimentList.status": "Status";
-    readonly "experimentList.coverage": "Coverage";
     readonly "experimentList.evalAttempt": "Eval / Attempt";
     readonly "experimentList.duration": "Duration";
     readonly "experimentList.filterPlaceholder": "Filter experiments…";

package/dist/report/model/locale.js

@@ -86,7 +86,6 @@ const en = {
     "experimentList.cost": "Cost",
     "experimentList.result": "Record",
     "experimentList.status": "Status",
-    "experimentList.coverage": "Coverage",
     "experimentList.evalAttempt": "Eval / Attempt",
     "experimentList.duration": "Duration",
     "experimentList.filterPlaceholder": "Filter experiments…",
@@ -269,7 +268,6 @@ const zhCN = {
     "experimentList.cost": "成本",
     "experimentList.result": "结果",
     "experimentList.status": "状态",
-    "experimentList.coverage": "覆盖构成",
     "experimentList.evalAttempt": "题目 / Attempt",
     "experimentList.duration": "耗时",
     "experimentList.filterPlaceholder": "筛选实验…",

package/dist/report/model/types.d.ts

@@ -242,6 +242,8 @@ export interface DeltaCell {
     totalCostUSD?: number;
     /** true 时该格来自跨快照携带的历史执行(时效标注见 experiment-table.md「时效不写字」)。 */
     historical: boolean;
+    /** `historical` 为 true 时,距今的毫秒数(渲染时刻起算);新执行时省略,不伪造 0。 */
+    staleSinceMs?: number;
 }
 export interface DeltaData {
     byDimension: string;
@@ -262,6 +264,12 @@ export interface DeltaData {
             tokens?: number;
             costUSD?: number;
         }>;
+        /**
+         * 键是条件值,只在该条件缺席这道题(`cells` 无键)且记录里存在不可比历史判定时才有条目
+         * (docs/feature/reports/show/compare.md「— ✓ 12d」);它不进 `totals`、`delta` 与配对覆盖的
+         * 任何一个数,只提供 locator 下钻。
+         */
+        references?: globalThis.Record<string, StaleConclusionReference>;
     }>;
     /** 各条件自身覆盖面的描述,分母是该条件有结果的 eval 数;不用于跨条件直接归因。 */
     totals: globalThis.Record<string, {

package/dist/report/presentation.d.ts

@@ -18,21 +18,68 @@ export type DimensionDeclarations = Readonly<Record<string, DimensionDeclaration
 export type DimensionPins = Readonly<Record<string, Readonly<Record<string, number>>>>;
 export declare const VISUAL_SLOT_COUNT = 24;
 export type SeriesVariant = 1 | 2 | 3 | 4;
-/** 槽 1..24 → (色板下标 1..6, 形状变体 1..4)，与 README 槽序表逐项对应。 */
+/**
+ * 槽 1..24 → (色板下标 1..6, 形状变体 1..4)。
+ * 与 components/README「视觉编码容量」槽序表一致:1–6 第一变体、7–12 第二变体,依此类推。
+ * `colorIndex = (slot-1) % 6 + 1`,`variant = floor((slot-1)/6) + 1`。
+ */
 export declare function seriesChannelsOf(slot: number): {
     colorIndex: number;
     variant: SeriesVariant;
 };
-export interface PresentedValue {
+export interface PresentationIdentity {
+    /** 完整维度值，作为排序、筛选、React key 与证据身份。 */
     readonly value: string;
+    /** 当前页完整 label keyset 内生成的显示名。 */
     readonly label: string;
-    readonly seriesSlot?: number;
-    readonly colorIndex?: number;
-    readonly variant?: SeriesVariant;
 }
+export interface LabelPresentation extends PresentationIdentity {
+    readonly kind: "label";
+}
+export interface ColorPresentation extends PresentationIdentity {
+    readonly kind: "color";
+    /** `var(--niceeval-color-series-N)`。 */
+    readonly color: string;
+}
+export interface LineSeriesPresentation extends PresentationIdentity {
+    readonly kind: "series";
+    readonly mark: "line";
+    readonly stroke: string;
+    readonly strokeDasharray: string;
+    readonly marker: {
+        readonly path: string;
+        readonly viewBox: string;
+        readonly fill: string;
+        readonly stroke: string;
+    };
+}
+export interface ScatterSeriesPresentation extends PresentationIdentity {
+    readonly kind: "series";
+    readonly mark: "scatter";
+    readonly marker: LineSeriesPresentation["marker"];
+}
+export interface FillSeriesPresentation extends PresentationIdentity {
+    readonly kind: "series";
+    readonly mark: "bar" | "area";
+    /** 颜色，或可直接使用的 `url(#pattern-id)`。 */
+    readonly fill: string;
+    readonly stroke: string;
+    readonly strokeDasharray: string;
+}
+export type DimensionPresentation = LabelPresentation | ColorPresentation | LineSeriesPresentation | ScatterSeriesPresentation | FillSeriesPresentation;
+export type PresentationFor<E extends DimensionEncoding> = E extends {
+    kind: "label";
+} ? LabelPresentation : E extends {
+    kind: "color";
+} ? ColorPresentation : LineSeriesPresentation | ScatterSeriesPresentation | FillSeriesPresentation;
+/**
+ * 句柄上的呈现面。`at(i)` 返回可直接交给 SVG/CSS 的值;text 面恒为 label 支。
+ * `labels` 是本维度整页 label keyset 的最短唯一后缀表,便于探针与调试。
+ */
 export interface PresentedDimension {
+    readonly length: number;
     readonly labels: ReadonlyMap<string, string>;
-    at(index: number): PresentedValue;
+    at(index: number): DimensionPresentation;
 }
 export declare class UndeclaredDimensionValueError extends Error {
     readonly handle: string;

package/dist/report/presentation.js

@@ -1,6 +1,11 @@
 import { shortestUniqueLabels as labels } from "./model/format.js";
+import { seriesColorVar, seriesFill, seriesMarker, seriesStrokeDasharray, } from "./assets/series-encoding.js";
 export const VISUAL_SLOT_COUNT = 24;
-/** 槽 1..24 → (色板下标 1..6, 形状变体 1..4)，与 README 槽序表逐项对应。 */
+/**
+ * 槽 1..24 → (色板下标 1..6, 形状变体 1..4)。
+ * 与 components/README「视觉编码容量」槽序表一致:1–6 第一变体、7–12 第二变体,依此类推。
+ * `colorIndex = (slot-1) % 6 + 1`,`variant = floor((slot-1)/6) + 1`。
+ */
 export function seriesChannelsOf(slot) {
     if (!Number.isInteger(slot) || slot < 1 || slot > VISUAL_SLOT_COUNT) {
         throw new Error(`seriesSlot must be an integer in [1, ${VISUAL_SLOT_COUNT}], got ${slot}.`);
@@ -8,7 +13,7 @@ export function seriesChannelsOf(slot) {
     const zero = slot - 1;
     return {
         colorIndex: (zero % 6) + 1,
-        variant: ((((zero % 4) + Math.floor(zero / 12)) % 4) + 1),
+        variant: (Math.floor(zero / 6) + 1),
     };
 }
 export class UndeclaredDimensionValueError extends Error {
@@ -33,6 +38,35 @@ export function presentDimension(declaration) {
     return presented;
 }
 export const shortestUniqueLabels = labels;
+function presentChannels(value, label, seriesSlot, encoding) {
+    const { colorIndex, variant } = seriesChannelsOf(seriesSlot);
+    if (encoding.kind === "color") {
+        return { kind: "color", value, label, color: seriesColorVar(colorIndex) };
+    }
+    if (encoding.kind !== "series") {
+        return { kind: "label", value, label };
+    }
+    const stroke = seriesColorVar(colorIndex);
+    const strokeDasharray = seriesStrokeDasharray(variant);
+    const marker = seriesMarker(colorIndex, variant);
+    switch (encoding.mark) {
+        case "line":
+            return { kind: "series", mark: "line", value, label, stroke, strokeDasharray, marker };
+        case "scatter":
+            return { kind: "series", mark: "scatter", value, label, marker };
+        case "bar":
+        case "area":
+            return {
+                kind: "series",
+                mark: encoding.mark,
+                value,
+                label,
+                fill: seriesFill(colorIndex, variant),
+                stroke,
+                strokeDasharray,
+            };
+    }
+}
 /**
  * 页级呈现分配：收集整页 dimensions() 声明，产出 label / visual 两套 keyset 上的映射。
  * pins 原样占位；未钉键以稳定散列为起点、撞槽按显示键字典序线性探测。
@@ -79,6 +113,7 @@ export function allocatePageDimensions(handles, pins = {}, options = { face: "we
         const values = declaration.values;
         const encoding = declaration.encoding;
         byHandle.set(handle, {
+            length: values.length,
             labels: dimLabels,
             at(index) {
                 const value = values[index];
@@ -86,15 +121,15 @@ export function allocatePageDimensions(handles, pins = {}, options = { face: "we
                     throw new UndeclaredDimensionValueError(`dimension handle "${handle}" has no value at index ${index} (declared length ${values.length}).`, handle, index);
                 }
                 const label = dimLabels.get(value) ?? value;
+                // text 面恒返回 label 支:不上 ANSI 色,拿不到颜色、线型或 pattern。
                 if (options.face === "text" || encoding.kind === "label") {
-                    return { value, label };
+                    return { kind: "label", value, label };
                 }
                 const seriesSlot = slots?.get(value);
                 if (seriesSlot === undefined) {
                     throw new UndeclaredDimensionValueError(`dimension handle "${handle}" value ${JSON.stringify(value)} has no seriesSlot on this page.`, handle, index);
                 }
-                const channels = seriesChannelsOf(seriesSlot);
-                return { value, label, seriesSlot, colorIndex: channels.colorIndex, variant: channels.variant };
+                return presentChannels(value, label, seriesSlot, encoding);
             },
         });
     }

package/dist/report/react/index.d.ts

@@ -8,6 +8,6 @@ export { formatCellText } from "../definition/cell.ts";
 export type { AttemptEvidence, AttemptEvidenceCapabilities } from "../../record/attempt-evidence.ts";
 export { formatAxisTick, formatInstant, formatMetricValue, formatTimeDistance, missingText } from "../model/format.ts";
 export { presentDimension, shortestUniqueLabels } from "../presentation.ts";
-export type { DimensionDeclaration, DimensionEncoding, PresentedDimension } from "../presentation.ts";
+export type { ColorPresentation, DimensionDeclaration, DimensionEncoding, DimensionPresentation, FillSeriesPresentation, LabelPresentation, LineSeriesPresentation, PresentedDimension, ScatterSeriesPresentation, } from "../presentation.ts";
 export { DEFAULT_REPORT_LOCALE, localizedTextEquals, resolveLocalizedText, resolveMetricLabel, } from "../model/locale.ts";
 export type { LocalizedText, ReportLocale } from "../model/locale.ts";

package/dist/report/slices/compute.js

@@ -12,7 +12,7 @@
 // - core 中立:只认 Metric / Dimension 接口,不出现具体 agent 名的分支。
 import { comparabilityConfigOf, deepEqualJson } from "../../sample/index.js";
 import { foldEvalVerdict } from "../../shared/verdict.js";
-import { assertUniqueMetricNames, axisValueOf, collectItems, computeCell, dimensionKey, dimensionName, evalGroupOf, evalIdOf, evaluateMetric, experimentIdOf, filterItems, fullEvalKey, groupItems, historicalOf, locatorOf, refDisplayKey, resolveInput, seriesKey, seriesName, toColumn, } from "../model/aggregate.js";
+import { assertUniqueMetricNames, axisValueOf, collectItems, computeCell, dimensionKey, dimensionName, evalGroupOf, evalIdOf, evaluateMetric, experimentIdOf, filterItems, fullEvalKey, groupItems, historicalOf, locatorOf, msSince, refDisplayKey, resolveInput, seriesKey, seriesName, staleReferenceOf, toColumn, } from "../model/aggregate.js";
 import { costUSD as costUSDMetric, examScore, tokens as tokensMetric, totalScore as totalScoreMetric } from "../model/metrics.js";
 import { formatMetricValue, formatPlainNumber } from "../model/format.js";
 import { metricFieldOf } from "../model/dataset.js";
@@ -420,6 +420,10 @@ async function buildDeltaCell(items) {
     const verdict = foldEvalVerdict(items.map((item) => ({ verdict: item.attempt.result.verdict })));
     const refs = new Set();
     let historical = false;
+    // 距今最久的历史执行决定这一格的时距——多个 attempt 折进同一格时,时距说的是「这批结论里
+    // 最旧的证据有多旧」,不是最新那条(与 experiment-table 的 attempt 行时距同一份数据来源,
+    // 只是这里先跨 attempt 折叠成一格)。
+    let staleStartedAt;
     let scoreSum = 0;
     let scoreCount = 0;
     let tokensSum = 0;
@@ -428,8 +432,12 @@ async function buildDeltaCell(items) {
     let costCount = 0;
     for (const item of items) {
         refs.add(locatorOf(item));
-        if (historicalOf(item))
+        if (historicalOf(item)) {
             historical = true;
+            const startedAt = item.attempt.result.startedAt ?? item.run.startedAt;
+            if (staleStartedAt === undefined || startedAt < staleStartedAt)
+                staleStartedAt = startedAt;
+        }
         if (evaluationKind === "points") {
             const value = await evaluateMetric(totalScoreMetric, item.attempt);
             if (value !== null) {
@@ -458,10 +466,21 @@ async function buildDeltaCell(items) {
         ...(tokensCount > 0 ? { totalTokens: tokensSum } : {}),
         ...(costCount > 0 ? { totalCostUSD: costSum } : {}),
         historical,
+        ...(staleStartedAt !== undefined ? { staleSinceMs: msSince(staleStartedAt) } : {}),
     };
 }
+/** 每个 experiment 当前基准的 configHash:该 experiment 在 `runs` 里最新快照的 configHash。 */
+function latestConfigHashByExperiment(runs) {
+    const latest = new Map();
+    for (const run of runs) {
+        const existing = latest.get(run.experimentId);
+        if (existing === undefined || run.startedAt > existing.startedAt)
+            latest.set(run.experimentId, run);
+    }
+    return new Map([...latest].map(([id, run]) => [id, run.configHash]));
+}
 export async function deltaTableData(input, options) {
-    const { runs, attempts } = resolveInput(input);
+    const { runs, attempts, historyAttempts, fresh } = resolveInput(input);
     const items = filterItems(collectItems(runs, attempts), options.evals);
     let conditions;
     let experiments;
@@ -526,6 +545,13 @@ export async function deltaTableData(input, options) {
         for (const evalId of byEval.keys())
             evalIdsSet.add(evalId);
     const knownEvalIds = [...evalIdsSet].sort();
+    // 每个条件背后的 experiment id 集合(by: "experiment" 时条件字符串本身通常就是唯一一个 id);
+    // 过期结论参考按各自 experiment 的当前基准 configHash 判定。
+    const experimentIdsByCondition = new Map();
+    for (const [condition, conditionItems] of itemsByCondition) {
+        experimentIdsByCondition.set(condition, new Set(conditionItems.map((item) => experimentIdOf(item))));
+    }
+    const anchorConfigHashByExperiment = latestConfigHashByExperiment(runs);
     const baseline = conditions[0];
     const rows = [];
     for (const evalId of knownEvalIds) {
@@ -558,7 +584,29 @@ export async function deltaTableData(input, options) {
                 }
             }
         }
-        rows.push({ key: evalId, flipped, cells, ...(delta ? { delta } : {}) });
+        // 过期结论参考(show/compare.md「— ✓ 12d」):只在该条件缺席这道题、且记录里存在与该
+        // experiment 当前基准不可比的历史判定时才给,口径与 experiment-table 两档占位行一致——
+        // `fresh` 为 true 时不给参考,读者已声明只看新执行。它只写进 references,不进 cells,
+        // 因此天然不参与 totals / delta / 配对覆盖的任何一个数。
+        let references;
+        if (!fresh) {
+            for (const condition of conditions) {
+                if (cells[condition] !== undefined)
+                    continue;
+                const experimentIds = experimentIdsByCondition.get(condition);
+                if (!experimentIds || experimentIds.size === 0)
+                    continue;
+                const candidates = historyAttempts.filter((a) => experimentIds.has(a.experimentId) &&
+                    a.evalId === evalId &&
+                    a.run.configHash !== anchorConfigHashByExperiment.get(a.experimentId));
+                const reference = staleReferenceOf(candidates);
+                if (reference) {
+                    references ??= {};
+                    references[condition] = reference;
+                }
+            }
+        }
+        rows.push({ key: evalId, flipped, cells, ...(delta ? { delta } : {}), ...(references ? { references } : {}) });
     }
     // 各条件自身覆盖面:分母是该条件有结果的 eval 数,不看其它条件是否也覆盖了这道题。
     const totals = {};

package/dist/report/slices/content.d.ts

@@ -1,6 +1,7 @@
 import type { TableContent, TableContentRow } from "../definition/cell.ts";
 import type { DeltaData, StabilityMatrixCell, StabilityMatrixData } from "../model/types.ts";
-export declare function deltaTableContent(data: DeltaData): TableContent;
+import { type ReportLocale } from "../model/locale.ts";
+export declare function deltaTableContent(data: DeltaData, locale?: ReportLocale): TableContent;
 export interface StabilityContentRow extends TableContentRow {
     readonly evalId: string;
     /** 全部条件历史执行中通过次数为 0 且执行数 > 0。 */

package/dist/report/slices/content.js

@@ -1,6 +1,46 @@
 // 指标视图 TableContent 投影:compute *Data → Table 原语可直接消费的形状。
-import { localizedMessage } from "../model/locale.js";
-export function deltaTableContent(data) {
+import { DEFAULT_REPORT_LOCALE, localizedMessage } from "../model/locale.js";
+import { formatMetricValue, formatPlainNumber, formatPoints, formatTimeDistance, verdictMark } from "../model/format.js";
+/**
+ * 带符号的美元/tokens 差值:复用 `formatMetricValue` 折终值(内建 unit 格式不分 locale,
+ * presentation.md「unit 决定格式」),只在外面补一个恒定的正负号——负值 `formatMetricValue`
+ * 已经自带 "-",这里只需要给非负值补 "+"。
+ */
+function signedMetricText(value, unit) {
+    const sign = value > 0 ? "+" : "";
+    return `${sign}${formatMetricValue(value, unit)}`;
+}
+/** 带符号的挣分差值("+4 pts" / "-4 pts");`formatPointsSuffix` 恒加 "+" 号,不适用于可能为负的差值。 */
+function signedPointsText(value) {
+    const sign = value > 0 ? "+" : value < 0 ? "-" : "";
+    const abs = Math.abs(value);
+    return `${sign}${formatPlainNumber(abs)} ${abs === 1 ? "pt" : "pts"}`;
+}
+/**
+ * 一格的判定读法(docs/feature/reports/show/compare.md):有数据时通过制只留判定符(`bare`,
+ * 历史执行再接相对时距)、计分制显示挣分;该条件缺席这道题时,记录里有过期结论参考才给
+ * `— <判定符> <时距>`(`—` 不被参考替换,它标记「这一格没有可聚合的结果」,参考只是附注),
+ * 没有参考就是纯 `notApplicable`。参考不进任何计数——它压根不出现在 `cells` 里,只在这一格
+ * 的显示上多一句附注。
+ */
+function conditionVerdictCell(cell, reference, locale) {
+    if (!cell) {
+        if (!reference)
+            return { kind: "notApplicable" };
+        const mark = verdictMark(reference.verdict === "skipped" ? "skipped" : reference.verdict);
+        return { kind: "text", text: `— ${mark} ${formatTimeDistance(reference.staleSinceMs, locale)}` };
+    }
+    if (cell.evaluationKind === "points") {
+        return { kind: "text", text: cell.totalScore !== undefined ? formatPoints(cell.totalScore) : "—" };
+    }
+    return {
+        kind: "verdict",
+        verdict: cell.verdict,
+        bare: true,
+        ...(cell.historical && cell.staleSinceMs !== undefined ? { staleSinceMs: cell.staleSinceMs } : {}),
+    };
+}
+export function deltaTableContent(data, locale = DEFAULT_REPORT_LOCALE) {
     const conditionColumns = data.conditions.flatMap((condition) => [
         { key: `${condition}:verdict` },
         { key: `${condition}:tokens` },
@@ -20,31 +60,24 @@ export function deltaTableContent(data) {
             };
             for (const condition of data.conditions) {
                 const cell = row.cells[condition];
-                cells[`${condition}:verdict`] = cell
-                    ? cell.evaluationKind === "points"
-                        ? {
-                            kind: "text",
-                            text: cell.totalScore !== undefined ? String(cell.totalScore) : "—",
-                        }
-                        : { kind: "verdict", verdict: cell.verdict }
-                    : { kind: "notApplicable" };
+                cells[`${condition}:verdict`] = conditionVerdictCell(cell, row.references?.[condition], locale);
                 cells[`${condition}:tokens`] =
                     cell?.totalTokens !== undefined
-                        ? { kind: "text", text: String(cell.totalTokens) }
+                        ? { kind: "metric", metric: { value: cell.totalTokens, unit: "tokens", basis: "eval", samples: 1, total: 1, refs: cell.attempts } }
                         : { kind: "notApplicable" };
                 cells[`${condition}:cost`] =
                     cell?.totalCostUSD !== undefined
-                        ? { kind: "text", text: String(cell.totalCostUSD) }
+                        ? { kind: "metric", metric: { value: cell.totalCostUSD, unit: "$", basis: "eval", samples: 1, total: 1, refs: cell.attempts } }
                         : { kind: "notApplicable" };
             }
             for (const condition of data.conditions.slice(1)) {
                 const delta = row.delta?.[condition];
                 cells[`${condition}:Δscore`] =
-                    delta?.score !== undefined ? { kind: "text", text: String(delta.score) } : { kind: "notApplicable" };
+                    delta?.score !== undefined ? { kind: "text", text: signedPointsText(delta.score) } : { kind: "notApplicable" };
                 cells[`${condition}:Δtokens`] =
-                    delta?.tokens !== undefined ? { kind: "text", text: String(delta.tokens) } : { kind: "notApplicable" };
+                    delta?.tokens !== undefined ? { kind: "text", text: signedMetricText(delta.tokens, "tokens") } : { kind: "notApplicable" };
                 cells[`${condition}:Δcost`] =
-                    delta?.costUSD !== undefined ? { kind: "text", text: String(delta.costUSD) } : { kind: "notApplicable" };
+                    delta?.costUSD !== undefined ? { kind: "text", text: signedMetricText(delta.costUSD, "$") } : { kind: "notApplicable" };
             }
             return { key: row.key, cells };
         }),

package/dist/report/slices/validate.js

@@ -129,6 +129,20 @@ function deltaCellProblem(value, path) {
         return `"${path}.totalCostUSD" must be a number`;
     if (typeof value.historical !== "boolean")
         return `"${path}.historical" must be a boolean`;
+    if (value.staleSinceMs !== undefined && typeof value.staleSinceMs !== "number")
+        return `"${path}.staleSinceMs" must be a number`;
+    return null;
+}
+/** 缺席格的过期结论参考(与 experiment-table 占位行同一份 StaleConclusionReference 形状)。 */
+function staleReferenceProblem(value, path) {
+    if (!isObject(value))
+        return `"${path}" must be an object { locator, verdict, staleSinceMs }`;
+    if (typeof value.locator !== "string")
+        return `"${path}.locator" must be a string`;
+    if (typeof value.verdict !== "string")
+        return `"${path}.verdict" must be a string`;
+    if (typeof value.staleSinceMs !== "number")
+        return `"${path}.staleSinceMs" must be a number`;
     return null;
 }
 function deltaTotalsProblem(value, path) {
@@ -206,6 +220,15 @@ export const validateDeltaData = (data) => {
                     return `"${path}.delta.${condition}.costUSD" must be a number`;
             }
         }
+        if (row.references !== undefined) {
+            if (!isObject(row.references))
+                return `"${path}.references" must be an object`;
+            for (const [condition, reference] of Object.entries(row.references)) {
+                const problem = staleReferenceProblem(reference, `${path}.references.${condition}`);
+                if (problem !== null)
+                    return problem;
+            }
+        }
         return null;
     });
     if (rowsProblem !== null)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "niceeval",
-  "version": "0.11.4-canary.21",
+  "version": "0.12.0",
   "description": "Agent-native eval tool — eval agents, services, functions, and coding-agent fixtures",
   "type": "module",
   "license": "MIT",