niceeval 0.12.1 → 0.12.2-canary.31

package/src/record/skipped-notice.ts

@@ -1,44 +0,0 @@
-// 把 unreadable 目录按 producer 版本分组——被跳过的 niceeval 自身落盘(incompatible)
-// 里,同一个 producer.version 的往往不止一份,给每份重复拼同一条 npx 提示没有意义。
-// 中性 results 层实现,show / view 两个宿主共用同一份分组结果,各自按自己的 CLI 语法
-// (show 走 `--run <结果根>`,view 走单快照路径)拼各自的命令文案。
-
-import type { Producer, UnreadableRun } from "./types.ts";
-
-/** 一组「同一 niceeval 版本写的、schemaVersion 不兼容」的落盘。 */
-export interface SkippedVersionGroup {
-  schemaVersion: number | undefined;
-  producer: Producer;
-  /** 该组下每份落盘的目录(绝对路径),保留原始顺序。 */
-  dirs: string[];
-}
-
-/**
- * 把 `unreadable` 拆成「可按版本分组给出统一 npx 建议的」与「其余原样列出的」两部分。
- * 只有 reason 为 `incompatible` 且 `producer.name === "niceeval"`、`producer.version`
- * 存在时才分组——第三方 harness 如实报名字版本、不拼 npx(docs/feature/record/library.md 的裁决);
- * 版本信息缺失时也没有可执行的统一建议,归入 `rest`。分组键是 `(producer.version, schemaVersion)`,
- * 因为同一 producer.version 理论上 schemaVersion 恒定,但落盘可能来自更旧的 patch 版本,
- * 拆开更保守。
- */
-export function groupIncompatibleVersionSkips(unreadable: readonly UnreadableRun[]): {
-  groups: SkippedVersionGroup[];
-  rest: UnreadableRun[];
-} {
-  const byKey = new Map<string, SkippedVersionGroup>();
-  const rest: UnreadableRun[] = [];
-  for (const s of unreadable) {
-    if (s.reason === "incompatible" && s.producer?.name === "niceeval" && s.producer.version) {
-      const key = `${s.producer.version}\u0000${s.schemaVersion ?? ""}`;
-      let group = byKey.get(key);
-      if (!group) {
-        group = { schemaVersion: s.schemaVersion, producer: s.producer, dirs: [] };
-        byKey.set(key, group);
-      }
-      group.dirs.push(s.dir);
-    } else {
-      rest.push(s);
-    }
-  }
-  return { groups: [...byKey.values()], rest };
-}

package/src/record/source-hash.ts

@@ -1,28 +0,0 @@
-// Eval 源码的归一化与哈希:discovery 时的捕获(src/runner/eval-source.ts)与证据重建
-// (annotated-source.ts 的完整源码树装配)必须对同一份源码算出同一个 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 用 createWriter),所以 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/record/timing-activity.test.ts

