niceeval 0.11.4-canary.20 → 0.12.0

package/dist/report/components/entity-lists/compute.js

@@ -8,7 +8,7 @@
 // - core 中立:只认 Metric / Dimension 接口,不出现具体 agent 名的分支。
 import { comparabilityConfigOf, deepEqualJson } from "../../../sample/index.js";
 import { foldEvalVerdict } from "../../../shared/verdict.js";
-import { collectItems, computeCell, evalIdOf, experimentIdOf, fullEvalKey, groupItems, historicalOf, locatorOf, resolveInput, } from "../../model/aggregate.js";
+import { collectItems, computeCell, evalIdOf, experimentIdOf, fullEvalKey, groupItems, historicalOf, locatorOf, msSince, resolveInput, staleReferenceOf, } from "../../model/aggregate.js";
 import { attemptCostUSD, costUSD, durationMs, examScore, passRate, tokens, totalScore } from "../../model/metrics.js";
 import { compactAssertionSummary, primaryAssertionSummary, summaryText } from "../../../assertions/display.js";
 import { firstLine } from "../../../util.js";
@@ -47,6 +47,11 @@ export function failureSummaryOf(result) {
 async function attemptListItemOf(item) {
     const result = item.attempt.result;
     const { summary, more } = failureSummaryOf(result);
+    const historical = historicalOf(item);
+    // 缺 startedAt(legacy / 第三方落盘)时退化到所属快照的 startedAt——时效标注宁可粗一档
+    // 时距,不留空字段(与 dedupeAttempts「缺才不去重」同一条「不伪造」纪律,这里伪造的只是
+    // 展示粒度,不影响身份判定)。
+    const startedAt = result.startedAt ?? item.run.startedAt;
     return {
         experimentId: experimentIdOf(item),
         evalId: evalIdOf(item),
@@ -60,14 +65,21 @@ async function attemptListItemOf(item) {
         totalScore: await computeCell(totalScore, [item]),
         durationMs: result.durationMs,
         costUSD: attemptCostUSD(result),
-        // 缺 startedAt(legacy / 第三方落盘)时退化到所属快照的 startedAt——时效标注宁可粗一档
-        // 时距,不留空字段(与 dedupeAttempts「缺才不去重」同一条「不伪造」纪律,这里伪造的只是
-        // 展示粒度,不影响身份判定)。
-        startedAt: result.startedAt ?? item.run.startedAt,
-        historical: historicalOf(item),
+        startedAt,
+        historical,
+        ...(historical ? { staleSinceMs: msSince(startedAt) } : {}),
         locator: locatorOf(item),
     };
 }
+/**
+ * 「只看新执行」开关在场的判据(docs/feature/reports/components/summaries/experiment-table.md
+ * 「只看新执行」):Sample 里既没有历史执行也没有过期结论时不画开关——一个永远不改变行集的
+ * 控件只会让人怀疑自己看漏了什么。`ExperimentTable` 与内建默认报告共用同一条判据。
+ */
+export function hasHistoricalOrStale(items) {
+    return items.some((item) => Object.keys(item.staleReferences).length > 0 ||
+        item.evalRows.some((row) => row.attempts.some((attempt) => attempt.historical)));
+}
 /** 已选出的 AttemptHandle[] → 列表行；顺序保持传入顺序（不再次按 Sample 去重）。 */
 export async function attemptRowsOf(attempts) {
     return Promise.all(attempts.map((attempt) => attemptListItemOf({ attempt, run: attempt.run, watermark: attempt.run })));
@@ -158,6 +170,38 @@ function byMetricDescThenId(valueOf) {
         return vb - va || a.experimentId.localeCompare(b.experimentId);
     };
 }
+/**
+ * 覆盖缺口两档占位的「过期结论」参考(docs/feature/reports/components/summaries/experiment-table.md
+ * 「覆盖缺口的两档占位行」):`missingEvalIds` 里、`historyAttempts` 中存在与 `anchorConfigHash`
+ * 不可比判定的题,取其中最近一条。`fresh` 为 true 时整份不给参考——读者已声明只看新执行,
+ * 占位行就不再把被排除的历史结论请回来。
+ */
+function staleReferencesFor(experimentId, missingEvalIds, historyAttempts, anchorConfigHash, fresh) {
+    if (fresh || missingEvalIds.length === 0)
+        return {};
+    const missing = new Set(missingEvalIds);
+    const candidatesByEval = new Map();
+    for (const attempt of historyAttempts) {
+        if (attempt.experimentId !== experimentId)
+            continue;
+        if (!missing.has(attempt.evalId))
+            continue;
+        if (attempt.run.configHash === anchorConfigHash)
+            continue; // 可比,不是「过期结论」候选
+        const list = candidatesByEval.get(attempt.evalId);
+        if (list)
+            list.push(attempt);
+        else
+            candidatesByEval.set(attempt.evalId, [attempt]);
+    }
+    const out = {};
+    for (const [evalId, candidates] of candidatesByEval) {
+        const reference = staleReferenceOf(candidates);
+        if (reference)
+            out[evalId] = reference;
+    }
+    return out;
+}
 /**
  * `experimentListData(input)`:每个 experiment 一项,展开到每道 Eval;初始排序按这份列表
  * 自身的题型构成选择主读数——纯通过制沿用端到端通过率降序,纯计分制改按总分降序(缺数据
@@ -168,7 +212,7 @@ function byMetricDescThenId(valueOf) {
  * 看跨配置演化用 run 维度或 MetricLine,不把两套配置拼成一行冒充单一配置。
  */
 export async function experimentListData(input) {
-    const { runs, attempts, coverage } = resolveInput(input);
+    const { runs, attempts, coverage, historyAttempts, fresh } = resolveInput(input);
     const coverageByExperiment = new Map(coverage.map((c) => [c.experimentId, c]));
     // 可比性配置单义检查:同一 experiment 的输入快照必须共享一套可比性配置。
     const configByExperiment = new Map();
@@ -216,6 +260,7 @@ export async function experimentListData(input) {
         }
         const experiment = newest.run.experiment ?? newest.attempt.result.experiment;
         const model = newest.attempt.result.model ?? newest.run.model;
+        const missingEvalIds = coverageByExperiment.get(experimentId)?.missingEvalIds ?? [];
         out.push({
             experimentId,
             agent: newest.run.agent || newest.attempt.result.agent,
@@ -231,7 +276,8 @@ export async function experimentListData(input) {
             evals: stats.evals,
             attempts: stats.attempts,
             historicalAttempts: group.filter(historicalOf).length,
-            missingEvalIds: coverageByExperiment.get(experimentId)?.missingEvalIds ?? [],
+            missingEvalIds,
+            staleReferences: staleReferencesFor(experimentId, missingEvalIds, historyAttempts, coverageByExperiment.get(experimentId)?.run.configHash, fresh),
             lastRunAt: stats.lastRunAt,
             evalRows,
         });
@@ -263,6 +309,7 @@ export async function experimentListData(input) {
             attempts: 0,
             historicalAttempts: 0,
             missingEvalIds: coverageEntry.missingEvalIds,
+            staleReferences: staleReferencesFor(coverageEntry.experimentId, coverageEntry.missingEvalIds, historyAttempts, anchor.configHash, fresh),
             lastRunAt: anchor.startedAt,
             evalRows: [],
         });

package/dist/report/components/entity-lists/content.d.ts

@@ -1,5 +1,7 @@
 import type { TableContent } from "../../definition/cell.ts";
 import type { AttemptListItem, EvalListItem, ExperimentListItem } from "../../model/types.ts";
+/** 覆盖构成副行的 key 前缀;测试与消费方靠它把这一行从 Eval / 组行里筛出去。 */
+export declare const COVERAGE_ROW_PREFIX = "coverage:";
 export declare function experimentListContent(items: readonly ExperimentListItem[]): TableContent;
 export declare function evalListContent(items: readonly EvalListItem[]): TableContent;
 export declare function attemptListContent(items: readonly AttemptListItem[]): TableContent;

package/dist/report/components/entity-lists/content.js

@@ -5,6 +5,10 @@ import { localizedMessage } from "../../model/locale.js";
 import { experimentListEvaluationKindComposition } from "../../model/format.js";
 /** 组内零样本读数格的结构化原因码;renderer 经 missingText 映射文案。 */
 const GROUP_NO_SAMPLES = "noSamples";
+/** 覆盖缺口两档占位行共用的原因码——两档说的是同一个事实,`code` 相同。 */
+const NO_CURRENT_RESULT = "noCurrentResult";
+/** 覆盖构成四段的声明序:新执行 → 历史执行 → 过期结论 → 未跑到(段序即声明序)。 */
+const COVERAGE_SEGMENT_KEYS = ["coverage.fresh", "coverage.historical", "coverage.stale", "coverage.notRun"];
 /** 三张实体表共用的列表头。文案单源在 locale 字典,这里只烤成随列走的 LocalizedText。 */
 const HEADER = {
     entity: localizedMessage("experimentList.experiment"),
@@ -86,7 +90,7 @@ function attemptCells(item) {
         entity: {
             kind: "locator",
             locator: item.locator,
-            staleSinceMs: item.historical ? 1 : undefined,
+            staleSinceMs: item.staleSinceMs,
             verdict,
         },
         verdict: { kind: "verdict", verdict },
@@ -216,10 +220,20 @@ function evalRow(row, view, label) {
         subRows: row.attempts.map((a) => attemptRow(a, view.columns)),
     };
 }
-function placeholderRow(experimentId, evalId, label, columns) {
+/**
+ * 覆盖缺口的两档占位行(docs/feature/reports/components/summaries/experiment-table.md
+ * 「覆盖缺口的两档占位行」):`code` 与补跑命令两档相同——都是「当前配置下没有结果」这同一个
+ * 事实;差别只在有没有 `reference`,带参考时它替代原因文案,不把同一句话说两遍。
+ */
+function placeholderRow(experimentId, evalId, label, columns, reference) {
     const bag = {
         entity: textCell(label),
-        result: textCell("No result for current config", `niceeval exp ${experimentId}`),
+        record: {
+            kind: "missing",
+            code: NO_CURRENT_RESULT,
+            detail: `niceeval exp ${experimentId}`,
+            ...(reference ? { reference } : {}),
+        },
     };
     return {
         key: `${experimentId}:${evalId}:missing`,
@@ -252,7 +266,7 @@ function evalRowsEvaluationKindComposition(evalRows) {
 function leafTableRow(member, label, item, view) {
     return member.kind === "eval"
         ? evalRow(member.row, view, label)
-        : placeholderRow(item.experimentId, member.evalId, label, view.columns);
+        : placeholderRow(item.experimentId, member.evalId, label, view.columns, item.staleReferences[member.evalId]);
 }
 function groupTableRow(
 /** 组行显示的这一段(不带祖先前缀)。 */
@@ -348,13 +362,52 @@ function nestLevel(members, dirPrefix, labelPrefix, item, view) {
         .map((member) => leafTableRow(member, relativeLabel(memberEvalId(member), labelPrefix), item, view));
     return [...rows, ...flat];
 }
-/** experiment 的 evalRows + missingEvalIds → 递归嵌套的 subRows。 */
+/**
+ * 覆盖构成的四段计数(docs/feature/reports/components/summaries/experiment-table.md「覆盖构成」):
+ * 新执行 / 历史执行 = 有 attempt 的题按其中是否有非历史(新执行)划分;过期结论 = 缺口题里
+ * `staleReferences` 命中的那些;未跑到 = 缺口题里剩下的那些。四段互斥且合计等于已知题数。
+ */
+function coverageSegments(item) {
+    let fresh = 0;
+    for (const row of item.evalRows) {
+        if (row.attempts.some((a) => !a.historical))
+            fresh += 1;
+    }
+    const historical = item.evalRows.length - fresh;
+    const stale = Object.keys(item.staleReferences).length;
+    const notRun = item.missingEvalIds.length - stale;
+    return COVERAGE_SEGMENT_KEYS.map((key, i) => ({
+        label: localizedMessage(key),
+        count: [fresh, historical, stale, notRun][i],
+    }));
+}
+/** 覆盖构成副行的 key 前缀;测试与消费方靠它把这一行从 Eval / 组行里筛出去。 */
+export const COVERAGE_ROW_PREFIX = "coverage:";
+/**
+ * 覆盖构成副行(docs/feature/reports/components/summaries/experiment-table.md「覆盖构成」):
+ * experiment 行 subRows 的最后一条,把已知题按结论出身分成四段互斥的构成格,交给中立的
+ * `composition` 格——渲染在同一个 `record` 列位置(与 Eval / Attempt 行的判定构成、占位行的
+ * missing 格同一个槽位,三种形态各自对应不同的行语义,不是同一行的三种读法)。
+ * 它不是 Eval / 组行,没有身份(entity 是 notApplicable),不参与嵌套排序或收起判定。
+ */
+function coverageRow(item, view) {
+    const bag = {
+        entity: { kind: "notApplicable" },
+        record: { kind: "composition", segments: coverageSegments(item) },
+    };
+    return {
+        key: `${COVERAGE_ROW_PREFIX}${item.experimentId}`,
+        cells: projectCells(bag, view.columns),
+    };
+}
+/** experiment 的 evalRows + missingEvalIds → 递归嵌套的 subRows,末尾追加覆盖构成副行。 */
 function experimentSubRows(item, view) {
     const members = [
         ...item.evalRows.map((row) => ({ kind: "eval", row })),
         ...item.missingEvalIds.map((evalId) => ({ kind: "missing", evalId })),
     ];
-    return nestLevel(members, "", "", item, view);
+    const nested = nestLevel(members, "", "", item, view);
+    return members.length > 0 ? [...nested, coverageRow(item, view)] : nested;
 }
 function experimentRow(item, view) {
     const bag = {

package/dist/report/components/entity-lists/index.d.ts

@@ -1,6 +1,7 @@
+import type { TableContent } from "../../definition/cell.ts";
 import type { ReportInput } from "../../model/types.ts";
 import type { AttemptHandle, Sample } from "../../../record/types.ts";
-import type { ReportLocale } from "../../model/locale.ts";
+import { type ReportLocale } from "../../model/locale.ts";
 import { attemptRowsOf } from "./compute.ts";
 export { validateAttemptListData, validateEvalListData, validateExperimentListData } from "./validate.ts";
 export interface FailureListProps {
@@ -24,5 +25,24 @@ export interface ExperimentTableProps {
     locale?: ReportLocale;
     className?: string;
 }
+interface ExperimentTableViewProps {
+    fullContent: TableContent;
+    /** 只在 Sample 里确有历史执行或过期结论时才非 null——开关是否出现由这个字段的存在与否决定。 */
+    freshContent: TableContent | null;
+    sort?: string;
+    searchable?: boolean;
+    locale?: ReportLocale;
+    className?: string;
+}
+/**
+ * `ExperimentTable` 的渲染叶子:web 面在有 `freshContent` 时叠一层「只看新执行」开关——
+ * 两份 Content 都已经由 `ExperimentTable` 按 fresh 与非 fresh 两态重新投影好,`Table` 原语
+ * 本身不知道这个开关存在(本体里没有任何时效分支,语义全部住在投影层)。切换纯靠原生
+ * checkbox 状态经 CSS `:has()` 驱动的可见性完成(styles.css `.niceeval-fresh-toggle`),
+ * 不重新请求或重新计算任何数据,也不需要 JavaScript——初始态(未勾选)展示 `fullContent`
+ * 这份完整表。text 面没有这个开关的等价物,`--fresh` CLI 选项就是它的入口,这里只渲染
+ * `fullContent`。
+ */
+export declare const ExperimentTableView: import("../../definition/tree.ts").ReportComponent<ExperimentTableViewProps>;
 export declare const ExperimentTable: import("../../definition/tree.ts").ReportComponent<ExperimentTableProps>;
 export { attemptRowsOf };

package/dist/report/components/entity-lists/index.js

@@ -1,9 +1,10 @@
-import { jsx as _jsx } from "react/jsx-runtime";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 // 实体列表组合件:FailureList / AttemptList；列表本体是 Table 原语。
 import { defineComponent } from "../../definition/tree.js";
 import { TableContentView } from "../../definition/primitives.js";
 import { collectItems, locatorOf, resolveInput } from "../../model/aggregate.js";
-import { attemptListData, attemptRowsOf } from "./compute.js";
+import { localeText } from "../../model/locale.js";
+import { attemptListData, attemptRowsOf, hasHistoricalOrStale } from "./compute.js";
 import { attemptListContent, experimentListContent } from "./content.js";
 import { toAttemptRows, toExperimentRows } from "../../model/conversions.js";
 export { validateAttemptListData, validateEvalListData, validateExperimentListData } from "./validate.js";
@@ -35,13 +36,45 @@ export const AttemptList = defineComponent(async (props) => {
     return _jsx(TableContentView, { data: attemptListContent(rows), locale: props.locale, className: props.className });
 });
 AttemptList.displayName = "AttemptList";
+/**
+ * `ExperimentTable` 的渲染叶子:web 面在有 `freshContent` 时叠一层「只看新执行」开关——
+ * 两份 Content 都已经由 `ExperimentTable` 按 fresh 与非 fresh 两态重新投影好,`Table` 原语
+ * 本身不知道这个开关存在(本体里没有任何时效分支,语义全部住在投影层)。切换纯靠原生
+ * checkbox 状态经 CSS `:has()` 驱动的可见性完成(styles.css `.niceeval-fresh-toggle`),
+ * 不重新请求或重新计算任何数据,也不需要 JavaScript——初始态(未勾选)展示 `fullContent`
+ * 这份完整表。text 面没有这个开关的等价物,`--fresh` CLI 选项就是它的入口,这里只渲染
+ * `fullContent`。
+ */
+export const ExperimentTableView = defineComponent({
+    dimensions: () => ({}),
+    web(props, ctx) {
+        const table = (_jsx(TableContentView, { data: props.fullContent, sort: props.sort, searchable: props.searchable, locale: props.locale, className: props.className }));
+        if (!props.freshContent)
+            return table;
+        const locale = props.locale ?? ctx.locale;
+        return (_jsxs("div", { className: "niceeval-report niceeval-experiment-table", children: [_jsxs("label", { className: "niceeval-fresh-toggle", children: [_jsx("input", { type: "checkbox" }), localeText(locale, "experimentTable.freshOnlyToggle")] }), _jsx("div", { className: "niceeval-fresh-all", children: table }), _jsx("div", { className: "niceeval-fresh-only", children: _jsx(TableContentView, { data: props.freshContent, sort: props.sort, searchable: props.searchable, locale: props.locale, className: props.className }) })] }));
+    },
+    text(props, ctx) {
+        return ctx.render(_jsx(TableContentView, { data: props.fullContent, sort: props.sort, searchable: props.searchable, locale: props.locale, className: props.className }));
+    },
+});
+ExperimentTableView.displayName = "ExperimentTableView";
 export const ExperimentTable = defineComponent(async (props, ctx) => {
-    const items = await toExperimentRows(props.input ?? ctx.scope);
-    const content = experimentListContent(items);
-    const hasPassRate = content.columns.some((column) => column.key === "passRate");
-    const hasTotalScore = content.columns.some((column) => column.key === "totalScore");
+    const sample = props.input ?? ctx.scope;
+    const full = await toExperimentRows(sample);
+    const fullContent = experimentListContent(full);
+    const hasPassRate = fullContent.columns.some((column) => column.key === "passRate");
+    const hasTotalScore = fullContent.columns.some((column) => column.key === "totalScore");
     const defaultSort = hasPassRate === hasTotalScore ? undefined : hasPassRate ? "passRate" : "totalScore";
-    return (_jsx(TableContentView, { data: content, sort: props.sort ?? defaultSort, searchable: props.searchable ?? true, locale: props.locale, className: props.className }));
+    const freshContent = hasHistoricalOrStale(full)
+        ? experimentListContent(await toExperimentRows(sample.freshOnly()))
+        : null;
+    // 没有历史执行也没有过期结论时直接产出 `<TableContentView>`,与开关引入前的树形状逐字相同——
+    // 只有真的需要开关那一态,才多绕一层 `ExperimentTableView`。
+    if (freshContent === null) {
+        return (_jsx(TableContentView, { data: fullContent, sort: props.sort ?? defaultSort, searchable: props.searchable ?? true, locale: props.locale, className: props.className }));
+    }
+    return (_jsx(ExperimentTableView, { fullContent: fullContent, freshContent: freshContent, sort: props.sort ?? defaultSort, searchable: props.searchable ?? true, locale: props.locale, className: props.className }));
 });
 ExperimentTable.displayName = "ExperimentTable";
 // re-export for callers that still import attemptRowsOf locally

package/dist/report/components/entity-lists/validate.js

@@ -40,8 +40,22 @@ function attemptListItemProblem(value, path) {
         return `"${path}.startedAt" must be a string`;
     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 or omitted`;
+    }
+    if (typeof value.locator !== "string")
+        return `"${path}.locator" must be a string`;
+    return null;
+}
+function staleConclusionReferenceProblem(value, path) {
+    if (!isObject(value))
+        return `"${path}" must be an object`;
     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;
 }
 export const validateExperimentListData = (data) => arrayProblem(data, "data", (item, path) => {
@@ -81,6 +95,13 @@ export const validateExperimentListData = (data) => arrayProblem(data, "data", (
     const missingProblem = arrayProblem(item.missingEvalIds, `${path}.missingEvalIds`, (id, idPath) => typeof id === "string" ? null : `"${idPath}" must be a string`);
     if (missingProblem !== null)
         return missingProblem;
+    if (!isObject(item.staleReferences))
+        return `"${path}.staleReferences" must be an object`;
+    for (const [evalId, reference] of Object.entries(item.staleReferences)) {
+        const referenceProblem = staleConclusionReferenceProblem(reference, `${path}.staleReferences.${evalId}`);
+        if (referenceProblem !== null)
+            return referenceProblem;
+    }
     if (typeof item.lastRunAt !== "string")
         return `"${path}.lastRunAt" must be a string`;
     return arrayProblem(item.evalRows, `${path}.evalRows`, (row, rowPath) => {

package/dist/report/components/fixtures.js

@@ -281,6 +281,7 @@ export const experimentListItems = [
         attempts: 3,
         historicalAttempts: 0,
         missingEvalIds: [],
+        staleReferences: {},
         lastRunAt: "2026-07-01T10:00:00Z",
         evalRows: [
             {
@@ -321,6 +322,7 @@ export const experimentListItems = [
         attempts: 1,
         historicalAttempts: 0,
         missingEvalIds: [],
+        staleReferences: {},
         lastRunAt: "2026-07-01T11:30:00Z",
         evalRows: [
             {

package/dist/report/definition/cell.d.ts

@@ -25,6 +25,10 @@ export type Cell = {
     readonly counts?: VerdictCounts;
     /** 计票覆盖的 attempt 引用(有证据可下钻的计票格才携带,如稳定性矩阵)。 */
     readonly refs?: readonly AttemptLocator[];
+    /** 单判定形态历史执行的距今毫秒数;新执行时省略,不伪造 0(与 locator 格同一条纪律)。 */
+    readonly staleSinceMs?: number;
+    /** 单判定形态省略判定词、只留判定符(如对照矩阵逐格只放得下一个符号的场景)。 */
+    readonly bare?: boolean;
 } | {
     readonly kind: "score";
     readonly earned: number;
@@ -48,6 +52,24 @@ export type Cell = {
 } | {
     readonly kind: "missing";
     readonly code: string;
+    /** 补上这一格的命令,可直接复制(如 `niceeval exp <experimentId>`)。 */
+    readonly detail?: string;
+    /**
+     * 记录里存在、但与当前基准不可比的最近一条判定;不进任何计数,两面都降饱和显示,
+     * 只提供 locator 下钻(docs/feature/reports/library/presentation.md「missing 格的完整形状」)。
+     */
+    readonly reference?: {
+        readonly locator: AttemptLocator;
+        readonly verdict: Verdict | "skipped";
+        readonly staleSinceMs: number;
+    };
+} | {
+    readonly kind: "composition";
+    /** 段名由投影按 locale 给出;Table 不认识段的业务含义,只按声明序渲染,计数为零的段不显示。 */
+    readonly segments: readonly {
+        readonly label: LocalizedText;
+        readonly count: number;
+    }[];
 };
 export interface ColumnSpec {
     readonly key: string;

package/dist/report/definition/cell.js

@@ -1,6 +1,6 @@
 // 官方表格数据协议的单元格类型(docs/feature/reports/components/primitives/table.md「单元格类型」)。
 // Table / Grid / Stat 共用这份判别联合;自定义 Source 要交给这些原语必须适配成这个形状。
-import { formatMetricValue, missingText, verdictMark } from "../model/format.js";
+import { formatMetricValue, formatTimeDistance, missingText, verdictMark } from "../model/format.js";
 import { DEFAULT_REPORT_LOCALE, localeText, resolveLocalizedText, } from "../model/locale.js";
 /** 把 Cell 折成 text 面可见字符串(缺数据 / 不适用统一不补成 0)。 */
 export function formatCellText(cell, locale) {
@@ -9,12 +9,18 @@ export function formatCellText(cell, locale) {
     switch (cell.kind) {
         case "notApplicable":
             return "—";
-        case "missing":
-            return missingText(cell.code, locale ?? DEFAULT_REPORT_LOCALE);
+        case "missing": {
+            const loc = locale ?? DEFAULT_REPORT_LOCALE;
+            // 带参考时用参考替代原因文案——参考本身已经说明这一格为什么空着,不把同一句话说两遍。
+            const reason = cell.reference
+                ? `${verdictMark(cell.reference.verdict === "skipped" ? "skipped" : cell.reference.verdict)} ${cell.reference.locator} ${formatTimeDistance(cell.reference.staleSinceMs, loc)}`
+                : missingText(cell.code, loc);
+            return cell.detail ? `${reason} · ${cell.detail}` : reason;
+        }
         case "text":
             return cell.detail ? `${cell.text}\n  ${cell.detail}` : cell.text;
         case "locator": {
-            const stale = cell.staleSinceMs !== undefined ? ` ↩ ${formatStale(cell.staleSinceMs)}` : "";
+            const stale = cell.staleSinceMs !== undefined ? ` ${formatTimeDistance(cell.staleSinceMs, locale ?? DEFAULT_REPORT_LOCALE)}` : "";
             const mark = cell.verdict !== undefined ? `${verdictMark(cell.verdict === "skipped" ? "skipped" : cell.verdict)} ` : "";
             return `${mark}${cell.locator}${stale}`;
         }
@@ -34,8 +40,12 @@ export function formatCellText(cell, locale) {
             }
             if (cell.verdict !== undefined) {
                 const v = cell.verdict === "skipped" ? "skipped" : cell.verdict;
+                const stale = cell.staleSinceMs !== undefined ? ` ${formatTimeDistance(cell.staleSinceMs, loc)}` : "";
                 // 判定符与判定词同场,与 locator 格、web 面同一条纪律:单色打印下照样读得出。
-                return `${verdictMark(v)} ${localeText(loc, `verdict.${v}`)}`;
+                // bare 省略判定词,只留判定符(+ 可选时距),供逐格空间紧张的场景(如对照矩阵)使用。
+                if (cell.bare)
+                    return `${verdictMark(v)}${stale}`;
+                return `${verdictMark(v)} ${localeText(loc, `verdict.${v}`)}${stale}`;
             }
             return "—";
         }
@@ -43,6 +53,14 @@ export function formatCellText(cell, locale) {
             const m = cell.metric;
             return formatMetricValue(m.value, m.unit, m.format, locale ?? DEFAULT_REPORT_LOCALE);
         }
+        case "composition": {
+            const loc = locale ?? DEFAULT_REPORT_LOCALE;
+            // text 面退化成与判定计票同构的计数串,与「计数为零的段不出现」同一条规则。
+            const parts = cell.segments
+                .filter((segment) => segment.count > 0)
+                .map((segment) => `${segment.count} ${resolveLocalizedText(segment.label, loc)}`);
+            return parts.join(" · ") || "—";
+        }
         default: {
             const _exhaustive = cell;
             return _exhaustive;
@@ -76,7 +94,3 @@ export function flattenTableContentForText(content, locale) {
         walk(row, 0);
     return { columns, rows };
 }
-function formatStale(ms) {
-    const days = Math.max(1, Math.round(ms / 86_400_000));
-    return `${days}d`;
-}