@twinsearth/dsh-master 3.2.10 → 3.3.1

package/dist-host/cost/toolface.js

@@ -0,0 +1,147 @@
+// 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 · M2 交付物：**工具面 token 下降 + 归因**。
+ *
+ * 两件事必须分开算，因为它们属于两本不同的账：
+ *
+ *   * **A1 紧凑输出**：回执变短 ⇒ 每次交互更便宜 ⇒ **execution 节省**。
+ *     默认 `shadow` 时只能报「本可节省」，不许算成真节省。
+ *   * **A2 渐进纰漏**：常驻工具面收敛 ⇒ 每轮 schema 更少；但 `load_tools` 的装载
+ *     是**作者/选择成本** ⇒ **governance 账**（与 §5.1 一致），永不混进节省。
+ *
+ * 关闭 A2 时必须 `reductionRatio === 0`（fail-open 回全量工具面），这是可测的。
+ */
+const num = (value) => {
+    const n = Number(value);
+    return Number.isFinite(n) && n >= 0 ? n : 0;
+};
+const tokensOf = (text) => (String(text ?? '').length > 0 ? Math.ceil(String(text).length / 4) : 0);
+/**
+ * 计算工具面：全量（基线）vs 可见（常驻 + 已加载）。
+ * @param {{
+ *   schemas: Array<{name: string, description?: string, parameters?: unknown}>,
+ *   enabled?: boolean,
+ *   resident?: string[],
+ *   loaded?: string[],
+ * }} input
+ */
+export function planToolFace(input = {}) {
+    const schemas = Array.isArray(input.schemas) ? input.schemas : [];
+    const enabled = input.enabled === true;
+    const resident = new Set(Array.isArray(input.resident) ? input.resident.map(String) : []);
+    const loaded = new Set(Array.isArray(input.loaded) ? input.loaded.map(String) : []);
+    const tokenOfSchema = (schema) => tokensOf(JSON.stringify({ name: schema?.name, description: schema?.description, parameters: schema?.parameters }));
+    const baselineTokens = schemas.reduce((sum, schema) => sum + tokenOfSchema(schema), 0);
+    const visible = enabled ? schemas.filter((schema) => resident.has(String(schema?.name)) || loaded.has(String(schema?.name))) : schemas;
+    const residentTokens = visible.reduce((sum, schema) => sum + tokenOfSchema(schema), 0);
+    const savedTokens = Math.max(0, baselineTokens - residentTokens);
+    return Object.freeze({
+        enabled,
+        baseline: Object.freeze({ count: schemas.length, tokens: baselineTokens }),
+        resident: Object.freeze({ count: visible.length, tokens: residentTokens, names: visible.map((schema) => String(schema?.name)) }),
+        savedTokens,
+        reductionRatio: baselineTokens > 0 ? savedTokens / baselineTokens : 0,
+        /** 关闭时必须是 0（fail-open 回全量），调用方可直接断言。 */
+        perTurn: Object.freeze({ tokensBefore: baselineTokens, tokensAfter: residentTokens }),
+    });
+}
+/**
+ * M2 报表：工具面下降（A2） + 回执压缩（A1） + 归因分列。
+ *
+ * @param {{
+ *   schemas?: object[],
+ *   disclosure?: {enabled?: boolean, resident?: string[], loaded?: string[]},
+ *   compactions?: Array<{toolName?: string, applied?: boolean, evaluated?: boolean, estimated?: boolean, savedTokens?: number, savedChars?: number}>,
+ *   loads?: Array<{toolName?: string, tokens?: number}>,
+ *   mode?: 'off' | 'shadow' | 'enforce',
+ * }} input
+ */
+export function buildToolFaceReport(input = {}) {
+    const disclosure = input.disclosure ?? {};
+    const face = planToolFace({ schemas: input.schemas, enabled: disclosure.enabled === true, resident: disclosure.resident, loaded: disclosure.loaded });
+    const mode = input.mode === 'off' || input.mode === 'enforce' ? input.mode : 'shadow';
+    const byTool = {};
+    let evaluated = 0;
+    let applied = 0;
+    let appliedSaved = 0;
+    let wouldSave = 0;
+    let estimatedSaved = 0;
+    for (const event of Array.isArray(input.compactions) ? input.compactions : []) {
+        if (event?.evaluated === false)
+            continue;
+        evaluated += 1;
+        const saved = num(event?.savedTokens ?? (num(event?.savedChars) / 4));
+        if (event?.applied === true) {
+            applied += 1;
+            appliedSaved += saved;
+            if (event?.estimated === true)
+                estimatedSaved += saved;
+        }
+        else {
+            wouldSave += saved;
+        }
+        const toolName = String(event?.toolName ?? 'unknown');
+        if (!byTool[toolName])
+            byTool[toolName] = { evaluated: 0, applied: 0, savedTokens: 0 };
+        byTool[toolName].evaluated += 1;
+        if (event?.applied === true) {
+            byTool[toolName].applied += 1;
+            byTool[toolName].savedTokens += saved;
+        }
+    }
+    // A2 的装载成本：进 governance，不进节省
+    const loadEvents = Array.isArray(input.loads) ? input.loads.length : 0;
+    const governanceTokens = (Array.isArray(input.loads) ? input.loads : []).reduce((sum, event) => sum + num(event?.tokens), 0);
+    // A1 的节省口径：只有 enforce 且真的替换了才算执行节省
+    const a1ExecutionSaved = mode === 'enforce' ? appliedSaved : 0;
+    const a1WouldSaveTokens = mode === 'enforce' ? 0 : wouldSave + appliedSaved;
+    const executionSaved = a1ExecutionSaved;
+    return Object.freeze({
+        ok: true,
+        mode,
+        toolFace: face,
+        a1: Object.freeze({
+            module: 'a1-compact',
+            evaluated,
+            applied,
+            /** enforce 且替换成功时才算的节省。 */
+            executionSavedTokens: a1ExecutionSaved,
+            /** shadow 下「本可节省」——不是节省，报表必须显式标出。 */
+            wouldSaveTokens: a1WouldSaveTokens,
+            estimatedSavedTokens: estimatedSaved,
+            byTool: Object.freeze(byTool),
+        }),
+        a2: Object.freeze({
+            module: 'a2-disclosure',
+            enabled: face.enabled,
+            loadEvents,
+            /** 装载成本属于作者/选择成本 ⇒ governance（永不并入节省）。 */
+            governanceTokens,
+            perTurnSavedTokens: face.savedTokens,
+        }),
+        attribution: Object.freeze({
+            /** 工具面下降算 A2 的贡献，但**只有在 enabled 时才非 0**。 */
+            'a2-disclosure': face.savedTokens,
+            'a1-compact': a1ExecutionSaved,
+            governance: governanceTokens,
+        }),
+        totals: Object.freeze({
+            executionSaved,
+            governanceTokens,
+            /** 净收益 = 执行节省（A1，enforce 才有） + 工具面下降（A2，per-turn） − 装载治理成本。 */
+            netBenefit: executionSaved + face.savedTokens - governanceTokens,
+            /** 两项分列（图省事合并会导致 §8 的重复计风险）。 */
+            byKind: Object.freeze({
+                toolFaceSavedTokens: face.savedTokens,
+                receiptSavedTokens: a1ExecutionSaved,
+            }),
+        }),
+        discipline: Object.freeze({
+            shadowNeverCountedAsSavings: mode !== 'enforce',
+            loadCostIsGovernance: true,
+            disabledDisclosureReducesNothing: face.enabled !== true || face.savedTokens >= 0,
+        }),
+    });
+}

