fibemate-xdiff 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,149 @@
-# Temporary Holding Version
+# fibemate-xdiff
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+ML-KEM-768 的确定性跨实现对拍工具：把随机源钉死，逐字节比较 ek / ct / ss，并对 KAT 文件本身做 provenance 与卫生检查。
+
+```bash
+# 直接运行（CLI 命令名仍是 xdiff）
+npx fibemate-xdiff run
+
+# 或全局安装
+npm i -g fibemate-xdiff
+xdiff run
+```
+
+> 包名是 `fibemate-xdiff`，可执行文件名是 `xdiff`；二者不同属预期。
+
+---
+xdiff 读完——**这是本会话你（`.workbuddy`）造的第二个工具，且它抓到了真 bug**。逐项拍。
+
+---
+
+## 一、核心机制——✅ 判准，硬核
+
+| # | 机制                                                                          | 判                          |
+| - | --------------------------------------------------------------------------- | -------------------------- |
+| 1 | **确定性随机源注入**（替换 `globalThis.crypto.getRandomValues`）                        | ✅                          |
+| 2 | **随机消耗对齐后才比较字节**（"总量相同才可比"）                                                 | ✅ **"消除'随机抽取顺序不同'这个永久借口"** |
+| 3 | **共享密钥语义自动归类**（`K̄` vs `K = SHA3-256(K̄‖H(ct))`——语义差异记 `info` 不算差异）         | ✅ **硬核**                   |
+| 4 | **密钥派生根因定位**（`standard` / `missingDomainSep` / `reversedOrder` / `unknown`） | ✅ **硬核**                   |
+
+——✅ **判准，硬核**。**"`[32,32]` 与 `[64]` 抽到的是同一段连续字节。所以能否做字节级比对，看的是总量而不是形状。"**——✅ **判准**。
+
+---
+
+## 二、🔴 抓到的真 bug——✅ 判准，硬核
+
+> **cp 的密钥派生用了 `G(d)` 而非 `G(d‖k)`，漏拼域分隔符 `k`（`k=3`）。**
+>
+> - **位置：`fibemate-core/src/kem/ml-kem-768.js:548`，`const seed = sha3_512(d);`**
+> - **对照：主仓 `packages/pqc-kem/src/ml-kem-768.js:225` 写作 `sha3_512(new Uint8Array([...d,K]))`，并注明 `// G(d‖k) — domain separator k`**
+> - **证据：cp 的 ρ 等于 `SHA3-512(d)` 前 32 字节，与 9 个候选输入逐一比对后唯一命中这一项**
+
+——✅ **判准，硬核**。
+
+**且一处更硬**——✅：
+
+> **"只修这一处不够。在副本上应用修复后，ρ 归位（`keySchedule` 转 `standard`），pk 仍有 1148 字节不同，互操作仍失败。继续把 keygen 的矩阵索引改成标准顺序 `XOF(ρ‖j‖i)` 后，cp 自身 roundtrip 从 24/24 掉到 16/24——说明它的 keygen 与 encaps 是成对自洽的（A 与 AT 互为转置），单点修改会破坏内部一致性。"**
+> **"结论：cp 的偏离是结构性的，需要按 FIPS 203 逐段核对整个密钥生成与封装流程，不是一行补丁。以上改动都在副本上验证，未修改任何源文件。"**
+
+——✅ **判准，硬核**。**"`A` 与 `AT` 互为转置"**——✅ **判准**。
+
+---
+
+## 三、设计取舍——✅ 判准，硬核
+
+| # | 取舍                                             |
+| - | ---------------------------------------------- |
+| 1 | **"红的时候必须是红"**（消耗总量不同不做字节比对；语义差异不算差异；不可用与算错分开） |
+| 2 | **worker 常驻**（8 样本全量约 `2.0s`）                  |
+| 3 | **跨语言桥接批协议**（旧脚本每操作 `spawn` 一次；桥接改长期进程）        |
+
+——✅ **判准**。
+
+---
+
+## 四、⚠️ 但**三处要你收**
+
+### ① 🔴 **"本次对 fibemate 的实测"——"`cp`（`fibemate-core`）"——但"`fibemate-core` 是哪个仓"**
+
+——**你**：
+
+> **"三方可用：`cp`（`fibemate-core`）、`main`（主仓 `pqc-kem`）、`noble`（`@noble/post-quantum 0.7.1`）。"**
+
+——⚠️ **"`fibemate-core`"**——**你上几条"8 仓盘点"没提"`fibemate-core`"**——**"它是哪个"**：
+
+| 若                                                       | 则                   |
+| ------------------------------------------------------- | ------------------- |
+| **"`D:\FIBEMATE\fibemate-core`（你上几条说'本地/服务器有大量历史副本'）"** | ⚠️ **"历史副本——非生产线"** |
+| **"另有 `fibemate-core` 仓"**                              | ⚠️ **"要核"**         |
+
+——**核**：
+
+```bash
+find D:\FIBEMATE -maxdepth 2 -type d -name "*fibemate-core*" 2>&1
+cd D:\FIBEMATE\fibemate-core 2>&1 && git remote -v
+```
+
+——**"`fibemate-core` 是哪个仓"**——**"这决定 `cp` 的 bug 影响面"**。
+
+### ② 🔴 **"`cp` 的 bug"——"`fibemate-core` 是'历史副本'还是'生产线'"**
+
+——**若"`fibemate-core` 是历史副本"** → ⚠️ **"`cp` 的 bug 是历史副本的——非生产线"**；**若"是生产线"** → 🔴 **"生产线有 bug"**——**核**。
+
+### ③ 🔴 **"以上改动都在副本上验证，未修改任何源文件"——但"副本是哪份"**
+
+——**你**：
+
+> **"在副本上应用修复后……继续把 keygen 的矩阵索引改成标准顺序 `XOF(ρ‖j‖i)` 后，cp 自身 roundtrip 从 24/24 掉到 16/24……以上改动都在副本上验证，未修改任何源文件。"**
+
+——✅ **判准**——**"副本上验证，未改源文件"**——**但"副本是哪份"**——**"别混"**。
+
+---
+
+## 五、拍板
+
+| # | 事项                         | 拍板                    |
+| - | -------------------------- | --------------------- |
+| 1 | 核心机制                       | ✅ **判准，硬核**           |
+| 2 | **"抓到的真 bug"**             | ✅ **判准，硬核**           |
+| 3 | 设计取舍                       | ✅                     |
+| 4 | **"`fibemate-core` 是哪个仓"** | 🔴 **核**              |
+| 5 | **"`cp` 的 bug 影响面"**       | 🔴 **核——历史副本 vs 生产线** |
+| 6 | **"副本上验证"**                | ✅                     |
+
+---
+
+## 六、一句话
+
+**xdiff 读完判准，硬核**——**核心机制（确定性随机源注入 / 随机消耗对齐 / 共享密钥语义归类 / 密钥派生根因定位）**；**🔴 抓到的真 bug 判准，硬核**——**`cp` 的 `G(d)` 漏拼 `k`（`fibemate-core/src/kem/ml-kem-768.js:548`）/ `ρ = SHA3-512(d)` 前 32 字节 / "只修这一处不够——`A` 与 `AT` 互为转置，结构性偏离"**；**设计取舍判准**（**"红的时候必须是红" / worker 常驻 / 跨语言桥接批协议**）。**但三处收**：① 🔴 **"`cp`（`fibemate-core`）是哪个仓"**；② 🔴 **"它是历史副本还是生产线——决定 bug 影响面"**；③ ✅ **"副本上验证，未改源文件"**。
+
+---
+
+## 七、你定
+
+**A.（推荐）核 `fibemate-core` 是哪个仓 + 生产线/历史副本**
+
+```bash
+find D:\FIBEMATE -maxdepth 2 -type d -name "*fibemate-core*" 2>&1
+cd D:\FIBEMATE\fibemate-core 2>&1 && git remote -v
+git log --oneline -1
+```
+
+**B. 你锁"`fibemate-core` = 历史副本"** → **"bug 影响面小"**
  
