@geoly-ai/skills-hub 0.2.0 → 0.3.0

package/README.md

@@ -6,6 +6,22 @@
 `geoly-ai` 的 skill 分发中心：一条命令装单个 skill、装矩阵包，
 并支持外部投稿与过审。
 
+## 线上
+
+| | |
+|---|---|
+| registry 浏览站 | **https://skills-hub-pearl.vercel.app/** |
+| 埋点摄入端 | `https://skills-hub-telemetry.vercel.app/v1/events` |
+
+🔴 **不是 `skills-hub.vercel.app`** —— `.vercel.app` 子域名全局唯一，项目名撞车时
+Vercel 会自动追加一个随机词（这就是 `-pearl` 的来历）。那个裸域名**不属于本项目**，
+访问它拿到的是 Vercel 边缘层的 `NOT_FOUND`（`text/plain`，不是站点自己的 404 页）。
+
+⚠️ 这一条踩过：看到裸域名 404 就以为站点坏了，实际站点一直好好的。
+   ⚠️ 更值得记的是随之而来的第二个错误 —— 曾经在**那个 404 页面**上
+   `grep _vercel/insights` 来判断「站点有没有引 analytics 脚本」。
+   **在错误的 URL 上取证，结论就算碰巧对了也是无效的。**
+
 ## 安装
 
 ```sh

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@geoly-ai/skills-hub",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "geoly-ai 的 skill 分发中心 —— 安装、校验、审计",
   "type": "module",
   "bin": {

package/src/commands/context.mjs

@@ -222,6 +222,13 @@ export function makeContext(globals, deps = {}) {
     verifier: deps.verifier ?? null,
     /** 注入点：测试用内存 registry，生产用 `registry.mjs` 的缓存适配器 */
     registryFactory: deps.registryFactory ?? null,
+    /**
+     * 注入点：出网。生产走内建 `fetch`（`src/download.mjs` 的默认值）。
+     * 🔴 与 `verifier` 一样**没有逃生口**：不给就是真出网，
+     *    不存在「测试忘了注入所以静默不出网」这种状态 ——
+     *    那会让「--offline 有没有被绕过」这个问题看起来被回答了，其实没有。
+     */
+    fetchImpl: deps.fetchImpl ?? null,
     /** 注入点：埋点。生产是 `telemetry.record` */
     record: deps.record ?? null,
     /**

package/src/commands/install.mjs

@@ -30,6 +30,7 @@ import { parseSpec, resolveSpec } from './resolve.mjs';
 import { annotations, annotationSuffix } from './output.mjs';
 import { UsageError, ConflictError, UnsupportedError, EXIT, classify } from '../exit-codes.mjs';
 import { resolveSnapshotForCommand } from './snapshot-access.mjs';
+import { preheatForInstall, preheatAssetsFor } from './preheat-run.mjs';
 import { makeLockfileHook } from './sync-lock.mjs';
 
 /**
@@ -494,6 +495,12 @@ export async function cmdInstall(ctx, argv, out) {
   }
 
   // ── 解析当前快照（metadata 锁在 trust 内核里起落，本层不碰它） ───────────
+  // ── 联网刷新 metadata（🔴 必须在解析快照**之前**）────────────────────────
+  //    出网只发生在这里；`resolveSnapshotForCommand` 之后的一切都是同步的、
+  //    只读本地缓存。`--offline` 时这一步直接跳过 —— 走的是同一条码，
+  //    不是「另一条不出网的实现」。
+  await preheatForInstall(ctx, out);
+
   const { snapshot: snap, stale, floor, pinned, verifier } = await resolveSnapshotForCommand(ctx);
   if (stale) out.warn('timestamp 已过期：本次输出全部按 stale 处理（--allow-stale 已给）');
 
@@ -515,6 +522,10 @@ export async function cmdInstall(ctx, argv, out) {
   //    完全同一个**的兼容性检查 —— 一处判定、一种文案。
   //    因此这里 `client: null`：让 resolvePackInstall 只管成员，不重复判 client。
   const byId = new Map(snap.artifacts.map((r) => [r.id, r]));
+  // 🔴 `fetchAsset` 是**同步**的（内核要求），所以字节必须在这之前就到本地。
+  //    分两波是因为 pack 本体要先下回来、验过、读出 manifest，
+  //    才知道它的成员是哪些 —— 成员的资产在下面第二波。
+  await preheatAssetsFor(ctx, records.filter((r) => r.kind === 'pack'), snap);
   const packInfos = records.filter((r) => r.kind === 'pack').map((record) => {
     const bytes = ctx.registry.fetchAsset(record);
     const manifest = withPackErrors(() => withVerifiedArtifact(
@@ -563,6 +574,12 @@ export async function cmdInstall(ctx, argv, out) {
     }
   }
 
+  // ── 第二波：单元资产（🔴 也必须在进事务之前）────────────────────────────
+  //    `installOneTarget` 是**同步**的 —— 它在锁与事务里面，不能 await。
+  //    所以真正会落盘的那些字节必须在这里就到本地。
+  //    ⚠️ 各 client 的单元可能不同，所以取的是**并集**；按摘要落盘，重复的不会重下。
+  await preheatAssetsFor(ctx, [...perClient.values()].flatMap((v) => v.units.map((u) => u.record)), snap);
+
   if (isAll) {
     // 🔴 **名单为空的 client 整个跳过，不要走一个空事务。**
     //    实测（2026-08-30 探针）：不跳的话它照样 bootstrap 出 `.geoly`、烧掉一代

package/src/commands/preheat-run.mjs

@@ -0,0 +1,105 @@
+// preheat 的**编排** —— 把「出网取字节」与「同步验签」缝在一起。
+//
+// 🔴 顺序是这个模块存在的全部理由：
+//
+//   ① preheatMetadata   出网，只往 staging 写         （async）
+//   ② resolveCurrent    验签/新鲜度/floor，读 staging  （**同步、原样未改**）
+//   ③ promoteMetadata   持 metadata 锁，原子提升        （同步）
+//
+// ②**不能**接受 Promise —— 内核就是同步的，这也是 preheat 必须存在的原因。
+// 所以 ① 与 ③ 之间那一段里，「已下载但还没验」的字节**只在 staging**。
+//
+// ⚠️ ② 内部会取 metadata 锁（`advanceTrustFloor` 自己 acquire/release），
+//    而 ③ 也要取同一把。`src/lock.mjs` **禁止重入**，所以 ③ 必须在 ② **返回之后**
+//    调用，不能把 ② 包进 ③ 的临界区里。
+
+import { existsSync } from 'node:fs';
+import { resolveCurrent } from '../snapshot.mjs';
+import { readTrustFloor, resolveStateDir } from '../trust.mjs';
+import { preheatAssets, preheatMetadata, promoteMetadata, discard, newBudget } from '../preheat.mjs';
+import { createCacheRegistry } from './registry.mjs';
+
+/**
+ * 联网刷新一次 metadata（timestamp + 当前快照）到本地缓存。
+ *
+ * @returns {{refreshed:boolean, n:number|null, reason:string}}
+ */
+export async function preheatOnce({
+  cacheDir, stateDir, verifier, cliVersion, now, fetchImpl, timeoutMs,
+  budget = newBudget(),
+}) {
+  const { stagingDir, n } = await preheatMetadata({ cacheDir, fetchImpl, timeoutMs, budget });
+  try {
+    // 🔴 registry 指向 **staging**，不是 cache —— 验的必须是刚下回来的那份。
+    //    指向 cache 的话，验的是上一轮的旧字节，而新字节从没被验过就被提升了。
+    const staged = createCacheRegistry({ cacheDir: stagingDir, offline: false });
+    resolveCurrent({
+      stateDir,
+      fetchTimestamp: staged.fetchTimestamp,
+      fetchSnapshot: staged.fetchSnapshot,
+      verifier, cliVersion, now,
+      offline: false,
+    });
+    // 到这里 floor 已经被 ② 推进过了；③ 在锁内重读并比对它。
+    const floor = readTrustFloor(resolveStateDir(stateDir));
+    promoteMetadata({ cacheDir, stateDir, stagingDir, n, expectedFloor: floor });
+    return { refreshed: true, n, reason: 'ok' };
+  } catch (e) {
+    // 🔴 验不过就整个丢掉 staging —— 缓存里那份**旧的、验过的**原样保留。
+    //    这正是「未验证字节不进缓存」那条的落点：攻击者投毒一次，
+    //    也只是让这一次刷新失败，而不是把本地永久毒成验不过。
+    discard(stagingDir);
+    throw e;
+  }
+}
+
+/**
+ * install 之前的刷新。**失败要不要致命，取决于本地有没有可用的缓存。**
+ *
+ * 🔴 有缓存时网络失败**不该**中断安装：离线可用是这个 CLI 的核心属性之一。
+ *    但**验签失败**永远致命 —— 那不是「网络不好」，那是有人在改字节。
+ *    两者报的错必须分得开，否则「网络抖了一下」会被写进 issue 说成「你们被入侵了」，
+ *    反过来更糟：真被投毒时被当成网络问题重试掉。
+ */
+export async function preheatForInstall(ctx, out) {
+  if (ctx.offline) return { refreshed: false, reason: 'offline' };
+  // 🔴 注入了自定义 registry 时不 preheat：那种情况下字节**根本不从缓存来**，
+  //    下载只是在给一个没人会读的目录塞东西。
+  //    ⚠️ 这不是「测试专用后门」—— 判据是「字节的来源是不是本地缓存」，
+  //    生产入口 `bin/skills-hub.mjs` 一个 dep 都不传，永远走不到这条。
+  if (ctx.registryFactory) return { refreshed: false, reason: 'custom-registry' };
+  const haveCache = existsSync(`${ctx.cacheDir}/timestamp.json`);
+  try {
+    const r = await preheatOnce({
+      cacheDir: ctx.cacheDir, stateDir: ctx.stateDir,
+      verifier: ctx.verifier, cliVersion: ctx.cliVersion, now: ctx.now,
+      fetchImpl: ctx.fetchImpl,
+    });
+    if (r.refreshed) out?.note?.(`已刷新到快照 ${r.n}`);
+    return r;
+  } catch (e) {
+    // 完整性/验签问题一律上抛 —— 它们**不是**「网络不好」。
+    if (e.name === 'IntegrityError' || e.name === 'WireError' || e.code?.startsWith?.('E_')) throw e;
+    if (!haveCache) throw e;      // 没缓存又取不到 = 真的装不了
+    out?.note?.(`联网刷新失败（${e.message}）—— 改用本地缓存继续`);
+    return { refreshed: false, reason: 'network-failed-cache-used' };
+  }
+}
+
+/**
+ * 下载一批记录的资产。`--offline` 时直接跳过 —— 缓存未命中会在
+ * `registry.fetchAsset()` 那里报「离线未命中」，那是**它**该报的错。
+ *
+ * 🔴 `records` 必须来自**已验签的快照**。调用方传进来的对象里
+ *    `asset.sha256` / `size` / `file` 决定了下载什么、校验什么 ——
+ *    如果它们不是从验过的快照里来的，「校验通过」就只是在和自己对暗号。
+ */
+export async function preheatAssetsFor(ctx, records, snap) {
+  if (ctx.offline || ctx.registryFactory || records.length === 0) return;
+  await preheatAssets({
+    cacheDir: ctx.cacheDir,
+    n: snap.snapshot,
+    records,
+    fetchImpl: ctx.fetchImpl ?? undefined,
+  });
+}

package/src/download.mjs

@@ -0,0 +1,191 @@
+// 取字节的**唯一**出网口 —— preheat 用它，别的地方不许自己开 fetch。
+//
+// 🔴 这一层**一个校验都不做**（除了下面这几条纯粹的传输上限）。
+//    签名、摘要、新鲜度、trust floor 全在 `snapshot.resolveCurrent()` 与
+//    `artifact.*` 里。理由与 `commands/registry.mjs` 顶部那条相同：把校验
+//    放进取字节层，会诱使人写「这次是我自己下的、可以信」。
+//    **下载器不认识「可信」这个概念。**
+//
+// 出网规矩与 `upload.mjs` 保持一套（那边已经踩过一遍）：
+//   · https-only，且用 URL 解析判断而不是 `startsWith`
+//   · 禁止重定向
+//   · 超时必须覆盖到**读完 body**，不能 fetch 一返回就 clear
+//
+// ⚠️ 与 upload 不同的一条：那边是**发**数据，这边是**收**。
+//    收的一侧多一个上限问题 —— 见 `readCapped` 的注释。
+
+import { NetworkError } from './exit-codes.mjs';
+
+/** 单次下载的硬上限。资产另有更大的上限，由调用方按快照记录的 size 传入。 */
+export const MAX_DOWNLOAD_BYTES = 8 * 1024 * 1024;
+
+/**
+ * 默认超时。🔴 覆盖全程：DNS、连接、TLS、响应头、**整条重定向链**、读完 body。
+ *
+ * ⚠️ 这一行原本是单行注释，里面的 `**整条重定向链**` 紧跟一个斜杠 ——
+ *    `*` + `/` 当场把块注释关掉了，报的却是「Unexpected identifier 'body'」。
+ *    在块注释里写 Markdown 粗体时，**别让星号紧挨着斜杠**。
+ */
+export const DEFAULT_TIMEOUT_MS = 30_000;
+
+/**
+ * 允许被重定向到的 host。
+ *
+ * 🔴 **不能只允许 0 次重定向** —— 2026-09-03 实测，GitHub Release 资产必然 302：
+ *
+ *     github.com/<repo>/releases/download/<tag>/<file>
+ *       → 302 → release-assets.githubusercontent.com/…?sp=r&sig=…&jwt=…
+ *
+ *    所以「一次都不跟随」等于一个字节都下不来。我第一版正是这么写的。
+ *
+ * ⚠️ 注意跳转目标**带查询串**（那是它的签名参数）——
+ *    因此「禁止 query/fragment」只能管**初始 URL**，不能一并套到跳转目标上，
+ *    否则同样是全部下载失败。
+ */
+export const REDIRECT_HOSTS = Object.freeze(['release-assets.githubusercontent.com']);
+
+/** 重定向跳数上限。实测只需 1 跳；给 3 是留余量，不是没有上限。 */
+export const MAX_REDIRECTS = 3;
+
+/**
+ * 校验下载地址。
+ *
+ * 🔴 host 必须由调用方钉死，**不接受来自被下载内容的地址**。
+ *    locator 契约（02-registry.md §4.0）要求推导链上不出现未验签输入 ——
+ *    一个「服务端告诉你去哪儿取下一段」的下载器，正好破坏那条契约。
+ */
+export function assertDownloadUrl(raw, expectHost, { isRedirect = false } = {}) {
+  if (!expectHost) {
+    // 🔴 不给 host 就不许下载。默认放行等于把这道闸留在「注释里」——
+    //    我第一版正是只写了注释、没写代码（见下面那条实测）。
+    throw new NetworkError('assertDownloadUrl 必须传 expectHost —— 下载地址的 host 由调用方钉死');
+  }
+  const allowed = Array.isArray(expectHost) ? expectHost : [expectHost];
+  let u;
+  try { u = new URL(raw); } catch { throw new NetworkError(`下载地址不是合法 URL：${raw}`); }
+  if (u.protocol !== 'https:') throw new NetworkError(`下载地址必须是 https：${raw}`);
+  if (u.username || u.password) throw new NetworkError('下载地址不得内嵌凭据');
+  // 🔴 **真正拦住改道的是 host 这一条，不是上面的 protocol 检查。**
+  //    实测：`https:/\evil.test/a`（一条反斜杠）被 WHATWG URL 规范化成
+  //    `https://evil.test/a` —— protocol 是 https、凭据也没有，
+  //    上面两条**全部放行**，字节从 evil.test 来。
+  //    ⚠️ 所以「用 URL 解析而不是 startsWith」只解决了协议混淆，
+  //    没解决 host 混淆；host 必须单独比，且比的是解析后的 `u.host`。
+  if (!allowed.includes(u.host)) {
+    throw new NetworkError(
+      `下载地址的 host 是 ${u.host}，不在允许列表 [${allowed.join(', ')}] 里：${raw}`,
+    );
+  }
+  // 初始 URL 由 locator 契约推导，**必须是干净路径**：带 query/fragment 说明
+  // 它不是我们自己拼出来的。跳转目标反过来——GitHub 的签名参数就在 query 里，
+  // 对它套同一条会让所有下载失败（实测）。
+  if (!isRedirect && (u.search || u.hash)) {
+    throw new NetworkError(`初始下载地址不得带查询串或片段：${raw}`);
+  }
+  return u;
+}
+
+/**
+ * 读 body，并在**读的过程中**记账。
+ *
+ * 🔴 不能只信 `Content-Length`：它是服务端自己说的。声称 1 KiB 却发 10 GiB
+ *    是一行代码的事，而 `res.arrayBuffer()` 会**先把它全收下来**再让你发现超限 ——
+ *    那时候内存已经没了。所以：Content-Length 先做一次早筛（能省则省），
+ *    真正的上限在流式读取里逐块累计，超了当场断开。
+ */
+async function readCapped(res, cap, what) {
+  const declared = Number(res.headers?.get?.('content-length'));
+  if (Number.isFinite(declared) && declared > cap) {
+    throw new NetworkError(`${what} 声称 ${declared} 字节，超过上限 ${cap}`);
+  }
+  if (!res.body?.getReader) {
+    // 测试替身可能只给 arrayBuffer()。生产路径（undici）一定有 body。
+    const buf = Buffer.from(await res.arrayBuffer());
+    if (buf.length > cap) throw new NetworkError(`${what} 有 ${buf.length} 字节，超过上限 ${cap}`);
+    return buf;
+  }
+  const reader = res.body.getReader();
+  const chunks = [];
+  let total = 0;
+  for (;;) {
+    const { done, value } = await reader.read();
+    if (done) break;
+    total += value.length;
+    if (total > cap) {
+      await reader.cancel().catch(() => {});
+      throw new NetworkError(`${what} 超过上限 ${cap} 字节（读到 ${total} 就断开了）`);
+    }
+    chunks.push(value);
+  }
+  return Buffer.concat(chunks, total);
+}
+
+/**
+ * 下载一个 URL，返回 Buffer。
+ *
+ * @param {string} url
+ * @param {object} [o]
+ * @param {number} [o.cap]        字节上限，默认 MAX_DOWNLOAD_BYTES
+ * @param {function} [o.fetchImpl] 注入用
+ * @param {number} [o.timeoutMs]
+ * @param {string} [o.what]       出错信息里怎么称呼它
+ */
+export async function download(url, {
+  host,
+  redirectHosts = REDIRECT_HOSTS,
+  maxRedirects = MAX_REDIRECTS,
+  cap = MAX_DOWNLOAD_BYTES,
+  fetchImpl = globalThis.fetch,
+  timeoutMs = DEFAULT_TIMEOUT_MS,
+  what = url,
+} = {}) {
+  assertDownloadUrl(url, host);
+  if (typeof fetchImpl !== 'function') {
+    throw new NetworkError('当前 Node 没有内建 fetch，且调用方没有注入 fetchImpl');
+  }
+  const ac = new AbortController();
+  // 🔴 计时器覆盖**整条重定向链 + 读完 body**，只在最后 clear。
+  //    在 fetch 返回时就 clear 的话，一个慢慢滴字节的服务端可以让这次下载
+  //    永远挂着（upload.mjs 同款教训）；每跳各起一个计时器的话，
+  //    N 跳就等于把超时放大 N 倍。
+  const timer = setTimeout(() => ac.abort(), timeoutMs);
+  try {
+    let current = url;
+    for (let hop = 0; ; hop += 1) {
+      let res;
+      try {
+        res = await fetchImpl(current, {
+          method: 'GET',
+          // 🔴 'manual' 而不是 'follow'：跳到哪儿由**我们**决定，
+          //    每一跳都重新过一遍 https + host allowlist。
+          //    交给 fetch 的 follow 就没有这道复核了。
+          redirect: 'manual',
+          signal: ac.signal,
+        });
+      } catch (e) {
+        if (ac.signal.aborted) throw new NetworkError(`${what} 下载超时（${timeoutMs} ms）`);
+        throw new NetworkError(`${what} 下载失败：${e.message}`);
+      }
+
+      if (res.status >= 300 && res.status < 400) {
+        const loc = res.headers?.get?.('location');
+        if (!loc) throw new NetworkError(`${what} 回了 HTTP ${res.status} 却没给 location`);
+        if (hop >= maxRedirects) {
+          throw new NetworkError(`${what} 重定向超过 ${maxRedirects} 跳，放弃`);
+        }
+        // 相对 location 也要能处理；解析基准是当前这一跳的地址
+        const next = new URL(loc, current).toString();
+        // 🔴 每一跳都复核。跳转目标允许带 query（GitHub 的签名参数在那里），
+        //    但 https 与 host allowlist 一步都不能少。
+        assertDownloadUrl(next, redirectHosts, { isRedirect: true });
+        current = next;
+        continue;
+      }
+
+      if (!res.ok) throw new NetworkError(`${what} 下载失败：HTTP ${res.status}`);
+      return await readCapped(res, cap, what);
+    }
+  } finally {
+    clearTimeout(timer);
+  }
+}

