@zhushanwen/subagent-core 0.2.0 → 0.4.0

package/src/shared/__tests__/atomic-write.test.ts

@@ -0,0 +1,267 @@
+/**
+ * atomic-write 原语测试（sink 设计 U6a / B6，验收 §4 S6 的确定性子集）。
+ *
+ * 断言面：
+ * - 正常写（sync/async、string/Uint8Array、encoding、父目录自动创建）
+ * - 半截目标文件恢复语义：torn 目标被整体替换，读者只见旧版或完整新版
+ * - 失败路径残留 tmp 清理语义：原错误上抛 + 自身 tmp 清除
+ * - 陈旧 tmp 扫描/清理：约定形态识别、maxAgeMs 在途保护窗、幂等
+ * - 并发写同目标不串写：rename 原子性下并发读永不见混合/半截内容
+ *
+ * 观察口径：全部经真实文件系统（临时目录），无 fs mock（对齐 TEST-STRATEGY 红线）。
+ */
+import {
+  existsSync,
+  mkdirSync,
+  mkdtempSync,
+  readFileSync,
+  readdirSync,
+  rmSync,
+  utimesSync,
+  writeFileSync,
+} from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+
+import {
+  atomicTmpPathFor,
+  cleanupStaleTmpFiles,
+  listStaleTmpFiles,
+  parseAtomicTmpPath,
+  writeAtomicFile,
+  writeAtomicFileSync,
+} from "../atomic-write.ts";
+
+let dir: string;
+
+beforeEach(() => {
+  dir = mkdtempSync(join(tmpdir(), "atomic-write-test-"));
+});
+
+afterEach(() => {
+  rmSync(dir, { recursive: true, force: true });
+});
+
+/** 目录内约定形态 tmp 残留计数（断言「无残留」用）。 */
+function tmpResidue(targetDir: string): string[] {
+  return readdirSync(targetDir).filter((n) => n.includes(".tmp."));
+}
+
+describe("writeAtomicFileSync 正常写", () => {
+  it("字符串内容落盘，父目录缺失时自动创建（ensureDir 缺省 true）", () => {
+    const target = join(dir, "nested/deep/target.json");
+    writeAtomicFileSync(target, '{"a":1}');
+    expect(readFileSync(target, "utf8")).toBe('{"a":1}');
+  });
+
+  it("Uint8Array 内容逐字节落盘（encoding 不适用）", () => {
+    const target = join(dir, "bin/blob");
+    const bytes = Uint8Array.from([0x00, 0x01, 0xff, 0xfe, 0xe6, 0xb1, 0x89]);
+    writeAtomicFileSync(target, bytes);
+    expect(readFileSync(target)).toEqual(Buffer.from(bytes));
+  });
+
+  it("encoding 选项生效（latin1 单字节）", () => {
+    const target = join(dir, "enc.txt");
+    writeAtomicFileSync(target, "é", { encoding: "latin1" });
+    expect(readFileSync(target)).toEqual(Buffer.from([0xe9]));
+  });
+
+  it("ensureDir:false 且父目录缺失 → ENOENT 原样上抛", () => {
+    const target = join(dir, "missing/target.txt");
+    expect(() => writeAtomicFileSync(target, "x", { ensureDir: false })).toThrow(/ENOENT/);
+  });
+
+  it("写入后目录无 tmp 残留", () => {
+    const target = join(dir, "t.txt");
+    writeAtomicFileSync(target, "ok");
+    expect(tmpResidue(dir)).toEqual([]);
+  });
+});
+
+describe("writeAtomicFile 正常写（fsync 生产模式）", () => {
+  it("字符串内容落盘 + 父目录自动创建", async () => {
+    const target = join(dir, "a/b/c.json");
+    await writeAtomicFile(target, '{"n":1}');
+    expect(readFileSync(target, "utf8")).toBe('{"n":1}');
+    expect(tmpResidue(dir)).toEqual([]);
+  });
+
+  it("fsyncDir:false 可关目录 fsync（弱耐久场景）", async () => {
+    const target = join(dir, "fast.json");
+    await writeAtomicFile(target, "fast", { fsyncDir: false });
+    expect(readFileSync(target, "utf8")).toBe("fast");
+  });
+});
+
+describe("半截目标文件恢复语义（S6 确定性场景）", () => {
+  it("torn 目标被原子写整体替换：内容与长度精确等于新版本", () => {
+    const target = join(dir, "state.json");
+    writeFileSync(target, '{"half":tru', "utf8"); // 模拟非原子写半截产物
+    const full = JSON.stringify({ version: 2, entries: { a: 1, b: 2 } }, null, 2);
+    writeAtomicFileSync(target, full);
+    const after = readFileSync(target, "utf8");
+    expect(after).toBe(full);
+    expect(after.length).toBe(full.length);
+    expect(tmpResidue(dir)).toEqual([]);
+  });
+
+  it("async 写同样整体替换 torn 目标", async () => {
+    const target = join(dir, "state2.json");
+    writeFileSync(target, "{trun", "utf8");
+    await writeAtomicFile(target, '{"complete":true}');
+    expect(readFileSync(target, "utf8")).toBe('{"complete":true}');
+  });
+
+  it("崩溃残留 tmp 不影响新写入正确性，残留可被统一扫描+清理（恢复闭环）", () => {
+    const target = join(dir, "wf-state.json");
+    writeFileSync(target, "{old", "utf8");
+    // 模拟上次进程死在 tmp 阶段的残留（约定形态）
+    const staleTmp = atomicTmpPathFor(target);
+    writeFileSync(staleTmp, '{"pid-was":9,"entries":', "utf8");
+
+    // 新写入不受残留干扰：目标精确等于新内容
+    writeAtomicFileSync(target, '{"v":3}');
+    expect(readFileSync(target, "utf8")).toBe('{"v":3}');
+
+    // 残留仍可按约定反查目标路径 → 统一入口清理
+    const refs = listStaleTmpFiles(dir);
+    expect(refs).toHaveLength(1);
+    expect(refs[0].targetPath).toBe(target);
+    expect(refs[0].tmpPath).toBe(staleTmp);
+    const result = cleanupStaleTmpFiles(dir);
+    expect(result.removed).toEqual([staleTmp]);
+    expect(existsSync(staleTmp)).toBe(false);
+    expect(existsSync(target)).toBe(true);
+    expect(readFileSync(target, "utf8")).toBe('{"v":3}');
+  });
+});
+
+describe("写入失败残留 tmp 清理语义", () => {
+  it("sync：rename 失败（目标是目录）→ 原错误上抛 + 自身 tmp 清除", () => {
+    const target = join(dir, "occupied");
+    mkdirSync(target);
+    writeFileSync(join(target, "child.txt"), "block", "utf8"); // 非空目录确保 rename 失败
+    expect(() => writeAtomicFileSync(target, "x", { ensureDir: false })).toThrow();
+    expect(tmpResidue(dir)).toEqual([]);
+  });
+
+  it("async：rename 失败（目标是目录）→ 原错误 reject + 自身 tmp 清除", async () => {
+    const target = join(dir, "occupied-async");
+    mkdirSync(target);
+    writeFileSync(join(target, "child.txt"), "block", "utf8");
+    await expect(writeAtomicFile(target, "x", { ensureDir: false })).rejects.toThrow();
+    expect(tmpResidue(dir)).toEqual([]);
+  });
+});
+
+describe("统一 tmp 命名与扫描（B6 约定）", () => {
+  it("atomicTmpPathFor 命中约定标记且同进程内唯一", () => {
+    const target = join(dir, "x.json");
+    const a = atomicTmpPathFor(target);
+    const b = atomicTmpPathFor(target);
+    expect(a).toMatch(/\.tmp\.\d+\.[0-9a-z-]+$/);
+    expect(a.startsWith(`${target}.tmp.${process.pid}.`)).toBe(true);
+    expect(a).not.toBe(b);
+  });
+
+  it("parseAtomicTmpPath 往返解析；目标名含 .tmp. 时前缀正确还原", () => {
+    const ref = parseAtomicTmpPath("/data/x.json.tmp.4242.7-abc");
+    expect(ref).toEqual({
+      tmpPath: "/data/x.json.tmp.4242.7-abc",
+      targetPath: "/data/x.json",
+      pid: 4242,
+    });
+    // 目标名自身含 .tmp.：贪婪前缀还原到最近的 .tmp.<pid>.<uniq> 结构
+    const tricky = parseAtomicTmpPath("/data/foo.tmp.json.tmp.42.7-abc");
+    expect(tricky?.targetPath).toBe("/data/foo.tmp.json");
+    // 不合约定形态（uniq 段缺 pid 后的第二段 / pid 非数字）一律不认
+    expect(parseAtomicTmpPath("/data/foo.tmp.json.tmp.1-9")).toBeNull();
+    expect(parseAtomicTmpPath("/data/plain.json")).toBeNull();
+    expect(parseAtomicTmpPath("/data/x.tmp.notpid.txt")).toBeNull();
+  });
+
+  it("listStaleTmpFiles 只认约定形态；目录不存在返回空（宽容扫描）", () => {
+    const target = join(dir, "m.json");
+    writeFileSync(atomicTmpPathFor(target), "1", "utf8");
+    writeFileSync(join(dir, "unrelated.txt"), "keep", "utf8");
+    writeFileSync(join(dir, "m.json.tmp.notpid"), "old-format", "utf8");
+    const refs = listStaleTmpFiles(dir);
+    expect(refs).toHaveLength(1);
+    expect(refs[0].targetPath).toBe(target);
+    expect(refs[0].pid).toBe(process.pid);
+    expect(listStaleTmpFiles(join(dir, "no-such-dir"))).toEqual([]);
+  });
+
+  it("cleanupStaleTmpFiles：maxAgeMs 窗口内保留（在途保护）、窗口外清除、幂等", () => {
+    const now = Date.now();
+    const oldTmp = atomicTmpPathFor(join(dir, "old.json"));
+    const freshTmp = atomicTmpPathFor(join(dir, "fresh.json"));
+    writeFileSync(oldTmp, "old", "utf8");
+    writeFileSync(freshTmp, "fresh", "utf8");
+    // mtime 全部确定性注入（文件系统真实 mtime 不可控）
+    const oldPast = new Date(now - 60_000);
+    const freshPast = new Date(now - 1_000);
+    utimesSync(oldTmp, oldPast, oldPast);
+    utimesSync(freshTmp, freshPast, freshPast);
+
+    const first = cleanupStaleTmpFiles(dir, { maxAgeMs: 10_000, now });
+    expect(first.removed).toEqual([oldTmp]);
+    expect(first.kept).toEqual([freshTmp]);
+    expect(existsSync(oldTmp)).toBe(false);
+    expect(existsSync(freshTmp)).toBe(true);
+
+    // 第二轮：fresh 已过窗 → 清除；无 maxAgeMs = 全清
+    const agedPast = new Date(now - 60_000);
+    utimesSync(freshTmp, agedPast, agedPast);
+    const second = cleanupStaleTmpFiles(dir, { maxAgeMs: 10_000, now });
+    expect(second.removed).toEqual([freshTmp]);
+    const third = cleanupStaleTmpFiles(dir);
+    expect(third).toEqual({ removed: [], kept: [], failed: [] });
+  });
+});
+
+describe("并发写同目标不串写", () => {
+  it("24 路并发 async 写 + 并发读：每次读要么旧版完整要么新版完整，绝不混合", async () => {
+    const target = join(dir, "contended.json");
+    const baseline = '{"i":-1,"blob":""}';
+    writeFileSync(target, baseline, "utf8"); // 旧版基线
+    const payloads = Array.from({ length: 24 }, (_, i) =>
+      JSON.stringify({ i, blob: `x${i}`.repeat(700), tag: `payload-${i}` }),
+    );
+
+    // 读循环与写并发：每次让出 macrotask 让 async 写推进；快照只收集不判断
+    const snapshots: string[] = [];
+    const reader = (async () => {
+      for (let k = 0; k < 120; k++) {
+        try {
+          snapshots.push(readFileSync(target, "utf8"));
+        } catch {
+          // ENOENT 理论不可达（基线先于并发段存在）；快照缺失由计数断言兜底
+        }
+        await new Promise((resolve) => setTimeout(resolve, 0));
+      }
+    })();
+
+    await Promise.all([...payloads.map((p) => writeAtomicFile(target, p)), reader]);
+    expect(snapshots.length).toBeGreaterThan(0);
+
+    // 每个快照字节级恰等于某一份完整版本（基线或 24 份 payload 之一）——串写/半截必产生集合外内容
+    const validFulls = new Set([baseline, ...payloads]);
+    for (const snap of snapshots) {
+      expect(validFulls.has(snap)).toBe(true);
+    }
+
+    const final = readFileSync(target, "utf8");
+    expect(payloads).toContain(final); // 终态恰为其中一份完整 payload
+    expect(tmpResidue(dir)).toEqual([]); // 全部 tmp 已被各自 rename 消费
+  });
+
+  it("sync 原语串发写：终态为最后一次写入的完整内容", () => {
+    const target = join(dir, "serial.json");
+    const payloads = Array.from({ length: 8 }, (_, i) => JSON.stringify({ seq: i }));
+    for (const p of payloads) writeAtomicFileSync(target, p);
+    expect(readFileSync(target, "utf8")).toBe(payloads[payloads.length - 1]);
+  });
+});

