niceeval 0.5.4 → 0.6.1

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/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;

package/dist/results/types.d.ts

@@ -0,0 +1,204 @@
+import type { EvalResult, ExperimentRunInfo, LocalizedText } from "../types.ts";
+import type { O11ySummary, StreamEvent, TraceSpan } from "../types.ts";
+import type { AgentSetupManifest, DiffData, SourceArtifact } from "../types.ts";
+import type { AttemptLocator } from "./locator.ts";
+/** attempt 级 artifact 的种类;文件名见 format.ts 的 artifactFileOf,布局见 docs/feature/results/architecture.md。 */
+export declare const ARTIFACT_KINDS: readonly ["events", "trace", "o11y", "agentSetup", "diff", "sources"];
+export type ArtifactKind = (typeof ARTIFACT_KINDS)[number];
+/** 写这份结果的工具:niceeval 自己,或经 niceeval/results 写入面转换的第三方 harness。 */
+export interface Producer {
+    name: string;
+    version?: string;
+    commit?: string;
+}
+/**
+ * `snapshot.json` 的持久化契约:快照元数据 —— 身份、快照级字段与版本元数据,
+ * 不含任何逐 attempt 数据。快照开始时写入;收尾时补写 `completedAt`。
+ * 字段规则与版本判定见 docs/feature/results/architecture.md「snapshot.json」「版本与升级设计」。
+ */
+export interface SnapshotMeta {
+    /** 恒为 "niceeval.results";和 schemaVersion、producer 一起构成持久化契约,永不移动或改名。 */
+    format: "niceeval.results";
+    /** 结果格式版本;与读取器不同即视为不兼容,提示用 producer.version 对应的 niceeval 查看。 */
+    schemaVersion: number;
+    producer: Producer;
+    /** 权威的实验身份;实验目录名是它的清洗投影。 */
+    experimentId: string;
+    /** 实验运行配置(flags / runs / earlyExit / sandbox / timeoutMs / budget),快照内全部 attempt 共享。 */
+    experiment?: ExperimentRunInfo;
+    agent: string;
+    model?: string;
+    startedAt: string;
+    /** 收尾时补写;缺失 = 快照未收尾(进程中断),已落盘的 attempt 照常可读。 */
+    completedAt?: string;
+    /** 写入时刻该实验已知的 eval 并集 —— 残缺检测的分母随数据走(copySnapshots 自动补记,writer 可声明)。 */
+    knownEvalIds?: string[];
+    /** 项目名(来自 config.name),透传给 `niceeval view` 顶部 hero 显示。 */
+    name?: LocalizedText;
+}
+/**
+ * 回到证据的引用:快照目录(根相对)+ 快照内 attempt 目录(快照相对)。
+ * 字段名(snapshot / attempt)是 view 深链 `#/attempt/<snapshot>/<attempt>` 的持久化路由契约,
+ * 不随句柄改名;`snapshot` 恒为两段(`<实验目录>/<快照目录>`),`attempt` 是 `<evalId 路径>/a<n>`,
+ * 路由按「前两段 = 快照」解析。Reports 的 MetricCell.refs 用的是同一个身份。
+ */
+export interface AttemptRef {
+    /** 根相对快照目录:`<experiment-dir>/<快照目录>`。 */
+    snapshot: string;
+    /** 快照相对 attempt 目录:`<evalId 路径>/a<n>`。 */
+    attempt: string;
+}
+/**
+ * 单个 eval attempt:瘦身条目 + 重 artifact 的懒加载方法。
+ * 懒加载即存在性判断: artifact 缺失返回 null,不抛错;同一 handle 内读过一次即记忆化。
+ * artifact 定位按候选顺序回退:先本 attempt 目录,再 artifactBase 指向的原快照 attempt 目录
+ * (--resume 合入条目的 artifact 留在原快照里);原快照被清理后如实返回 null。
+ */
+export interface AttemptHandle {
+    /** 属于哪道题 —— 直达字段,不绕 result。 */
+    evalId: string;
+    /** 属于哪个实验。 */
+    experimentId: string;
+    /** EvalResult 瘦身条目:判定、断言、用量、成本(快照级字段已拼合)。 */
+    result: EvalResult;
+    /** 证据引用,指条目所在的落盘(合入后的新快照); artifact 经候选回退仍可达。 */
+    ref: AttemptRef;
+    /** 所属快照(反向引用);去重「保留最新快照里的那份」靠它比较新旧。 */
+    snapshot: Snapshot;
+    /**
+     * 不透明的 Attempt 定位符(见 `locator.ts`);openResults() 产出的 handle 恒会填这个字段
+     * (result.json 里有就直接用,没有则按当前身份兜底算,见 open.ts 的回填逻辑)。可选只是为了
+     * 不强制手工构造的 AttemptHandle(测试里的内存 fake)也必须带上——真实读取路径永远有值。
+     */
+    locator?: AttemptLocator;
+    events(): Promise<StreamEvent[] | null>;
+    trace(): Promise<TraceSpan[] | null>;
+    o11y(): Promise<O11ySummary | null>;
+    /** 这次 attempt 的 agent setup 装了什么(Skill / native plugin / MCP / Python plugin);没装扩展的 agent 恒为 null。 */
+    agentSetup(): Promise<AgentSetupManifest | null>;
+    diff(): Promise<DiffData | null>;
+    sources(): Promise<SourceArtifact[] | null>;
+}
+/** 一道题在一个快照里的结果:id + 该题的全部 attempt(重试历史)。 */
+export interface Eval {
+    id: string;
+    attempts: AttemptHandle[];
+}
+/** 快照 = 单次跑的实验,物理上就是一个快照目录,没有更低一层。 */
+export interface Snapshot {
+    /** 权威身份(snapshot.json 字段;实验目录名只是它的清洗投影)。 */
+    experimentId: string;
+    startedAt: string;
+    /** 缺失 = 未收尾(进程中断);已落盘 attempt 照常在下面读到。 */
+    completedAt?: string;
+    /** 本快照自己的 agent。 */
+    agent: string;
+    model?: string;
+    /** 实验运行配置(flags / runs / budget …),快照内全部 attempt 共享。 */
+    experiment?: ExperimentRunInfo;
+    /** 谁写的这份结果(niceeval 或第三方 harness)。 */
+    producer: Producer;
+    /** 结果格式版本(能读进来的恒为当前版本;不兼容的在 skipped)。 */
+    schemaVersion: number;
+    /** 项目名(来自 config.name),透传给 `niceeval view` 顶部 hero 显示。 */
+    name?: LocalizedText;
+    /** 每道题一项:{ id, attempts };残缺检测 / 逐题遍历从这里走。 */
+    evals: Eval[];
+    /** 全部 attempt 平铺(= evals 逐题展开),不关心题目边界的聚合消费用。 */
+    attempts: AttemptHandle[];
+    /** 快照目录的绝对路径(物理落盘就是快照本身,没有更低一层)。 */
+    dir: string;
+    /** 写入时刻该实验已知的 eval 并集(可选);copySnapshots 自动补记,writer.snapshot() 也可声明。 */
+    knownEvalIds?: string[];
+}
+/** 一个实验的全部历史:同一 experiment id 的历次快照归在一起。 */
+export interface Experiment {
+    id: string;
+    /** 历次快照,最新在前。 */
+    snapshots: Snapshot[];
+    /** 最新一次(= snapshots[0])。 */
+    latest: Snapshot;
+    /** 已知 eval 并集 = 本地历史 ∪ 各快照携带的 knownEvalIds —— 残缺检测的分母。 */
+    evalIds: string[];
+}
+/** 目录扫描里读不了、但必须让调用方知道的落盘;无关 JSON 不记(静默忽略)。 */
+export interface SkippedDir {
+    /** 落盘目录的绝对路径。 */
+    dir: string;
+    /**
+     * incompatible-version:schemaVersion 与读取器不同(不解析、不迁移、不降级);
+     * malformed:snapshot.json(或历史版本的 summary.json)是坏数据;
+     * incomplete:有 attempt 落盘、没有 snapshot.json —— 快照目录建好但元数据没写完的极小窗口,
+     * 或人为删文件。snapshot.json 是收尾事实,reader 不读无 snapshot.json 的目录;
+     * 已完成的 attempt 留在盘上供手工排查。
+     */
+    reason: "incompatible-version" | "malformed" | "incomplete";
+    /** 那份结果声明的 schemaVersion(incomplete 没有 snapshot.json,自然缺失)。 */
+    schemaVersion?: number;
+    /** 完整的 producer(name + version):只有 name === "niceeval" 才能拼 npx 提示,第三方如实报名字。 */
+    producer?: Producer;
+    /** malformed:一句英文诊断。 */
+    detail?: string;
+}
+/** openResults 的返回:experiments 分层;skipped 不静默丢。 */
+export interface Results {
+    /** 每个实验一项,挂着自己的全部历史(id 字典序)。 */
+    experiments: Experiment[];
+    skipped: SkippedDir[];
+    /**
+     * 每个实验取最新一次快照,返回 Selection(快照与挑选警告绑在一起走)。
+     * `experiments` 是 experiment id 前缀过滤(string | string[]),同 CLI 位置参数语义。
+     */
+    latest(opts?: {
+        experiments?: string | string[];
+    }): Selection;
+}
+/**
+ * Selection:选出的快照 + 挑选过程算出的警告。渲染与否在消费方,但缺口永远被算出来。
+ * 下游(Reports 计算函数、copySnapshots)收 `Selection | Snapshot[]`;
+ * 手工挑的裸数组没有挑选过程,自然没有 warnings 可带,也如实。
+ */
+export interface Selection {
+    snapshots: Snapshot[];
+    warnings: SelectionWarning[];
+    /**
+     * 只删不换:返回新 Selection,快照删减,warnings 按规则修剪 ——
+     * experimentId 不在幸存快照中的丢弃,非实验作用域的保留。
+     * 「换成上一个完整快照」这类替换式重挑不给方法,回 exp.snapshots 自己挑。
+     */
+    filter(predicate: (snapshot: Snapshot) => boolean): Selection;
+}
+/**
+ * 挑选警告:每种带 kind、可判断的结构化字段和渲染好的英文 message;
+ * kind 是契约的一部分,全集与触发条件见 docs/feature/results/library.md「警告 kind 全集」。
+ */
+export type SelectionWarning = {
+    /** 选中快照的覆盖 < 该实验已知 eval 并集(本地历史 ∪ knownEvalIds)。 */
+    kind: "partial-coverage";
+    experimentId: string;
+    covered: number;
+    total: number;
+    message: string;
+} | {
+    /** 该实验选中的快照早于 Selection 中最新的落盘;无阈值,如实触发,要阈值消费方按字段自比。 */
+    kind: "stale-snapshot";
+    experimentId: string;
+    startedAt: string;
+    latestStartedAt: string;
+    message: string;
+} | {
+    /** 选中快照缺 completedAt(进程中断,未收尾);已落盘 attempt 照常读出,警告提示集合可能不完整。 */
+    kind: "unfinished-snapshot";
+    experimentId: string;
+    startedAt: string;
+    /** 该快照目录的绝对路径。 */
+    dir: string;
+    message: string;
+};
+/** dedupeAttempts 的警告:身份键缺 startedAt,宁可不去重也不误删。 */
+export interface DedupeWarning {
+    kind: "missing-startedAt";
+    experimentId: string;
+    evalId: string;
+    message: string;
+}