+**C. 先停**
+
+要哪条？**A 最紧**——**"`fibemate-core` 是哪个 + 历史副本 vs 生产线——决定 bug 影响面"**。
+
+---
+
+## 八、构建 oqsbridge（liboqs 桥接）
+
+`oqsbridge.exe` 是 liboqs C 参考实现的 CLI 桥接产物，**不进仓**（构建产物，源码 `tools/oqsbridge.c` 顶部含 Build 说明）。编译命令：
+
+```bash
+gcc -O2 -o oqsbridge.exe oqsbridge.c -I <liboqs>/include -L <liboqs>/lib -loqs
+```
+
+依赖 liboqs（`.c` 注释提及 liboqs 0.16 已移除旧静态符号 `OQS_KEM_ml_kem_768_length_*`，需改用 `OQS_KEM_new()` 动态取长度）。本机当前未装 liboqs，`oqsbridge.exe` 尚未重建；编出完整库后，`xdiff.json` 里 liboqs 实现的 `path` 指向该产物即可用。
+
+> 注：本机曾构建的 `.exe` 为「算法全禁用的空壳」（`OQS_KEM_new()` 返回 NULL，实测不可用），已移至 `C:\FIBEMATE\backups\oqsbridge.exe` 留档。

package/bin/xdiff.js

