@twinsearth/dsh-master 3.2.10 → 3.3.1

package/dist-host/cost/milestones.js

@@ -0,0 +1,209 @@
+// 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 · milestones（里程碑与依赖顺序，设计 §14）。
+ *
+ * 规格原文：
+ *
+ * | 阶段 | 内容 | 产出 |
+ * |---|---|---|
+ * | M1 | 系统层：ledger/budget/policy/audit + 4 切点接入（observe） | 记账报表 + 预算闸测试 |
+ * | M2 | 模块层 A：A1 紧凑输出、A2 渐进纰漏（shadow→enforce 白名单） | 工具面 token 下降 + 归因 |
+ * | M3 | 模块层 B：B1 EDG、B2 GDR（shadow 计算证书，不替换） | 命中率与「本可节省」报表 |
+ * | M4 | B3 CCS enforce（白名单）+ 自动回退 | 真实替换 + 证书链 + 成功率对照 |
+ * | M5 | A3 批量（若宿主支持）、B4 RSI 离线流程、与瓮城回流/信息栏对接 | 离线候选冻结清单 + 面板 |
+ *
+ * 依赖顺序：**M1 必须先行**（没有账本后续收益不可信）；**M4 必须等 M3 的守卫准确率数据**。
+ *
+ * 本文件把这张表变成机器可读的里程碑状态：每个阶段分「实现」与「效果证据」两件事判定，
+ * 缺数据只能说 `effect-unmeasured`，**不许把"实现了"说成"达标了"**。
+ */
+export const MILESTONE_IDS = Object.freeze(['M1', 'M2', 'M3', 'M4', 'M5']);
+/** M4 放行前，M3 需要给出的守卫准确率最小样本量（与 policy.enforce 门禁一致）。 */
+export const M3_MIN_SAMPLES = 20;
+/** M4 放行前要求的最小守卫准确率（与 ENFORCE_GATE.minAccuracy 一致）。 */
+export const M3_MIN_ACCURACY = 0.98;
+/**
+ * M5 回流放行条件：至少 3 条事件拿到对端回执，且对端自报身份在白名单内。
+ * 自环（同一进程里服务端+客户端）与未知 peer 一律不算达标。
+ */
+export const M5_MIN_RELAY_EVENTS = 3;
+export const M5_RELAY_PEERS = Object.freeze(['dsh-fang-bundle', 'contract-server']);
+export const MILESTONES = Object.freeze([
+    Object.freeze({
+        id: 'M1',
+        title: '系统层：ledger/budget/policy/audit + 4 切点接入（observe）',
+        deliverable: '记账报表 + 预算闸测试',
+        dependsOn: [],
+        /** 实现落点（文件存在即视为实现完成；行为由测试保证）。 */
+        implementation: ['src/cost/ledger.ts', 'src/cost/budget.ts', 'src/cost/policy.ts', 'src/cost/audit.ts', 'worker/cost-hooks.ts'],
+        tests: ['test/cost-ledger.test.mjs', 'test/cost-budget.test.mjs', 'test/cost-policy.test.mjs', 'test/cost-audit.test.mjs', 'test/worker-cost-hooks.test.ts', 'test/worker-budget-guard.test.ts'],
+    }),
+    Object.freeze({
+        id: 'M2',
+        title: '模块层 A：A1 紧凑输出、A2 渐进纰漏（shadow→enforce 白名单）',
+        deliverable: '工具面 token 下降 + 归因',
+        dependsOn: ['M1'],
+        implementation: ['worker/tool-compact.ts', 'worker/tool-disclosure.ts', 'src/cost/attribution.ts'],
+        tests: ['test/worker-tool-compact.test.ts', 'test/worker-tool-disclosure.test.ts', 'test/cost-attribution.test.mjs', 'test/cost-disclosure.test.mjs'],
+    }),
+    Object.freeze({
+        id: 'M3',
+        title: '模块层 B：B1 EDG、B2 GDR（shadow 计算证书，不替换）',
+        deliverable: '命中率与「本可节省」报表',
+        dependsOn: ['M1'],
+        implementation: ['worker/edg.ts', 'worker/gdr.ts'],
+        tests: ['test/worker-edg.test.ts', 'test/worker-gdr.test.ts', 'test/worker-decision-spi.test.ts'],
+    }),
+    Object.freeze({
+        id: 'M4',
+        title: 'B3 CCS enforce（白名单）+ 自动回退',
+        deliverable: '真实替换 + 证书链 + 成功率对照',
+        dependsOn: ['M3'],
+        implementation: ['worker/ccs.ts'],
+        tests: ['test/worker-ccs.test.ts', 'test/cost-substitution.test.mjs', 'test/invariants.test.ts'],
+    }),
+    Object.freeze({
+        id: 'M5',
+        title: 'A3 批量（若宿主支持）、B4 RSI 离线流程、与瓮城回流/信息栏对接',
+        deliverable: '离线候选冻结清单 + 面板',
+        dependsOn: ['M1'],
+        implementation: ['worker/tool-batch.ts', 'src/cost/rsi.ts', 'scripts/rsi-offline.mjs', 'client.js'],
+        tests: ['test/worker-tool-batch.test.ts', 'test/cost-rsi.test.mjs'],
+    }),
+]);
+/**
+ * 评估里程碑。
+ *
+ * @param {{
+ *   files?: string[],                       // 仓库里实际存在的文件（相对路径）
+ *   guard?: {samples?: number, accuracy?: number},   // M3 的守卫准确率数据（来自 shadow 报告）
+ *   forkExperiment?: {ok?: boolean},        // M4 的成功率对照（来自 gate 的 G5）
+ *   fangRelay?: {available?: boolean, peer?: string, events?: number,
+ *                sameProcess?: boolean, transport?: string, contractVersion?: string,
+ *                reason?: string},          // M5 的回流对端证据（独立进程实测）
+ * }} evidence
+ */
+export function evaluateMilestones(evidence = {}) {
+    const files = new Set(Array.isArray(evidence.files) ? evidence.files : []);
+    const rows = [];
+    const done = new Set();
+    let relayEvidence = null;
+    for (const milestone of MILESTONES) {
+        const missingImplementation = milestone.implementation.filter((file) => !files.has(file));
+        const missingTests = milestone.tests.filter((file) => !files.has(file));
+        const dependenciesMet = milestone.dependsOn.every((id) => done.has(id));
+        const implemented = missingImplementation.length === 0 && missingTests.length === 0;
+        let effect = 'unmeasured';
+        const reasons = [];
+        if (!implemented) {
+            reasons.push(`missing:${[...missingImplementation, ...missingTests].join('|')}`);
+        }
+        if (!dependenciesMet) {
+            reasons.push(`dependency-unmet:${milestone.dependsOn.filter((id) => !done.has(id)).join('|')}`);
+        }
+        // 各阶段的效果证据要求
+        if (implemented && dependenciesMet) {
+            if (milestone.id === 'M1') {
+                effect = 'verified'; // 系统层效果由测试直接证明（记账、预算闸）
+            }
+            else if (milestone.id === 'M2') {
+                effect = evidence.attributionObserved === true ? 'verified' : 'unmeasured';
+                if (effect === 'unmeasured')
+                    reasons.push('effect-needs-real-token-drop');
+            }
+            else if (milestone.id === 'M3') {
+                const samples = Math.max(0, Number(evidence?.guard?.samples ?? 0) || 0);
+                const accuracy = Number(evidence?.guard?.accuracy ?? 0) || 0;
+                if (samples >= M3_MIN_SAMPLES && accuracy >= M3_MIN_ACCURACY)
+                    effect = 'verified';
+                else
+                    reasons.push(`effect-needs-guard-accuracy(samples=${samples}, accuracy=${accuracy})`);
+            }
+            else if (milestone.id === 'M4') {
+                if (evidence?.forkExperiment?.ok === true)
+                    effect = 'verified';
+                else
+                    reasons.push('effect-needs-fork-success-comparison');
+            }
+            else if (milestone.id === 'M5') {
+                // 回流必须有**对端回执**才算达标：可用 + 非自环 + 对端自报身份在白名单 + 至少 3 条事件。
+                const relay = evidence?.fangRelay && typeof evidence.fangRelay === 'object' ? evidence.fangRelay : null;
+                const available = relay?.available === true;
+                const peer = String(relay?.peer ?? '');
+                const events = Math.max(0, Number(relay?.events ?? 0) || 0);
+                if (!available) {
+                    reasons.push(`fang-relay-unavailable:${String(relay?.reason ?? 'not-provided')}`);
+                }
+                else if (relay?.sameProcess === true) {
+                    reasons.push('fang-relay-self-loop');
+                }
+                else if (!M5_RELAY_PEERS.includes(peer)) {
+                    reasons.push(`fang-relay-peer-invalid:${peer || 'missing'}`);
+                }
+                else if (events < M5_MIN_RELAY_EVENTS) {
+                    reasons.push(`fang-relay-no-receipts(events=${events})`);
+                }
+                else {
+                    effect = 'verified';
+                }
+                relayEvidence = Object.freeze({
+                    available,
+                    peer: peer || null,
+                    events,
+                    sameProcess: relay?.sameProcess === true,
+                    transport: relay?.transport ?? null,
+                    contractVersion: relay?.contractVersion ?? relay?.peerContractVersion ?? null,
+                });
+            }
+        }
+        const status = !implemented
+            ? 'not-implemented'
+            : !dependenciesMet
+                ? 'blocked-by-dependency'
+                : effect === 'verified' ? 'done' : 'implemented-effect-unmeasured';
+        rows.push(Object.freeze({
+            id: milestone.id,
+            title: milestone.title,
+            deliverable: milestone.deliverable,
+            dependsOn: milestone.dependsOn,
+            implemented,
+            dependenciesMet,
+            effect,
+            status,
+            reasons,
+            /** M5：回流对端证据（peer 自报 + 事件数 + 是否自环）；其它阶段为 null。 */
+            relay: relayEvidence,
+            /** 剩余缺口说明（不隐藏）。 */
+            notes: milestone.id === 'M5' && relayEvidence?.peer === 'contract-server'
+                ? ['peer=contract-server：契约对端独立进程实测，dsh-fang-bundle 采用 contract 1.1 后应变为 peer=dsh-fang-bundle']
+                : [],
+        }));
+        if (status === 'done')
+            done.add(milestone.id);
+    }
+    // 依赖顺序的静态校验：M1 必须最先；M4 只依赖 M3。
+    const orderProblems = [];
+    const m1 = MILESTONES.find((item) => item.id === 'M1');
+    if (!m1 || m1.dependsOn.length !== 0)
+        orderProblems.push('M1-must-be-first');
+    const m4 = MILESTONES.find((item) => item.id === 'M4');
+    if (!m4 || !m4.dependsOn.includes('M3'))
+        orderProblems.push('M4-must-depend-on-M3');
+    const allImplemented = rows.every((row) => row.implemented);
+    const allDone = rows.every((row) => row.status === 'done');
+    return Object.freeze({
+        ok: orderProblems.length === 0 && allDone,
+        implementedAll: allImplemented,
+        doneAll: allDone,
+        orderProblems,
+        rows: Object.freeze(rows),
+        /** 摘要在面板/报表用：实现了多少、真达标多少。 */
+        summary: Object.freeze({
+            implemented: rows.filter((row) => row.implemented).length,
+            verified: rows.filter((row) => row.status === 'done').length,
+            total: rows.length,
+        }),
+    });
+}

