niceeval 0.5.4 → 0.6.0

package/dist/report/web.js

@@ -0,0 +1,37 @@
+// web 宿主(view --report)的装载入口:同一棵树走 web 面,renderToStaticMarkup 吐静态
+// HTML 烘进查看器的报告槽。只有这一侧真正 import react-dom(import 边界即运行时边界),
+// 所以本文件不从 niceeval/report 的入口 re-export —— 宿主与测试按源路径 import。
+import * as React from "react";
+import { renderToStaticMarkup } from "react-dom/server";
+import { resolveReportTree, runWithWebContext, validateReportTree } from "./tree.js";
+import { DEFAULT_REPORT_LOCALE } from "./locale.js";
+/**
+ * 挑选警告的 HTML 形态:宿主级前置块,与 RunOverview 里的警告用同一套结构和类名
+ * (`.nre nre-report-warnings` 外壳内一个 `ul.nre-warnings` + `li.nre-warning[data-kind]`,
+ * 复用 styles.css 已有的 `.nre .nre-warnings` 样式)。经 renderToStaticMarkup 走 React,
+ * message 文本自动转义,不裸拼 HTML。裸跑 / --report 都在报告顶上如实报残缺,不静默。
+ */
+function renderSelectionWarningsHtml(warnings) {
+    return renderToStaticMarkup(React.createElement("div", { className: "nre nre-report-warnings" }, React.createElement("ul", { className: "nre-warnings" }, warnings.map((w, i) => React.createElement("li", { key: i, className: "nre-warning", "data-kind": w.kind }, w.message)))));
+}
+/**
+ * build → 渲染前解析数据组件(唯一的 await 边界)→ 树校验(与 text 宿主同一遍)→ 静态渲染
+ * web 面;Selection 有挑选警告时在报告顶部前置一块警告 HTML；报告树里的 RunOverview
+ * 已经渲染同一条时不重复。
+ */
+export async function renderReportToStaticHtml(definition, ctx, options) {
+    const node = await definition.build(ctx);
+    const resolved = await resolveReportTree(node);
+    validateReportTree(resolved);
+    const webCtx = {
+        attemptHref: options?.attemptHref ?? ((locator) => `#/attempt/${locator}`),
+        locale: options?.locale ?? DEFAULT_REPORT_LOCALE,
+    };
+    const body = runWithWebContext(webCtx, () => renderToStaticMarkup(resolved));
+    const missingWarnings = ctx.selection.warnings.filter((warning) => {
+        const escapedMessage = renderToStaticMarkup(React.createElement(React.Fragment, null, warning.message));
+        return !body.includes(escapedMessage);
+    });
+    const warnings = missingWarnings.length > 0 ? renderSelectionWarningsHtml(missingWarnings) : "";
+    return warnings + body;
+}

package/dist/results/annotated-source.d.ts

