@twinsearth/dsh-master 3.2.10 → 3.3.0

package/dist-host/cost/bus.js

@@ -0,0 +1,95 @@
+// 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 系统层 · bus（事件总线与回流出口，设计 §5.6）。
+ *
+ * 对外只暴露三种内部事件（冒号命名，与 Router 事件通道一致）：
+ *   * `cost:event`         —— 账本/归因/预算等一般成本事件（payload.kind 区分）；
+ *   * `cost:degraded`      —— 模块降级（不伪装成节省）；
+ *   * `cost:substitution`  —— 替换证书（与审计链同源）。
+ *
+ * 可选对外出口（3.3.0 不阻塞主线）：
+ *   * `web`  —— Worker→Router 既有事件通道（Router 落库后供状态页/分身信息栏读取）；
+ *   * `fang` —— 瓮城「产物回流」；未就绪时状态里必须显式 `available: false` + 原因，
+ *               **不得**静默丢弃或假装成功。
+ */
+export const COST_EVENT_TYPES = Object.freeze(['cost:event', 'cost:degraded', 'cost:substitution']);
+/**
+ * @param {{maxEvents?: number, now?: () => number, relays?: Array<{name:string, publish?:Function, available?:boolean, reason?:string}>}} [options]
+ */
+export function createCostBus(options = {}) {
+    const now = typeof options.now === 'function' ? options.now : () => Date.now();
+    const maxEvents = Math.max(1, Number(options.maxEvents ?? 200) || 200);
+    const events = [];
+    const subscribers = new Set();
+    /** 外部出口（web / fang）；available=false 的出口只记录状态，不投递。 */
+    const relays = (Array.isArray(options.relays) ? options.relays : [])
+        .filter((relay) => relay && typeof relay === 'object' && relay.name)
+        .map((relay) => ({
+        name: String(relay.name),
+        publish: typeof relay.publish === 'function' ? relay.publish : null,
+        available: relay.available === true && typeof relay.publish === 'function',
+        reason: String(relay.reason ?? ''),
+        delivered: 0,
+        failed: 0,
+    }));
+    let dropped = 0;
+    function publish(type, payload = {}) {
+        const event = Object.freeze({ type: String(type ?? 'unknown'), at: now(), payload: Object.freeze({ ...payload }) });
+        events.push(event);
+        if (events.length > maxEvents) {
+            events.shift();
+            dropped += 1;
+        }
+        for (const listener of [...subscribers]) {
+            try {
+                listener(event);
+            }
+            catch { /* 订阅者异常不影响成本链路 */ }
+        }
+        for (const relay of relays) {
+            if (!relay.available || !relay.publish)
+                continue;
+            try {
+                relay.publish(event);
+                relay.delivered += 1;
+            }
+            catch {
+                relay.failed += 1;
+                // 出口失败不得影响主流程，但必须留痕（failed 计数），不静默吞掉。
+            }
+        }
+        return event;
+    }
+    function subscribe(listener) {
+        if (typeof listener !== 'function')
+            return () => { };
+        subscribers.add(listener);
+        return () => { subscribers.delete(listener); };
+    }
+    function snapshot(limit = 50) {
+        const n = Math.max(1, Number(limit) || 50);
+        return Object.freeze({
+            ok: true,
+            count: events.length,
+            dropped,
+            subscribers: subscribers.size,
+            events: events.slice(-n),
+            /** §5.6 出口状态：不可用必须显式说明原因，不假装成功。 */
+            relays: relays.map((relay) => Object.freeze({
+                name: relay.name,
+                available: relay.available,
+                reason: relay.reason,
+                delivered: relay.delivered,
+                failed: relay.failed,
+            })),
+        });
+    }
+    function reset() {
+        events.length = 0;
+        dropped = 0;
+        return { ok: true };
+    }
+    return Object.freeze({ publish, subscribe, snapshot, reset });
+}

package/dist-host/cost/cert-chain.js

