niceeval 0.10.3-canary.6 → 0.11.0

package/src/sandbox/resolve.test.ts

@@ -0,0 +1,100 @@
+// cases: docs/engineering/testing/unit/sandbox.md
+// 覆盖 provisioning「对外的空间轴映射」的调度端接线(见
+// docs/feature/sandbox/architecture.md#provisioning-失败与重试):`withDeterministicProvisionScope`
+// 只在 provider 自身分类判定为 "unknown"(确定性)时才把可证明死因浮出为 FailureClass.scope;
+// 瞬时失败(拒绝类/歧义类)重试耗尽后原样抛出,不附带 scope。这里直接注入 `work`/`classify`
+// 闭包(与 retry.test.ts 对 withProvisionRetry 的做法同形),不需要经过真实 provider SDK
+// ——provider 专属的错误形状已在 errors.test.ts 覆盖。
+import { describe, expect, it } from "vitest";
+import type { SandboxProvisionErrorKind } from "./errors.ts";
+import { type ResolvedSandbox, withDeterministicProvisionScope } from "./resolve.ts";
+
+function resolvedSandbox(environments?: Record<string, unknown>): ResolvedSandbox {
+  return {
+    provider: "docker",
+    exclusive: false,
+    ...(environments !== undefined ? { environments } : {}),
+  } as ResolvedSandbox;
+}
+
+function alwaysThrows(error: unknown): () => Promise<never> {
+  return async () => {
+    throw error;
+  };
+}
+
+describe("withDeterministicProvisionScope", () => {
+  it("attaches eval scope for template-not-found when the spec carries an environments table", async () => {
+    const error = new Error("template not found");
+    const r = resolvedSandbox({ "python-3.9": { image: "acme/py39" } });
+
+    await expect(
+      withDeterministicProvisionScope(alwaysThrows(error), () => "unknown" as SandboxProvisionErrorKind, r),
+    ).rejects.toBe(error);
+
+    expect((error as unknown as { _tag?: string })._tag).toBe("NiceevalClassifiedError");
+    expect((error as unknown as { class?: unknown }).class).toEqual({ retryable: false, scope: "eval" });
+  });
+
+  it("attaches experiment scope for template-not-found when the spec has no environments table", async () => {
+    const error = new Error("no such image: acme/missing:latest");
+    const r = resolvedSandbox(undefined);
+
+    await expect(
+      withDeterministicProvisionScope(alwaysThrows(error), () => "unknown" as SandboxProvisionErrorKind, r),
+    ).rejects.toBe(error);
+
+    expect((error as unknown as { class?: unknown }).class).toEqual({ retryable: false, scope: "experiment" });
+  });
+
+  it("attaches experiment scope for credentials-missing regardless of the environments table", async () => {
+    const error = Object.assign(new Error("Unauthorized, please check your credentials."), { name: "AuthenticationError" });
+    const r = resolvedSandbox({ "python-3.9": { image: "acme/py39" } });
+
+    await expect(
+      withDeterministicProvisionScope(alwaysThrows(error), () => "unknown" as SandboxProvisionErrorKind, r),
+    ).rejects.toBe(error);
+
+    expect((error as unknown as { class?: unknown }).class).toEqual({ retryable: false, scope: "experiment" });
+  });
+
+  it("attaches experiment scope for permission-denied", async () => {
+    const error = new Error("pull access denied for acme/private-image");
+    const r = resolvedSandbox(undefined);
+
+    await expect(
+      withDeterministicProvisionScope(alwaysThrows(error), () => "unknown" as SandboxProvisionErrorKind, r),
+    ).rejects.toBe(error);
+
+    expect((error as unknown as { class?: unknown }).class).toEqual({ retryable: false, scope: "experiment" });
+  });
+
+  it("does not attach a scope for transient failures even after retries are exhausted", async () => {
+    const error = new Error("too many requests");
+    const r = resolvedSandbox({ "python-3.9": { image: "acme/py39" } });
+
+    await expect(
+      withDeterministicProvisionScope(alwaysThrows(error), () => "rate_limit" as SandboxProvisionErrorKind, r),
+    ).rejects.toBe(error);
+
+    expect((error as unknown as { _tag?: string })._tag).toBeUndefined();
+    expect((error as unknown as { class?: unknown }).class).toBeUndefined();
+  });
+
+  it("does not attach a scope for a deterministic error that matches none of the three provable causes", async () => {
+    const error = new Error("invalid argument: timeout must be positive");
+    const r = resolvedSandbox(undefined);
+
+    await expect(
+      withDeterministicProvisionScope(alwaysThrows(error), () => "unknown" as SandboxProvisionErrorKind, r),
+    ).rejects.toBe(error);
+
+    expect((error as unknown as { _tag?: string })._tag).toBeUndefined();
+  });
+
+  it("passes through a successful work() untouched", async () => {
+    const r = resolvedSandbox(undefined);
+    const result = await withDeterministicProvisionScope(async () => "sandbox", () => "unknown" as SandboxProvisionErrorKind, r);
+    expect(result).toBe("sandbox");
+  });
+});