package/dist/runner/eval-source.d.ts

@@ -0,0 +1,22 @@
+export interface CapturedEvalSource {
+    /** 项目相对路径(正斜杠),与 SourceArtifact.path / SourceLoc.file 同一约定。 */
+    path: string;
+    /** 归一化后的源码文本(去 BOM、CRLF/CR 统一成 LF)。 */
+    content: string;
+    /** 归一化文本的 SHA-256 十六进制摘要;同一份内容(哪怕跨平台不同换行符)恒相同。 */
+    sha256: string;
+}
+/**
+ * 读一个 eval 定义文件、归一化文本、算哈希。`filePath` 是绝对路径(discoverEvals() 里
+ * `DiscoveredEval.sourcePath` 的形状);`opts.root` 决定 `path` 字段相对谁计算,省略时
+ * 用 `process.cwd()`(与 src/source-loc.ts 的 captureLoc()、runner/attempt.ts 的
+ * collectSources() 同一约定——项目相对路径永远相对进程 cwd,不是相对 discoverEvals() 的
+ * `root` 参数,两者通常相同但不保证,显式传参让调用方按需要覆盖,也让单测不依赖真实 cwd)。
+ *
+ * 读不到文件(已删除 / 权限问题)如实抛错——发现阶段的源码文件应当总是可读,
+ * 与 collectSources() 运行后"读不到就跳过"的降级语义不同:那时源码可能已经在沙箱里、
+ * 已被清理;这里读的是刚刚 import 成功的同一个文件,读不到是需要暴露的异常。
+ */
+export declare function captureEvalSource(filePath: string, opts?: {
+    root?: string;
+}): Promise<CapturedEvalSource>;