@@ -1,395 +0,0 @@
-// cases: docs/engineering/testing/unit/record.md
-// 覆盖类别:
-// - 开放 activity key 的往返与未知 key 读取
-// - Run / attempt 双时钟域
-// - TimingOrigin 的 attempt / run 两支
-// - publish / carry 对 timing 引用的忠实保留
-// - sandboxBuilds 与 timingNodeId 引用完整性
-
-import { afterEach, describe, expect, it } from "vitest";
-import { mkdtemp, readFile, rm } from "node:fs/promises";
-import { tmpdir } from "node:os";
-import { basename, join } from "node:path";
-import {
-  RECORD_SCHEMA_VERSION,
-  createWriter,
-  openRecord,
-  publish,
-  type EvalResult,
-  type SandboxBuildRecord,
-  type TimingActivity,
-} from "./index.ts";
-import { attemptOrigin, createRunTimingRecorder, createTimingRecorder, runOrigin } from "../runner/timing.ts";
-import { completeEvidenceCoverage } from "../assertions/coverage.ts";
-
-const roots: string[] = [];
-async function makeRoot(): Promise<string> {
-  const root = await mkdtemp(join(tmpdir(), "niceeval-timing-"));
-  roots.push(root);
-  return root;
-}
-afterEach(async () => {
-  await Promise.all(roots.splice(0).map((r) => rm(r, { recursive: true, force: true })));
-});
-
-function officialTurn(over: Partial<TimingActivity> = {}): TimingActivity {
-  return {
-    id: "n1",
-    key: "agent.turn",
-    label: "turn1",
-    startOffsetMs: 10,
-    durationMs: 100,
-    sessionIndex: 1,
-    turnIndex: 1,
-    ...over,
-  };
-}
-
-describe("开放 activity key 往返与未知 key 读取", () => {
-  it("writer 接受第三方未知 key 原样落盘;openRecord 读回同一棵树,不因 key 不在官方词表而拒绝", async () => {
-    const root = await makeRoot();
-    const writer = createWriter(root, { producer: { name: "third-party-harness", version: "1.0.0" } });
-    const snap = await writer.run({
-      experimentId: "timing/unknown-key",
-      agent: "custom",
-      startedAt: "2026-07-30T10:00:00.000Z",
-    });
-    const unknownChild: TimingActivity = {
-      id: "u1",
-      key: "acme.provider.image.pull",
-      label: "pull acme/base:latest",
-      startOffsetMs: 5,
-      durationMs: 40,
-      children: [officialTurn({ id: "n2", startOffsetMs: 12 })],
-    };
-    await snap.writeAttempt({
-      id: "q1",
-      attempt: 1,
-      verdict: "passed",
-      durationMs: 200,
-      executionMs: 180,
-      assertions: [],
-      evidenceCoverage: completeEvidenceCoverage,
-      phases: [
-        {
-          name: "sandbox.create",
-          durationMs: 50,
-          children: [unknownChild],
-        },
-        { name: "eval.run", durationMs: 130 },
-      ],
-    });
-    await snap.finish({
-      timings: [
-        {
-          id: "r1",
-          key: "vendor.cache.warm",
-          label: "warm vendor cache",
-          startOffsetMs: 0,
-          durationMs: 25,
-        },
-      ],
-    });
-
-    const record = await openRecord(root);
-    expect(record.unreadable).toHaveLength(0);
-    const run = record.experiments[0]!.latestRun;
-    expect(run.schemaVersion).toBe(RECORD_SCHEMA_VERSION);
-    expect(run.timings).toEqual([
-      { id: "r1", key: "vendor.cache.warm", label: "warm vendor cache", startOffsetMs: 0, durationMs: 25 },
-    ]);
-    const attempt = run.attempts[0]!;
-    const createPhase = attempt.result.phases?.find((p) => p.name === "sandbox.create");
-    expect(createPhase?.children?.[0]).toMatchObject({
-      key: "acme.provider.image.pull",
-      label: "pull acme/base:latest",
-      children: [{ key: "agent.turn", id: "n2" }],
-    });
-    // 未知 key 不进口径:executionMs 仍是写入值,不因子树变化重算。
-    expect(attempt.result.executionMs).toBe(180);
-    expect(attempt.result.verdict).toBe("passed");
-  });
-});
-
-describe("Run / attempt 双时钟域", () => {
-  it("两边 activity 同刻写入后读回各自相对本域起点;共享构建只在 Run 域", async () => {
-    const root = await makeRoot();
-    const runClock = createRunTimingRecorder(() => 1_000);
-    const attemptClock = createTimingRecorder(() => 5_000);
-    attemptClock.enter("sandbox.create");
-    const attemptChild = attemptClock.child({
-      key: "provider.image.pull",
-      label: "pull",
-      startOffsetMs: attemptClock.offsetNow(),
-      durationMs: 10,
-    });
-    attemptClock.closeCurrent();
-    const phases = attemptClock.finalize();
-
-    const buildNode = runClock.child({
-      key: "sandbox.build",
-      label: "build Dockerfile",
-      startOffsetMs: runClock.offsetNow(),
-      durationMs: 600_000,
-    });
-    const runTimings = runClock.finalize();
-
-    expect(attemptChild?.startOffsetMs).toBe(0);
-    expect(buildNode.startOffsetMs).toBe(0);
-    // 两域各自从 0 起算——同刻墙钟不同域不能混加。
-    expect(attemptChild?.startOffsetMs).toBe(buildNode.startOffsetMs);
-
-    const writer = createWriter(root, { producer: { name: "niceeval", version: "0.12.0" } });
-    const snap = await writer.run({
-      experimentId: "timing/dual-clock",
-      agent: "codex",
-      startedAt: "2026-07-30T11:00:00.000Z",
-    });
-    await snap.writeAttempt({
-      id: "q1",
-      attempt: 1,
-      verdict: "passed",
-      durationMs: 50,
-      executionMs: 40,
-      assertions: [],
-      evidenceCoverage: completeEvidenceCoverage,
-      phases,
-    });
-    const builds: SandboxBuildRecord[] = [
-      {
-        buildKey: "bk-1",
-        provider: "docker",
-        status: "built",
-        timingNodeId: buildNode.id,
-        inputs: { dockerfile: "Dockerfile" },
-      },
-    ];
-    await snap.finish({ timings: runTimings, sandboxBuilds: builds });
-
-    const run = (await openRecord(root)).experiments[0]!.latestRun;
-    expect(run.timings?.[0]?.key).toBe("sandbox.build");
-    expect(run.timings?.[0]?.durationMs).toBe(600_000);
-    expect(run.attempts[0]!.result.executionMs).toBe(40);
-    expect(run.attempts[0]!.result.phases?.some((p) => p.children?.some((c) => c.key === "sandbox.build"))).toBe(false);
-  });
-});
-
-describe("TimingOrigin 的 attempt / run 两支", () => {
-  it("attempt 支带锚点;run 支指向同一 timing node;缺失 origin 的 Run diagnostic 三态可区分", async () => {
-    const root = await makeRoot();
-    const writer = createWriter(root, { producer: { name: "niceeval", version: "0.12.0" } });
-    const snap = await writer.run({
-      experimentId: "timing/origin",
-      agent: "codex",
-      startedAt: "2026-07-30T12:00:00.000Z",
-    });
-    const buildId = "n-build-1";
-    await snap.writeAttempt({
-      id: "dep-a",
-      attempt: 1,
-      verdict: "errored",
-      durationMs: 0,
-      assertions: [],
-      evidenceCoverage: completeEvidenceCoverage,
-      error: {
-        code: "sandbox-build-failed",
-        message: "build failed",
-        origin: runOrigin(buildId),
-      },
-    });
-    await snap.writeAttempt({
-      id: "dep-b",
-      attempt: 1,
-      verdict: "errored",
-      durationMs: 0,
-      assertions: [],
-      evidenceCoverage: completeEvidenceCoverage,
-      error: {
-        code: "sandbox-build-failed",
-        message: "build failed",
-        origin: runOrigin(buildId),
-      },
-    });
-    await snap.writeAttempt({
-      id: "local-fail",
-      attempt: 1,
-      verdict: "errored",
-      durationMs: 5,
-      assertions: [],
-      evidenceCoverage: completeEvidenceCoverage,
-      error: {
-        code: "unexpected-error",
-        message: "boom",
-        origin: attemptOrigin("eval.run", "n-cmd"),
-      },
-      diagnostics: [{ code: "teardown-failed", level: "warning", detail: "cleanup hiccup", origin: attemptOrigin("sandbox.cleanup") }],
-    });
-    await snap.finish({
-      timings: [{ id: buildId, key: "sandbox.build", label: "build", startOffsetMs: 0, durationMs: 12, failed: true }],
-      diagnostics: [
-        { code: "build-failed", level: "error", detail: "shared build failed", origin: runOrigin(buildId) },
-        { code: "orphan-note", level: "warning", detail: "no origin on purpose" },
-      ],
-      sandboxBuilds: [
-        {
-          buildKey: "bk-fail",
-          provider: "docker",
-          status: "failed",
-          timingNodeId: buildId,
-          inputs: { dockerfile: "Dockerfile" },
-          error: { code: "build-failed", message: "exit 1" },
-        },
-      ],
-    });
-
-    const run = (await openRecord(root)).experiments[0]!.latestRun;
-    const deps = run.attempts.filter((a) => a.evalId.startsWith("dep-"));
-    expect(deps).toHaveLength(2);
-    expect(deps.every((a) => a.result.error?.origin.scope === "run" && a.result.error.origin.timingNodeId === buildId)).toBe(true);
-    const local = run.attempts.find((a) => a.evalId === "local-fail")!;
-    expect(local.result.error?.origin).toEqual({ scope: "attempt", phase: "eval.run", timingNodeId: "n-cmd" });
-    expect(run.diagnostics).toEqual([
-      { code: "build-failed", level: "error", detail: "shared build failed", origin: { scope: "run", timingNodeId: buildId } },
-      { code: "orphan-note", level: "warning", detail: "no origin on purpose" },
-    ]);
-  });
-});
-
-describe("publish / carry 对 timing 引用的忠实保留", () => {
-  it("publish 恒复制 timings、sandboxBuilds 与 attempt phases;携带条目 phases 原样保留且不继承本 Run timings", async () => {
-    const root = await makeRoot();
-    const writer = createWriter(root, { producer: { name: "niceeval", version: "0.12.0" } });
-    const original = await writer.run({
-      experimentId: "timing/publish",
-      agent: "codex",
-      startedAt: "2026-07-30T13:00:00.000Z",
-    });
-    const buildId = "n-b";
-    await original.writeAttempt({
-      id: "q1",
-      attempt: 1,
-      verdict: "passed",
-      durationMs: 30,
-      assertions: [],
-      evidenceCoverage: completeEvidenceCoverage,
-      phases: [{ name: "eval.run", durationMs: 30, children: [officialTurn()] }],
-    });
-    await original.finish({
-      timings: [{ id: buildId, key: "sandbox.build", label: "build", startOffsetMs: 0, durationMs: 9 }],
-      sandboxBuilds: [
-        { buildKey: "bk", provider: "docker", status: "hit", timingNodeId: buildId, inputs: { dockerfile: "Dockerfile" } },
-      ],
-    });
-
-    const source = await openRecord(root);
-    const sourceRun = source.experiments[0]!.latestRun;
-    const dest = await makeRoot();
-    await publish([sourceRun], dest);
-
-    const published = await openRecord(dest);
-    const pubRun = published.experiments[0]!.latestRun;
-    expect(pubRun.timings).toEqual(sourceRun.timings);
-    expect(pubRun.sandboxBuilds).toEqual(sourceRun.sandboxBuilds);
-    expect(pubRun.attempts[0]!.result.phases).toEqual(sourceRun.attempts[0]!.result.phases);
-
-    // 携带:新 Run 有自己的 timings;携带条目的 phases 仍是原 attempt 树,不出现本 Run 的 activity key。
-    const writer2 = createWriter(root, { producer: { name: "niceeval", version: "0.12.0" } });
-    const next = await writer2.run({
-      experimentId: "timing/publish",
-      agent: "codex",
-      startedAt: "2026-07-30T14:00:00.000Z",
-    });
-    const snapName = basename(original.dir);
-    const expDir = basename(join(original.dir, ".."));
-    const prior = sourceRun.attempts[0]!.result;
-    await writer2.writeAttemptFor({
-      ...prior,
-      agent: "codex",
-      experimentId: "timing/publish",
-      artifactBase: `${expDir}/${snapName}/q1/a1`,
-    } as EvalResult);
-    await next.finish({
-      timings: [{ id: "new-only", key: "agent.artifact.prepare", label: "prepare", startOffsetMs: 0, durationMs: 3 }],
-    });
-
-    const after = await openRecord(root);
-    const latest = after.experiments.find((e) => e.id === "timing/publish")!.latestRun;
-    expect(latest.timings?.[0]?.key).toBe("agent.artifact.prepare");
-    const carriedAttempt = latest.attempts.find((a) => a.carried)!;
-    expect(carriedAttempt.result.phases?.[0]?.children?.[0]?.key).toBe("agent.turn");
-    expect(JSON.stringify(carriedAttempt.result.phases)).not.toContain("agent.artifact.prepare");
-  });
-});
-
-describe("sandboxBuilds 与 timingNodeId 引用完整性", () => {
-  it("四 status 各可往返;timingNodeId 指向同份 timings;本表不复制 duration", async () => {
-    const root = await makeRoot();
-    const writer = createWriter(root, { producer: { name: "niceeval", version: "0.12.0" } });
-    const snap = await writer.run({
-      experimentId: "timing/builds",
-      agent: "codex",
-      startedAt: "2026-07-30T15:00:00.000Z",
-    });
-    await snap.writeAttempt({ id: "q1", attempt: 1, verdict: "passed", durationMs: 1, assertions: [], evidenceCoverage: completeEvidenceCoverage });
-    const timings: TimingActivity[] = [
-      { id: "t-hit", key: "sandbox.build", label: "query hit", startOffsetMs: 0, durationMs: 2 },
-      { id: "t-built", key: "sandbox.build", label: "cold build", startOffsetMs: 2, durationMs: 100 },
-      { id: "t-failed", key: "sandbox.build", label: "failed build", startOffsetMs: 102, durationMs: 5, failed: true },
-      { id: "t-cancelled", key: "sandbox.build", label: "cancelled", startOffsetMs: 107, durationMs: 1, failed: true },
-    ];
-    const builds: SandboxBuildRecord[] = [
-      { buildKey: "k-hit", provider: "docker", status: "hit", timingNodeId: "t-hit", inputs: { tag: "a" }, locator: "sha256:aaa" },
-      { buildKey: "k-built", provider: "docker", status: "built", timingNodeId: "t-built", inputs: { tag: "b" }, locator: "sha256:bbb" },
-      {
-        buildKey: "k-failed",
-        provider: "docker",
-        status: "failed",
-        timingNodeId: "t-failed",
-        inputs: { tag: "c" },
-        error: { code: "build-failed", message: "exit 1" },
-      },
-      { buildKey: "k-cancelled", provider: "docker", status: "cancelled", timingNodeId: "t-cancelled", inputs: { tag: "d" } },
-    ];
-    await snap.finish({ timings, sandboxBuilds: builds });
-
-    const onDisk = JSON.parse(await readFile(join(snap.dir, "run.json"), "utf-8"));
-    expect(onDisk.sandboxBuilds.every((b: SandboxBuildRecord) => !("durationMs" in b))).toBe(true);
-    const run = (await openRecord(root)).experiments[0]!.latestRun;
-    expect(run.sandboxBuilds?.map((b) => b.status)).toEqual(["hit", "built", "failed", "cancelled"]);
-    for (const b of run.sandboxBuilds ?? []) {
-      expect(run.timings?.some((t) => t.id === b.timingNodeId && t.key === "sandbox.build")).toBe(true);
-    }
-  });
-});
-
-describe("双时钟 recorder", () => {
-  it("attempt recorder 把 children 挂到当前锚点;Run recorder 把 activity 挂到根", () => {
-    let t = 0;
-    const attempt = createTimingRecorder(() => t);
-    attempt.enter("eval.run");
-    t = 10;
-    const turn = attempt.child({
-      key: "agent.turn",
-      label: "turn1",
-      startOffsetMs: attempt.offsetNow(),
-      durationMs: 5,
-      sessionIndex: 1,
-      turnIndex: 1,
-    });
-    attempt.closeCurrent();
-    const phases = attempt.finalize();
-    expect(phases?.[0]?.children?.[0]?.id).toBe(turn?.id);
-    expect(phases?.[0]?.children?.[0]?.key).toBe("agent.turn");
-
-    t = 0;
-    const run = createRunTimingRecorder(() => t);
-    t = 3;
-    const build = run.child({
-      key: "sandbox.build",
-      label: "build",
-      startOffsetMs: run.offsetNow(),
-      durationMs: 7,
-    });
-    expect(run.finalize()).toEqual([expect.objectContaining({ id: build.id, key: "sandbox.build", startOffsetMs: 3 })]);
-  });
-});

