@danceiny/gotry 0.0.1-rc.21 → 0.0.1-rc.24

package/dist/scripts/kernel-manifest-tests.js

@@ -0,0 +1,212 @@
+/**
+ * 内核清单冻结 + 运行模块证据 自测(issue #234;全离线,fixture 走临时目录,
+ * 唯一真实 trace 在 §7 终检且 import-only 零状态写入)。
+ *
+ * 反证矩阵(issue #234 验收 3:反证必须失败):
+ *   改核心(§5a)/删核心文件(§5b)/替换内核为废弃层(§4f)/未加载核心(§6b)/
+ *   错 manifestHash(§6c)/错 evidenceHash(§6d)/错 candidateSHA(§6e)/
+ *   缺路径覆盖-套件缺失(§5c)/缺路径覆盖-不再 import 内核(§5d)/
+ *   schema 纪律-空依据/坏组/路径逃逸/重复条目(§4)。
+ *
+ * 运行:cd ts && npx tsx scripts/kernel-manifest-tests.ts
+ */
+import assert from 'node:assert/strict';
+import { cpSync, existsSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join, resolve } from 'node:path';
+import { evidenceHash, importClosure, loadKernelManifest, MANIFEST_REL, manifestHash, validateEvidence, validateFunctionalCoverage, validateKernelIntegrity, validateManifestSchema, } from './kernel-manifest.js';
+import { buildEvidence } from './kernel-manifest-evidence.js';
+import { main as gateMain } from './kernel-manifest-gate.js';
+const repoRoot = resolve(import.meta.dirname, '..', '..');
+const KERNEL_FILES = ['ts/src/unified.ts', 'ts/src/model.ts', 'ts/src/state-ledger.ts', 'ts/src/bookable-facts.ts', 'ts/src/artifact-gate.ts'];
+const SUITE_FILES = ['ts/scripts/unified-tests.ts', 'ts/scripts/ledger-tests.ts', 'ts/scripts/fact-gate-tests.ts'];
+let section = 0;
+function head(title) {
+    section += 1;
+    console.log(`--- §${section} ${title}`);
+}
+function expectFinding(findings, code, label) {
+    assert.ok(findings.some((f) => f.code === code), `${label}:期望出现 ${code},实际 [${findings.map((f) => f.code).join(', ')}]`);
+}
+/** 临时 fixture 仓库:根 package.json(无 files 面) + 内核文件 + 覆盖套件 + 冻结清单,全部从真实仓库逐字节拷贝。 */
+function makeFixtureRepo() {
+    const dir = mkdtempSync(join(tmpdir(), 'gotry-kernel-fixture-'));
+    writeFileSync(join(dir, 'package.json'), JSON.stringify({ name: 'gotry-kernel-fixture', private: true }, null, 2) + '\n');
+    for (const rel of [...KERNEL_FILES, ...SUITE_FILES]) {
+        const target = join(dir, rel);
+        cpSync(join(repoRoot, rel), target);
+    }
+    cpSync(join(repoRoot, MANIFEST_REL), join(dir, MANIFEST_REL));
+    return dir;
+}
+function fakeTraceAll() {
+    return { ok: true, nodeVersion: process.versions.node, moduleCount: KERNEL_FILES.length, repoModuleCount: KERNEL_FILES.length, loadedRepoModules: [...KERNEL_FILES].sort() };
+}
+function baseEvidence(fixture, manifest) {
+    return buildEvidence(manifest, {
+        repoRoot: fixture,
+        manifestRel: MANIFEST_REL,
+        now: '2026-09-11T00:00:00.000Z',
+        candidateSHA: manifest.baseSHA,
+        trace: fakeTraceAll(),
+    });
+}
+// §1 真实仓库:冻结清单 schema 纪律绿。
+head('真实仓库 冻结清单 schema 纪律');
+const manifest = loadKernelManifest(repoRoot);
+{
+    const result = validateManifestSchema(manifest);
+    assert.equal(result.ok, true, `真实清单 schema 应绿:${JSON.stringify(result.findings)}`);
+    assert.ok(manifest.entries.length >= 5, '内核条目至少 5 项(宁窄勿宽,但必须覆盖引擎/账本/闸)');
+    const groups = new Set(manifest.entries.map((e) => e.group));
+    for (const g of ['engine', 'ledger', 'gate'])
+        assert.ok(groups.has(g), `清单必须覆盖 group ${g}`);
+    // 冻结清单哈希必须确定可复算(规范化 JSON 的哈希绑定)。
+    assert.equal(manifestHash(manifest), manifestHash(loadKernelManifest(repoRoot)), 'manifestHash 必须确定');
+}
+// §2 真实仓库:内核零 diff + 打包面绿。
+head('真实仓库 内核零 diff + npm 打包面');
+{
+    const result = validateKernelIntegrity(manifest, repoRoot);
+    assert.equal(result.ok, true, `真实内核零 diff 应绿:${JSON.stringify(result.findings)}`);
+}
+// §3 真实仓库:功能路径覆盖绿(套件存在 + 静态 import 闭包含内核)。
+head('真实仓库 功能路径覆盖(同引擎/账本/闸路径)');
+{
+    const result = validateFunctionalCoverage(manifest, repoRoot);
+    assert.equal(result.ok, true, `真实功能路径覆盖应绿:${JSON.stringify(result.findings)}`);
+    for (const fp of manifest.functionalPaths) {
+        const closure = importClosure(repoRoot, fp.suite);
+        for (const km of fp.kernelModules)
+            assert.ok(closure.has(km), `${fp.suite} 闭包应含 ${km}`);
+    }
+}
+// §4 schema 纪律反证:空依据/坏组/路径逃逸/重复条目/废弃层冒充内核。
+head('schema 纪律反证(全部必须红)');
+{
+    const clone = (overrides) => ({ ...manifest, ...overrides });
+    const badGroup = validateManifestSchema(clone({ entries: [{ ...manifest.entries[0], group: 'misc' }] }));
+    expectFinding(badGroup.findings, 'manifest-group', '坏 group');
+    const noBasis = validateManifestSchema(clone({ entries: [{ ...manifest.entries[0], basis: '' }] }));
+    expectFinding(noBasis.findings, 'manifest-basis-missing', '空依据');
+    const noRationale = validateManifestSchema(clone({ entries: [{ ...manifest.entries[0], rationale: ' ' }] }));
+    expectFinding(noRationale.findings, 'manifest-rationale-missing', '空 rationale');
+    const escapePath = validateManifestSchema(clone({ entries: [{ ...manifest.entries[0], path: '../outside.js' }] }));
+    expectFinding(escapePath.findings, 'manifest-path-shape', '路径逃逸');
+    const dup = validateManifestSchema(clone({ entries: [manifest.entries[0], { ...manifest.entries[0] }] }));
+    expectFinding(dup.findings, 'manifest-duplicate-path', '重复条目');
+    // 废弃兼容层(journey.ts)冒充内核:清单层面直接拒绝。
+    const deprecated = validateManifestSchema(clone({ entries: [{ ...manifest.entries[0], path: 'ts/src/journey.ts' }] }));
+    expectFinding(deprecated.findings, 'manifest-forbidden-path', '废弃层冒充内核');
+    const empty = validateManifestSchema(clone({ entries: [] }));
+    expectFinding(empty.findings, 'manifest-empty', '空清单');
+}
+// §5 fixture 内核零 diff + 功能路径反证(红→绿)。
+head('fixture 内核零 diff / 功能路径反证(红)');
+{
+    const fixture = makeFixtureRepo();
+    try {
+        const fx = loadKernelManifest(fixture, MANIFEST_REL);
+        // 绿基线:逐字节拷贝的 fixture 必须零 diff、覆盖成立。
+        assert.equal(validateKernelIntegrity(fx, fixture).ok, true, 'fixture 基线应绿');
+        assert.equal(validateFunctionalCoverage(fx, fixture).ok, true, 'fixture 覆盖基线应绿');
+        // (a) 改核心:哈希漂移必须红。
+        writeFileSync(join(fixture, 'ts/src/model.ts'), readFileSync(join(fixture, 'ts/src/model.ts'), 'utf8') + '\n// 反证:核心被改动\n');
+        const tampered = validateKernelIntegrity(fx, fixture);
+        assert.equal(tampered.ok, false, '改核心必须红');
+        expectFinding(tampered.findings, 'kernel-hash-mismatch', '改核心');
+        // (b) 删核心文件:事后删文件制造零 diff 被封死。
+        rmSync(join(fixture, 'ts/src/artifact-gate.ts'));
+        const missing = validateKernelIntegrity(fx, fixture);
+        expectFinding(missing.findings, 'kernel-file-missing', '删核心文件');
+        // (c) 缺路径覆盖:覆盖套件缺失。
+        const fxCov = loadKernelManifest(fixture, MANIFEST_REL);
+        rmSync(join(fixture, 'ts/scripts/ledger-tests.ts'));
+        const cov = validateFunctionalCoverage(fxCov, fixture);
+        assert.equal(cov.ok, false, '套件缺失必须红');
+        expectFinding(cov.findings, 'coverage-suite-missing', '套件缺失');
+        // (d) 缺路径覆盖:套件不再 import 内核模块。
+        writeFileSync(join(fixture, 'ts/scripts/fact-gate-tests.ts'), "import { ok } from 'node:assert/strict'\nconsole.log(ok)\n");
+        const cov2 = validateFunctionalCoverage(fxCov, fixture);
+        assert.equal(cov2.ok, false, '套件不再 import 内核必须红');
+        expectFinding(cov2.findings, 'coverage-suite-not-importing-kernel', '覆盖断裂');
+    }
+    finally {
+        rmSync(fixture, { recursive: true, force: true });
+    }
+}
+// §6 证据快照哈希绑定 + 加载覆盖反证(红)。
+head('证据快照哈希绑定 / 未加载核心 反证(红)');
+{
+    const fixture = makeFixtureRepo();
+    try {
+        const fx = loadKernelManifest(fixture, MANIFEST_REL);
+        // 绿基线:完整证据(全加载)必须绿。
+        const good = baseEvidence(fixture, fx);
+        const goodResult = validateEvidence(good, fx, fixture, { requireLoadedCoverage: true, expectedCandidateSha: fx.baseSHA });
+        assert.equal(goodResult.ok, true, `完整证据基线应绿:${JSON.stringify(goodResult.findings)}`);
+        assert.equal(evidenceHash(good), good.evidenceHash, 'evidenceHash 必须自洽');
+        // (a) 快照缺内核条目/出现清单外条目。
+        const missingEntry = { ...good, kernel: good.kernel.slice(1) };
+        missingEntry.evidenceHash = evidenceHash(missingEntry);
+        const r0 = validateEvidence(missingEntry, fx, fixture, { requireLoadedCoverage: true });
+        expectFinding(r0.findings, 'evidence-kernel-missing', '快照缺内核条目');
+        // (b) 未加载核心:trace 缺一个内核模块必须红(issue #234「未加载核心」反证)。
+        const partialTrace = { ...fakeTraceAll(), loadedRepoModules: fakeTraceAll().loadedRepoModules.filter((p) => p !== 'ts/src/state-ledger.ts') };
+        const partial = buildEvidence(fx, { repoRoot: fixture, manifestRel: MANIFEST_REL, now: '2026-09-11T00:00:00.000Z', candidateSHA: fx.baseSHA, trace: partialTrace });
+        const r1 = validateEvidence(partial, fx, fixture, { requireLoadedCoverage: true });
+        assert.equal(r1.ok, false, '未加载核心必须红');
+        expectFinding(r1.findings, 'kernel-not-loaded', '未加载核心');
+        // (c) 错 manifestHash(冻结清单被改动/快照错绑)。
+        const wrongManifestHash = { ...good, manifestRef: { ...good.manifestRef, sha256: '0'.repeat(64) } };
+        wrongManifestHash.evidenceHash = evidenceHash(wrongManifestHash);
+        const r2 = validateEvidence(wrongManifestHash, fx, fixture, { requireLoadedCoverage: true });
+        expectFinding(r2.findings, 'manifest-hash-mismatch', '错 manifestHash');
+        // (d) 快照内容被改动(evidenceHash 不再自洽)。
+        const tamperedSnapshot = { ...good, generatedAt: '2030-01-01T00:00:00.000Z' };
+        const r3 = validateEvidence(tamperedSnapshot, fx, fixture, { requireLoadedCoverage: true });
+        expectFinding(r3.findings, 'evidence-hash-mismatch', '快照被改动');
+        // (e) 错 candidateSHA(绑定面)。
+        const r4 = validateEvidence(good, fx, fixture, { requireLoadedCoverage: true, expectedCandidateSha: 'a'.repeat(40) });
+        expectFinding(r4.findings, 'evidence-candidate-sha-mismatch', '错 candidateSHA');
+        // (f) 空 trace 冒充运行证据。
+        const emptyTrace = buildEvidence(fx, { repoRoot: fixture, manifestRel: MANIFEST_REL, now: '2026-09-11T00:00:00.000Z', candidateSHA: fx.baseSHA, trace: { ok: true, nodeVersion: process.versions.node, moduleCount: 0, repoModuleCount: 0, loadedRepoModules: [] } });
+        const r5 = validateEvidence(emptyTrace, fx, fixture, { requireLoadedCoverage: true });
+        expectFinding(r5.findings, 'evidence-trace-empty', '空 trace');
+        expectFinding(r5.findings, 'kernel-not-loaded', '空 trace 必然未加载');
+    }
+    finally {
+        rmSync(fixture, { recursive: true, force: true });
+    }
+}
+// §7 真实端到端:闸默认模式(真实运行 trace)→ 快照 → 审计 → 篡改快照必红。
+head('真实端到端 闸 + 证据快照审计');
+{
+    const outSnapshot = join(mkdtempSync(join(tmpdir(), 'gotry-kernel-e2e-')), 'evidence.json');
+    try {
+        const exitGen = gateMain(['--out', outSnapshot]);
+        assert.equal(exitGen, 0, `闸默认模式(真实 trace)应绿且 exit 0,得到 ${exitGen}`);
+        assert.ok(existsSync(outSnapshot), '闸应写出证据快照');
+        const snapshot = JSON.parse(readFileSync(outSnapshot, 'utf8'));
+        assert.equal(snapshot.schemaVersion, 'gotry_kernel_evidence_v1');
+        assert.equal(snapshot.kernel.length, manifest.entries.length, '快照内核条目数与清单一致');
+        for (const k of snapshot.kernel)
+            assert.equal(k.loadedInTrace, true, `真实运行应加载内核:${k.path}`);
+        assert.ok(snapshot.runtime.moduleCount > 0, 'trace 必须记录到真实模块');
+        const exitVerify = gateMain(['--verify', outSnapshot]);
+        assert.equal(exitVerify, 0, `快照审计应绿,得到 ${exitVerify}`);
+        // 篡改快照(错 SHA 面)必须红:exit 1。
+        const tampered = { ...snapshot, kernel: snapshot.kernel.map((k, i) => (i === 0 ? { ...k, sha256Current: '0'.repeat(64) } : k)) };
+        const tamperedPath = outSnapshot.replace(/evidence\.json$/, 'evidence-tampered.json');
+        writeFileSync(tamperedPath, JSON.stringify(tampered, null, 2) + '\n');
+        const exitTampered = gateMain(['--verify', tamperedPath]);
+        assert.equal(exitTampered, 1, `篡改快照必须红,得到 ${exitTampered}`);
+        // manifestHash 外部钉值校验:对偶面。
+        assert.equal(gateMain(['--skip-trace', '--manifest-hash', manifestHash(manifest)]), 0, 'manifestHash 钉值匹配应绿');
+        assert.equal(gateMain(['--skip-trace', '--manifest-hash', 'f'.repeat(64)]), 1, 'manifestHash 钉值不符必须红');
+    }
+    finally {
+        rmSync(outSnapshot, { recursive: true, force: true });
+    }
+}
+console.log(`KERNEL MANIFEST TESTS: GREEN(§1–§${section};反证矩阵 §4/§5/§6 全部按预期红,§7 真实运行 trace 端到端绿)`);

