@twinsearth/dsh-master 3.2.10 → 3.3.1

package/dist-host/cost/report.js

@@ -0,0 +1,156 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// Copyright (c) 2026 dsh-Master contributors — see LICENSE-CORE.
+// @ts-nocheck — host JS→TS 迁移阶段：运行时行为优先，类型注解逐步补齐（worker/ 仍严格检查）。
+/**
+ * 3.3.0 系统层 · report（两条链路联动报表，设计 §8）。
+ *
+ * 两条链路的节省**必须分列、且不重复计**：
+ *
+ *   * **单价项（A）**：A1 压缩回执 → 每次交互更便宜。来源 = execution 账里 `phase:'tool'`
+ *     的压缩归因条目（`meta.kind` 为 attribution）。
+ *   * **次数项（B）**：B2/B3 命中 → 少调一次模型。来源 = **替换证书**（不是账本），
+ *     每个 dispatched 证书代表一次被跳过的回调，金额 = 该证书的 `savedTokens`（基线单价）。
+ *
+ * 总节省 = Σ(跳过的调用数 × 该步基线单价) + Σ(每次交互的单价下降)，两项分列。
+ *
+ * 作者的代价必须摊进去：EDG 编写与 RSI 离线成本都在 governance 账；
+ * 若某任务 `execution 节省 < governance 摊销`，该任务记为**净亏**并显式列出，不隐藏。
+ */
+function num(value) {
+    const n = Number(value);
+    return Number.isFinite(n) ? n : 0;
+}
+const nonNegative = (value) => Math.max(0, num(value));
+/**
+ * 判定某条账本事件属于哪一列（互斥）：
+ *   * B 列**只认证书**：替换产生的账本事件（`meta.kind === 'substitution'`）单列出来，
+ *     既不进 A 也不进 B —— 否则同一次节省会被证书与账本各算一遍；
+ *   * A 列只认 execution + tool 相位 + 非外部（external 是宿主面插件收益，单列）。
+ */
+export function classifyEntry(entry) {
+    if (!entry || entry.account !== 'execution')
+        return 'governance';
+    if (entry.external === true)
+        return 'external';
+    if (entry.meta?.kind === 'substitution')
+        return 'skipped-call-ledger';
+    if (entry.phase === 'tool' && entry.savedTokens > 0)
+        return 'unit-price';
+    if (entry.savedTokens > 0)
+        return 'other-execution';
+    return 'consumption';
+}
+/**
+ * @param {{
+ *   entries?: object[],
+ *   certificates?: object[],
+ *   amortize?: 'even' | 'per-task',
+ *   moduleOf?: (entry: object) => string,
+ * }} input
+ */
+export function buildSavingsReport(input = {}) {
+    const entries = Array.isArray(input.entries) ? input.entries : [];
+    const certificates = Array.isArray(input.certificates) ? input.certificates : [];
+    const amortize = input.amortize === 'per-task' ? 'per-task' : 'even';
+    // ---- 列 A：单价下降（A1 回执压缩） ----
+    const unitPrice = { savedTokens: 0, interactions: 0, byModule: {}, byTask: {} };
+    // ---- 列 B：跳过调用（B2/B3 复用） ----
+    const skippedCalls = { savedTokens: 0, calls: 0, byTool: {}, byTask: {} };
+    // ---- 治理成本（作者 + 离线） ----
+    const governance = { totalTokens: 0, byKind: {}, byTask: {} };
+    // ---- 其它（消耗、外部）----
+    const consumption = { tokens: 0, entries: 0 };
+    const externalSaved = 0;
+    for (const entry of entries) {
+        const bucket = classifyEntry(entry);
+        if (bucket === 'governance') {
+            const tokens = nonNegative(entry.total);
+            governance.totalTokens += tokens;
+            const kind = String(entry.meta?.kind ?? entry.source ?? 'governance');
+            governance.byKind[kind] = (governance.byKind[kind] ?? 0) + tokens;
+            const taskKey = entry.taskId ?? 'unattributed';
+            governance.byTask[taskKey] = (governance.byTask[taskKey] ?? 0) + tokens;
+            continue;
+        }
+        if (bucket === 'unit-price') {
+            const saved = nonNegative(entry.savedTokens);
+            unitPrice.savedTokens += saved;
+            unitPrice.interactions += 1;
+            const moduleKey = String(entry.module ?? 'unattributed');
+            unitPrice.byModule[moduleKey] = (unitPrice.byModule[moduleKey] ?? 0) + saved;
+            const taskKey = entry.taskId ?? 'unattributed';
+            unitPrice.byTask[taskKey] = (unitPrice.byTask[taskKey] ?? 0) + saved;
+            continue;
+        }
+        if (bucket === 'consumption') {
+            consumption.tokens += nonNegative(entry.total);
+            consumption.entries += 1;
+        }
+    }
+    // B 列：只来自证书，且只算真正派发成功的
+    for (const cert of certificates) {
+        if (cert?.dispatched === false)
+            continue;
+        const saved = nonNegative(cert?.savedTokens);
+        skippedCalls.calls += 1;
+        skippedCalls.savedTokens += saved;
+        const tool = String(cert?.toolName ?? 'unknown');
+        skippedCalls.byTool[tool] = (skippedCalls.byTool[tool] ?? 0) + saved;
+        const taskKey = cert?.taskId ?? 'unattributed';
+        skippedCalls.byTask[taskKey] = (skippedCalls.byTask[taskKey] ?? 0) + saved;
+    }
+    // ---- 任务级净额：execution 节省（A+B） − governance 摊销 ----
+    const taskIds = [...new Set([
+            ...Object.keys(unitPrice.byTask),
+            ...Object.keys(skippedCalls.byTask),
+            ...Object.keys(governance.byTask),
+        ])].filter((taskId) => taskId !== 'unattributed').sort();
+    const amortized = {};
+    if (amortize === 'even') {
+        // RSI/离线等无法落到具体任务的成本，按任务数均摊（显式声明策略）。
+        const shared = governance.byTask.unattributed ?? 0;
+        const perTask = taskIds.length > 0 ? shared / taskIds.length : 0;
+        for (const taskId of taskIds)
+            amortized[taskId] = (governance.byTask[taskId] ?? 0) + perTask;
+    }
+    else {
+        for (const taskId of taskIds)
+            amortized[taskId] = governance.byTask[taskId] ?? 0;
+    }
+    const tasks = taskIds.map((taskId) => {
+        const executionSaved = (unitPrice.byTask[taskId] ?? 0) + (skippedCalls.byTask[taskId] ?? 0);
+        const governanceAmortized = amortized[taskId] ?? 0;
+        const net = executionSaved - governanceAmortized;
+        return {
+            taskId,
+            executionSaved,
+            unitPriceSaved: unitPrice.byTask[taskId] ?? 0,
+            skippedCallSaved: skippedCalls.byTask[taskId] ?? 0,
+            governanceAmortized,
+            net,
+            /** §8：净亏任务必须显示，不隐藏。 */
+            netLoss: net < 0,
+        };
+    });
+    const netLossTasks = tasks.filter((task) => task.netLoss);
+    const totalSavedTokens = unitPrice.savedTokens + skippedCalls.savedTokens;
+    return Object.freeze({
+        ok: true,
+        amortize,
+        /** 两项分列——报表必须分别展示，禁止只报合计。 */
+        columns: Object.freeze({
+            unitPrice: Object.freeze({ ...unitPrice, byModule: { ...unitPrice.byModule }, byTask: { ...unitPrice.byTask } }),
+            skippedCalls: Object.freeze({ ...skippedCalls, byTool: { ...skippedCalls.byTool }, byTask: { ...skippedCalls.byTask } }),
+        }),
+        totalSavedTokens,
+        governance: Object.freeze({ ...governance, byKind: { ...governance.byKind }, byTask: { ...governance.byTask } }),
+        consumption: Object.freeze({ ...consumption }),
+        /** 宿主面外部插件自报收益：只展示，永不并入总节省。 */
+        externalSaved,
+        /** A/B 两列来源互斥（A=账本、B=证书），结构上不可能重复计。 */
+        doubleCountGuard: true,
+        tasks: Object.freeze(tasks.map((task) => Object.freeze(task))),
+        netLossTasks: Object.freeze(netLossTasks.map((task) => Object.freeze(task))),
+        netSaved: totalSavedTokens - governance.totalTokens,
+    });
+}