@@ -0,0 +1,61 @@
+import type { AssertionResult } from "../types.ts";
+/** 一行源码 + 映射到这一行的全部断言(保持原始顺序;可以是空数组)。 */
+export interface AnnotatedSourceLine {
+    /** 1-indexed 行号,与 SourceLoc.line 同一坐标系。 */
+    line: number;
+    /** 这一行的原始文本(已按 normalizeEvalSource 归一化,不含行尾换行符)。 */
+    text: string;
+    /**
+     * 映射到这一行的断言,按输入顺序(通常即执行顺序)排列。每条断言自带 severity / score /
+     * passed / detail / evidence —— 这就是"状态 / 严重度 / 分数 / detail / evidence"标回源码行
+     * 的完整信息,不需要额外的行级折叠字段:折叠成单一显示态是 renderer 的展示决定,不是这份
+     * 领域 model 的职责(与 indexAsserts() 的先例一致,它同样只分桶、不折叠)。
+     */
+    assertions: AssertionResult[];
+}
+export interface AnnotatedEvalSourceSummary {
+    /** 参与统计的断言总数 = mappedAssertions + unmappedAssertions。 */
+    totalAssertions: number;
+    /** 成功映射到某一行源码的断言数。 */
+    mappedAssertions: number;
+    /** 落进 unmapped 桶的断言数。 */
+    unmappedAssertions: number;
+    /** 按 passed 计票(映射与未映射的断言都计入)。 */
+    passed: number;
+    failed: number;
+    /** 按 severity 计票(映射与未映射的断言都计入)。 */
+    gate: number;
+    soft: number;
+    /** 源码总行数,等于 lines.length。 */
+    totalLines: number;
+    /** 至少挂了一条断言的行数。 */
+    annotatedLines: number;
+}
+export interface AnnotatedEvalSource {
+    /** 项目相对路径,与 SourceArtifact.path / SourceLoc.file 同一约定。 */
+    sourcePath: string;
+    /** 归一化后源码文本的 SHA-256(与 captureEvalSource() 的算法一致,见 source-hash.ts)。 */
+    sourceSha256: string;
+    lines: AnnotatedSourceLine[];
+    /**
+     * 没有落到 lines 里任何一行的断言,原始顺序保留,永不丢弃。三种情况都进这里:
+     * 没有 SourceLoc(如 skip 前就出错的 eval、或调用方尚未收集到位置)、SourceLoc 指向
+     * 另一个文件(loc.file !== sourcePath —— 罕见,如断言写在共享 helper 里)、
+     * SourceLoc 的行号落在这份源码的行范围之外(源码与断言记录不同步的边界情况)。
+     * 后两种不是文档明确要求的场景,但"never silently dropped"的契约对它们同样成立 ——
+     * 这份 model 是分桶断言的唯一出口,不属于任何一行就必须出现在这里。
+     */
+    unmapped: AssertionResult[];
+    summary: AnnotatedEvalSourceSummary;
+}
+/**
+ * 纯函数:给定一份源码文本(未归一化也可以,内部会 normalizeEvalSource)与一批断言,
+ * 产出标注好的 AnnotatedEvalSource。幂等 / 无 IO —— 可以在渲染路径上安全调用。
+ *
+ * 断言 → 源码行的映射规则:`a.loc` 存在、`a.loc.file === source.path`、且
+ * `1 <= a.loc.line <= lines.length` 三者同时成立才落到对应行;否则进 `unmapped`。
+ */
+export declare function buildAnnotatedEvalSource(source: {
+    path: string;
+    content: string;
+}, assertions: readonly AssertionResult[]): AnnotatedEvalSource;

package/dist/results/attempt-evidence.d.ts