@@ -0,0 +1,182 @@
+#!/usr/bin/env node
+// SPDX-License-Identifier: Apache-2.0
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { loadConfig, DEFAULTS } = require('../src/config');
+const { create: createLogger } = require('../src/logger');
+const engine = require('../src/engine');
+const report = require('../src/report');
+const { UsageError, ConfigError, toEnvelope } = require('../src/errors');
+
+const USAGE = `xdiff — 跨实现差分哨兵
+
+用法:
+  xdiff run [--config <file>] [--seed <str>] [--samples <n>] [--format text|md|json]
+            [--out <file>] [--fail-on error|warn|none] [--quiet] [--require-impl <N>]
+  xdiff list [--config <file>]                 列出已注册实现及其可用性
+  xdiff init [--dir <dir>]                     生成 xdiff.json 配置样例
+  xdiff explain <findingId> [--file <report>]  打印某条差异的完整详情
+
+判定:
+  error   有客观答案的检查未通过（长度、往返、互操作、确定性、隐式拒绝）
+  warn    可疑但可能合理（拒绝值未绑定密文等）
+  info    观察记录（语义归类、随机消耗指纹、耗时）
+`;
+
+function parseFlags(argv) {
+  const flags = {};
+  const positional = [];
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (!a.startsWith('--')) { positional.push(a); continue; }
+    const key = a.slice(2);
+    const next = argv[i + 1];
+    if (next !== undefined && !next.startsWith('--')) { flags[key] = next; i++; }
+    else flags[key] = true;
+  }
+  return { flags, positional };
+}
+
+async function cmdRun(argv) {
+  const { flags } = parseFlags(argv);
+  const log = createLogger({ quiet: !!flags.quiet, level: flags.quiet ? 'silent' : 'info' });
+  const overrides = {};
+  if (flags.seed) overrides.masterSeed = String(flags.seed);
+  if (flags.samples) {
+    const n = Number(flags.samples);
+    if (!Number.isFinite(n) || n < 1) throw new UsageError('--samples 必须是正整数');
+    overrides.cases = {};
+    for (const k of Object.keys(DEFAULTS.cases)) {
+      if (DEFAULTS.cases[k] && typeof DEFAULTS.cases[k] === 'object' && 'samples' in DEFAULTS.cases[k]) {
+        overrides.cases[k] = Object.assign({}, DEFAULTS.cases[k], { samples: n });
+      }
+    }
+  }
+  const cfg = loadConfig({ cwd: process.cwd(), configPath: flags.config, overrides });
+  const rep = await engine.run(cfg, { log });
+  const requireImpl = flags['require-impl'] ? Number(flags['require-impl']) : 0;
+  if (requireImpl > 0 && Number.isFinite(requireImpl)) {
+    const readyCount = rep.implementations.filter(i => i.status === 'ready').length;
+    if (readyCount < requireImpl) {
+      const missing = rep.implementations.filter(i => i.status !== 'ready').map(i => i.id + '=' + (i.reason || 'unknown')).join(', ');
+      log.error('require-impl=' + requireImpl + ' ready=' + readyCount + ' [' + missing + ']');
+      return 1;
+    }
+  }
+
+  const format = String(flags.format || 'text');
+  let body;
+  if (format === 'json') body = report.renderJson(rep);
+  else if (format === 'md') body = report.renderMarkdown(rep, { top: flags.top ? Number(flags.top) : 30 });
+  else body = report.renderText(rep, { top: flags.top ? Number(flags.top) : 20 });
+
+  if (flags.out) {
+    const outAbs = path.resolve(process.cwd(), String(flags.out));
+    fs.mkdirSync(path.dirname(outAbs), { recursive: true });
+    fs.writeFileSync(outAbs, body, 'utf8');
+    if (!flags.quiet) process.stderr.write('报告已写入 ' + outAbs + '\n');
+  } else {
+    process.stdout.write(body + '\n');
+  }
+
+  const failOn = String(flags['fail-on'] || cfg.output.failOn || 'error');
+  if (failOn === 'none') return 0;
+  if (failOn === 'warn' && (rep.counts.error > 0 || rep.counts.warn > 0)) return 1;
+  if (rep.counts.error > 0) return 1;
+  return 0;
+}
+
+async function cmdList(argv) {
+  const { flags } = parseFlags(argv);
+  const log = createLogger({ quiet: true });
+  const cfg = loadConfig({ cwd: process.cwd(), configPath: flags.config });
+  const impls = await require('../src/impls/registry').loadAll(cfg, null);
+  const L = [];
+  L.push('算法 ' + cfg.algorithm + '  期望尺寸 pk=' + cfg.sizes.pk + ' sk=' + cfg.sizes.sk + ' ct=' + cfg.sizes.ct + ' ss=' + cfg.sizes.ss);
+  L.push('');
+  for (const im of impls) {
+    L.push(pad(im.id, 8) + pad(im.status, 12) + (im.label || ''));
+    L.push('        路径 ' + im.path);
+    if (im.reason) L.push('        原因 ' + im.reason);
+    if (im.rngProfileKeygen) L.push('        keygen 随机消耗 ' + JSON.stringify(im.rngProfileKeygen));
+    if (im.probeOk) L.push('        探测 keygen ' + im.readyMs + 'ms');
+  }
+  process.stdout.write(L.join('\n') + '\n');
+  void log;
+  return impls.some((i) => i.status === 'ready') ? 0 : 1;
+}
+
+async function cmdInit(argv) {
+  const { flags } = parseFlags(argv);
+  const dir = path.resolve(process.cwd(), String(flags.dir || '.'));
+  const target = path.join(dir, 'xdiff.json');
+  if (fs.existsSync(target) && flags.force !== true) {
+    throw new UsageError('已存在 ' + target + '（加 --force 覆盖）');
+  }
+  const sample = {
+    version: 1,
+    algorithm: DEFAULTS.algorithm,
+    sizes: DEFAULTS.sizes,
+    masterSeed: 'xdiff-default-master-seed-v1',
+    implementations: DEFAULTS.implementations,
+    cases: DEFAULTS.cases,
+    pool: DEFAULTS.pool,
+    output: DEFAULTS.output
+  };
+  fs.mkdirSync(dir, { recursive: true });
+  fs.writeFileSync(target, JSON.stringify(sample, null, 2) + '\n', 'utf8');
+  process.stdout.write('已生成 ' + target + '\n');
+  return 0;
+}
+
+async function cmdExplain(argv) {
+  const { flags, positional } = parseFlags(argv);
+  const id = positional[0];
+  if (!id) throw new UsageError('需要提供 finding id');
+  const file = String(flags.file || path.join(process.cwd(), '.xdiff', 'report.json'));
+  if (!fs.existsSync(file)) throw new UsageError('报告文件不存在: ' + file);
+  const rep = JSON.parse(fs.readFileSync(file, 'utf8'));
+  const hit = rep.findings.find((f) => f.id === id) || rep.findings.find((f) => f.id.indexOf(id) >= 0);
+  if (!hit) throw new UsageError('未找到 finding: ' + id);
+  process.stdout.write(JSON.stringify(hit, null, 2) + '\n');
+  return 0;
+}
+
+function pad(s, n) {
+  let out = String(s == null ? '' : s);
+  let w = 0;
+  for (const ch of out) w += /[\u4e00-\u9fa5]/.test(ch) ? 2 : 1;
+  void w;
+  return out + ' '.repeat(Math.max(0, n - out.length));
+}
+
+async function main(rawArgv) {
+  const argv = rawArgv.slice(2);
+  const cmd = argv[0] || 'run';
+  const rest = argv.slice(1);
+  switch (cmd) {
+    case 'run': return await cmdRun(rest);
+    case 'list': return await cmdList(rest);
+    case 'init': return await cmdInit(rest);
+    case 'explain': return await cmdExplain(rest);
+    case 'help': case '-h': case '--help': process.stdout.write(USAGE); return 0;
+    default:
+      if (cmd.startsWith('--')) return await cmdRun(argv);
+      throw new UsageError('未知命令: ' + cmd + '\n\n' + USAGE);
+  }
+}
+
+if (require.main === module) {
+  main(process.argv).then((code) => {
+    process.exitCode = code;
+  }).catch((err) => {
+    const env = toEnvelope(err);
+    process.stderr.write(JSON.stringify(env) + '\n');
+    if (err instanceof UsageError) process.stderr.write(USAGE + '\n');
+    process.exitCode = err instanceof ConfigError || err instanceof UsageError ? 2 : 1;
+  });
+}
+
+module.exports = { main };