package/dist-host/cost/reuse-report.js

@@ -0,0 +1,128 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// Copyright (c) 2026 dsh-Master contributors — see LICENSE-CORE.
+// @ts-nocheck — host JS→TS 迁移阶段：运行时行为优先，类型注解逐步补齐（worker/ 仍严格检查）。
+/**
+ * 3.3.0 · M3 交付物：**命中率与「本可节省」报表**（B1 EDG + B2 GDR，shadow 只算不替换）。
+ *
+ * 口径纪律（M3 最关键的一条）：
+ *
+ *   * **shadow 的节省是「本可节省」，不是节省**。报表字段名就叫 `wouldSaveTokens`，
+ *     并且 `actualSavedTokens` 在 shadow 下恒为 0；
+ *   * **分母是「每次复用尝试」**，不是每次工具调用、也不是每个任务；
+ *   * 未命中必须给原因分布（`schema-drift` / `guard-miss` / `arg-unextractable` …），
+ *     这是 RSI（B4）唯一能拿来做改进的输入；
+ *   * shadow 证书**不进审计链**（它们没有派发，没有 native dispatcher 证据）。
+ */
+export const GDR_REASONS = Object.freeze([
+    'no-edge',
+    'tool-mismatch',
+    'schema-drift',
+    'dependency-incomplete',
+    'guard-miss',
+    'arg-unextractable',
+]);
+const num = (value) => {
+    const n = Number(value);
+    return Number.isFinite(n) && n >= 0 ? n : 0;
+};
+/**
+ * M3 报表。
+ *
+ * @param {{
+ *   attempts?: Array<{toolName?: string, hit?: boolean, reason?: string | null, stage?: string | null, edgeId?: string | null, wouldSaveTokens?: number}>,
+ *   shadowCertificates?: Array<object>,
+ *   substitutions?: Array<object>,
+ *   mode?: 'off' | 'shadow' | 'enforce',
+ * }} input
+ */
+export function buildReuseReport(input = {}) {
+    const attempts = Array.isArray(input.attempts) ? input.attempts : [];
+    const shadowCertificates = Array.isArray(input.shadowCertificates) ? input.shadowCertificates : [];
+    const substitutions = Array.isArray(input.substitutions) ? input.substitutions : [];
+    const mode = input.mode === 'enforce' ? 'enforce' : input.mode === 'off' ? 'off' : 'shadow';
+    const byReason = Object.fromEntries(GDR_REASONS.map((reason) => [reason, 0]));
+    const byTool = {};
+    const byStage = {};
+    let hits = 0;
+    let wouldSaveTokens = 0;
+    for (const attempt of attempts) {
+        const toolName = String(attempt?.toolName ?? 'unknown');
+        if (!byTool[toolName])
+            byTool[toolName] = { attempts: 0, hits: 0, wouldSaveTokens: 0 };
+        const row = byTool[toolName];
+        row.attempts += 1;
+        if (attempt?.hit === true) {
+            hits += 1;
+            row.hits += 1;
+            const wouldSave = num(attempt?.wouldSaveTokens);
+            wouldSaveTokens += wouldSave;
+            row.wouldSaveTokens += wouldSave;
+        }
+        else {
+            const reason = String(attempt?.reason ?? 'guard-miss');
+            if (reason in byReason)
+                byReason[reason] += 1;
+            else
+                byReason['guard-miss'] += 1;
+            const stage = String(attempt?.stage ?? 'unknown');
+            byStage[stage] = (byStage[stage] ?? 0) + 1;
+        }
+    }
+    const total = attempts.length;
+    const hitRate = total > 0 ? hits / total : 0;
+    // shadow 与 enforce 的节省口径必须分开：shadow 的命中只是「本可替换」
+    const dispatchedSubstitutions = substitutions.filter((cert) => cert?.dispatched === true);
+    const actualSavedTokens = mode === 'enforce'
+        ? dispatchedSubstitutions.reduce((sum, cert) => sum + num(cert?.savedTokens), 0)
+        : 0;
+    return Object.freeze({
+        ok: true,
+        mode,
+        attempts: total,
+        hits,
+        hitRate,
+        /** 分母口径写进报表，避免被误读成「每次工具调用的命中率」。 */
+        denominator: 'reuse-attempts',
+        byReason: Object.freeze({ ...byReason }),
+        byStage: Object.freeze({ ...byStage }),
+        byTool: Object.freeze(Object.fromEntries(Object.entries(byTool).map(([key, row]) => [key, Object.freeze({ ...row })]))),
+        /** M3 的核心数字：shadow 下的「本可节省」。 */
+        wouldSaveTokens,
+        /** 真正派发成功的替换节省；shadow 恒为 0，绝不会把「本可」写成「已省」。 */
+        actualSavedTokens,
+        shadowCertificates: shadowCertificates.length,
+        shadowCertificateDispatched: shadowCertificates.filter((cert) => cert?.dispatched === true).length,
+        substitutions: dispatchedSubstitutions.length,
+        /** 三档语义：shadow 只算不替换；enforce 才可能真的替换成功。 */
+        discipline: Object.freeze({
+            shadowNeverBooksSavings: mode === 'shadow' ? actualSavedTokens === 0 : true,
+            shadowCertificatesNotAudited: shadowCertificates.every((cert) => cert?.dispatched !== true),
+            denominatorIsAttempts: true,
+        }),
+        /** 数据不足时的诚实提示（样本太小不能下结论）。 */
+        sufficiency: Object.freeze({
+            samples: total,
+            enoughForConclusion: total >= 20,
+            note: total >= 20 ? null : '样本不足 20：命中率尚不足以下结论',
+        }),
+    });
+}
+/** 人读行（CLI / 面板共用）。 */
+export function formatReuseReport(report) {
+    const lines = [];
+    lines.push(`复用报表（${report.mode}）  尝试 ${report.attempts} · 命中 ${report.hits} · 命中率 ${(report.hitRate * 100).toFixed(1)}%`);
+    lines.push(`本可节省 ${report.wouldSaveTokens} tokens · 实际节省 ${report.actualSavedTokens} tokens`);
+    lines.push(`shadow 证书 ${report.shadowCertificates}（未派发 ${report.shadowCertificates - report.shadowCertificateDispatched}）· 真实替换 ${report.substitutions}`);
+    lines.push('');
+    lines.push('未命中原因分布');
+    for (const [reason, count] of Object.entries(report.byReason))
+        lines.push(`  ${reason.padEnd(22)} ${count}`);
+    lines.push('');
+    lines.push('按工具');
+    for (const [tool, row] of Object.entries(report.byTool)) {
+        lines.push(`  ${tool.padEnd(20)} 尝试 ${row.attempts} · 命中 ${row.hits} · 本可节省 ${row.wouldSaveTokens}`);
+    }
+    if (report.sufficiency.note)
+        lines.push(`\n注意：${report.sufficiency.note}`);
+    return lines.join('\n');
+}

