@geoly-ai/skills-hub 0.1.0

package/src/exit-codes.mjs

@@ -0,0 +1,265 @@
+// 退出码 —— 规格见 09-cli.md §6。
+//
+// 🔴 本模块**不 import 任何内核模块**。
+//    理由：它要给 `recover.mjs` / `trust.mjs` / `lock.mjs` / `journal.mjs` 抛出来的错分类，
+//    真去 import 它们会立刻绕成环（命令面 → 内核 → 退出码 → 内核）。
+//    因此分类**只按错误对象自身可观测的属性**：`exitCode` → `name` → 鸭子类型字段。
+//
+// 🔴 分类是**白名单式**的：认不出来的错**不给 0**（见下面 `UNCLASSIFIED` 的说明），
+//    绝不静默变成成功。
+
+/** 09-cli.md §6 的那张表，一个不多一个不少。 */
+export const EXIT = Object.freeze({
+  /** 全部成功（`skipped: 目录不存在` / `skipped: unsupported` 算成功） */
+  OK: 0,
+  /** 用法错误 / 解析失败 / 候选歧义 */
+  USAGE: 1,
+  /** 完整性失败：验签失败、摘要不符、算法不认识、资产 sha256 不符、签名身份不对 */
+  INTEGRITY: 2,
+  /** 冲突未解决 */
+  CONFLICT: 3,
+  /** 部分 target 失败 */
+  PARTIAL: 4,
+  /** 残留事务需 recover；或锁被占用 */
+  NEEDS_RECOVER: 5,
+  /** 网络 / 缓存未命中 */
+  NETWORK: 6,
+  /** 需要认证或权限不足 */
+  AUTH: 7,
+  /** 陈旧：timestamp 过期且未给 --allow-stale */
+  STALE: 8,
+  /** 平台 / 文件系统不受支持；或 .geoly 是挂载点、检出嵌套 target */
+  UNSUPPORTED: 9,
+  /** target 不可写（无法创建 <target>/.geoly/） */
+  NOT_WRITABLE: 10,
+  /** CLI 版本低于 timestamp 的 min_cli_version */
+  MIN_CLI: 11,
+});
+
+/**
+ * 🔴 §6 **没有**为「CLI 自身出了 bug」开一格，而我们也不发明第 12 个码。
+ *
+ * 认不出来的错必须有一个去处，且那个去处**绝不能是 0**。这里落到 2，
+ * 并且**只在退出码这一层**与「制品有问题」同格 —— 两者的区分放在别处：
+ *   · 人类输出以「内部错误（CLI 自身的 bug，不是制品有问题）：」开头；
+ *   · `--json` 的 `error.unclassified` 为 `true`。
+ *
+ * ⚠️ **诚实边界**：只看退出码是分不出这两者的。要分就得读 JSON 或文案。
+ */
+export const UNCLASSIFIED = EXIT.INTEGRITY;
+
+// ── 命令面自己的错误类型 ────────────────────────────────────────────────────
+//
+// 🔴 每一个都带 `exitCode`，这样 `classify()` 的第一档就能定死，
+//    不必靠 `instanceof`（跨 ESM 实例的 instanceof 不可靠）也不必靠文案匹配。
+
+class CliError extends Error {
+  constructor(message, exitCode, extra = {}) {
+    super(message);
+    this.name = new.target.name;
+    this.exitCode = exitCode;
+    Object.assign(this, extra);
+  }
+}
+
+/** 用法错误：未知 flag、缺参数、被明令删除的开关（--no-verify 等）。 */
+export class UsageError extends CliError {
+  constructor(message, extra) { super(message, EXIT.USAGE, extra); }
+}
+
+/** §5 解析规则：多 namespace 同名、skill 与 pack 同名 —— **报错列候选，不猜**。 */
+export class AmbiguousError extends CliError {
+  constructor(message, candidates) {
+    super(message, EXIT.USAGE, { candidates: Object.freeze([...candidates]) });
+  }
+}
+
+/** 冲突未解决：未认领同名目录未给 --replace、§8.2 遮蔽未给 --shadow-global。 */
+export class ConflictError extends CliError {
+  constructor(message, extra) { super(message, EXIT.CONFLICT, extra); }
+}
+
+/**
+ * 部分 target 失败。🔴 只在「至少一个成功、至少一个失败」时用 ——
+ * 全失败不是「部分失败」，那应当照最严重的那条单项错误报。
+ */
+export class PartialFailure extends CliError {
+  constructor(message, results) { super(message, EXIT.PARTIAL, { results }); }
+}
+
+/** 网络 / 缓存未命中（含 `--offline` 下缓存没命中）。 */
+export class NetworkError extends CliError {
+  constructor(message, extra) { super(message, EXIT.NETWORK, extra); }
+}
+
+/** 需要认证或权限不足。 */
+export class AuthError extends CliError {
+  constructor(message, extra) { super(message, EXIT.AUTH, extra); }
+}
+
+/** 平台 / 文件系统不受支持（win32 非 WSL、拒绝的 fstype、挂载点、嵌套 target）。 */
+export class UnsupportedError extends CliError {
+  constructor(message, extra) { super(message, EXIT.UNSUPPORTED, extra); }
+}
+
+// ── 预检违规码 → 退出码 ─────────────────────────────────────────────────────
+//
+// 键取自 `target.mjs` 的 `V`。🔴 这里**写死字符串而不是 import V**：
+// 本模块不 import 内核（见文件头）。两边漂了会被 `test/cli-exit-codes.test.mjs`
+// 的「V 的每一个取值都在这张表里」那条断言抓住。
+
+const VIOLATION_EXIT = Object.freeze({
+  'fs.unsupported-fstype': EXIT.UNSUPPORTED,        // §2.2
+  'fs.cross-device': EXIT.UNSUPPORTED,              // §2.2
+  'geoly.is-mount-point': EXIT.UNSUPPORTED,         // §3.4 → §6 第 9 条点名
+  'geoly.mount-point-under': EXIT.UNSUPPORTED,      // §3.4
+  'target.nested': EXIT.UNSUPPORTED,                // §3.5 → §6 第 9 条点名
+  'target.symlink-in-chain': EXIT.UNSUPPORTED,      // §3.4
+  'target.not-plain-dir': EXIT.UNSUPPORTED,         // §3.4
+  'geoly.symlink-state-path': EXIT.UNSUPPORTED,     // §3.4
+  'geoly.not-plain': EXIT.UNSUPPORTED,              // §3.4
+  // 🔴 「扫不完就不能宣称没有」——它是 fail-closed 的拒绝，不是「不支持」，
+  //    但 §6 里没有第二个能装它的格子。归 9 并在文案里说清是扫描超预算。
+  'target.nested-scan-incomplete': EXIT.UNSUPPORTED,
+  'geoly.state-scan-incomplete': EXIT.UNSUPPORTED,
+  'target.not-writable': EXIT.NOT_WRITABLE,         // §3.6 → §6 第 10 条点名
+  // 🔴 可信 base 缺失是**我们自己**没把 adapter 的 base 传进去 —— 用户改不了它。
+  //    报 9（「不支持」）会把用户送去查文件系统。归 1（用法/内部）并点名。
+  'target.base-missing': EXIT.USAGE,
+  'target.outside-base': EXIT.USAGE,
+});
+
+/**
+ * 🔴 一次预检会报**全部**违规项，可能同时命中不同档。取哪一个？
+ *
+ * 取**最根本的死路**，不是「第一条」也不是「码最大的那条」：
+ * `.geoly` 在 NFS 上（9）与「目录不可写」（10）同时命中时，报 10 会让用户去 `chmod`，
+ * 而 chmod 完照样装不上 —— fstype 是他改不掉的那一条。
+ *
+ * 顺序即优先级；表里没有的码排在最后。
+ */
+const VIOLATION_PRIORITY = Object.freeze([
+  'fs.unsupported-fstype',
+  'fs.cross-device',
+  'geoly.is-mount-point',
+  'geoly.mount-point-under',
+  'target.nested',
+  'target.symlink-in-chain',
+  'geoly.symlink-state-path',
+  'target.not-plain-dir',
+  'geoly.not-plain',
+  'target.nested-scan-incomplete',
+  'geoly.state-scan-incomplete',
+  'target.base-missing',
+  'target.outside-base',
+  'target.not-writable',
+]);
+
+/** 一组预检违规 → 一个退出码。空数组返回 `null`（调用方自己决定）。 */
+export function exitForViolations(violations) {
+  if (!Array.isArray(violations) || violations.length === 0) return null;
+  const codes = new Set(violations.map((v) => v?.code));
+  for (const c of VIOLATION_PRIORITY) if (codes.has(c)) return VIOLATION_EXIT[c];
+  // 认不出来的违规码：fail-closed 到 9，并让 classify 的调用方看得见 unclassified
+  return EXIT.UNSUPPORTED;
+}
+
+export { VIOLATION_EXIT, VIOLATION_PRIORITY };
+
+// ── 分类 ────────────────────────────────────────────────────────────────────
+
+/**
+ * 内核错误的 `name` → 退出码。
+ *
+ * 🔴 `Corrupt` 落 **5**，不落 2 —— 判据不是我们的猜测，是**内核自己写死的**：
+ *    `journal.mjs` 的 `Corrupt` 构造器里就是 `this.code = 5`，
+ *    而 11-wire-contract.md §5 对 journal CRC 失败要求「停机，报告为需要人工介入」。
+ *    §6 第 2 条（完整性失败）说的是验签 / 摘要 / 资产 sha256 / 签名身份 ——
+ *    那些来自 `trust.mjs` 与 `untar.mjs`，不来自 `Corrupt`。
+ *
+ * 🔴 但 `Corrupt` 被 journal / ledger / plan / lockfile **共用**，
+ *    单凭错误类分不出来源。因此凡是「这里抛的 Corrupt 其实是另一档」的地方，
+ *    都在**调用点**显式包装成 `ConflictError` / integrity 错，
+ *    **绝不**靠对错误文案做正则。已经这么做的两处：
+ *      · `commands/install.mjs`：未认领同名目录 → `ConflictError`（3）；
+ *      · lockfile 的结构 / 闭包校验 → 由调用点包成完整性失败（2）。
+ */
+const BY_NAME = Object.freeze({
+  // trust.mjs
+  // 🔴 `WireError` 落 **1**，不落 2 —— 内核构造器里写死的就是 `this.code = 1`
+  //    并注明「解析失败」，而 §6 第 1 条正是「用法错误 / **解析失败** / 候选歧义」。
+  //    §6 第 2 条列举的是验签失败 / 摘要不符 / 算法不认识 / 资产 sha256 不符 /
+  //    签名身份不对 —— 那些是 `IntegrityError` 与 `TarViolation`。
+  WireError: EXIT.USAGE,
+  IntegrityError: EXIT.INTEGRITY,
+  StaleError: EXIT.STALE,
+  MinCliVersionError: EXIT.MIN_CLI,
+  // untar.mjs / artifact.mjs
+  TarViolation: EXIT.INTEGRITY,
+  // journal.mjs（ledger / plan / lockfile / install / recover 共用）
+  Corrupt: EXIT.NEEDS_RECOVER,
+  // lock.mjs
+  LockBusyError: EXIT.NEEDS_RECOVER,
+  // recover.mjs
+  NeedsRecover: EXIT.NEEDS_RECOVER,
+});
+
+/**
+ * 把任意异常映射成退出码。
+ *
+ * @param {unknown} err
+ * @param {object} [o]
+ * @param {number} [o.preferCode]
+ *        调用方已经知道这个错该落哪一档时给它（例如 recover 的分流拒绝 → 5）。
+ *        🔴 只在**认得出**这个错的前提下用；它压不过 `err.exitCode`。
+ * @returns {{code:number, unclassified:boolean, reason:string}}
+ *        `reason` 是给埋点用的 `REASONS` 代码，`null` 表示没有合适的代码。
+ */
+export function classify(err, o = {}) {
+  // ① 我们自己抛的：码写在对象上，最权威
+  if (err && Number.isInteger(err.exitCode)) {
+    return { code: err.exitCode, unclassified: false, reason: reasonFor(err, err.exitCode) };
+  }
+  // ② 预检聚合错：带 violations 数组
+  if (err && Array.isArray(err.violations) && err.violations.length) {
+    const code = exitForViolations(err.violations);
+    return { code, unclassified: false, reason: reasonFor(err, code) };
+  }
+  // ③ 内核错误按 name
+  const named = err && BY_NAME[err.name];
+  if (named !== undefined) {
+    const code = o.preferCode !== undefined && named === EXIT.INTEGRITY ? o.preferCode : named;
+    return { code, unclassified: false, reason: reasonFor(err, code) };
+  }
+  // ④ lock.mjs 的 LockBusyError 万一被跨实例包装过：它带 code === 5 与 holder
+  if (err && err.code === 5 && Object.hasOwn(err, 'holder')) {
+    return { code: EXIT.NEEDS_RECOVER, unclassified: false, reason: 'lock-busy' };
+  }
+  // ⑤ 认不出来 —— 绝不给 0
+  return { code: UNCLASSIFIED, unclassified: true, reason: 'unknown' };
+}
+
+/**
+ * 埋点的 `reason`：🔴 必须来自 `telemetry.REASONS` 那张**有限代码表**。
+ * 这里只挑得出代码，挑不出就返回 `'unknown'`（它也在表里）——
+ * **绝不**把错误文案塞进 reason（那正是 REASONS 存在的理由）。
+ */
+function reasonFor(err, code) {
+  const name = err?.name;
+  if (name === 'LockBusyError') return 'lock-busy';
+  if (name === 'StaleError') return 'unknown';          // REASONS 里没有 stale 这一条
+  if (name === 'MinCliVersionError') return 'unknown';  // 同上
+  if (name === 'NeedsRecover') return 'journal-corrupt';
+  if (name === 'TarViolation') return 'digest-mismatch';
+  if (err?.telemetryReason) return err.telemetryReason;  // 调用方点名的代码（自己保证在表里）
+  switch (code) {
+    case EXIT.INTEGRITY: return 'digest-mismatch';
+    case EXIT.NETWORK: return 'network-error';
+    case EXIT.AUTH: return 'unknown';
+    case EXIT.NOT_WRITABLE: return 'target-not-writable';
+    case EXIT.UNSUPPORTED: return 'unsupported-client';
+    case EXIT.CONFLICT: return 'version-conflict';
+    case EXIT.USAGE: return 'unknown';
+    default: return 'unknown';
+  }
+}

