@danceiny/gotry 0.0.1-rc.8 → 0.2.0-rc.27

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

@@ -0,0 +1,126 @@
+/**
+ * 内核清单冻结机械闸(issue #234;g5-guard/dsh-target-closure-proof 同形态:
+ * 清单冻结 + 机械校验,不是新政策)。对照真实运行面裁决,漂移即红:
+ *   1. 冻结清单 schema/依据/路径形状纪律(宁窄勿宽,ts/src/ 内核面);
+ *   2. 内核零 diff:当前文件 SHA256 == 冻结值(改核心/删文件 → 红,事后删文件
+ *      制造零 diff 被封死);
+ *   3. 打包面:内核 ⊆ npm 包 files 面(发布产物才可能内核一致);
+ *   4. 真实运行 import trace(默认模式,子进程离线):内核清单全部被产品运行面
+ *      ts/src/index.ts 实际加载(替换/绕过/未加载内核 → 红);
+ *   5. 功能路径覆盖:同引擎/账本/闸路径的 run-all 套件存在且静态 import 闭包
+ *      包含所声称内核模块(缺路径覆盖 → 红);
+ *   6. 证据快照哈希绑定(--verify 审计历史快照):manifestHash/evidenceHash/
+ *      candidateSHA/baseSHA 全对得上(错 SHA → 红)。
+ *
+ * 边界:只输出工程复用证据,不冒充 traveler 效果或 M6 试点签约(issue #234
+ * 验收 4;#137 门注:M6 实施门以 #136 M5 Exit + P6 批准为前提)。
+ *
+ * 用法:cd ts && npx tsx scripts/kernel-manifest-gate.ts [--verify <snapshot.json>] [--out <file>] [--root <dir>] [--manifest <path>] [--manifest-hash <hex>] [--skip-trace]
+ * 退出码:0 = 绿;1 = 漂移/反证成立;2 = 闸自身无法运行(环境/缺文件/trace 失败)。
+ */
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { currentHeadSha, defaultRepoRoot, loadKernelManifest, manifestHash, MANIFEST_REL, nodeSupportsRegisterHooks, runRuntimeTrace, validateEvidence, validateFunctionalCoverage, validateKernelIntegrity, validateManifestSchema, } from './kernel-manifest.js';
+import { buildEvidence } from './kernel-manifest-evidence.js';
+function printFindings(headline, findings) {
+    console.error(`${headline}(${findings.length} 处):`);
+    for (const f of findings)
+        console.error(`  [${f.code}] ${f.detail}`);
+}
+export function main(argv = process.argv.slice(2)) {
+    const argOf = (flag) => {
+        const i = argv.indexOf(flag);
+        return i >= 0 ? argv[i + 1] : undefined;
+    };
+    const repoRoot = resolve(argOf('--root') ?? defaultRepoRoot());
+    const manifestRel = argOf('--manifest') ?? MANIFEST_REL;
+    const verifyPath = argOf('--verify');
+    const outPath = argOf('--out');
+    const manifestHashPin = argOf('--manifest-hash');
+    const skipTrace = argv.includes('--skip-trace');
+    const manifestAbs = resolve(repoRoot, manifestRel);
+    if (!existsSync(manifestAbs)) {
+        console.error(`KERNEL MANIFEST GATE: FAIL(exit 2)— 冻结清单不存在:${manifestRel}`);
+        return 2;
+    }
+    const manifest = loadKernelManifest(repoRoot, manifestRel);
+    const recomputedManifestHash = manifestHash(manifest);
+    if (manifestHashPin && manifestHashPin !== recomputedManifestHash) {
+        console.error(`KERNEL MANIFEST GATE: FAIL — manifestHash 与外部钉值不符:${manifestHashPin} ≠ ${recomputedManifestHash}`);
+        return 1;
+    }
+    if (verifyPath) {
+        // 审计模式:历史快照 ↔ 当前树 ↔ 冻结清单 三方一致性。离线,不重跑 trace;
+        // 快照里的 loadedRepoModules 即生成时刻的运行证据,当前树零 diff 由哈希面证明。
+        let evidence;
+        try {
+            evidence = JSON.parse(readFileSync(resolve(verifyPath), 'utf8'));
+        }
+        catch (err) {
+            console.error(`KERNEL MANIFEST GATE: FAIL(exit 2)— 快照不可读/非法 JSON:${verifyPath}(${err instanceof Error ? err.message : String(err)})`);
+            return 2;
+        }
+        const result = validateEvidence(evidence, manifest, repoRoot, { requireLoadedCoverage: true });
+        if (!result.ok) {
+            printFindings(`KERNEL MANIFEST GATE: FAIL — 快照审计 ${verifyPath} 漂移`, result.findings);
+            return 1;
+        }
+        console.log(`KERNEL MANIFEST GATE: OK — 快照审计通过 ${verifyPath}(manifestHash ${recomputedManifestHash.slice(0, 12)}…,candidateSHA ${evidence.candidateSHA.slice(0, 12)}…,内核 ${evidence.kernel.length} 项对当前树零 diff,功能路径 ${evidence.functionalPaths.length} 条覆盖成立)`);
+        return 0;
+    }
+    // 默认模式:HEAD 全量校验 + 真实运行 import trace。
+    const head = currentHeadSha(repoRoot);
+    if (head === null) {
+        console.error('KERNEL MANIFEST GATE: FAIL(exit 2)— 无法读取 git HEAD(需要 git 仓库)');
+        return 2;
+    }
+    if (!skipTrace && !nodeSupportsRegisterHooks()) {
+        console.error(`KERNEL MANIFEST GATE: FAIL(exit 2)— Node ${process.versions.node} 缺少 node:module registerHooks(需 ≥ 22.15.0),无法产生运行模块证据;可用 --skip-trace 退化为静态面`);
+        return 2;
+    }
+    const staticFindings = [
+        ...validateManifestSchema(manifest).findings,
+        ...validateKernelIntegrity(manifest, repoRoot).findings,
+        ...validateFunctionalCoverage(manifest, repoRoot).findings,
+    ];
+    if (staticFindings.length > 0) {
+        printFindings('KERNEL MANIFEST GATE: FAIL — 内核清单静态面漂移', staticFindings);
+        return 1;
+    }
+    if (skipTrace) {
+        // 静态退化面:零 diff + 打包 + 功能路径成立,但无运行加载证据(显式声明,不冒充完整证据)。
+        console.log(`KERNEL MANIFEST GATE: OK(--skip-trace 静态面,无运行加载证据)— 内核清单零 diff(manifestHash ${recomputedManifestHash.slice(0, 12)}…),功能路径 ${manifest.functionalPaths?.length ?? 0} 条覆盖成立`);
+        return 0;
+    }
+    const trace = runRuntimeTrace(repoRoot);
+    if (!trace.ok) {
+        console.error(`KERNEL MANIFEST GATE: FAIL(exit 2)— ${trace.error}`);
+        return 2;
+    }
+    let evidence;
+    try {
+        evidence = buildEvidence(manifest, { repoRoot, manifestRel, trace, candidateSHA: head });
+    }
+    catch (err) {
+        console.error(`KERNEL MANIFEST GATE: FAIL(exit 2)— 证据组装失败:${err instanceof Error ? err.message : String(err)}`);
+        return 2;
+    }
+    const result = validateEvidence(evidence, manifest, repoRoot, { requireLoadedCoverage: true, expectedCandidateSha: head });
+    if (!result.ok) {
+        printFindings('KERNEL MANIFEST GATE: FAIL — 运行模块证据面漂移', result.findings);
+        return 1;
+    }
+    if (outPath) {
+        writeFileSync(resolve(outPath), JSON.stringify(evidence, null, 2) + '\n');
+    }
+    const notLoaded = evidence.kernel.filter((k) => !k.loadedInTrace);
+    const unloadedNote = notLoaded.length === 0
+        ? `内核 ${evidence.kernel.length}/${evidence.kernel.length} 被真实运行加载`
+        : `内核 ${evidence.kernel.length - notLoaded.length}/${evidence.kernel.length} 被加载`;
+    console.log(`KERNEL MANIFEST GATE: OK — 内核清单零 diff(manifestHash ${recomputedManifestHash.slice(0, 12)}…),${unloadedNote},功能路径 ${evidence.functionalPaths.length} 条覆盖成立,candidateSHA ${head.slice(0, 12)}…${outPath ? `,快照 → ${resolve(outPath)}` : ''}`);
+    return 0;
+}
+const isDirectRun = process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url);
+if (isDirectRun)
+    process.exit(main());

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),不静默。
+  }
+})