package/dist-host/cost/types.js

@@ -0,0 +1,31 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// Copyright (c) 2026 dsh-Master contributors — see LICENSE-CORE.
+export const COST_PHASES = Object.freeze(['prompt', 'completion', 'tool', 'authoring', 'substitution']);
+export const COST_MODULES = Object.freeze([
+    'a1-compact',
+    'a2-disclosure',
+    'a3-batch',
+    'b1-edg',
+    'b2-gdr',
+    'b3-ccs',
+    'b4-rsi',
+    'unattributed',
+]);
+export const COST_SOURCES = Object.freeze([
+    'model',
+    'tool',
+    'substitution',
+    'retry',
+    'authoring',
+    'offline',
+]);
+export const POLICY_MODES = Object.freeze(['observe', 'shadow', 'enforce']);
+/** 两个作用面（设计 §3.3）：不可合并统计。 */
+export const COST_SURFACES = Object.freeze(['worker', 'host']);
+/** 默认预算：与 Worker 现有 maxTokens 对齐（task=50k），fork=500k。 */
+export const DEFAULT_BUDGET_LIMITS = Object.freeze([
+    Object.freeze({ unit: 'task', limitTokens: 50_000, onExhaust: 'hard-stop' }),
+    Object.freeze({ unit: 'fork', limitTokens: 500_000, onExhaust: 'hard-stop' }),
+]);
+/** enforce 门禁（设计 §13）：准确率 ≥0.98、样本 ≥20、零破坏性命中、非空白名单。 */
+export const ENFORCE_GATE = Object.freeze({ minAccuracy: 0.98, minSamples: 20 });

