niceeval 0.5.4 → 0.6.0

package/src/results/select.ts

@@ -1,30 +1,31 @@
-// 快照选集与 attempt 去重(定稿见 docs/results-lib.md「选择快照」「身份键与去重」)。
+// 快照 Selection 与 attempt 去重(定稿见 docs/feature/results/library.md「选择快照」「身份键与去重」)。
 //
 // 选择器只有一个(latest),长在集合上;它不是 DSL,只是最常用的那次筛选。
-// 选择器必须诚实:残缺、落后、合成键都被算出来,以结构化 warnings 随选集走 ——
+// 选择器必须诚实:残缺、落后、未收尾都被算出来,以结构化 warnings 随 Selection 走 ——
 // 渲染与否在消费方(message 是渲染好的英文句子),但缺口不静默。
 
-import { experimentKeyOf } from "./format.ts";
 import type {
   AttemptHandle,
   DedupeWarning,
+  Eval,
   Experiment,
-  RunDir,
+  Results,
   Selection,
   SelectionWarning,
   Snapshot,
 } from "./types.ts";
+import { evalPrefixPredicate } from "../shared/aggregate.ts";
 
 /** Results.latest() 的实现:每个实验取最新一次快照(= exp.snapshots[0]),生成挑选警告。 */
 export function selectLatest(
   experiments: Experiment[],
   opts?: { experiments?: string | string[] },
 ): Selection {
-  const selected = filterByExperimentPrefix(experiments, opts?.experiments);
+  const selected = filterExperiments(experiments, opts?.experiments);
   const snapshots = selected.map((exp) => exp.latest);
   const warnings: SelectionWarning[] = [];
 
-  // stale 的基准:选集中最新的落盘(无阈值,如实触发;要阈值消费方按字段自比)。
+  // stale 的基准:Selection 中最新的落盘(无阈值,如实触发;要阈值消费方按字段自比)。
   let latestStartedAt = "";
   for (const snapshot of snapshots) {
     if (snapshot.startedAt > latestStartedAt) latestStartedAt = snapshot.startedAt;
@@ -37,16 +38,12 @@ export function selectLatest(
     const covered = snapshot.evals.length;
     const total = exp.evalIds.length;
     if (covered < total) {
-      // 合成键不是真实 experiment id,拼不出可执行的 `niceeval exp` 命令,提示退化成中性说法。
-      const hint = snapshot.synthetic
-        ? "re-run the experiment for a full snapshot"
-        : `re-run \`niceeval exp ${exp.id}\` for a full snapshot`;
       warnings.push({
         kind: "partial-coverage",
         experimentId: exp.id,
         covered,
         total,
-        message: `snapshot covers ${covered} of ${total} evals seen in history; ${hint}`,
+        message: `snapshot covers ${covered} of ${total} evals seen in history; re-run \`niceeval exp ${exp.id}\` for a full snapshot`,
       });
     }
     if (snapshot.startedAt < latestStartedAt) {
@@ -58,18 +55,126 @@ export function selectLatest(
         message: `snapshot "${exp.id}" (${snapshot.startedAt}) predates the latest run in this selection by ${humanizeGap(snapshot.startedAt, latestStartedAt)}`,
       });
     }
-    if (snapshot.synthetic) {
+    if (!snapshot.completedAt) {
       warnings.push({
-        kind: "synthetic-experiment-id",
+        kind: "unfinished-snapshot",
         experimentId: exp.id,
-        runDir: snapshot.runDir.dir,
-        message: `run "${snapshot.runDir.dir}" has results without experimentId; grouped as "${exp.id}" by agent/model`,
+        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);
 }
 
+/** 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 function selectCurrentResults(results: Results, scope: ResultScope = {}): Selection {
+  const match =
+    scope.patterns && scope.patterns.length > 0 ? evalPrefixPredicate(scope.patterns) : () => true;
+  const experiments = filterExperiments(results.experiments, scope.experiment);
+
+  const snapshots: Snapshot[] = [];
+  const warnings: SelectionWarning[] = [];
+
+  for (const exp of experiments) {
+    // 逐题取最新:快照按最新在前,首个出现即最新判定
+    const taken = new Map<string, { ev: Eval; snapshot: Snapshot }>();
+    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: Snapshot = 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 留位置)。
@@ -92,8 +197,8 @@ export function makeSelection(snapshots: Snapshot[], warnings: SelectionWarning[
 
 /**
  * 跨快照聚合前的身份键去重:(experimentId, evalId, attempt, startedAt)。
- * --resume 会把上一轮已通过的结果原样合入新 run 的 summary,同一 attempt 因此存在于多份落盘;
- * 重复时保留最新 run 目录里的那份(内容相同,取新 run 的副本让 ref 落在最新落盘上;
+ * --resume 会把上一轮已通过的结果原样合入新快照,同一 attempt 因此存在于多份落盘;
+ * 重复时保留最新快照里的那份(内容相同,取新快照的副本让 ref 落在最新落盘上;
  * 位置取首次出现处,顺序稳定)。startedAt 缺失时宁可不去重也不误删,记入 warnings。
  */
 export function dedupeAttempts(attempts: AttemptHandle[]): { attempts: AttemptHandle[]; warnings: DedupeWarning[] } {
@@ -113,26 +218,27 @@ export function dedupeAttempts(attempts: AttemptHandle[]): { attempts: AttemptHa
       deduped.push(attempt);
       continue;
     }
-    const key = JSON.stringify([experimentKeyOf(r).id, r.id, r.attempt, r.startedAt]);
+    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 (isNewerRunDir(attempt.runDir, deduped[existing].runDir)) {
+    } else if (isNewerSnapshot(attempt.snapshot, deduped[existing].snapshot)) {
       deduped[existing] = attempt;
     }
   }
   return { attempts: deduped, warnings };
 }
 
-/** run 新旧比较:startedAt 优先,同刻按目录名(时间戳目录,字典序即时序)。 */
-export function isNewerRunDir(a: RunDir, b: RunDir): boolean {
-  const byStart = a.summary.startedAt.localeCompare(b.summary.startedAt);
+/** 快照新旧比较:startedAt 优先,同刻按快照目录名(时间戳 + 随机后缀,字典序即时序)。 */
+export function isNewerSnapshot(a: Snapshot, b: Snapshot): boolean {
+  const byStart = a.startedAt.localeCompare(b.startedAt);
   if (byStart !== 0) return byStart > 0;
   return a.dir.localeCompare(b.dir) > 0;
 }
 
-function filterByExperimentPrefix(experiments: Experiment[], filter?: string | string[]): Experiment[] {
+/** experiment id 分段前缀过滤(--experiment / latest({ experiments }) 同一语义);包内使用,不进公共 barrel。 */
+export function filterExperiments(experiments: Experiment[], filter?: string | string[]): Experiment[] {
   if (filter === undefined) return experiments;
   // 允许 "compare/" 这种带尾斜杠的写法,与 "compare" 等价;分段匹配不误配 "compare2"。
   const prefixes = (Array.isArray(filter) ? filter : [filter]).map((p) => p.replace(/\/+$/, ""));

package/src/results/source-hash.ts

@@ -0,0 +1,28 @@
+// Eval 源码的归一化与哈希:discovery 时的捕获(src/runner/eval-source.ts)与证据重建
+// (annotated-source.ts 的 buildAnnotatedEvalSource)必须对同一份源码算出同一个 SHA-256,
+// 所以归一化规则与哈希算法只住这一处 —— 两侧各自 import,不各写一份可能跑偏的实现。
+//
+// 只做归一化 + 哈希,不碰文件系统:住在 results/ 而不是 shared/,是因为 shared/ 的既有约定
+// 是"环境无关、vite 前端直接打包"(见 shared/verdict.ts、shared/aggregate.ts 的注释),
+// node:crypto 在浏览器打包下不成立;results/ 已经是纯 Node 库(writer.ts / open.ts 也用
+// node:fs),多一个 node:crypto 不破坏任何边界。runner 已经单向依赖 results(reporters/
+// artifacts.ts 用 createResultsWriter),所以 src/runner/eval-source.ts 反过来 import 这里
+// 不新增循环依赖。
+
+import { createHash } from "node:crypto";
+
+/**
+ * 归一化 eval 源码文本:去 UTF-8 BOM、把 CRLF / CR 统一成 LF。
+ * 幂等——已归一化的文本再跑一次结果不变,所以 capture 时归一化一次、重建时可以放心再跑一次,
+ * 两处算出的 SHA-256 恒相同。不做其它改写(不 trim 行尾空白、不折叠空行):
+ * 行号是断言 SourceLoc 的锚,任何改变行结构的归一化都会让映射错位。
+ */
+export function normalizeEvalSource(text: string): string {
+  const withoutBom = text.charCodeAt(0) === 0xfeff ? text.slice(1) : text;
+  return withoutBom.replace(/\r\n/g, "\n").replace(/\r/g, "\n");
+}
+
+/** 对(已归一化的)源码文本算 SHA-256 十六进制摘要。 */
+export function hashEvalSource(content: string): string {
+  return createHash("sha256").update(content, "utf-8").digest("hex");
+}

package/src/results/types.ts

@@ -1,59 +1,94 @@
-// results 域类型:openResults 的分层读取契约与选集(定稿见 docs/results-lib.md)。
+// results 域类型:openResults 的分层读取契约与 Selection(定稿见 docs/feature/results/library.md、docs/feature/results/architecture.md)。
 //
-// 结果数据类型(EvalResult / RunSummary / StreamEvent / …)仍住在各自的域文件里,
+// 结果数据类型(EvalResult / ExperimentRunInfo / StreamEvent / …)仍住在各自的域文件里,
 // 这里只 import,不搬家 —— 「类型的家」迁移(facade 反向 re-export)是下一波,不在本次范围。
 //
-// 命名约定:Experiment / Snapshot / Eval / RunDir 是纯数据,不带 Handle 后缀;
+// 命名约定:Experiment / Snapshot / Eval 是纯数据,不带 Handle 后缀;
 // 唯一叫 AttemptHandle 的是 attempt —— 它的方法真的会碰磁盘,后缀标记的就是这件事。
 
-import type { EvalResult, RunSummary } from "../types.ts";
+import type { EvalResult, ExperimentRunInfo, LocalizedText } from "../types.ts";
 import type { O11ySummary, StreamEvent, TraceSpan } from "../types.ts";
-import type { DiffData, SourceArtifact } from "../types.ts";
+import type { AgentSetupManifest, DiffData, SourceArtifact } from "../types.ts";
+import type { AttemptLocator } from "./locator.ts";
 
-/** attempt 级工件的种类;文件名恒为 `<kind>.json`,布局见 docs/results-format.md。 */
-export const ARTIFACT_KINDS = ["events", "trace", "o11y", "diff", "sources"] as const;
+/** attempt 级 artifact 的种类;文件名见 format.ts 的 artifactFileOf,布局见 docs/feature/results/architecture.md。 */
+export const ARTIFACT_KINDS = ["events", "trace", "o11y", "agentSetup", "diff", "sources"] as const;
 export type ArtifactKind = (typeof ARTIFACT_KINDS)[number];
 
+/** 写这份结果的工具:niceeval 自己,或经 niceeval/results 写入面转换的第三方 harness。 */
+export interface Producer {
+  name: string;
+  version?: string;
+  commit?: string;
+}
+
 /**
- * 回到证据的引用:run 目录名(相对结果根目录)+ summary.results[] 下标。
- * 字段名(run / result)是 view 深链 `#/attempt/<run>/<result>` 的持久化路由契约,不随句柄改名;
- * Reports 的 MetricCell.refs 用的是同一个身份。
+ * `snapshot.json` 的持久化契约:快照元数据 —— 身份、快照级字段与版本元数据,
+ * 不含任何逐 attempt 数据。快照开始时写入;收尾时补写 `completedAt`。
+ * 字段规则与版本判定见 docs/feature/results/architecture.md「snapshot.json」「版本与升级设计」。
  */
-export interface AttemptRef {
-  run: string;
-  result: number;
+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;
 }
 
-/** 一个物理落盘 run 目录(低层忠实磁盘面);多数消费方走 experiments,不碰它。 */
-export interface RunDir {
-  /** run 目录的绝对路径(summary.json 所在目录)。 */
-  dir: string;
-  /** 与写入侧同一类型的 RunSummary(results[] 是瘦身条目)。 */
-  summary: RunSummary;
-  /** summary.results[] 逐条包一层懒加载句柄(按下标顺序)。 */
-  attempts: AttemptHandle[];
+/**
+ * 回到证据的引用:快照目录(根相对)+ 快照内 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:瘦身条目 + 重工件的懒加载方法。
- * 懒加载即存在性判断:工件缺失返回 null,不抛错;同一 handle 内读过一次即记忆化。
- * 工件定位按候选顺序回退:先本 run 的 artifactsDir,再 artifactBase 指向的原 run 目录
- * (--resume 合入条目的工件留在原 run 里);原 run 被清理后如实返回 null。
+ * 单个 eval attempt:瘦身条目 + 重 artifact 的懒加载方法。
+ * 懒加载即存在性判断: artifact 缺失返回 null,不抛错;同一 handle 内读过一次即记忆化。
+ * artifact 定位按候选顺序回退:先本 attempt 目录,再 artifactBase 指向的原快照 attempt 目录
+ * (--resume 合入条目的 artifact 留在原快照里);原快照被清理后如实返回 null。
  */
 export interface AttemptHandle {
   /** 属于哪道题 —— 直达字段,不绕 result。 */
   evalId: string;
-  /** 属于哪个实验;落盘缺 experimentId 时是 "<agent>/<model>" 合成键(所属快照 synthetic: true)。 */
+  /** 属于哪个实验。 */
   experimentId: string;
-  /** EvalResult 瘦身条目:判决、断言、用量、成本、experiment 元数据。 */
+  /** EvalResult 瘦身条目:判定、断言、用量、成本(快照级字段已拼合)。 */
   result: EvalResult;
-  /** 证据引用,指条目所在的落盘(合入后的新 run);工件经候选回退仍可达。 */
+  /** 证据引用,指条目所在的落盘(合入后的新快照); artifact 经候选回退仍可达。 */
   ref: AttemptRef;
-  /** 条目所在的物理落盘;去重「保留最新 run 目录里的那份」靠它比较新旧。 */
-  runDir: RunDir;
+  /** 所属快照(反向引用);去重「保留最新快照里的那份」靠它比较新旧。 */
+  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>;
 }
@@ -64,29 +99,30 @@ export interface Eval {
   attempts: AttemptHandle[];
 }
 
-/**
- * 快照 = 单次跑的实验(experiment × run 切片)。一个 run 目录可以装多个 experiment
- * (`niceeval exp compare`),所以「每个 experiment 最新一次」只能用快照粒度表达。
- */
+/** 快照 = 单次跑的实验,物理上就是一个快照目录,没有更低一层。 */
 export interface Snapshot {
-  /** 结果里缺 experimentId 时以 "<agent>/<model>" 合成键,并经 latest() 记入 warnings。 */
+  /** 权威身份(snapshot.json 字段;实验目录名只是它的清洗投影)。 */
   experimentId: string;
   startedAt: string;
-  /** 本快照自己的 agent —— 不是落盘顶层那个「第一个配置」。 */
+  /** 缺失 = 未收尾(进程中断);已落盘 attempt 照常在下面读到。 */
+  completedAt?: string;
+  /** 本快照自己的 agent。 */
   agent: string;
   model?: string;
-  /** 谁写的这份结果(niceeval 或第三方 harness;legacy 结果可能缺失)。 */
-  producer?: RunSummary["producer"];
-  /** 结果格式版本(能读进来的恒为当前版本;不兼容的在 skipped),缺失按 1。 */
+  /** 实验运行配置(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[];
-  /** 所属物理落盘(低层面)。 */
-  runDir: RunDir;
-  /** experimentId 是合成键(结果里没有 experimentId)时为 true。 */
-  synthetic?: boolean;
+  /** 快照目录的绝对路径(物理落盘就是快照本身,没有更低一层)。 */
+  dir: string;
   /** 写入时刻该实验已知的 eval 并集(可选);copySnapshots 自动补记,writer.snapshot() 也可声明。 */
   knownEvalIds?: string[];
 }
@@ -103,31 +139,30 @@ export interface Experiment {
 }
 
 /** 目录扫描里读不了、但必须让调用方知道的落盘;无关 JSON 不记(静默忽略)。 */
-export interface SkippedRun {
-  /** run 目录的绝对路径。 */
+export interface SkippedDir {
+  /** 落盘目录的绝对路径。 */
   dir: string;
   /**
    * incompatible-version:schemaVersion 与读取器不同(不解析、不迁移、不降级);
-   * malformed:summary.json 是坏数据;
-   * incomplete:有 attempt 工件、没有 summary.json —— run 中途 crash、writer 没走到 finish()。
-   * summary 是收尾事实,reader 不读无 summary 的目录;已完成的工件留在盘上供手工排查。
+   * malformed:snapshot.json(或历史版本的 summary.json)是坏数据;
+   * incomplete:有 attempt 落盘、没有 snapshot.json —— 快照目录建好但元数据没写完的极小窗口,
+   * 或人为删文件。snapshot.json 是收尾事实,reader 不读无 snapshot.json 的目录;
+   * 已完成的 attempt 留在盘上供手工排查。
    */
   reason: "incompatible-version" | "malformed" | "incomplete";
-  /** 那份结果声明的 schemaVersion(incomplete 没有 summary,自然缺失)。 */
+  /** 那份结果声明的 schemaVersion(incomplete 没有 snapshot.json,自然缺失)。 */
   schemaVersion?: number;
   /** 完整的 producer(name + version):只有 name === "niceeval" 才能拼 npx 提示,第三方如实报名字。 */
-  producer?: RunSummary["producer"];
+  producer?: Producer;
   /** malformed:一句英文诊断。 */
   detail?: string;
 }
 
-/** openResults 的返回:experiments 分层;skipped 不静默丢;runDirs 忠实磁盘(新→旧)。 */
+/** openResults 的返回:experiments 分层;skipped 不静默丢。 */
 export interface Results {
   /** 每个实验一项,挂着自己的全部历史(id 字典序)。 */
   experiments: Experiment[];
-  skipped: SkippedRun[];
-  /** 低层忠实磁盘面:物理落盘目录,新→旧;多数消费方不碰。 */
-  runDirs: RunDir[];
+  skipped: SkippedDir[];
   /**
    * 每个实验取最新一次快照,返回 Selection(快照与挑选警告绑在一起走)。
    * `experiments` 是 experiment id 前缀过滤(string | string[]),同 CLI 位置参数语义。
@@ -136,7 +171,7 @@ export interface Results {
 }
 
 /**
- * 选集:选出的快照 + 挑选过程算出的警告。渲染与否在消费方,但缺口永远被算出来。
+ * Selection:选出的快照 + 挑选过程算出的警告。渲染与否在消费方,但缺口永远被算出来。
  * 下游(Reports 计算函数、copySnapshots)收 `Selection | Snapshot[]`;
  * 手工挑的裸数组没有挑选过程,自然没有 warnings 可带,也如实。
  */
@@ -152,8 +187,8 @@ export interface Selection {
 }
 
 /**
- * 挑选警告:每种带 kind、可判断的结构化字段和渲染好的英文 message。
- * kind 是契约的一部分;全集与触发条件见 docs/results-lib.md「警告 kind 全集」。
+ * 挑选警告:每种带 kind、可判断的结构化字段和渲染好的英文 message;
+ * kind 是契约的一部分,全集与触发条件见 docs/feature/results/library.md「警告 kind 全集」。
  */
 export type SelectionWarning =
   | {
@@ -165,7 +200,7 @@ export type SelectionWarning =
       message: string;
     }
   | {
-      /** 该实验选中的快照早于选集中最新的落盘;无阈值,如实触发,要阈值消费方按字段自比。 */
+      /** 该实验选中的快照早于 Selection 中最新的落盘;无阈值,如实触发,要阈值消费方按字段自比。 */
       kind: "stale-snapshot";
       experimentId: string;
       startedAt: string;
@@ -173,11 +208,12 @@ export type SelectionWarning =
       message: string;
     }
   | {
-      /** 落盘缺 experimentId,以 "<agent>/<model>" 合成键(快照的 synthetic: true 同源)。 */
-      kind: "synthetic-experiment-id";
+      /** 选中快照缺 completedAt(进程中断,未收尾);已落盘 attempt 照常读出,警告提示集合可能不完整。 */
+      kind: "unfinished-snapshot";
       experimentId: string;
-      /** 该快照所在 run 目录的绝对路径。 */
-      runDir: string;
+      startedAt: string;
+      /** 该快照目录的绝对路径。 */
+      dir: string;
       message: string;
     };