@@ -0,0 +1,69 @@
+import type { AttemptHandle } from "./types.ts";
+import { type AttemptIdentity, type AttemptLocator } from "./locator.ts";
+import type { AnnotatedEvalSource } from "./annotated-source.ts";
+import { type ExecutionTree } from "../o11y/execution-tree.ts";
+import type { DiffData, EvalResult } from "../types.ts";
+/**
+ * 一个 Attempt 的 artifact 落盘位置。单一目录足够:一个 attempt 的全部 artifact
+ * (events.json / trace.json / o11y.json / diff.json / sources.json,见 ARTIFACT_KINDS)
+ * 要么全在它自己的 attempt 目录,要么(--resume 携带条目——本轮没写任何新数据,
+ * 见 writer.ts 对携带分支的说明)全在 artifactBase 回退到的原快照 attempt 目录,
+ * 从不出现"这个 kind 在自己目录、那个 kind 在 artifactBase"的拆分场景,不需要
+ * 按 kind 逐个给路径。想要某一种 artifact 的具体文件,自己拼
+ * `join(artifactPaths.dir, "<kind>.json")`(kind 见 `ArtifactKind`)。
+ *
+ * 与 show/render.ts 的 `attemptArtifactsPath(attempt, cwd)` 是同一份"这个 attempt 的证据在哪"
+ * 知识的两种呈现:那边为 CLI 文本展示把它转成 cwd 相对的短路径,这里给 evidence 层的调用方
+ * (view / 静态导出 / 报告列表,它们没有统一的"cwd"概念)一份绝对路径,不做相对化。
+ */
+export interface EvidencePaths {
+    /** 绝对路径。 */
+    dir: string;
+}
+/**
+ * 每一位只在数据真的存在且非空时为 true——从不因为对应的 artifact 文件"存在"就点亮,
+ * 见本文件头注逐位的门槛说明。show/view/静态导出/报告列表读这四位来决定要不要显示
+ * 对应的证据切面,不自己重新判断"这个 attempt 有没有 X"。
+ */
+export interface AttemptEvidenceCapabilities {
+    /** evalSource 非空且有内容(源码行或断言二选一非空)。 */
+    eval: boolean;
+    /** events 非空数组——有骨架可看。 */
+    execution: boolean;
+    /** execution 成立且这次运行接入过 OTel(ExecutionTree.timingAvailable)。 */
+    timing: boolean;
+    /** diff 非空且至少改动/删除了一个文件。 */
+    diff: boolean;
+}
+/**
+ * 一个 Attempt 的完整证据聚合。除 `locator` 外每个字段要么是别的模块已经产出的纯数据类型,
+ * 要么是这四样拼出来的判定——本类型自己不发明新的证据形状。
+ */
+export interface AttemptEvidence {
+    locator: AttemptLocator;
+    /** locator 派生自的不可变身份元组,与 `locator` 编码的是同一份数据,供不想解码 locator
+     * 的调用方直接读结构化字段(如按 experimentId 分组、按时间排序)。 */
+    identity: AttemptIdentity;
+    result: EvalResult;
+    /** 运行时保存的 Eval 源码标注(`--eval` 切面);没有 sources() 就是 null,不伪造空文档。 */
+    evalSource: AnnotatedEvalSource | null;
+    /** 标准事件流 + OTel enrichment(`--execution` 切面);没有非空 events 就是 null,
+     * 不产出一棵只剩 telemetry-only 节点、没有真实骨架的误导性树(见头注 execution 门槛)。 */
+    execution: ExecutionTree | null;
+    /** 被测 Agent 对 Sandbox 工作区的文件变化(`--diff` 切面);原样透传 attempt.diff()。 */
+    diff: DiffData | null;
+    artifactPaths: EvidencePaths;
+    capabilities: AttemptEvidenceCapabilities;
+}
+/**
+ * 纯组合:一次性 await 好 attempt 的四类懒加载证据(events / trace / diff / 经
+ * loadAnnotatedEvalSource 解引用的 eval 源码),拼成一份 AttemptEvidence。不重新实现
+ * Eval 源码标注、ExecutionTree 合并或 diff 语义的任何一条规则——那些规则的家分别在
+ * annotated-source.ts / execution-tree.ts / attempt.diff() 自身,这里只调用与判定"够不够
+ * 亮起对应的证据切面"。
+ *
+ * `attempt.locator` 在真实读取路径(openResults() 产出的 handle)恒有值;缺失时按当前身份
+ * 元组按 encodeAttemptLocator 兜底算一份,同 open.ts 给 record.locator 做的兜底同一口径——
+ * 只服务手工构造 AttemptHandle 的测试场景,不改变真实读取路径的行为。
+ */
+export declare function loadAttemptEvidence(attempt: AttemptHandle): Promise<AttemptEvidence>;

package/dist/results/attempt-source.d.ts

@@ -0,0 +1,15 @@
+import type { AttemptHandle } from "./types.ts";
+import { type AnnotatedEvalSource } from "./annotated-source.ts";
+/**
+ * 给定一个 attempt,取回它的 eval 源码(经 sources() 解引用,可能来自本快照或
+ * artifactBase 回退到的原快照)与它的断言,产出标注好的 AnnotatedEvalSource。
+ *
+ * 没有 sources()(eval 从没被 `loc` 引用到、或落盘里压根没有 sources.json/artifactBase
+ * 已失效)时返回 null——没有源码就没有「标注源码」这回事,不伪造一份空文档。
+ *
+ * 一个 attempt 的 sources() 理论上可以有多份文件(主 eval 文件 + 罕见的跨文件 loc);
+ * 这里按「哪份文件被最多断言的 loc 命中」选一份作为主文件喂给 buildAnnotatedEvalSource——
+ * 只服务这条打通链路的验证目的,不是最终选择策略(后续阶段如需要为每份引用到的文件
+ * 都出一份 AnnotatedEvalSource,在这基础上很容易扩成返回数组)。
+ */
+export declare function loadAnnotatedEvalSource(attempt: AttemptHandle): Promise<AnnotatedEvalSource | null>;