package/dist-host/kernel.js

@@ -7,7 +7,7 @@
  * 与瓮城 dsh-Fang 的协作只走 DSH 服务键，不 import fang 代码。
  */
 import crypto from 'node:crypto';
-export const MASTER_VERSION = '3.2.10';
+export const MASTER_VERSION = '3.3.1';
 export const FANG_CONTRACT_MIN = '3.1.14';
 export const SERVICE = Object.freeze({
     master: 'dshMaster',
@@ -16,6 +16,32 @@ export const SERVICE = Object.freeze({
     cost: 'dshMasterCost',
     dual: 'dshMasterDual',
 });
+/**
+ * 3.3.0 §11：成本系统的**可选子服务**。
+ *
+ * 主服务 `SERVICE.cost` 的形态不变（向后兼容）；子服务由 cost-optimizer 在能力允许时
+ * 额外 `provide`，消费方必须用 `probeOptionalServices(ctx)` **探测**而不是假定存在 ——
+ * 缺了就是缺了，不能假装拿到空壳对象。
+ */
+export const OPTIONAL_SERVICE = Object.freeze({
+    costLedger: 'dshMasterCostLedger',
+    costBudget: 'dshMasterCostBudget',
+    costPolicy: 'dshMasterCostPolicy',
+    costAudit: 'dshMasterCostAudit',
+});
+/** 探测可选子服务是否就位（只读、无副作用）。 */
+export function probeOptionalServices(ctx) {
+    const present = {};
+    for (const [key, name] of Object.entries(OPTIONAL_SERVICE)) {
+        try {
+            present[key] = typeof ctx?.get === 'function' ? Boolean(ctx.get(name)) : false;
+        }
+        catch {
+            present[key] = false;
+        }
+    }
+    return present;
+}
 export const FANG_SERVICE = Object.freeze({
     orchestrator: 'fang',
     forker: 'fangForker',
@@ -33,7 +59,7 @@ export const ROW = Object.freeze({
 });
 export const ROLE = Object.freeze({ mother: 'mother', essence: 'essence', fork: 'fork' });
 /**
- * 角色矩阵（3.2.10）：
+ * 角色矩阵：
  *   * Router 在 essence 与 mother 激活：只评估/建票/派发，不执行代码；fork 不注册。
  *   * Worker / Worker Agent Loop 在 fork 与 essence 激活：原身可直接执行工单，
  *     分身仍是默认执行体；mother 不执行。

package/dist-host/plugins/cost-optimizer.js

@@ -2,18 +2,25 @@
 // Copyright (c) 2026 dsh-Master contributors — see LICENSE-CORE.
 // @ts-nocheck — host JS→TS 迁移阶段：运行时行为优先，类型注解逐步补齐（worker/ 仍严格检查）。
 /**
- * 子插件 2：成本优化（HarnessMM 观察层）—— 为分身装“燃油表”。
+ * 子插件 2：成本优化（3.3.0 M1：系统层接入，observe-only）。
  *
- * 3.2.0 先交付可观测/可估算的骨架，不做推理拦截：
- *   * `observe` 模式只统计/估算，不改写任何模型调用；
- *   * HarnessMM 的 EGD/GDR/CCS 真实接入在 3.3.0 里程碑（见 docs/ROADMAP.md）；
- *   * 角色：只允许 fork（分身生产盘），母体/元主不加载。
+ * 本行在 3.2.x 的 observe 骨架上扩展，**保持** `estimate/record/summary/reset/status`
+ * 兼容面，内部改为委托 3.3.0 系统层（`src/cost`）：
+ *   * ledger：两本账（execution / governance）+ 归因；
+ *   * budget：task/fork 预算闸（fail-closed，附 remaining）；
+ *   * policy：observe → shadow → enforce 三档与 enforce 门禁；
+ *   * audit：治理事件哈希链。
+ *
+ * M1 只记账：不拦截模型调用、不改写工具输出、不替换推理回调；
+ * 工具面（A1–A3）与决策复用（B1–B4）在 M2/M3/M4 接入。
+ * 角色：仍只允许 fork（分身生产盘）。
  */
-import { ROW, ROLE, SERVICE, detectRole, enabledOf, masterError, roleAllowed, safeGet, } from "../kernel.js";
+import { OPTIONAL_SERVICE, ROW, ROLE, SERVICE, detectRole, enabledOf, masterError, roleAllowed, safeGet, } from "../kernel.js";
+import { createCostSystem, createFangRelayFromContext, DEFAULT_BUDGET_LIMITS } from "../cost/index.js";
 export const name = 'dsh-master-cost-optimizer';
 export const inject = ['dshMaster'];
 export const ROW_ID = ROW.cost;
-/** HarnessMM 官方基准（3.2.0 文档引用；3.3.0 接入后应被实测值覆盖）。 */
+/** HarnessMM 官方基准（3.2.0 文档引用；3.3.0 的实测值应覆盖它，而不是替代对标）。 */
 export const HARNESSMM_BENCHMARK = Object.freeze({
     baselineTokens: 96280,
     optimizedTokens: 11620,
@@ -26,7 +33,15 @@ function finiteNonNegative(value) {
 }
 /**
  * @param {object} ctx
- * @param {{enabled?:boolean, mode?:string, targetSavingsRatio?:number}} [config]
+ * @param {{
+ *   enabled?: boolean, mode?: string, targetSavingsRatio?: number,
+ *   budget?: Array<{unit: string, limitTokens: number, onExhaust?: string}>,
+ *   enforceAllowlist?: string[],
+ *   relay?: {enabled?: boolean, httpBaseUrl?: string, httpToken?: string, fileDir?: string,
+ *            timeoutMs?: number, maxBatch?: number, maxQueue?: number, probeTtlMs?: number,
+ *            autoFlushMs?: number},
+ *   dispatch?: {motherUrl?: string, motherToken?: string, contractFileDir?: string},
+ * }} [config]
  */
 export function apply(ctx, config = {}) {
     if (!enabledOf(config))
@@ -44,11 +59,45 @@ export function apply(ctx, config = {}) {
         return { skipped: true, reason: 'master-core-unavailable' };
     }
     const targetSavingsRatio = finiteNonNegative(config.targetSavingsRatio);
-    const policy = Object.freeze({
-        mode: 'observe', // 3.2.0 只允许 observe；replay 在 3.3.0 打开
-        requestedMode: String(config.mode ?? 'observe'),
-        targetSavingsRatio: targetSavingsRatio !== null && targetSavingsRatio <= 1 ? targetSavingsRatio : 0.8,
+    /**
+     * §5.6 / M5：瓮城回流出口。
+     * 传输按「插件配置 relay → dispatch 配置 → 环境变量 DSH_FANG_*」装配；
+     * 一个都没有时不造客户端，出口状态显式 `relay-client-absent`。
+     */
+    const relayWiring = createFangRelayFromContext(ctx, config, { logger: ctx?.logger });
+    const system = createCostSystem({
+        mode: config.mode,
+        allowlist: config.enforceAllowlist ?? config.allowlist,
+        policyScopes: config.scopes,
+        budgetLimits: Array.isArray(config.budget) && config.budget.length > 0 ? config.budget : DEFAULT_BUDGET_LIMITS,
+        degradeModels: config.degradeModels,
+        // 宿主会话工具面适配器：默认关闭；开启也只做外部收益登记，不重写任何宿主插件。
+        hostSurface: config.hostSurface && typeof config.hostSurface === 'object'
+            ? { enabled: config.hostSurface.enabled === true, source: config.hostSurface.source }
+            : undefined,
+        relay: relayWiring.relay,
+        logger: ctx?.logger,
     });
+    const policy = system.policy.describe();
+    // M5：加载后异步探测一次回流对端（不阻塞 apply；没有客户端时立即返回 absent）。
+    try {
+        void Promise.resolve(system.relayProbe()).catch(() => { });
+    }
+    catch { /* 探测失败不影响主流程 */ }
+    /** M5：回流自动投递；没有客户端或 autoFlushMs=0 时不开定时器。 */
+    const autoFlushMs = Math.max(0, Number(config.relay?.autoFlushMs ?? 2_000) || 0);
+    let relayTimer = null;
+    if (relayWiring.client && autoFlushMs > 0) {
+        relayTimer = setInterval(() => { try {
+            void system.relayFlush().catch(() => { });
+        }
+        catch { /* ignore */ } }, autoFlushMs);
+        try {
+            relayTimer.unref?.();
+        }
+        catch { /* ignore */ }
+    }
+    // 3.2.x 兼容计数器（任务级实测汇总；系统层另有账本，两者口径不同、互不覆盖）。
     const metrics = {
         tasks: 0,
         baselineTokens: 0,
@@ -59,20 +108,23 @@ export function apply(ctx, config = {}) {
     };
     const service = {
         id: SERVICE.cost,
-        version: '3.2.5',
+        version: '3.3.1',
         role,
-        mode: policy.mode,
-        /** 基于 HarnessMM 基准 + 目标比例做派生前预估。 */
+        get mode() {
+            return system.policy.describe().mode;
+        },
+        /** 基于 HarnessMM 基准 + 目标比例做派生前预估（不承诺节省）。 */
         estimate({ baselineTokens } = {}) {
             const baseline = finiteNonNegative(baselineTokens);
             if (baseline === null)
                 return masterError('baseline-tokens-invalid', 'baselineTokens must be a non-negative number');
-            const projectedOptimized = Math.round(baseline * (1 - policy.targetSavingsRatio));
+            const current = system.policy.describe();
+            const projectedOptimized = Math.round(baseline * (1 - (targetSavingsRatio !== null && targetSavingsRatio <= 1 ? targetSavingsRatio : 0.8)));
             return {
                 ok: true,
-                mode: policy.mode,
+                mode: current.mode,
                 baselineTokens: baseline,
-                targetSavingsRatio: policy.targetSavingsRatio,
+                targetSavingsRatio: targetSavingsRatio !== null && targetSavingsRatio <= 1 ? targetSavingsRatio : 0.8,
                 projectedOptimizedTokens: projectedOptimized,
                 projectedSavingsTokens: baseline - projectedOptimized,
                 basis: {
@@ -83,8 +135,8 @@ export function apply(ctx, config = {}) {
                 },
             };
         },
-        /** 归档后记录实测；3.3.0 起由 HarnessMM 的 EGD/GDR/CCS 自动上报。 */
-        record({ taskId, baselineTokens, optimizedTokens, success } = {}) {
+        /** 归档后记录实测；3.3.0 起同时写系统层 execution 账本（baseline 给定时才算 saved）。 */
+        record({ taskId, baselineTokens, optimizedTokens, success, estimated = false, estimatedTokens = 0, forkId, sessionId } = {}) {
             const baseline = finiteNonNegative(baselineTokens);
             const optimized = finiteNonNegative(optimizedTokens);
             if (baseline === null)
@@ -102,13 +154,129 @@ export function apply(ctx, config = {}) {
                 if (success)
                     metrics.observedSuccess += 1;
             }
+            const meta = { success: success === undefined ? null : Boolean(success) };
+            // §5.1：估算与实测分列，绝不混算。两部分各自入账（baseline 按比例拆分，保证 sum 一致）。
+            const estimatedPart = Math.min(optimized, Math.max(0, Number(estimatedTokens) || 0));
+            const measuredPart = optimized - estimatedPart;
+            const entries = [];
+            if (measuredPart > 0 || estimatedPart === 0) {
+                const measuredBaseline = estimatedPart === 0 ? baseline : Math.round(baseline * (measuredPart / optimized));
+                const measured = system.recordUsage({
+                    account: 'execution',
+                    module: 'unattributed',
+                    source: 'model',
+                    phase: 'completion',
+                    taskId: taskId === undefined ? null : String(taskId),
+                    forkId,
+                    sessionId,
+                    totalTokens: measuredPart,
+                    baselineTokens: measuredBaseline,
+                    estimated: estimated === true && estimatedPart === 0,
+                    meta,
+                });
+                if (!measured.ok)
+                    return masterError(measured.code, 'ledger append failed');
+                entries.push(measured.entry.id);
+            }
+            if (estimatedPart > 0) {
+                const estimatedBaseline = Math.max(0, baseline - Math.round(baseline * (measuredPart / optimized)));
+                const measured = system.recordUsage({
+                    account: 'execution',
+                    module: 'unattributed',
+                    source: 'model',
+                    phase: 'completion',
+                    taskId: taskId === undefined ? null : String(taskId),
+                    forkId,
+                    sessionId,
+                    totalTokens: estimatedPart,
+                    baselineTokens: estimatedBaseline,
+                    estimated: true,
+                    meta: { ...meta, estimatedFallback: true },
+                });
+                if (!measured.ok)
+                    return masterError(measured.code, 'ledger append failed');
+                entries.push(measured.entry.id);
+            }
             return {
                 ok: true,
                 taskId: taskId === undefined ? null : String(taskId),
                 savedTokens: baseline - optimized,
+                ledger: { ids: entries, measuredTokens: measuredPart, estimatedTokens: estimatedPart },
                 summary: service.summary(),
             };
         },
+        /** 3.3.0 M2：A1 归因。enforce 记入 execution 账本；shadow 只累计「本可节省」。 */
+        recordAttribution({ taskId, module, savedTokens, mode = 'shadow', meta, forkId, sessionId } = {}) {
+            return system.attribute({ taskId, forkId, sessionId, module, savedTokens, mode, meta });
+        },
+        /** 3.3.0 §5.5：写替换证书 + 对应账本事件（共用 taskId+step）。 */
+        recordSubstitution(cert = {}) {
+            return system.substitute(cert);
+        },
+        /** 3.3.0 §5.5：按 taskId(+step) 回放「这一省是怎么来的」。 */
+        trace({ taskId, step } = {}) {
+            return system.trace({ taskId, step });
+        },
+        /** 3.3.0 §6 A2：工具装载成本记 **governance**（明确归类，绝不算节省）。 */
+        recordGovernance({ taskId, module = 'a2-disclosure', tokens = 0, kind = 'tools.load', meta, forkId, sessionId } = {}) {
+            const amount = finiteNonNegative(tokens);
+            if (amount === null)
+                return masterError('tokens-invalid', 'tokens must be a non-negative number');
+            const out = system.recordUsage({
+                account: 'governance',
+                module,
+                source: 'authoring',
+                phase: 'authoring',
+                taskId: taskId === undefined ? null : String(taskId),
+                forkId,
+                sessionId,
+                totalTokens: amount,
+                meta: { ...(meta && typeof meta === 'object' ? meta : {}), kind },
+            });
+            if (!out.ok)
+                return masterError(out.code, out.message ?? 'governance ledger append failed');
+            return { ok: true, account: 'governance', module, tokens: amount, ledger: { id: out.entry.id } };
+        },
+        /** M1 交付物：记账报表（估算/实测分列、两本账不合并、外部面单列）。 */
+        ledgerReport(input = {}) {
+            return system.ledgerReport(input);
+        },
+        /** 3.3.0 §10.1：七项验收指标（必须给全；缺项返回 complete:false + missing[]）。 */
+        metrics(input = {}) {
+            return system.metrics(input);
+        },
+        /** 3.3.0 §8：A（单价）/ B（跳过调用）分列报表 + 逐任务净额（净亏不隐藏）。 */
+        savingsReport(input = {}) {
+            return system.savingsReport(input);
+        },
+        /** 3.3.0 §5.4：总额结算，差额自动进 unattributed（不 blame 到任何模块）。 */
+        recordAttributionTotal({ taskId, totalSavedTokens, items = [], mode = 'shadow', forkId, sessionId } = {}) {
+            return system.attributeTotal({ taskId, totalSavedTokens, items, mode, forkId, sessionId });
+        },
+        /** 3.3.0 目标 2.1-5：模块异常降级留痕（审计 + 事件总线，不计入节省）。 */
+        recordDegraded({ taskId, module, phase = 'transform', message = '', count = 1 } = {}) {
+            return system.degraded({ taskId, module, phase, message, count });
+        },
+        /** 3.3.0：宿主会话工具面（外部插件）收益登记；只作对照，不计入本项目节省。 */
+        recordHostSurface({ taskId, savedTokens, meta } = {}) {
+            return system.hostSurface.record({ taskId, savedTokens, meta });
+        },
+        /** 3.3.0 §5.1：按维度查询账本（task/fork/session/module/account/phase/时间窗）。 */
+        query(filter = {}) {
+            return system.query(filter);
+        },
+        /** 3.3.0 §5.1：从 JSONL 回放。 */
+        replayLedger(direction = 'forward') {
+            return system.replay(direction);
+        },
+        /** 3.3.0：归因快照（按模块与任务聚合）。 */
+        attribution() {
+            return system.attribution.snapshot();
+        },
+        /** 3.3.0：订阅成本事件（宿主可转发给瓮城回流/信息栏）；返回取消订阅函数。 */
+        subscribeCost(listener) {
+            return system.subscribe(listener);
+        },
         summary() {
             const ratio = metrics.baselineTokens > 0 ? metrics.savedTokens / metrics.baselineTokens : 0;
             const successRate = metrics.observedTotal > 0 ? metrics.observedSuccess / metrics.observedTotal : null;
@@ -116,20 +284,119 @@ export function apply(ctx, config = {}) {
         },
         reset() {
             Object.assign(metrics, { tasks: 0, baselineTokens: 0, optimizedTokens: 0, savedTokens: 0, observedSuccess: 0, observedTotal: 0 });
+            system.ledger.reset();
+            system.budget.reset();
+            system.attribution.reset();
+            system.bus.reset();
             return { ok: true };
         },
+        /** 3.3.0 系统层：账本快照（两本账 + 归因）。 */
+        ledger() {
+            return system.ledger.snapshot();
+        },
+        /** M4：账本事件查询（证书链核对需要原始事件，不只要快照）。 */
+        ledgerEntries(filter = {}) {
+            return system.query(filter);
+        },
+        /** 3.3.0 系统层：预算授权（① 唯一检查点；超限 masterError + 结构化 remaining）。 */
+        authorizeBudget({ unit, key = 'default', tokens = 0, cost = 0 } = {}) {
+            return system.authorize({ unit, key, tokens, cost });
+        },
+        /** 3.3.0 系统层：当前账单 + 预算 + 审计 + 节省口径。 */
+        cost() {
+            return system.status();
+        },
+        /** 3.3.0 §5.3：解析某上下文的生效档（global → fork → task，取最严格）。 */
+        resolvePolicy(context = {}) {
+            return system.policy.resolve(context);
+        },
+        /** 3.3.0 §5.3：守卫命中上报（observe 只计数 / shadow 落证书不替换 / enforce 才替换）。 */
+        recordGuardHit(input = {}) {
+            return system.policy.recordHit(input);
+        },
+        /** 3.3.0 §5.3：设置 fork/task 级档位。 */
+        setScope(scope, id, next) {
+            return system.policy.setScope(scope, id, next);
+        },
+        /** 3.3.0 §5.3：三档命中统计与证书。 */
+        policyStats() {
+            return system.policy.stats();
+        },
+        /** 3.3.0 系统层：灰度模式（enforce 需过门禁，见 policy.requestMode）。 */
+        requestMode(next, evidence = {}) {
+            return system.policy.requestMode(next, evidence);
+        },
+        /** 回滚：任何时刻可降级（observe 一行回滚）。 */
+        setMode(next) {
+            return system.policy.setMode(next);
+        },
+        audit() {
+            return system.audit.snapshot();
+        },
+        /** M4：证书列表（供证书链核对报表用；只读）。 */
+        substitutions(filter = {}) {
+            return system.audit.substitutions(filter);
+        },
+        /** M5：瓮城回流出口状态（只读；不可用时必须带具体原因）。 */
+        relayStatus() {
+            return system.relayStatus();
+        },
+        /** M5：立即探测回流对端（hello 协商 + relay 状态），返回最新状态。 */
+        async relayProbe(input = {}) {
+            return await system.relayProbe(input);
+        },
+        /** M5：立即投递队列中的回流事件；回执里的数字才是送达证据。 */
+        async relayFlush() {
+            return await system.relayFlush();
+        },
         status() {
+            const current = system.policy.describe();
             return {
                 ok: true,
                 id: 'cost-optimizer',
-                version: '3.2.5',
+                version: '3.3.1',
                 role,
-                mode: policy.mode,
-                requestedMode: policy.requestedMode,
-                targetSavingsRatio: policy.targetSavingsRatio,
+                mode: current.mode,
+                requestedMode: current.requestedMode,
+                targetSavingsRatio: targetSavingsRatio !== null && targetSavingsRatio <= 1 ? targetSavingsRatio : 0.8,
                 benchmark: HARNESSMM_BENCHMARK,
                 summary: service.summary(),
-                note: '3.2.0 observe-only：不拦截/不改写模型调用；EGD/GDR/CCS 在 3.3.0 接入。',
+                policy: current,
+                policyStats: system.policy.stats(),
+                budget: system.budget.state(),
+                ledger: system.ledger.snapshot(),
+                audit: system.audit.verify(),
+                shadow: Object.fromEntries(system.attribution.snapshot().modules.map((row) => [row.module, {
+                        events: row.events,
+                        projectedTokens: row.projectedTokens,
+                        appliedTokens: row.enforceSavedTokens,
+                    }])),
+                attribution: system.attribution.snapshot(),
+                attributionSummary: system.status().attributionSummary,
+                bus: system.bus.snapshot(1),
+                /** §5.6 / M5：瓮城回流出口（可达 ⇒ available:true + 对端自报 peer；否则带原因）。 */
+                relay: system.relayStatus(),
+                /** §5.6：内部事件类型（冒号命名）与对外出口状态。 */
+                events: { types: ['cost:event', 'cost:degraded', 'cost:substitution'], relays: system.bus.snapshot(1).relays },
+                degraded: system.status().degraded,
+                surfaces: system.status().surfaces,
+                hostSurface: system.hostSurface.status(),
+                tokens: system.status().tokens,
+                savings: system.status().savings,
+                /** §8：两项分列的总节省（单价项 + 跳过调用项），避免只报合计。 */
+                savingsColumns: (() => {
+                    const report = system.savingsReport({ limit: 5000 });
+                    return {
+                        unitPriceSaved: report.columns.unitPrice.savedTokens,
+                        skippedCallSaved: report.columns.skippedCalls.savedTokens,
+                        skippedCalls: report.columns.skippedCalls.calls,
+                        governanceTotal: report.governance.totalTokens,
+                        netSaved: report.netSaved,
+                        netLossTasks: report.netLossTasks.map((task) => task.taskId),
+                        doubleCountGuard: report.doubleCountGuard,
+                    };
+                })(),
+                note: '3.3.1：系统层记账/预算/灰度/审计 + A1 工具输出紧凑化（默认 shadow）+ 瓮城回流出口（contract 1.1 真实投递）；工具面 A2–A3 与决策复用 B1–B4 已接入（shadow 默认）。',
             };
         },
     };
@@ -137,11 +404,46 @@ export function apply(ctx, config = {}) {
         ctx.effect(() => ctx.provide(SERVICE.cost, service));
     }
     catch { /* fake ctx */ }
+    try {
+        ctx.effect(() => () => {
+            if (relayTimer)
+                clearInterval(relayTimer);
+            relayTimer = null;
+        });
+    }
+    catch { /* fake ctx */ }
+    // 3.3.0 §11：可选子服务（主服务形态不变；消费方必须探测，不能假定存在）。
+    const optionalFaces = {
+        [OPTIONAL_SERVICE.costLedger]: Object.freeze({
+            query: (input) => system.query(input),
+            replay: (direction) => system.replay(direction),
+            snapshot: () => system.status().ledger,
+        }),
+        [OPTIONAL_SERVICE.costBudget]: Object.freeze({
+            authorize: (input) => system.authorize(input),
+            snapshot: () => system.status().budget,
+        }),
+        [OPTIONAL_SERVICE.costPolicy]: Object.freeze({
+            snapshot: () => system.status().policy,
+            stats: () => system.status().policyStats,
+        }),
+        [OPTIONAL_SERVICE.costAudit]: Object.freeze({
+            verify: () => system.audit().verify(),
+            substitutions: (filter) => system.audit().substitutions(filter),
+            trace: (input) => system.trace(input),
+        }),
+    };
+    for (const [name, face] of Object.entries(optionalFaces)) {
+        try {
+            ctx.effect(() => ctx.provide(name, face));
+        }
+        catch { /* 不支持可选子服务的运行时也无妨 */ }
+    }
     master.registerSubplugin({
         id: 'cost-optimizer',
         name: 'dsh-master-cost-optimizer',
-        capabilities: ['token-estimate', 'savings-record', 'cost-status'],
-        description: 'HarnessMM observe 层（仅 fork）',
+        capabilities: ['token-estimate', 'savings-record', 'cost-status', 'cost-ledger', 'cost-budget', 'cost-policy', 'cost-audit'],
+        description: 'HarnessMM observe 层（仅 fork；3.3.0 M1 系统层）',
     });
     return service;
 }