@twinsearth/dsh-master 3.2.10 → 3.3.1

package/dist-host/cost/experiment.js

@@ -0,0 +1,132 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// Copyright (c) 2026 dsh-Master contributors — see LICENSE-CORE.
+// @ts-nocheck — host JS→TS 迁移阶段：运行时行为优先，类型注解逐步补齐（worker/ 仍严格检查）。
+/**
+ * M5 实验台：**A/B 对照执行器**（control = ccs off / enforce = ccs enforce）。
+ *
+ * 设计原则（决定它能不能当证据）：
+ *   * 走**真实 Worker 代码路径**（工具注册表、A1 紧凑、A3 批量、B1/B2/B3 全都在）；
+ *   * 每组 ≥10 任务，**同一 corpus 同一顺序**，control 与 enforce 只差一个开关；
+ *   * 输出**同表**：tokens/task 与成功率并列，绝不只报实验组；
+ *   * **自报口径**：`harness:'local-dry-run'` 与 `runner` 字段写进结果 ——
+ *     用脚本化 LLM 跑的 dry run 不能冒充「真实 fork 实机」证据（G5 会因此继续被挡住）。
+ */
+export const EXPERIMENT_HARNESS = Object.freeze({
+    dryRun: 'local-dry-run',
+    /** 真实 provider + 真实 Worker 代码路径（票据可以是合成的，但模型与工具是真的）。 */
+    realProvider: 'real-provider-real-worker',
+    realFork: 'real-fork',
+});
+const num = (value) => {
+    const n = Number(value);
+    return Number.isFinite(n) ? n : 0;
+};
+/**
+ * 单组执行：把 corpus 逐个跑完，收集指标。
+ *
+ * @param {{
+ *   tasks: Array<{taskId: string, run: (task: object) => Promise<object>}>,
+ *   group: 'control' | 'enforce',
+ * }} input
+ */
+export async function runGroup(input = {}) {
+    const tasks = Array.isArray(input.tasks) ? input.tasks : [];
+    const rows = [];
+    for (const task of tasks) {
+        const startedAt = Date.now();
+        let result;
+        try {
+            result = await task.run(task);
+        }
+        catch (error) {
+            result = { ok: false, error: { code: 'harness-error', message: error instanceof Error ? error.message : String(error) } };
+        }
+        const elapsedMs = Date.now() - startedAt;
+        const cost = result?.cost ?? {};
+        rows.push({
+            taskId: String(task.taskId),
+            ok: result?.ok === true,
+            tokens: num(result?.tokenUsage),
+            elapsedMs: num(result?.elapsedMs) || elapsedMs,
+            steps: Array.isArray(result?.steps) ? result.steps.length : 0,
+            a1: cost.compaction
+                ? {
+                    mode: cost.compaction.mode,
+                    applied: cost.compaction.applied === true,
+                    savedChars: num(cost.compaction.savedChars),
+                    estimatedTokens: num(cost.compaction.estimatedTokens),
+                }
+                : null,
+            a3: cost.batch ? { taught: cost.batch.taught === true, corrections: num(cost.batch.corrections) } : null,
+            reuse: cost.ccs
+                ? {
+                    mode: cost.ccs.mode,
+                    attempts: Array.isArray(cost.ccs.attempts) ? cost.ccs.attempts.length : 0,
+                    hits: Array.isArray(cost.ccs.attempts) ? cost.ccs.attempts.filter((item) => item.hit === true).length : 0,
+                    wouldSaveTokens: Array.isArray(cost.ccs.attempts) ? cost.ccs.attempts.reduce((sum, item) => sum + num(item.wouldSaveTokens), 0) : 0,
+                    skippedModelCalls: num(cost.ccs.skippedModelCalls),
+                    substitutions: Array.isArray(cost.ccs.substitutions) ? cost.ccs.substitutions.length : 0,
+                    dispatched: Array.isArray(cost.ccs.substitutions) ? cost.ccs.substitutions.filter((cert) => cert.dispatched === true).length : 0,
+                    failures: Array.isArray(cost.ccs.substitutions) ? cost.ccs.substitutions.filter((cert) => cert.dispatched === false).length : 0,
+                    shadowCertificates: Array.isArray(cost.ccs.shadowCertificates) ? cost.ccs.shadowCertificates.length : 0,
+                }
+                : null,
+        });
+    }
+    return { group: String(input.group ?? 'unknown'), tasks: rows };
+}
+/** 两组同表对比（成功率差值按 §10.1 的 2pp 门禁）。 */
+export function compareGroups({ control, enforce, harness = EXPERIMENT_HARNESS.dryRun, runner = 'scripted-llm' } = {}) {
+    const avg = (rows) => (rows.length > 0 ? rows.reduce((sum, row) => sum + num(row.tokens), 0) / rows.length : null);
+    const rate = (rows) => (rows.length > 0 ? rows.filter((row) => row.ok === true).length / rows.length : null);
+    const ctl = Array.isArray(control?.tasks) ? control.tasks : [];
+    const trt = Array.isArray(enforce?.tasks) ? enforce.tasks : [];
+    const controlTokens = avg(ctl);
+    const enforceTokens = avg(trt);
+    const controlSuccess = rate(ctl);
+    const enforceSuccess = rate(trt);
+    const tokenDeltaPct = controlTokens !== null && enforceTokens !== null && controlTokens > 0
+        ? (enforceTokens - controlTokens) / controlTokens
+        : null;
+    const successDelta = controlSuccess !== null && enforceSuccess !== null ? enforceSuccess - controlSuccess : null;
+    const reuse = trt.map((row) => row.reuse).filter(Boolean);
+    const a1 = trt.map((row) => row.a1).filter(Boolean);
+    return Object.freeze({
+        harness,
+        runner,
+        /** 这条是给 G5 用的：dry-run 永远不足以当证据；真实 provider + 真实 worker 才算测量有效。 */
+        qualifiesForGate: harness === EXPERIMENT_HARNESS.realFork || harness === EXPERIMENT_HARNESS.realProvider,
+        table: [
+            { group: 'control', samples: ctl.length, tokensPerTask: controlTokens, successRate: controlSuccess, elapsedMsMedian: median(ctl.map((row) => num(row.elapsedMs))) },
+            { group: 'enforce', samples: trt.length, tokensPerTask: enforceTokens, successRate: enforceSuccess, elapsedMsMedian: median(trt.map((row) => num(row.elapsedMs))) },
+        ],
+        delta: { tokensPerTask: controlTokens !== null && enforceTokens !== null ? enforceTokens - controlTokens : null, tokensPerTaskPct: tokenDeltaPct, successRate: successDelta },
+        a1: {
+            tasks: a1.length,
+            /** pplied 只反映**最后一次**压缩事件；真正判断贡献要看是否产生了估算节省。 */
+            tasksWithSavings: a1.filter((row) => num(row.estimatedTokens) > 0).length,
+            applied: a1.filter((row) => row.applied === true).length,
+            estimatedTokens: a1.reduce((sum, row) => sum + num(row.estimatedTokens), 0),
+        },
+        reuse: {
+            attempts: reuse.reduce((sum, row) => sum + num(row.attempts), 0),
+            hits: reuse.reduce((sum, row) => sum + num(row.hits), 0),
+            wouldSaveTokens: reuse.reduce((sum, row) => sum + num(row.wouldSaveTokens), 0),
+            skippedModelCalls: reuse.reduce((sum, row) => sum + num(row.skippedModelCalls), 0),
+            dispatched: reuse.reduce((sum, row) => sum + num(row.dispatched), 0),
+            failures: reuse.reduce((sum, row) => sum + num(row.failures), 0),
+            shadowCertificates: reuse.reduce((sum, row) => sum + num(row.shadowCertificates), 0),
+        },
+        /** 与 gate G5 同形，便于直接喂 `evaluateForkExperiment`。 */
+        gateShape: Object.freeze({
+            control: { tasks: ctl.map((row) => ({ taskId: row.taskId, tokens: row.tokens, success: row.ok })) },
+            enforce: { tasks: trt.map((row) => ({ taskId: row.taskId, tokens: row.tokens, success: row.ok })) },
+        }),
+    });
+}
+function median(values) {
+    const sorted = [...values].sort((a, b) => a - b);
+    if (sorted.length === 0)
+        return null;
+    return sorted[Math.min(sorted.length - 1, Math.ceil(0.5 * sorted.length) - 1)];
+}