package/package.json

@@ -1,6 +1,40 @@
 {
   "name": "fibemate-xdiff",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Deterministic cross-implementation diff harness for ML-KEM-768: KAT provenance, RNG-consumption alignment, key-schedule root cause.",
+  "type": "commonjs",
+  "main": "src/engine.js",
+  "bin": {
+    "xdiff": "./bin/xdiff.js"
+  },
+  "files": [
+    "bin",
+    "src",
+    "tools",
+    "README.md"
+  ],
+  "scripts": {
+    "test": "node test/run.js",
+    "run": "node bin/xdiff.js run",
+    "list": "node bin/xdiff.js list",
+    "test:mutation": "node test/mutation.js"
+  },
+  "keywords": [
+    "ml-kem",
+    "kyber",
+    "post-quantum",
+    "pqc",
+    "kat",
+    "differential-testing"
+  ],
+  "license": "Apache-2.0",
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {},
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Lennonhaha/fibemate-tools.git",
+    "directory": "xdiff"
+  }
+}

package/src/config.js

@@ -0,0 +1,176 @@
+// SPDX-License-Identifier: Apache-2.0
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+const { ConfigError } = require('./errors');
+
+const FILE_NAME = 'xdiff.json';
+
+const DEFAULTS = {
+  version: 1,
+  algorithm: 'ML-KEM-768',
+  // 期望尺寸，来自 FIPS 203 对 ML-KEM-768 的规定
+  sizes: { pk: 1184, sk: 2400, ct: 1088, ss: 32 },
+  // 算法参数，供密钥派生根因定位使用（k 是域分隔符，768 → 3）
+  params: { k: 3, eta1: 2, eta2: 2 },
+
+  masterSeed: 'xdiff-default-master-seed-v1',
+
+  implementations: [
+    {
+      id: 'cp',
+      label: 'fibemate-core 纯 JS',
+      type: 'js-mlkem',
+      path: '../../fibemate-core/index.js',
+      note: '独立发布的纯 JS 包，Keccak 为 32 位字实现'
+    },
+    {
+      id: 'main',
+      label: '主仓 packages/pqc-kem',
+      type: 'js-mlkem',
+      path: '../../fibemate/packages/pqc-kem/src/ml-kem-768.js',
+      note: '主仓副本，453 行，与 cp 已分叉'
+    },
+    {
+      id: 'noble',
+      label: '@noble/post-quantum ml_kem768',
+      type: 'noble-mlkem',
+      path: '../../fibemate/node_modules/@noble/post-quantum',
+      note: '第三方独立实现，作为交叉参考'
+    },
+    {
+      id: 'liboqs',
+      label: 'liboqs 0.16 (C)',
+      type: 'liboqs-bridge',
+      path: './tools/oqsbridge.c',
+      note: 'pending: needs cross-platform build; only oqsbridge.c source, no compiled binary',
+      enabled: false
+    }
+  ],
+
+  cases: {
+    lengthCompliance: { enabled: true },
+    roundtrip: { enabled: true, samples: 8 },
+    crossInterop: { enabled: true, samples: 8 },
+    determinism: { enabled: true, samples: 4 },
+    seedAlignment: { enabled: true },
+    keySchedule: { enabled: true },
+    kat: { enabled: true, rsp: null, vectors: 16 },
+    katFileHygiene: { enabled: true },
+    entropy: { enabled: true, samples: 8 },
+    implicitRejection: { enabled: true, samples: 4 },
+    rngProfile: { enabled: true },
+    timing: { enabled: true, samples: 20 }
+  },
+
+  matrix: {
+    // 互操作矩阵里允许「已知不同且已接受」的组合，避免噪声
+    allowSemanticGroups: true,
+    // 已确认的预期差异（例如 draft Kyber 与 FIPS 203 的 ss 语义不同）
+    expectedDivergence: []
+  },
+
+  pool: { workers: 0, timeoutMs: 120000 },   // workers: 0 = 自动
+
+  output: { dir: '.xdiff', failOn: 'error' },
+
+  cache: { enabled: true }
+};
+
+function isPlainObject(v) {
+  return Object.prototype.toString.call(v) === '[object Object]';
+}
+
+function deepMerge(base, patch) {
+  if (!isPlainObject(patch)) return base;
+  const out = Array.isArray(base) ? base.slice() : Object.assign({}, base);
+  for (const k of Object.keys(patch)) {
+    const pv = patch[k];
+    if (pv === undefined) continue;
+    if (isPlainObject(pv) && isPlainObject(out[k])) out[k] = deepMerge(out[k], pv);
+    else out[k] = Array.isArray(pv) ? pv.slice() : pv;
+  }
+  return out;
+}
+
+function findConfigFile(startDir) {
+  let cur = path.resolve(startDir);
+  for (let i = 0; i < 8; i++) {
+    const p = path.join(cur, FILE_NAME);
+    if (fs.existsSync(p)) return p;
+    const parent = path.dirname(cur);
+    if (parent === cur) break;
+    cur = parent;
+  }
+  return null;
+}
+
+function loadConfig(opts) {
+  const o = opts || {};
+  const cwd = path.resolve(o.cwd || process.cwd());
+  let fileCfg = {};
+  const configPath = o.configPath || findConfigFile(cwd);
+  if (configPath) {
+    let raw;
+    try { raw = fs.readFileSync(configPath, 'utf8'); } catch (e) {
+      throw new ConfigError('配置文件读取失败', { configPath, message: e.message });
+    }
+    try { fileCfg = JSON.parse(raw); } catch (e) {
+      throw new ConfigError('配置文件不是合法 JSON', { configPath, message: e.message });
+    }
+  }
+
+  const envCfg = {
+    masterSeed: process.env.XDIFF_SEED || undefined
+  };
+  const stripped = {};
+  for (const k of Object.keys(envCfg)) if (envCfg[k] !== undefined) stripped[k] = envCfg[k];
+
+  let cfg = deepMerge(DEFAULTS, fileCfg);
+  cfg = deepMerge(cfg, stripped);
+  cfg = deepMerge(cfg, o.overrides || {});
+
+  cfg.__cwd = cwd;
+  cfg.__configPath = configPath;
+
+  // Resolve relative implementation paths against config file directory
+  if (Array.isArray(cfg.implementations)) {
+    const base = cfg.__configPath ? path.dirname(cfg.__configPath) : cfg.__cwd;
+    for (const im of cfg.implementations) {
+      if (im.path && !path.isAbsolute(im.path)) {
+        im.path = path.resolve(base, im.path);
+      }
+    }
+  }
+
+  validate(cfg);
+  return cfg;
+}
+
+function validate(cfg) {
+  if (!cfg.algorithm) throw new ConfigError('algorithm 不能为空');
+  const impls = cfg.implementations;
+  if (!Array.isArray(impls) || !impls.length) throw new ConfigError('implementations 至少需要一项');
+  const seen = new Set();
+  for (const im of impls) {
+    if (!im.id) throw new ConfigError('每项 implementation 需要 id');
+    if (seen.has(im.id)) throw new ConfigError('implementation id 重复: ' + im.id);
+    seen.add(im.id);
+    if (!im.type) throw new ConfigError('implementation 需要 type: ' + im.id);
+    if (!im.path) throw new ConfigError('implementation 需要 path: ' + im.id);
+    if (im.enabled === false) continue;
+    if (!fs.existsSync(im.path)) {
+      // 路径不存在不算致命：适配器会把它标成 unavailable
+      im.__missingPath = true;
+    }
+  }
+  if (!cfg.sizes || typeof cfg.sizes.pk !== 'number') throw new ConfigError('sizes.pk 必须是数字');
+}
+
+function cpuCount() {
+  try { return os.cpus().length || 4; } catch (_) { return 4; }
+}
+
+module.exports = { loadConfig, DEFAULTS, deepMerge, cpuCount, FILE_NAME };

