@bolloon/bolloon-agent 0.5.5 → 0.6.0

package/dist/kernel/gate-scan.js

@@ -0,0 +1,1036 @@
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+/**
+ * Bolloon Native Macro-Kernel —— K0 门的**判据** (纯函数: 吃源码文本, 出违规清单)
+ *
+ * 为什么判据是纯函数而不是几条 `expect`:
+ *   只有这样, 「变异验证」才能把**人为改坏的源码**喂给**同一份**判据 (测试里真的这么干)。
+ *   先例: src/agents/goal-flywheel/wiring/* 的 scan* + src/test/goal-flywheel-wiring-freeze.test.ts。
+ *
+ * 本文件只 import 名册 (kernel 内部), 自己就是 K1 的样本。
+ */
+import { LAYERS, } from './roster.js';
+import { HISTORY_OPS } from './plan-channel-actor.js';
+/** 行内注释剥掉 (保护 `https://` 这类) —— 拿子串当判据前先剥注释是本仓的硬规矩 */
+export function stripLineComment(line) {
+    const m = line.indexOf('//');
+    if (m < 0)
+        return line;
+    if (line[m - 1] === ':')
+        return line; // https:// 之类
+    return line.slice(0, m);
+}
+export function isCommentOnly(line) {
+    const s = line.trim();
+    return s.startsWith('//') || s.startsWith('*') || s.startsWith('/*') || s.startsWith('*/');
+}
+// 2026-10-02 修真缺陷: 原先只认 `from '...'` 与动态 `import('...')`,
+//   漏掉**副作用 import** (`import './x.js';` —— 既无 from 也无括号) ⇒ 入边被少算 ⇒ 删除候选虚高。
+const FROM_RE = /\bfrom\s*['"]([^'"]+)['"]|\bimport\s*\(\s*['"]([^'"]+)['"]\s*\)|\bimport\s+['"]([^'"]+)['"]/g;
+/** 抽出所有 import/export-from/动态 import 的说明符 + 行号 */
+export function importSpecifiers(text) {
+    const out = [];
+    text.split('\n').forEach((raw, i) => {
+        if (isCommentOnly(raw))
+            return;
+        const line = stripLineComment(raw);
+        FROM_RE.lastIndex = 0;
+        let m;
+        while ((m = FROM_RE.exec(line)) !== null) {
+            const spec = m[1] ?? m[2] ?? m[3];
+            if (spec)
+                out.push({ line: i + 1, spec });
+        }
+    });
+    return out;
+}
+/**
+ * 把说明符解析成「相对 src/ 的路径 (无扩展名)」。
+ * 非相对说明符 (node 内置 / 第三方包) → null: **仓内跨层边**才是本门管的范围。
+ */
+export function resolveFrom(file, spec) {
+    if (!spec.startsWith('.'))
+        return null;
+    const dir = file.includes('/') ? file.slice(0, file.lastIndexOf('/')) : '';
+    const parts = (dir ? dir.split('/') : []).concat(spec.split('/'));
+    const stack = [];
+    for (const p of parts) {
+        if (p === '' || p === '.')
+            continue;
+        if (p === '..')
+            stack.pop();
+        else
+            stack.push(p);
+    }
+    let rel = stack.join('/');
+    if (rel.endsWith('.js'))
+        rel = rel.slice(0, -3);
+    if (rel.endsWith('.jsx'))
+        rel = rel.slice(0, -4);
+    if (rel.endsWith('.mjs'))
+        rel = rel.slice(0, -4);
+    return rel || null;
+}
+/** 这个路径属于哪一层 (目录前缀 或 精确文件) */
+export function layerOf(rel) {
+    for (const layer of LAYERS) {
+        for (const p of layer.paths) {
+            if (p.endsWith('/') ? rel.startsWith(p) : rel === p)
+                return layer.id;
+        }
+    }
+    return null;
+}
+export function filesOfLayer(files, layer) {
+    return files.filter((f) => layerOf(f.path) === layer);
+}
+const KERNEL_BOUNDARY = 'kernel-dir-boundary';
+/**
+ * K1 —— kernel 目录的每一条仓内 import 都必须落在允许前缀里。
+ * 违规 = 内核自己伸手去摸业务模块 (那正是 pi-sdk.ts 长成 4099 行单体的成因)。
+ */
+export function scanKernelImports(kernel, allowedPrefixes) {
+    const out = [];
+    for (const f of kernel) {
+        for (const { line, spec } of importSpecifiers(f.text)) {
+            const rel = resolveFrom(f.path, spec);
+            if (rel === null)
+                continue; // node / 第三方
+            if (allowedPrefixes.some((p) => rel.startsWith(p)))
+                continue;
+            out.push({ rule: KERNEL_BOUNDARY, file: f.path, line, what: `${spec} → ${rel}` });
+        }
+    }
+    return out;
+}
+/** K2 —— 一条禁令在给定源码面上的全部命中 */
+export function scanProhibition(files, p) {
+    const out = [];
+    const targets = p.targets ?? [];
+    const calls = p.writeCalls ?? [];
+    const callRe = calls.length ? new RegExp(`\\b(${calls.join('|')})\\s*\\(`) : null;
+    for (const f of files) {
+        if (p.mode === 'import-edge') {
+            for (const { line, spec } of importSpecifiers(f.text)) {
+                const rel = resolveFrom(f.path, spec);
+                if (rel === null)
+                    continue;
+                if (targets.some((t) => rel === t || rel.startsWith(`${t}/`))) {
+                    out.push({ rule: p.id, file: f.path, line, what: `import ${spec}` });
+                }
+            }
+            continue;
+        }
+        // write-call: 只认**调用**(读不算) —— 定义处/import 解构都带不出 `(`
+        f.text.split('\n').forEach((raw, i) => {
+            if (isCommentOnly(raw))
+                return;
+            const line = stripLineComment(raw);
+            if (!callRe)
+                return;
+            const m = callRe.exec(line);
+            if (m)
+                out.push({ rule: p.id, file: f.path, line: i + 1, what: `${m[1]}()` });
+        });
+    }
+    return out;
+}
+/** 把命中归并成 (rule|file|call/import) → 次数, 供与欠账台账**逐字相等**比对 */
+export function groupFindings(findings) {
+    const m = new Map();
+    for (const f of findings) {
+        const call = f.what.replace(/\(\)$/, '').replace(/^import\s+/, '');
+        const key = `${f.rule}|${f.file}|${call}`;
+        m.set(key, (m.get(key) ?? 0) + 1);
+    }
+    return [...m.entries()].map(([key, count]) => ({ key, count })).sort((a, b) => a.key.localeCompare(b.key));
+}
+/** 与欠账台账比对: 双向相等 (多一条红 / 少一条也红, 强制台账与事实同步) */
+export function debtDiff(findings, debt, rule) {
+    const actual = groupFindings(findings).filter((g) => g.key.startsWith(`${rule}|`));
+    const want = debt
+        .filter((d) => d.prohibition === rule)
+        .map((d) => `${d.prohibition}|${d.file}|${d.call}|${d.count}`)
+        .sort();
+    const got = actual.map((g) => `${g.key}|${g.count}`).sort();
+    return {
+        missing: got.filter((g) => !want.includes(g)),
+        extra: want.filter((w) => !got.includes(w)),
+    };
+}
+/** K3 —— 行数 (整文件行数; 空行也算, 因为预算量的是「文件有多大」) */
+export function countCodeLines(files) {
+    return files.reduce((n, f) => n + f.text.split('\n').filter((_, i, a) => i < a.length - (a[a.length - 1] === '' ? 1 : 0)).length, 0);
+}
+/** 归属判定 = **最长前缀** (目录键以 / 结尾按前缀, 文件键按相等)。null = 无归属 ⇒ 门判红。 */
+export function ownerOfFile(rel, owners) {
+    let best = null;
+    for (const o of owners) {
+        const hit = o.key.endsWith('/') ? rel.startsWith(o.key) : rel === o.key;
+        if (hit && (!best || o.key.length > best.key.length))
+            best = o;
+    }
+    return best;
+}
+export function scanOwnerCoverage(files, owners) {
+    const out = [];
+    for (const f of files) {
+        if (!ownerOfFile(f.path, owners))
+            out.push({ rule: 'owner-coverage', file: f.path, line: 1, what: '无 owner' });
+    }
+    return out;
+}
+/** owner 名册里声明了但盘上不存在的键 (空承诺) —— 先例: 冻结门的「名册路径必须真实存在」 */
+export function scanOwnerPromises(owners, exists) {
+    return owners
+        .filter((o) => !exists(o.key))
+        .map((o) => ({ rule: 'owner-promise', file: o.key, line: 1, what: '名册声明但盘上不存在' }));
+}
+const PROMPT_CALL_RE = /([\w\.\)\]]+)\s*\.\s*(prompt|promptStream|promptWithPivotLoop)\s*\(/;
+const PROMPT_DEF_RE = /^(export\s+)?(async\s+)?(prompt|promptStream|promptWithPivotLoop)\s*\(/;
+/** 重算全仓入口调用点 (与 ENTRY_GRAPH 逐字比对; 任何新旁路都会浮出来) */
+export function scanEntrySites(files, adapterFiles = ['agents/pi-sdk.ts']) {
+    const m = new Map();
+    for (const f of files) {
+        f.text.split('\n').forEach((raw) => {
+            if (isCommentOnly(raw))
+                return;
+            const line = stripLineComment(raw);
+            if (PROMPT_DEF_RE.test(line.trim()))
+                return;
+            const hit = PROMPT_CALL_RE.exec(line);
+            if (!hit)
+                return;
+            const recv = hit[1];
+            const kind = adapterFiles.includes(f.path)
+                ? 'adapter-internal'
+                : recv === 'this' ? 'readline-tui' : 'agent-entry';
+            const key = `${f.path}|${kind}|${hit[2]}`;
+            const prev = m.get(key);
+            m.set(key, { file: f.path, kind, method: hit[2], count: (prev?.count ?? 0) + 1 });
+        });
+    }
+    return [...m.values()].sort((a, b) => `${a.file}|${a.kind}|${a.method}`.localeCompare(`${b.file}|${b.kind}|${b.method}`));
+}
+export function entryGraphDiff(actual, declared) {
+    const key = (e) => `${e.file}|${e.kind}|${e.method}|${e.count}`;
+    const got = actual.map(key).sort();
+    const want = declared.map(key).sort();
+    return { extra: got.filter((g) => !want.includes(g)), missing: want.filter((w) => !got.includes(w)) };
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// K0 ④ 旧代码删除台账
+// ─────────────────────────────────────────────────────────────────────────────
+const DELETION_FIELDS = [
+    'target', 'oldEntry', 'replacement', 'remainingRefs',
+    'runtimeHits', 'acceptance', 'rollbackCommit', 'deletedAt',
+];
+/** 8 字段缺一律红 (leo 的五个删除条件之 ②: 剩余引用必须为 0) */
+export function validateDeletionRecord(rec) {
+    const bad = [];
+    for (const f of DELETION_FIELDS) {
+        const v = rec[f];
+        if (v === undefined || v === null || v === '')
+            bad.push(f);
+        if (f === 'remainingRefs' && v !== 0)
+            bad.push('remainingRefs≠0');
+    }
+    return bad;
+}
+/** 第一批删除候选 = 产品码里 **0 入边引用** 且非入口形态 (机械派生, 不手写) */
+const ENTRY_SHAPE_RE = /(index\.ts$|cli-entry\.ts$|electron\.ts$|\.d\.ts$|server\.ts$|main\.ts$|route|command|register|setup|bootstrap|migration|types\.ts$|constants?\.ts$|config)/;
+/**
+ * **豁免规则 (2026-10-02)**: 冻结面自身的文件 (KERNEL_FILES 成员 —— `kernel/roster.ts` / `kernel/plan*.ts`)
+ * **不算删除候选**。它们是台账/名册, 在"0 入边"口径下天然是孤岛, 每加一个台账就会让候选集变一次
+ * (已因此被迫改过三次 sha)。删除台账不是"删死代码", 走的是它自己的 8 字段记录流程。
+ */
+// 2026-10-02 (第 4 次候选集漂移后定的根规则): **kernel 冻结面整体不算删除候选**。
+//   理由: ① 台账/名册在"0 入边"口径下天然是孤岛, 每加一个就改一次 sha (已四次);
+//        ② 只被测试 import 的产品文件 (如 channel-actor.ts 这种"先落容器、后接线"的基建) 同样会被误判成死码;
+//        ③ kernel 内部要删东西, 走的是它自己的 8 字段删除记录流程, 不是"删死代码"。
+const LEDGER_SELF_EXEMPT = /^kernel\//;
+export function deletionCandidates(files) {
+    const paths = new Set(files.map((f) => f.path));
+    const inbound = new Map();
+    for (const f of files) {
+        for (const { spec } of importSpecifiers(f.text)) {
+            const rel = resolveFrom(f.path, spec);
+            if (!rel)
+                continue;
+            for (const c of [rel + '.ts', rel + '.tsx', rel + '/index.ts']) {
+                if (paths.has(c))
+                    inbound.set(c, (inbound.get(c) ?? 0) + 1);
+            }
+        }
+    }
+    return files
+        .map((f) => f.path)
+        .filter((p) => (inbound.get(p) ?? 0) === 0 && !ENTRY_SHAPE_RE.test(p) && !LEDGER_SELF_EXEMPT.test(p))
+        .sort();
+}
+/** 归属 = 最长前缀; 入参 rel 相对 constraint-runtime/ */
+export function constraintClassOf(rel, rules) {
+    let best = null;
+    for (const r of rules) {
+        const hit = r.key.endsWith('/') ? rel.startsWith(r.key) : rel === r.key;
+        if (hit && (!best || r.key.length > best.key.length))
+            best = r;
+    }
+    return best;
+}
+/** 每个源码文件必须恰好命中一条规则 (BUILD/META 子树另算) */
+export function scanConstraintCoverage(sourceFiles, rules) {
+    const out = [];
+    for (const rel of sourceFiles) {
+        if (!constraintClassOf(rel, rules))
+            out.push({ rule: 'constraint-coverage', file: rel, line: 1, what: '未分类' });
+    }
+    return out;
+}
+/** 说明符 → 台账里的目标键 (包入口 / 去掉 src|dist 前缀与 .js) */
+export function constraintTargetOf(spec) {
+    if (!spec.includes('constraint-runtime'))
+        return null;
+    if (/^@bolloon\/constraint-runtime$/.test(spec))
+        return '__pkg_entry__';
+    const marker = 'constraint-runtime/';
+    const i = spec.lastIndexOf(marker);
+    if (i < 0)
+        return '__pkg_entry__';
+    return spec.slice(i + marker.length).replace(/^(src|dist)\//, '').replace(/\.js$/, '');
+}
+/**
+ * 目标键 → 规则键。
+ * 台账里的 target 是**模块名**(无扩展名, 如 `tools/SafeSDK/deploySafe`), 而名册键是**文件路径**
+ * (如 `src/tools/SafeSDK/deploySafe.ts`) ⇒ 三种写法都试 (裸名 / +.ts / +/index.ts)。
+ */
+export function constraintRuleOfTarget(target, rules) {
+    if (target === '__pkg_entry__')
+        return rules.find((r) => r.key === '__pkg_entry__') ?? null;
+    return constraintClassOf(`src/${target}`, rules)
+        ?? constraintClassOf(`src/${target}.ts`, rules)
+        ?? constraintClassOf(`src/${target}/index.ts`, rules);
+}
+/** 重算主仓 (非 constraint-runtime 子树) 对 constraint-runtime 的全部引用点 */
+export function scanConstraintUses(files, constraintRoot) {
+    const m = new Map();
+    for (const f of files) {
+        if (f.path.startsWith(constraintRoot))
+            continue;
+        const kind = f.path.startsWith('test/') ? 'test' : 'prod';
+        for (const { spec } of importSpecifiers(f.text)) {
+            const target = constraintTargetOf(spec);
+            if (!target)
+                continue;
+            const key = `${f.path}|${target}|${kind}`;
+            const prev = m.get(key);
+            m.set(key, { file: f.path, target, count: (prev?.count ?? 0) + 1, kind });
+        }
+    }
+    return [...m.values()].sort((a, b) => key2(a).localeCompare(key2(b)));
+}
+function key2(r) { return `${r.file}|${r.target}|${r.kind}`; }
+export function constraintUseDiff(actual, declared) {
+    const k = (r) => `${r.file}|${r.target}|${r.kind}|${r.count}`;
+    const got = actual.map(k).sort();
+    const want = declared.map(k).sort();
+    return { extra: got.filter((g) => !want.includes(g)), missing: want.filter((w) => !got.includes(w)) };
+}
+/**
+ * 越界引用 (K1 的核心判据):
+ *   · C 类被 **prod** 引用 ⇒ 违规 (不许被 Kernel 侧 import);
+ *   · B 类被 **prod** 直接引用 ⇒ 欠账 (只能经 Tool Capability 接入, K7 还清)。
+ */
+export function scanConstraintViolations(uses, rules) {
+    const cViolations = [];
+    const bDebt = [];
+    for (const u of uses) {
+        if (u.kind !== 'prod')
+            continue;
+        const rule = constraintRuleOfTarget(u.target, rules);
+        if (!rule)
+            cViolations.push({ rule: 'constraint-unclassified-use', file: u.file, line: 1, what: u.target });
+        else if (rule.cls === 'C' || rule.cls === 'BUILD' || rule.cls === 'META')
+            cViolations.push({ rule: 'constraint-c-imported-by-prod', file: u.file, line: 1, what: `${u.target} (${rule.cls})` });
+        else if (rule.cls === 'B')
+            bDebt.push(u);
+    }
+    return { cViolations, bDebt };
+}
+/** 台账自身与门自身不算"引用" (否则会自己指自己) */
+function isGateOwnFile(rel) {
+    return rel.startsWith('kernel/') || /^test\/kernel-[\w-]+\.test\.ts$/.test(rel);
+}
+/**
+ * verdict 同步判据:
+ *   ready   ⇒ 目标在盘上存在 **且** 仓内(排除门自身) 0 引用 —— 有引用就不许 ready;
+ *   blocked ⇒ 每个 blocker 文件存在 **且** 它现在还真的提到这个目标 —— blocker 消失就必须改判 ready;
+ *   done    ⇒ 目标不在盘上 **且** DELETION_LEDGER 里有对应记录 (删了必须留账)。
+ */
+export function scanDeletionVerdictSync(files, verdicts, opts) {
+    const out = [];
+    const scannable = files.filter((f) => !isGateOwnFile(f.path) && !f.path.startsWith('constraint-runtime/dist/'));
+    for (const v of verdicts) {
+        // basename 去扩展名: 目标常写作路径 (.../remote_runtime.ts), 而引用处写作模块名 (remote_runtime.js)
+        const basename = v.needle ?? v.target.replace(/\/$/, '').split('/').pop().replace(/\.(tsx?|js|mjs|json|cjs)$/, '');
+        if (v.verdict === 'ready') {
+            if (!opts.exists(v.target)) {
+                out.push({ rule: 'deletion-ready-but-missing', file: v.target, line: 1, what: '标了 ready 但盘上不存在 (是不是已删? 那要改 done + 记台账)' });
+                continue;
+            }
+            const refs = scannable.filter((f) => !f.path.startsWith(v.target.replace(/^src\//, '')) && f.text.includes(basename));
+            for (const r of refs.slice(0, 5)) {
+                out.push({ rule: 'deletion-ready-with-refs', file: r.path, line: 1, what: `标了 ready 但这里提到 ${basename}` });
+            }
+            continue;
+        }
+        if (v.verdict === 'blocked') {
+            if (v.blockers.length === 0) {
+                out.push({ rule: 'deletion-blocked-without-evidence', file: v.target, line: 1, what: '标了 blocked 却给不出 blocker' });
+                continue;
+            }
+            for (const b of v.blockers) {
+                if (!opts.exists(b.file)) {
+                    out.push({ rule: 'deletion-stale-blocker', file: b.file, line: 1, what: `blocker 文件已不存在 (blocker 该重算了)` });
+                    continue;
+                }
+                // blocker 的"还成立吗"判据 = 该文件现在仍然提到这个目标 (扫得到就行; 扫不到 = 借口过期)
+                const hit = scannable.find((f) => f.path === b.file && f.text.includes(basename));
+                if (!hit)
+                    out.push({ rule: 'deletion-stale-blocker', file: b.file, line: 1, what: `blocker 已不再提到 ${basename} ⇒ 必须改判` });
+            }
+            continue;
+        }
+        if (v.verdict === 'not-deletable') {
+            // 明确"不许删"的一类 (环境声明等): 必须给出 blocker 且文件在盘上
+            if (v.blockers.length === 0)
+                out.push({ rule: 'deletion-blocked-without-evidence', file: v.target, line: 1, what: 'not-deletable 却没有依据' });
+            if (!opts.exists(v.target))
+                out.push({ rule: 'deletion-missing', file: v.target, line: 1, what: '标了 not-deletable 但盘上没了' });
+            continue;
+        }
+        // done
+        if (opts.exists(v.target))
+            out.push({ rule: 'deletion-done-but-present', file: v.target, line: 1, what: '标了 done 但盘上还在' });
+        if (!opts.ledgerTargets.includes(v.target))
+            out.push({ rule: 'deletion-done-without-record', file: v.target, line: 1, what: '标了 done 但没有删除记录' });
+    }
+    return out;
+}
+/**
+ * 判据 (吃源码文本, **先剥注释**):
+ *   · 逐字段 `this.<name>` 实测计数必须与冻结值**双向相等**
+ *     —— 多一处 = 新增泄漏; 少一处 = 改了代码没改账 (要求显式 rebase, 迁移必须是看得见的动作);
+ *   · `migrated: true` 的字段访问必须为 0 —— 否则是假完成;
+ *   · 每个字段的 `into` 必须落在 RunContext 目标清单里 —— 不然"外置"没有落点。
+ */
+export function scanRunContextLeaks(files, fields, opts) {
+    const out = [];
+    for (const f of fields) {
+        if (!opts.target.includes(f.into)) {
+            out.push({ rule: 'runcontext-field-without-home', file: f.name, line: 1, what: `into='${f.into}' 不在 RunContext 目标清单里` });
+        }
+        // 口径: **匹配次数** (不是行数) —— 与 scanRunIdSeed 一致。一行含两处就读 2
+        //   (2026-10-02 踩过: 两个判据一个按行、一个按匹配 ⇒ 同一条台账给出 37 / 38 两个答案)
+        const rx = new RegExp(`this\\.${f.name}\\b`, 'g');
+        let actual = 0;
+        for (const file of files) {
+            for (const raw of file.text.split('\n')) {
+                actual += (stripLineComment(raw).match(rx) || []).length;
+            }
+        }
+        if (actual !== f.accesses) {
+            out.push({
+                rule: 'runcontext-access-drift',
+                file: f.name,
+                line: 1,
+                what: `实测 ${actual} 处 ≠ 冻结 ${f.accesses} 处 (${actual > f.accesses ? '新增泄漏' : '已减少 ⇒ 必须把台账下调到实测值'})`,
+            });
+        }
+        if (f.migrated && actual > 0) {
+            out.push({ rule: 'runcontext-migrated-but-leaking', file: f.name, line: 1, what: `标了 migrated 但还有 ${actual} 处 this. 访问` });
+        }
+    }
+    return out;
+}
+/** K2 收尾: 从 seedRunContext 助手体里数"播种读取" —— 只数**助手体内**, 不数全仓同形字符串 */
+export function extractSeedHelper(text) {
+    const i = text.indexOf('private seedRunContext(');
+    if (i < 0)
+        return '';
+    const j = text.indexOf('\n  }', i);
+    return j < 0 ? text.slice(i) : text.slice(i, j + 4);
+}
+/**
+ * 判据 (吃源码文本, **先剥注释**):
+ *   · `currentRunId` 总访问数 == 冻结值 (任何新读取点都判红, 含循环内部);
+ *   · 播种读取 (`runId: this.currentRunId`) 恰好 `seedReads` 处, **且只在 seedRunContext 助手体内**;
+ *   · 调用播种的入口数 == `seedSites` (且都必须在循环方法之外 —— 由"播种只存在于助手"间接保证);
+ *   · 复位点 (`this.runCtx = createRunContext()`) 不得带播种 (清空不许携带身份)。
+ */
+export function scanRunIdSeed(files, opts) {
+    const out = [];
+    const code = files.map((f) => f.text.split('\n').map(stripLineComment).join('\n')).join('\n');
+    const total = (code.match(/this\.currentRunId\b/g) || []).length; // 批次5 后应为 0 (名字已从 pi-sdk 消失)
+    if (total !== opts.frozenTotal) {
+        out.push({ rule: 'runid-access-drift', file: 'agents/pi-sdk.ts', line: 1, what: `currentRunId 实测 ${total} 处 ≠ 冻结 ${opts.frozenTotal} (循环内不得新增读取点; 减少也要下调台账)` });
+    }
+    const helper = extractSeedHelper(code);
+    // 批次5: 播种读取读的是**本体** (actor.state.activeRun) —— 语义不变 (仍是"恰好一处, 且在播种体内")
+    const seedInHelper = (helper.match(/runId: this\.actor!\.state\.activeRun\b/g) || []).length;
+    const seedAnywhere = (code.match(/runId: this\.currentRunId\b/g) || []).length;
+    if (seedInHelper !== opts.seedReads) {
+        out.push({ rule: 'runid-seed-count', file: 'agents/pi-sdk.ts', line: 1, what: `seedRunContext 体内播种读取 ${seedInHelper} 处 ≠ 冻结 ${opts.seedReads}` });
+    }
+    // 注: 这里**不**判"全文件播种模式出现几次" —— harness 上下文 / startRun 等处本就有同形字符串
+    // (`runId: this.currentRunId || undefined` 等), 那条规则会假阳性。别处偷偷加播种已由上面的
+    // "总访问数 == 冻结值" 覆盖 (任何新读取点都会让总数变)。2026-10-02 实测: 该规则误报 8 处后删除。
+    const sites = (code.match(/this\.seedRunContext\(/g) || []).length;
+    if (sites !== opts.seedSites) {
+        out.push({ rule: 'runid-seed-sites', file: 'agents/pi-sdk.ts', line: 1, what: `调用播种的入口 ${sites} 处 ≠ 冻结 ${opts.seedSites}` });
+    }
+    const resets = (code.match(/this\.runCtx = createRunContext\(\)/g) || []).length;
+    if ((code.match(/this\.runCtx = this\.seedRunContext\(\)/g) || []).length > 0) {
+        out.push({ rule: 'runid-seed-on-reset', file: 'agents/pi-sdk.ts', line: 1, what: '复位点带了播种 (清空不许携带身份)' });
+    }
+    if (resets < 5)
+        out.push({ rule: 'runid-reset-missing', file: 'agents/pi-sdk.ts', line: 1, what: `复位点只剩 ${resets} 处 (期望 ≥5)` });
+    return out;
+}
+/**
+ * 判据 (纯函数; 盘上事实由 `exists` 注入):
+ *   ① 清单完整: Actor 状态 9 项 (名字唯一) · 验收 ≥6 · 步骤 8 · 删除前置 7;
+ *   ② **与盘上事实同步**: 标 `not-started` ⇒ 容器文件**必须不存在**; 容器存在 ⇒ stage 必须已过 not-started;
+ *   ③ 进度棘轮: `fieldsMigrated ≤ fieldsTotal` · `entriesWired ≤ entriesTotal` · not-started ⇒ 两个计数都必须是 0;
+ *   ④ **跨台账一致**: 从 K2 移交的 4 个 session 字段, 其冻结访问数必须与 K2 台账逐字相等;
+ *   ⑤ 验收标准里必须真的接住从 K2 移过来的那条 (history 不互相污染)。
+ */
+export function scanActorLedger(ledger, opts) {
+    const out = [];
+    const f = (rule, what) => out.push({ rule, file: 'kernel/plan-channel-actor.ts', line: 1, what });
+    // ① 完整性
+    if (ledger.stateItems.length !== 9)
+        f('actor-state-count', `Actor 状态项 ${ledger.stateItems.length} 项 ≠ 9`);
+    const names = ledger.stateItems.map((i) => i.name);
+    if (new Set(names).size !== names.length)
+        f('actor-state-dup', 'Actor 状态项有重名');
+    for (const i of ledger.stateItems) {
+        if (!i.name || !i.why || !i.owner)
+            f('actor-state-shape', `状态项字段不全: ${i.name || '(空)'}`);
+    }
+    if (ledger.acceptance.length < 6)
+        f('actor-acceptance-count', `验收标准 ${ledger.acceptance.length} 条 < 6`);
+    if (ledger.steps.length !== 8)
+        f('actor-steps-count', `迁移步骤 ${ledger.steps.length} 步 ≠ 8`);
+    if (ledger.preconditions.length !== 7)
+        f('actor-precond-count', `删除前置 ${ledger.preconditions.length} 条 ≠ 7`);
+    if (!ledger.acceptance.some((a) => a.includes('history') && (a.includes('污染') || a.includes('隔离')))) {
+        f('actor-handoff-missing', '验收标准没有接住从 K2 移来的「history 不互相污染」');
+    }
+    // ② 与盘上事实同步
+    const containerExists = opts.exists(ledger.progress.containerPath);
+    if (ledger.progress.stage === 'not-started' && containerExists) {
+        f('actor-stage-stale', `标了 not-started 但 ${ledger.progress.containerPath} 已存在 ⇒ 台账该改`);
+    }
+    if (ledger.progress.stage !== 'not-started' && !containerExists) {
+        f('actor-container-missing', `stage=${ledger.progress.stage} 但容器文件不存在 ⇒ 假进度`);
+    }
+    // ③ 进度棘轮
+    if (ledger.progress.fieldsMigrated > ledger.progress.fieldsTotal)
+        f('actor-fields-overflow', 'fieldsMigrated > fieldsTotal');
+    if (ledger.progress.entriesWired > ledger.progress.entriesTotal)
+        f('actor-entries-overflow', 'entriesWired > entriesTotal');
+    if (ledger.progress.entrySites.wired > ledger.progress.entrySites.total)
+        f('actor-entrysites-overflow', 'entrySites.wired > entrySites.total');
+    if (ledger.progress.stage === 'not-started' && (ledger.progress.fieldsMigrated !== 0 || ledger.progress.entriesWired !== 0)) {
+        f('actor-progress-premature', 'not-started 阶段不许有非零进度');
+    }
+    // ③b 进度位不许自说自话: 迁了几个字段, 就得逐个点名 (名字还必须都在移交字段里)
+    const migrated = ledger.progress.migratedFieldNames ?? [];
+    if (migrated.length !== ledger.progress.fieldsMigrated) {
+        f('actor-fieldnames-mismatch', `fieldsMigrated=${ledger.progress.fieldsMigrated} 但名单 ${migrated.length} 个 ⇒ 进度位与名单不一致`);
+    }
+    for (const n of migrated) {
+        if (!ledger.inheritedFields.some((x) => x.name === n)) {
+            f('actor-fieldnames-unknown', `已迁名单里的 ${n} 不在移交字段 (K5_INHERITED_FIELDS) 里`);
+        }
+    }
+    if (ledger.progress.stage === 'fields-migrated' && ledger.progress.fieldsMigrated !== ledger.progress.fieldsTotal) {
+        f('actor-stage-ahead', `stage=fields-migrated 但 fieldsMigrated=${ledger.progress.fieldsMigrated}/${ledger.progress.fieldsTotal} ⇒ 阶段名超前`);
+    }
+    // ③c history 操作搬迁位: 搬了几个操作就得逐个点名, 名字必须 ∈ HISTORY_OPS, 且不许超总量
+    const ops = ledger.progress.historyOpsNames ?? [];
+    if (ops.length !== ledger.progress.historyOpsMigrated) {
+        f('actor-ops-mismatch', `historyOpsMigrated=${ledger.progress.historyOpsMigrated} 但名单 ${ops.length} 个 ⇒ 进度位与名单不一致`);
+    }
+    if (ledger.progress.historyOpsMigrated > ledger.progress.historyOpsTotal)
+        f('actor-ops-overflow', 'historyOpsMigrated > historyOpsTotal');
+    for (const n of ops) {
+        if (!HISTORY_OPS.includes(n))
+            f('actor-ops-unknown', `已搬操作 ${n} 不在 HISTORY_OPS 里`);
+    }
+    // ④ 跨台账一致 (K2 → K5)
+    for (const k5 of ledger.inheritedFields) {
+        const k2 = opts.k2SessionFields.find((x) => x.name === k5.name);
+        if (!k2) {
+            f('actor-inherit-unknown', `移交字段 ${k5.name} 在 K2 台账里找不到`);
+            continue;
+        }
+        if (k2.accesses !== k5.accesses) {
+            f('actor-inherit-drift', `${k5.name} 访问数 K5=${k5.accesses} ≠ K2=${k2.accesses} (两个台账必须逐字相等)`);
+        }
+    }
+    if (ledger.inheritedFields.length !== opts.k2SessionFields.length) {
+        f('actor-inherit-count', `移交字段 ${ledger.inheritedFields.length} 个 ≠ K2 session 级 ${opts.k2SessionFields.length} 个`);
+    }
+    return out;
+}
+/**
+ * **K2 ↔ K5 交接契约** (2026-10-02 定): session 级字段必须**仍是实例字段**,
+ * **除非 K5 台账 (migratedFieldNames) 声明它已迁**。
+ *
+ * 为什么需要这条: K2 的镜像规则原本是"session 级字段一律不许离开实例" —— 那是 K2 阶段的口径;
+ * K5 第 4 步要做的事正是把 `messageHistory` 迁走。若把禁令写死, K5 一到就得改门 (门就成了橡皮章);
+ * 若把禁令删掉, 半搬状态没人拦。⇒ 让**台账**当唯一的开关: 声明了才放行, 声明了不存在的字段也判红。
+ */
+export function scanSessionFieldResidence(code, sessionFields, migratedByK5) {
+    const out = [];
+    const migrated = new Set(migratedByK5);
+    for (const f of sessionFields) {
+        if (migrated.has(f.name))
+            continue; // K5 已声明迁移 ⇒ 允许离开实例
+        if (!new RegExp(`private\\s+${f.name}\\s*[=:]`).test(code)) {
+            out.push({
+                rule: 'session-field-vanished',
+                file: 'agents/pi-sdk.ts',
+                line: 1,
+                what: `session 级字段 ${f.name} 既不在实例上, K5 台账也没声明迁移它 ⇒ 半搬状态`,
+            });
+        }
+    }
+    for (const n of migratedByK5) {
+        if (!sessionFields.some((f) => f.name === n)) {
+            out.push({
+                rule: 'k5-migration-unknown-field',
+                file: 'kernel/plan-channel-actor.ts',
+                line: 1,
+                what: `K5 声明迁移了 ${n}, 但它不是 K2 的 session 级字段`,
+            });
+        }
+    }
+    return out;
+}
+/**
+ * **K5 第 4 步 — history 写入的"唯一漏斗"判据**。
+ *
+ * 迁移前的盘上事实 (2026-10-02 实测, 记在台账 `HISTORY_WRITE_SITES`):
+ *   `this.messageHistory.push(` × 31 · `this.messageHistory.pop()` × 1 · 整体赋值 `this.messageHistory = ` × 3
+ * 迁移目标: 全部收敛到三个漏斗方法 —— `pushHistory` / `popHistory` / `replaceHistory`。
+ * ⇒ 判据: 每个直写模式在 `pi-sdk.ts` 里**必须是 0 处** (漏斗本体写 `this._history` / actor 方法, 不碰 `this.messageHistory`),
+ *    且三个漏斗方法必须真的存在。
+ * (注释必须先由调用方剥掉 —— 否则文档里的示例会被当成真写入。)
+ */
+export const HISTORY_WRITE_PATTERNS = [
+    { id: 'push', src: 'this\\.messageHistory\\.push\\(' },
+    { id: 'pop', src: 'this\\.messageHistory\\.pop\\(\\)' },
+    { id: 'assign', src: 'this\\.messageHistory\\s*=\\s' },
+];
+/**
+ * 漏斗判据 —— 漏斗清单**由台账传入** (`plan-channel-actor.ts` 的 `HISTORY_WRITE_FUNNEL`): 台账是数据, 判据是纯函数。
+ *   (曾经这里另抄了一份同名常量 = 两份真相, 改台账不改它就会让判据看着还绿。)
+ */
+export function scanHistoryWriteSites(code, funnel) {
+    const out = [];
+    for (const p of HISTORY_WRITE_PATTERNS) {
+        const n = (code.match(new RegExp(p.src, 'g')) ?? []).length;
+        // 迁移后直写必须为 **0** —— 漏斗本体写的是 `this._history` / actor 的方法, 不碰 `this.messageHistory`
+        if (n > 0) {
+            out.push({
+                rule: `history-direct-${p.id}`,
+                file: 'agents/pi-sdk.ts',
+                line: 1,
+                what: `还有 ${n} 处 ${p.id} 直写 ⇒ 绕过了唯一漏斗 (pushHistory/popHistory/replaceHistory)`,
+            });
+        }
+    }
+    // 拿不到事实就拒跑 (不许"跳过")
+    if (!funnel || funnel.length === 0) {
+        return [{ rule: 'history-funnel-missing', file: 'agents/pi-sdk.ts', line: 1, what: '漏斗清单为空/拿不到 ⇒ 拒跑 (不许跳过)' }];
+    }
+    for (const f of funnel) {
+        // ① 声明必须在 (类方法声明: 行首缩进 + 可选可见性修饰符 + 名字 + "(")
+        const declared = new RegExp(`^\\s*(?:private\\s+|public\\s+)?${f.name}\\(`, 'm').test(code);
+        // ② 可见性必须与账一致 —— TS 里 public 是**默认**, 所以判"没有 private 修饰符"而不是"有 public"
+        const isPrivate = new RegExp(`^\\s*private\\s+${f.name}\\(`, 'm').test(code);
+        if (!declared) {
+            out.push({ rule: 'history-funnel-missing', file: 'agents/pi-sdk.ts', line: 1,
+                what: `写入漏斗 ${f.name} 不见了 (调用点会全部落到直写或编译失败)` });
+        }
+        else if (f.vis === 'private' && !isPrivate) {
+            out.push({ rule: 'history-funnel-missing', file: 'agents/pi-sdk.ts', line: 1,
+                what: `漏斗 ${f.name} 账上是 private, 盘上已不是 (可见性改动必须现形于台账)` });
+        }
+        else if (f.vis === 'public' && isPrivate) {
+            out.push({ rule: 'history-funnel-missing', file: 'agents/pi-sdk.ts', line: 1,
+                what: `漏斗 ${f.name} 账上是 public (唯一"种历史"入口), 盘上仍标 private` });
+        }
+    }
+    return out;
+}
+/**
+ * **K5 步骤④ — 入口执行点的精确计数口径** (判据与台账必须用同一口径, 否则数字对不上):
+ *   ① 只数 `.<promptStream>(` 与 `.<prompt>(` (**非流式也算** —— 它同样会启动一次执行);
+ *   ② 先剥 `//` 行注释, 并丢掉 `*` 开头的块注释行 (否则注释里的示例会被当成执行点);
+ *   ③ `excludeReceivers`: **已核实的非执行点 receiver** 名单 (台账里的数据, 冻结):
+ *      `this` = CLI readline (`this.prompt('> ')`); `s` = index.ts 的 UI 打印助手 (`s.prompt('📩 …')`)。
+ *      名单改动会出现在 diff 里 ⇒ 不能拿它偷偷把执行点数变小。
+ */
+export function countEntryExecutionPoints(code, opts = {}) {
+    const excludeReceivers = opts.excludeReceivers ?? ['this'];
+    // **方法名单也是台账数据**: 启动一次执行的 AgentSession 方法 (不只是 prompt)
+    //   —— 漏掉它会让 P2P 入站那种走 `summarizeDocument/improveDocument` 的入口永远数不到 (实测漏过 4 处)。
+    const methods = opts.methods ?? ['prompt', 'promptStream'];
+    let n = 0;
+    for (const raw of code.split(/\r?\n/)) {
+        const l = raw.replace(/\/\/.*$/, '');
+        if (/^\s*\*/.test(l))
+            continue; // 块注释行
+        for (const m of methods) {
+            // `[!?]?` 允许非空断言 / 可选调用: `session.runExecution!(req)` 也是执行点
+            //   (实测: 不带这一段, 改成请求式的站点会从计数里消失 ⇒ 该文件 total 从 11 掉到 10)
+            const rx = new RegExp(`\\.\\s*${m}\\s*[!?]?\\s*\\(`, 'g');
+            if (!rx.test(l))
+                continue;
+            const recv = new RegExp(`([A-Za-z_$][\\w$]*|this)\\s*\\.\\s*${m}\\s*[!?]?\\s*\\(`).exec(l);
+            if (recv && excludeReceivers.includes(recv[1]))
+                continue; // 已核实的非执行点
+            n += 1;
+        }
+    }
+    return n;
+}
+/** 同一口径下**已投递**的点数 (`deliverThroughActor(` 的出现次数) */
+export function countDeliveredPoints(code) {
+    return (code.match(/deliverThroughActor\(/g) ?? []).length;
+}
+/**
+ * **K5 步骤④ — 入口投递的进度不许自报**: 台账里的 `total` / `wired` 都必须**从盘上重算**得到。
+ *   少包一处却把 wired 写大 ⇒ 红; 新增执行点不登记 ⇒ 红; wired > total ⇒ 红; 台账里有盘上不存在的文件 ⇒ 红。
+ */
+export function scanEntryDelivery(sources, progressLike) {
+    const out = [];
+    const f = (file, what) => out.push({ rule: 'entry-delivery-mismatch', file, line: 1, what });
+    const methods = progressLike.entryMethods ?? ['prompt', 'promptStream'];
+    const complete = new Set();
+    for (const s of progressLike.entrySites) {
+        const src = sources.find((x) => x.file === s.file);
+        if (!src) {
+            f(s.file, `台账登记的文件在扫描面里不存在 ⇒ 口径不可信`);
+            continue;
+        }
+        const total = countEntryExecutionPoints(src.text, { excludeReceivers: s.excludeReceivers ?? ['this'], methods });
+        const wired = countDeliveredPoints(src.text);
+        if (total !== s.total)
+            f(s.file, `入口执行点盘上 ${total} 处 ≠ 台账 ${s.total} ⇒ 新增/删除没登记`);
+        if (wired !== s.wired)
+            f(s.file, `已投递盘上 ${wired} 处 ≠ 台账 ${s.wired} ⇒ 进度对不上事实`);
+        if (s.wired > s.total)
+            f(s.file, `wired ${s.wired} > total ${s.total}`);
+        // `total === 0` (该文件没有执行点) 算**空真完成** —— 否则"入口声明完成"会因为它永远判红
+        if (s.total === s.wired)
+            complete.add(s.file);
+    }
+    // **入口级声明双向校验** (两侧都能判): 说完成了 ⇒ 它的文件必须全接完; 说没完成 ⇒ 必须真有文件没接完。
+    const groups = progressLike.entryGroups ?? [];
+    for (const g of groups) {
+        const all = g.files.every((x) => complete.has(x));
+        if (g.wired && !all)
+            f(g.files[0], `入口「${g.entry}」标完成, 但 ${g.files.filter((x) => !complete.has(x)).join('/')} 还没接完`);
+        if (!g.wired && all)
+            f(g.files[0], `入口「${g.entry}」的文件都接完了, 却还标着未完成 ⇒ 台账该前进`);
+    }
+    if (progressLike.entriesWired !== undefined && progressLike.entriesWired !== groups.filter((g) => g.wired).length) {
+        f('kernel/plan-channel-actor.ts', `entriesWired=${progressLike.entriesWired} ≠ 标完成的入口数 ${groups.filter((g) => g.wired).length}`);
+    }
+    return out;
+}
+/**
+ * **K5 步骤⑤ — channel 级串行锁的开关必须与盘上事实一致** (双向):
+ *   `enabled === true` ⇒ 必须真有调用点传了 `serializeByChannel: true`;
+ *   `enabled === false` ⇒ 一个都不许有 (否则"台账说没启用, 代码却启用了");
+ *   调用点数必须与台账 `callSites` 相等。
+ */
+export function scanChannelLock(sources, lock) {
+    const out = [];
+    const f = (what) => out.push({ rule: 'channel-lock-mismatch', file: 'kernel/plan-channel-actor.ts', line: 1, what });
+    let sites = 0;
+    for (const s of sources) {
+        for (const raw of s.text.split(/\r?\n/)) {
+            const l = raw.replace(/\/\/.*$/, '');
+            if (/^\s*\*/.test(l))
+                continue;
+            sites += (l.match(/serializeByChannel:\s*true/g) ?? []).length;
+        }
+    }
+    if (sites !== lock.callSites)
+        f(`盘上 ${sites} 个调用点传了 serializeByChannel:true ≠ 台账 ${lock.callSites}`);
+    if (lock.enabled && sites === 0)
+        f('台账说 channel 级串行已启用, 但盘上一个调用点都没传 ⇒ 假开关');
+    if (!lock.enabled && sites > 0)
+        f('台账说未启用, 但盘上已有调用点启用 ⇒ 台账落后于代码');
+    return out;
+}
+/**
+ * **K5 步骤⑥ — Run 身份的归属判据** (双向):
+ *   标 `migrated: true` ⇒ 盘上源码**不许再有** `private currentRunId [=:]` (它已变成访问器, 本体在 actor);
+ *   标 `migrated: false` ⇒ 必须**还有**那个声明 (不许偷偷搬走却不改账)。
+ */
+export function scanRunBoundaryResidence(code, rb) {
+    const out = [];
+    const f = (what) => out.push({ rule: 'run-boundary-residence', file: 'agents/pi-sdk.ts', line: 1, what });
+    const declared = new RegExp(`private\\s+${rb.field}\\s*[=:]`).test(code);
+    if (rb.migrated && declared)
+        f(`${rb.field} 仍以实例字段存在 (${rb.into} 已接管却被留下 ⇒ 两份真相)`);
+    if (!rb.migrated && !declared)
+        f(`${rb.field} 不见了, 台账却说没迁 (migrated=false) ⇒ 半搬状态`);
+    return out;
+}
+/**
+ * **K5 步骤⑦ — 一次性 `ExecutionRequest` 的收敛进度** (只验**真数得到**的那一半, 不编造可验证性):
+ *   · `converted` = 入口面上 `runExecution` 调用数 (请求式投递; 允许非空断言 `runExecution!(`);
+ *   · 判据: `converted` 必须等于盘上计数 · 不许超过已投递点数 · Pi 侧必须真的有
+ *     `runExecution(` 与 `applyExecutionRequest(` (台账说加了就必须加, 反之亦然);
+ *   · **`remaining` 是派生值** (= 已投递点数 − converted), 台账里注明它是算出来的, 不假装被独立验证:
+ *     位置参数式的形态太多 (多行 / `as any` / 带参箭头), 行级正则会**数不准**; 与其编一个假精确的门,
+ *     不如把"请求式"这半钉死, 剩下那半用算术表示。
+ */
+export function scanExecutionRequest(entrySources, piCode, req) {
+    const out = [];
+    const f = (what) => out.push({ rule: 'execution-request-mismatch', file: 'kernel/plan-channel-actor.ts', line: 1, what });
+    let converted = 0;
+    for (const s of entrySources) {
+        for (const raw of s.text.split(/\r?\n/)) {
+            const l = raw.replace(/\/\/.*$/, '');
+            if (/^\s*\*/.test(l))
+                continue;
+            converted += (l.match(/runExecution[!?]?\(/g) ?? []).length;
+        }
+    }
+    if (converted !== req.converted)
+        f(`请求式投递 盘上 ${converted} 处 ≠ 台账 ${req.converted}`);
+    if (converted > req.wiredTotal)
+        f(`请求式 ${converted} > 已投递点数 ${req.wiredTotal}`);
+    const hasRun = /runExecution\s*\(/.test(piCode);
+    const hasApply = /applyExecutionRequest\s*\(/.test(piCode);
+    if (req.methodAdded && (!hasRun || !hasApply))
+        f('台账说唯一入口已加, 但 pi-sdk 里缺 runExecution/applyExecutionRequest');
+    if (!req.methodAdded && hasRun)
+        f('pi-sdk 里已有 runExecution, 台账却说没加');
+    return out;
+}
+/**
+ * **K5 步骤⑧ — "暂存字段已删"必须与盘上双向一致**: 台账说删了 ⇒ 源码里不许再有那些 `private <field>` 声明;
+ * 台账没列而源码里也没有 ⇒ 说明有字段被删了却没登记 (迁移必须看得见)。
+ */
+export function scanStagingFieldDeletion(piCode, del) {
+    const out = [];
+    const f = (what) => out.push({ rule: 'staging-field-deletion', file: 'agents/pi-sdk.ts', line: 1, what });
+    for (const name of del.sourceFields) {
+        const declared = new RegExp(`private\\s+${name}\\b`).test(piCode);
+        const claimedDeleted = del.deletedStagingFields.includes(name);
+        if (claimedDeleted && declared)
+            f(`${name} 台账说已删, 源码里还在`);
+        if (!claimedDeleted && !declared)
+            f(`${name} 源码里已不存在, 台账却没登记删除`);
+    }
+    return out;
+}
+/**
+ * **K5 步骤⑧ 棘轮判据**: 盘上重算 pi-sdk 对已迁字段访问器的引用数, 与台账**逐字相等**。
+ *   增 ⇒ 迁移回退; 减 ⇒ 改了盘上没改账 (账必须与事实同步)。两侧都是真发现。
+ */
+export function scanAccessorSurface(piCode, surface) {
+    const out = [];
+    const lines = piCode.split('\n').filter((l) => !/^\s*\*/.test(l));
+    for (const f of surface.accessorFields) {
+        const rx = new RegExp(`this\\.${f}\\b`, 'g');
+        let n = 0;
+        for (const l of lines)
+            n += (l.replace(/\/\/.*$/, '').match(rx) ?? []).length;
+        const frozen = surface.frozenInPiSdk[f];
+        if (frozen === undefined)
+            out.push({ rule: 'accessor-surface', file: 'agents/pi-sdk.ts', line: 1, what: `${f} 没有冻结值` });
+        else if (n > frozen)
+            out.push({ rule: 'accessor-surface', file: 'agents/pi-sdk.ts', line: 1, what: `${f} 引用数 ${n} > 冻结 ${frozen} (迁移回退)` });
+        else if (n < frozen)
+            out.push({ rule: 'accessor-surface', file: 'agents/pi-sdk.ts', line: 1, what: `${f} 引用数 ${n} < 冻结 ${frozen} (盘上变了账没跟上)` });
+    }
+    return out;
+}
+/**
+ * **前置必须点名背书**: 每条删除前置都要有 `backedBy`, 且每个背书要么是盘上存在的文件, 要么是 gate-scan 里存在的判据函数名。
+ *   (只核"背书存在", 不代替真跑 —— 判据不谎称可验证性。)
+ */
+export function scanPreconditionBacking(preconditions, opts) {
+    const out = [];
+    if (preconditions.length === 0)
+        out.push({ rule: 'precondition-backing', file: 'kernel/plan-channel-actor.ts', line: 1, what: '前置清单为空 (拿不到事实就拒跑)' });
+    for (const p of preconditions) {
+        if (!p.backedBy || p.backedBy.length === 0) {
+            out.push({ rule: 'precondition-backing', file: 'kernel/plan-channel-actor.ts', line: 1, what: `前置没有背书: ${p.text}` });
+            continue;
+        }
+        for (const b of p.backedBy) {
+            const isFile = b.includes('/') || b.endsWith('.test.ts');
+            const ok = isFile ? fs.existsSync(path.join(opts.repoRoot, b)) : opts.judgeNames.includes(b) || b.startsWith('K5_');
+            if (!ok)
+                out.push({ rule: 'precondition-backing', file: 'kernel/plan-channel-actor.ts', line: 1, what: `背书不存在: ${b} (前置: ${p.text})` });
+        }
+    }
+    return out;
+}
+/**
+ * **K5 步骤⑧ 完成判据** —— 声明必须与**从盘上重算**的事实一致 (双向):
+ *   条件 A: 5 个访问器在 pi-sdk 侧 0 引用;
+ *   条件 B: 5 个"绑定前暂存"字段的 `private <name>` 声明不存在;
+ *   条件 C: 入口投递 wired === total。
+ *   声明完成而任一条件不成立 ⇒ 红; 事实三条全成立而台账说没完成 ⇒ 红 (台账要跟上)。
+ */
+export function scanStep8Completion(piCode, step8, surface, fieldDeletion) {
+    const out = [];
+    const f = (what) => out.push({ rule: 'step8-completion', file: 'kernel/plan-channel-actor.ts', line: 1, what });
+    const liveAccessors = scanAccessorSurface(piCode, surface).map((x) => x.what);
+    const stagingStillDeclared = fieldDeletion.sourceFields.filter((n) => new RegExp(`private\\s+${n}\\b`).test(piCode));
+    const entriesOk = step8.entriesTotal > 0 && step8.entriesWired === step8.entriesTotal;
+    const conditionsHold = liveAccessors.length === 0 && stagingStillDeclared.length === 0 && entriesOk;
+    if (step8.claimedComplete) {
+        if (liveAccessors.length > 0)
+            f(`声明⑧ 完成, 但访问器仍非 0 引用: ${liveAccessors.join(' / ')}`);
+        if (stagingStillDeclared.length > 0)
+            f(`声明⑧ 完成, 但暂存字段仍在: ${stagingStillDeclared.join(', ')}`);
+        if (!entriesOk)
+            f(`声明⑧ 完成, 但入口投递 ${step8.entriesWired}/${step8.entriesTotal}`);
+    }
+    else if (conditionsHold) {
+        f('三条完成条件都已成立, 台账却说⑧ 未完成 ⇒ 台账该跟上 (事实优先)');
+    }
+    return out;
+}
+/**
+ * **越权欠账不许"烂在账上"**: 若某条欠账写着 `payDownIn: <K>`, 而 `<K>` 已按台账收工 (`STAGE_STATUS[K] === 'done'`),
+ *   那就说明"记着让那个阶段还, 而那个阶段过完了" —— 必须二选一: 立刻还清, 或把 `payDownIn` 重排并写明 `note`。
+ *   (台账自己的注释就写着"不许台账烂在上面", 但没有判据 ⇒ 这条规则让它可被抓。)
+ */
+export function scanDebtPaydownStaleness(debt, stageStatus) {
+    const out = [];
+    for (const d of debt) {
+        if (!d.payDownIn) {
+            out.push({ rule: 'debt-unassigned', file: d.file, line: 1, what: `欠账 ${d.call} 没排期 (payDownIn 为空)` });
+            continue;
+        }
+        if (stageStatus[d.payDownIn] === 'done') {
+            out.push({
+                rule: 'debt-paydown-stale', file: d.file, line: 1,
+                what: `欠账 ${d.call} 记着由 ${d.payDownIn} 还清, 而 ${d.payDownIn} 已收工 —— 要么现在还清, 要么重排并写明 note`,
+            });
+        }
+        if (!d.note || d.note.trim().length < 10) {
+            out.push({ rule: 'debt-note-missing', file: d.file, line: 1, what: `欠账 ${d.call} 没有写明还款路径/重排原因 (note)` });
+        }
+    }
+    return out;
+}
+/**
+ * **旧写口调用点数的唯一口径** (台账与判据共用同一函数 —— 口径不一致会让两侧各报一个数):
+ *   全仓给定文件集 (调用方**排除** `test/` 与 `kernel/`) 里 `name(` 的匹配次数, **去掉含 `function name` 的声明行**。
+ *   为什么去声明行: 否则"函数自己那行"会被算成一个调用点, 额度虚高。
+ */
+export function countModelWritePortCalls(files, name) {
+    const rx = new RegExp(`\\b${name}\\s*\\(`);
+    const decl = new RegExp(`\\bfunction\\s+${name}\\b`);
+    let n = 0;
+    for (const f of files) {
+        for (const line of f.text.split('\n')) {
+            if (decl.test(line))
+                continue;
+            n += (line.match(rx) || []).length;
+        }
+    }
+    return n;
+}
+/**
+ * **K6 门**:
+ *   ① 旧写口棘轮: 每个写口的调用点数**从盘上重算**, 与台账逐字相等
+ *      (增 ⇒ 新层偷偷改旧状态 = 回退; 减 ⇒ 改了盘没改账);
+ *   ② 合计自洽: 各项之和 == 冻结值, 且冻结值 == 台账里的合计;
+ *   ③ 能力清单每项都有非空 why + 合法 status; 明确不做清单 5 条齐全 (防越界);
+ *   ④ **"声明未实现 ⇒ 运行时文件必须不存在"** (与 K5 的容器规则同款, 防假进度);
+ *   ⑤ `acquire` 只读要求必须记为 `readOnly: true` 且写着 ratchet 口径。
+ */
+export function scanModelRuntimeLedger(ledger, files, opts) {
+    const out = [];
+    const f = (what) => out.push({ rule: 'modelruntime-ledger', file: 'kernel/plan-modelruntime.ts', line: 1, what });
+    // ① 逐写口重算
+    for (const p of ledger.writePorts) {
+        const actual = countModelWritePortCalls(files, p.name);
+        if (actual > p.callSites)
+            f(`${p.name} 调用点 ${actual} > 冻结 ${p.callSites} ⇒ 新层在增加旧写口调用 (回退)`);
+        else if (actual < p.callSites)
+            f(`${p.name} 调用点 ${actual} < 冻结 ${p.callSites} ⇒ 盘上变了账没跟上`);
+    }
+    // ② 合计自洽
+    const sum = ledger.writePorts.reduce((a, b) => a + b.callSites, 0);
+    if (sum !== ledger.writePortsFrozenAt)
+        f(`写口调用点合计 ${sum} ≠ 冻结值 ${ledger.writePortsFrozenAt}`);
+    // ③ 能力清单 + 越界清单
+    if (ledger.capabilities.length === 0)
+        f('能力清单为空 (拿不到事实就拒跑)');
+    for (const c of ledger.capabilities) {
+        if (!c.why || c.why.length < 4)
+            f(`能力 ${c.key} 没写"为什么"(why)`);
+        if (!['not-started', 'in-progress', 'done'].includes(c.status))
+            f(`能力 ${c.key} 状态非法: ${c.status}`);
+    }
+    if (ledger.outOfScope.length !== 5)
+        f(`"明确不做"清单 ${ledger.outOfScope.length} 条 ≠ 5 (防越界清单不许缩减)`);
+    // ④ 假进度
+    const declaredNotStarted = ledger.progress.stage === 'not-started';
+    if (declaredNotStarted && opts.runtimeExists)
+        f(`标了 not-started 但 ${ledger.progress.runtimePath} 已存在 ⇒ 台账该改`);
+    if (!declaredNotStarted && !opts.runtimeExists)
+        f(`stage=${ledger.progress.stage} 但 ${ledger.progress.runtimePath} 不存在 ⇒ 假进度`);
+    // ⑤ 只读要求
+    if (ledger.acquireRule.readOnly !== true)
+        f('acquire 的只读要求被拿掉了 (这是 K6 的核心不变量)');
+    if (!ledger.acquireRule.ratchet.includes('只许不变或减少'))
+        f('ratchet 口径文案被改 (必须写明"只许不变或减少")');
+    return out;
+}
+/**
+ * **K6 读写分离: 运行时文件里不许出现任何旧写口名** —— 这是"只读"最机械的那半证据
+ *   (另一半是真跑: 冻结的 snapshot 上调用不许抛 / 不许触发注入的写端口)。
+ *   同时核: 文件必须真的含 `acquire(` 与 AbortController (否则"实现了"是空话),
+ *   以及 `capabilitiesDone` 必须等于能力清单里 status==='done' 的条数 (台账不许自报)。
+ */
+export function scanModelRuntimeFile(code, opts) {
+    const out = [];
+    const f = (what) => out.push({ rule: 'modelruntime-file', file: 'kernel/model-runtime.ts', line: 1, what });
+    if (code.trim().length === 0) {
+        f('运行时文件为空 ⇒ 拒跑 (不许跳过)');
+        return out;
+    }
+    for (const name of opts.writePortNames) {
+        if (new RegExp(`\\b${name}\\b`).test(code))
+            f(`运行时文件里出现旧写口 ${name} ⇒ 读写没分开 (K6 只读红线)`);
+    }
+    if (!/\bacquire\s*\(/.test(code))
+        f('没有 acquire( ⇒ 入口没实现');
+    if (!/AbortController/.test(code))
+        f('没有 AbortController ⇒ 取消/超时没有真做到 (只"等"不"中止")');
+    if (!/clearTimeout/.test(code))
+        f('没有 clearTimeout ⇒ 超时定时器会泄漏 (调用成功也留着)');
+    const done = opts.capabilities.filter((c) => c.status === 'done').length;
+    if (opts.progress.capabilitiesDone !== done)
+        f(`capabilitiesDone=${opts.progress.capabilitiesDone} ≠ 清单里 done 的条数 ${done}`);
+    return out;
+}