@zhushanwen/subagent-core 0.2.0 → 0.5.1

package/src/shared/agent-ref.ts

@@ -8,6 +8,13 @@
  *
  * 名字不再是引用——只是注入段展示标签。执行侧拿到引用后一律 normalizeRef →
  * 文件加载（AgentRegistry.loadByPath / WorkflowScriptRegistry.getPath）。
+ *
+ * `..` 路径段拒绝（sink 设计 ⛔2 声明的安全收紧，agent .md 与 workflow .js 引用
+ * 同受此面——两宿主现状均放行，非等值变更）：`/x/../y.md` 形态允许引用逃逸出
+ * 注入段声明的目录集（G1 例 2），引用串含 `..` 段一律拒绝。检测在 `~/` 展开前的
+ * 原始引用上——join 展开会 normalize 消解 `..` 段（`~/../x` → `<home>/../x` 被解析
+ * 成已消解路径），原始串检测使 `~/../x.md` 与 `/x/../y.md` 同判（`..` 逃逸向量与
+ * 前缀形态无关）。保留 `.` 段与 `~/` 展开——最小收紧，不伤合法引用。
  */
 import { homedir } from "node:os";
 import { isAbsolute, join } from "node:path";
@@ -16,15 +23,25 @@ import { isAbsolute, join } from "node:path";
 const HOME_DIR_PREFIX = "~/";
 
 /**
- * 归一化资源引用：~ 展开 + 绝对路径校验。
+ * 引用串是否含 `..` 段（`/x/../y`、`x\..\y`、`~/../x` 同判——展开前检测）。
+ * 手动 split(/[\\/]) 与 displayAgentName 同款跨平台切分（本模块避免平台分支）。
+ */
+function hasParentSegment(ref: string): boolean {
+  return ref.split(/[\\/]/).includes("..");
+}
+
+/**
+ * 归一化资源引用：~ 展开 + 绝对路径校验 + `..` 段拒绝（⛔2 安全收紧）。
  *
  * @param ref   原始引用（注入段 location / 工具参数值）
  * @param ext   期望扩展名（如 ".md" / ".js"），不匹配返回 null
- * @returns 归一化绝对路径；非法（空/相对路径/扩展名不符）返回 null
+ * @returns 归一化绝对路径；非法（空/相对路径/含 `..` 段/扩展名不符）返回 null
  */
 export function normalizeRef(ref: string, ext?: string): string | null {
   const trimmed = ref.trim();
   if (!trimmed) return null;
+  // ⛔2：`..` 段 = 目录逃逸向量，展开前检测（join 会 normalize 消解 `..`，展开后判会漏）
+  if (hasParentSegment(trimmed)) return null;
 
   const expanded = trimmed.startsWith(HOME_DIR_PREFIX)
     ? join(homedir(), trimmed.slice(HOME_DIR_PREFIX.length))
@@ -35,6 +52,130 @@ export function normalizeRef(ref: string, ext?: string): string | null {
   return expanded;
 }
 
+// ── 报错文案工厂（sink 设计 U1）──────────────────────────────
+
+/** invalidAgentRefMessage 的可选注入：宿主的清单段名（缺省 pi 的注入段）。 */
+export interface InvalidAgentRefMessageOptions {
+  /**
+   * 清单指引：宿主注入段名。缺省 `<available_subagents>`（pi 注入段）；第三宿主
+   * 注入段名不同（zsw `<available_agents>` 等）时注入替代，文案口径不变。
+   */
+  howToList?: string;
+}
+
+/**
+ * agent ref 非法的统一报错文案（消费方唯一文案口径——不各自拼 message）。
+ *
+ * 基准 = AgentRegistry.loadByPath(require) 的既有 throw 文案
+ * （"Invalid agent ref: ... absolute paths to .md files ..."），工厂收敛后该消费点
+ * 与后续宿主接线点共用此处。`..` 形态附纠正指引（⛔2 新失败路径——错误必须指向
+ * 恢复动作：去掉 `..` 段、改用注入段 location）。
+ */
+export function invalidAgentRefMessage(
+  ref: string,
+  opts?: InvalidAgentRefMessageOptions,
+): string {
+  const howToList = opts?.howToList ?? "<available_subagents>";
+  if (hasParentSegment(ref)) {
+    return (
+      `Invalid agent ref: ${ref}. Agent refs must be absolute paths to .md files ` +
+      `without ".." path segments (use <location> from ${howToList}).`
+    );
+  }
+  return (
+    `Invalid agent ref: ${ref}. Agent refs must be absolute paths to .md files ` +
+    `(use <location> from ${howToList}).`
+  );
+}
+
+// ── workflow ref 原语（sink 设计 U1 / §2.2 D3 行）────────────
+
+/** normalizeWorkflowRef 的可选注入：宿主已知的 workflow 名清单。 */
+export interface NormalizeWorkflowRefOptions {
+  /**
+   * 宿主注入的已知 workflow 名清单（内置 + 用户级，宿主按自身优先级合并去重——
+   * pi 为 config-loader 的 tmp>project>npm>user 去重产物，内置名优先已由该清单
+   * 体现）。省略 = 无已知名，全部裸名按 unknown_name 拒绝。
+   */
+  knownNames?: Iterable<string>;
+}
+
+/** workflow ref 名分支的保留字：`.` / `..` 是文件系统相对路径段保留语义，任何域不可作名引用。 */
+export const WORKFLOW_REF_RESERVED_NAMES: readonly string[] = [".", ".."];
+
+/** normalizeWorkflowRef 拒绝原因（结构化裁决——文案留宿主，与 knownNames 宿主注入哲学一致）。 */
+export type WorkflowRefInvalidReason =
+  | "empty" // 空引用
+  | "reserved" // 名分支命中保留字（保留字裁决优先于 knownNames）
+  | "unknown_name" // 裸名未命中 knownNames
+  | "not_absolute" // 路径分支：相对路径无基准
+  | "parent_segment" // 路径分支：含 `..` 段（⛔2 同面）
+  | "bad_ext"; // 路径分支：非 .js
+
+/**
+ * normalizeWorkflowRef 的三分裁决结果：
+ * - name    → 裸名命中 knownNames，按名引用（内置名优先已由宿主清单体现）
+ * - path    → 路径形态经 normalizeRef 全套校验（~/ 展开、绝对路径、.js、`..` 拒绝）
+ * - invalid → 拒绝（reason 给精确裁决原因，消费方出恢复指引）
+ */
+export type NormalizedWorkflowRef =
+  | { kind: "name"; name: string }
+  | { kind: "path"; path: string }
+  | { kind: "invalid"; ref: string; reason: WorkflowRefInvalidReason };
+
+/**
+ * workflow 引用统一原语（名/路径二分 + 保留字裁决 + 内置名优先，三层口径单源化——
+ * pi「收裸名+路径」、zsw「入口拒裸名/内层宽松」的统一替代）。
+ *
+ * 二分判据：含 `/`、`\` 分隔符或 `~` 前缀 → 路径分支；否则 → 裸名分支。对齐 pi
+ * 现行为「名字是简单标识符，路径串不会撞 workflow 名」（tool-workflow actionRun：
+ * get(name) 先于 getPath——名命中即用，不猜路径，内置名优先由此成立）。
+ *
+ * 裁决顺序（裸名分支）：保留字 > knownNames > unknown——保留字命中即拒，即便宿主
+ * 清单异常含保留字也不放行（`..` 若被当名接受会绕过路径域的 ⛔2 收紧）。
+ *
+ * 路径分支复用 normalizeRef(WORKFLOW_REF_EXT)：`..` 段拒绝、~/ 展开、扩展名校验
+ * 与 agent 域同面（G1：同一校验语义）。
+ */
+export function normalizeWorkflowRef(
+  ref: string,
+  opts?: NormalizeWorkflowRefOptions,
+): NormalizedWorkflowRef {
+  const trimmed = ref.trim();
+  if (!trimmed) return { kind: "invalid", ref, reason: "empty" };
+
+  const looksLikePath = trimmed.includes("/") || trimmed.includes("\\") || trimmed.startsWith("~");
+  if (looksLikePath) {
+    const path = normalizeRef(trimmed, WORKFLOW_REF_EXT);
+    if (path !== null) return { kind: "path", path };
+    // 失败原因细分（normalizeRef 返回 null 不带原因——此处按同一判据重放；重放
+    // 顺序与 normalizeRef 判序逐位对齐：parent_segment 先于 not_absolute，否则
+    // `a/../b.js` 类「相对路径 + 含 .. 段」被误归因 not_absolute，指引改绝对路径
+    // 后仍被 .. 段拒绝——两步误导。`..` 段对原始串检测，与展开前判位一致）
+    const expanded = trimmed.startsWith(HOME_DIR_PREFIX)
+      ? join(homedir(), trimmed.slice(HOME_DIR_PREFIX.length))
+      : trimmed;
+    const reason: WorkflowRefInvalidReason = hasParentSegment(trimmed)
+      ? "parent_segment"
+      : !isAbsolute(expanded)
+        ? "not_absolute"
+        : "bad_ext";
+    return { kind: "invalid", ref, reason };
+  }
+
+  // 裸名分支：保留字 > knownNames > unknown
+  if (WORKFLOW_REF_RESERVED_NAMES.includes(trimmed)) {
+    return { kind: "invalid", ref, reason: "reserved" };
+  }
+  const known = opts?.knownNames;
+  if (known !== undefined) {
+    for (const name of known) {
+      if (name === trimmed) return { kind: "name", name: trimmed };
+    }
+  }
+  return { kind: "invalid", ref, reason: "unknown_name" };
+}
+
 /** agentRef 扩展名。 */
 export const AGENT_REF_EXT = ".md";
 /** workflowRef 扩展名。 */

package/src/shared/atomic-write.ts

@@ -0,0 +1,323 @@
+/**
+ * 原子写原语（sink 设计 U6a / B6）：tmp+rename 的单一实现。
+ *
+ * 背景：core 内部曾散布 6-7 份 tmp+rename 写点（manifest-store / sessions-index /
+ * worktree-registry / engine-discovery / zcode preparer / zcode appserver-home），
+ * tmp 命名各异（`.tmp.<pid>` / `.tmp_<pid>_<rand>` / `.tmp-<pid>-<ts>`）、失败路径
+ * 清理纪律不齐（worktree-registry 失败时漏清残留 tmp）。本模块给出统一原语供全
+ * 部写点收敛（调用点迁移归 u-wire 单元，本单元只建原语）。现存消费方 4 处：
+ * manifest-store / sessions-index / worktree-registry / engine-discovery——zcode
+ * preparer 与 zcode appserver-home 两处写点已随 2026-09 共享宿主 HOME 重构删除。
+ *
+ * **统一 tmp 命名约定**：`<最终路径>.tmp.<pid>.<seq>-<rand>`。
+ * - `.tmp.` 标记向后兼容 manifest-store 既有扫描（`x.json` 的 tmp 名为
+ *   `x.json.tmp.…`，命中其 `.json.tmp.` 模式）；
+ * - pid 防两进程共用同一 tmp，seq+rand 防同进程内并发写同目标共用同一 tmp
+ *   （对齐 sessions-index tmp 后缀的双重防撞设计）。
+ *
+ * **失败清理语义**：写入或 rename 失败 → 尽力 unlink 自身 tmp（失败仅 debug
+ * 记录）→ 原错误原样上抛（不掩盖、不包装）。rename 成功后 tmp 已不存在，无需
+ * 清理。跨进程/跨历史的陈旧残留 tmp 不由写入路径处理——统一走
+ * listStaleTmpFiles / cleanupStaleTmpFiles 扫描入口（崩溃残留恢复语义的单点，
+ * 见 sink 设计 §4 S6）。
+ *
+ * **两种耐久档位**（对齐现存两族写点的生产模式）：
+ * - sync（writeAtomicFileSync）：writeFileSync + renameSync，无 fsync——对齐
+ *   worktree-registry / engine-discovery 两处同步写点现状（注册表/发现缓存类，
+ *   进程崩溃窗口可容忍）；
+ * - async（writeAtomicFile）：fsync 文件 → rename → 尽力 fsync 目录——对齐
+ *   manifest-store / sessions-index 的生产耐久模式（掉电也不丢已确认写入）。
+ */
+
+import { mkdirSync, readdirSync, renameSync, statSync, unlinkSync, writeFileSync } from "node:fs";
+import * as fsPromises from "node:fs/promises";
+import * as path from "node:path";
+
+import { getLogger } from "../core/logger.ts";
+import { toErrorMessage } from "../core/error-message.ts";
+
+const logger = getLogger("subagents");
+
+/** tmp 命名标记：`${最终路径}.tmp.${pid}.${uniq}`。 */
+const TMP_MARKER = ".tmp.";
+
+/** 解析约定 tmp 名：贪婪目标段 + `.tmp.` + pid + `.` + uniq（alnum/-）。 */
+const TMP_NAME_PATTERN = /^(.+)\.tmp\.(\d+)\.[0-9A-Za-z-]+$/;
+
+/** 同进程内 tmp 单调序号（与随机段联合防并发写同目标撞名）。 */
+let tmpSeq = 0;
+
+/** 随机段生成参数：base36 编码去掉「0.x」前缀后取 6 字符。 */
+const RAND_RADIX = 36;
+const RAND_SLICE_START = 2;
+const RAND_SLICE_END = 8;
+
+/**
+ * 目标文件的原子写 tmp 路径（统一约定：`<最终路径>.tmp.<pid>.<seq>-<rand>`）。
+ *
+ * 独立导出供调用方预告 tmp 名（如崩溃恢复扫描按约定反查）与测试锚定命名形态；
+ * 两个 write 原语内部各自调用（每次写独立 tmp，并发写同目标互不串写）。
+ */
+export function atomicTmpPathFor(filePath: string): string {
+  tmpSeq += 1;
+  const rand = Math.random().toString(RAND_RADIX).slice(RAND_SLICE_START, RAND_SLICE_END);
+  return `${filePath}${TMP_MARKER}${process.pid}.${tmpSeq}-${rand}`;
+}
+
+/** 约定 tmp 路径的解析视图。 */
+export interface AtomicTmpRef {
+  /** tmp 文件自身完整路径。 */
+  tmpPath: string;
+  /** 该 tmp 写入的目标路径（约定前缀还原）。 */
+  targetPath: string;
+  /** 创建该 tmp 的进程 pid（扫描方可据此实现存活过滤等策略）。 */
+  pid: number;
+}
+
+/**
+ * 解析约定 tmp 路径为目标视图；非约定形态返回 null。
+ *
+ * 注意贪婪匹配方向：目标名自身含 `.tmp.` 时（如 `foo.tmp.json.tmp.1-x`）
+ * 前缀段正确还原为 `foo.tmp.json`。反之，恰以 `.tmp.<数字>.<uniq>` 结尾的
+ * 用户文件会被误认——清理入口只应在受管目录（runtime 数据目录）内使用。
+ */
+export function parseAtomicTmpPath(tmpPath: string): AtomicTmpRef | null {
+  const match = TMP_NAME_PATTERN.exec(tmpPath);
+  if (match === null) return null;
+  return { tmpPath, targetPath: match[1], pid: Number(match[2]) };
+}
+
+// ── 写入原语 ─────────────────────────────────────────────────
+
+export interface AtomicWriteOptions {
+  /** 字符串内容的编码（默认 "utf8"；Uint8Array 内容忽略此项）。 */
+  encoding?: BufferEncoding;
+  /** 目标父目录缺失时递归创建（默认 true，对齐四处同步写点的 mkdir 纪律）。 */
+  ensureDir?: boolean;
+}
+
+export interface AtomicWriteFileOptions extends AtomicWriteOptions {
+  /**
+   * rename 成功后尽力 fsync 目标目录（默认 true）。POSIX 不要求；失败不否定
+   * 已成功的 rename（对齐 manifest-store/sessions-index 的 best-effort 目录
+   * fsync）。设 false 跳过（省两次目录句柄开销，弱耐久场景）。
+   */
+  fsyncDir?: boolean;
+}
+
+const DEFAULT_ENCODING: BufferEncoding = "utf8";
+
+/** 失败路径清理自身 tmp：尽力 unlink，失败仅 debug（不掩盖原错误）。 */
+function removeTmpBestEffortSync(tmpPath: string): void {
+  try {
+    unlinkSync(tmpPath);
+  } catch (cleanupErr) {
+    // tmp 可能已被 rename 消费或从未创建；原错误由调用方上抛
+    logger.debug("[subagent-core] atomic-write cleanup tmp failed", {
+      detail: toErrorMessage(cleanupErr),
+      tmpPath,
+    });
+  }
+}
+
+/**
+ * 同步原子写（writeFileSync + renameSync，无 fsync）。
+ *
+ * 读者要么看到旧版完整内容、要么看到新版完整内容，绝无半成品（rename 原子性）。
+ * 失败语义见模块头。适用 prep/注册表类高频小文件；需掉电耐久用 writeAtomicFile。
+ */
+export function writeAtomicFileSync(
+  filePath: string,
+  content: string | Uint8Array,
+  options: AtomicWriteOptions = {},
+): void {
+  const encoding = options.encoding ?? DEFAULT_ENCODING;
+  if (options.ensureDir !== false) {
+    mkdirSync(path.dirname(filePath), { recursive: true });
+  }
+  const tmpPath = atomicTmpPathFor(filePath);
+  try {
+    writeFileSync(tmpPath, content, encoding);
+    renameSync(tmpPath, filePath);
+  } catch (err) {
+    // rename 未成功 → 清理残留 tmp（尽力，不掩盖原错误）
+    removeTmpBestEffortSync(tmpPath);
+    throw err;
+  }
+}
+
+/**
+ * 异步原子写（fsync 文件 → rename → 尽力 fsync 目录）。
+ *
+ * manifest-store.writeManifest / sessions-index.saveIndex 生产耐久模式的统一
+ * 实现。失败语义见模块头。真异步（fs.promises，不阻塞 event loop）。
+ */
+export async function writeAtomicFile(
+  filePath: string,
+  content: string | Uint8Array,
+  options: AtomicWriteFileOptions = {},
+): Promise<void> {
+  const encoding = options.encoding ?? DEFAULT_ENCODING;
+  const fsyncDir = options.fsyncDir ?? true;
+  if (options.ensureDir !== false) {
+    mkdirSync(path.dirname(filePath), { recursive: true });
+  }
+  const tmpPath = atomicTmpPathFor(filePath);
+  const dirPath = path.dirname(filePath);
+
+  let renamed = false;
+  try {
+    // 1. 写 tmp → fsync 文件
+    const fh = await fsPromises.open(tmpPath, "w");
+    try {
+      await fh.writeFile(content, encoding);
+      await fh.sync();
+    } finally {
+      await fh.close();
+    }
+
+    // 2. rename tmp → final（放在 try 内：失败时 catch 清理 tmp）
+    await fsPromises.rename(tmpPath, filePath);
+    renamed = true;
+
+    // 3. fsync 目录（尽力：POSIX 不要求，失败不否定已成功的 rename）
+    if (fsyncDir) {
+      try {
+        const dirFh = await fsPromises.open(dirPath, "r");
+        try {
+          await dirFh.sync();
+        } finally {
+          await dirFh.close();
+        }
+      } catch (dirSyncErr) {
+        logger.debug("[subagent-core] atomic-write fsync dir failed", {
+          detail: toErrorMessage(dirSyncErr),
+          dirPath,
+        });
+      }
+    }
+  } catch (err) {
+    // rename 未成功 → 清理残留 tmp（尽力，不掩盖原错误）
+    if (!renamed) {
+      try {
+        await fsPromises.unlink(tmpPath);
+      } catch (cleanupErr) {
+        logger.debug("[subagent-core] atomic-write cleanup tmp failed", {
+          detail: toErrorMessage(cleanupErr),
+          tmpPath,
+        });
+      }
+    }
+    throw err;
+  }
+}
+
+// ── 崩溃残留扫描 / 清理（S6 统一恢复语义的单点）──────────────
+
+/**
+ * 扫描目录内全部约定形态的 tmp 文件（不做删除）。
+ *
+ * 供两类消费方：
+ * - cleanupStaleTmpFiles 的内部步骤；
+ * - 需要按域校验内容再决定「删 or 提升为正式文件」的宿主恢复逻辑
+ *   （manifest-store.recoverTmpFiles 模式：tmp 合法且目标缺失 → rename 提升）。
+ *
+ * 目录不存在 → 返回空数组（恢复扫描对未初始化布局宽容）。非约定形态文件
+ * 一律不认（用户数据零误伤边界见 parseAtomicTmpPath 注释）。
+ */
+export function listStaleTmpFiles(dir: string): AtomicTmpRef[] {
+  let names: string[];
+  try {
+    names = readdirSync(dir);
+  } catch (readdirErr) {
+    if (typeof (readdirErr as NodeJS.ErrnoException).code === "string" &&
+        (readdirErr as NodeJS.ErrnoException).code === "ENOENT") {
+      return [];
+    }
+    throw readdirErr;
+  }
+  const refs: AtomicTmpRef[] = [];
+  for (const name of names) {
+    // 以 join 后完整路径解析：targetPath 需带目录前缀（恢复提升 rename 用）
+    const ref = parseAtomicTmpPath(path.join(dir, name));
+    if (ref !== null) {
+      refs.push(ref);
+    }
+  }
+  return refs;
+}
+
+export interface CleanupStaleTmpOptions {
+  /**
+   * 只清理 mtime 早于 now - maxAgeMs 的残留（进程内在途写入的兜底保护窗口）。
+   * 缺省 = 全清（启动期恢复场景，目录归本进程管）。需按 pid 存活过滤的调用方
+   * 改用 listStaleTmpFiles 自行实现策略（ref.pid 可判活）。
+   */
+  maxAgeMs?: number;
+  /** maxAgeMs 的基准时刻（缺省 Date.now()；测试注入确定性时钟）。 */
+  now?: number;
+}
+
+export interface CleanupStaleTmpResult {
+  /** 已删除（含扫描与删除之间已消失的——幂等终态）。 */
+  removed: string[];
+  /** 因 maxAgeMs 窗口内被保留的（疑似他方在途写入）。 */
+  kept: string[];
+  /** unlink 失败的（尽力语义，错误已 debug 记录）。 */
+  failed: string[];
+}
+
+/**
+ * 清理目录内约定形态的 tmp 残留（单条失败不阻断其余条目，逐条结果回传）。
+ *
+ * 恢复语义（对齐 manifest-store.recoverTmpFiles 的删除分支泛化）：本函数只做
+ * 「删除」级恢复；「校验后提升为正式文件」需域知识（manifest 记录合法性），
+ * 由调用方基于 listStaleTmpFiles + parseAtomicTmpPath().targetPath 自行实现。
+ */
+export function cleanupStaleTmpFiles(
+  dir: string,
+  options: CleanupStaleTmpOptions = {},
+): CleanupStaleTmpResult {
+  const now = options.now ?? Date.now();
+  const result: CleanupStaleTmpResult = { removed: [], kept: [], failed: [] };
+  for (const ref of listStaleTmpFiles(dir)) {
+    if (options.maxAgeMs !== undefined) {
+      try {
+        const mtimeMs = statSync(ref.tmpPath).mtimeMs;
+        if (now - mtimeMs < options.maxAgeMs) {
+          result.kept.push(ref.tmpPath);
+          continue;
+        }
+      } catch (statErr) {
+        if (typeof (statErr as NodeJS.ErrnoException).code === "string" &&
+            (statErr as NodeJS.ErrnoException).code === "ENOENT") {
+          // 扫描与 stat 之间已消失（他方收尾）——按已删除的幂等终态记账
+          result.removed.push(ref.tmpPath);
+          continue;
+        }
+        logger.debug("[subagent-core] cleanupStaleTmpFiles stat failed", {
+          detail: toErrorMessage(statErr),
+          tmpPath: ref.tmpPath,
+        });
+        result.failed.push(ref.tmpPath);
+        continue;
+      }
+    }
+    try {
+      unlinkSync(ref.tmpPath);
+      result.removed.push(ref.tmpPath);
+    } catch (unlinkErr) {
+      if (typeof (unlinkErr as NodeJS.ErrnoException).code === "string" &&
+          (unlinkErr as NodeJS.ErrnoException).code === "ENOENT") {
+        result.removed.push(ref.tmpPath);
+      } else {
+        logger.debug("[subagent-core] cleanupStaleTmpFiles unlink failed", {
+          detail: toErrorMessage(unlinkErr),
+          tmpPath: ref.tmpPath,
+        });
+        result.failed.push(ref.tmpPath);
+      }
+    }
+  }
+  return result;
+}

package/src/shared/bounded-serialize.ts

@@ -0,0 +1,154 @@
+/**
+ * bounded JSON pretty 序列化原语（sink 设计 U6a / B7）。
+ *
+ * 来源：自 pi-sw（extensions/universal/subagent-workflow）interface/helpers.ts
+ * 的同名私有函数**逐字平移**（函数体逐字符一致，仅补 export）——输出与该实现
+ * 字节级一致，由 `__tests__/bounded-serialize.test.ts` 的等价锚定 + 硬编码字节
+ * 快照断言守护。pi-sw 本地实现删除与消费切换归 u-sw-misc 单元（设计 U11）。
+ */
+
+// ── bounded pretty 序列化（IF13/#19，TC5/ES5）────────────────
+
+const JSON_INDENT = 2;
+
+/**
+ * bounded JSON pretty 序列化：只生成会被保留的前缀（≤8000 输出与
+ * JSON.stringify(value, null, JSON_INDENT) 逐字节一致；>8000 输出与
+ * 全量序列化后 .slice(0, budget) + "\n... (truncated)" 逐字节一致——
+ * 等价测试锚定，见 __tests__/bounded-serialize.test.ts）。
+ *
+ * 现状成本：全量 stringify 产生数 MB 中间串再丢弃 99%；本函数在输出字符流
+ * 越过 budget 后停止一切生成。保真策略：原语（string/number/boolean/null/bigint）
+ * 逐值复用 JSON.stringify（转义/Unicode/数字格式原生一致，零重实现），仅结构
+ * 拼装（2 空格缩进/逗号/括号）自实现。
+ *
+ * 特殊值语义（TC5 a-d，与原生 JSON.stringify 全值域对齐）：
+ * (a) 含 toJSON 的对象 → 该子树整体走一次 JSON.stringify(subtree)（原生会先调
+ *     toJSON，如 Date 输出带引号序列化串；bounded 拼装展开会与原生不同）。注意
+ *     边界：toJSON 返回对象时原生 pretty 会按缩进展开，本实现按原语串接其
+ *     compact 形态——设计 TC5 锚定面为 Date 型（返回字符串）toJSON。
+ * (b) 任何 stringify 抛出（BigInt → TypeError）→ 整体回退 String(value)（对齐
+ *     旧实现整体 try/catch 的整串回退；禁止逐节点回退——输出形态与整串回退不同）。
+ * (c) 对象属性值为 undefined/function/symbol → 拼装时跳过（原生省略）。
+ * (d) 数组元素为 undefined/function/symbol → 序列化为 "null"（原生行为）。
+ *
+ * 截断边界（输出字符流层级，与对完整串 slice 逐字节等价）：逐段 append 时本段
+ * 会使总长越过 budget → 只 append 本段前 (budget - 已累积) 字符（恰好 budget，
+ * 可切在转义序列/括号中间，不补任何结构闭合）；越过（exceeded）才追加
+ * "\n... (truncated)" 标记——恰好 ===budget 不加（> 判定）。
+ *
+ * 祖先 Set 循环引用守卫：命中 → 整体回退 String(value)（同 (b) 整串回退语义）。
+ */
+export function boundedPrettySerialize(value: unknown, budget: number): string {
+  const ancestors = new Set<object>();
+  let out = "";
+  let exceeded = false;
+
+  /** 逐段追加：越过 budget 时截到恰好 budget 并置 exceeded（后续生成全部剪枝）。 */
+  function append(s: string): void {
+    if (exceeded) return;
+    if (out.length + s.length <= budget) {
+      out += s;
+      return;
+    }
+    out += s.slice(0, budget - out.length);
+    exceeded = true;
+  }
+
+  /** 数组分支：元素逐个缩进序列化（(d) undefined/function/symbol → "null"）。 */
+  function serializeArray(
+    arr: unknown[],
+    depth: number,
+    childIndent: string,
+    closeIndent: string,
+  ): void {
+    if (arr.length === 0) {
+      append("[]");
+      return;
+    }
+    append("[\n");
+    for (let i = 0; i < arr.length && !exceeded; i++) {
+      if (i > 0) append(",\n");
+      append(childIndent);
+      const el = arr[i];
+      // (d) 数组元素 undefined/function/symbol → "null"
+      if (el === undefined || typeof el === "function" || typeof el === "symbol") {
+        append("null");
+      } else {
+        serialize(el, depth + 1);
+      }
+    }
+    append("\n" + closeIndent + "]");
+  }
+
+  /** 对象分支：(c) 属性 undefined/function/symbol 跳过后逐对序列化。 */
+  function serializeObject(
+    obj: object,
+    depth: number,
+    childIndent: string,
+    closeIndent: string,
+  ): void {
+    // (c) 对象属性 undefined/function/symbol 跳过（Object.entries 同原生：
+    // 只取 own enumerable，symbol 键天然不出现；getter 求值语义与原生一致）
+    const entries = Object.entries(obj).filter(
+      ([, val]) => val !== undefined && typeof val !== "function" && typeof val !== "symbol",
+    );
+    if (entries.length === 0) {
+      append("{}");
+      return;
+    }
+    append("{\n");
+    for (let i = 0; i < entries.length && !exceeded; i++) {
+      if (i > 0) append(",\n");
+      append(childIndent + JSON.stringify(entries[i][0]) + ": ");
+      serialize(entries[i][1], depth + 1);
+    }
+    append("\n" + closeIndent + "}");
+  }
+
+  function serialize(v: unknown, depth: number): void {
+    if (exceeded) return;
+    const t = typeof v;
+    // 原语逐值复用原生序列化；bigint 的 JSON.stringify 抛 TypeError → 顶层 catch
+    // 整体回退 (b)；NaN/Infinity → "null"（原生行为）
+    if (v === null || t === "string" || t === "number" || t === "boolean" || t === "bigint") {
+      append(JSON.stringify(v));
+      return;
+    }
+    if (t === "object" && v !== null) {
+      const obj = v as object;
+      if (ancestors.has(obj)) {
+        // 循环引用 → 整体回退 String(value)（旧实现同款整串回退）
+        throw new TypeError("circular reference");
+      }
+      // (a) toJSON 子树整体 stringify（Reflect.get 取属性，避免不安全断言）
+      if (typeof Reflect.get(obj, "toJSON") === "function") {
+        append(JSON.stringify(obj));
+        return;
+      }
+      ancestors.add(obj);
+      const childIndent = " ".repeat(JSON_INDENT * (depth + 1));
+      const closeIndent = " ".repeat(JSON_INDENT * depth);
+      if (Array.isArray(obj)) {
+        serializeArray(obj as unknown[], depth, childIndent, closeIndent);
+      } else {
+        serializeObject(obj, depth, childIndent, closeIndent);
+      }
+      ancestors.delete(obj);
+      return;
+    }
+    // 顶层 undefined/function/symbol（调用方守卫后不可达；防御兜底对齐原生 "null"）
+    append(JSON.stringify(v) ?? "null");
+  }
+
+  try {
+    serialize(value, 0);
+    return exceeded ? out + "\n... (truncated)" : out;
+  } catch {
+    // (b) 整体回退：String(value)（超 budget 仍截断 + 标记，与旧实现截断路径一致）
+    const fallback = String(value);
+    return fallback.length > budget
+      ? fallback.slice(0, budget) + "\n... (truncated)"
+      : fallback;
+  }
+}