niceeval 0.4.5 → 0.5.0

package/src/results/select.ts

@@ -1,75 +1,115 @@
-// 快照选择器与 attempt 去重(设计见 docs/results-lib.md「选择快照」「身份键与去重」)。
+// 快照选集与 attempt 去重(定稿见 docs/results-lib.md「选择快照」「身份键与去重」)。
 //
-// 选择器不是 DSL,只是最常用的那次筛选;更细的口径消费方自己 .filter()。
-// 选择器必须诚实:残缺(最新快照覆盖的 eval 少于历史并集)永远被算出来,以 warnings 返回,
-// 渲染与否在消费方,但缺口不静默。
+// 选择器只有一个(latest),长在集合上;它不是 DSL,只是最常用的那次筛选。
+// 选择器必须诚实:残缺、落后、合成键都被算出来,以结构化 warnings 随选集走 ——
+// 渲染与否在消费方(message 是渲染好的英文句子),但缺口不静默。
 
 import { experimentKeyOf } from "./format.ts";
-import type { AttemptHandle, RunHandle, SnapshotHandle } from "./types.ts";
+import type {
+  AttemptHandle,
+  DedupeWarning,
+  Experiment,
+  RunDir,
+  Selection,
+  SelectionWarning,
+  Snapshot,
+} from "./types.ts";
 