package/dist-host/cost/rsi.js

@@ -0,0 +1,367 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// Copyright (c) 2026 dsh-Master contributors — see LICENSE-CORE.
+// @ts-nocheck — host JS→TS 迁移阶段：运行时行为优先，类型注解逐步补齐（worker/ 仍严格检查）。
+/**
+ * 3.3.0 · B4 `rsi`（离线递归自改进，设计 §7）。
+ *
+ * **位置：离线**。本文件不属于 Worker 热路径，不 import 任何 worker 模块，
+ * 也不会被插件 `apply()` 调用 —— 它只在运维侧被显式执行（见 `scripts/rsi-offline.mjs`）。
+ *
+ * 输入（全部来自已落库的事实）：
+ *   * ledger 快照（`status().ledger`）—— 省了多少、哪些模块、估算占比；
+ *   * 替换证书（`audit.substitutions()`）—— 哪些边真的被复用；
+ *   * 失败原因分布（`WorkerResult.cost.ccs.guard.byReason` 汇总）—— 为什么没命中。
+ *
+ * 产物（**候选配置**）：
+ *   * `guard-relax`     —— 守卫表达式调整（针对 guard-miss 集中处）；
+ *   * `template-add`    —— 把反复出现的成功边固化成模板；
+ *   * `guidance-rewrite`—— 批量/披露教学文案改写（针对 shape 纠偏次数）。
+ *
+ * 纪律：
+ *   * 每个候选**必须**过验证集打分（`score()`），未达阈值**不得冻结**；
+ *   * `freeze()` 产出冻结清单条目（含输入摘要 + 打分 + 阈值 + 时间），
+ *     **冻结后才允许被 active 使用**；
+ *   * 报表把「候选」与「基线」放在同一张表里对比，禁止只报候选的漂亮数字；
+ *   * 3.3.0 只交付**可复现的离线流程 + 冻结清单**，不做自动上线。
+ */
+import crypto from 'node:crypto';
+/* ------------------------------------------------------------------ *
+ * 输入归一化（可复现的关键：一切排序 + 稳定序列化）
+ * ------------------------------------------------------------------ */
+function canonical(value) {
+    if (Array.isArray(value))
+        return `[${value.map((item) => canonical(item)).join(',')}]`;
+    if (value && typeof value === 'object') {
+        const keys = Object.keys(value).sort();
+        return `{${keys.map((key) => `${JSON.stringify(key)}:${canonical(value[key])}`).join(',')}}`;
+    }
+    if (typeof value === 'number')
+        return Number.isFinite(value) ? String(value) : 'null';
+    if (value === undefined)
+        return 'null';
+    return JSON.stringify(value) ?? 'null';
+}
+export function digestOf(value) {
+    return `sha256:${crypto.createHash('sha256').update(canonical(value)).digest('hex')}`;
+}
+const MISS_REASONS = Object.freeze([
+    'no-edge',
+    'tool-mismatch',
+    'schema-drift',
+    'dependency-incomplete',
+    'guard-miss',
+    'arg-unextractable',
+]);
+/**
+ * @param {{
+ *   ledger?: object, certificates?: object[], guardStats?: {byReason?: object, matches?: number, hits?: number},
+ *   corrections?: number, generatedAt?: number,
+ * }} input
+ */
+export function normalizeInput(input = {}) {
+    const byReason = {};
+    for (const reason of MISS_REASONS)
+        byReason[reason] = Math.max(0, Number(input?.guardStats?.byReason?.[reason] ?? 0) || 0);
+    const certificates = (Array.isArray(input?.certificates) ? input.certificates : [])
+        .map((cert) => ({
+        edgeId: String(cert?.edgeId ?? ''),
+        toolName: String(cert?.toolName ?? ''),
+        guardExpr: String(cert?.guardExpr ?? ''),
+        dispatched: cert?.dispatched !== false,
+        savedTokens: Math.max(0, Number(cert?.savedTokens ?? 0) || 0),
+    }))
+        .sort((a, b) => `${a.edgeId}|${a.toolName}`.localeCompare(`${b.edgeId}|${b.toolName}`));
+    return {
+        ledger: {
+            ownExecutionSaved: Math.max(0, Number(input?.ledger?.ownExecutionSaved ?? 0) || 0),
+            governanceTotal: Math.max(0, Number(input?.ledger?.governance?.total ?? 0) || 0),
+            measuredTokens: Math.max(0, Number(input?.ledger?.tokens?.measuredTokens ?? 0) || 0),
+            estimatedTokens: Math.max(0, Number(input?.ledger?.tokens?.estimatedTokens ?? 0) || 0),
+        },
+        certificates,
+        guardStats: {
+            matches: Math.max(0, Number(input?.guardStats?.matches ?? 0) || 0),
+            hits: Math.max(0, Number(input?.guardStats?.hits ?? 0) || 0),
+            byReason,
+        },
+        corrections: Math.max(0, Number(input?.corrections ?? 0) || 0),
+        generatedAt: Number(input?.generatedAt ?? 0) || 0,
+    };
+}
+/* ------------------------------------------------------------------ *
+ * 分析 → 候选配置
+ * ------------------------------------------------------------------ */
+export function analyze(input = {}) {
+    const data = normalizeInput(input);
+    const total = data.guardStats.matches;
+    const hits = data.guardStats.hits;
+    const hitRate = total > 0 ? hits / total : 0;
+    const findings = [];
+    const reason = (name) => data.guardStats.byReason[name] ?? 0;
+    if (reason('guard-miss') > 0)
+        findings.push({ key: 'guard-miss', count: reason('guard-miss'), note: '守卫过严或回执形态变化' });
+    if (reason('arg-unextractable') > 0)
+        findings.push({ key: 'arg-unextractable', count: reason('arg-unextractable'), note: '参数来源无法确定性提取' });
+    if (reason('schema-drift') > 0)
+        findings.push({ key: 'schema-drift', count: reason('schema-drift'), note: '工具 schema 变更导致旧图作废' });
+    if (reason('tool-mismatch') > 0 || reason('no-edge') > 0)
+        findings.push({ key: 'coverage-gap', count: reason('tool-mismatch') + reason('no-edge'), note: '图里缺边' });
+    if (reason('dependency-incomplete') > 0)
+        findings.push({ key: 'dependency-incomplete', count: reason('dependency-incomplete'), note: '依赖链过长' });
+    if (data.corrections > 0)
+        findings.push({ key: 'batch-shape', count: data.corrections, note: '批量形状纠偏触发' });
+    return Object.freeze({
+        ok: true,
+        inputDigest: digestOf(data),
+        data,
+        baseline: Object.freeze({
+            hitRate,
+            matches: total,
+            hits,
+            savedTokens: data.ledger.ownExecutionSaved,
+            governanceTokens: data.ledger.governanceTotal,
+            estimatedRatio: data.ledger.measuredTokens + data.ledger.estimatedTokens > 0
+                ? data.ledger.estimatedTokens / (data.ledger.measuredTokens + data.ledger.estimatedTokens)
+                : 0,
+        }),
+        findings: findings.sort((a, b) => b.count - a.count || a.key.localeCompare(b.key)),
+    });
+}
+/**
+ * 从分析结果生成**候选配置**（只提案，不生效）。
+ * 每个候选都带 `requiresValidation: true`，未过验证集不得冻结。
+ */
+export function proposeCandidates(analysis) {
+    const findings = Array.isArray(analysis?.findings) ? analysis.findings : [];
+    const certificates = Array.isArray(analysis?.data?.certificates) ? analysis.data.certificates : [];
+    const candidates = [];
+    const guardMiss = findings.find((item) => item.key === 'guard-miss');
+    if (guardMiss) {
+        candidates.push({
+            id: 'cand_guard_relax',
+            kind: 'guard-relax',
+            rationale: `guard-miss ${guardMiss.count} 次：守卫过于严格`,
+            change: { action: 'relax-guard', target: 'edges-with-frequent-guard-miss', note: '把 equals 放宽为 regex，或增加 negate 分支' },
+            risk: 'high',
+            requiresValidation: true,
+        });
+    }
+    const unextractable = findings.find((item) => item.key === 'arg-unextractable');
+    if (unextractable) {
+        candidates.push({
+            id: 'cand_arg_source',
+            kind: 'guard-relax',
+            rationale: `arg-unextractable ${unextractable.count} 次：参数来源不可确定性提取`,
+            change: { action: 'switch-arg-source', from: 'literal', to: 'jsonpath', note: '改用回执里稳定出现的字段' },
+            risk: 'medium',
+            requiresValidation: true,
+        });
+    }
+    // 反复成功的边 → 固化为模板
+    const successByEdge = new Map();
+    for (const cert of certificates) {
+        if (!cert.dispatched)
+            continue;
+        const key = `${cert.edgeId}|${cert.toolName}|${cert.guardExpr}`;
+        successByEdge.set(key, (successByEdge.get(key) ?? 0) + Math.max(1, cert.savedTokens > 0 ? 1 : 0));
+    }
+    const repeatable = [...successByEdge.entries()].filter(([, count]) => count >= 2).sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0]));
+    if (repeatable.length > 0) {
+        candidates.push({
+            id: 'cand_template_add',
+            kind: 'template-add',
+            rationale: `${repeatable.length} 条边被重复复用 ≥2 次，值得固化进模板库`,
+            change: { action: 'add-templates', edges: repeatable.map(([key]) => key.split('|')[0]) },
+            risk: 'low',
+            requiresValidation: true,
+        });
+    }
+    if (findings.some((item) => item.key === 'batch-shape')) {
+        candidates.push({
+            id: 'cand_guidance',
+            kind: 'guidance-rewrite',
+            rationale: '批量形状纠偏仍在触发，教学文案可再收紧',
+            change: { action: 'rewrite-guidance', target: 'tool-batch.guidance', note: '把反例写得更具体' },
+            risk: 'low',
+            requiresValidation: true,
+        });
+    }
+    return Object.freeze(candidates.sort((a, b) => a.id.localeCompare(b.id)));
+}
+/* ------------------------------------------------------------------ *
+ * 验证集打分 → 冻结
+ * ------------------------------------------------------------------ */
+const DEFAULT_THRESHOLDS = Object.freeze({ minAccuracy: 0.98, maxDestructiveHits: 0, minSamples: 20 });
+/**
+ * 用验证集给候选打分。验证集必须**独立于**生成候选的样本（调用方保证）。
+ * @param {{candidate: object, validation: {samples?: number, correct?: number, destructiveHits?: number, savedTokens?: number}}} input
+ */
+export function score(input = {}) {
+    const candidate = input?.candidate;
+    if (!candidate || !candidate.id)
+        return { ok: false, code: 'candidate-invalid', message: 'candidate with id required' };
+    const samples = Math.max(0, Number(input?.validation?.samples ?? 0) || 0);
+    const correct = Math.max(0, Number(input?.validation?.correct ?? 0) || 0);
+    const destructiveHits = Math.max(0, Number(input?.validation?.destructiveHits ?? 0) || 0);
+    const savedTokens = Math.max(0, Number(input?.validation?.savedTokens ?? 0) || 0);
+    if (correct > samples)
+        return { ok: false, code: 'validation-invalid', message: 'correct cannot exceed samples' };
+    const accuracy = samples > 0 ? correct / samples : 0;
+    return {
+        ok: true,
+        candidateId: String(candidate.id),
+        samples,
+        correct,
+        accuracy,
+        destructiveHits,
+        savedTokens,
+        scoredAt: Date.now(),
+    };
+}
+/**
+ * 冻结：**未达阈值一律拒绝**。产出冻结清单条目（含输入摘要，可复现核对）。
+ * @param {{candidate: object, score: object, analysis: object, thresholds?: object, now?: () => number}} input
+ */
+export function freeze(input = {}) {
+    const candidate = input?.candidate;
+    const scoreValue = input?.score;
+    const analysis = input?.analysis;
+    if (!candidate?.id)
+        return { ok: false, code: 'candidate-invalid', message: 'candidate with id required' };
+    if (!scoreValue || scoreValue.ok !== true)
+        return { ok: false, code: 'score-missing', message: 'candidate must be scored before freezing' };
+    const thresholds = { ...DEFAULT_THRESHOLDS, ...(input?.thresholds ?? {}) };
+    const reasons = [];
+    if (scoreValue.samples < thresholds.minSamples)
+        reasons.push('samples-below-threshold');
+    if (scoreValue.accuracy < thresholds.minAccuracy)
+        reasons.push('accuracy-below-threshold');
+    if (scoreValue.destructiveHits > thresholds.maxDestructiveHits)
+        reasons.push('destructive-hits');
+    if (!analysis?.inputDigest)
+        reasons.push('input-digest-missing');
+    if (reasons.length > 0)
+        return { ok: false, code: 'freeze-refused', reasons };
+    const entry = Object.freeze({
+        candidateId: String(candidate.id),
+        kind: String(candidate.kind ?? 'unknown'),
+        risk: String(candidate.risk ?? 'unknown'),
+        changeDigest: digestOf(candidate.change ?? {}),
+        inputDigest: analysis.inputDigest,
+        validation: Object.freeze({
+            samples: scoreValue.samples,
+            correct: scoreValue.correct,
+            accuracy: scoreValue.accuracy,
+            destructiveHits: scoreValue.destructiveHits,
+            savedTokens: scoreValue.savedTokens,
+        }),
+        thresholds: Object.freeze({ ...thresholds }),
+        frozenAt: typeof input?.now === 'function' ? input.now() : Date.now(),
+        /** 冻结后才允许 active 使用；冻结 ≠ 自动上线。 */
+        usableByActive: true,
+    });
+    return { ok: true, entry };
+}
+/**
+ * 生成报表：候选与基线**同表展示**（防止只展示候选的漂亮数字）。
+ */
+export function report({ analysis, scored = [], frozen = [] }) {
+    const baseline = analysis?.baseline ?? { hitRate: 0, matches: 0, hits: 0, savedTokens: 0, governanceTokens: 0, estimatedRatio: 0 };
+    const rows = [
+        {
+            id: 'baseline',
+            kind: 'baseline',
+            hitRate: baseline.hitRate,
+            samples: baseline.matches,
+            accuracy: null,
+            savedTokens: baseline.savedTokens,
+            governanceTokens: baseline.governanceTokens,
+            status: 'baseline',
+        },
+        ...scored.map((item) => {
+            const frozenEntry = frozen.find((entry) => entry.candidateId === item.candidateId);
+            return {
+                id: item.candidateId,
+                kind: 'candidate',
+                hitRate: null,
+                samples: item.samples,
+                accuracy: item.accuracy,
+                savedTokens: item.savedTokens,
+                governanceTokens: null,
+                status: frozenEntry ? 'frozen' : 'candidate',
+            };
+        }),
+    ];
+    return Object.freeze({
+        ok: true,
+        inputDigest: analysis?.inputDigest ?? null,
+        generatedAt: Date.now(),
+        findings: analysis?.findings ?? [],
+        rows,
+        frozen: frozen.map((entry) => ({ ...entry })),
+        /** 3.3.0 不做自动上线：清单之外的一切都只是提案。 */
+        autoDeploy: false,
+    });
+}
+/**
+ * M5 交付物：**冻结清单**（可持久化、可复核）。
+ *
+ * 清单只描述"在什么数据、什么阈值下冻结了什么"，不含执行能力：
+ *   * `inputDigest`：生成候选时的输入摘要（同一输入必得同一摘要）；
+ *   * `entries`：逐条冻结记录，按 candidateId 排序保证可 diff；
+ *   * `manifestDigest`：整份清单的摘要，用于事后核对「清单没被改过」。
+ */
+export function buildFreezeManifest({ analysis, frozen = [], now } = {}) {
+    const entries = [...(Array.isArray(frozen) ? frozen : [])]
+        .map((entry) => ({ ...entry }))
+        .sort((a, b) => String(a.candidateId).localeCompare(String(b.candidateId)));
+    const manifest = {
+        kind: 'rsi-freeze-manifest',
+        version: 1,
+        inputDigest: analysis?.inputDigest ?? null,
+        thresholds: { ...DEFAULT_THRESHOLDS },
+        generatedAt: Number(now ?? 0) || 0,
+        entries,
+        /** 3.3.0 不自动上线：清单只声明「可被 active 使用」，上线仍是人工动作。 */
+        autoDeploy: false,
+    };
+    return Object.freeze({ ...manifest, manifestDigest: digestOf(manifest) });
+}
+/**
+ * 复核冻结清单：清单没被改动、输入没变、条目仍然满足阈值。
+ * 返回 `issues[]` —— 任何一条都意味着"这份清单不能再作为依据"。
+ */
+export function verifyFreezeManifest(manifest, { analysis, thresholds } = {}) {
+    const issues = [];
+    if (!manifest || manifest.kind !== 'rsi-freeze-manifest')
+        issues.push('manifest-kind-invalid');
+    const entries = Array.isArray(manifest?.entries) ? manifest.entries : [];
+    if (entries.length === 0)
+        issues.push('manifest-empty');
+    if (manifest?.autoDeploy !== false)
+        issues.push('manifest-must-not-auto-deploy');
+    // 清单自身完整性：重算摘要必须一致（防止事后手改）
+    const body = { ...manifest };
+    delete body.manifestDigest;
+    if (manifest?.manifestDigest !== digestOf(body))
+        issues.push('manifest-digest-mismatch');
+    // 输入漂移：候选是在旧数据上冻结的，就不能再当依据
+    if (analysis?.inputDigest && manifest?.inputDigest && analysis.inputDigest !== manifest.inputDigest) {
+        issues.push('input-digest-drift');
+    }
+    const limits = { ...DEFAULT_THRESHOLDS, ...(thresholds ?? {}) };
+    for (const entry of entries) {
+        const validation = entry?.validation ?? {};
+        if (Number(validation.samples ?? 0) < limits.minSamples)
+            issues.push(`entry-samples-below:${entry?.candidateId}`);
+        if (Number(validation.accuracy ?? 0) < limits.minAccuracy)
+            issues.push(`entry-accuracy-below:${entry?.candidateId}`);
+        if (Number(validation.destructiveHits ?? 0) > limits.maxDestructiveHits)
+            issues.push(`entry-destructive-hits:${entry?.candidateId}`);
+        if (entry?.usableByActive !== true)
+            issues.push(`entry-not-usable:${entry?.candidateId}`);
+    }
+    return Object.freeze({ ok: issues.length === 0, issues: Object.freeze(issues), entries: entries.length });
+}
+export const RSI_THRESHOLDS = DEFAULT_THRESHOLDS;
+export { MISS_REASONS };