@geoly-ai/skills-hub 0.1.0

package/src/artifact.mjs

@@ -0,0 +1,376 @@
+// 制品链：资产验证 → 隔离解包 → 重算树摘要 → manifest 绑定
+// 规范：02-registry.md §6 第 7 步、01-artifacts.md §4/§5/§5.3/§6、04-install.md §7
+import { createHash } from 'node:crypto';
+import {
+  mkdtempSync, mkdirSync, openSync, writeSync, fsyncSync, closeSync, futimesSync,
+  utimesSync, chmodSync, fchmodSync, fstatSync, lstatSync, readFileSync, existsSync, statSync, rmSync, constants,
+} from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { fsyncDir } from './atomic-fs.mjs';
+import { treeDigest } from './tree-digest.mjs';
+import { untarGz, assertArtifactPath, TarViolation } from './untar.mjs';
+import {
+  IntegrityError, WireError,
+  parseWireJson, assertExactKeys, assertString, assertStringArray, assertUint, assertTreeDigest,
+} from './trust.mjs';
+
+export const SKILL_MANIFEST_SCHEMA = 'geoly.skills.skill/1';
+export const PACK_MANIFEST_SCHEMA = 'geoly.skills.pack/1';
+
+const viol = (v, m) => { throw new IntegrityError(v, m); };
+
+// ── 资产 ────────────────────────────────────────────────────────────────────
+
+/**
+ * §6 第 7 步的第一件事：验 `asset.sha256`（顺带验 `asset.size`）。
+ * 🔴 没有期望值就直接抛 —— API 上不存在「不给期望值就跳过」的口子。
+ */
+export function assertAssetBytes(bytes, record) {
+  const buf = Buffer.isBuffer(bytes) ? bytes : Buffer.from(bytes);
+  const expected = record?.asset?.sha256;
+  if (typeof expected !== 'string') viol('E_NO_EXPECTED_DIGEST', 'record.asset.sha256 缺失，拒绝校验资产');
+  const got = 'sha256:' + createHash('sha256').update(buf).digest('hex');
+  if (got !== expected) viol('E_ASSET_SHA256', `资产 sha256 是 ${got}，快照说应为 ${expected}`);
+  // 🔴 `asset.size` **必填**，不是「有就查」。
+  //    snapshot parser 本来就要求它存在，所以这里写成可选只在**直接调本 API** 时有区别 ——
+  //    也就是说，它唯一的作用是给绕过尺寸一致性校验留一个口子。
+  //    同 E_NO_EXPECTED_DIGEST 的立场：API 上不存在「不给期望值就跳过」。
+  if (typeof record.asset.size !== 'number') {
+    viol('E_NO_EXPECTED_SIZE', 'record.asset.size 缺失，拒绝校验资产');
+  }
+  if (buf.length !== record.asset.size) {
+    viol('E_ASSET_SIZE', `资产 ${buf.length} 字节，快照说应为 ${record.asset.size}`);
+  }
+  return got;
+}
+
+// ── 隔离临时目录 ────────────────────────────────────────────────────────────
+
+/**
+ * 🔴 解到**隔离临时目录**（不是 target，不是 stage）——04-install.md §7 第 2 步。
+ * `mkdtemp` 生成的目录名不可预测且 mode 0700：别人预先占位、或在解包途中
+ * 往里塞 symlink，都需要先能写进这个目录。
+ */
+export function createIsolatedDir(parent = tmpdir()) {
+  const d = mkdtempSync(join(parent, 'geoly-unpack-'));
+  chmodSync(d, 0o700);
+  return d;
+}
+
+/**
+ * 把内存里的条目写进隔离目录。
+ *
+ * 🔴 每个中间目录都由**本函数自己**创建（`mkdir` 不带 recursive，`EEXIST` 即违规），
+ * 每个文件用 `O_CREAT|O_EXCL|O_NOFOLLOW` 打开。
+ * 为什么不用「先 lstat 再写」：那是 TOCTOU —— 检查与写之间有窗口。
+ * 让内核在 `open` 这一次系统调用里同时完成「必须不存在」与「不许跟随符号链接」。
+ */
+export function writeEntries(destDir, entries) {
+  const madeDirs = [];
+  const known = new Set([destDir]);
+
+  const ensureDir = (abs) => {
+    if (known.has(abs)) return;
+    try {
+      mkdirSync(abs, 0o755);
+    } catch (e) {
+      // 🔴 EEXIST 在这里就是异常：目录是我们刚建的、由我们独占，
+      //    里面不该有别人先放好的东西
+      viol('E_DEST_DIRTY', `隔离目录里已存在 ${abs}（${e.code}）：拒绝写入`);
+    }
+    // 建完立刻 lstat 确认它确实是目录而不是被换成了符号链接。
+    // ⚠️ 这**收窄**竞态窗口，不消除它：Node 没有 openat/mkdirat，
+    //    中间目录的 check-then-use 无法在纯 Node 里做成原子的。残余风险见交付汇报。
+    const st = lstatSync(abs);
+    if (!st.isDirectory() || st.isSymbolicLink()) viol('E_DEST_DIRTY', `${abs} 建出来之后不是普通目录`);
+    chmodSync(abs, 0o755); // 绕开 umask，把 mode 钉死（§6.2：目录 mode 一律 0755）
+    known.add(abs);
+    madeDirs.push(abs);
+  };
+
+  const O_NOFOLLOW = constants.O_NOFOLLOW ?? 0;
+  for (const e of entries) {
+    const segs = e.path.split('/');
+    for (let i = 1; i < segs.length; i++) ensureDir(join(destDir, ...segs.slice(0, i)));
+    const abs = join(destDir, ...segs);
+    let fd;
+    try {
+      fd = openSync(abs, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | O_NOFOLLOW, e.mode);
+    } catch (err) {
+      viol('E_DEST_DIRTY', `无法以 O_EXCL|O_NOFOLLOW 创建 ${e.path}（${err.code}）`);
+    }
+    try {
+      writeSync(fd, e.data, 0, e.data.length, 0);
+      // 🔴 mode 用 fchmod 而不是 chmod：`open` 受 umask 影响（umask 077 会把
+      //    0644 变成 0600），必须钉死；而按**路径**再 chmod 一次等于重新解析路径，
+      //    那正是 Codex 指出的 TOCTOU 窗口。用已经拿到的 fd 就没有这次重解析。
+      fchmodSync(fd, e.mode);
+      fsyncSync(fd);
+      // §6.2：mtime / atime 解包时一律置 0（epoch），归档里的时间戳不参与也不保留
+      futimesSync(fd, 0, 0);
+      const st = fstatSync(fd);
+      if (!st.isFile() || st.nlink !== 1) viol('E_DEST_DIRTY', `${e.path} 写完之后不是 nlink=1 的普通文件`);
+      if ((st.mode & 0o777) !== e.mode) viol('E_DEST_DIRTY', `${e.path} 的 mode 没能钉成 0${e.mode.toString(8)}`);
+    } finally {
+      closeSync(fd);
+    }
+  }
+
+  // 目录时间与 fsync 放到最后：先设时间会被后续写子项覆盖
+  for (let i = madeDirs.length - 1; i >= 0; i--) { utimesSync(madeDirs[i], 0, 0); fsyncDir(madeDirs[i]); }
+  fsyncDir(destDir);
+  return { dirs: madeDirs.length, files: entries.length };
+}
+
+/**
+ * 🔴 `0755` 仅当 capability 声明了 `shell`（01-artifacts.md §5 载荷规则表）。
+ * mode 进树摘要正是因为它关联这条 capability —— 只校验摘要不校验这条绑定，
+ * 等于让一个没声明 shell 的制品带着可执行位装进去。
+ */
+export function assertModeCapabilityBinding(entries, record) {
+  const caps = Array.isArray(record?.capabilities) ? record.capabilities : [];
+  if (caps.includes('shell')) return;
+  const bad = entries.filter(e => e.mode === 0o755).map(e => e.path);
+  if (bad.length) {
+    viol('E_MODE_CAPABILITY',
+      `制品未声明 shell capability，却含 0755 文件：${bad.slice(0, 5).join(', ')}${bad.length > 5 ? ` 等 ${bad.length} 个` : ''}`);
+  }
+}
+
+/**
+ * §6 第 7 步全流程：
+ *   验 asset.sha256 → 隔离临时目录解包 → 重算 tree_digest → 校验归档内逻辑路径与 mode。
+ *
+ * 🔴 顺序不可调换：**解包永远发生在 sha256 验证之后**。
+ * 先解包再验摘要等于把未经验证的字节喂给解析器，解析器的任何缺陷都直接可达。
+ */
+export function verifyAndExtract({ bytes, record, parent = tmpdir() }) {
+  assertAssetBytes(bytes, record);
+
+  const { entries, totals } = untarGz(bytes);
+  if (entries.length === 0) viol('E_EMPTY_ARTIFACT', '制品没有任何文件');
+
+  // 纵深防御：不信任 untar 的路径判定，再判一遍。任一侧将来放松，另一侧还在。
+  for (const e of entries) assertArtifactPath(e.path, `payload:${e.path}`);
+  assertModeCapabilityBinding(entries, record);
+
+  const dir = createIsolatedDir(parent);
+  // 🔴 失败路径必须自己收尸。这之前只有成功路径会把 dir 交给调用方，
+  //    写盘失败或树摘要不符时目录就留在 /tmp 里没人管 —— 一个合法 gzip 配上错的
+  //    tree_digest 就能让每次调用都完整写一遍盘再抛错，反复调用会堆出一地
+  //    geoly-unpack-*。调用方拿不到 dir，也就不可能替我们删。
+  let ok = false;
+  try {
+    writeEntries(dir, entries);
+
+    // 解完重算树摘要（§7 第 4 步）
+    const got = treeDigest(dir);
+    if (got !== record.tree_digest) {
+      viol('E_TREE_DIGEST', `解包后重算 ${got}，快照说应为 ${record.tree_digest}`);
+    }
+    ok = true;
+    return { dir, entries, totals, treeDigest: got };
+  } finally {
+    // 只删我们自己用 mkdtemp 建的那一个；成功时所有权移交调用方，不能删
+    if (!ok) { try { rmSync(dir, { recursive: true, force: true }); } catch { /* 清理尽力而为 */ } }
+  }
+}
+
+// ── manifest 绑定（01-artifacts.md §5.3） ──────────────────────────────────
+
+const SKILL_MANIFEST_KEYS = {
+  required: ['schema', 'kind', 'namespace', 'name', 'version', 'description', 'license',
+    'clients', 'capabilities', 'replaces', 'conflicts', 'provenance'],
+};
+
+const PACK_MANIFEST_KEYS = {
+  required: ['schema', 'kind', 'namespace', 'name', 'version', 'description', 'license',
+    'members', 'bundled', 'conflicts', 'contract_paths', 'compatibility'],
+};
+
+/** 最小 YAML frontmatter 子集：`---` 包围、单行 `key: value`。其余一律拒绝。 */
+export function parseFrontmatter(text) {
+  if (!text.startsWith('---\n')) throw new WireError('E_FRONTMATTER', 'SKILL.md 必须以 --- 开头的 YAML frontmatter 起始');
+  const end = text.indexOf('\n---\n', 3);
+  if (end === -1) throw new WireError('E_FRONTMATTER', 'SKILL.md 的 frontmatter 没有闭合的 ---');
+  const body = text.slice(4, end + 1);
+  const out = {};
+  for (const raw of body.split('\n')) {
+    if (raw.trim() === '') continue;
+    if (raw.includes('\t')) throw new WireError('E_FRONTMATTER', 'frontmatter 含 TAB');
+    if (raw === '---' || raw.startsWith('---')) throw new WireError('E_FRONTMATTER', 'frontmatter 里出现多文档分隔符');
+    const m = /^([A-Za-z0-9_-]+): (.*)$/.exec(raw);
+    if (!m) throw new WireError('E_FRONTMATTER', `frontmatter 只支持单行 key: value，无法解析：${JSON.stringify(raw)}`);
+    let v = m[2];
+    // 拒绝 YAML 锚点 / 别名 / 合并键 —— 它们能让同一份文本解出不同结构
+    if (/^[&*]/.test(v) || m[1] === '<<') throw new WireError('E_FRONTMATTER', 'frontmatter 禁止 YAML 锚点/别名');
+    if ((v.startsWith('"') && v.endsWith('"') && v.length >= 2) || (v.startsWith("'") && v.endsWith("'") && v.length >= 2)) {
+      v = v.slice(1, -1);
+    }
+    if (Object.hasOwn(out, m[1])) throw new WireError('E_FRONTMATTER', `frontmatter 重复 key ${m[1]}`);
+    out[m[1]] = v;
+  }
+  return out;
+}
+
+function readPayloadJson(payloadDir, file) {
+  const p = join(payloadDir, file);
+  if (!existsSync(p) || !statSync(p).isFile()) {
+    viol('E_MANIFEST_MISSING', `载荷根缺少 ${file}（01-artifacts.md §5.1/§5.2）`);
+  }
+  return { bytes: readFileSync(p), path: p };
+}
+
+/**
+ * 🔴 §5.3：manifest ↔ ArtifactId 的**六项全等**（skill 再加第七项）。
+ * v1 只强制了「三处 name 一致」，能发布出「路径 x@1.0.0、载荷声明 x@2.0.0」的制品。
+ *
+ * 这一步必须在**第 7 步**做 —— manifest 在资产内部，第 5 步（解析快照）时
+ * 根本还没下载到（v3 在第 5 步要求校验它，顺序上不可能）。
+ */
+export function assertManifestBinding(record, payloadDir) {
+  const isSkill = record.kind === 'skill';
+  const file = isSkill ? 'skill.json' : 'pack.json';
+  const { bytes } = readPayloadJson(payloadDir, file);
+  const doc = parseWireJson(bytes, file);
+
+  // 🔴 「skill.json 里没有 digest 字段，永远不会有。摘要只存在于 registry snapshot，
+  //    投稿者声明的一律不读。」——给它一个专门的违规码，别混在「未知字段」里。
+  if (Object.hasOwn(doc, 'digest')) {
+    viol('E_MANIFEST_DIGEST', `${file} 出现 digest 字段：投稿者声明的摘要一律不读（01-artifacts.md §5.1）`);
+  }
+
+  if (!isSkill) {
+    // pack.json（03-packs.md §2）。这里只做**绑定所需**的严格校验：
+    // schema、必填键集、成员锁定必须是精确版本+摘要。
+    // ⚠️ 成员图的解析、degraded 判定、conflicts 匹配等属于 packs 模块的职责，不在本模块。
+    assertExactKeys(doc, PACK_MANIFEST_KEYS, file);
+    if (doc.schema !== PACK_MANIFEST_SCHEMA) {
+      throw new WireError('E_SCHEMA', `${file}.schema 必须是 ${PACK_MANIFEST_SCHEMA}，得到 ${JSON.stringify(doc.schema)}`);
+    }
+    assertString(doc.description, `${file}.description`);
+    assertString(doc.license, `${file}.license`);
+    assertStringArray(doc.conflicts, `${file}.conflicts`);
+    assertStringArray(doc.contract_paths, `${file}.contract_paths`);
+    for (const listName of ['members', 'bundled']) {
+      const list = doc[listName];
+      if (!Array.isArray(list)) throw new WireError('E_WIRE_TYPE', `${file}.${listName} 必须是数组`);
+      list.forEach((m, i) => {
+        const w = `${file}.${listName}[${i}]`;
+        assertExactKeys(m, { required: ['id', 'tree_digest', 'role'], optional: ['order'] }, w);
+        // 🔴 成员锁定：精确版本 + 摘要，不接受 semver range
+        //    （range 意味着「装的时候才知道装到什么」）
+        if (!/^(skill|pack):[a-z0-9-]+\/[a-z0-9-]+@[^*^~ ]+$/.test(assertString(m.id, `${w}.id`))) {
+          throw new WireError('E_PACK_MEMBER_ID', `${w}.id 必须是精确的 ArtifactId，不接受 range：${m.id}`);
+        }
+        assertTreeDigest(m.tree_digest, `${w}.tree_digest`);
+        assertString(m.role, `${w}.role`);
+        if (Object.hasOwn(m, 'order')) assertUint(m.order, `${w}.order`);
+      });
+    }
+  }
+
+  if (isSkill) {
+    assertExactKeys(doc, SKILL_MANIFEST_KEYS, file);
+    if (doc.schema !== SKILL_MANIFEST_SCHEMA) {
+      throw new WireError('E_SCHEMA', `${file}.schema 必须是 ${SKILL_MANIFEST_SCHEMA}，得到 ${JSON.stringify(doc.schema)}`);
+    }
+    assertString(doc.description, `${file}.description`);
+    assertString(doc.license, `${file}.license`);
+    assertStringArray(doc.clients, `${file}.clients`);
+    assertStringArray(doc.capabilities, `${file}.capabilities`);
+    assertStringArray(doc.replaces, `${file}.replaces`);
+    assertStringArray(doc.conflicts, `${file}.conflicts`);
+  }
+
+  // ①—⑤：仓库路径、kind、namespace、name、version
+  const wantPath = `artifacts/${record.kind}s/${record.namespace}/${record.name}/${record.version}`;
+  const checks = [
+    ['① 仓库路径', record.path, wantPath],
+    ['② kind', doc.kind, record.kind],
+    ['③ namespace', doc.namespace, record.namespace],
+    ['④ name', doc.name, record.name],
+    ['⑤ version', doc.version, record.version],
+    // ⑥ snapshot record 的 id / ns / name / version / kind
+    ['⑥ id', record.id, `${record.kind}:${record.namespace}/${record.name}@${record.version}`],
+  ];
+  for (const [label, got, want] of checks) {
+    if (got !== want) viol('E_MANIFEST_BINDING', `${label} 不一致：${JSON.stringify(got)} ≠ ${JSON.stringify(want)}`);
+  }
+
+  // ⑦ skill 的第七项：SKILL.md frontmatter 的 name
+  let frontmatter = null;
+  if (isSkill) {
+    const sp = join(payloadDir, 'SKILL.md');
+    if (!existsSync(sp) || !statSync(sp).isFile()) viol('E_MANIFEST_MISSING', '载荷根缺少 SKILL.md（§5.1）');
+    frontmatter = parseFrontmatter(readFileSync(sp, 'utf8'));
+    if (frontmatter.name !== record.name) {
+      viol('E_MANIFEST_BINDING', `⑦ SKILL.md frontmatter 的 name 是 ${JSON.stringify(frontmatter.name)}，应为 ${record.name}`);
+    }
+    if (typeof frontmatter.description !== 'string' || frontmatter.description === '') {
+      viol('E_MANIFEST_BINDING', 'SKILL.md frontmatter 缺少 description（§5.1）');
+    }
+    // 🔴 版本只放 skill.json；SKILL.md frontmatter 只承担运行时语义（§5.1 末段）
+    if (Object.hasOwn(frontmatter, 'version')) {
+      viol('E_MANIFEST_BINDING', 'SKILL.md frontmatter 不得带 version —— 版本只放 skill.json（§5.1）');
+    }
+  }
+
+  return { manifest: doc, frontmatter };
+}
+
+/**
+ * 第 7 步的组合入口：验资产 → 解包 → 树摘要 → manifest 绑定。
+ *
+ * 🔴 成功时 `dir` 的所有权移交调用方，**调用方必须调 `dispose()`**。
+ * 返回值里带 `dispose` 而不是只在文档里写一句「记得删」——
+ * 实测「靠调用方记得」是不成立的：我们自己的测试就漏了一地，
+ * 一轮全量跑之后 `$TMPDIR` 里有 3807 个 `geoly-unpack-*`。
+ *
+ * 能用 `withVerifiedArtifact()` 就用它，那个结构上不可能忘。
+ */
+export function verifyArtifact({ bytes, record, parent = tmpdir() }) {
+  const r = verifyAndExtract({ bytes, record, parent });
+  // 🔴 `dispose` 必须在**任何可能抛错的步骤之前**就能用。
+  // 早先它构造在 assertManifestBinding 之后 —— 绑定失败时 r.dir 就没人收尸了，
+  // 而调用方连 dir 都拿不到（异常里没有它），想清也清不了。
+  // 与 verifyAndExtract 里那段「失败路径必须自己收尸」是同一条，我漏了这一处。
+  let disposed = false;
+  const dispose = () => {
+    if (disposed) return;
+    disposed = true;
+    try { rmSync(r.dir, { recursive: true, force: true }); } catch { /* 尽力而为 */ }
+  };
+  let b;
+  try {
+    b = assertManifestBinding(record, r.dir);
+  } catch (err) {
+    dispose();
+    throw err;
+  }
+  return { ...r, ...b, dispose };
+}
+
+/**
+ * 作用域版：`fn` 无论正常返回还是抛错，隔离目录都会被清掉。
+ *
+ * 🔴 **这是首选入口。** 把「记得清理」从一条纪律变成一个结构性质：
+ * 调用方拿不到不清理的写法。异步 `fn` 也支持。
+ */
+export function withVerifiedArtifact({ bytes, record, parent = tmpdir() }, fn) {
+  const art = verifyArtifact({ bytes, record, parent });
+  let promise = false;
+  try {
+    const out = fn(art);
+    if (out && typeof out.then === 'function') {
+      promise = true;
+      return out.finally(() => art.dispose());
+    }
+    return out;
+  } finally {
+    if (!promise) art.dispose();
+  }
+}
+
+export { TarViolation };