package/dist-host/cost/fang-relay.js

@@ -0,0 +1,329 @@
+// 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.1 · 瓮城回流出口（设计 §5.6，里程碑 M5）。
+ *
+ * 3.3.0 里这条通道是硬编码的 `{ target:'fang', available:false,
+ * reason:'fang-channel-not-ready' }`：接口位在，但没有实现。3.3.1 把它换成
+ * **真实探测 + 真实投递**：
+ *
+ *   1. `probe()`：用契约 SDK 的 `hello()` 协商，看对端在公共 minor 下是否宣告
+ *      `fang.relay.publish` / `fang.relay.status`（contract 1.1 才有的方法）；
+ *      宣告了再读一次 `fang.relay.status` 确认对端**真的在服务**，不是只挂方法名。
+ *   2. `enqueue()` / `flush()`：把 `cost:event` / `cost:degraded` /
+ *      `cost:substitution` 批量投递，按事件 id 幂等，回执里的 `accepted` /
+ *      `duplicates` / `cursor` 才是“送达”的唯一证据。
+ *   3. `status()`：同步返回**最近一次已知状态**（`probe()` 异步更新）。
+ *
+ * 两条硬约束（与 I1–I8 一致）：
+ *   * 不可用必须显式 `available:false` + 具体原因，**不得**把队列长度当送达；
+ *   * 投递失败不重试成“假成功”：批次退回队列、`failed` 计数、状态转不可用，
+ *     并保留 `lastError`。
+ *
+ * 对端身份（`peer`）由对端在 `fang.relay.status` 里**自报**（如
+ * `dsh-fang-bundle` / `contract-server`），只用于记录“对端是谁”，不参与鉴权，
+ * 也不得被当成“已对接真实瓮城”的证据 —— 那需要 `peer === 'dsh-fang-bundle'`。
+ */
+import path from 'node:path';
+import { METHODS, createContractClient } from '../contract/index.js';
+/** 允许作为 M5 证据的对端标识（自报值白名单）。 */
+export const RELAY_PEERS = Object.freeze(['dsh-fang-bundle', 'contract-server']);
+/** 默认值：批量/队列/探测都有界，避免长跑进程无界增长。 */
+export const RELAY_DEFAULTS = Object.freeze({
+    maxBatch: 32,
+    maxQueue: 500,
+    probeTtlMs: 60_000,
+    timeoutMs: 15_000,
+});
+function asString(value) { return String(value ?? '').trim(); }
+function clampInt(value, fallback, min, max) {
+    const n = Number(value);
+    if (!Number.isFinite(n))
+        return fallback;
+    return Math.min(max, Math.max(min, Math.floor(n)));
+}
+function describeError(error) {
+    const code = asString(error?.code) || 'relay-error';
+    const message = asString(error?.message ?? error);
+    return message ? `${code}:${message.slice(0, 160)}` : code;
+}
+/**
+ * 创建回流出口。
+ *
+ * @param {{
+ *   client?: object | null,          // createContractClient() 的返回值；null ⇒ 明确不可用
+ *   target?: string,
+ *   now?: () => number,
+ *   maxBatch?: number, maxQueue?: number, probeTtlMs?: number, timeoutMs?: number,
+ *   logger?: object,
+ * }} [options]
+ */
+export function createFangRelay(options = {}) {
+    const client = options.client && typeof options.client === 'object' ? options.client : null;
+    const target = asString(options.target) || 'fang';
+    const now = typeof options.now === 'function' ? options.now : () => Date.now();
+    const maxBatch = clampInt(options.maxBatch, RELAY_DEFAULTS.maxBatch, 1, 128);
+    const maxQueue = clampInt(options.maxQueue, RELAY_DEFAULTS.maxQueue, 1, 5_000);
+    const probeTtlMs = clampInt(options.probeTtlMs, RELAY_DEFAULTS.probeTtlMs, 1_000, 600_000);
+    const timeoutMs = clampInt(options.timeoutMs, RELAY_DEFAULTS.timeoutMs, 1_000, 300_000);
+    const logger = options.logger ?? null;
+    const queue = [];
+    const counters = { enqueued: 0, delivered: 0, duplicates: 0, failed: 0, dropped: 0, batches: 0, roundTrips: 0 };
+    let sequence = 0;
+    let batchSequence = 0;
+    let cursor = null;
+    let lastError = null;
+    let lastDeliveredAt = 0;
+    let probing = null;
+    // 没有客户端时开局即知不可用（不需要“探测中”这种灰色状态去掩盖）。
+    let state = Object.freeze({
+        available: false,
+        reason: client ? 'probe-pending' : 'relay-client-absent',
+        peer: null,
+        peerContractVersion: null,
+        transport: null,
+        probedAt: 0,
+    });
+    function setState(next) {
+        state = Object.freeze({ ...state, probedAt: now(), ...next });
+    }
+    function status() {
+        return Object.freeze({
+            target,
+            available: state.available === true,
+            reason: state.reason ?? null,
+            peer: state.peer ?? null,
+            peerContractVersion: state.peerContractVersion ?? null,
+            transport: state.transport ?? null,
+            delivered: counters.delivered,
+            failed: counters.failed,
+            queued: queue.length,
+            dropped: counters.dropped,
+            duplicates: counters.duplicates,
+            batches: counters.batches,
+            cursor,
+            lastError,
+            lastDeliveredAt,
+            probedAt: state.probedAt,
+            limits: { maxBatch, maxQueue, probeTtlMs, timeoutMs },
+        });
+    }
+    /** 探测对端：hello 协商 → 方法裁剪判定 → 读一次 relay 状态确认真的可用。 */
+    async function probe({ force = false } = {}) {
+        if (!client) {
+            setState({ available: false, reason: 'relay-client-absent', peer: null });
+            return status();
+        }
+        if (!force && state.probedAt > 0 && now() - state.probedAt < probeTtlMs)
+            return status();
+        if (probing)
+            return probing;
+        probing = (async () => {
+            try {
+                const hello = await client.hello(true);
+                if (!hello || hello.ok !== true) {
+                    setState({ available: false, reason: `hello-failed:${asString(hello?.code) || 'unknown'}`, peer: null });
+                    return status();
+                }
+                const methods = Array.isArray(hello.negotiation?.methods) ? hello.negotiation.methods : [];
+                const peerContractVersion = asString(hello.hello?.contractVersion) || null;
+                const offersRelay = methods.includes(METHODS.RELAY_PUBLISH) && methods.includes(METHODS.RELAY_STATUS);
+                if (!offersRelay) {
+                    // 1.0 对端不会宣告 1.1 方法；这是“协议层没有回流”，不是传输故障。
+                    setState({
+                        available: false,
+                        reason: `peer-contract-without-relay:${peerContractVersion ?? 'unknown'}`,
+                        peer: null,
+                        peerContractVersion,
+                        transport: asString(hello.transport) || null,
+                    });
+                    return status();
+                }
+                const remote = await client.relayStatus({}, { timeoutMs });
+                if (!remote || remote.ok !== true) {
+                    setState({
+                        available: false,
+                        reason: `relay-status-failed:${asString(remote?.code) || 'unknown'}`,
+                        peer: null,
+                        peerContractVersion,
+                        transport: asString(hello.transport) || null,
+                    });
+                    return status();
+                }
+                const result = remote.response?.result ?? {};
+                cursor = Number.isFinite(Number(result.cursor)) ? Number(result.cursor) : cursor;
+                setState({
+                    available: true,
+                    reason: null,
+                    peer: asString(result.peer) || null,
+                    peerContractVersion: asString(result.contractVersion) || peerContractVersion,
+                    transport: asString(remote.transport ?? hello.transport) || null,
+                });
+                return status();
+            }
+            catch (error) {
+                setState({ available: false, reason: `probe-threw:${describeError(error)}`, peer: null });
+                try {
+                    logger?.warn?.(`[cost-relay] probe failed: ${describeError(error)}`);
+                }
+                catch { /* ignore */ }
+                return status();
+            }
+        })();
+        try {
+            return await probing;
+        }
+        finally {
+            probing = null;
+        }
+    }
+    /** 入队一条总线事件；不可用时不假装收下（记 dropped 并返回原因）。 */
+    function enqueue(event = {}) {
+        if (state.available !== true) {
+            counters.dropped += 1;
+            return { ok: false, code: 'relay-unavailable', reason: state.reason ?? 'unknown' };
+        }
+        const type = asString(event.type) || 'cost:event';
+        sequence += 1;
+        const item = Object.freeze({
+            // id 稳定且唯一：重投同一批时对端按 id 去重，不会重复记账。
+            id: `cost-${type}-${sequence}-${Math.max(0, Math.floor(Number(event.at ?? now()) || 0))}`,
+            type,
+            at: Math.max(0, Math.floor(Number(event.at ?? now()) || 0)),
+            payload: event.payload && typeof event.payload === 'object' ? { ...event.payload } : {},
+        });
+        if (queue.length >= maxQueue) {
+            queue.shift();
+            counters.dropped += 1;
+        }
+        queue.push(item);
+        counters.enqueued += 1;
+        return { ok: true, id: item.id, queued: queue.length };
+    }
+    /** 投递一个批次；失败时批次退回队列并把状态转不可用（不吞错）。 */
+    async function flush() {
+        if (!client)
+            return { ok: false, code: 'relay-client-absent', ...status() };
+        if (state.available !== true)
+            return { ok: false, code: 'relay-unavailable', reason: state.reason ?? 'unknown', ...status() };
+        if (queue.length === 0)
+            return { ok: true, delivered: 0, sent: 0, queued: 0 };
+        const batch = queue.slice(0, maxBatch);
+        batchSequence += 1;
+        const batchId = `relay-${batchSequence}`;
+        let outcome = null;
+        try {
+            outcome = await client.publishRelay({ batchId, events: batch }, { timeoutMs });
+        }
+        catch (error) {
+            outcome = { ok: false, code: 'relay-threw', error: describeError(error) };
+        }
+        counters.roundTrips += 1;
+        if (outcome && outcome.ok === true) {
+            const result = outcome.response?.result ?? {};
+            const accepted = Math.max(0, Number(result.accepted ?? 0) || 0);
+            const duplicates = Math.max(0, Number(result.duplicates ?? 0) || 0);
+            // 只有对端回执才算送达：从队列头移除本次实际发送的批次。
+            queue.splice(0, batch.length);
+            counters.batches += 1;
+            counters.delivered += accepted + duplicates;
+            counters.duplicates += duplicates;
+            if (Number.isFinite(Number(result.cursor)))
+                cursor = Number(result.cursor);
+            lastDeliveredAt = now();
+            lastError = null;
+            return { ok: true, delivered: accepted, duplicates, sent: batch.length, queued: queue.length, cursor, batchId };
+        }
+        const code = asString(outcome?.code) || 'publish-failed';
+        const detail = asString(outcome?.failures?.[0]?.code) || asString(outcome?.error);
+        lastError = detail && !detail.startsWith(code) ? `${code}:${detail}`.slice(0, 200) : (detail || code);
+        counters.failed += batch.length;
+        setState({ available: false, reason: `publish-failed:${lastError}` });
+        try {
+            logger?.warn?.(`[cost-relay] publish failed: ${lastError}`);
+        }
+        catch { /* ignore */ }
+        return { ok: false, code, error: lastError, sent: batch.length, queued: queue.length };
+    }
+    /** 挂到事件总线上：订阅者异常与投递异常都不影响主流程。 */
+    function attach(bus) {
+        if (!bus || typeof bus.subscribe !== 'function')
+            return () => { };
+        return bus.subscribe((event) => {
+            try {
+                enqueue(event);
+            }
+            catch { /* 回流不得影响主流程 */ }
+        });
+    }
+    function reset() {
+        queue.length = 0;
+        lastError = null;
+        setState({ available: false, reason: 'probe-pending', peer: null });
+        return status();
+    }
+    return Object.freeze({ target, probe, enqueue, flush, attach, status, reset, describe: status });
+}
+/**
+ * 从插件配置/环境装配契约客户端。
+ *
+ * 未配置任何传输时返回 null（**不**创建空客户端去假装探测过）。
+ *
+ * @param {object} ctx
+ * @param {{relay?: object, dispatch?: object}} [config]
+ * @param {{fetchImpl?: typeof fetch, env?: object}} [options]
+ */
+export function createRelayClient(ctx, config = {}, options = {}) {
+    const raw = config.relay && typeof config.relay === 'object' ? config.relay : {};
+    const dispatch = config.dispatch && typeof config.dispatch === 'object' ? config.dispatch : {};
+    const env = options.env ?? process.env;
+    const fetchImpl = options.fetchImpl ?? fetch;
+    const httpBaseUrl = asString(raw.httpBaseUrl) || asString(dispatch.motherUrl) || asString(env.DSH_FANG_CONTRACT_URL) || asString(env.DSH_MASTER_MOTHER_URL);
+    const httpToken = asString(raw.httpToken) || asString(dispatch.motherToken) || asString(env.DSH_FANG_CONTRACT_TOKEN);
+    const motherDataDir = asString(env.DSH_FANG_MOTHER);
+    const fileDir = asString(raw.fileDir) || asString(dispatch.contractFileDir) || (motherDataDir ? path.join(motherDataDir, 'contract-outbox') : '');
+    const localService = (() => {
+        try {
+            return ctx && typeof ctx.get === 'function' ? ctx.get('fangContract') : null;
+        }
+        catch {
+            return null;
+        }
+    })();
+    const enabled = raw.enabled === true || Boolean(httpBaseUrl) || Boolean(fileDir) || Boolean(localService);
+    if (!enabled)
+        return null;
+    if (raw.enabled === false)
+        return null;
+    return createContractClient({
+        ctx,
+        config: {
+            httpBaseUrl,
+            httpToken,
+            httpHeaders: raw.httpHeaders && typeof raw.httpHeaders === 'object' ? raw.httpHeaders : undefined,
+            fileDir,
+            timeoutMs: clampInt(raw.timeoutMs, RELAY_DEFAULTS.timeoutMs, 1_000, 300_000),
+            fileTimeoutMs: clampInt(raw.fileTimeoutMs, 30_000, 1_000, 300_000),
+            order: Array.isArray(raw.order) ? raw.order : undefined,
+        },
+        fetchImpl,
+    });
+}
+/**
+ * 一次性装配：配置 → 客户端 → 出口。返回的 `client` 为 null 表示没有任何
+ * 可用传输（此时出口状态是 `relay-client-absent`，不是“探测中”）。
+ */
+export function createFangRelayFromContext(ctx, config = {}, options = {}) {
+    const client = createRelayClient(ctx, config, options);
+    const relay = createFangRelay({
+        client,
+        now: options.now,
+        maxBatch: config.relay?.maxBatch,
+        maxQueue: config.relay?.maxQueue,
+        probeTtlMs: config.relay?.probeTtlMs,
+        timeoutMs: config.relay?.timeoutMs,
+        logger: options.logger,
+    });
+    return { client, relay };
+}