@@ -0,0 +1,100 @@
+// 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 · M4 交付物：**证书链核对报告**（真实替换 → 证书 → 审计链 → 账本）。
+ *
+ * 一张证书要说清楚三件事，缺一件就不算"可回放"：
+ *
+ *   1. **派发证据**：`viaNativeDispatcher === true` 且 `dispatched === true`（真的走了原生派发器）；
+ *   2. **审计落链**：能在审计链里按 `taskId + step + edgeId` 找到对应记录，且 `verify()` 不断链；
+ *   3. **账本对账**：同一 `taskId + step` 的替换账本事件金额与证书金额一致。
+ *
+ * 任何一项不成立 ⇒ 该证书 `ok:false` 并给出 `issue`，报表整体 `ok:false`。
+ * 失败替换（`dispatched:false`）单列：它们是**自动回退的证据**，不是节省。
+ */
+const num = (value) => {
+    const n = Number(value);
+    return Number.isFinite(n) && n >= 0 ? n : 0;
+};
+/**
+ * @param {{
+ *   certificates?: Array<object>,
+ *   entries?: Array<object>,
+ *   audit?: {ok?: boolean, count?: number, records?: Array<object>},
+ * }} input
+ */
+export function buildCertChainReport(input = {}) {
+    const certificates = Array.isArray(input.certificates) ? input.certificates : [];
+    const entries = Array.isArray(input.entries) ? input.entries : [];
+    const auditOk = input?.audit?.ok !== false;
+    const auditRecords = Array.isArray(input?.audit?.records) ? input.audit.records : [];
+    // 替换账本事件：按 taskId+step 索引（同一步可能有多条，取合计）
+    const ledgerByKey = new Map();
+    for (const entry of entries) {
+        if (entry?.meta?.kind !== 'substitution')
+            continue;
+        const key = `${String(entry.taskId)}|${Number(entry.step)}`;
+        ledgerByKey.set(key, (ledgerByKey.get(key) ?? 0) + num(entry.savedTokens));
+    }
+    const rows = certificates.map((cert) => {
+        const taskId = String(cert?.taskId ?? '');
+        const step = Number(cert?.step ?? -1);
+        const key = `${taskId}|${step}`;
+        // 审计链只接受已派发的证书；因此 dispatched 缺省视为 true，显式 false 才是失败替换。
+        const dispatched = cert?.dispatched !== false;
+        const native = cert?.viaNativeDispatcher === true;
+        const ledgerSaved = ledgerByKey.get(key) ?? null;
+        const certSaved = num(cert?.savedTokens);
+        const audited = auditRecords.some((record) => String(record?.payload?.edgeId ?? '') === String(cert?.edgeId ?? '')
+            && String(record?.payload?.taskId ?? '') === taskId
+            && Number(record?.payload?.step ?? -1) === step);
+        const issues = [];
+        if (!native)
+            issues.push('not-native-dispatcher');
+        if (dispatched && ledgerSaved === null)
+            issues.push('missing-ledger-entry');
+        if (dispatched && ledgerSaved !== null && ledgerSaved !== certSaved)
+            issues.push('ledger-mismatch');
+        if (dispatched && !audited && auditRecords.length > 0)
+            issues.push('missing-audit-record');
+        if (dispatched && !auditOk)
+            issues.push('audit-chain-broken');
+        return Object.freeze({
+            edgeId: String(cert?.edgeId ?? ''),
+            toolName: String(cert?.toolName ?? ''),
+            replacedCallbackId: String(cert?.replacedCallbackId ?? ''),
+            taskId,
+            step,
+            dispatched,
+            viaNativeDispatcher: native,
+            certificateSavedTokens: certSaved,
+            ledgerSavedTokens: ledgerSaved,
+            audited,
+            issue: issues.length > 0 ? issues.join(',') : null,
+            /** 失败替换是「自动回退」的证据，不是缺陷也不是节省。 */
+            fallback: !dispatched,
+            ok: issues.length === 0,
+        });
+    });
+    const dispatchedRows = rows.filter((row) => row.dispatched);
+    const fallbackRows = rows.filter((row) => row.fallback);
+    return Object.freeze({
+        ok: rows.every((row) => row.ok),
+        certificates: rows.length,
+        dispatched: dispatchedRows.length,
+        fallbacks: fallbackRows.length,
+        /** 证书声明的节省总额（只算派发成功的）。 */
+        savedTokens: dispatchedRows.reduce((sum, row) => sum + num(row.certificateSavedTokens), 0),
+        audit: Object.freeze({ ok: auditOk, records: Number(input?.audit?.count ?? auditRecords.length) }),
+        /** 自动回退证据：每条失败替换的原因。 */
+        fallbackReasons: Object.freeze(fallbackRows.map((row) => Object.freeze({ edgeId: row.edgeId, reason: String(row.issue ?? 'not-dispatched') }))),
+        rows: Object.freeze(rows),
+        discipline: Object.freeze({
+            /** 失败替换不计节省、不算替换成功。 */
+            fallbacksNeverCountAsSavings: fallbackRows.every((row) => num(row.certificateSavedTokens) === 0 || row.dispatched === false),
+            everyDispatchHasLedgerEntry: dispatchedRows.every((row) => row.ledgerSavedTokens !== null),
+            nativeDispatcherOnly: rows.every((row) => row.viaNativeDispatcher === true),
+        }),
+    });
+}

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/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,
+    };
+}