package/src/atomic-fs.mjs

@@ -0,0 +1,166 @@
+// 原子写与目录链 fsync —— 规范见 11-wire-contract.md §5、04-install.md §5.2.1
+//
+// 🔴 本模块是**全部**状态写入的唯一出口。故障注入框架（src/fault-inject.mjs）
+//    在这里埋具名注入点并维护「持久性影子」，因此**绕过本模块的裸 fs 写入
+//    对崩溃测试不可见**。事务内核必须只走这里。
+import {
+  openSync, closeSync, fsyncSync, writeFileSync, renameSync, mkdirSync,
+  existsSync, statSync, lstatSync, readdirSync, unlinkSync, rmdirSync, readFileSync,
+} from 'node:fs';
+import { dirname, join } from 'node:path';
+import {
+  fp, durableDir, durableFile, pendingCreate, pendingData, pendingRename, pendingUnlink,
+  shadowActive,
+} from './fault-inject.mjs';
+
+/** fsync 一个目录（POSIX：需以只读方式打开目录 fd） */
+export function fsyncDir(dir) {
+  fp('fsync-dir:pre', { dir });
+  const fd = openSync(dir, 'r');
+  try { fsyncSync(fd); } finally { closeSync(fd); }
+  durableDir(dir);
+  fp('fsync-dir:post', { dir });
+}
+
+/**
+ * 原子写：临时文件 → fsync → rename → fsync 父目录。
+ * 🔴 §11 §5：禁止原地覆写。
+ * 🔴 失败即停机；**不得声称「磁盘未变」** —— rename 之后、父目录 fsync 报错时文件可能已存在。
+ */
+// 🔴 `.${Date.now()}-${pid}.tmp` 在同一毫秒内会撞名，`wx` 直接 EEXIST。
+//    事务的 journal 每个段都要重写一次，一毫秒里写两次是常态 —— 故障注入
+//    框架第一次跑就打出来了。加进程内单调计数器，同进程必不重复。
+let tmpSeq = 0;
+
+export function writeAtomic(path, data) {
+  const dir = dirname(path);
+  const tmp = join(dir, `.${Date.now().toString(36)}-${process.pid}-${(tmpSeq++).toString(36)}.tmp`);
+  const buf = Buffer.isBuffer(data) ? data : Buffer.from(data, 'utf8');
+  const fd = openSync(tmp, 'wx', 0o644);
+  try {
+    // 🔴 探针必须在 try 里：放在 try 之前时，throw 模式会漏掉这个 fd。
+    pendingCreate(tmp);
+    fp('atomic-write:post-open-tmp', { path });
+    fp('atomic-write:pre-write', { path, syscall: 'write' });
+    writeFileSync(fd, buf);
+    pendingData(tmp);
+    fp('atomic-write:post-write', { path });
+    fp('atomic-write:pre-fsync-file', { path, syscall: 'fsync' });
+    fsyncSync(fd);
+    durableFile(tmp);
+    fp('atomic-write:post-fsync-file', { path });
+  } finally { closeSync(fd); }
+  fp('atomic-write:pre-rename', { path, syscall: 'rename' });
+  // 掉电模型需要「这次 rename 没发生」时把被覆盖的旧目标写回去。
+  // 🔴 只在影子激活时读 —— 否则生产热路径每写一次状态文件就多读一遍旧文件。
+  const overwritten = shadowActive() && existsSync(path) ? readFileSync(path) : undefined;
+  renameSync(tmp, path);
+  pendingRename(tmp, path, overwritten);
+  fp('atomic-write:post-rename', { path });
+  fsyncDir(dir);
+  fp('atomic-write:post-fsync-dir', { path });
+}
+
+/**
+ * 逐层创建目录并 fsync 到已存在的祖先为止（§5.2.1）。
+ * 反例：只 fsync 叶子时，断电可能「叶子里的文件在、而叶子本身的目录项不在」。
+ */
+export function mkdirChainFsync(target) {
+  const missing = [];
+  let cur = target;
+  while (!existsSync(cur)) { missing.unshift(cur); cur = dirname(cur); }
+  if (missing.length === 0) return;
+  for (const d of missing) { mkdirSync(d, 0o755); pendingCreate(d); }
+  fp('mkdir-chain:post-mkdir', { target, created: missing.length });
+  // 从最深处往上 fsync：每个新建目录 + 其父
+  for (let i = missing.length - 1; i >= 0; i--) {
+    fsyncDir(missing[i]);
+    fp('mkdir-chain:mid-fsync', { dir: missing[i] });
+  }
+  fsyncDir(cur); // 已存在的最近祖先
+  fp('mkdir-chain:post-fsync', { target });
+}
+
+/** rmtree 之后 fsync 父目录（§5.4 幂等规则） */
+export function fsyncParentAfter(path) {
+  const p = dirname(path);
+  if (existsSync(p)) fsyncDir(p);
+}
+
+/**
+ * 整棵目录的 rename + 两侧父目录 fsync —— §5.3 的 ② 与 ④。
+ * 🔴 两侧都要 fsync：只 fsync 目标侧时，断电可能留下「源与目标都在」，
+ *    正是 §5.4 幂等表里判 corrupt 的分支 ②。
+ */
+export function renameDirFsync(from, to) {
+  fp('rename-dir:pre', { from, to, syscall: 'rename' });
+  renameSync(from, to);
+  pendingRename(from, to);
+  fp('rename-dir:post-rename', { from, to });
+  fsyncDir(dirname(to));
+  fp('rename-dir:post-fsync-dst', { from, to });
+  const src = dirname(from);
+  if (src !== dirname(to)) {
+    // 🔴 源父目录不见了不是「跳过」的理由 —— 那说明有第三方在动我们的状态目录。
+    //    fail-closed（§5.4 的 I/O 统一规则）。
+    if (!existsSync(src)) throw new Error(`rename-dir：源父目录 ${src} 已不存在，无法 fsync`);
+    fsyncDir(src);
+  }
+  fp('rename-dir:post-fsync-src', { from, to });
+}
+
+/**
+ * 递归删除 + fsync 父目录。
+ * §5.4：`rmtree` 天然幂等（不存在就跳过），但 🔴 **成功后必须 fsync 父目录**。
+ *
+ * 🔴 **自己写递归，不用 `rmSync({recursive:true})`** —— 后者是一次调用，
+ *    「删到一半崩」根本注入不进去。而 §5.4 明说「`retired/<name>` 的递归删除
+ *    本身是**多次**操作」，那正是要打的窗口。`rmtree:mid` 就埋在每删掉一项之后。
+ */
+export function rmtreeFsync(path) {
+  fp('rmtree:pre', { path });
+  // 🔴 `existsSync` 是 fail-open 的：broken symlink、EACCES 都返回 false，
+  // 于是「看不见」被当成「不存在」，清理被标记完成而目标其实还在。
+  // 判据必须是 lstat 的 errno：只有 ENOENT/ENOTDIR 才是真的没有。
+  try {
+    lstatSync(path);
+  } catch (err) {
+    if (err?.code === 'ENOENT' || err?.code === 'ENOTDIR') {
+      fp('rmtree:post', { path, skipped: true });
+      return;
+    }
+    throw err;   // EACCES 之类：看不见就不能声称删干净了
+  }
+  rmtreeStepwise(path);
+  fp('rmtree:post', { path });
+  const p = dirname(path);
+  if (existsSync(p)) fsyncDir(p);
+  fp('rmtree:post-fsync-parent', { path });
+}
+
+/**
+ * 🔴 **逐项**登记删除效果（Codex 第二轮 #10）。
+ * 以前是整棵删完才登记一次、且 undo 是空函数，于是「删到一半掉电」这个窗口
+ * 在 powerfail 模型里等于没建模 —— 那正是 §5.6 阶段 C 最危险的一格。
+ * 现在每删掉一个条目就存下它的前像，undo 逆序把它放回去。
+ */
+function rmtreeStepwise(path) {
+  const st = lstatSync(path);
+  if (!st.isDirectory()) {
+    const preimage = shadowActive() ? readFileSync(path) : null;
+    const mode = st.mode & 0o777;
+    unlinkSync(path);
+    pendingUnlink(path, preimage, mode);
+    fp('rmtree:mid', { removed: path });
+    return;
+  }
+  for (const name of readdirSync(path).sort()) rmtreeStepwise(join(path, name));
+  rmdirSync(path);
+  pendingUnlink(path, null, 0o755, true);
+  fp('rmtree:mid', { removed: path });
+}
+
+/** 判断两个路径是否同设备（stage 与 target 必须同设备，否则 rename 会 EXDEV） */
+export function sameDevice(a, b) {
+  return statSync(a).dev === statSync(b).dev;
+}