package/dist/scripts/kernel-manifest-trace-entry.js

@@ -0,0 +1,7 @@
+/**
+ * 运行模块 trace 入口(issue #234):真实 import 产品运行面——dsh 插件入口
+ * ts/src/index.ts。import-only:不调用任何工具、不注册到任何 ctx、零状态写入
+ * (gotry-state 红线面零接触);trace 结果由 kernel-manifest-trace-hook.mjs 记录。
+ */
+await import('../src/index.js');
+process.stdout.write('KERNEL_TRACE_ENTRY_OK\n');

package/dist/scripts/kernel-manifest-trace-hook.mjs

@@ -0,0 +1,28 @@
+/**
+ * 运行模块 trace 钩子(issue #234;由 kernel-manifest.ts runRuntimeTrace 以
+ * `node --import tsx/esm --import <本文件>` 装载)。node:module registerHooks
+ * 是同步钩子(主线程,Node ≥ 22.15),能记录真实实例化的每个模块 URL;
+ * 异步 register() 的钩子跑在独立线程,主进程拿不到数组——这是选同步 API 的原因。
+ * 输出:KR_TRACE_OUT 指向的文件,{ loaded: [url, …] }。
+ */
+import { registerHooks } from 'node:module'
+import { writeFileSync } from 'node:fs'
+
+const loaded = []
+
+registerHooks({
+  load(url, context, nextLoad) {
+    loaded.push(url)
+    return nextLoad(url, context)
+  },
+})
+
+process.on('exit', () => {
+  const out = process.env.KR_TRACE_OUT
+  if (!out) return
+  try {
+    writeFileSync(out, JSON.stringify({ loaded }))
+  } catch {
+    // 输出失败时父进程按「trace 文件缺失」裁决为环境失败(exit 2),不静默。
+  }
+})