package/dist-host/cost/gate.js

@@ -0,0 +1,189 @@
+// 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 · gate（发布门禁，设计 §10.2）。
+ *
+ * **3.3.0 不通过不发布**。六道门：
+ *
+ * | # | 门禁 | 判定 |
+ * |---|---|---|
+ * | G1 | `npm run check` 0 error | 退出码 |
+ * | G2 | `npm run build` 0 error | 退出码 |
+ * | G3 | `npm test` 全绿（含新增模块测试） | 退出码 + 用例数 |
+ * | G4 | 新增测试至少覆盖：I1–I8 各一条、守卫命中/未命中、schema 漂移、证书回放、归因不重复计 | 覆盖清单逐项核验 |
+ * | G5 | 真实 fork 实机：≥10 任务的对照组 vs enforce 组，tokens/task 与成功率同表 | 样本量 + 同表 + 成功率不退化 |
+ * | G6 | 零残留：临时 profile / 工作区清理证据 | 路径扫描 |
+ * | G7 | 发布需用户明确授权 | 默认 **未授权**（设计不含发布动作） |
+ *
+ * 门禁的价值在于**敢说不**：任一门不满足即 `ok:false` 并列出 `blockers`，
+ * 不允许"部分通过"。
+ */
+/** 必须被测试覆盖的能力（G4），每项给出识别标记。 */
+export const REQUIRED_COVERAGE = Object.freeze([
+    { id: 'I1', label: '预算不足不启动模型调用', patterns: [/I1:.*budget/u] },
+    { id: 'I2', label: 'CCS 只经原生派发器 / 无派发器拒绝', patterns: [/I2:.*native dispatcher/u, /I2:.*non-native/u] },
+    { id: 'I3', label: '破坏性工具默认不入池', patterns: [/I3:.*destructive/u] },
+    { id: 'I4', label: 'schema 漂移整图作废', patterns: [/I4:.*schema drift/u] },
+    { id: 'I5', label: '守卫不匹配回落慢模型', patterns: [/I5:.*guard miss/u] },
+    { id: 'I6', label: '模块异常 degraded 且任务继续', patterns: [/I6:.*throwing module/u] },
+    { id: 'I7', label: '压缩回执可回读原文（spill）', patterns: [/I7:.*read back/u] },
+    { id: 'I8', label: '取消信号阻断替换', patterns: [/I8:.*aborted signal/u] },
+    { id: 'guard-hit', label: '守卫命中', patterns: [/all five gates must pass/u] },
+    { id: 'guard-miss', label: '守卫未命中', patterns: [/each gate has its own miss reason/u] },
+    { id: 'schema-drift', label: 'schema 漂移（B2 层）', patterns: [/schema drift archives the whole graph/u, /schemaHash/u] },
+    { id: 'cert-replay', label: '证书回放', patterns: [/100% replayable/u] },
+    { id: 'no-double-count', label: '归因不重复计', patterns: [/doubleCountGuard/u, /mutually exclusive/u] },
+]);
+/** G5：对照组 vs enforce 组的最小样本量。 */
+export const MIN_FORK_TASKS = 10;
+/** G5：成功率允许的最大下降（与 §10.1 的 2pp 门禁一致）。 */
+export const MAX_SUCCESS_DROP_PP = 0.02;
+const num = (value) => {
+    const n = Number(value);
+    return Number.isFinite(n) ? n : 0;
+};
+/**
+ * G4：扫描测试源码，逐项确认覆盖（找不到标记即报缺）。
+ * @param {Record<string, string>} sources 文件名 → 源码
+ */
+export function checkCoverage(sources = {}) {
+    const haystack = Object.values(sources).join('\n');
+    const missing = [];
+    const covered = [];
+    for (const item of REQUIRED_COVERAGE) {
+        const found = item.patterns.some((pattern) => pattern.test(haystack));
+        if (found)
+            covered.push(item.id);
+        else
+            missing.push({ id: item.id, label: item.label });
+    }
+    return { ok: missing.length === 0, covered, missing };
+}
+/**
+ * G5：评估真实 fork 实机对照实验。
+ * @param {{control?: {tasks: Array<{taskId: string, tokens: number, success: boolean}>}, enforce?: {tasks: Array<{taskId: string, tokens: number, success: boolean}>}}} input
+ */
+export function evaluateForkExperiment(input = {}) {
+    const control = Array.isArray(input?.control?.tasks) ? input.control.tasks : [];
+    const enforce = Array.isArray(input?.enforce?.tasks) ? input.enforce.tasks : [];
+    const problems = [];
+    // 证据来源必须真实：dry-run（合成语料 + 脚本化模型）不能冒充 G5。
+    const harness = input?.harness === undefined ? 'real-fork' : String(input.harness);
+    if (harness === 'local-dry-run')
+        problems.push('harness-not-real');
+    if (control.length < MIN_FORK_TASKS)
+        problems.push(`control-tasks<${MIN_FORK_TASKS}`);
+    if (enforce.length < MIN_FORK_TASKS)
+        problems.push(`enforce-tasks<${MIN_FORK_TASKS}`);
+    const avg = (rows) => (rows.length > 0 ? rows.reduce((sum, row) => sum + num(row?.tokens), 0) / rows.length : null);
+    const rate = (rows) => (rows.length > 0 ? rows.filter((row) => row?.success === true).length / rows.length : null);
+    const controlTokensPerTask = avg(control);
+    const enforceTokensPerTask = avg(enforce);
+    const controlSuccess = rate(control);
+    const enforceSuccess = rate(enforce);
+    const tokenDelta = controlTokensPerTask !== null && enforceTokensPerTask !== null
+        ? Math.round((enforceTokensPerTask - controlTokensPerTask) * 100) / 100
+        : null;
+    const successDelta = controlSuccess !== null && enforceSuccess !== null
+        ? Math.round((enforceSuccess - controlSuccess) * 10000) / 10000
+        : null;
+    if (successDelta !== null && successDelta <= -MAX_SUCCESS_DROP_PP)
+        problems.push('success-regression>=2pp');
+    // 同表：两组必须都在同一份报告里给出 tokens/task 与成功率
+    const sameTable = controlTokensPerTask !== null && enforceTokensPerTask !== null && controlSuccess !== null && enforceSuccess !== null;
+    if (!sameTable)
+        problems.push('groups-not-in-same-table');
+    return {
+        ok: problems.length === 0,
+        problems,
+        samples: { control: control.length, enforce: enforce.length },
+        table: [
+            { group: 'control', samples: control.length, tokensPerTask: controlTokensPerTask, successRate: controlSuccess },
+            { group: 'enforce', samples: enforce.length, tokensPerTask: enforceTokensPerTask, successRate: enforceSuccess },
+        ],
+        delta: { tokensPerTask: tokenDelta, successRate: successDelta },
+        /** token 变好且成功率不退化，才算"通过且有效"。 */
+        improvement: tokenDelta !== null && tokenDelta < 0 && (successDelta === null || successDelta > -MAX_SUCCESS_DROP_PP),
+    };
+}
+/**
+ * G6：零残留——给出的路径里不允许还有临时 profile / 工作区。
+ * @param {Array<{path: string, exists: boolean, kind?: string}>} checks
+ */
+export function checkResidue(checks = []) {
+    const leftovers = checks.filter((entry) => entry?.exists === true).map((entry) => ({ path: String(entry.path), kind: String(entry.kind ?? 'unknown') }));
+    return {
+        ok: leftovers.length === 0,
+        checked: checks.length,
+        leftovers,
+        /** 没有检查项等于没有证据，不算通过。 */
+        evidence: checks.length > 0 ? '<results>' : null,
+    };
+}
+/**
+ * 汇总门禁。
+ * @param {{
+ *   commands?: Array<{id: string, exitCode: number, note?: string}>,
+ *   coverage?: ReturnType<typeof checkCoverage>,
+ *   forkExperiment?: ReturnType<typeof evaluateForkExperiment>,
+ *   residue?: ReturnType<typeof checkResidue>,
+ *   releaseAuthorized?: boolean,
+ * }} input
+ */
+export function evaluateGate(input = {}) {
+    const items = [];
+    const blockers = [];
+    for (const command of Array.isArray(input.commands) ? input.commands : []) {
+        const id = String(command?.id ?? 'unknown');
+        const passed = num(command?.exitCode) === 0;
+        items.push({ gate: id, ok: passed, detail: `exit=${num(command?.exitCode)}${command?.note ? ` ${command.note}` : ''}` });
+        if (!passed)
+            blockers.push(`${id}:exit-code`);
+    }
+    const coverage = input.coverage;
+    if (!coverage) {
+        blockers.push('G4:coverage-not-checked');
+        items.push({ gate: 'G4', ok: false, detail: '未执行覆盖核验' });
+    }
+    else {
+        items.push({ gate: 'G4', ok: coverage.ok === true, detail: coverage.ok ? `${coverage.covered.length} 项全中` : `缺 ${coverage.missing.map((item) => item.id).join(',')}` });
+        if (coverage.ok !== true)
+            blockers.push(`G4:missing:${coverage.missing.map((item) => item.id).join(',')}`);
+    }
+    const fork = input.forkExperiment;
+    if (!fork) {
+        blockers.push('G5:fork-experiment-missing');
+        items.push({ gate: 'G5', ok: false, detail: '尚无真实 fork 对照数据（≥10 任务/组）' });
+    }
+    else {
+        items.push({ gate: 'G5', ok: fork.ok === true, detail: fork.ok ? `control ${fork.table[0].tokensPerTask} → enforce ${fork.table[1].tokensPerTask} tokens/task` : fork.problems.join(',') });
+        if (fork.ok !== true)
+            blockers.push(`G5:${fork.problems.join(',')}`);
+    }
+    const residue = input.residue;
+    if (!residue) {
+        blockers.push('G6:residue-not-checked');
+        items.push({ gate: 'G6', ok: false, detail: '未提供清理证据' });
+    }
+    else {
+        items.push({ gate: 'G6', ok: residue.ok === true, detail: residue.ok ? `${residue.checked} 个路径均无残留` : `残留: ${residue.leftovers.map((item) => item.path).join(',')}` });
+        if (residue.ok !== true)
+            blockers.push('G6:residue');
+    }
+    // G7：默认未授权。设计本身不含发布动作；授权是人工显式行为。
+    const authorized = input.releaseAuthorized === true;
+    items.push({ gate: 'G7', ok: authorized, detail: authorized ? '用户已明确授权' : '未授权（发布需用户明确授权）' });
+    if (!authorized)
+        blockers.push('G7:release-not-authorized');
+    const hardGates = ['G1', 'G2', 'G3', 'G4', 'G5', 'G6'];
+    const hardOk = items.filter((item) => hardGates.includes(item.gate)).every((item) => item.ok);
+    return {
+        ok: hardOk && authorized,
+        /** 不发布 ≠ 代码不可用：G1–G4 + G6 全绿时，代码质量门禁是过了的。 */
+        bootstrapOk: hardOk,
+        blockers,
+        items,
+        releaseAuthorized: authorized,
+    };
+}