@geoly-ai/skills-hub 0.1.0

package/src/commands/resolve.mjs

@@ -0,0 +1,171 @@
+// 制品 spec 的解析 —— 09-cli.md §5「解析规则」。
+//
+//   1. 含 `@` → 精确版本；否则取 `latest`（非 yank、非 prerelease、**非 degraded**）。
+//   2. 含 `/` → namespace 已定；否则 ①先在 `geoly` 里找 ②全快照找唯一匹配
+//      ③多 namespace 同名 → **报错列候选**，不猜。
+//   3. `pack:` 前缀强制 kind；无前缀且同名同时存在 skill 与 pack → 报错列候选。
+//   4. 目标 pack 的全部版本都 `degraded` → 报「无可安装版本」并列出各版本被哪个成员拖累。
+//
+// 🔴 「不猜」是这条规则的全部意义。任何一处 fallback 都会让同一条命令在不同快照下
+//    装出不同东西，而用户完全看不出来。
+
+import { UsageError, AmbiguousError, ConflictError } from '../exit-codes.mjs';
+import { compareSemver, parseSemver } from '../snapshot.mjs';
+
+export const DEFAULT_NAMESPACE = 'geoly';
+
+const RE_SPEC = /^(?:(skill|pack):)?(?:([a-z0-9][a-z0-9-]*)\/)?([a-z0-9][a-z0-9-]*)(?:@(.+))?$/;
+
+/** 把一条 spec 拆成 `{ kind, namespace, name, version }`，缺席的为 `null`。 */
+export function parseSpec(spec) {
+  if (typeof spec !== 'string' || spec === '') throw new UsageError('制品 spec 不能为空');
+  const m = RE_SPEC.exec(spec);
+  if (!m) {
+    throw new UsageError(
+      `制品 spec 不合 grammar：${spec}\n`
+      + '  形如 `[skill:|pack:][<namespace>/]<name>[@<version>]`，'
+      + 'namespace 与 name 只允许小写字母、数字与连字符。',
+    );
+  }
+  const [, kind, namespace, name, version] = m;
+  if (version !== undefined) parseSemver(version, `spec ${spec} 的版本`);   // 形式非法即拒
+  return { raw: spec, kind: kind ?? null, namespace: namespace ?? null, name, version: version ?? null };
+}
+
+/**
+ * 在快照里解析一条 spec，返回**唯一**的 record。
+ *
+ * @param {object} snap    `parseSnapshot()` 的产物
+ * @param {object} q       `parseSpec()` 的产物
+ * @param {object} o
+ * @param {boolean} o.pre         允许预发布版本
+ * @param {boolean} o.allowYanked 允许装 yanked（🔴 只放行 `yanked`，**绝不放行 `degraded`**，§8.1.1）
+ */
+export function resolveSpec(snap, q, { pre = false, allowYanked = false } = {}) {
+  // ── 规则 2/3：先把候选收窄到「同名」的全部 record ────────────────────────
+  let pool = snap.artifacts.filter((r) => r.name === q.name);
+  if (q.kind) pool = pool.filter((r) => r.kind === q.kind);
+  if (q.namespace) pool = pool.filter((r) => r.namespace === q.namespace);
+  if (pool.length === 0) {
+    throw new UsageError(
+      `快照 ${snap.snapshot} 里找不到 ${q.raw}。`
+      + (q.namespace ? '' : `（未指定 namespace 时先找 ${DEFAULT_NAMESPACE}，再找全快照的唯一匹配）`),
+      { telemetryReason: 'not-found' },
+    );
+  }
+
+  // 规则 3：无 kind 前缀而 skill 与 pack 同名 → 报错列候选
+  if (!q.kind) {
+    const kinds = [...new Set(pool.map((r) => r.kind))].sort();
+    if (kinds.length > 1) {
+      throw new AmbiguousError(
+        `${q.name} 在快照 ${snap.snapshot} 里同时存在 skill 与 pack —— 请加前缀点名：\n`
+        + kinds.map((k) => `  ${k}:${q.name}`).join('\n'),
+        kinds.map((k) => `${k}:${q.name}`),
+      );
+    }
+  }
+
+  // 规则 2：namespace 没定 → ① geoly ② 全快照唯一匹配 ③ 多 namespace 同名报错
+  if (!q.namespace) {
+    const inDefault = pool.filter((r) => r.namespace === DEFAULT_NAMESPACE);
+    if (inDefault.length > 0) pool = inDefault;
+    else {
+      const nss = [...new Set(pool.map((r) => r.namespace))].sort();
+      if (nss.length > 1) {
+        throw new AmbiguousError(
+          `${q.name} 在多个 namespace 下都存在，不猜 —— 请点名其中一个：\n`
+          + nss.map((ns) => `  ${ns}/${q.name}`).join('\n'),
+          nss.map((ns) => `${ns}/${q.name}`),
+        );
+      }
+    }
+  }
+
+  const kind = pool[0].kind;
+  const ns = pool[0].namespace;
+
+  // ── 规则 1：精确版本 ─────────────────────────────────────────────────────
+  if (q.version !== null) {
+    const rec = pool.find((r) => r.version === q.version);
+    if (!rec) {
+      throw new UsageError(
+        `${kind}:${ns}/${q.name}@${q.version} 不在快照 ${snap.snapshot} 里。已有版本：`
+        + pool.map((r) => r.version).sort().join(', '),
+        { telemetryReason: 'not-found' },
+      );
+    }
+    assertInstallable(rec, snap, { allowYanked });
+    return rec;
+  }
+
+  // ── 规则 1：latest ───────────────────────────────────────────────────────
+  // 🔴 snapshot.latest 已经由 `parseSnapshot()` 校验过自洽（非 yank、非 prerelease、
+  //    **非 degraded** 的最高版本）。默认路径直接用它，不自己再算一遍 ——
+  //    自己算就会和快照的 latest 投影分叉。
+  if (!pre) {
+    const key = `${kind}:${ns}/${q.name}`;
+    const v = snap.latest[key];
+    if (v === undefined) {
+      // 规则 4：一个可装版本都没有 —— 说清是被什么挡住的
+      throw noInstallableVersion(kind, ns, q.name, pool, snap);
+    }
+    const rec = pool.find((r) => r.version === v);
+    assertInstallable(rec, snap, { allowYanked });
+    return rec;
+  }
+
+  // `--pre`：把预发布也纳入，仍然排除 yanked 与 degraded
+  const cands = pool.filter((r) => r.status !== 'yanked' && r.status !== 'degraded');
+  if (cands.length === 0) throw noInstallableVersion(kind, ns, q.name, pool, snap);
+  cands.sort((a, b) => compareSemver(a._semver, b._semver));
+  const rec = cands[cands.length - 1];
+  assertInstallable(rec, snap, { allowYanked });
+  return rec;
+}
+
+function noInstallableVersion(kind, ns, name, pool, snap) {
+  const lines = pool
+    .slice()
+    .sort((a, b) => (a.version < b.version ? -1 : 1))
+    .map((r) => {
+      if (r.status !== 'degraded') return `  ${r.version} —— status=${r.status}`;
+      // 规则 4：列出**各版本被哪个成员拖累**。degraded 是 pack 的状态，
+      // 成员信息在 pack 的载荷里而不在快照 record 里 —— 快照能给的只有
+      // 「该 pack 版本被标记为 degraded」。🔴 如实说清楚这一点，不要假装知道成员名。
+      return `  ${r.version} —— degraded（被某个已 yank 的成员拖累；成员清单在 pack 载荷里，`
+        + `快照 record 不携带，需取回该 pack 后才能列出）`;
+    });
+  return new ConflictError(
+    `${kind}:${ns}/${name} 在快照 ${snap.snapshot} 里没有可安装版本：\n${lines.join('\n')}\n`
+    + '🔴 --allow-yanked 只放行 yanked，**绝不放行 degraded**（04-install.md §8.1.1）。'
+    + '要装就自己按成员逐个装。',
+    { telemetryReason: 'version-conflict' },
+  );
+}
+
+/** 状态门。🔴 `--allow-yanked` 只放行 `yanked` 一种（§8.1.1）。 */
+export function assertInstallable(rec, snap, { allowYanked = false } = {}) {
+  if (rec.status === 'degraded') {
+    throw new ConflictError(
+      `${rec.id} 的状态是 degraded（某个成员被 yank）。`
+      + '🔴 --allow-yanked **不放行 degraded**（04-install.md §8.1.1）——'
+      + '它是针对具体制品的知情豁免，而 degraded 会连带装一个你没有豁免过的成员。'
+      + '要装请按成员逐个装。',
+      { telemetryReason: 'version-conflict' },
+    );
+  }
+  if (rec.status === 'yanked') {
+    if (!allowYanked) {
+      const y = snap.yanked.find((x) => x.id === rec.id);
+      throw new ConflictError(
+        `${rec.id} 已被 yank：${y?.reason ?? '（快照未给原因）'}`
+        + (y?.advisory ? `\n  advisory：${y.advisory}` : '')
+        + (y?.superseded_by ? `\n  已被 ${y.superseded_by} 取代` : '')
+        + '\n  要取证安装请显式给 --allow-yanked（会大声告警并写进账本）。',
+        { telemetryReason: 'yanked' },
+      );
+    }
+  }
+  return rec;
+}