package/dist/results/locator.d.ts

@@ -0,0 +1,75 @@
+/** 不透明的 Attempt 定位符:`@` + 1 位 scheme 字符 + 定长 base36 body。字符串品牌,防止和普通 string 混用。 */
+export type AttemptLocator = string & {
+    readonly __brand: "AttemptLocator";
+};
+/** locator 派生自的不可变身份元组;attempt 是 EvalResult.attempt 的 0-indexed 值,不是展示用的 1-indexed 序号。 */
+export interface AttemptIdentity {
+    experimentId: string;
+    /** SnapshotMeta.startedAt 字段(不是快照目录名——两者通常但不总是相等,见 writer.ts 的说明)。 */
+    snapshotStartedAt: string;
+    evalId: string;
+    /** 0-indexed;展示层(CLI/show)在边界处 +1,身份本身永远用内部下标。 */
+    attempt: number;
+}
+/** locator 前缀,恒为 `@`;与 Eval id 前缀在 CLI 位置参数解析里无歧义(eval id 不以 `@` 起头)。 */
+export declare const ATTEMPT_LOCATOR_PREFIX = "@";
+/**
+ * 确定性、带版本编码:同一身份元组永远产出同一 locator;scheme 版本混进哈希输入,
+ * 一旦编码规则升级(scheme 号递增),新旧两代 locator 天然落在不同哈希空间,不会互相撞车。
+ */
+export declare function encodeAttemptLocator(identity: AttemptIdentity): AttemptLocator;
+/** decodeAttemptLocator 的结果:locator 是身份的单向哈希,这里只判断字符串本身合不合法,不还原身份元组。 */
+export type LocatorDecodeResult = {
+    valid: true;
+    scheme: number;
+} | {
+    valid: false;
+    reason: string;
+};
+/**
+ * 语法校验:`@` 前缀 + scheme 字符 + body。不查 body 是否真对应某个已知 Attempt——
+ * 那是 reader 建好的 locator → AttemptHandle 索引的事(resolveAttemptLocator)。
+ */
+export declare function decodeAttemptLocator(locator: string): LocatorDecodeResult;
+/** buildLocatorIndex 的输入项:一个已知 Attempt 的身份 + 调用方自己的句柄类型(通常是 AttemptHandle)。 */
+export interface LocatorAttempt<T> {
+    identity: AttemptIdentity;
+    handle: T;
+}
+/**
+ * 撞车:两个不同的身份元组独立编码出了同一个 locator 字符串。设计上应当极其罕见
+ * (见 BODY_LENGTH 的空间量级),但绝不能被静默吞掉——reader 打开结果根时一旦命中,
+ * 直接抛出,交给上层(未来的 CLI 层)决定怎么给用户看。
+ */
+export declare class LocatorCollisionError extends Error {
+    readonly locator: AttemptLocator;
+    readonly identities: readonly [AttemptIdentity, AttemptIdentity];
+    constructor(locator: AttemptLocator, identities: readonly [AttemptIdentity, AttemptIdentity]);
+}
+/**
+ * 批量建 locator → 句柄索引。同一身份元组出现多次(如 --resume 携带条目在新旧两个快照里
+ * 都能被扫描到,身份沿用原 Attempt 不变)不算撞车,后出现的覆盖先出现的;真正撞车
+ * ——两个不同身份编码同一个字符串——才抛 LocatorCollisionError。
+ *
+ * @param encode @internal 仅供测试注入确定性会撞车的编码函数;生产调用不传,用默认实现。
+ */
+export declare function buildLocatorIndex<T>(attempts: Iterable<LocatorAttempt<T>>, encode?: (identity: AttemptIdentity) => AttemptLocator): Map<AttemptLocator, T>;
+/** resolveAttemptLocator 的结果:found / malformed / not-found 三种失败模式互相区分,不折叠成一个 Error。 */
+export type LocatorResolution<T> = {
+    kind: "found";
+    locator: AttemptLocator;
+    handle: T;
+} | {
+    kind: "malformed";
+    input: string;
+    reason: string;
+} | {
+    kind: "not-found";
+    locator: AttemptLocator;
+};
+/**
+ * 拿用户输入的原始字符串(通常来自 CLI 的 `@...` 位置参数)在已建好的索引里查找。
+ * 先语法校验(decodeAttemptLocator),语法都不对就不必查索引;语法对但索引里没有 ——
+ * 已损坏、已过期(指向被清理的快照)、或纯粹打错——一律 not-found,由调用方决定怎么提示。
+ */
+export declare function resolveAttemptLocator<T>(index: ReadonlyMap<AttemptLocator, T>, input: string): LocatorResolution<T>;