package/src/preheat.mjs

@@ -0,0 +1,416 @@
+// preheat —— 把「取字节」这件事**整个挪到 resolveCurrent() 之前**。
+//
+// 为什么必须是这个形状：`snapshot.resolveCurrent()` 是**同步**函数，它要求
+// `fetchTimestamp()` / `fetchSnapshot(n)` 同步返回。内建 fetch 返回 Promise，
+// 接不进去；把内核改成 async 是内核 API 变更。于是：
+//
+//   preheat（async，出网，只往 staging 写）
+//     → resolveCurrent（同步，原样未改，只读缓存/staging）
+//     → 提升（持 metadata 锁，原子 rename）
+//
+// 🔴 **缓存里只放验过的字节。** timestamp.json 与 snapshots/<N> **不是内容寻址**
+//    （文件名不含摘要），未验证就写进去的话，攻击者投毒一次就能让之后每一次
+//    `--offline` 都验签失败 —— 那是**持久 DoS**，而且看起来像「我们的签名坏了」。
+//    staging 让这件事在构造上不可能。
+//
+// ⚠️ **可证明的承诺只有这两条**（Codex 2026-09-03 纠正了我原来的说法）：
+//    · 提升**之前**失败：旧的可达缓存不变。
+//    · 提升**过程中**失败：只可能留下**已验证、且不被新 timestamp 引用**的孤儿文件；
+//      **不会留下坏指针**。
+//    我原本写的是「任何失败 cache 一个字节都没被碰过」—— 那是**假的**：
+//    提升是多次 rename，第一次成、第二次挂，缓存就已经变了。多文件 rename
+//    不是事务，说它是事务只会让后来的人依赖一个不存在的保证。
+
+import { existsSync, linkSync, readFileSync, renameSync, rmSync, statSync, unlinkSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { randomBytes } from 'node:crypto';
+import { download } from './download.mjs';
+import { unwrapTimestamp } from './timestamp-envelope.mjs';
+import { acquire } from './lock.mjs';
+import { NetworkError } from './exit-codes.mjs';
+import {
+  IntegrityError, METADATA_LOCK, assertFloorUnchanged, resolveStateDir, sha256Of,
+} from './trust.mjs';
+import { fsyncDir, fsyncParentAfter, mkdirChainFsync, writeAtomic } from './atomic-fs.mjs';
+
+/** 内建 host。🔴 只能来自这里 —— 不接受 timestamp/snapshot/用户输入里的地址。 */
+export const REGISTRY_HOST = 'github.com';
+export const REGISTRY_BASE = `https://${REGISTRY_HOST}/geoly-ai/skills-hub`;
+
+/** 单份 JSON 的上限，与 11-wire-contract.md §2 一致。 */
+export const MAX_JSON_BYTES = 8 * 1024 * 1024;
+
+/**
+ * 一次 preheat 的总量闸。
+ *
+ * 🔴 单文件上限拦不住「很多个小文件」：`install --all` 的记录集来自快照，
+ *    而快照是验过签的 —— 但**先下载后验签**的顺序意味着，在验签之前
+ *    我们已经按它说的条数发了那么多请求。总量闸是这一段的兜底。
+ */
+export const MAX_TOTAL_BYTES = 512 * 1024 * 1024;
+export const MAX_REQUESTS = 512;
+
+/** 整个 preheat 的总 deadline（单次下载另有自己的超时）。 */
+export const MAX_TOTAL_MS = 10 * 60 * 1000;
+
+// ── locator（02-registry.md §4.0）────────────────────────────────────────────
+//
+// 🔴 推导链上不出现任何未验签的输入：`<N>` 来自**已验签**的 timestamp，
+//    `<file>` 由**已验签**快照里那条记录的字段重算，`<host>` 是内建常量。
+
+export const timestampUrl = () => `${REGISTRY_BASE}/releases/download/timestamp/timestamp.json`;
+export const snapshotUrl = (n) => `${REGISTRY_BASE}/releases/download/hub-v${n}/hub-${n}.json`;
+export const snapshotBundleUrl = (n) => `${REGISTRY_BASE}/releases/download/hub-v${n}/hub-${n}.json.sigstore.json`;
+export const assetUrl = (n, file) => `${REGISTRY_BASE}/releases/download/hub-v${n}/${file}`;
+
+/**
+ * 快照号必须是**非负安全整数**，且原样可往回写成同一个字符串。
+ *
+ * 🔴 拒绝浮点、指数、前导零、负数、超过 2^53-1。
+ *    理由不是「不好看」：这个值要拼进 URL，也要拼进本地文件名。
+ *    `Number('1e3')` 是 1000、`Number('007')` 是 7 —— 两个不同的字符串
+ *    映到同一个 N，等于给缓存投毒开了一扇门（同一个文件名两种来源）。
+ */
+export function assertSnapshotNumber(v, where = 'latest_snapshot') {
+  if (typeof v !== 'number' || !Number.isSafeInteger(v) || v < 0) {
+    throw new IntegrityError('E_SNAPSHOT_N', `${where} 必须是非负安全整数，得到 ${JSON.stringify(v)}`);
+  }
+  return v;
+}
+
+/**
+ * 资产文件名的安全校验 —— **不是黑名单，是重算后逐字节比**。
+ *
+ * 🔴 黑名单（拒 `/` `\` `..` query fragment 百分号编码…）永远漏得掉一种写法。
+ *    而发布端的命名是**确定性**的（`scripts/build-snapshot.mjs` 的
+ *    `assetFileName()`：`<kind>_<ns>_<name>_<version>.tar.gz`），
+ *    所以客户端可以用记录**自己的字段**重算一遍再比 —— 对不上就拒。
+ *    这样「什么字符算安全」这个问题根本不需要回答。
+ *
+ * ⚠️ 这也堵住了一类更隐蔽的：`asset.file` 指向**另一条记录**的资产。
+ *    黑名单查不出这种（它完全是个合法文件名）。
+ */
+export function assertAssetFile(rec) {
+  const expect = `${rec.kind}_${rec.namespace}_${rec.name}_${rec.version}.tar.gz`;
+  if (rec.asset?.file !== expect) {
+    throw new IntegrityError(
+      'E_ASSET_FILE',
+      `记录 ${rec.id} 的 asset.file 是 ${JSON.stringify(rec.asset?.file)}，`
+      + `但按它自己的字段应为 ${JSON.stringify(expect)}`,
+    );
+  }
+  return expect;
+}
+
+// ── staging ────────────────────────────────────────────────────────────────
+
+function makeStaging(cacheDir) {
+  // 🔴 必须在 cacheDir **内部**：跨设备的 rename 不是原子的，
+  //    而 /tmp 与用户 home 经常不在一个设备上。
+  const dir = join(cacheDir, '.staging', randomBytes(8).toString('hex'));
+  mkdirChainFsync(dir);
+  mkdirChainFsync(join(dir, 'snapshots'));
+  return dir;
+}
+
+/**
+ * 落一个文件到 staging。
+ *
+ * 🔴 走 `writeAtomic` 而不是裸 `writeFileSync` —— 后者**不 fsync 文件本身**，
+ *    断电后可能留下一个「存在但内容是零」的文件。对内容寻址的资产尤其要命：
+ *    文件名是摘要，看起来就像验过了（Codex 2026-09-03 P1）。
+ *    `writeAtomic` 还接着项目的掉电影子模型，绕过它等于这条路径不受故障注入覆盖。
+ *
+ * 这里仍然**一个校验都不做** —— 只保证「字节确实持久到盘上了」。
+ */
+function stage(dir, rel, bytes) {
+  const p = join(dir, rel);
+  writeAtomic(p, bytes);
+  return p;
+}
+
+/**
+ * 提升一个文件。
+ *
+ * 🔴 **滚动的东西不能用 no-replace。**
+ *    `timestamp.json` 每次都是新的：no-replace 会让第二次 preheat 必然
+ *    抛 E_CACHE_CONFLICT，而 floor 此前**已经推进** —— 缓存就永久卡在
+ *    旧 timestamp，之后每一次 install 都失败。
+ *    ⚠️ 这个 bug 我自己没看出来，是 Codex 2026-09-03 指出的；
+ *    更糟的是我那条「幂等」测试只覆盖了**同内容**的情形，
+ *    等于把错的契约钉死了 —— 断言了错误的契约，所以永远绿。
+ *
+ *    判据：**内容寻址或不可变的用 no-replace，滚动的用替换。**
+ *    · snapshots/<N>.json / .sigstore.json —— N 定了内容就定了，不可变
+ *    · assets/<hex>                        —— 名字就是摘要，不可变
+ *    · timestamp.json                      —— 滚动
+ */
+function promote(from, to, { what, rolling = false }) {
+  const srcDir = dirname(from);
+  if (rolling) {
+    renameSync(from, to);
+    fsyncParentAfter(to);
+    fsyncDir(srcDir);
+    return true;
+  }
+  // 🔴 no-replace 用 `link()` 的 EEXIST，**不是** `existsSync()` + `rename()`。
+  //    后者中间有一条缝：查的时候不在，rename 的时候已经被别人放进去了 ——
+  //    于是我们悄悄覆盖了别人刚写好的字节（TOCTOU，Codex 指出）。
+  //    `link` 在内核里是原子的：要么建成，要么 EEXIST。
+  try {
+    linkSync(from, to);
+  } catch (e) {
+    if (e.code !== 'EEXIST') throw e;
+    const a = readFileSync(to);
+    const b = readFileSync(from);
+    if (!a.equals(b)) {
+      throw new IntegrityError(
+        'E_CACHE_CONFLICT',
+        `${what} 在缓存里已存在，且内容与刚下载的不一致 —— 拒绝覆盖。`
+        + `\n  这两份字节都自称是同一个名字，其中至少一份是错的。`,
+      );
+    }
+    unlinkSync(from);
+    return false;
+  }
+  fsyncParentAfter(to);
+  unlinkSync(from);
+  fsyncDir(srcDir);
+  return true;
+}
+
+// ── 主流程 ─────────────────────────────────────────────────────────────────
+
+/**
+ * 取回 metadata（timestamp + 当前快照），放进 staging。
+ *
+ * 返回 `{ stagingDir, n }`。**一次校验都不做** —— 调用方拿它喂给
+ * `resolveCurrent()`，由后者验签、验新鲜度、推进 floor。
+ *
+ * 🔴 第 2 步的「未验签窥探 N」只决定**下载哪个文件**。若 N 是伪造的，
+ *    第 3 方（resolveCurrent）验不过，staging 整个丢掉，缓存没被碰过。
+ */
+export async function preheatMetadata({
+  cacheDir, fetchImpl, timeoutMs, budget = newBudget(),
+}) {
+  const stagingDir = makeStaging(cacheDir);
+  try {
+    const tsBytes = await spend(budget, (left) => download(timestampUrl(), {
+      host: REGISTRY_HOST, cap: MAX_JSON_BYTES, fetchImpl,
+      timeoutMs: Math.min(timeoutMs ?? Infinity, left), what: 'timestamp.json',
+    }));
+    stage(stagingDir, 'timestamp.json', tsBytes);
+
+    // 🔴 窥探：**只**为了知道下载哪个 N。用严格解析 + 严格整数校验，
+    //    且**只把数值** N 拼进 URL，不把原始 JSON 字符串拼进去。
+    const n = peekLatestSnapshot(tsBytes);
+
+    const [snapBytes, bundleBytes] = [
+      await spend(budget, (left) => download(snapshotUrl(n), {
+        host: REGISTRY_HOST, cap: MAX_JSON_BYTES, fetchImpl,
+        timeoutMs: Math.min(timeoutMs ?? Infinity, left), what: `快照 ${n}`,
+      })),
+      await spend(budget, (left) => download(snapshotBundleUrl(n), {
+        host: REGISTRY_HOST, cap: MAX_JSON_BYTES, fetchImpl,
+        timeoutMs: Math.min(timeoutMs ?? Infinity, left), what: `快照 ${n} 的 bundle`,
+      })),
+    ];
+    stage(stagingDir, join('snapshots', `${n}.json`), snapBytes);
+    stage(stagingDir, join('snapshots', `${n}.sigstore.json`), bundleBytes);
+    return { stagingDir, n };
+  } catch (e) {
+    discard(stagingDir);
+    throw e;
+  }
+}
+
+/**
+ * 从**未验签**的 timestamp 字节里取出 latest_snapshot。
+ *
+ * ⚠️ 名字里的 `peek` 是认真的：这一步的输出**只能**用来决定下载哪个文件。
+ *    任何拿它做判断（「比本地新就…」）的用法都是在信未验签的数据。
+ */
+export function peekLatestSnapshot(tsBytes) {
+  // 🔴 用**同一个** `unwrapTimestamp()` 拆信封，不另写一个解析器。
+  //    我第一版自己写了一份（判断 payload 是字符串就 base64 解）——
+  //    虽然结论碰巧一样，但**两个解析器对同一份字节给出不同答案**本身就是一类洞：
+  //    窥探这一步认了 A，验签那一步认了 B，中间就有一条缝。
+  //    `unwrapTimestamp` 明说它只做形状检查、不做信任判断，正是这里该用的。
+  let inner;
+  try {
+    inner = JSON.parse(unwrapTimestamp(tsBytes).bytes.toString('utf8'));
+  } catch (e) {
+    // 取到一页 HTML（登录墙、错误页、404 页）是**网络/端点**问题。
+    // 报成完整性问题会让人去查签名 —— 方向全错。
+    throw new NetworkError(
+      `timestamp.json 解析不了，取到的字节不像 registry 的响应：${e.message}`,
+    );
+  }
+  return assertSnapshotNumber(inner?.latest_snapshot);
+}
+
+/**
+ * 下载并校验一批资产，落进 `assets/<sha256hex>`。
+ *
+ * 🔴 `records` **必须来自已验签的快照**，不能是调用方随手拼的对象 ——
+ *    否则 `asset.sha256` / `size` / `file` 全是攻击者说了算，
+ *    「校验通过」就只是在和自己对暗号。
+ *
+ * ⚠️ 这里**允许留下孤儿**：单个资产验过就落盘（按摘要命名）。
+ *    整套矩阵下到一半断网时，已经下好的那些下次直接命中 ——
+ *    「全部下完再统一提升」会让每次断网都从头再来。
+ *    孤儿是安全的：文件名就是摘要，读回来还要再验一次。
+ */
+export async function preheatAssets({
+  cacheDir, n, records, fetchImpl, timeoutMs, budget = newBudget(),
+}) {
+  // 🔴 每个把 n 拼进路径或 URL 的入口都要自己校验一次。
+  //    只在 peekLatestSnapshot 里校验是不够的 —— 调用方可以直接调这个函数，
+  //    而一个字符串 n（比如 "../x"）会把路径带出 snapshots/。
+  assertSnapshotNumber(n, 'preheatAssets 的 n');
+  const assetsDir = join(cacheDir, 'assets');
+  mkdirChainFsync(assetsDir);
+  const staging = makeStaging(cacheDir);
+  const got = [];
+  try {
+    for (const rec of records) {
+      // 🔴 **校验在缓存命中之前。** 我原本把 assertAssetFile 放在 existsSync 之后 ——
+      //    于是「已经有同摘要文件」时，一条 asset.file 写错的记录会被**静默放行**
+      //    （Codex 2026-09-03）。闸放在快路径后面 = 快路径上没有闸。
+      assertAssetFile(rec);
+      const hex = String(rec.asset.sha256).replace(/^sha256:/, '');
+      const dest = join(assetsDir, hex);
+      // 🔴 去重**就是**这一句缓存命中，不需要另设一个 seen 集合。
+      //    我原本两样都写了，变异测试当场指出「去掉 seen 没有任何测试变红」——
+      //    因为第一条记录落盘之后，第二条本来就会命中这里。
+      //    而且 seen 那版更差：它 `continue` 时不往 got 里推，报告会少一条记录。
+      if (existsSync(dest)) {
+        // 🔴 缓存命中**不等于**那份字节还是对的。名字是摘要，所以一个
+        //    崩溃留下的截断文件**看起来就像验过了**（Codex 2026-09-03）。
+        //    这里只查大小 —— 完整的摘要复验在 `artifact.assertAssetBytes()`
+        //    里每次安装都会做，在这儿再算一遍大资产的 sha256 是白花钱。
+        //    大小对不上就删掉重下，而不是报错：**这是我们自己的缓存坏了，
+        //    不是分发被投毒** —— 让用户去查签名是把人引向错误的方向。
+        if (statSync(dest).size === rec.asset.size) {
+          got.push({ id: rec.id, cached: true });
+          continue;
+        }
+        unlinkSync(dest);
+      }
+
+      const file = rec.asset.file;
+      // 资产上限按**这一条记录自己声明的 size**，不是一个固定的 8 MiB ——
+      // 固定值会拒掉规格允许的合法资产（Codex 指出）。
+      const bytes = await spend(budget, (left) => download(assetUrl(n, file), {
+        host: REGISTRY_HOST, cap: rec.asset.size, fetchImpl,
+        timeoutMs: Math.min(timeoutMs ?? Infinity, left),
+        what: `资产 ${rec.id}（${file}）`,
+      }), rec.asset.size);
+
+      // ⚠️ 字节数不同 → 摘要必然不同，所以这一条**抓不到摘要抓不到的东西**。
+      //    留着是为了**错误信息**：说「少了 3 个字节」比说「摘要对不上」
+      //    更快指向真正的原因（截断的下载 / 代理插了一段）。
+      //    顺序必须在摘要之前，否则这条永远轮不到。
+      if (bytes.length !== rec.asset.size) {
+        throw new IntegrityError('E_ASSET_SIZE',
+          `资产 ${rec.id} 下回来是 ${bytes.length} 字节，快照说应为 ${rec.asset.size}`);
+      }
+      const actual = sha256Of(bytes);
+      if (actual !== `sha256:${hex}`) {
+        throw new IntegrityError('E_ASSET_DIGEST',
+          `资产 ${rec.id} 的摘要是 ${actual}，快照说应为 sha256:${hex}`);
+      }
+      const tmp = stage(staging, hex, bytes);
+      promote(tmp, dest, { what: `资产 ${rec.id}` });
+      got.push({ id: rec.id, cached: false });
+    }
+    return got;
+  } finally {
+    discard(staging);
+  }
+}
+
+/**
+ * 把 staging 里的 metadata 提升进缓存。
+ *
+ * 🔴 必须在**自己持有 metadata 锁**的临界区内做，并在同一段临界区里
+ *    重读 floor 比对（`assertFloorUnchanged` 的文档明说它自己不是屏障）。
+ *
+ *    不这么做会出这个竞态（Codex 2026-09-03）：
+ *      ① preheat A 验过 v2、推进 floor 到 v2
+ *      ② preheat B 推进到 v3 并落盘
+ *      ③ A 这时才把自己的 v2 提升进 cache
+ *    结果 `cache/timestamp.json = v2` 而 floor 已是 v3 ——
+ *    **之后每一次 install 都必然失败**，且看不出为什么。
+ *
+ * 🔴 提升顺序：snapshots/<N>.json → .sigstore.json → timestamp.json **最后**。
+ *    断电时最多留下「没人引用的孤儿快照」，而不是「timestamp 指向一个
+ *    不存在的 N」—— 后者会让客户端每次都取不到那份快照，
+ *    而它手上的 timestamp 是验过签的，于是像是分发被投毒了。
+ */
+export function promoteMetadata({ cacheDir, stateDir, stagingDir, n, expectedFloor }) {
+  assertSnapshotNumber(n, 'promoteMetadata 的 n');
+  const dir = resolveStateDir(stateDir);
+  const release = acquire(join(dir, METADATA_LOCK), { cli: 'skills-hub preheat' });
+  try {
+    assertFloorUnchanged(dir, expectedFloor);
+    mkdirChainFsync(join(cacheDir, 'snapshots'));
+    promote(join(stagingDir, 'snapshots', `${n}.json`),
+      join(cacheDir, 'snapshots', `${n}.json`), { what: `快照 ${n}` });
+    promote(join(stagingDir, 'snapshots', `${n}.sigstore.json`),
+      join(cacheDir, 'snapshots', `${n}.sigstore.json`), { what: `快照 ${n} 的 bundle` });
+    // 🔴 最后这一个。它是**指针**，指向的东西必须先就位。
+    //    而且它是**滚动**的 —— 用替换语义，不是 no-replace（见 promote 顶部）。
+    promote(join(stagingDir, 'timestamp.json'),
+      join(cacheDir, 'timestamp.json'), { what: 'timestamp.json', rolling: true });
+  } finally {
+    release();
+    discard(stagingDir);
+  }
+}
+
+// ── 预算 ───────────────────────────────────────────────────────────────────
+
+export function newBudget({
+  maxBytes = MAX_TOTAL_BYTES, maxRequests = MAX_REQUESTS, maxMs = MAX_TOTAL_MS, now = Date.now,
+} = {}) {
+  return { bytes: 0, requests: 0, maxBytes, maxRequests, maxMs, deadline: now() + maxMs, now };
+}
+
+/**
+ * 跑一次下载并记账。
+ *
+ * 🔴 **字节要事前预留，不能事后记账**（Codex 2026-09-03 指出）。
+ *    事后检查的话，最后一个资产可以任意大 —— 它已经下完了才发现超限，
+ *    内存和磁盘早就被吃掉了。总量闸的意义正在于「不让它下下来」。
+ *    资产的 size 在快照里写着，所以预留是做得到的。
+ *
+ * 🔴 单次超时也要取**剩余**总时限。否则最后一个请求可以整整越过总 deadline
+ *    再跑满自己的 30 秒。
+ *
+ * @param {number} [reserve] 这次预计的字节数（已知时传，如资产的 asset.size）
+ */
+async function spend(b, fn, reserve = 0) {
+  if (b.requests >= b.maxRequests) {
+    throw new NetworkError(`本次 preheat 的请求数超过上限 ${b.maxRequests}`);
+  }
+  const left = b.deadline - b.now();
+  if (left <= 0) throw new NetworkError(`本次 preheat 超过总时限 ${b.maxMs} ms`);
+  if (b.bytes + reserve > b.maxBytes) {
+    throw new NetworkError(
+      `本次 preheat 的总字节数会超过上限 ${b.maxBytes}（已用 ${b.bytes}，这一份还要 ${reserve}）`,
+    );
+  }
+  b.requests += 1;
+  const out = await fn(left);
+  b.bytes += out.length;
+  // 事前预留之后这一条只可能在 reserve=0（未知大小）的路径上触发
+  if (b.bytes > b.maxBytes) {
+    throw new NetworkError(`本次 preheat 的总字节数超过上限 ${b.maxBytes}`);
+  }
+  return out;
+}
+
+export function discard(stagingDir) {
+  try { rmSync(stagingDir, { recursive: true, force: true }); } catch { /* 尽力而为 */ }
+}