package/src/core/kat.js

@@ -0,0 +1,133 @@
+// SPDX-License-Identifier: Apache-2.0
+'use strict';
+
+/**
+ * NIST .rsp 格式的 ML-KEM KAT 向量解析 + 参考文件卫生检查。
+ *
+ * 向量字段：count / seed(32B) / m(32B) / ek(1184B) / dk(2400B) / c(1088B) / k(32B)。
+ * 解析只做结构校验，不猜语义；dk 的区域含义由 hygiene 检查显式标注。
+ */
+
+const U = require('../util');
+
+const FIELD_LEN = { seed: 32, m: 32, ek: 1184, dk: 2400, c: 1088, k: 32 };
+
+/** 解析 .rsp 文本 → 向量数组（值保留 Buffer）。 */
+function parseRsp(text) {
+  const vectors = [];
+  let cur = null;
+  const lines = String(text).split(/\r?\n/);
+  for (const line of lines) {
+    const m = line.match(/^([A-Za-z]+)\s*=\s*([0-9a-fA-F]+)\s*$/);
+    if (!m) continue;
+    const field = m[1];
+    const hex = m[2].toLowerCase();
+    if (field === 'count') {
+      if (cur) vectors.push(cur);
+      cur = { count: parseInt(hex || '0', 10) };
+      continue;
+    }
+    if (!cur) continue;
+    if (!(field in FIELD_LEN)) { cur[field] = hex; continue; }
+    const buf = Buffer.from(hex, 'hex');
+    cur[field] = buf;
+    cur[field + 'LenOk'] = buf.length === FIELD_LEN[field];
+  }
+  if (cur) vectors.push(cur);
+  return vectors;
+}
+
+/** 结构完整性：每条向量的必备字段与长度。 */
+function checkStructure(vectors) {
+  const bad = [];
+  for (const v of vectors) {
+    for (const f of Object.keys(FIELD_LEN)) {
+      if (!v[f]) { bad.push({ count: v.count, field: f, problem: 'missing' }); continue; }
+      if (v[f + 'LenOk'] === false) bad.push({ count: v.count, field: f, problem: 'length', got: v[f].length, expect: FIELD_LEN[f] });
+    }
+  }
+  return bad;
+}
+
+/**
+ * 卫生检查：dk 的分区域分析。
+ * FIPS 203 的 compact 布局：d(0:32) ‖ ek(32:1216) ‖ H(ek)(1216:1248) ‖ z(1248:1280)。
+ * z 与 1280 之后的尾部都应当由实现确定性写出；发现不可读来源的字节（ASCII 串、
+ * 指针模式、非零残留）时如实报告数量——这是信号，不是判决。
+ */
+function analyzeHygiene(vectors) {
+  const compact = { dMatch: 0, ekMatch: 0, hMatch: 0, of: 0 };
+  const zStats = { total: 0, asciiReadable: 0, allZero: 0, unique: 0 };
+  const tailStats = { total: 0, allZero: 0, nonZero: 0, asciiReadable: 0 };
+  const zSeen = new Set();
+
+  for (const v of vectors) {
+    if (!v.dk || v.dk.length !== 2400 || !v.seed || !v.ek) continue;
+    const dk = v.dk;
+    compact.of++;
+    if (dk.slice(0, 32).equals(v.seed)) compact.dMatch++;
+    if (dk.slice(32, 1216).equals(v.ek)) compact.ekMatch++;
+    if (dk.slice(1216, 1248).equals(U.sha3_256(v.ek))) compact.hMatch++;
+
+    const z = dk.slice(1248, 1280);
+    zStats.total++;
+    zSeen.add(z.toString('hex'));
+    if (z.every((b) => b === 0)) zStats.allZero++;
+    if (hasAsciiRun(z, 6)) zStats.asciiReadable++;
+
+    const tail = dk.slice(1280);
+    tailStats.total++;
+    if (tail.every((b) => b === 0)) tailStats.allZero++;
+    else {
+      tailStats.nonZero++;
+      if (hasAsciiRun(tail, 8)) tailStats.asciiReadable++;
+    }
+  }
+  zStats.unique = zSeen.size;
+  return { compact, z: zStats, tail: tailStats };
+}
+
+function hasAsciiRun(buf, minLen) {
+  let run = 0;
+  for (const b of buf) {
+    if (b >= 0x20 && b <= 0x7e) { run++; if (run >= minLen) return true; }
+    else run = 0;
+  }
+  return false;
+}
+
+/**
+ * 判定 KAT 文件自身的派生路径：ρ 到底等于 G(d‖k)、G(d) 还是 G(k‖d)。
+ *
+ * 纯函数，不加载任何实现——因此在只检出 fibemate-tools（没有 fibemate /
+ * fibemate-core 可加载）的 CI 里也能测。k 为空时返回 unknown 与空 tally。
+ *
+ * @param {Array<{seed?: Buffer, ek?: Buffer}>} vectors
+ * @param {number|null} k  FIPS 203 的模块维度（ML-KEM-768 = 3）
+ * @returns {{provenance: string, tally: Record<string, number>}}
+ */
+function analyzeProvenance(vectors, k) {
+  const tally = {};
+  if (typeof k !== 'number') return { provenance: 'unknown', tally };
+  const kByte = Buffer.from([k]);
+  const crypto = require('crypto');
+  const sha3_512 = (buf) => crypto.createHash('sha3-512').update(buf).digest();
+  for (const v of (vectors || []).slice(0, 8)) {
+    if (!v || !v.ek || !v.seed) continue;
+    const rho = v.ek.slice(v.ek.length - 32);
+    const cands = {
+      standard: sha3_512(Buffer.concat([v.seed, kByte])).slice(0, 32),
+      missingDomainSep: sha3_512(v.seed).slice(0, 32),
+      reversedOrder: sha3_512(Buffer.concat([kByte, v.seed])).slice(0, 32),
+    };
+    let hit = 'unknown';
+    for (const [name, val] of Object.entries(cands)) {
+      if (val.equals(rho)) { hit = name; break; }
+    }
+    tally[hit] = (tally[hit] || 0) + 1;
+  }
+  const ranked = Object.entries(tally).sort((a, b) => b[1] - a[1]);
+  return { provenance: ranked.length ? ranked[0][0] : 'unknown', tally };
+}
+
+module.exports = { parseRsp, checkStructure, analyzeHygiene, analyzeProvenance, FIELD_LEN };