package/dist-host/cost/host-surface.js

@@ -0,0 +1,80 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// Copyright (c) 2026 dsh-Master contributors — see LICENSE-CORE.
+// @ts-nocheck — host JS→TS 迁移阶段：运行时行为优先，类型注解逐步补齐（worker/ 仍严格检查）。
+const SOURCES = new Set(['dsh-ops', 'other']);
+function finiteNonNegative(value) {
+    const n = Number(value);
+    return Number.isFinite(n) && n >= 0 ? Math.floor(n) : null;
+}
+/**
+ * @param {{
+ *   ledger: {append: Function},
+ *   enabled?: boolean,
+ *   source?: string,
+ *   bus?: ReturnType<typeof createCostBus>,
+ *   now?: () => number,
+ * }} options
+ */
+export function createHostSurfaceAdapter(options = {}) {
+    const ledger = options.ledger;
+    if (!ledger || typeof ledger.append !== 'function')
+        throw new Error('host-surface adapter requires a ledger');
+    const enabled = options.enabled === true;
+    const source = SOURCES.has(String(options.source ?? 'dsh-ops')) ? String(options.source ?? 'dsh-ops') : 'other';
+    const bus = options.bus && typeof options.bus.publish === 'function' ? options.bus : null;
+    const now = typeof options.now === 'function' ? options.now : () => Date.now();
+    let recorded = 0;
+    let tokensClaimed = 0;
+    /**
+     * 登记一次宿主面外部收益（只展示，不计入本项目节省）。
+     * @param {{taskId?: string, savedTokens: number, baselineTokens?: number, meta?: object}} input
+     */
+    function record(input = {}) {
+        if (!enabled)
+            return { ok: false, code: 'host-adapter-disabled', message: 'host surface adapter is opt-in; enable it in config' };
+        const saved = finiteNonNegative(input.savedTokens);
+        if (saved === null)
+            return { ok: false, code: 'saved-tokens-invalid', message: 'savedTokens must be a non-negative number' };
+        const appended = ledger.append({
+            account: 'execution',
+            surface: 'host',
+            external: true,
+            module: 'a1-compact',
+            source: 'tool',
+            phase: 'tool',
+            taskId: input.taskId,
+            totalTokens: 0,
+            savedTokens: saved,
+            meta: {
+                ...(input.meta && typeof input.meta === 'object' ? input.meta : {}),
+                adapter: source,
+                external: true,
+                note: 'third-party host-surface saving; shown for comparison only',
+            },
+        });
+        if (!appended.ok)
+            return { ok: false, code: appended.code, message: appended.message };
+        recorded += 1;
+        tokensClaimed += saved;
+        try {
+            bus?.publish?.('cost.host-surface', { adapter: source, savedTokens: saved, taskId: input.taskId ?? null });
+        }
+        catch { /* ignore */ }
+        return { ok: true, adapter: source, external: true, savedTokens: saved, ledger: { id: appended.entry.id }, at: now() };
+    }
+    function status() {
+        return Object.freeze({
+            ok: true,
+            enabled,
+            adapter: source,
+            /** 明确声明：本适配器不产生本项目收益。 */
+            contributesToOwnSavings: false,
+            recorded,
+            savedTokens: tokensClaimed,
+            note: enabled
+                ? '外部宿主面收益只做对照展示，不计入 executionSaved / netSaved'
+                : '未启用：本设计不依赖任何第三方宿主插件',
+        });
+    }
+    return Object.freeze({ record, status });
+}