package/src/record/truncate.ts

@@ -1,116 +0,0 @@
-// 落盘大值截断(见 docs/feature/record/architecture.md「大值截断」)。
-// 运行时全量,落盘截断:落点唯一在 snap.writeAttempt(writer.ts)——不在 adapter、不在 OTLP
-// 解析、不在事件归一化里做。适用范围:events.json 的事件字段与 trace.json 的 span 属性里的
-// 任意字符串值,按 256 KiB 上限;commands.json 的 stdout/stderr 各自按 64 KiB 上限独立截断
-// (见「commandsjson」)——上限更小是因为现在成功命令也记录,体量不再天然有界于失败命令数。
-// 没有 flag、没有配置项;截断永远不影响判决(落盘是证据,不是评分输入)。
-
-import type { CommandExitEvidence, JsonValue, StreamEvent, TraceSpan, Truncation } from "../types.ts";
-
-/** events.json / trace.json 每个字符串值的落盘上限(UTF-8 字节)。 */
-export const ARTIFACT_VALUE_MAX_BYTES = 256 * 1024;
-
-/** commands.json 每条命令 stdout / stderr 各自的落盘上限(UTF-8 字节)。 */
-export const COMMAND_STREAM_MAX_BYTES = 64 * 1024;
-
-const encoder = new TextEncoder();
-
-/** 截断到 maxBytes(按 UTF-8 字符边界回退,不切断多字节字符),末尾追加人可读 marker。 */
-function truncateToBytes(value: string, originalBytes: number, maxBytes: number): string {
-  // 按字节预算切:先按「字节数 ≥ 字符数」粗切,再逐步回退到不超预算的字符边界。
-  let sliceLen = Math.min(value.length, maxBytes);
-  let head = value.slice(0, sliceLen);
-  while (encoder.encode(head).length > maxBytes && sliceLen > 0) {
-    // 超出量 ÷ 4(UTF-8 最长 4 字节)是安全的最小回退步长;循环兜底处理边界。
-    sliceLen -= Math.max(1, Math.ceil((encoder.encode(head).length - maxBytes) / 4));
-    head = value.slice(0, sliceLen);
-  }
-  const kept = encoder.encode(head).length;
-  return `${head}\n[niceeval] truncated ${originalBytes} → ${kept} bytes`;
-}
-
-function truncateString(value: string, originalBytes: number): string {
-  return truncateToBytes(value, originalBytes, ARTIFACT_VALUE_MAX_BYTES);
-}
-
-/**
- * 深度遍历一个 JSON 值,截断其中超限的字符串;返回(可能新建的)值与收集到的截断记录。
- * `path` 用点分段(数组下标同样入段),事件里从字段名起、span 属性里从 attribute key 起。
- */
-function truncateJsonValue(value: JsonValue, path: string, out: Truncation[]): JsonValue {
-  if (typeof value === "string") {
-    const bytes = encoder.encode(value).length;
-    if (bytes <= ARTIFACT_VALUE_MAX_BYTES) return value;
-    out.push({ path, originalBytes: bytes });
-    return truncateString(value, bytes);
-  }
-  if (Array.isArray(value)) {
-    let changed = false;
-    const next = value.map((v, i) => {
-      const r = truncateJsonValue(v, `${path}.${i}`, out);
-      if (r !== v) changed = true;
-      return r;
-    });
-    return changed ? next : value;
-  }
-  if (value !== null && typeof value === "object") {
-    let changed = false;
-    const next: globalThis.Record<string, JsonValue> = {};
-    for (const [k, v] of Object.entries(value)) {
-      const r = truncateJsonValue(v, path ? `${path}.${k}` : k, out);
-      if (r !== v) changed = true;
-      next[k] = r;
-    }
-    return changed ? next : value;
-  }
-  return value;
-}
-
-/** events.json 落盘前的截断:逐事件处理全部字符串字段,超限的加结构化 `truncated` 标记。 */
-export function truncateEvents(events: readonly StreamEvent[]): StreamEvent[] {
-  return events.map((event) => {
-    const out: Truncation[] = [];
-    const next: globalThis.Record<string, JsonValue> = {};
-    let changed = false;
-    for (const [k, v] of Object.entries(event) as [string, JsonValue][]) {
-      if (k === "type" || k === "truncated") {
-        next[k] = v;
-        continue;
-      }
-      const r = truncateJsonValue(v, k, out);
-      if (r !== v) changed = true;
-      next[k] = r;
-    }
-    if (!changed) return event;
-    return { ...event, ...next, truncated: [...(event.truncated ?? []), ...out] } as StreamEvent;
-  });
-}
-
-/** trace.json 落盘前的截断:span 属性里的任意字符串值(name 一并覆盖——可携带动态内容)。 */
-export function truncateSpans(spans: readonly TraceSpan[]): TraceSpan[] {
-  return spans.map((span) => {
-    const out: Truncation[] = [];
-    const attributes = span.attributes
-      ? truncateJsonValue(span.attributes, "", out) as TraceSpan["attributes"]
-      : span.attributes;
-    if (out.length === 0) return span;
-    return { ...span, attributes, truncated: [...(span.truncated ?? []), ...out] };
-  });
-}
-
-/** commands.json 落盘前的截断:stdout / stderr 各自独立按 `COMMAND_STREAM_MAX_BYTES` 截断。 */
-export function truncateCommands(commands: readonly CommandExitEvidence[]): CommandExitEvidence[] {
-  return commands.map((command) => {
-    const out: Truncation[] = [];
-    const next: { stdout?: string; stderr?: string } = {};
-    for (const path of ["stdout", "stderr"] as const) {
-      const value = command[path];
-      const bytes = encoder.encode(value).length;
-      if (bytes <= COMMAND_STREAM_MAX_BYTES) continue;
-      out.push({ path, originalBytes: bytes });
-      next[path] = truncateToBytes(value, bytes, COMMAND_STREAM_MAX_BYTES);
-    }
-    if (out.length === 0) return command;
-    return { ...command, ...next, truncated: [...(command.truncated ?? []), ...out] };
-  });
-}