package/dist/results/select.d.ts

@@ -0,0 +1,45 @@
+import type { AttemptHandle, DedupeWarning, Experiment, Results, Selection, SelectionWarning, Snapshot } from "./types.ts";
+/** Results.latest() 的实现:每个实验取最新一次快照(= exp.snapshots[0]),生成挑选警告。 */
+export declare function selectLatest(experiments: Experiment[], opts?: {
+    experiments?: string | string[];
+}): Selection;
+/** selectCurrentResults 的范围输入:experiment id 前缀与 eval id 前缀,都可缺省。 */
+export interface ResultScope {
+    /** experiment id 前缀(--experiment),分段匹配语义同 filterExperiments。 */
+    experiment?: string;
+    /** eval id 前缀(位置参数),收窄 Selection 覆盖的 eval;覆盖警告分母同步收窄到范围内。 */
+    patterns?: string[];
+}
+/**
+ * 两个宿主(show / view)共用的现刻水位选择器:每个 experiment × eval 取时间上最新的那份
+ * 判定,跨 run 合成。results.latest() 只挑「每实验最新快照」,带 eval 前缀的局部重跑会产出
+ * 残缺快照;现刻水位承诺「不会因为一次局部重跑变残缺」,所以在实验的全部历史快照上逐 eval
+ * 向更早的 run 补齐,再把合成好的 Selection 交给宿主注入报告槽——内置默认报告与 --report 吃
+ * 同一份。
+ *
+ * 同一 eval 的全部 attempts 必须整批取自包含它的最新快照,不把历史快照的 attempts 平铺后
+ * 按 eval 聚合——否则会把不同运行的重试混成一次虚构运行。合成快照的 dir/元数据只服务报告
+ * 分组与来源展示,证据身份一律来自 attempt 自己的 ref。
+ * 警告随 Selection 重算:partial-coverage 的分母 = 已知并集 ∩ 范围(范围收窄时分母同步收窄,
+ * 不让范围外的缺口刷屏);stale / unfinished 与 results.latest() 同口径。
+ */
+export declare function selectCurrentResults(results: Results, scope?: ResultScope): Selection;
+/**
+ * Selection 构造:filter 只删不换 —— 快照删减,warnings 修剪规则是
+ * 「experimentId 不在幸存快照中的丢弃,非实验作用域的保留」(为将来非 per-experiment 的 kind 留位置)。
+ */
+export declare function makeSelection(snapshots: Snapshot[], warnings: SelectionWarning[]): Selection;
+/**
+ * 跨快照聚合前的身份键去重:(experimentId, evalId, attempt, startedAt)。
+ * --resume 会把上一轮已通过的结果原样合入新快照,同一 attempt 因此存在于多份落盘;
+ * 重复时保留最新快照里的那份(内容相同,取新快照的副本让 ref 落在最新落盘上;
+ * 位置取首次出现处,顺序稳定)。startedAt 缺失时宁可不去重也不误删,记入 warnings。
+ */
+export declare function dedupeAttempts(attempts: AttemptHandle[]): {
+    attempts: AttemptHandle[];
+    warnings: DedupeWarning[];
+};
+/** 快照新旧比较:startedAt 优先,同刻按快照目录名(时间戳 + 随机后缀,字典序即时序)。 */
+export declare function isNewerSnapshot(a: Snapshot, b: Snapshot): boolean;
+/** experiment id 分段前缀过滤(--experiment / latest({ experiments }) 同一语义);包内使用,不进公共 barrel。 */
+export declare function filterExperiments(experiments: Experiment[], filter?: string | string[]): Experiment[];