package/dist/scripts/kernel-manifest.js

@@ -0,0 +1,369 @@
+/**
+ * GoTry 内核清单冻结 + 运行模块证据(issue #234;M5 备产系列,父单 #136)。
+ *
+ * 把复用矩阵纪律「哪些模块属于 GoTry 内核(不允许被替换/绕过)」机械化为可校验清单:
+ *   1. 冻结清单 ts/data/kernel-manifest.json(gotry_kernel_manifest_v1):预先冻结
+ *      内核文件集合 + 文件 SHA256 + 每项依据,绑定 baseSHA——零 diff 证明 = 哈希相等,
+ *      不存在「事后删文件制造零 diff」的空间(删文件即 kernel-file-missing 红)。
+ *   2. 运行模块证据(gotry_kernel_evidence_v1):对真实产品运行面(ts/src/index.ts
+ *      dsh 插件入口)做真实运行 import trace(node:module registerHooks 同步钩子,
+ *      子进程离线),断言内核清单全部被运行加载;再对照功能路径覆盖(同引擎/账本/闸
+ *      路径的 run-all 套件静态 import 闭包)。仅 LOC/字符串扫描不构成复用证明。
+ *   3. 证据快照哈希绑定(manifestHash + evidenceHash),离线可复跑、可审计。
+ *
+ * 边界(诚实声明,对齐 issue #234 与 #137 门注):本面只输出工程复用证据,
+ * 不冒充 traveler 效果或 M6 试点签约;精确运行模块证据成为实施门以 #136 M5 Exit
+ * 与创始人 P6 批准记录在 #137 为前提——本面是 pre-entry 设计 + 确定性 fixture。
+ *
+ * 用法:
+ *   npx tsx scripts/kernel-manifest-evidence.ts  生成证据快照(--out 或 stdout)
+ *   npx tsx scripts/kernel-manifest-gate.ts      机械闸(默认 HEAD 全量校验)
+ *   npx tsx scripts/kernel-manifest-tests.ts     反证自测(全离线)
+ */
+import { spawnSync } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import { existsSync, mkdtempSync, readFileSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { dirname, isAbsolute, join, relative, resolve, sep } from 'node:path';
+import { fileURLToPath } from 'node:url';
+export const MANIFEST_SCHEMA_VERSION = 'gotry_kernel_manifest_v1';
+export const EVIDENCE_SCHEMA_VERSION = 'gotry_kernel_evidence_v1';
+export const MANIFEST_REL = 'ts/data/kernel-manifest.json';
+export const RUNTIME_ENTRY_REL = 'ts/src/index.ts';
+export const TRACE_ENTRY_REL = 'ts/scripts/kernel-manifest-trace-entry.ts';
+export const TRACE_HOOK_REL = 'ts/scripts/kernel-manifest-trace-hook.mjs';
+/** registerHooks 需 Node ≥ 22.15(同步、主线程);低于此版本闸无法运行(exit 2)。 */
+export const MIN_NODE_FOR_REGISTER_HOOKS = [22, 15, 0];
+export const KERNEL_GROUPS = ['engine', 'ledger', 'gate'];
+function toResult(findings) {
+    return { ok: findings.length === 0, findings };
+}
+/** 规范化 JSON:键递归排序,消除键序对哈希的扰动(哈希绑定的基础)。 */
+export function canonicalJson(value) {
+    if (value === null || typeof value !== 'object')
+        return JSON.stringify(value) ?? 'null';
+    if (Array.isArray(value))
+        return `[${value.map((v) => canonicalJson(v)).join(',')}]`;
+    const keys = Object.keys(value).sort();
+    const body = keys
+        .map((k) => `${JSON.stringify(k)}:${canonicalJson(value[k])}`)
+        .join(',');
+    return `{${body}}`;
+}
+export function sha256Hex(text) {
+    return createHash('sha256').update(text, 'utf8').digest('hex');
+}
+/** 冻结清单的哈希绑定:清单内容(规范化)的 SHA256。 */
+export function manifestHash(manifest) {
+    return sha256Hex(canonicalJson(manifest));
+}
+/** 证据快照的哈希绑定:去掉 evidenceHash 字段后(规范化)的 SHA256。 */
+export function evidenceHash(evidence) {
+    const { evidenceHash: _ignored, ...rest } = evidence;
+    return sha256Hex(canonicalJson(rest));
+}
+export function repoRelative(repoRoot, absPath) {
+    return relative(repoRoot, absPath).split(sep).join('/');
+}
+export function defaultRepoRoot() {
+    // 本文件位于 <repo>/ts/scripts/,仓库根在其上两级。
+    return resolve(dirname(fileURLToPath(import.meta.url)), '..', '..');
+}
+export function loadKernelManifest(repoRoot, manifestRel = MANIFEST_REL) {
+    const raw = JSON.parse(readFileSync(join(repoRoot, manifestRel), 'utf8'));
+    return raw;
+}
+const SHA256_RE = /^[0-9a-f]{64}$/;
+const GIT_SHA_RE = /^[0-9a-f]{40}$/;
+/** 内核条目只允许产品运行面 ts/src/<module>.ts(宁窄勿宽,拒绝目录/逃逸/杂类)。 */
+const KERNEL_PATH_RE = /^ts\/src\/[A-Za-z0-9_-]+\.ts$/;
+/** 废弃兼容层永远不得冒充内核(AGENTS.md:engine.ts / journey.ts deprecated)。 */
+export const FORBIDDEN_KERNEL_PATHS = new Set(['ts/src/engine.ts', 'ts/src/journey.ts']);
+/** 计算文件当前 SHA256;文件缺失返回 null。 */
+export function fileSha256(repoRoot, relPath) {
+    const abs = join(repoRoot, relPath);
+    if (!existsSync(abs))
+        return null;
+    return sha256Hex(readFileSync(abs, 'utf8'));
+}
+/**
+ * 静态 import 闭包:从 entryRel 出发,沿相对 .ts import(transitive)收集可达文件
+ * (仓库相对路径)。仓库约定 import 带 .ts 扩展名;覆盖 `from '...'` 与 `import('...')`。
+ */
+export function importClosure(repoRoot, entryRel) {
+    const seen = new Set();
+    const queue = [entryRel];
+    const FROM_RE = /from\s+'([^']+)'/g;
+    const DYNAMIC_RE = /import\('([^']+)'\)/g;
+    while (queue.length > 0) {
+        const current = queue.pop();
+        if (seen.has(current))
+            continue;
+        seen.add(current);
+        const abs = join(repoRoot, current);
+        if (!existsSync(abs))
+            continue;
+        const content = readFileSync(abs, 'utf8');
+        const specifiers = new Set();
+        for (const re of [FROM_RE, DYNAMIC_RE]) {
+            re.lastIndex = 0;
+            let m;
+            while ((m = re.exec(content)) !== null)
+                specifiers.add(m[1]);
+        }
+        for (const spec of specifiers) {
+            if (!spec.startsWith('.') || !spec.endsWith('.ts'))
+                continue;
+            const target = repoRelative(repoRoot, resolve(dirname(abs), spec));
+            if (!target.startsWith('..'))
+                queue.push(target);
+        }
+    }
+    return seen;
+}
+/** 当前 git HEAD(40 hex);非 git 环境/失败返回 null。 */
+export function currentHeadSha(repoRoot) {
+    const result = spawnSync('git', ['rev-parse', 'HEAD'], { cwd: repoRoot, encoding: 'utf8' });
+    if (result.error || result.status !== 0)
+        return null;
+    const sha = result.stdout.trim();
+    return GIT_SHA_RE.test(sha) ? sha : null;
+}
+function nodeVersionTuple() {
+    return process.versions.node.split('.').map((n) => Number(n));
+}
+/** 运行环境是否具备 registerHooks(同步钩子)能力。 */
+export function nodeSupportsRegisterHooks() {
+    const [maj, min, patch] = nodeVersionTuple();
+    const [rMaj, rMin, rPatch] = MIN_NODE_FOR_REGISTER_HOOKS;
+    return maj > rMaj || (maj === rMaj && (min > rMin || (min === rMin && patch >= rPatch)));
+}
+/**
+ * 真实运行 import trace:子进程里对真实产品运行面(ts/src/index.ts)执行 import,
+ * 用 node:module registerHooks 同步 load 钩子记录全部实例化模块;返回仓库内
+ * ts/ 面的相对路径(排序)。import-only,零状态写入,全离线。
+ */
+export function runRuntimeTrace(repoRoot) {
+    const nodeVersion = process.versions.node;
+    if (!nodeSupportsRegisterHooks()) {
+        return {
+            ok: false,
+            error: `Node ${nodeVersion} 缺少 node:module registerHooks(需 ≥ ${MIN_NODE_FOR_REGISTER_HOOKS.join('.')});无法产生运行模块证据`,
+            nodeVersion,
+            moduleCount: 0,
+            repoModuleCount: 0,
+            loadedRepoModules: [],
+        };
+    }
+    const tsDir = join(repoRoot, 'ts');
+    const outDir = mkdtempSync(join(tmpdir(), 'gotry-kernel-trace-'));
+    const outPath = join(outDir, 'trace.json');
+    const result = spawnSync(process.execPath, ['--import', 'tsx/esm', '--import', join(tsDir, 'scripts', 'kernel-manifest-trace-hook.mjs'), join(tsDir, 'scripts', 'kernel-manifest-trace-entry.ts')], { cwd: tsDir, encoding: 'utf8', timeout: 180_000, env: { ...process.env, KR_TRACE_OUT: outPath } });
+    try {
+        if (result.error) {
+            return { ok: false, error: `trace 子进程失败:${result.error.message}`, nodeVersion, moduleCount: 0, repoModuleCount: 0, loadedRepoModules: [] };
+        }
+        if (result.status !== 0) {
+            return { ok: false, error: `trace 子进程非零退出 ${result.status}:${(result.stderr ?? '').trim().slice(0, 400)}`, nodeVersion, moduleCount: 0, repoModuleCount: 0, loadedRepoModules: [] };
+        }
+        if (!(readFileSync(outPath, 'utf8') ?? '').includes('loaded')) {
+            return { ok: false, error: 'trace 输出缺失或形状不符(load 钩子未记录任何模块)', nodeVersion, moduleCount: 0, repoModuleCount: 0, loadedRepoModules: [] };
+        }
+        const parsed = JSON.parse(readFileSync(outPath, 'utf8'));
+        const repoModules = parsed.loaded
+            .filter((url) => url.startsWith('file://'))
+            .map((url) => repoRelative(repoRoot, fileURLToPath(url)))
+            .filter((rel) => rel.startsWith('ts/') && !rel.includes('/node_modules/') && !rel.startsWith('ts/dsh-runtime/'))
+            .sort();
+        const seen = new Set(repoModules);
+        return { ok: true, nodeVersion, moduleCount: parsed.loaded.length, repoModuleCount: repoModules.length, loadedRepoModules: [...seen] };
+    }
+    finally {
+        try {
+            rmSync(outDir, { recursive: true, force: true });
+        }
+        catch { /* 临时目录清理失败不影响裁决 */ }
+    }
+}
+/** 冻结清单本身的结构纪律(schema/依据/路径形状),与其余校验分离以便单独反证。 */
+export function validateManifestSchema(manifest) {
+    const findings = [];
+    if (manifest.schemaVersion !== MANIFEST_SCHEMA_VERSION) {
+        findings.push({ code: 'manifest-schema-version', detail: `schemaVersion 必须是 ${MANIFEST_SCHEMA_VERSION}(当前 ${manifest.schemaVersion})` });
+    }
+    if (!GIT_SHA_RE.test(manifest.baseSHA ?? '')) {
+        findings.push({ code: 'manifest-base-sha', detail: `baseSHA 必须是 40 位十六进制 git SHA(当前 ${JSON.stringify(manifest.baseSHA)})` });
+    }
+    if (!manifest.frozenAt || typeof manifest.frozenAt !== 'string') {
+        findings.push({ code: 'manifest-frozen-at', detail: 'frozenAt 必须非空(冻结日期)' });
+    }
+    const entries = manifest.entries ?? [];
+    if (entries.length === 0) {
+        findings.push({ code: 'manifest-empty', detail: '内核清单为空:宁窄勿宽,但不允许空清单冒充冻结面' });
+    }
+    const seen = new Set();
+    for (const entry of entries) {
+        if (!KERNEL_PATH_RE.test(entry.path ?? '') || entry.path.includes('..') || isAbsolute(entry.path)) {
+            findings.push({ code: 'manifest-path-shape', detail: `内核路径必须是 ts/src/<module>.ts 形状(当前 ${JSON.stringify(entry.path)})` });
+        }
+        if (FORBIDDEN_KERNEL_PATHS.has(entry.path ?? '')) {
+            findings.push({ code: 'manifest-forbidden-path', detail: `废弃兼容层不得进入内核清单:${entry.path}(AGENTS.md:engine.*/journey.* deprecated)` });
+        }
+        if (seen.has(entry.path))
+            findings.push({ code: 'manifest-duplicate-path', detail: `内核路径重复:${entry.path}` });
+        seen.add(entry.path);
+        if (!KERNEL_GROUPS.includes(entry.group)) {
+            findings.push({ code: 'manifest-group', detail: `group 必须属于 ${KERNEL_GROUPS.join('/')}(当前 ${JSON.stringify(entry.group)})` });
+        }
+        if (!SHA256_RE.test(entry.sha256 ?? '')) {
+            findings.push({ code: 'manifest-sha-shape', detail: `sha256 必须是 64 位十六进制:${entry.path}` });
+        }
+        if (!entry.rationale || entry.rationale.trim().length === 0) {
+            findings.push({ code: 'manifest-rationale-missing', detail: `内核条目缺 rationale(为什么属于内核):${entry.path}` });
+        }
+        if (!entry.basis || entry.basis.trim().length === 0) {
+            findings.push({ code: 'manifest-basis-missing', detail: `内核条目缺 basis(依据:architecture §/ADR/AGENTS 条款):${entry.path}` });
+        }
+    }
+    return toResult(findings);
+}
+/**
+ * 内核零 diff 校验:当前工作区每个内核文件存在且 SHA256 与冻结值一致。
+ * 改核心 → kernel-hash-mismatch;删文件 → kernel-file-missing(事后删文件
+ * 制造零 diff 的反证被此条封死)。
+ */
+export function validateKernelIntegrity(manifest, repoRoot, opts = {}) {
+    const findings = [];
+    for (const entry of manifest.entries ?? []) {
+        const current = fileSha256(repoRoot, entry.path);
+        if (current === null) {
+            findings.push({ code: 'kernel-file-missing', detail: `内核文件缺失(冻结面不允许事后删文件):${entry.path}` });
+            continue;
+        }
+        if (current !== entry.sha256) {
+            findings.push({ code: 'kernel-hash-mismatch', detail: `内核文件被改动:${entry.path}(frozen ${entry.sha256.slice(0, 12)}… → current ${current.slice(0, 12)}…)` });
+        }
+    }
+    if (opts.packagingCheck !== false) {
+        const rootPkgAbs = join(repoRoot, 'package.json');
+        if (existsSync(rootPkgAbs)) {
+            const pkg = JSON.parse(readFileSync(rootPkgAbs, 'utf8'));
+            if (Array.isArray(pkg.files) && pkg.files.length > 0) {
+                for (const entry of manifest.entries ?? []) {
+                    const packaged = pkg.files.some((f) => f === entry.path || entry.path.startsWith(f.endsWith('/') ? f : `${f}/`));
+                    if (!packaged) {
+                        findings.push({ code: 'kernel-not-packaged', detail: `内核文件不在 npm 包 files 面内(发布产物无法内核一致):${entry.path}` });
+                    }
+                }
+            }
+        }
+    }
+    return toResult(findings);
+}
+/**
+ * 功能路径覆盖:同引擎/账本/闸路径各由一个 run-all 套件承载,套件必须真实存在
+ * 且其静态 import 闭包包含所声称的内核模块(缺路径覆盖 → 红)。
+ */
+export function validateFunctionalCoverage(manifest, repoRoot) {
+    const findings = [];
+    const paths = manifest.functionalPaths ?? [];
+    const entries = manifest.entries ?? [];
+    const coveredGroups = new Set();
+    for (const fp of paths) {
+        if (!KERNEL_GROUPS.includes(fp.group)) {
+            findings.push({ code: 'coverage-group', detail: `功能路径 group 非法:${fp.name}(${JSON.stringify(fp.group)})` });
+            continue;
+        }
+        coveredGroups.add(fp.group);
+        if (!Number.isInteger(fp.runAllSection) || fp.runAllSection <= 0) {
+            findings.push({ code: 'coverage-runall-section', detail: `功能路径缺有效 runAllSection:${fp.name}` });
+        }
+        if (typeof fp.suite !== 'string' || !fp.suite.startsWith('ts/scripts/') || fp.suite.includes('..')) {
+            findings.push({ code: 'coverage-suite-path', detail: `功能路径 suite 必须位于 ts/scripts/:${fp.name}(${JSON.stringify(fp.suite)})` });
+            continue;
+        }
+        if (!existsSync(join(repoRoot, fp.suite))) {
+            findings.push({ code: 'coverage-suite-missing', detail: `功能路径套件缺失(缺路径覆盖):${fp.suite}` });
+            continue;
+        }
+        const closure = importClosure(repoRoot, fp.suite);
+        for (const kernelPath of fp.kernelModules ?? []) {
+            const entry = entries.find((e) => e.path === kernelPath);
+            if (!entry) {
+                findings.push({ code: 'coverage-foreign-module', detail: `功能路径声称覆盖的模块不在内核清单:${fp.name} → ${kernelPath}` });
+                continue;
+            }
+            if (entry.group !== fp.group) {
+                findings.push({ code: 'coverage-group-mismatch', detail: `功能路径 group 与内核条目 group 不一致:${fp.name}(${fp.group}) → ${kernelPath}(${entry.group})` });
+            }
+            if (!closure.has(kernelPath)) {
+                findings.push({ code: 'coverage-suite-not-importing-kernel', detail: `套件静态 import 闭包不含内核模块(路径覆盖断裂):${fp.suite} ↛ ${kernelPath}` });
+            }
+        }
+    }
+    for (const entry of entries) {
+        if (!coveredGroups.has(entry.group)) {
+            findings.push({ code: 'coverage-entry-without-path', detail: `内核条目无任何功能路径覆盖:${entry.path}(group ${entry.group})` });
+        }
+    }
+    return toResult(findings);
+}
+/** 证据快照 ↔ 当前树 ↔ 冻结清单 三方一致性(requireLoadedCoverage=false 用于离线审计无 trace 面)。 */
+export function validateEvidence(evidence, manifest, repoRoot, opts = {}) {
+    const findings = [];
+    if (evidence.schemaVersion !== EVIDENCE_SCHEMA_VERSION) {
+        findings.push({ code: 'evidence-schema-version', detail: `schemaVersion 必须是 ${EVIDENCE_SCHEMA_VERSION}(当前 ${evidence.schemaVersion})` });
+    }
+    if (!GIT_SHA_RE.test(evidence.candidateSHA ?? '')) {
+        findings.push({ code: 'evidence-candidate-sha', detail: `candidateSHA 必须是 40 位十六进制(当前 ${JSON.stringify(evidence.candidateSHA)})` });
+    }
+    if (opts.expectedCandidateSha && evidence.candidateSHA !== opts.expectedCandidateSha) {
+        findings.push({ code: 'evidence-candidate-sha-mismatch', detail: `candidateSHA 与当前 HEAD 不一致:${evidence.candidateSHA} ≠ ${opts.expectedCandidateSha}` });
+    }
+    if (evidence.baseSHA !== manifest.baseSHA) {
+        findings.push({ code: 'evidence-base-sha-mismatch', detail: `baseSHA 与冻结清单不一致:${evidence.baseSHA} ≠ ${manifest.baseSHA}` });
+    }
+    if (evidence.manifestRef?.sha256 !== manifestHash(manifest)) {
+        findings.push({ code: 'manifest-hash-mismatch', detail: `manifestHash 与冻结清单不符(清单被改动或快照错绑):${JSON.stringify(evidence.manifestRef?.sha256)} ≠ ${manifestHash(manifest).slice(0, 12)}…` });
+    }
+    if (evidence.evidenceHash !== evidenceHash(evidence)) {
+        findings.push({ code: 'evidence-hash-mismatch', detail: `evidenceHash 与快照内容不符(快照被改动):${JSON.stringify(evidence.evidenceHash)} ≠ ${evidenceHash(evidence).slice(0, 12)}…` });
+    }
+    const integrity = validateKernelIntegrity(manifest, repoRoot);
+    findings.push(...integrity.findings);
+    const coverage = validateFunctionalCoverage(manifest, repoRoot);
+    findings.push(...coverage.findings);
+    const manifestPaths = new Set((manifest.entries ?? []).map((e) => e.path));
+    const evidenceKernel = evidence.kernel ?? [];
+    const evidencePaths = new Set(evidenceKernel.map((k) => k.path));
+    for (const path of manifestPaths) {
+        if (!evidencePaths.has(path))
+            findings.push({ code: 'evidence-kernel-missing', detail: `证据快照缺内核条目:${path}` });
+    }
+    for (const item of evidenceKernel) {
+        if (!manifestPaths.has(item.path)) {
+            findings.push({ code: 'evidence-kernel-foreign', detail: `证据快照出现清单外内核条目:${item.path}` });
+            continue;
+        }
+        const entry = (manifest.entries ?? []).find((e) => e.path === item.path);
+        if (item.sha256Frozen !== entry.sha256) {
+            findings.push({ code: 'evidence-frozen-sha-mismatch', detail: `证据快照冻结哈希与清单不符:${item.path}` });
+        }
+        const current = fileSha256(repoRoot, item.path);
+        if (current !== null && item.sha256Current !== current) {
+            findings.push({ code: 'evidence-current-sha-stale', detail: `证据快照当前哈希与工作区不符(快照未重算):${item.path}` });
+        }
+    }
+    const loaded = new Set(evidence.runtime?.loadedRepoModules ?? []);
+    if (opts.requireLoadedCoverage !== false) {
+        if (loaded.size === 0) {
+            findings.push({ code: 'evidence-trace-empty', detail: '运行模块 trace 为空:缺真实运行 import 证据' });
+        }
+        for (const entry of manifest.entries ?? []) {
+            if (!loaded.has(entry.path)) {
+                findings.push({ code: 'kernel-not-loaded', detail: `内核模块未被真实运行加载(替换/绕过内核的形状):${entry.path}` });
+            }
+        }
+    }
+    return toResult(findings);
+}