package/dist-host/cost/modules/index.js

@@ -0,0 +1,5 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// Copyright (c) 2026 dsh-Master contributors — see LICENSE-CORE.
+// @ts-nocheck
+/** 3.3.0 §11：`src/cost/modules/` 入口（模块清单；可执行实现在 worker/，见 manifests.ts 说明）。 */
+export { MODULE_KIND, MODULE_LAYER, MODULE_MODES, MODULE_MANIFESTS, MODULE_IDS, manifestOf, validateManifests, } from "./manifests.js";

package/dist-host/cost/modules/manifests.js

@@ -0,0 +1,130 @@
+// 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 §11：模块清单（`src/cost/modules/`）。
+ *
+ * **进程边界说明（重要）**：A/B 类模块的可执行实现运行在 **fork worker 进程**里，
+ * 因此实体代码在 `worker/`（`tool-compact.ts`、`tool-disclosure.ts`、`tool-batch.ts`、
+ * `edg.ts`、`gdr.ts`、`ccs.ts`）。本目录提供的是**宿主侧清单**：模块 id、层级、默认档、
+ * 开关环境变量、实现文件与文档锚点 —— 供编排器、面板与门禁统一引用，
+ * 避免"宿主侧再抄一份实现"导致两套语义。
+ */
+export const MODULE_KIND = Object.freeze({ tool: 'tool', decision: 'decision' });
+export const MODULE_LAYER = Object.freeze({ a: 'a', b: 'b' });
+export const MODULE_MODES = Object.freeze(['off', 'shadow', 'enforce']);
+/** 7 个模块（A1–A3 / B1–B4）的宿主侧清单。 */
+export const MODULE_MANIFESTS = Object.freeze([
+    Object.freeze({
+        id: 'a1-compact',
+        kind: 'tool',
+        layer: 'a',
+        name: '工具输出紧凑化',
+        implementation: 'worker/tool-compact.ts',
+        defaultMode: 'shadow',
+        envFlag: 'DSH_MASTER_COMPACT_MODE',
+        surfaces: ['worker'],
+        changesObservableSemantics: false,
+        docs: 'docs/DESIGN-v3.3.0-cost-optimization.md#a1-tool-compact工具输出紧凑化',
+    }),
+    Object.freeze({
+        id: 'a2-disclosure',
+        kind: 'tool',
+        layer: 'a',
+        name: '渐进式纰漏',
+        implementation: 'worker/tool-disclosure.ts',
+        defaultMode: 'off',
+        envFlag: 'DSH_MASTER_DISCLOSURE',
+        surfaces: ['worker'],
+        changesObservableSemantics: false,
+        docs: 'docs/DESIGN-v3.3.0-cost-optimization.md#a2-tool-disclosure渐进式纰漏',
+    }),
+    Object.freeze({
+        id: 'a3-batch',
+        kind: 'tool',
+        layer: 'a',
+        name: '批量调用引导',
+        implementation: 'worker/tool-batch.ts',
+        defaultMode: 'shadow',
+        envFlag: 'DSH_MASTER_BATCH',
+        surfaces: ['worker'],
+        changesObservableSemantics: false,
+        docs: 'docs/DESIGN-v3.3.0-cost-optimization.md#a3-tool-batch批量调用',
+    }),
+    Object.freeze({
+        id: 'b1-edg',
+        kind: 'decision',
+        layer: 'b',
+        name: '可执行决策图',
+        implementation: 'worker/edg.ts',
+        defaultMode: 'off',
+        envFlag: 'DSH_MASTER_EDG',
+        surfaces: ['worker'],
+        changesObservableSemantics: false,
+        docs: 'docs/DESIGN-v3.3.0-cost-optimization.md#b1-edg可执行决策图',
+    }),
+    Object.freeze({
+        id: 'b2-gdr',
+        kind: 'decision',
+        layer: 'b',
+        name: '回执守卫',
+        implementation: 'worker/gdr.ts',
+        defaultMode: 'off',
+        envFlag: 'DSH_MASTER_GDR',
+        surfaces: ['worker'],
+        changesObservableSemantics: false,
+        docs: 'docs/DESIGN-v3.3.0-cost-optimization.md#b2-gdr回执守卫',
+    }),
+    Object.freeze({
+        id: 'b3-ccs',
+        kind: 'decision',
+        layer: 'b',
+        name: '认证回调替换',
+        implementation: 'worker/ccs.ts',
+        defaultMode: 'off',
+        envFlag: 'DSH_MASTER_CCS',
+        surfaces: ['worker'],
+        /** 替换会**跳过模型推理**：只在 enforce + 白名单下发生。 */
+        changesObservableSemantics: false,
+        docs: 'docs/DESIGN-v3.3.0-cost-optimization.md#b3-ccs认证回调替换',
+    }),
+    Object.freeze({
+        id: 'b4-rsi',
+        kind: 'decision',
+        layer: 'b',
+        name: '离线自改进',
+        implementation: 'src/cost/rsi.ts',
+        defaultMode: 'off',
+        envFlag: null,
+        surfaces: ['host'],
+        changesObservableSemantics: false,
+        docs: 'docs/DESIGN-v3.3.0-cost-optimization.md#b4-rsi离线自改进',
+    }),
+]);
+export const MODULE_IDS = Object.freeze(MODULE_MANIFESTS.map((manifest) => manifest.id));
+export function manifestOf(id) {
+    return MODULE_MANIFESTS.find((manifest) => manifest.id === String(id)) ?? null;
+}
+/** 校验清单自身：7 个模块、id 唯一、默认档合法。 */
+export function validateManifests(manifests = MODULE_MANIFESTS) {
+    const problems = [];
+    const ids = new Set();
+    for (const manifest of manifests) {
+        if (!manifest?.id)
+            problems.push('missing-id');
+        if (ids.has(manifest?.id))
+            problems.push(`duplicate-id:${manifest.id}`);
+        ids.add(manifest?.id);
+        if (!MODULE_MODES.includes(manifest?.defaultMode))
+            problems.push(`bad-default-mode:${manifest?.id}`);
+        if (!MODULE_KIND[manifest?.kind])
+            problems.push(`bad-kind:${manifest?.id}`);
+        if (!MODULE_LAYER[manifest?.layer])
+            problems.push(`bad-layer:${manifest?.id}`);
+        if (manifest?.changesObservableSemantics !== false)
+            problems.push(`observable-semantics:${manifest?.id}`);
+    }
+    if (manifests.length !== 7)
+        problems.push(`module-count:${manifests.length}!=7`);
+    return { ok: problems.length === 0, problems };
+}