package/src/commands/snapshot-access.mjs

@@ -0,0 +1,91 @@
+// 快照取用 —— 02-registry.md §6（解析当前）与 §6.1（历史读取路径）在命令面的入口。
+//
+// 🔴 **这是两条不同的路径，不能混用**：
+//   · `resolveCurrent()`：回答「现在最新的是哪张快照」，会**推进 trust floor**，
+//     并且「N 小于本地 floor 即拒绝」。metadata 锁在 `advanceTrustFloor()` 内部起落 ——
+//     🔴 命令面**不得**再包一层 metadata 锁（`src/lock.mjs` 禁止重入，会当场抛）。
+//   · `readHistoricalSnapshot()`：**只读**。可用于 `--snapshot <N>` 复现、
+//     `check` 的第一问、lockfile 闭包重解析。
+//     ❌ 不得用它回答「现在还能不能用」—— 那必须查当前快照。
+
+import { existsSync } from 'node:fs';
+import { mkdirChainFsync } from '../atomic-fs.mjs';
+import { resolveCurrent, readHistoricalSnapshot } from '../snapshot.mjs';
+import { readTrustFloor } from '../trust.mjs';
+import { realVerifier } from './context.mjs';
+import { EXIT, classify } from '../exit-codes.mjs';
+
+export async function getVerifier(ctx) {
+  // 🔴 验签没有逃生口。`ctx.verifier` 只有 `main(argv, deps)` 的调用方给得了；
+  //    生产入口一个 dep 都不传，因此这里落到真验签器（内置信任根）。
+  return ctx.verifier ?? realVerifier();
+}
+
+/**
+ * @returns {{snapshot:object, stale:boolean, floor:object|null, pinned:boolean, verifier:Function}}
+ */
+export async function resolveSnapshotForCommand(ctx) {
+  const verifier = await getVerifier(ctx);
+
+  if (ctx.snapshot !== null) {
+    // `--snapshot <N>`：钉快照复现。走 §6.1 的**只读**路径，**不推进 floor**。
+    const { bytes, bundle } = ctx.registry.fetchSnapshot(ctx.snapshot);
+    const { snapshot } = readHistoricalSnapshot({
+      bytes, bundle, verifier, expectSnapshot: ctx.snapshot,
+    });
+    // 🔴 R-9 的 floor 复验仍然要做：钉快照不代表可以放弃「安装期间 floor 没被推进」
+    //    这条检查。取磁盘上当前的 floor 当期望值；还没 bootstrap 就显式 null
+    //    （`assertFloorBarrier` 要求**显式**给出，忘了传是拒绝、不是跳过）。
+    // 🔴 **这条路径只读，不建目录**：`--snapshot` / `check` 的第一问都走它，
+    //    让一次只读查询顺手建出全局状态目录，与「历史读取路径只读」自相矛盾。
+    let floor = null;
+    if (existsSync(ctx.stateDir)) floor = readTrustFloor(ctx.stateDir);
+    return { snapshot, stale: false, floor, pinned: true, verifier };
+  }
+
+  // 只有「解析当前」这条路径会**推进 floor**，也只有它需要状态目录存在
+  mkdirChainFsync(ctx.stateDir);      // resolveStateDir 要 realpath 它
+  const r = resolveCurrent({
+    stateDir: ctx.stateDir,
+    fetchTimestamp: () => ctx.registry.fetchTimestamp(),
+    fetchSnapshot: (n) => ctx.registry.fetchSnapshot(n),
+    verifier,
+    cliVersion: ctx.cliVersion,
+    now: ctx.now().getTime(),
+    offline: ctx.offline,
+    allowStale: ctx.allowStale,
+  });
+  return { snapshot: r.snapshot, stale: r.stale === true, floor: r.floor, pinned: false, verifier };
+}
+
+/**
+ * 历史快照的 memo 读取器（`check` / `sync-lock` / lockfile 闭包共用）。
+ * 🔴 每一份都**独立验签**（identity = release.yml）——命中缓存只省网络，不省校验。
+ */
+/**
+ * 🔴 只读命令（`list` / `check`）在取不到当前快照时可以**降级并如实标注**，
+ *    但**只有「取不到」这一种**可以降级。
+ *
+ * 早先 `list` / `check` 是 `try { … } catch { 标 offline 继续 }` ——
+ * 那会把这三类一起吞掉，而它们各自在 §6 里有自己的格子：
+ *   · `StaleError`（8）：timestamp 过期且未给 `--allow-stale`。吞掉它 = CI 拿着
+ *     一张过期的信任根照常绿灯，正是 `--allow-stale` 存在的理由被绕过；
+ *   · `IntegrityError` / `TarViolation`（2）：验签失败、摘要不符、抗回滚命中；
+ *   · `MinCliVersionError`（11）。
+ *
+ * 判据是**退出码分类**，不是错误文案：只有落在 `NETWORK`（6）那一格的才可降级。
+ */
+export function isDegradable(err) {
+  return classify(err).code === EXIT.NETWORK;
+}
+
+export function historicalReader(ctx, verifier) {
+  const memo = new Map();
+  return function read(n) {
+    if (memo.has(n)) return memo.get(n);
+    const { bytes, bundle } = ctx.registry.fetchSnapshot(n);
+    const { snapshot } = readHistoricalSnapshot({ bytes, bundle, verifier, expectSnapshot: n });
+    memo.set(n, snapshot);
+    return snapshot;
+  };
+}