package/dist/runner/fingerprint.d.ts

@@ -0,0 +1,23 @@
+import type { DiscoveredEval, EvalResult } from "../types.ts";
+import type { AgentRun } from "./types.ts";
+export declare function cacheKey(run: AgentRun, evalId: string): string;
+/**
+ * @param sourceCache 按 sourcePath 缓存文件内容:一个矩阵(实验 × eval)会对同一批源文件
+ * 反复算指纹,不带缓存会在任何 attempt 起跑前做 E×N 次重复文件读。
+ */
+export declare function computeFingerprint(evalDef: DiscoveredEval, run: AgentRun, sourceCache?: Map<string, Promise<string>>): Promise<string>;
+export interface CarryPlan {
+    /** `cacheKey(run, evalId)` → 本次规划出的指纹,供调用方按同一口径判断"这条要不要携入"。 */
+    plannedFingerprints: Map<string, string>;
+    /** 命中携入条件(passed/failed 终态 + 指纹匹配)的 `${experimentId}|${evalId}` 集合。 */
+    priorRunKeys: Set<string>;
+    /** priorRunKeys 对应的完整结果对象,供 run.ts 直接并入 summary、cli.ts 直接取 verdict 展示。 */
+    carriedResults: EvalResult[];
+}
+/**
+ * 算出这一批 (agentRun × eval) 的指纹,并据此从 priorResults 里筛出可以携入(跳过重跑)的结果。
+ * run.ts 与 cli.ts(live 表格构建)必须共用这同一份计算 —— 否则两边一旦对"哪些携入"的判断
+ * 不一致,live 表格就会显示"还在等名额",而 run.ts 其实已经把它筛掉、根本不会调度这个 attempt
+ * (见 memory 的 live-carry-row-shows-waiting-forever)。
+ */
+export declare function planCarry(evals: DiscoveredEval[], agentRuns: AgentRun[], priorResults: EvalResult[] | undefined): Promise<CarryPlan>;