package/dist/results/select.js

@@ -0,0 +1,230 @@
+// 快照 Selection 与 attempt 去重(定稿见 docs/feature/results/library.md「选择快照」「身份键与去重」)。
+//
+// 选择器只有一个(latest),长在集合上;它不是 DSL,只是最常用的那次筛选。
+// 选择器必须诚实:残缺、落后、未收尾都被算出来,以结构化 warnings 随 Selection 走 ——
+// 渲染与否在消费方(message 是渲染好的英文句子),但缺口不静默。
+import { evalPrefixPredicate } from "../shared/aggregate.js";
+/** Results.latest() 的实现:每个实验取最新一次快照(= exp.snapshots[0]),生成挑选警告。 */
+export function selectLatest(experiments, opts) {
+    const selected = filterExperiments(experiments, opts?.experiments);
+    const snapshots = selected.map((exp) => exp.latest);
+    const warnings = [];
+    // stale 的基准:Selection 中最新的落盘(无阈值,如实触发;要阈值消费方按字段自比)。
+    let latestStartedAt = "";
+    for (const snapshot of snapshots) {
+        if (snapshot.startedAt > latestStartedAt)
+            latestStartedAt = snapshot.startedAt;
+    }
+    for (const exp of selected) {
+        const snapshot = exp.latest;
+        // 残缺检测:分母 = 该实验已知 eval 并集(本地历史 ∪ 各快照携带的 knownEvalIds)。
+        // 位置参数允许只重跑一道题,产出的「最新快照」可能只有一道题 —— 不能安静吞下。
+        const covered = snapshot.evals.length;
+        const total = exp.evalIds.length;
+        if (covered < total) {
+            warnings.push({
+                kind: "partial-coverage",
+                experimentId: exp.id,
+                covered,
+                total,
+                message: `snapshot covers ${covered} of ${total} evals seen in history; re-run \`niceeval exp ${exp.id}\` for a full snapshot`,
+            });
+        }
+        if (snapshot.startedAt < latestStartedAt) {
+            warnings.push({
+                kind: "stale-snapshot",
+                experimentId: exp.id,
+                startedAt: snapshot.startedAt,
+                latestStartedAt,
+                message: `snapshot "${exp.id}" (${snapshot.startedAt}) predates the latest run in this selection by ${humanizeGap(snapshot.startedAt, latestStartedAt)}`,
+            });
+        }
+        if (!snapshot.completedAt) {
+            warnings.push({
+                kind: "unfinished-snapshot",
+                experimentId: exp.id,
+                startedAt: snapshot.startedAt,
+                dir: snapshot.dir,
+                message: `snapshot "${exp.id}" (${snapshot.startedAt}) has no completedAt — the run was interrupted; results may be incomplete`,
+            });
+        }
+    }
+    return makeSelection(snapshots, warnings);
+}
+/**
+ * 两个宿主(show / view)共用的现刻水位选择器:每个 experiment × eval 取时间上最新的那份
+ * 判定,跨 run 合成。results.latest() 只挑「每实验最新快照」,带 eval 前缀的局部重跑会产出
+ * 残缺快照;现刻水位承诺「不会因为一次局部重跑变残缺」,所以在实验的全部历史快照上逐 eval
+ * 向更早的 run 补齐,再把合成好的 Selection 交给宿主注入报告槽——内置默认报告与 --report 吃
+ * 同一份。
+ *
+ * 同一 eval 的全部 attempts 必须整批取自包含它的最新快照,不把历史快照的 attempts 平铺后
+ * 按 eval 聚合——否则会把不同运行的重试混成一次虚构运行。合成快照的 dir/元数据只服务报告
+ * 分组与来源展示,证据身份一律来自 attempt 自己的 ref。
+ * 警告随 Selection 重算:partial-coverage 的分母 = 已知并集 ∩ 范围(范围收窄时分母同步收窄,
+ * 不让范围外的缺口刷屏);stale / unfinished 与 results.latest() 同口径。
+ */
+export function selectCurrentResults(results, scope = {}) {
+    const match = scope.patterns && scope.patterns.length > 0 ? evalPrefixPredicate(scope.patterns) : () => true;
+    const experiments = filterExperiments(results.experiments, scope.experiment);
+    const snapshots = [];
+    const warnings = [];
+    for (const exp of experiments) {
+        // 逐题取最新:快照按最新在前,首个出现即最新判定
+        const taken = new Map();
+        for (const snapshot of exp.snapshots) {
+            for (const ev of snapshot.evals) {
+                if (!match(ev.id) || taken.has(ev.id))
+                    continue;
+                taken.set(ev.id, { ev, snapshot });
+            }
+        }
+        if (taken.size === 0)
+            continue;
+        const picks = [...taken.values()].sort((a, b) => a.ev.id.localeCompare(b.ev.id));
+        let startedAt = "";
+        let newest = picks[0].snapshot;
+        for (const pick of picks) {
+            if (pick.snapshot.startedAt > startedAt) {
+                startedAt = pick.snapshot.startedAt;
+                newest = pick.snapshot;
+            }
+        }
+        const evals = picks.map((p) => p.ev);
+        const base = exp.latest;
+        snapshots.push({
+            experimentId: exp.id,
+            startedAt,
+            agent: base.agent,
+            ...(base.model !== undefined ? { model: base.model } : {}),
+            producer: base.producer,
+            schemaVersion: base.schemaVersion,
+            evals,
+            attempts: evals.flatMap((ev) => ev.attempts),
+            dir: newest.dir,
+            ...(newest.completedAt !== undefined ? { completedAt: newest.completedAt } : {}),
+            ...(base.knownEvalIds ? { knownEvalIds: [...base.knownEvalIds] } : {}),
+        });
+        // 残缺检测:跨快照补齐后仍缺,只可能是历史上见过(或 knownEvalIds 声明过)
+        // 却从未在可读落盘里出现的题 —— 分母收窄到范围内,不让范围外的缺口刷屏。
+        const total = exp.evalIds.filter(match).length;
+        if (evals.length < total) {
+            warnings.push({
+                kind: "partial-coverage",
+                experimentId: exp.id,
+                covered: evals.length,
+                total,
+                message: `verdicts cover ${evals.length} of ${total} evals seen in history; re-run \`niceeval exp ${exp.id}\` for a full snapshot`,
+            });
+        }
+    }
+    let latestStartedAt = "";
+    for (const snapshot of snapshots) {
+        if (snapshot.startedAt > latestStartedAt)
+            latestStartedAt = snapshot.startedAt;
+    }
+    for (const snapshot of snapshots) {
+        if (snapshot.startedAt < latestStartedAt) {
+            warnings.push({
+                kind: "stale-snapshot",
+                experimentId: snapshot.experimentId,
+                startedAt: snapshot.startedAt,
+                latestStartedAt,
+                message: `verdicts for "${snapshot.experimentId}" were produced at ${snapshot.startedAt}, before the latest run in this selection (${latestStartedAt})`,
+            });
+        }
+        if (snapshot.completedAt === undefined) {
+            warnings.push({
+                kind: "unfinished-snapshot",
+                experimentId: snapshot.experimentId,
+                startedAt: snapshot.startedAt,
+                dir: snapshot.dir,
+                message: `snapshot "${snapshot.experimentId}" (${snapshot.startedAt}) is unfinished (the process was interrupted); completed attempts are read as-is, but the set may be incomplete`,
+            });
+        }
+    }
+    return makeSelection(snapshots, warnings);
+}
+/**
+ * Selection 构造:filter 只删不换 —— 快照删减,warnings 修剪规则是
+ * 「experimentId 不在幸存快照中的丢弃,非实验作用域的保留」(为将来非 per-experiment 的 kind 留位置)。
+ */
+export function makeSelection(snapshots, warnings) {
+    return {
+        snapshots,
+        warnings,
+        filter(predicate) {
+            const kept = snapshots.filter(predicate);
+            const survivors = new Set(kept.map((s) => s.experimentId));
+            const keptWarnings = warnings.filter((w) => {
+                const scope = w.experimentId;
+                return typeof scope !== "string" || survivors.has(scope);
+            });
+            return makeSelection(kept, keptWarnings);
+        },
+    };
+}
+/**
+ * 跨快照聚合前的身份键去重:(experimentId, evalId, attempt, startedAt)。
+ * --resume 会把上一轮已通过的结果原样合入新快照,同一 attempt 因此存在于多份落盘;
+ * 重复时保留最新快照里的那份(内容相同,取新快照的副本让 ref 落在最新落盘上;
+ * 位置取首次出现处,顺序稳定)。startedAt 缺失时宁可不去重也不误删,记入 warnings。
+ */
+export function dedupeAttempts(attempts) {
+    const deduped = [];
+    const indexByKey = new Map();
+    const warnings = [];
+    for (const attempt of attempts) {
+        const r = attempt.result;
+        if (!r.startedAt) {
+            warnings.push({
+                kind: "missing-startedAt",
+                experimentId: attempt.experimentId,
+                evalId: attempt.evalId,
+                message: `attempt ${r.attempt} of eval "${attempt.evalId}" in experiment "${attempt.experimentId}" has no startedAt; kept as-is without dedupe`,
+            });
+            deduped.push(attempt);
+            continue;
+        }
+        const key = JSON.stringify([attempt.experimentId, r.id, r.attempt, r.startedAt]);
+        const existing = indexByKey.get(key);
+        if (existing === undefined) {
+            indexByKey.set(key, deduped.length);
+            deduped.push(attempt);
+        }
+        else if (isNewerSnapshot(attempt.snapshot, deduped[existing].snapshot)) {
+            deduped[existing] = attempt;
+        }
+    }
+    return { attempts: deduped, warnings };
+}
+/** 快照新旧比较:startedAt 优先,同刻按快照目录名(时间戳 + 随机后缀,字典序即时序)。 */
+export function isNewerSnapshot(a, b) {
+    const byStart = a.startedAt.localeCompare(b.startedAt);
+    if (byStart !== 0)
+        return byStart > 0;
+    return a.dir.localeCompare(b.dir) > 0;
+}
+/** experiment id 分段前缀过滤(--experiment / latest({ experiments }) 同一语义);包内使用,不进公共 barrel。 */
+export function filterExperiments(experiments, filter) {
+    if (filter === undefined)
+        return experiments;
+    // 允许 "compare/" 这种带尾斜杠的写法,与 "compare" 等价;分段匹配不误配 "compare2"。
+    const prefixes = (Array.isArray(filter) ? filter : [filter]).map((p) => p.replace(/\/+$/, ""));
+    return experiments.filter((exp) => prefixes.some((p) => exp.id === p || exp.id.startsWith(p + "/")));
+}
+/** stale 警告的人话时距:选粒度最大的单位,四舍五入。 */
+function humanizeGap(fromIso, toIso) {
+    const ms = Math.max(0, Date.parse(toIso) - Date.parse(fromIso));
+    const seconds = Math.round(ms / 1000);
+    if (seconds < 90)
+        return `${seconds} second${seconds === 1 ? "" : "s"}`;
+    const minutes = Math.round(seconds / 60);
+    if (minutes < 90)
+        return `${minutes} minute${minutes === 1 ? "" : "s"}`;
+    const hours = Math.round(minutes / 60);
+    if (hours < 36)
+        return `${hours} hour${hours === 1 ? "" : "s"}`;
+    const days = Math.round(hours / 24);
+    return `${days} day${days === 1 ? "" : "s"}`;
+}

package/dist/results/source-hash.d.ts

@@ -0,0 +1,9 @@
+/**
+ * 归一化 eval 源码文本:去 UTF-8 BOM、把 CRLF / CR 统一成 LF。
+ * 幂等——已归一化的文本再跑一次结果不变,所以 capture 时归一化一次、重建时可以放心再跑一次,
+ * 两处算出的 SHA-256 恒相同。不做其它改写(不 trim 行尾空白、不折叠空行):
+ * 行号是断言 SourceLoc 的锚,任何改变行结构的归一化都会让映射错位。
+ */
+export declare function normalizeEvalSource(text: string): string;
+/** 对(已归一化的)源码文本算 SHA-256 十六进制摘要。 */
+export declare function hashEvalSource(content: string): string;