package/dist-host/cost/policy.js

@@ -0,0 +1,276 @@
+// 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 系统层 · policy（灰度与回滚，设计 §5.3）。
+ *
+ * 三档语义：
+ *   * `observe`  —— 只计量、只计算命中，**绝不替换**（3.2.x 现状，默认档）；
+ *   * `shadow`   —— 决策层真实计算守卫结果并落证书，但**仍调用慢模型**（可对比「本可节省」）；
+ *   * `enforce`  —— 守卫命中才真正替换，且受白名单（forkId / task 标签 / 工具集）限制。
+ *
+ * 粒度：`global → forkId → taskId`，取**最严格**档（observe 最严格，enforce 最宽松）。
+ * 默认 observe；enforce 只能由显式配置或用户指令开启（过门禁，不自动升级）。
+ * 任何时刻都可降级（回滚优先）。
+ */
+import { ENFORCE_GATE, POLICY_MODES } from "./types.js";
+/** 越靠前越严格（限制越少自动化）。 */
+const STRICTNESS = Object.freeze(['observe', 'shadow', 'enforce']);
+function mostRestrictive(modes) {
+    const valid = modes.filter((mode) => POLICY_MODES.includes(mode));
+    if (valid.length === 0)
+        return 'observe';
+    return valid.reduce((strict, current) => (STRICTNESS.indexOf(current) < STRICTNESS.indexOf(strict) ? current : strict));
+}
+function normalizeList(input) {
+    const list = Array.isArray(input) ? input : [];
+    return Object.freeze([...new Set(list.map((item) => String(item ?? '').trim()).filter(Boolean))]);
+}
+/**
+ * 归一化白名单：兼容 3.3.0 早期的扁平数组（等价于「forkId 或标签命中」），
+ * 也接受显式四维对象 `{forks, tasks, tags, tools}`。空维度 = 该维度不限制。
+ */
+function normalizeAllowlist(input) {
+    if (Array.isArray(input)) {
+        const flat = normalizeList(input);
+        return Object.freeze({ legacy: true, forks: flat, tasks: Object.freeze([]), tags: flat, tools: Object.freeze([]) });
+    }
+    const source = input && typeof input === 'object' ? input : {};
+    return Object.freeze({
+        legacy: false,
+        forks: normalizeList(source.forks),
+        tasks: normalizeList(source.tasks),
+        tags: normalizeList(source.tags),
+        tools: normalizeList(source.tools),
+    });
+}
+/**
+ * @param {{
+ *   mode?: string,
+ *   scopes?: { global?: string, forks?: Record<string,string>, tasks?: Record<string,string> },
+ *   allowlist?: string[] | { forks?: string[], tasks?: string[], tags?: string[], tools?: string[] },
+ *   audit?: { append?: Function },
+ *   now?: () => number,
+ * }} [options]
+ */
+export function createPolicy(options = {}) {
+    const now = typeof options.now === 'function' ? options.now : () => Date.now();
+    const audit = options.audit && typeof options.audit.append === 'function' ? options.audit : null;
+    const allowlist = normalizeAllowlist(options.allowlist);
+    const requestedMode = String(options.mode ?? 'observe');
+    let mode = POLICY_MODES.includes(requestedMode) ? requestedMode : 'observe';
+    let lastRefusal = null;
+    const scopes = options.scopes && typeof options.scopes === 'object' ? options.scopes : {};
+    const forkScopes = scopes.forks && typeof scopes.forks === 'object' ? { ...scopes.forks } : {};
+    const taskScopes = scopes.tasks && typeof scopes.tasks === 'object' ? { ...scopes.tasks } : {};
+    /** 命中计数（observe 也要算，不然「灰度」无从判断）。 */
+    const hits = new Map();
+    const CERTIFICATE_LIMIT = 200;
+    const certificates = [];
+    const record = (type, payload) => {
+        try {
+            audit?.append({ type, actor: 'cost-policy', payload });
+        }
+        catch { /* 审计失败不改变策略行为 */ }
+    };
+    /** 解析当前上下文的生效档：global → fork → task，取最严格。 */
+    function resolve(context = {}) {
+        const forkId = String(context.forkId ?? '');
+        const taskId = String(context.taskId ?? '');
+        const layers = [{ scope: 'global', mode }];
+        if (forkId && POLICY_MODES.includes(String(forkScopes[forkId]))) {
+            layers.push({ scope: 'fork', mode: String(forkScopes[forkId]) });
+        }
+        if (taskId && POLICY_MODES.includes(String(taskScopes[taskId]))) {
+            layers.push({ scope: 'task', mode: String(taskScopes[taskId]) });
+        }
+        const effective = mostRestrictive(layers.map((layer) => layer.mode));
+        return Object.freeze({
+            mode: effective,
+            decidedBy: layers.find((layer) => layer.mode === effective)?.scope ?? 'global',
+            layers,
+        });
+    }
+    /** enforce 是否被白名单放行（forkId / taskId / tags / toolName 四个维度，非空维度必须命中）。 */
+    function allowlisted(context = {}) {
+        const forkId = String(context.forkId ?? '');
+        const taskId = String(context.taskId ?? '');
+        const tags = Array.isArray(context.tags) ? context.tags.map((tag) => String(tag)) : [];
+        const toolName = String(context.toolName ?? '');
+        if (allowlist.legacy) {
+            if (allowlist.forks.length === 0)
+                return { ok: false, reason: 'allowlist-empty' };
+            const matched = (forkId !== '' && allowlist.forks.includes(forkId)) || tags.some((tag) => allowlist.tags.includes(tag));
+            return matched ? { ok: true, reason: null } : { ok: false, reason: 'allowlist-miss' };
+        }
+        if (allowlist.forks.length === 0 && allowlist.tasks.length === 0 && allowlist.tags.length === 0 && allowlist.tools.length === 0) {
+            return { ok: false, reason: 'allowlist-empty' };
+        }
+        if (allowlist.forks.length > 0 && !(forkId !== '' && allowlist.forks.includes(forkId)))
+            return { ok: false, reason: 'fork-not-allowlisted' };
+        if (allowlist.tasks.length > 0 && !(taskId !== '' && allowlist.tasks.includes(taskId)))
+            return { ok: false, reason: 'task-not-allowlisted' };
+        if (allowlist.tags.length > 0 && !tags.some((tag) => allowlist.tags.includes(tag)))
+            return { ok: false, reason: 'tag-not-allowlisted' };
+        if (allowlist.tools.length > 0 && !(toolName !== '' && allowlist.tools.includes(toolName)))
+            return { ok: false, reason: 'tool-not-allowlisted' };
+        return { ok: true, reason: null };
+    }
+    /**
+     * 决策复用模块在守卫「命中」时调用（B1/B2/B3 都会经过这里）。
+     *   observe —— 只计数；
+     *   shadow  —— 计数 + 落证书（记录本可节省），**不替换**；
+     *   enforce —— 计数 + 落证书 + 允许替换（还需白名单命中）。
+     */
+    function recordHit(input = {}) {
+        const context = { forkId: input.forkId, taskId: input.taskId, tags: input.tags, toolName: input.toolName };
+        const resolved = resolve(context);
+        const key = `${resolved.mode}:${String(input.module ?? 'unattributed')}`;
+        const row = hits.get(key) ?? { mode: resolved.mode, module: String(input.module ?? 'unattributed'), hits: 0, wouldSaveTokens: 0, substituted: 0 };
+        row.hits += 1;
+        row.wouldSaveTokens += Math.max(0, Number(input.wouldSaveTokens ?? 0) || 0);
+        hits.set(key, row);
+        let certificate = null;
+        if (resolved.mode === 'observe') {
+            return Object.freeze({ ok: true, mode: 'observe', substituted: false, counted: true, certificate: null, resolved });
+        }
+        const allowed = resolved.mode === 'enforce' ? allowlisted(context) : { ok: false, reason: 'shadow-does-not-substitute' };
+        const substituted = resolved.mode === 'enforce' && allowed.ok;
+        if (substituted)
+            row.substituted += 1;
+        certificate = Object.freeze({
+            at: now(),
+            module: String(input.module ?? 'unattributed'),
+            guardId: input.guardId === undefined ? null : String(input.guardId),
+            edgeId: input.edgeId === undefined ? null : String(input.edgeId),
+            receiptHash: input.receiptHash === undefined ? null : String(input.receiptHash),
+            mode: resolved.mode,
+            substituted,
+            wouldSaveTokens: Math.max(0, Number(input.wouldSaveTokens ?? 0) || 0),
+            allowlist: allowed.ok ? 'matched' : allowed.reason,
+        });
+        certificates.push(certificate);
+        if (certificates.length > CERTIFICATE_LIMIT)
+            certificates.shift();
+        record('policy.hit', { ...certificate });
+        return Object.freeze({
+            ok: true,
+            mode: resolved.mode,
+            substituted,
+            counted: true,
+            certificate,
+            resolved,
+            allowlist: allowed,
+        });
+    }
+    function describe() {
+        return Object.freeze({
+            mode,
+            requestedMode,
+            scopes: Object.freeze({ global: mode, forks: Object.freeze({ ...forkScopes }), tasks: Object.freeze({ ...taskScopes }) }),
+            allowlist: Object.freeze({
+                legacy: allowlist.legacy,
+                forks: allowlist.forks.slice(),
+                tasks: allowlist.tasks.slice(),
+                tags: allowlist.tags.slice(),
+                tools: allowlist.tools.slice(),
+            }),
+            gate: { minAccuracy: ENFORCE_GATE.minAccuracy, minSamples: ENFORCE_GATE.minSamples, allowlistRequired: true },
+            lastRefusal,
+        });
+    }
+    function canEnforce(context = {}) {
+        if (resolve(context).mode !== 'enforce')
+            return false;
+        return allowlisted(context).ok;
+    }
+    function requestMode(next, evidence = {}) {
+        const target = String(next);
+        if (!POLICY_MODES.includes(target)) {
+            return { ok: false, code: 'mode-invalid', message: `mode must be one of ${POLICY_MODES.join('/')}` };
+        }
+        if (target === mode)
+            return { ok: true, mode, unchanged: true, at: now() };
+        const from = mode;
+        if (target === 'enforce') {
+            const reasons = [];
+            if (from === 'observe' && evidence.force !== true)
+                reasons.push('shadow-required');
+            const accuracy = Number(evidence.accuracy);
+            if (!Number.isFinite(accuracy) || accuracy < ENFORCE_GATE.minAccuracy)
+                reasons.push('accuracy-below-threshold');
+            const samples = Number(evidence.samples);
+            if (!Number.isFinite(samples) || samples < ENFORCE_GATE.minSamples)
+                reasons.push('samples-below-threshold');
+            const destructiveHits = Number(evidence.destructiveHits ?? 0);
+            if (!Number.isFinite(destructiveHits) || destructiveHits > 0)
+                reasons.push('destructive-hits');
+            const allowlistEmpty = allowlist.legacy
+                ? allowlist.forks.length === 0
+                : allowlist.forks.length === 0 && allowlist.tasks.length === 0 && allowlist.tags.length === 0 && allowlist.tools.length === 0;
+            if (allowlistEmpty)
+                reasons.push('allowlist-empty');
+            if (reasons.length > 0) {
+                lastRefusal = Object.freeze({ at: now(), next: target, reasons });
+                record('policy.refused', { from, to: target, reasons });
+                return { ok: false, code: 'enforce-gate-failed', reasons, mode, at: lastRefusal.at };
+            }
+        }
+        mode = target;
+        lastRefusal = null;
+        record('policy.mode', { from, to: target, evidence: { ...evidence } });
+        return { ok: true, mode, from, at: now() };
+    }
+    function setMode(next) {
+        const target = String(next);
+        if (!POLICY_MODES.includes(target)) {
+            return { ok: false, code: 'mode-invalid', message: `mode must be one of ${POLICY_MODES.join('/')}` };
+        }
+        if (target === mode)
+            return { ok: true, mode, unchanged: true };
+        const from = mode;
+        mode = target;
+        record('policy.rollback', { from, to: target });
+        return { ok: true, mode, from };
+    }
+    /** 设置某个 fork / task 的档位（只能更严格或经 enforce 门禁前先下沉）。 */
+    function setScope(scope, id, next) {
+        const target = String(next);
+        if (!POLICY_MODES.includes(target)) {
+            return { ok: false, code: 'mode-invalid', message: `mode must be one of ${POLICY_MODES.join('/')}` };
+        }
+        const key = String(id ?? '').trim();
+        if (!key)
+            return { ok: false, code: 'scope-id-invalid', message: 'scope id must be a non-empty string' };
+        if (scope === 'fork')
+            forkScopes[key] = target;
+        else if (scope === 'task')
+            taskScopes[key] = target;
+        else
+            return { ok: false, code: 'scope-invalid', message: 'scope must be fork or task' };
+        record('policy.scope', { scope, id: key, to: target });
+        return { ok: true, scope, id: key, mode: target };
+    }
+    function stats() {
+        return Object.freeze({
+            ok: true,
+            rows: [...hits.values()].map((row) => Object.freeze({ ...row })),
+            totalHits: [...hits.values()].reduce((sum, row) => sum + row.hits, 0),
+            totalWouldSaveTokens: [...hits.values()].reduce((sum, row) => sum + row.wouldSaveTokens, 0),
+            totalSubstituted: [...hits.values()].reduce((sum, row) => sum + row.substituted, 0),
+            certificates: certificates.slice(-50),
+        });
+    }
+    return Object.freeze({
+        describe,
+        resolve,
+        allowlisted,
+        recordHit,
+        stats,
+        canEnforce,
+        requestMode,
+        setMode,
+        setScope,
+        isEnforce: (context = {}) => resolve(context).mode === 'enforce',
+    });
+}