package/src/fault-inject.mjs

@@ -0,0 +1,379 @@
+// 故障注入内核 —— M0 §6 P0 第 3 项。
+//
+// 规格依据：docs/m0/00-decisions.md §6、04-install.md §5.2/5.2.1/5.3/5.4/5.6/5.8/5.10、
+//           11-wire-contract.md §5。
+//
+// 设计三条：
+//   1. **注入点有名字，不按序号。** 「第 N 次 write」在代码改动后会静默错位，
+//      指到完全不同的操作上，测试照样绿。名字改了则 CATALOG 交叉核对会失败（可发现）。
+//   2. **框架能枚举注入点。** 无故障跑一趟拿到 trace，再对 trace 里的每一项各崩一次；
+//      测试不是手写几十个 case，而是「对这个事务的每一个注入点各跑一遍」。
+//   3. **未武装时零开销。** ACTIVE 为 false 时 fp() 第一行就 return。
+//
+// 🔴 各模式**能证明什么、不能证明什么**，见本文件末尾的 MODES 表与 README 段。
+//    特别是：**SIGKILL 不证明持久性**。
+
+import {
+  appendFileSync, cpSync, existsSync, mkdirSync, renameSync, rmSync, statSync, unlinkSync,
+  writeFileSync,
+} from 'node:fs';
+import { dirname } from 'node:path';
+
+// ── 模式 ─────────────────────────────────────────────────────────────────────
+
+/**
+ * 每种崩溃模式**证明什么 / 不证明什么**。测试报告直接引用这张表，
+ * 免得「跑了 200 个注入点」被当成「持久性已证明」。
+ */
+export const MODES = {
+  throw: {
+    proves: '调用栈在这一点中断，后续步骤没跑；catch/finally 路径不会把状态改坏。',
+    disproves_not:
+      '不证明进程真死时的行为 —— finally、进程退出钩子、SQLite 的 close 都仍会跑。',
+  },
+  exit: {
+    proves: 'process.exit()：finally 与 catch 都不跑，只有 exit 钩子跑。',
+    disproves_not: '不证明信号/内核级中止；exit 钩子仍有机会写盘。',
+  },
+  kill: {
+    proves:
+      'SIGKILL：进程内**任何**收尾代码都不可能跑（无 finally、无 atexit、无信号处理器）。' +
+      '证明的是「时序」—— 恢复逻辑必须能从「第 k 步之后、第 k+1 步之前」接上。',
+    disproves_not:
+      '🔴 **不证明持久性。** POSIX 下 write() 的数据在内核页缓存里，进程被杀不会丢；' +
+      '只有掉电/内核崩溃才会丢。因此「SIGKILL 后恢复正常」**不能**推出「fsync 用对了」。' +
+      '想证明 fsync 用对了，用 powerfail 模式（近似）或块设备层工具（dm-log-writes，非本框架范围）。',
+  },
+  errno: {
+    proves:
+      '以 EIO/ENOSPC 失败并把控制权交回调用方 —— 证明 §5.4「I/O 失败统一规则」的 ' +
+      'fail-closed：不推进 journal、不当成功、不吞错。\n' +
+      '🔴 **两种失败语义靠注入点位置区分，不靠模式**：\n' +
+      '  · 打在 `…:pre-X` 上  = 「syscall 失败且没有副作用」；\n' +
+      '  · 打在 `…:post-X` 上 = 「syscall 已生效但随后报错」—— 这正是 §11 §5 说的\n' +
+      '    「rename 已经生效、而随后的父目录 fsync 报错时，目标文件**可能已经存在**」，\n' +
+      '    规范据此禁止任何「写失败 → 磁盘未变」的说法。',
+    disproves_not: '不证明真实设备上的错误传播（EIO 之后 fd 状态、page 是否已回写）。',
+  },
+  powerfail: {
+    proves:
+      '掉电近似：把「已发生但其所在目录/文件尚未 fsync」的效果**撤销**，再 SIGKILL。' +
+      '这是唯一能打到 §5.2.1「两棵都丢」那个反例的模式 —— ' +
+      '只 fsync 叶子时，上层目录项没落盘，断电后新建的 tx 根连同两棵树一起消失。',
+    disproves_not:
+      '🔴 这是 **API 边界上的仿真**，不是块设备层的。不建模：写入乱序、页内撕裂（部分写）、' +
+      '文件系统自身的日志语义、以及**任何绕过 atomic-fs 的裸 fs 调用**（那些效果对它不可见）。',
+  },
+};
+
+export class FaultInjected extends Error {
+  constructor(name, nth, mode) {
+    super(`fault-inject: ${name} #${nth} (mode=${mode})`);
+    this.name = 'FaultInjected';
+    this.faultPoint = name;
+    this.nth = nth;
+    this.mode = mode;
+  }
+}
+
+// ── 状态 ─────────────────────────────────────────────────────────────────────
+
+let ACTIVE = false; // ARMED || TRACING —— fp() 的快速守卫
+let ARMED = false;
+let LOCKED = false; // lockdown() 之后永久不可武装（生产入口调用）
+let TARGET = null;
+let NTH = 1;
+let MODE = 'throw';
+let ERRNO = 'EIO';
+let TRACE_PATH = null;
+const counts = new Map();
+const hits = []; // 本进程命中过的 (name, nth)，供进程内测试断言
+
+function recompute() {
+  ACTIVE = ARMED || TRACE_PATH !== null;
+}
+
+// ── 注入点探针 ───────────────────────────────────────────────────────────────
+
+/**
+ * 具名注入点。埋在**每一个写操作的前后**，名字形如 `atomic-write:pre-rename`。
+ * @param {string} name  必须出现在 test/harness/fault-points.mjs 的 CATALOG 里
+ *                       （test/fault-matrix.test.mjs 做三向交叉核对）
+ * @param {object} [ctx] 诊断上下文，只进 trace，不参与判定
+ */
+export function fp(name, ctx) {
+  if (!ACTIVE) return;
+  const n = (counts.get(name) ?? 0) + 1;
+  counts.set(name, n);
+  // 🔴 trace 本身绝不能改变被测操作的语义：写 trace 失败、ctx 不可序列化，
+  //    都只能被吞掉，不能变成被测代码看到的异常。
+  if (TRACE_PATH !== null) {
+    let extra = '';
+    try { extra = ctx ? JSON.stringify(ctx) : ''; } catch { extra = '<unserializable>'; }
+    try { appendFileSync(TRACE_PATH, `${name}\t${n}\t${extra}\n`); } catch { /* 见上 */ }
+  }
+  if (!ARMED || name !== TARGET || n !== NTH) return;
+  hits.push({ name, nth: n });
+  return detonate(name, n, ctx);
+}
+
+function detonate(name, nth, ctx) {
+  switch (MODE) {
+    case 'throw':
+      throw new FaultInjected(name, nth, MODE);
+    case 'errno': {
+      const e = new FaultInjected(name, nth, MODE);
+      e.code = ERRNO;
+      e.errno = -5;
+      e.syscall = ctx?.syscall ?? 'write';
+      throw e;
+    }
+    case 'exit':
+      // 97 = 「这是注入的崩溃」，与任何真实退出码区分开
+      process.exit(97);
+      break;
+    case 'powerfail':
+      applyPowerFailure();
+      process.kill(process.pid, 'SIGKILL');
+      break;
+    case 'kill':
+      process.kill(process.pid, 'SIGKILL');
+      break;
+    default:
+      throw new Error(`fault-inject: 未知模式 ${MODE}`);
+  }
+  // SIGKILL 在返回用户态时投递，实践上是同步的；但不挡一下的话，
+  // 万一没落地，被注入的那一步会**继续执行**，注入点就错位了。
+  // 有界忙等（2s）之后退而求其次用 exit，避免测试套件真的悬挂。
+  if (MODE === 'kill' || MODE === 'powerfail') {
+    const until = Date.now() + 2000;
+    while (Date.now() < until) {
+      /* 等信号落地 */
+    }
+    process.exit(97);
+  }
+}
+
+// ── 武装 / 解除 ──────────────────────────────────────────────────────────────
+
+export function arm({ name, nth = 1, mode = 'throw', errno = 'EIO' } = {}) {
+  if (LOCKED) throw new Error('fault-inject: 已 lockdown，不可武装');
+  if (!name) throw new Error('fault-inject: arm 需要 name');
+  if (!(mode in MODES)) throw new Error(`fault-inject: 未知模式 ${mode}`);
+  ARMED = true;
+  TARGET = name;
+  NTH = Number(nth);
+  MODE = mode;
+  ERRNO = errno;
+  recompute();
+}
+
+export function disarm() {
+  ARMED = false;
+  TARGET = null;
+  recompute();
+}
+
+/** 生产入口（bin/）应调用它：此后 env 与 arm() 都无法再打开注入。 */
+export function lockdown() {
+  LOCKED = true;
+  ARMED = false;
+  TARGET = null;
+  TRACE_PATH = null;
+  pending.length = 0;
+  recompute();
+}
+
+export function setTrace(path) {
+  if (LOCKED) throw new Error('fault-inject: 已 lockdown');
+  TRACE_PATH = path;
+  recompute();
+}
+
+export function reset() {
+  counts.clear();
+  hits.length = 0;
+  pending.length = 0;
+}
+
+export function observed() {
+  return hits.slice();
+}
+
+export function hitCount(name) {
+  return counts.get(name) ?? 0;
+}
+
+export function state() {
+  return { ACTIVE, ARMED, LOCKED, TARGET, NTH, MODE, TRACE_PATH };
+}
+
+/** 生产热路径用它跳过只为掉电模型服务的额外 I/O */
+export function shadowActive() {
+  return ACTIVE;
+}
+
+/**
+ * 从环境读配置。🔴 **必须由调用方显式调用** —— 本模块**不在 import 时自动调用**。
+ *    子进程崩溃测试在 test/harness/child.mjs 里显式调它。
+ *
+ * 🔴 **双钥匙**：还必须有 `GEOLY_FAULT_ENABLE=1`。
+ *    单一变量太容易被误设/继承，而它能让生产 CLI 在真实 target 上崩溃。
+ *
+ *   GEOLY_FAULT_ENABLE 必须是 "1"，否则以下全部忽略
+ *   GEOLY_FAULT        注入点名
+ *   GEOLY_FAULT_NTH    第几次命中（默认 1）
+ *   GEOLY_FAULT_MODE   throw|exit|kill|errno|powerfail（默认 throw）
+ *   GEOLY_FAULT_ERRNO  errno 模式用的 code（默认 EIO）
+ *   GEOLY_FAULT_TRACE  trace 落点文件
+ * 🔴 名字里有冒号，所以**不做 `name:mode` 拼接**，各占一个变量。
+ */
+export function armFromEnv(env = process.env) {
+  if (LOCKED) return;
+  if (env.GEOLY_FAULT_ENABLE !== '1') return;
+  if (env.GEOLY_FAULT_TRACE) setTrace(env.GEOLY_FAULT_TRACE);
+  if (env.GEOLY_FAULT) {
+    arm({
+      name: env.GEOLY_FAULT,
+      nth: env.GEOLY_FAULT_NTH ? Number(env.GEOLY_FAULT_NTH) : 1,
+      mode: env.GEOLY_FAULT_MODE ?? 'throw',
+      errno: env.GEOLY_FAULT_ERRNO ?? 'EIO',
+    });
+  }
+}
+
+// ── 持久性影子（powerfail 模式）─────────────────────────────────────────────
+//
+// atomic-fs 每做一次「尚未持久」的改动就登记一条 undo；对应的 fsync 一旦成功
+// 就把它划掉。powerfail = 逆序执行还没划掉的 undo，然后 SIGKILL。
+//
+// 🔴 只覆盖走 atomic-fs 的改动。裸 fs 调用对它不可见 —— 这是仿真的边界，不是 bug。
+
+// 每条 pending：{ dirs: Set<string>, files: Set<string>, tag, undo() }
+// 「dirs 与 files 都被 fsync 过」才算持久，才从表里划掉。
+const pending = [];
+
+let POWERFAIL_STYLE = process.env.GEOLY_FAULT_POWERFAIL_STYLE ?? 'drop';
+
+export function setPowerfailStyle(s) {
+  POWERFAIL_STYLE = s;
+}
+
+/** 登记「`path` 这个目录项刚出现，但 `dirname(path)` 还没 fsync」 */
+export function pendingCreate(path) {
+  if (!ACTIVE) return;
+  pending.push({
+    dirs: new Set([dirname(path)]),
+    files: new Set(),
+    tag: `create ${path}`,
+    undo: () => rmSync(path, { recursive: true, force: true }),
+  });
+}
+
+/**
+ * 登记「`from` → `to` 的 rename 刚发生」。
+ * 🔴 rename 动两个目录项：源目录里少一个、目标目录里多一个。
+ *    **两侧父目录都 fsync 过**才算持久。
+ * 掉电后的两种合法结果，本模型二选一（GEOLY_FAULT_POWERFAIL_STYLE）：
+ *   · `drop`      —— 当作 rename 没发生（把 `to` 搬回 `from`）；
+ *   · `duplicate` —— 目标侧目录项落盘、源侧删除未落盘 ⇒ **两边都在**。
+ *                    这正是 §5.4 幂等表里判 corrupt 的分支 ②，值得单独打。
+ */
+export function pendingRename(from, to, overwrittenBytes) {
+  if (!ACTIVE) return;
+  pending.push({
+    dirs: new Set([dirname(to), dirname(from)]),
+    files: new Set(),
+    tag: `rename ${from} -> ${to}`,
+    undo: () => {
+      if (!existsSync(to) || existsSync(from)) return;
+      if (POWERFAIL_STYLE === 'duplicate') { cpSync(to, from, { recursive: true }); return; }
+      renameSync(to, from);
+      // 🔴 rename **覆盖**了一个已存在的目标时，「这次 rename 没发生」意味着
+      //    旧目标还在。不把它写回去，撤销结果就不是一个合法的掉电分支。
+      if (overwrittenBytes !== undefined) writeFileSync(to, overwrittenBytes);
+    },
+  });
+}
+
+/**
+ * 登记「`path` 刚被删，父目录还没 fsync」。
+ * 🔴 undo 会把它**放回去** —— 删除未落盘时掉电，目录项还在。
+ *    这一条是 §5.6 阶段 C「删到一半」那个窗口的唯一建模途径；
+ *    以前写成空函数时，powerfail 在这一格是**假绿**（Codex 第二轮 #10）。
+ * @param {Buffer|null} preimage 文件内容前像；目录传 null
+ * @param {number} mode
+ * @param {boolean} [isDir]
+ */
+export function pendingUnlink(path, preimage = null, mode = 0o644, isDir = false) {
+  if (!ACTIVE) return;
+  pending.push({
+    dirs: new Set([dirname(path)]),
+    files: new Set(),
+    tag: `unlink ${path}`,
+    undo: () => {
+      if (existsSync(path)) return;
+      if (isDir) { mkdirSync(path, mode); return; }
+      if (preimage !== null) writeFileSync(path, preimage, { mode });
+    },
+  });
+}
+
+/** 登记「`path` 的数据已 write，但文件自身与父目录都还没 fsync」 */
+export function pendingData(path) {
+  if (!ACTIVE) return;
+  pending.push({
+    dirs: new Set([dirname(path)]),
+    files: new Set([path]),
+    tag: `data ${path}`,
+    undo: () => {
+      try {
+        if (existsSync(path) && statSync(path).isFile()) unlinkSync(path);
+      } catch {
+        /* 掉电模型下这一步失败无所谓 */
+      }
+    },
+  });
+}
+
+function sweep() {
+  for (let i = pending.length - 1; i >= 0; i--) {
+    if (pending[i].dirs.size === 0 && pending[i].files.size === 0) pending.splice(i, 1);
+  }
+}
+
+/** 某个目录 fsync 成功 */
+export function durableDir(dir) {
+  if (!ACTIVE) return;
+  for (const p of pending) p.dirs.delete(dir);
+  sweep();
+}
+
+/** 某个文件 fsync 成功（它的目录项可能仍未持久 —— 那部分靠 durableDir 划） */
+export function durableFile(file) {
+  if (!ACTIVE) return;
+  for (const p of pending) p.files.delete(file);
+  sweep();
+}
+
+export function pendingEffects() {
+  return pending.map((p) => p.tag);
+}
+
+/** 逆序撤销全部未持久效果 */
+export function applyPowerFailure() {
+  for (let i = pending.length - 1; i >= 0; i--) {
+    try {
+      pending[i].undo();
+    } catch {
+      /* 掉电不会报错 */
+    }
+  }
+  pending.length = 0;
+}
+
+// 🔴 **刻意不在 import 时自动调用 armFromEnv()**（Codex 第二轮 P0-1）。
+//    生产入口 bin/skills-hub.mjs 在 import 之后才有机会 lockdown()，ESM 下已经太晚 ——
+//    只要模块一加载就读 env，用户环境里的 GEOLY_FAULT_ENABLE=1 就能让生产 CLI
+//    在真实 target 上 SIGKILL，GEOLY_FAULT_TRACE 还能让它往任意路径追加内容。
+//    改为**必须显式初始化**：测试 harness（test/harness/child.mjs）自己调 armFromEnv()。