package/src/shared/__tests__/bounded-serialize.test.ts

@@ -0,0 +1,236 @@
+/**
+ * boundedPrettySerialize 测试（自 pi-sw helpers-bounded-serialize.test.ts 平移
+ * + 字节快照，sink 设计 U6a / B7 验收②：与 pi-sw 现实现输出字节一致）。
+ *
+ * 平移说明（对照方式选型，二选一之「硬编码快照样例」）：pi-sw 侧实现为
+ * helpers.ts 私有函数（唯一公共出口 notifyDone 固定 budget=8000，且其 import
+ * 链依赖 pi SDK / extension-protocol，不宜从 core 测试直连）。字节一致的锚定
+ * 由三层构成：
+ * 1. **等价参照平移**——pi-sw 既有测试的全部用例（含 legacySerialize 参照实现）
+ *    平移至此，在 budget=8000 与小 budget 矩阵上断言 core 实现 ≡ 参照；
+ * 2. **硬编码字节快照**——期望串以 JSON.stringify 规范行为基准手工固化为字面量
+ *    （不回读被测实现），锚死具体字节形态；
+ * 3. 实施期实跑 pi-sw 侧 helpers-bounded-serialize.test.ts（其断言即
+ *    pi-sw 实现 ≡ 同一参照），三方经公共参照闭环为字节一致。
+ */
+import { describe, expect, it } from "vitest";
+
+import { boundedPrettySerialize } from "../bounded-serialize.ts";
+
+/** pi-sw 旧实现参照（全量序列化 + 截断；同 helpers-bounded-serialize.test.ts）。 */
+function legacySerialize(x: unknown, budget = 8000): string {
+  let serialized: string;
+  try {
+    serialized = JSON.stringify(x, null, 2);
+  } catch {
+    serialized = String(x);
+  }
+  return serialized.length > budget
+    ? serialized.slice(0, budget) + "\n... (truncated)"
+    : serialized;
+}
+
+// ── 深嵌套大对象 fixture（平移）───────────────────────────────
+
+function deepNested(): unknown {
+  const root: Record<string, unknown> = {};
+  let cur = root;
+  for (let i = 0; i < 60; i++) {
+    cur.header = `level-${i}-数据`;
+    cur.items = Array.from({ length: 12 }, (__, j) => ({
+      id: j,
+      name: `item-${i}-${j}`,
+      tags: ["alpha", "βeta", "γλυφ"],
+      nested: { deep: { deeper: { value: i * 1000 + j } } },
+    }));
+    cur.next = {};
+    cur = cur.next as Record<string, unknown>;
+  }
+  cur.end = "leaf";
+  return root;
+}
+
+describe("bounded 序列化等价锚定（平移自 pi-sw，budget=8000）", () => {
+  it("深嵌套大对象（>8000）：与全量 stringify 后 slice+标记 逐字节一致", () => {
+    const x = deepNested();
+    expect(JSON.stringify(x, null, 2).length).toBeGreaterThan(10_000);
+    expect(boundedPrettySerialize(x, 8000)).toBe(legacySerialize(x));
+  });
+
+  it("循环引用 → String(value) 整串回退（不抛出）", () => {
+    const x: Record<string, unknown> = { a: 1 };
+    x.self = x;
+    expect(boundedPrettySerialize(x, 8000)).toBe(legacySerialize(x));
+    expect(boundedPrettySerialize(x, 8000)).toBe(String(x));
+  });
+
+  it("含 BigInt → String(value) 整串回退且不抛出（对齐旧整体 catch）", () => {
+    const x = { count: 10n, label: "big" };
+    expect(boundedPrettySerialize(x, 8000)).toBe(String(x));
+    expect(boundedPrettySerialize(x, 8000)).toBe(legacySerialize(x));
+  });
+
+  it("含 Date（toJSON）→ 与原生逐字节一致（带引号序列化串）", () => {
+    const x = { at: new Date(0), note: "ts" };
+    expect(boundedPrettySerialize(x, 8000)).toBe(legacySerialize(x));
+    expect(boundedPrettySerialize(x, 8000)).toContain('"1970-01-01T00:00:00.000Z"');
+  });
+
+  it("undefined/function 属性省略与原生一致；数组内 undefined/function → null", () => {
+    const x = {
+      keep: 1,
+      dropU: undefined,
+      dropF: () => 1,
+      arr: [undefined, 2, () => 3, null],
+    };
+    expect(boundedPrettySerialize(x, 8000)).toBe(legacySerialize(x));
+    expect(boundedPrettySerialize(x, 8000)).toBe(JSON.stringify(x, null, 2));
+  });
+
+  it("≤8000 全形态与原生逐字节一致（原语/数组/嵌套/NaN/Infinity/Unicode）", () => {
+    const cases: unknown[] = [
+      "plain string",
+      42,
+      true,
+      NaN,
+      Infinity,
+      [1, [2, [3, "x"]]],
+      { a: { b: { c: [1, "汉", { d: null }] } } },
+      { emptyObj: {}, emptyArr: [] },
+      { unicode: "line sep  pic ⌘" },
+    ];
+    for (const x of cases) {
+      expect(boundedPrettySerialize(x, 8000)).toBe(legacySerialize(x));
+    }
+  });
+});
+
+describe("截断边界（平移自 pi-sw，恰好 8000 / 8001 / 转义序列中间）", () => {
+  /** 构造 pretty 全文恰好 len 字符的对象：{\n  "a": "<S>"\n} = 13 + S.length。 */
+  function sizedStringObject(totalLen: number): { a: string } {
+    return { a: "x".repeat(totalLen - 13) };
+  }
+
+  it("恰好 8000：不加标记，输出 === 原生全文", () => {
+    const x = sizedStringObject(8000);
+    expect(JSON.stringify(x, null, 2).length).toBe(8000);
+    const out = boundedPrettySerialize(x, 8000);
+    expect(out).toBe(JSON.stringify(x, null, 2));
+    expect(out).not.toContain("(truncated)");
+    expect(out.length).toBe(8000);
+  });
+
+  it("8001：截到 8000 + 标记", () => {
+    const x = sizedStringObject(8001);
+    expect(JSON.stringify(x, null, 2).length).toBe(8001);
+    const out = boundedPrettySerialize(x, 8000);
+    expect(out).toBe(JSON.stringify(x, null, 2).slice(0, 8000) + "\n... (truncated)");
+    expect(out.length).toBe(8000 + "\n... (truncated)".length);
+  });
+
+  it("截断点落在转义序列中间（\\u0001 被切半）：与 slice 逐字节一致", () => {
+    const esc = "\u0001";
+    let x: unknown = null;
+    let full = "";
+    for (let pad = 0; pad < 40; pad++) {
+      const candidate = { pad: "p".repeat(pad), payload: Array.from({ length: 1200 }, () => esc + "汉") };
+      const s = JSON.stringify(candidate, null, 2);
+      if (s.length > 8000 && s.charCodeAt(7999) === 92) {
+        x = candidate;
+        full = s;
+        break;
+      }
+    }
+    expect(x).not.toBeNull();
+    expect(full.charCodeAt(7999)).toBe(92);
+    const out = boundedPrettySerialize(x, 8000);
+    expect(out).toBe(full.slice(0, 8000) + "\n... (truncated)");
+    expect(out.slice(0, 8000).endsWith("\\")).toBe(true);
+  });
+});
+
+describe("小 budget 矩阵（截断路径全覆盖：特殊值形态 × 边界刻度）", () => {
+  const budgets = [0, 1, 5, 13, 21, 50];
+  // 仅含确定性前缀形态。(b) 整串回退路径（BigInt/循环引用）不入矩阵：其回退只在
+  // 抛出/检环节点被实际生成时触发，截断先于该节点完成时输出结构前缀——与 pi-sw
+  // 逐字平移的既有行为一致，临界行为单独钉在下方用例。
+  const cases: unknown[] = [
+    { a: 1, b: [1, "汉", { d: null }] },
+    { at: new Date(0) },
+    { keep: 1, dropU: undefined, arr: [undefined, 2, null] },
+    [NaN, Infinity],
+    {},
+    [],
+  ];
+
+  it("确定性前缀形态在每个 budget 上与参照逐字节一致", () => {
+    for (const x of cases) {
+      for (const budget of budgets) {
+        expect(boundedPrettySerialize(x, budget)).toBe(legacySerialize(x, budget));
+      }
+    }
+  });
+
+  it("(b) 整串回退的触达边界：抛出节点被生成前截断则不回退（逐字平移的既有行为）", () => {
+    const big = { count: 10n, label: "big" };
+    // budget 13 = "{\n  \"count\": " 恰好收完 → 抛出节点被触达 → fallback 截断（≡ 参照）
+    expect(boundedPrettySerialize(big, 13)).toBe(legacySerialize(big, 13));
+    expect(boundedPrettySerialize(big, 13)).toBe("[object Objec\n... (truncated)");
+    // budget 12：截断在抛出节点前完成 → 结构前缀（非 fallback，≠ 参照的 "[..." 回退）
+    expect(boundedPrettySerialize(big, 12)).toBe('{\n  "count":\n... (truncated)');
+    // 循环引用同款：budget 1 时截断先于环检测 → 结构前缀 "{"
+    const circular: Record<string, unknown> = { a: 1 };
+    circular.self = circular;
+    expect(boundedPrettySerialize(circular, 1)).toBe("{\n... (truncated)");
+    expect(legacySerialize(circular, 1)).toBe("[\n... (truncated)"); // 参照为 fallback 形态
+  });
+});
+
+describe("硬编码字节快照（期望串固化为字面量，不回读实现）", () => {
+  it("小型对象全文", () => {
+    expect(boundedPrettySerialize({ a: 1, b: [1, "汉", { d: null }] }, 8000)).toBe(
+      '{\n  "a": 1,\n  "b": [\n    1,\n    "汉",\n    {\n      "d": null\n    }\n  ]\n}',
+    );
+  });
+
+  it("Date（toJSON）序列化串", () => {
+    expect(boundedPrettySerialize({ at: new Date(0) }, 8000)).toBe(
+      '{\n  "at": "1970-01-01T00:00:00.000Z"\n}',
+    );
+  });
+
+  it("undefined/function 省略 + 数组元素 null 化", () => {
+    expect(boundedPrettySerialize({ arr: [undefined, 2, () => 3, null] }, 8000)).toBe(
+      '{\n  "arr": [\n    null,\n    2,\n    null,\n    null\n  ]\n}',
+    );
+  });
+
+  it("NaN/Infinity → null；空容器 compact 形态", () => {
+    expect(boundedPrettySerialize([NaN, Infinity], 8000)).toBe('[\n  null,\n  null\n]');
+    expect(boundedPrettySerialize({}, 8000)).toBe("{}");
+    expect(boundedPrettySerialize([], 8000)).toBe("[]");
+  });
+
+  it("循环引用 / BigInt 整串回退字面量", () => {
+    const circular: Record<string, unknown> = { a: 1 };
+    circular.self = circular;
+    expect(boundedPrettySerialize(circular, 8000)).toBe("[object Object]");
+    expect(boundedPrettySerialize({ count: 10n }, 8000)).toBe("[object Object]");
+  });
+
+  it("转义序列形态与三档截断的字节字面量（全文 21 字符）", () => {
+    // {\n  "key": "\u0001"\n} = 21 字符；第 12 字符为转义起始反斜杠
+    const full = '{\n  "key": "\\u0001"\n}';
+    expect(boundedPrettySerialize({ key: "\u0001" }, 8000)).toBe(full);
+    // 恰好 21：不加标记
+    expect(boundedPrettySerialize({ key: "\u0001" }, 21)).toBe(full);
+    // budget 20：切掉收尾 }，标记另起一行（两个连续 \n）
+    expect(boundedPrettySerialize({ key: "\u0001" }, 20)).toBe(
+      '{\n  "key": "\\u0001"\n' + "\n... (truncated)",
+    );
+    // budget 13：切在转义序列中间——末尾裸反斜杠，不补闭合
+    expect(boundedPrettySerialize({ key: "\u0001" }, 13)).toBe(
+      '{\n  "key": "\\' + "\n... (truncated)",
+    );
+  });
+});