package/src/commands/sync-lock.mjs

@@ -0,0 +1,189 @@
+// `sync-lock` —— 在 repo 锁下**幂等重算**并原子写 `geoly-skills.lock.json`（04-install.md §8.1）。
+//
+// 🔴 也是 `install` / `recover` 收尾时那个 `onLedgerChanged` 钩子的实现：
+//    §5.1 末尾要求 install / update / remove / **recover** 成功之后都要在 repo 锁下重算。
+//    钩子被调用时 repo 锁**已经由命令层持着** —— 所以本模块**不自己取 repo 锁**
+//    （`src/lock.mjs` 禁止重入，取第二次会当场抛）。取锁是调用方的事。
+//
+// 🔴 「任一项目级 target 处于未恢复事务中 → **拒绝重算**并要求先 recover」（§8.1）。
+
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { planTargets, assertPlanOk } from '../adapters/index.mjs';
+import { layout, readLedger } from '../ledger.mjs';
+import { listJournalGenerations, readJournal } from '../journal.mjs';
+import { projectLockfile, writeLockfile } from '../lockfile.mjs';
+import { REPO } from '../trust.mjs';
+import { withOrderedLocks } from './locks.mjs';
+import { getVerifier, historicalReader, resolveSnapshotForCommand } from './snapshot-access.mjs';
+import { UsageError, EXIT, NetworkError } from '../exit-codes.mjs';
+import { annotations } from './output.mjs';
+
+export const LOCKFILE_NAME = 'geoly-skills.lock.json';
+
+/** §8.1：有未恢复事务就拒绝重算。 */
+export function assertNoUnrecoveredTx(target) {
+  const P = layout(target);
+  if (!existsSync(P.state)) return;
+  if (existsSync(P.repairIntent)) {
+    throw new UsageError(
+      `${target} 存在未完成的 repair intent：请先跑 \`skills-hub recover --reinstall\`，再重算 lockfile。`,
+      { exitCode: EXIT.NEEDS_RECOVER },
+    );
+  }
+  for (const g of listJournalGenerations(P.journalDir)) {
+    const J = readJournal(layout(target, g).journal);
+    if (J.phase !== 'completed') {
+      const e = new UsageError(
+        `${target} 的第 ${g} 代事务停在 ${J.phase}：lockfile **拒绝重算**（04-install.md §8.1）。\n`
+        + '  请先 `skills-hub recover --continue` 或 `--rollback`。',
+      );
+      e.exitCode = EXIT.NEEDS_RECOVER;
+      throw e;
+    }
+  }
+}
+
+/**
+ * 从**已验签的**快照里取 entry 的 `asset_sha256`。
+ *
+ * 🔴 账本里没有这个字段（它是本机运行历史之外的东西），只能回快照取。
+ *    取不到就**失败**，绝不填一个占位值 —— lockfile 是别的机器的权威输入。
+ */
+function assetSha256For(artifactId, entrySnapshot, { current, readHistorical }) {
+  const fromCurrent = current?.artifacts.find((r) => r.id === artifactId);
+  if (fromCurrent) return fromCurrent.asset.sha256;
+  const snap = readHistorical(entrySnapshot);
+  const rec = snap.artifacts.find((r) => r.id === artifactId);
+  if (!rec) {
+    throw new NetworkError(
+      `快照 ${entrySnapshot} 里找不到 ${artifactId}，无法取它的 asset_sha256 —— lockfile 拒绝重算。`,
+      { telemetryReason: 'not-found' },
+    );
+  }
+  return rec.asset.sha256;
+}
+
+/**
+ * 重算（不取锁）。返回 `{ path, lockfile, targets }`；没有任何项目级 target 时返回 `null`。
+ *
+ * @param {object} o.current        当前快照（可为 null；那时逐个回历史快照取）
+ * @param {(n:number)=>object} o.readHistorical
+ */
+export function recalcLockfile(ctx, { current = null, readHistorical, inFlightTarget = null }) {
+  if (ctx.scope !== 'project') return null;
+  const tplan = planTargets({
+    clients: ctx.clients,
+    scope: 'project',
+    home: ctx.home,
+    env: ctx.env,
+    projectRoot: ctx.projectRoot,
+  });
+  assertPlanOk(tplan);
+
+  const targets = [];
+  for (const t of tplan.selected) {
+    const P = layout(t.target);
+    if (!existsSync(P.ledger)) continue;
+    // 🔴 口子只对**正在收尾的那一个 target** 开，不是对整次重算开。
+    //    §8.1 那条「有未恢复事务就拒绝重算」防的是**旁观者**拿中间态去投影；
+    //    而钩子是由事务本身在账本已经写定之后调的（rollback 的 `finalizeRollback()`
+    //    第 ③ 步就在第 ⑤ 步把 phase 置成 completed 之前）——
+    //    它对**自己**的 journal 有权威，对**别的** target 没有。
+    //    早先这里是一个整次生效的 `allowInFlight`，多 target recover 时会把
+    //    另一个 target 的中间态一起投影进 lockfile（Codex 第三轮 P0-2）。
+    if (t.target !== inFlightTarget) assertNoUnrecoveredTx(t.target);
+    const L = readLedger(P.ledger);
+    if (Object.keys(L.entries).length === 0 && Object.keys(L.roots).length === 0) continue;
+    const assetSha256 = {};
+    for (const [name, e] of Object.entries(L.entries)) {
+      assetSha256[name] = assetSha256For(e.artifact, e.snapshot, { current, readHistorical });
+    }
+    targets.push({
+      client: t.client,
+      scope: 'project',
+      // 🔴 `path` **只能由 adapter 推导**（§8.1 的闭合验证要求），仓库内相对路径
+      path: `${t.adapter.dirName}/skills`,
+      ledger: L,
+      assetSha256,
+    });
+  }
+  const lf = projectLockfile({ registry: REPO, targets });
+  const path = join(ctx.projectRoot, LOCKFILE_NAME);
+  writeLockfile(path, lf);
+  return { path, lockfile: lf, targets: targets.map((t) => t.path) };
+}
+
+/**
+ * 造 `onLedgerChanged` 钩子。
+ *
+ * 🔴 **入口就查**：`install.assertLockfileHook()` 在 `runTransaction` 的**第一行**
+ *    就要求项目级 target 必须注入它 —— 缺了要在「放弃还免费」的时候报，
+ *    而不是等事务提交完、journal 都删了才炸。
+ *
+ * ⚠️ **已知非原子路径（R-11 第四条）**：`runCleanup()` 先清 tx 与 journal，
+ *    **最后**才调本钩子。钩子抛错时 ledger 已提交、project lockfile 可能陈旧，
+ *    而 recover 已经没有 journal 可重试。兜底是：`check` 会报「lockfile 过时」，
+ *    用户跑 `sync-lock` 补。**这是已知缺口，不是被闭合了。**
+ */
+export function makeLockfileHook(ctx, { snap = null, verifier = null } = {}) {
+  if (ctx.scope !== 'project') return undefined;
+  // 🔴 `runLockfileRecalc(target, P, opts)` 会把**当前 target** 传进来 ——
+  //    口子就窄化在这个参数上。
+  return function onLedgerChanged(inFlightTarget = null) {
+    // 🔴 历史快照读取器**每次现造**：memo 缓在钩子外面会让一次长跑里的
+    //    「快照被换掉」看不见。它只省重复解析，不省任何一次验签。
+    const readHistorical = verifier === null
+      ? (n) => {
+        throw new NetworkError(
+          `重算 lockfile 需要快照 ${n} 里的 asset_sha256，但本次运行没有可用的验签器。`
+          + '请跑 `skills-hub sync-lock` 补齐。',
+          { telemetryReason: 'not-found' },
+        );
+      }
+      : historicalReader(ctx, verifier);
+    recalcLockfile(ctx, { current: snap, inFlightTarget, readHistorical });
+  };
+}
+
+export async function cmdSyncLock(ctx, argv, out) {
+  for (const a of argv) throw new UsageError(`sync-lock 不认得参数 ${a}`);
+  if (ctx.scope !== 'project') {
+    throw new UsageError('sync-lock 只对项目级安装有意义：请加 `--project [path]`（04-install.md §8）。');
+  }
+  const verifier = await getVerifier(ctx);
+  const readHistorical = historicalReader(ctx, verifier);
+  // 当前快照能拿到就拿（省去逐条回历史快照）；拿不到不是错 —— 历史路径仍然可用
+  let current = null;
+  try { current = (await resolveSnapshotForCommand(ctx)).snapshot; } catch { current = null; }
+
+  let result = null;
+  withOrderedLocks({ projectRoot: ctx.projectRoot, targets: [] }, () => {
+    result = recalcLockfile(ctx, { current, readHistorical });
+  });
+
+  // 🔴 埋点在**收尾处**，不在事务关键路径上；`record()` 自己不抛。
+  //    `kind` 取 KINDS 里现成的 `sync-lock`。
+  if (ctx.record) ctx.record({ kind: 'sync-lock', result: 'ok', scope: 'project' });
+
+  if (result === null) {
+    out.line('没有可投影的项目级 target（没有账本）。');
+    return out.emit('sync-lock', { lockfile: null, targets: [] }, EXIT.OK);
+  }
+  out.line(`已重算 ${result.path}`);
+  for (const t of result.lockfile.targets) {
+    out.line(`  ${t.client}/${t.scope}  ${t.path}  roots=${t.roots.length}  entries=${t.entries.length}`);
+  }
+  return out.emit('sync-lock', {
+    lockfile: result.path,
+    targets: result.lockfile.targets.map((t) => ({
+      // 🔴 标注挂在每一个 target 对象上（§7）
+      annotations: annotations({ offline: ctx.offline }),
+      client: t.client,
+      entries: t.entries.length,
+      path: t.path,
+      roots: t.roots.length,
+      scope: t.scope,
+    })),
+  }, EXIT.OK);
+}