package/src/sandbox/resolve.ts

@@ -13,6 +13,12 @@ import { t } from "../i18n/index.ts";
 import { reportActivity, reportDiagnostic } from "../runner/feedback/sink.ts";
 import { withProvisionRetry, type ProvisionSlot } from "./retry.ts";
 import { currentRunIdentity } from "./run-identity.ts";
+import {
+  attachProvisionFailureScope,
+  classifyProvisionConfigCause,
+  provisionConfigCauseScope,
+  type SandboxProvisionErrorKind,
+} from "./errors.ts";
 
 /** 归一化后的沙箱描述:确定的 provider + 各 provider 参数(只有对应 provider 用得上的会有值)。 */
 export interface ResolvedSandbox {
@@ -114,8 +120,10 @@ function fallbackFeedback(): ScopedFeedback {
   return {
     progress: (u) =>
       reportActivity(u.current !== undefined && u.total !== undefined ? `${u.message} (${u.current}/${u.total})` : u.message),
+    // key 只管折叠到多细(dedupeKey 里常编进 sandboxId 之类的实例细节),对外的稳定词法
+    // 一律是 code —— 不带 code 时 json.ts 会回落成 `code ?? key`,把复合去重串当成词法透出去。
     diagnostic: (d) =>
-      reportDiagnostic({ key: d.dedupeKey ?? d.code, severity: d.level, message: d.message, data: d.data }),
+      reportDiagnostic({ key: d.dedupeKey ?? d.code, code: d.code, severity: d.level, message: d.message, data: d.data }),
   };
 }
 
@@ -148,6 +156,40 @@ export function createSandbox(opts: {
   );
 }
 
+/**
+ * spec 是否带 `environments` 表:决定「模板不存在」死因的 scope 定档(见 errors.ts 的
+ * `provisionConfigCauseScope`)。查表本身(profile → 具体产物)是 runner/sandbox-selection.ts
+ * 的规划期职责;这里只读字段是否存在——`environments` 在 spec 声明了就会随 `resolveSandbox()`
+ * 的展开(以及 profile 派生 spec 的浅覆盖)原样带到这里,不需要重新解析 profile。
+ */
+function hasEnvironmentsTable(r: ResolvedSandbox): boolean {
+  const environments = (r as { environments?: unknown }).environments;
+  return typeof environments === "object" && environments !== null;
+}
+
+/**
+ * provisioning 失败向外浮出确定性配置死因的 scope(契约见
+ * docs/feature/sandbox/architecture.md#provisioning-失败与重试「对外的空间轴映射」)。
+ * `work` 失败后,只有 provider 自身分类判定为 `"unknown"`(确定性)时才进一步细分死因;
+ * 瞬时失败(拒绝类/歧义类)不论是否重试耗尽都原样抛出,不附带 scope——死因不可证明为
+ * 兄弟共享。导出供单测直接注入 `work`/`classify`,不需要经过真实 provider SDK。
+ */
+export async function withDeterministicProvisionScope<T>(
+  work: () => Promise<T>,
+  classify: (e: unknown) => SandboxProvisionErrorKind,
+  r: ResolvedSandbox,
+): Promise<T> {
+  try {
+    return await work();
+  } catch (e) {
+    if (classify(e) === "unknown") {
+      const cause = classifyProvisionConfigCause(e);
+      if (cause) attachProvisionFailureScope(e, provisionConfigCauseScope(cause, hasEnvironmentsTable(r)));
+    }
+    throw e;
+  }
+}
+
 async function createProvider(
   r: ResolvedSandbox,
   feedback: ScopedFeedback,
@@ -167,20 +209,25 @@ async function createProvider(
       // 运行标识(host/pid/startedAt)与 provision token 同一 label 机制:强杀之后
       // `sandbox list --orphans` / `prune` 按它事后核对与收回(见 run-identity.ts)。
       const runIdentity = currentRunIdentity();
-      return withProvisionRetry(
+      return withDeterministicProvisionScope(
         () =>
-          DockerSandbox.create({
-            timeout,
-            runtime: r.runtime,
-            image: r.image,
+          withProvisionRetry(
+            () =>
+              DockerSandbox.create({
+                timeout,
+                runtime: r.runtime,
+                image: r.image,
+                feedback,
+                provisionToken: token,
+                runIdentity,
+              }),
+            classifyProvisionError,
+            provisionSlot,
             feedback,
-            provisionToken: token,
-            runIdentity,
-          }),
+            () => reconcileProvision(token),
+          ),
         classifyProvisionError,
-        provisionSlot,
-        feedback,
-        () => reconcileProvision(token),
+        r,
       );
     }
     case "vercel": {
@@ -188,11 +235,16 @@ async function createProvider(
         throw new Error(t("sandbox.dependencyMissing.vercel"));
       });
       // vercel SDK 没有按元数据检索实例的通道:不传 reconcile,歧义类第一次抛出。
-      return withProvisionRetry(
-        () => VercelSandbox.create({ timeout, runtime: r.runtime, snapshotId: r.snapshotId, feedback }),
+      return withDeterministicProvisionScope(
+        () =>
+          withProvisionRetry(
+            () => VercelSandbox.create({ timeout, runtime: r.runtime, snapshotId: r.snapshotId, feedback }),
+            classifyProvisionError,
+            provisionSlot,
+            feedback,
+          ),
         classifyProvisionError,
-        provisionSlot,
-        feedback,
+        r,
       );
     }
     case "e2b": {
@@ -201,19 +253,24 @@ async function createProvider(
       });
       const token = randomUUID();
       const runIdentity = currentRunIdentity();
-      return withProvisionRetry(
+      return withDeterministicProvisionScope(
         () =>
-          E2BSandbox.create({
-            timeout,
-            runtime: r.runtime,
-            template: r.template,
-            provisionToken: token,
-            runIdentity,
-          }),
+          withProvisionRetry(
+            () =>
+              E2BSandbox.create({
+                timeout,
+                runtime: r.runtime,
+                template: r.template,
+                provisionToken: token,
+                runIdentity,
+              }),
+            classifyProvisionError,
+            provisionSlot,
+            feedback,
+            () => reconcileProvision(token),
+          ),
         classifyProvisionError,
-        provisionSlot,
-        feedback,
-        () => reconcileProvision(token),
+        r,
       );
     }
     case "local": {

package/src/shared/entry-file-store.test.ts

@@ -0,0 +1,149 @@
+// cases: docs/engineering/testing/unit/experiments-runner.md
+// 「用例锁与并发 Invocation」的共享原语半部——runner/teardown-registry.ts 与
+// sandbox/keep-registry.ts 各自的既有单测已经在验收"零行为变化"的迁移;这里只覆盖
+// entry-file-store.ts 自身语义无关的原语契约:写读往返、坏文件跳过、认领互斥、缺目录不抛错。
+
+import { afterEach, describe, expect, it } from "vitest";
+import { mkdir, mkdtemp, readdir, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import {
+  claimEntryFile,
+  hashEntryId,
+  readAllEntryFiles,
+  readEntryFile,
+  slugHashEntryId,
+  writeEntryFile,
+} from "./entry-file-store.ts";
+
+let dirs: string[] = [];
+async function makeDir(): Promise<string> {
+  const dir = await mkdtemp(join(tmpdir(), "niceeval-entry-file-store-"));
+  dirs.push(dir);
+  return dir;
+}
+afterEach(async () => {
+  await Promise.all(dirs.map((d) => rm(d, { recursive: true, force: true })));
+  dirs = [];
+});
+
+describe("hashEntryId / slugHashEntryId: 稳定、无碰撞", () => {
+  it("同样的 parts 反复调用得到同一个 id(稳定,可跨调用往返)", () => {
+    expect(hashEntryId(["a", "1"])).toBe(hashEntryId(["a", "1"]));
+  });
+
+  it("不同 parts 得到不同 id(无碰撞)", () => {
+    expect(hashEntryId(["a", "1"])).not.toBe(hashEntryId(["a", "2"]));
+    expect(hashEntryId(["a", "1"])).not.toBe(hashEntryId(["b", "1"]));
+  });
+
+  it("slugHashEntryId 带上可读 slug 前缀,且对同样输入稳定", () => {
+    const id = slugHashEntryId("exp/a-case one", ["exp/a", "case one"]);
+    expect(id.startsWith("exp-a-case-one-")).toBe(true);
+    expect(id).toBe(slugHashEntryId("exp/a-case one", ["exp/a", "case one"]));
+  });
+
+  it("slugHashEntryId 对不同 hashParts 产出不同 id,即使 slugSource 相同", () => {
+    const a = slugHashEntryId("same-slug", ["x", "1"]);
+    const b = slugHashEntryId("same-slug", ["x", "2"]);
+    expect(a).not.toBe(b);
+  });
+});
+
+describe("writeEntryFile / readEntryFile: 写读往返", () => {
+  it("写入后按 id 读回,内容与写入时相等", async () => {
+    const dir = await makeDir();
+    await writeEntryFile(dir, "abc123", { hello: "world", n: 1 });
+    const read = await readEntryFile<{ hello: string; n: number }>(dir, "abc123");
+    expect(read).toEqual({ hello: "world", n: 1 });
+  });
+
+  it("写入不残留 .tmp 临时文件", async () => {
+    const dir = await makeDir();
+    await writeEntryFile(dir, "abc123", { a: 1 });
+    const files = await readdir(dir);
+    expect(files.filter((f) => f.endsWith(".tmp"))).toEqual([]);
+    expect(files).toEqual(["abc123.json"]);
+  });
+
+  it("读不存在的 id 返回 undefined,不抛错", async () => {
+    const dir = await makeDir();
+    expect(await readEntryFile(dir, "nothing")).toBeUndefined();
+  });
+
+  it("读损坏 JSON 返回 undefined,不抛错", async () => {
+    const dir = await makeDir();
+    await mkdir(dir, { recursive: true });
+    await writeFile(join(dir, "bad.json"), "{not json", "utf-8");
+    expect(await readEntryFile(dir, "bad")).toBeUndefined();
+  });
+
+  it("读不存在的目录返回 undefined,不抛错", async () => {
+    const missing = join((await makeDir()), "does-not-exist");
+    expect(await readEntryFile(missing, "any")).toBeUndefined();
+  });
+
+  it("再次写入同一个 id 会覆盖旧内容", async () => {
+    const dir = await makeDir();
+    await writeEntryFile(dir, "abc123", { v: 1 });
+    await writeEntryFile(dir, "abc123", { v: 2 });
+    expect(await readEntryFile(dir, "abc123")).toEqual({ v: 2 });
+  });
+});
+
+describe("readAllEntryFiles: 全目录扫描", () => {
+  it("跳过损坏条目与点文件(dotfiles),不拖垮整次扫描", async () => {
+    const dir = await makeDir();
+    await writeEntryFile(dir, "good-1", { ok: true });
+    await writeEntryFile(dir, "good-2", { ok: true });
+    await mkdir(dir, { recursive: true });
+    await writeFile(join(dir, "corrupt.json"), "{not json", "utf-8");
+    await writeFile(join(dir, ".hidden-tmp.json"), JSON.stringify({ ok: true }), "utf-8");
+    await writeFile(join(dir, "not-json.txt"), "irrelevant", "utf-8");
+
+    const all = await readAllEntryFiles<{ ok: boolean }>(dir);
+    expect(all.map((e) => e.id).sort()).toEqual(["good-1", "good-2"]);
+  });
+
+  it("目录不存在时返回空集合,不抛错", async () => {
+    const missing = join((await makeDir()), "does-not-exist");
+    expect(await readAllEntryFiles(missing)).toEqual([]);
+  });
+
+  it("空目录返回空集合", async () => {
+    const dir = await makeDir();
+    expect(await readAllEntryFiles(dir)).toEqual([]);
+  });
+});
+
+describe("claimEntryFile: rename-墓碑认领互斥", () => {
+  it("认领存在的 entry 返回 true,并把文件从目录移除", async () => {
+    const dir = await makeDir();
+    await writeEntryFile(dir, "claim-me", { a: 1 });
+    expect(await claimEntryFile(dir, "claim-me")).toBe(true);
+    expect(await readEntryFile(dir, "claim-me")).toBeUndefined();
+    // 墓碑文件本身也应该被清理干净,不残留
+    const files = await readdir(dir);
+    expect(files).toEqual([]);
+  });
+
+  it("认领不存在的 entry 返回 false,不抛错", async () => {
+    const dir = await makeDir();
+    expect(await claimEntryFile(dir, "nothing-here")).toBe(false);
+  });
+
+  it("两个并发调用者竞争同一个 id:只有一方拿到 true", async () => {
+    const dir = await makeDir();
+    await writeEntryFile(dir, "contested", { a: 1 });
+    const results = await Promise.all([claimEntryFile(dir, "contested"), claimEntryFile(dir, "contested")]);
+    expect(results.sort()).toEqual([false, true]);
+  });
+
+  it("认领后目录里没有残留的 .claimed 墓碑文件", async () => {
+    const dir = await makeDir();
+    await writeEntryFile(dir, "claim-me", { a: 1 });
+    await claimEntryFile(dir, "claim-me");
+    const files = await readdir(dir);
+    expect(files.some((f) => f.includes(".claimed"))).toBe(false);
+  });
+});

package/src/shared/entry-file-store.ts

@@ -0,0 +1,117 @@
+// 逐条目原子文件原语:runner/teardown-registry.ts、sandbox/keep-registry.ts、runner/lock.ts
+// 共用的写盘纪律(临时文件 → fsync 文件 → rename → fsync 目录)与损坏容错的全目录扫描,以及
+// rename-墓碑认领互斥点。本模块语义无关——不知道登记/留存/锁各自的内容形状,也不做心跳、
+// 过期判断或 pid/host 这类判活逻辑,那些都留在各消费方自己的模块里。
+
+import { createHash, randomUUID } from "node:crypto";
+import { mkdir, open, readdir, readFile, rename, unlink } from "node:fs/promises";
+import { join } from "node:path";
+
+/** 纯哈希 entry id:parts 用 ":" 拼接后 sha256,取十六进制前缀。不带可读前缀,只须无碰撞。 */
+export function hashEntryId(parts: readonly string[], length = 12): string {
+  return createHash("sha256").update(parts.join(":")).digest("hex").slice(0, length);
+}
+
+/**
+ * slug + 哈希 entry id:人可读前缀(非 `[\w.-]` 字符替换为 `-`)拼接 `hashEntryId`,便于在目录里
+ * 目测定位是哪条身份;哈希部分仍然是唯一性的权威来源,slug 只是不承载解析的展示前缀。
+ */
+export function slugHashEntryId(slugSource: string, hashParts: readonly string[], length = 12): string {
+  const slug = slugSource.replace(/[^\w.-]/g, "-");
+  return `${slug}-${hashEntryId(hashParts, length)}`;
+}
+
+/** 原子写入一条 entry:临时文件 → fsync 文件 → rename → fsync 目录(尽力而为,见 fsyncDir)。 */
+export async function writeEntryFile(dir: string, id: string, data: unknown): Promise<void> {
+  await mkdir(dir, { recursive: true });
+  const tmpPath = join(dir, `.${id}.${process.pid}.tmp`);
+  const finalPath = join(dir, `${id}.json`);
+  const handle = await open(tmpPath, "w");
+  try {
+    await handle.writeFile(JSON.stringify(data, null, 2), "utf-8");
+    await handle.sync();
+  } finally {
+    await handle.close();
+  }
+  await rename(tmpPath, finalPath);
+  await fsyncDir(dir);
+}
+
+/** 读一条 entry(不存在或损坏都返回 undefined,不抛错)。 */
+export async function readEntryFile<T>(dir: string, id: string): Promise<T | undefined> {
+  try {
+    return JSON.parse(await readFile(join(dir, `${id}.json`), "utf-8")) as T;
+  } catch {
+    return undefined;
+  }
+}
+
+/** 读全部 entry(目录不存在返回空集合;跳过点文件与非 `.json` 文件;损坏条目跳过,不拖垮整次扫描)。 */
+export async function readAllEntryFiles<T>(dir: string): Promise<{ id: string; entry: T }[]> {
+  let files: string[];
+  try {
+    files = await readdir(dir);
+  } catch {
+    return [];
+  }
+  const out: { id: string; entry: T }[] = [];
+  for (const file of files) {
+    if (!file.endsWith(".json") || file.startsWith(".")) continue; // 点文件是在飞临时/墓碑文件
+    try {
+      const raw = await readFile(join(dir, file), "utf-8");
+      out.push({ id: file.slice(0, -".json".length), entry: JSON.parse(raw) as T });
+    } catch {
+      // 跳过损坏条目,不让一条坏文件拖垮整次扫描。
+    }
+  }
+  return out;
+}
+
+/**
+ * 认领互斥点:用 rename 把 entry 移到本次调用独有的墓碑名,而不是直接 `unlink`。同一个源路径的
+ * rename 只有一个调用者能命中——其余全部拿到 ENOENT,这把「谁先抢到」这件事和后续清理动作分开,
+ * 在某些文件系统里,并发对同一路径 `unlink` 的语义并不保证「恰好一个成功」,而并发 `rename` 到
+ * 各自独占的目标名没有这个歧义。抢到墓碑之后再尝试 `unlink` 墓碑并 fsync 目录,但即使墓碑清理
+ * 本身失败也不放弃已经拿到的认领权——它已经不在原路径,不会被第二个认领者看到。
+ *
+ * 两种上层用法共用同一个操作,只是拿到 `true` 之后做的事不同:
+ * - 「删除且只删一次」(收尾登记的用法):认领成功即代表删除完成,不必再写回。
+ * - 「接管后立刻在原路径重建」(用例锁的过期接管用法):认领成功后原路径已空出,赢家随即在
+ *   该路径写入自己的新记录;若这一步撞上 EEXIST(另一个赢家已经抢先写回),按认领失败处理即可,
+ *   不需要报错。
+ *
+ * 返回 `true` 即拿到认领权;返回 `false` 表示 entry 已被别的调用者认领或删除(rename 源
+ * ENOENT);其余错误原样抛出。
+ */
+export async function claimEntryFile(dir: string, id: string): Promise<boolean> {
+  const path = join(dir, `${id}.json`);
+  const claimedPath = join(dir, `.${id}.${process.pid}.${randomUUID()}.claimed`);
+  try {
+    await rename(path, claimedPath);
+  } catch (e) {
+    if ((e as NodeJS.ErrnoException).code === "ENOENT") return false;
+    throw e;
+  }
+  try {
+    await unlink(claimedPath);
+    await fsyncDir(dir);
+  } catch (e) {
+    // 已经夺得认领权;清理墓碑失败不允许把 entry 重新暴露给第二个认领者。
+    if ((e as NodeJS.ErrnoException).code !== "ENOENT") throw e;
+  }
+  return true;
+}
+
+/** 目录 fsync,尽力而为——部分平台/文件系统不支持目录 fsync(如 Windows),静默降级。 */
+export async function fsyncDir(dir: string): Promise<void> {
+  try {
+    const handle = await open(dir, "r");
+    try {
+      await handle.sync();
+    } finally {
+      await handle.close();
+    }
+  } catch {
+    // rename/rm 本身已是原子操作,fsync 只是尽力而为的额外保险。
+  }
+}

package/src/shared/failure-class.test.ts

@@ -0,0 +1,137 @@
+// cases: docs/engineering/testing/unit/eval.md
+import { describe, expect, it, vi } from "vitest";
+import {
+  EvalFatalError,
+  ExperimentFatalError,
+  attachFailureClass,
+  attemptFailureInfo,
+  failureClassOf,
+  resolveAttemptFailureClass,
+  type AttemptFailureInfo,
+} from "./failure-class.ts";
+
+describe("糖衣类 · 抛出点声明空间轴", () => {
+  it("ExperimentFatalError 携带 experiment 档,message 原样保留(它是走完全程的修复提示)", () => {
+    const error = new ExperimentFatalError("server probe failed — 修好隧道后重跑");
+    expect(failureClassOf(error)).toEqual({ retryable: false, scope: "experiment" });
+    expect(error.message).toBe("server probe failed — 修好隧道后重跑");
+  });
+
+  it("EvalFatalError 携带 eval 档,cause 原样透传", () => {
+    const cause = new Error("ENOENT");
+    const error = new EvalFatalError("fixture 缺失", { cause });
+    expect(failureClassOf(error)).toEqual({ retryable: false, scope: "eval" });
+    expect(error.cause).toBe(cause);
+  });
+
+  it("糖衣类是纯 Error 子类:instanceof Error 成立,可被常规 catch 捕获", () => {
+    expect(new ExperimentFatalError("x")).toBeInstanceOf(Error);
+    expect(new EvalFatalError("x")).toBeInstanceOf(Error);
+  });
+});
+
+describe("failureClassOf · 结构守卫", () => {
+  it("识别不依赖类身份:结构相同的手工对象同样命中(第二份 niceeval 实例下也不失效)", () => {
+    const impostor = { _tag: "NiceevalClassifiedError", class: { retryable: false, scope: "experiment" } };
+    expect(failureClassOf(impostor)).toEqual({ retryable: false, scope: "experiment" });
+  });
+
+  it("沿 cause 链穿透:糖衣类被上层库包装再抛,声明不丢失", () => {
+    const wrapped = new Error("sdk wrapper", { cause: new Error("layer 2", { cause: new EvalFatalError("boom") }) });
+    expect(failureClassOf(wrapped)).toEqual({ retryable: false, scope: "eval" });
+  });
+
+  it("取最外层命中:内外都带分类时,外层的声明生效", () => {
+    const outer = new ExperimentFatalError("outer", { cause: new EvalFatalError("inner") });
+    expect(failureClassOf(outer)).toEqual({ retryable: false, scope: "experiment" });
+  });
+
+  it("没有分类的错误、非对象值一律 undefined", () => {
+    expect(failureClassOf(new Error("plain"))).toBeUndefined();
+    expect(failureClassOf("just a string")).toBeUndefined();
+    expect(failureClassOf(undefined)).toBeUndefined();
+  });
+
+  it("`_tag` 对但 class 字段形状非法的对象不算命中(不把垃圾当分类喂给执行体)", () => {
+    expect(failureClassOf({ _tag: "NiceevalClassifiedError", class: { retryable: "yes" } })).toBeUndefined();
+    // retryable: true 必须带 reason(类型级规则),运行时进来的非法组合同样不认
+    expect(failureClassOf({ _tag: "NiceevalClassifiedError", class: { retryable: true } })).toBeUndefined();
+    expect(failureClassOf({ _tag: "NiceevalClassifiedError", class: { retryable: false, scope: "run" } })).toBeUndefined();
+  });
+});
+
+describe("attachFailureClass · 框架决议出的分类附着", () => {
+  it("挂上的两个字段不可枚举:不进 JSON,只是路由标记", () => {
+    const error = attachFailureClass(new Error("boom"), { retryable: false, scope: "eval" });
+    expect(failureClassOf(error)).toEqual({ retryable: false, scope: "eval" });
+    expect(Object.keys(error)).not.toContain("class");
+    expect(JSON.stringify({ ...error })).toBe("{}");
+  });
+
+  it("抛出点已声明过的分类不被框架覆盖", () => {
+    const declared = new ExperimentFatalError("tunnel down");
+    attachFailureClass(declared, { retryable: true, reason: "rate_limit" });
+    expect(failureClassOf(declared)).toEqual({ retryable: false, scope: "experiment" });
+  });
+
+  it("非对象抛出值原样返回,不制造新失败", () => {
+    expect(attachFailureClass("string failure", { retryable: false })).toBe("string failure");
+  });
+
+  it("冻结的错误对象标记不上也不抛错(分类是旁路)", () => {
+    const frozen = Object.freeze(new Error("frozen"));
+    expect(() => attachFailureClass(frozen, { retryable: false, scope: "eval" })).not.toThrow();
+    expect(failureClassOf(frozen)).toBeUndefined();
+  });
+});
+
+describe("resolveAttemptFailureClass · 生命周期阶段的三道链", () => {
+  const info = (error: unknown): AttemptFailureInfo => attemptFailureInfo("eval.setup", error);
+
+  it("抛出点携带的分类命中即定,不询问实验分类器", () => {
+    const classifier = vi.fn(() => ({ retryable: false as const, scope: "attempt" as const }));
+    expect(resolveAttemptFailureClass(info(new EvalFatalError("fixture missing")), classifier)).toEqual({
+      retryable: false,
+      scope: "eval",
+    });
+    expect(classifier).not.toHaveBeenCalled();
+  });
+
+  it("实验分类器认领第三方错误,scope 与自造 reason 原样生效", () => {
+    const result = resolveAttemptFailureClass(info(new Error("connect ECONNREFUSED tunnel.example:443")), (failure) =>
+      failure.text.includes("tunnel.example")
+        ? { retryable: false, scope: "experiment", reason: "tunnel_down" }
+        : undefined,
+    );
+    expect(result).toEqual({ retryable: false, scope: "experiment", reason: "tunnel_down" });
+  });
+
+  it("链上不挂兜底正则:限流文案在这些位置也不产时间轴,缺省不可重试", () => {
+    // 同一段文本在 turn 链上会被兜底判成 rate_limit 可重试;这里没有重试执行体,
+    // 时间轴即使给出也无人消费(见 architecture.md「分类链」)。
+    expect(resolveAttemptFailureClass(info(new Error("429 too many requests, please retry later")))).toEqual({
+      retryable: false,
+    });
+  });
+
+  it("实验分类器返回 undefined / 抛错都落缺省,不掩盖原始失败", () => {
+    expect(resolveAttemptFailureClass(info(new Error("boom")), () => undefined)).toEqual({ retryable: false });
+    expect(
+      resolveAttemptFailureClass(info(new Error("boom")), () => {
+        throw new Error("classifier bug");
+      }),
+    ).toEqual({ retryable: false });
+  });
+
+  it("分类器读到的 text 与报错文案同源:错误链(含 cause)message 串接", () => {
+    const error = new Error("eval setup failed", { cause: new Error("connect ECONNREFUSED tunnel.example:443") });
+    const seen: AttemptFailureInfo[] = [];
+    resolveAttemptFailureClass(attemptFailureInfo("eval.setup", error), (failure) => {
+      seen.push(failure);
+      return undefined;
+    });
+    expect(seen[0].phase).toBe("eval.setup");
+    expect(seen[0].text).toBe("eval setup failed · connect ECONNREFUSED tunnel.example:443");
+    expect(seen[0].cause).toBe(error);
+  });
+});