-/**
- * 每个 experiment 取最新一次快照(按所属 run 的 startedAt,同刻按 run 目录名兜底)。
- * `experiments` 是 experiment id 前缀过滤,同 CLI 位置参数语义("compare" 匹配自身与
- * "compare/..." 子级;允许写成 "compare/",等价)。
- */
-export function latestPerExperiment(
-  snapshots: SnapshotHandle[],
+/** Results.latest() 的实现:每个实验取最新一次快照(= exp.snapshots[0]),生成挑选警告。 */
+export function selectLatest(
+  experiments: Experiment[],
   opts?: { experiments?: string | string[] },
-): { snapshots: SnapshotHandle[]; warnings: string[] } {
-  const filtered = filterByExperiments(snapshots, opts?.experiments);
+): Selection {
+  const selected = filterByExperimentPrefix(experiments, opts?.experiments);
+  const snapshots = selected.map((exp) => exp.latest);
+  const warnings: SelectionWarning[] = [];
 
-  const byExperiment = new Map<string, SnapshotHandle[]>();
-  for (const snapshot of filtered) {
-    const group = byExperiment.get(snapshot.experimentId);
-    if (group) group.push(snapshot);
-    else byExperiment.set(snapshot.experimentId, [snapshot]);
+  // stale 的基准:选集中最新的落盘(无阈值,如实触发;要阈值消费方按字段自比)。
+  let latestStartedAt = "";
+  for (const snapshot of snapshots) {
+    if (snapshot.startedAt > latestStartedAt) latestStartedAt = snapshot.startedAt;
   }
 
-  const picked: SnapshotHandle[] = [];
-  const warnings: string[] = [];
-  for (const [experimentId, group] of byExperiment) {
-    let latest = group[0];
-    for (const candidate of group) {
-      if (isNewerRun(candidate.run, latest.run)) latest = candidate;
-    }
-    // 残缺检测:与该 experiment 全部历史快照的 evalId 并集对比。
+  for (const exp of selected) {
+    const snapshot = exp.latest;
+    // 残缺检测:分母 = 该实验已知 eval 并集(本地历史 ∪ 各快照携带的 knownEvalIds)。
     // 位置参数允许只重跑一道题,产出的「最新快照」可能只有一道题 —— 不能安静吞下。
-    const historyIds = new Set<string>();
-    for (const snapshot of group) for (const id of snapshot.evalIds) historyIds.add(id);
-    if (latest.evalIds.length < historyIds.size) {
+    const covered = snapshot.evals.length;
+    const total = exp.evalIds.length;
+    if (covered < total) {
       // 合成键不是真实 experiment id,拼不出可执行的 `niceeval exp` 命令,提示退化成中性说法。
-      const hint = latest.synthetic
-        ? "  Re-run the experiment for a full snapshot, or pick another via .filter()."
-        : `  Re-run \`niceeval exp ${experimentId}\` for a full snapshot, or pick another via .filter().`;
-      warnings.push(
-        `warning: snapshot "${experimentId}" @ ${latest.startedAt} covers ${latest.evalIds.length} of ${historyIds.size} evals seen in history.\n` +
-          hint,
-      );
+      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}`,
+      });
+    }
+    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.synthetic) {
+      warnings.push({
+        kind: "synthetic-experiment-id",
+        experimentId: exp.id,
+        runDir: snapshot.runDir.dir,
+        message: `run "${snapshot.runDir.dir}" has results without experimentId; grouped as "${exp.id}" by agent/model`,
+      });
     }
-    picked.push(latest);
   }
+  return makeSelection(snapshots, warnings);
+}
 
-  picked.sort((a, b) => a.experimentId.localeCompare(b.experimentId));
-  return { snapshots: picked, warnings };
+/**
+ * Selection 构造:filter 只删不换 —— 快照删减,warnings 修剪规则是
+ * 「experimentId 不在幸存快照中的丢弃,非实验作用域的保留」(为将来非 per-experiment 的 kind 留位置)。
+ */
+export function makeSelection(snapshots: Snapshot[], warnings: SelectionWarning[]): Selection {
+  return {
+    snapshots,
+    warnings,
+    filter(predicate: (snapshot: Snapshot) => boolean): Selection {
+      const kept = snapshots.filter(predicate);
+      const survivors = new Set(kept.map((s) => s.experimentId));
+      const keptWarnings = warnings.filter((w) => {
+        const scope = (w as { experimentId?: unknown }).experimentId;
+        return typeof scope !== "string" || survivors.has(scope);
+      });
+      return makeSelection(kept, keptWarnings);
+    },
+  };
 }
 
 /**
  * 跨快照聚合前的身份键去重:(experimentId, evalId, attempt, startedAt)。
  * --resume 会把上一轮已通过的结果原样合入新 run 的 summary,同一 attempt 因此存在于多份落盘;
- * 重复时保留最新 run 里的那份(位置取首次出现处,顺序稳定)。
- * startedAt 缺失时宁可不去重也不误删,并记入 warnings。
+ * 重复时保留最新 run 目录里的那份(内容相同,取新 run 的副本让 ref 落在最新落盘上;
+ * 位置取首次出现处,顺序稳定)。startedAt 缺失时宁可不去重也不误删,记入 warnings。
  */
-export function dedupeAttempts(attempts: AttemptHandle[]): { attempts: AttemptHandle[]; warnings: string[] } {
+export function dedupeAttempts(attempts: AttemptHandle[]): { attempts: AttemptHandle[]; warnings: DedupeWarning[] } {
   const deduped: AttemptHandle[] = [];
   const indexByKey = new Map<string, number>();
-  const warnings: string[] = [];
+  const warnings: DedupeWarning[] = [];
 
   for (const attempt of attempts) {
     const r = attempt.result;
     if (!r.startedAt) {
-      warnings.push(
-        `warning: attempt "${r.id}" (attempt ${r.attempt}) in run "${attempt.run.dir}" has no startedAt; kept as-is without dedupe.`,
-      );
+      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;
     }
@@ -78,7 +118,7 @@ export function dedupeAttempts(attempts: AttemptHandle[]): { attempts: AttemptHa
     if (existing === undefined) {
       indexByKey.set(key, deduped.length);
       deduped.push(attempt);
-    } else if (isNewerRun(attempt.run, deduped[existing].run)) {
+    } else if (isNewerRunDir(attempt.runDir, deduped[existing].runDir)) {
       deduped[existing] = attempt;
     }
   }
@@ -86,16 +126,28 @@ export function dedupeAttempts(attempts: AttemptHandle[]): { attempts: AttemptHa
 }
 
 /** run 新旧比较:startedAt 优先,同刻按目录名(时间戳目录,字典序即时序)。 */
-export function isNewerRun(a: RunHandle, b: RunHandle): boolean {
+export function isNewerRunDir(a: RunDir, b: RunDir): boolean {
   const byStart = a.summary.startedAt.localeCompare(b.summary.startedAt);
   if (byStart !== 0) return byStart > 0;
   return a.dir.localeCompare(b.dir) > 0;
 }
 
-function filterByExperiments(snapshots: SnapshotHandle[], experiments?: string | string[]): SnapshotHandle[] {
-  if (experiments === undefined) return snapshots;
-  const prefixes = (Array.isArray(experiments) ? experiments : [experiments])
-    // 允许 "compare/" 这种带尾斜杠的写法,与 "compare" 等价。
-    .map((p) => p.replace(/\/+$/, ""));
-  return snapshots.filter((s) => prefixes.some((p) => s.experimentId === p || s.experimentId.startsWith(p + "/")));
+function filterByExperimentPrefix(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(/\/+$/, ""));
+  return experiments.filter((exp) => prefixes.some((p) => exp.id === p || exp.id.startsWith(p + "/")));
+}
+
+/** stale 警告的人话时距:选粒度最大的单位,四舍五入。 */
+function humanizeGap(fromIso: string, toIso: string): string {
+  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/src/results/types.ts

@@ -1,47 +1,56 @@
-// results 域类型:openResults 返回的类型化句柄(读取面契约,见 docs/results-lib.md)。
+// results 域类型:openResults 的分层读取契约与选集(定稿见 docs/results-lib.md)。
 //
 // 结果数据类型(EvalResult / RunSummary / StreamEvent / …)仍住在各自的域文件里,
-// 这里只 import,不搬家 —— 「类型的家」迁移是 results-lib 设计里单独的一步,不在本次范围。
+// 这里只 import,不搬家 —— 「类型的家」迁移(facade 反向 re-export)是下一波,不在本次范围。
+//
+// 命名约定:Experiment / Snapshot / Eval / RunDir 是纯数据,不带 Handle 后缀;
+// 唯一叫 AttemptHandle 的是 attempt —— 它的方法真的会碰磁盘,后缀标记的就是这件事。
 
-import type { EvalResult, RunSummary } from "../runner/types.ts";
-import type { O11ySummary, StreamEvent, TraceSpan } from "../o11y/types.ts";
-import type { DiffData } from "../scoring/types.ts";
-import type { SourceArtifact } from "../shared/types.ts";
+import type { EvalResult, RunSummary } from "../types.ts";
+import type { O11ySummary, StreamEvent, TraceSpan } from "../types.ts";
+import type { DiffData, SourceArtifact } from "../types.ts";
 
 /** attempt 级工件的种类;文件名恒为 `<kind>.json`,布局见 docs/results-format.md。 */
-export const ARTIFACT_KINDS = ["events", "sources", "trace", "o11y", "diff"] as const;
+export const ARTIFACT_KINDS = ["events", "trace", "o11y", "diff", "sources"] as const;
 export type ArtifactKind = (typeof ARTIFACT_KINDS)[number];
 
 /**
  * 回到证据的引用:run 目录名(相对结果根目录)+ summary.results[] 下标。
- * Reports 的 MetricCell.refs 与 view 深链 `#/attempt/<run>/<result>` 用的是同一个身份。
+ * 字段名(run / result)是 view 深链 `#/attempt/<run>/<result>` 的持久化路由契约,不随句柄改名;
+ * Reports 的 MetricCell.refs 用的是同一个身份。
  */
 export interface AttemptRef {
   run: string;
   result: number;
 }
 
-/** 一个落盘 run 目录;忠实反映磁盘,不合并、不去重。 */
-export interface RunHandle {
+/** 一个物理落盘 run 目录(低层忠实磁盘面);多数消费方走 experiments,不碰它。 */
+export interface RunDir {
   /** run 目录的绝对路径(summary.json 所在目录)。 */
   dir: string;
   /** 与写入侧同一类型的 RunSummary(results[] 是瘦身条目)。 */
   summary: RunSummary;
-  /** summary.results[] 逐条包一层懒加载句柄。 */
+  /** summary.results[] 逐条包一层懒加载句柄(按下标顺序)。 */
   attempts: AttemptHandle[];
 }
 
 /**
  * 单个 eval attempt:瘦身条目 + 重工件的懒加载方法。
- * 懒加载即存在性判断:工件缺失返回 null,不抛错;同一 handle 内读过一次即缓存。
+ * 懒加载即存在性判断:工件缺失返回 null,不抛错;同一 handle 内读过一次即记忆化。
+ * 工件定位按候选顺序回退:先本 run 的 artifactsDir,再 artifactBase 指向的原 run 目录
+ * (--resume 合入条目的工件留在原 run 里);原 run 被清理后如实返回 null。
  */
 export interface AttemptHandle {
-  /** 所属物理 run;去重「保留最新 run 的那份」靠它比较新旧。 */
-  run: RunHandle;
-  /** 本 attempt 的证据引用(run 目录名 + summary.results 下标);消费方不必自己反查下标。 */
-  ref: AttemptRef;
+  /** 属于哪道题 —— 直达字段,不绕 result。 */
+  evalId: string;
+  /** 属于哪个实验;落盘缺 experimentId 时是 "<agent>/<model>" 合成键(所属快照 synthetic: true)。 */
+  experimentId: string;
   /** EvalResult 瘦身条目:判决、断言、用量、成本、experiment 元数据。 */
   result: EvalResult;
+  /** 证据引用,指条目所在的落盘(合入后的新 run);工件经候选回退仍可达。 */
+  ref: AttemptRef;
+  /** 条目所在的物理落盘;去重「保留最新 run 目录里的那份」靠它比较新旧。 */
+  runDir: RunDir;
   events(): Promise<StreamEvent[] | null>;
   trace(): Promise<TraceSpan[] | null>;
   o11y(): Promise<O11ySummary | null>;
@@ -49,50 +58,133 @@ export interface AttemptHandle {
   sources(): Promise<SourceArtifact[] | null>;
 }
 
+/** 一道题在一个快照里的结果:id + 该题的全部 attempt(重试历史)。 */
+export interface Eval {
+  id: string;
+  attempts: AttemptHandle[];
+}
+
 /**
- * 快照 = 一个 experiment 在一个 run 里的那部分 attempt(experiment × run 切片)。
- * 一个 run 目录可以装多个 experiment(`niceeval exp compare`),所以「每个 experiment
- * 最新一次」只能用快照粒度表达,不能用 run 粒度。
+ * 快照 = 单次跑的实验(experiment × run 切片)。一个 run 目录可以装多个 experiment
+ * (`niceeval exp compare`),所以「每个 experiment 最新一次」只能用快照粒度表达。
  */
-export interface SnapshotHandle {
-  /** experiment id;结果里缺 experimentId 时以 "<agent>/<model>" 合成,并记入集合级 warnings。 */
+export interface Snapshot {
+  /** 结果里缺 experimentId 时以 "<agent>/<model>" 合成键,并经 latest() 记入 warnings。 */
   experimentId: string;
-  /** 所属物理 run。 */
-  run: RunHandle;
-  /** = run.summary.startedAt;快照新旧按它比较。 */
   startedAt: string;
-  /** 本快照自己的 agent —— 不是 run 顶层那个「第一个配置」。 */
+  /** 本快照自己的 agent —— 不是落盘顶层那个「第一个配置」。 */
   agent: string;
   model?: string;
+  /** 谁写的这份结果(niceeval 或第三方 harness;legacy 结果可能缺失)。 */
+  producer?: RunSummary["producer"];
+  /** 结果格式版本(能读进来的恒为当前版本;不兼容的在 skipped),缺失按 1。 */
+  schemaVersion: number;
+  /** 每道题一项:{ id, attempts };残缺检测 / 逐题遍历从这里走。 */
+  evals: Eval[];
+  /** 全部 attempt 平铺(= evals 逐题展开),不关心题目边界的聚合消费用。 */
   attempts: AttemptHandle[];
-  /** 覆盖的 eval 集合(去重,保持首次出现顺序),供选择器做残缺检测。 */
-  evalIds: string[];
-  /** experimentId 是合成键(结果里没有 experimentId)时为 true;选择器据此调整提示文案。 */
+  /** 所属物理落盘(低层面)。 */
+  runDir: RunDir;
+  /** experimentId 是合成键(结果里没有 experimentId)时为 true。 */
   synthetic?: boolean;
+  /** 写入时刻该实验已知的 eval 并集(可选);copySnapshots 自动补记,writer.snapshot() 也可声明。 */
+  knownEvalIds?: string[];
+}
+
+/** 一个实验的全部历史:同一 experiment id 的历次快照归在一起。 */
+export interface Experiment {
+  id: string;
+  /** 历次快照,最新在前。 */
+  snapshots: Snapshot[];
+  /** 最新一次(= snapshots[0])。 */
+  latest: Snapshot;
+  /** 已知 eval 并集 = 本地历史 ∪ 各快照携带的 knownEvalIds —— 残缺检测的分母。 */
+  evalIds: string[];
 }
 
-/** 目录扫描里读不了、但必须让调用方知道的 run;无关 JSON 不记(静默忽略)。 */
-export interface SkippedResultsRun {
+/** 目录扫描里读不了、但必须让调用方知道的落盘;无关 JSON 不记(静默忽略)。 */
+export interface SkippedRun {
   /** run 目录的绝对路径。 */
   dir: string;
-  /** summary.json 的绝对路径。 */
-  path: string;
-  reason: "incompatible-version" | "malformed";
-  /** incompatible-version:那份报告声明的 schemaVersion。 */
+  /**
+   * incompatible-version:schemaVersion 与读取器不同(不解析、不迁移、不降级);
+   * malformed:summary.json 是坏数据;
+   * incomplete:有 attempt 工件、没有 summary.json —— run 中途 crash、writer 没走到 finish()。
+   * summary 是收尾事实,reader 不读无 summary 的目录;已完成的工件留在盘上供手工排查。
+   */
+  reason: "incompatible-version" | "malformed" | "incomplete";
+  /** 那份结果声明的 schemaVersion(incomplete 没有 summary,自然缺失)。 */
   schemaVersion?: number;
-  /** incompatible-version:写报告的 niceeval 版本,拼 `npx niceeval@<version> view` 提示用。 */
-  producerVersion?: string;
+  /** 完整的 producer(name + version):只有 name === "niceeval" 才能拼 npx 提示,第三方如实报名字。 */
+  producer?: RunSummary["producer"];
   /** malformed:一句英文诊断。 */
   detail?: string;
 }
 
-/** openResults 的返回:runs 忠实磁盘;snapshots 只切片、不合并、不去重;skipped 不静默丢。 */
-export interface ResultsCollection {
-  /** 按 startedAt 降序(最新在前),同刻按目录名降序。 */
-  runs: RunHandle[];
-  /** 按 runs 顺序逐 run 切片;每个 experiment 在每个 run 里至多一个快照。 */
-  snapshots: SnapshotHandle[];
-  skipped: SkippedResultsRun[];
-  /** 集合级警告(如 experimentId 缺失时的合成键);渲染与否在消费方,缺口永远被算出来。 */
-  warnings: string[];
+/** openResults 的返回:experiments 分层;skipped 不静默丢;runDirs 忠实磁盘(新→旧)。 */
+export interface Results {
+  /** 每个实验一项,挂着自己的全部历史(id 字典序)。 */
+  experiments: Experiment[];
+  skipped: SkippedRun[];
+  /** 低层忠实磁盘面:物理落盘目录,新→旧;多数消费方不碰。 */
+  runDirs: RunDir[];
+  /**
+   * 每个实验取最新一次快照,返回 Selection(快照与挑选警告绑在一起走)。
+   * `experiments` 是 experiment id 前缀过滤(string | string[]),同 CLI 位置参数语义。
+   */
+  latest(opts?: { experiments?: string | string[] }): 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/results-lib.md「警告 kind 全集」。
+ */
+export type SelectionWarning =
+  | {
+      /** 选中快照的覆盖 < 该实验已知 eval 并集(本地历史 ∪ knownEvalIds)。 */
+      kind: "partial-coverage";
+      experimentId: string;
+      covered: number;
+      total: number;
+      message: string;
+    }
+  | {
+      /** 该实验选中的快照早于选集中最新的落盘;无阈值,如实触发,要阈值消费方按字段自比。 */
+      kind: "stale-snapshot";
+      experimentId: string;
+      startedAt: string;
+      latestStartedAt: string;
+      message: string;
+    }
+  | {
+      /** 落盘缺 experimentId,以 "<agent>/<model>" 合成键(快照的 synthetic: true 同源)。 */
+      kind: "synthetic-experiment-id";
+      experimentId: string;
+      /** 该快照所在 run 目录的绝对路径。 */
+      runDir: string;
+      message: string;
+    };
+
+/** dedupeAttempts 的警告:身份键缺 startedAt,宁可不去重也不误删。 */
+export interface DedupeWarning {
+  kind: "missing-startedAt";
+  experimentId: string;
+  evalId: string;
+  message: string;
 }