package/src/crc32c.mjs

@@ -0,0 +1,27 @@
+// crc32c（Castagnoli）—— journal 自校验用，规范见 11-wire-contract.md §5。
+//
+// 🔴 覆盖范围由调用方给：§11 §5 说的是「**去掉 `crc32c` 这一个 key 之后**该对象的
+//    canonical 字节（含结尾换行）」。本模块只管算，不管取哪些字节 ——
+//    把「取哪些字节」写进这里会让它在别处（例如 audit archive）被误用。
+//
+// 这份实现原先躺在 test/harness/crc32c.mjs 里（框架先于内核落地）。搬到 src/ 之后
+// 两份必须逐字节等价，test/crc32c.test.mjs 有一条测试把它们钉在一起。
+
+const POLY = 0x82f63b78; // 反射多项式
+const TABLE = new Uint32Array(256);
+for (let i = 0; i < 256; i++) {
+  let c = i;
+  for (let k = 0; k < 8; k++) c = c & 1 ? (c >>> 1) ^ POLY : c >>> 1;
+  TABLE[i] = c >>> 0;
+}
+
+export function crc32c(buf) {
+  let c = 0xffffffff;
+  for (let i = 0; i < buf.length; i++) c = TABLE[(c ^ buf[i]) & 0xff] ^ (c >>> 8);
+  return (c ^ 0xffffffff) >>> 0;
+}
+
+/** §11 §5：小写 hex，**8 个字符，固定宽度补零** */
+export function crc32cHex(buf) {
+  return crc32c(buf).toString(16).padStart(8, '0');
+}