package/src/attestation.mjs

@@ -0,0 +1,136 @@
+// attestation（02-registry.md §1.1）—— DSSE envelope + in-toto statement
+//
+// 🔴 **安装链路不读它。** 它只服务取证：绑定「快照的 sha256 ↔ 源 commit」，
+// 单向依赖（source commit → snapshot → attestation），不构成自引用。
+// P0-1 把 release commit SHA 从快照里删掉了（那会自引用），代价是失去
+// 「哪条流水线生成了它」的强审计；补回来的方式不是塞回快照，而是另发这个签名对象。
+//
+// 本模块**不导出**任何会被安装链路调用的名字，函数名里带 ForForensics 就是提醒。
+import {
+  WireError, IntegrityError, REPO,
+  parseWireJson, assertExactKeys, assertUint, assertString, assertTreeDigest,
+} from './trust.mjs';
+
+export const DSSE_PAYLOAD_TYPE = 'application/vnd.in-toto+json';
+export const PREDICATE_TYPE = 'https://geoly.ai/skills-hub/release/v1';
+export const BUILD_TYPE = 'geoly-skills/release/v1';
+export const STATEMENT_TYPE = 'https://in-toto.io/Statement/v1';
+
+const RE_COMMIT = /^[0-9a-f]{40}$/;
+const RE_HEX64 = /^[0-9a-f]{64}$/;
+const RE_B64 = /^[A-Za-z0-9+/]*={0,2}$/;
+
+const ENVELOPE_KEYS = { required: ['payload', 'payloadType', 'signatures'] };
+const SIG_KEYS = { required: ['sig'], optional: ['keyid'] };
+const STATEMENT_KEYS = { required: ['_type', 'subject', 'predicateType', 'predicate'] };
+const SUBJECT_KEYS = { required: ['name', 'digest'] };
+const PREDICATE_KEYS = { required: ['buildType', 'sourceRepo', 'sourceCommit', 'workflowRef', 'promotionPr'] };
+
+/** DSSE 的 PAE 预认证编码 —— 验签器要签的就是这串字节 */
+export function pae(payloadType, payload) {
+  const t = Buffer.from(payloadType, 'utf8');
+  const p = Buffer.isBuffer(payload) ? payload : Buffer.from(payload);
+  return Buffer.concat([
+    Buffer.from(`DSSEv1 ${t.length} `, 'utf8'), t,
+    Buffer.from(` ${p.length} `, 'utf8'), p,
+  ]);
+}
+
+/** 严格 base64：拒绝空白、换行、非标准字母表、非 canonical 填充 */
+function decodeB64Strict(s, where) {
+  assertString(s, where);
+  if (!RE_B64.test(s) || s.length % 4 !== 0) throw new WireError('E_B64', `${where} 不是严格 base64`);
+  const buf = Buffer.from(s, 'base64');
+  if (buf.toString('base64') !== s) throw new WireError('E_B64', `${where} 的 base64 不是 canonical 形式`);
+  return buf;
+}
+
+/**
+ * 解析并严格校验一个 attestation。
+ *
+ * 🔴 **只用于取证**（02-registry.md §1.1 的契约表：「验证者 = 取证工具与人；
+ * CLI 的安装链路不读」）。把它接进安装链路等于把一个不参与信任的对象变成信任输入。
+ *
+ * @param {Buffer} bytes DSSE envelope 的 JSON 字节
+ * @param {{expectSnapshotSha256?:string, expectSnapshotN?:number}} expect
+ */
+export function parseAttestationForForensics(bytes, { expectSnapshotSha256, expectSnapshotN } = {}) {
+  const env = parseWireJson(bytes, 'attestation');
+  assertExactKeys(env, ENVELOPE_KEYS, 'attestation');
+  if (env.payloadType !== DSSE_PAYLOAD_TYPE) {
+    throw new WireError('E_DSSE_PAYLOAD_TYPE', `payloadType 必须是 ${DSSE_PAYLOAD_TYPE}，得到 ${JSON.stringify(env.payloadType)}`);
+  }
+  if (!Array.isArray(env.signatures) || env.signatures.length === 0) {
+    throw new WireError('E_DSSE_SIGNATURES', 'signatures 必须是非空数组');
+  }
+  env.signatures.forEach((s, i) => {
+    assertExactKeys(s, SIG_KEYS, `attestation.signatures[${i}]`);
+    decodeB64Strict(s.sig, `attestation.signatures[${i}].sig`);
+    if (Object.hasOwn(s, 'keyid')) assertString(s.keyid, `attestation.signatures[${i}].keyid`);
+  });
+
+  const payload = decodeB64Strict(env.payload, 'attestation.payload');
+  const stmt = parseWireJson(payload, 'attestation.payload');
+  assertExactKeys(stmt, STATEMENT_KEYS, 'attestation.payload');
+  if (stmt._type !== STATEMENT_TYPE) {
+    throw new WireError('E_STATEMENT_TYPE', `_type 必须是 ${STATEMENT_TYPE}，得到 ${JSON.stringify(stmt._type)}`);
+  }
+  if (stmt.predicateType !== PREDICATE_TYPE) {
+    throw new WireError('E_PREDICATE_TYPE', `predicateType 必须是固定字符串 ${PREDICATE_TYPE}（变更即升版本）`);
+  }
+  if (!Array.isArray(stmt.subject) || stmt.subject.length !== 1) {
+    throw new WireError('E_SUBJECT_COUNT', 'subject 必须恰好一项（一个 attestation 只绑一张快照）');
+  }
+  const sub = stmt.subject[0];
+  assertExactKeys(sub, SUBJECT_KEYS, 'attestation.subject[0]');
+  assertString(sub.name, 'attestation.subject[0].name');
+  assertExactKeys(sub.digest, { required: ['sha256'] }, 'attestation.subject[0].digest');
+  if (!RE_HEX64.test(assertString(sub.digest.sha256, 'attestation.subject[0].digest.sha256'))) {
+    throw new WireError('E_SUBJECT_DIGEST', 'subject[0].digest.sha256 必须是 64 位小写 hex');
+  }
+
+  const p = stmt.predicate;
+  assertExactKeys(p, PREDICATE_KEYS, 'attestation.predicate');
+  if (p.buildType !== BUILD_TYPE) throw new WireError('E_BUILD_TYPE', `buildType 必须是 ${BUILD_TYPE}`);
+  if (p.sourceRepo !== REPO) throw new WireError('E_SOURCE_REPO', `sourceRepo 必须是 ${REPO}，得到 ${p.sourceRepo}`);
+  if (!RE_COMMIT.test(assertString(p.sourceCommit, 'attestation.predicate.sourceCommit'))) {
+    throw new WireError('E_SOURCE_COMMIT', `sourceCommit 必须是 40 位小写 hex，得到 ${p.sourceCommit}`);
+  }
+  assertUint(p.promotionPr, 'attestation.predicate.promotionPr');
+
+  // 🔴 workflowRef 必须是**不可变标识**：`.github/workflows/release.yml@<40 位 sha>`。
+  //    **不接受 `@refs/heads/main`** —— 分支引用本身可变，写它等于没写。
+  const wf = assertString(p.workflowRef, 'attestation.predicate.workflowRef');
+  if (/@refs\/(heads|tags)\//.test(wf)) {
+    throw new WireError('E_WORKFLOW_REF_MUTABLE',
+      `workflowRef 用了可变的分支/标签引用（${wf}）：必须钉 40 位 commit sha`);
+  }
+  const m = /^\.github\/workflows\/release\.yml@([0-9a-f]{40})$/.exec(wf);
+  if (!m) {
+    throw new WireError('E_WORKFLOW_REF', `workflowRef 必须形如 .github/workflows/release.yml@<40 位小写 hex>，得到 ${wf}`);
+  }
+  // 规格给的示例里两者相同；这里强制相等，否则「哪条流水线」与「哪个源 commit」可以各说各话。
+  if (m[1] !== p.sourceCommit) {
+    throw new WireError('E_WORKFLOW_REF_COMMIT',
+      `workflowRef 钉的 commit(${m[1]}) 与 sourceCommit(${p.sourceCommit}) 不一致`);
+  }
+
+  // 与 timestamp 交叉核对（契约表：subject[].digest.sha256 必须与 timestamp.snapshot_sha256 一致）
+  if (expectSnapshotSha256 !== undefined) {
+    const want = expectSnapshotSha256.replace(/^sha256:/, '');
+    if (sub.digest.sha256 !== want) {
+      throw new IntegrityError('E_ATTEST_SUBJECT_MISMATCH',
+        `attestation 的 subject 摘要 ${sub.digest.sha256} 与 timestamp.snapshot_sha256 ${want} 不一致`);
+    }
+  }
+  if (expectSnapshotN !== undefined && sub.name !== `hub-${expectSnapshotN}.json`) {
+    throw new IntegrityError('E_ATTEST_SUBJECT_NAME',
+      `attestation 的 subject.name 是 ${sub.name}，期望 hub-${expectSnapshotN}.json`);
+  }
+
+  return { envelope: env, statement: stmt, predicate: p, subject: sub, pae: pae(env.payloadType, payload) };
+}
+
+// `assertTreeDigest` 在本模块用不到，但 re-export 会诱使调用方从这里拿安装用的校验器。
+// 故意不 re-export —— 保持「attestation 不在安装链路上」这条边界清晰。
+void assertTreeDigest;