@twinsearth/dsh-master 3.2.10 → 3.3.1

package/README.md

@@ -84,12 +84,16 @@ dsh plugin add <package>  # 加载 dist-host/dist-worker
 - [Worker Agent Loop](docs/WORKER-AGENT-LOOP.md)
 - [SuperAgent v3.2.1 设计与契约](docs/SUPERAGENT.md)
 - [架构设计](docs/ARCHITECTURE.md)
+- [3.3.0 成本优化架构（总体架构 / 实施进度）](docs/DESIGN-v3.3.0-cost-optimization.md)
+- [第三方参考实现与移植边界](docs/THIRD-PARTY.md)
 - [路线图（3.2.0–3.4.0）](docs/ROADMAP.md)
 - [安全边界](docs/SECURITY.md)
 - [变更记录](docs/CHANGELOG.md)
 
 ## 状态
 
+- **3.3.1 发布线**：M5 收口 —— 瓮城回流接口升级到 `@twinsearth/dsh-fang-contract` **1.1.0**（`fang.relay.publish` / `fang.relay.status`），房主侧 `src/cost/fang-relay.ts` 做真实探测与投递（只有对端回执才算送达，不可用给具名原因）；里程碑 **M1–M5 全部 done**。详见 [M5 回流实测](docs/EXPERIMENT-M5-fang-relay.md)。
+- **3.3.0 发布线**：成本优化系统层（ledger / budget / policy / audit）+ Worker 四个成本切点 + A1 紧凑化（默认 shadow）+ A2–A3 / B1–B4；真实 A/B 实测 tokens/task 6263 → 3906.75（−37.6%），成功率 0pp 差，详见 [3.3.0 架构设计](docs/DESIGN-v3.3.0-cost-optimization.md)。
 - 3.2.10 发布线：角色矩阵放宽——Router 进入母体（essence/mother），Worker 与 Worker Agent Loop 进入原身（fork/essence）；母体仍不接纳执行体，fork 仍不注册 Router。
 - 3.2.9 发布线：房主面板改注册到 `shell.overlay` 常驻浮层——点击面板之外不收起、侧栏「房主」按钮二次点击收起、正文独立滚动；新增无浏览器 hook 运行时行为测试（开关、无 outside-click 监听、滚动容器、SSE 失败不卸载面板）。
 - 3.2.8 发布线：与瓮城通过 fang-master contract 1.0 互联（local/http/file/legacy 四级保底）；GitHub Release + NPM public。

package/client.js

@@ -241,6 +241,55 @@ window.__ModuleLoader__.load({
       )
     }
 
+    /**
+     * §11：成本（只读）块。
+     *
+     * 只消费 `/dsh-master/api/superagent/cost` 的 `service` 段，**不写任何业务状态**、
+     * 不触发任何成本动作；A（单价项）与 B（跳过调用项）分列展示，绝不合并成一个数字。
+     */
+    function CostCard() {
+      const [cost, setCost] = React.useState(null)
+      const [failed, setFailed] = React.useState(false)
+
+      React.useEffect(() => {
+        let alive = true
+        const load = async () => {
+          try {
+            const response = await fetch('/dsh-master/api/superagent/cost', { headers: { accept: 'application/json' } })
+            const body = await response.json().catch(() => null)
+            if (!alive) return
+            setCost(response.ok && body ? body : null)
+            setFailed(!response.ok)
+          } catch { if (alive) setFailed(true) }
+        }
+        void load()
+        const timer = setInterval(load, 5000)
+        return () => { alive = false; clearInterval(timer) }
+      }, [])
+
+      const block = cost && cost.service ? cost.service : null
+      const columns = block && block.columns ? block.columns : null
+      const savings = block && block.savings ? block.savings : null
+      const fmt = (value) => (value === null || value === undefined ? '—' : Number(value).toLocaleString())
+
+      return h('div', { style: S.card, 'data-dsh-master': 'cost-block' },
+        h('div', { style: S.row },
+          h('span', { style: S.name }, '成本（只读）'),
+          tag(block ? '3.3.1' : '未启用', block ? undefined : '#B45309')),
+        failed ? h('div', { style: S.error }, '成本接口不可达') : null,
+        !block && !failed ? h('div', { style: S.desc }, '成本系统未装配（cost-optimizer 未启用或角色不匹配）') : null,
+        columns ? h('div', { style: S.desc },
+          '单价项 A：' + fmt(columns.unitPriceSaved) + ' · ',
+          '跳过调用 B：' + fmt(columns.skippedCallSaved) + '（' + fmt(columns.skippedCalls) + ' 次）') : null,
+        columns ? h('div', { style: S.desc },
+          'governance：' + fmt(columns.governanceTotal) + ' · 净节省：' + fmt(columns.netSaved)) : null,
+        columns && columns.netLossTasks && columns.netLossTasks.length > 0
+          ? h('div', { style: S.off }, '净亏任务：' + columns.netLossTasks.slice(0, 3).join(', '))
+          : null,
+        savings ? h('div', { style: S.desc }, '命中率：' + (block.hitRate === undefined || block.hitRate === null ? '—' : (Number(block.hitRate) * 100).toFixed(1) + '%')) : null,
+      )
+    }
+
     function MasterPanel() {
       const [status, setStatus] = React.useState(null)
       const [error, setError] = React.useState('')
@@ -283,6 +332,7 @@ window.__ModuleLoader__.load({
             h('div', { style: S.desc }, '运行：' + Math.max(1, Math.round((status.uptimeMs || 0) / 60000)) + ' 分钟'),
           ) : null,
           ...items.map((item) => h(SubpluginCard, { key: item.id, item })),
+          h(CostCard),
           h(FangCard, { cooperation: status && status.cooperation }),
           h(LiveFeed),
           h('div', { style: S.desc }, '3.2.10：角色矩阵放宽（Router→essence/mother，Worker/Loop→fork/essence）；面板常驻、按钮二次点击收起、正文可滚动；实时流（SSE）+ token 轮换/审计。'),

package/dist-host/contract/client.js

@@ -77,6 +77,13 @@ export function createContractClient(options = {}) {
         async resolveDecision(params, invokeOptions = {}) { return await client.invoke(METHODS.DECISION_RESOLVE, params, invokeOptions); },
         async listSessions(params = {}, invokeOptions = {}) { return await client.invoke(METHODS.SESSION_LIST, params, invokeOptions); },
         async orchestratorStatus(params = {}, invokeOptions = {}) { return await client.invoke(METHODS.ORCHESTRATOR_STATUS, params, invokeOptions); },
+        /** contract 1.1：批量投递回流事件（按 event.id 幂等；返回回执与游标）。 */
+        async publishRelay(events, invokeOptions = {}) {
+            const params = Array.isArray(events) ? { events } : (events && typeof events === 'object' ? events : { events: [] });
+            return await client.invoke(METHODS.RELAY_PUBLISH, params, invokeOptions);
+        },
+        /** contract 1.1：读取对端回流状态（对端自报 peer/cursor/累计计数）。 */
+        async relayStatus(params = {}, invokeOptions = {}) { return await client.invoke(METHODS.RELAY_STATUS, params, invokeOptions); },
     };
     return client;
 }

package/dist-host/contract/constants.js

@@ -9,7 +9,7 @@
  *   * 删除/改义必须升 MAJOR，并保留至少一个 MINOR 周期的双写（method@1 与 method@2）。
  */
 export const CONTRACT_PACKAGE = '@twinsearth/dsh-fang-contract';
-export const CONTRACT_VERSION = '1.0.0';
+export const CONTRACT_VERSION = '1.1.0';
 export const PROTOCOL = 'fang-master';
 export const PROTOCOL_VERSION = 1;
 export const MIN_COMPATIBLE_MAJOR = 1;
@@ -24,6 +24,8 @@ export const METHODS = Object.freeze({
     DECISION_RESOLVE: 'fang.decision.resolve',
     SESSION_LIST: 'fang.session.list',
     ORCHESTRATOR_STATUS: 'fang.orchestrator.status',
+    RELAY_PUBLISH: 'fang.relay.publish',
+    RELAY_STATUS: 'fang.relay.status',
 });
 /** 方法 → 契约版本（用于协商后的方法裁剪）。 */
 export const METHOD_VERSION = Object.freeze({
@@ -36,9 +38,11 @@ export const METHOD_VERSION = Object.freeze({
     [METHODS.DECISION_RESOLVE]: '1.0',
     [METHODS.SESSION_LIST]: '1.0',
     [METHODS.ORCHESTRATOR_STATUS]: '1.0',
+    [METHODS.RELAY_PUBLISH]: '1.1',
+    [METHODS.RELAY_STATUS]: '1.1',
 });
 export const CAPABILITIES = Object.freeze([
-    'sync', 'async', 'idempotent', 'stream-events', 'file-outbox',
+    'sync', 'async', 'idempotent', 'stream-events', 'file-outbox', 'event-relay',
 ]);
 export const ROLES = Object.freeze(['mother', 'essence', 'fork']);
 export const ERROR_CODES = Object.freeze({
@@ -68,3 +72,13 @@ export const LEGACY_SERVICE_KEYS = Object.freeze({
     sessionCatalog: 'fangSessionCatalog',
     orchestrator: 'fang',
 });
+/**
+ * 回流接口的硬上限（1.1）。超限是**协议错误**而不是静默截断：
+ * 调用方必须自己分批，服务端不得悄悄丢事件（回流要可对账）。
+ */
+export const RELAY_LIMITS = Object.freeze({
+    maxBatch: 128,
+    maxEventBytes: 32_000,
+    maxPayloadBytes: 512_000,
+    maxRecords: 5_000,
+});

package/dist-host/contract/index.js

@@ -13,5 +13,6 @@ export * from './constants.js';
 export * from './envelope.js';
 export * from './negotiate.js';
 export * from './server.js';
+export * from './relay.js';
 export * from './transports.js';
 export * from './client.js';

package/dist-host/contract/relay.js

@@ -0,0 +1,239 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// Copyright (c) 2026 dsh-Fang/dsh-Master contributors — see LICENSE.
+/**
+ * 回流（relay）接口 —— contract 1.1 新增能力。
+ *
+ * 背景：房主（dsh-Master）的成本总线产生 `cost:event` / `cost:degraded` /
+ * `cost:substitution` 三类事件，需要**单向**投递给瓮城（dsh-Fang）做产物回流与
+ * 信息栏展示。1.0 的方法表只有请求-响应式的 fork/decision/session，缺一个批量、
+ * 可去重、有回执的事件入口，因此 1.1 追加两个方法：
+ *
+ *   * `fang.relay.publish` —— 批量投递事件，按 `event.id` 幂等去重，返回回执与游标；
+ *   * `fang.relay.status`  —— 对端自报回流状态（自身标识 peerLabel、游标、累计计数）。
+ *
+ * 兼容规则（README §2）：新增方法只升 MINOR；1.0 的对端在 `hello` 协商时不会
+ * 宣告这两个方法，方法集被自动裁剪，调用方据此判定“回流不可用”，**不得**把
+ * 裁剪当成失败重试。
+ *
+ * 本文件只做协议与参考实现：不读写磁盘、不联网、不持有任何凭据。
+ */
+import { CONTRACT_VERSION, METHODS, RELAY_LIMITS } from './constants.js';
+import { createContractServer } from './server.js';
+function nowMs(now) {
+    const value = typeof now === 'function' ? now() : Date.now();
+    const n = Number(value);
+    return Number.isFinite(n) ? n : Date.now();
+}
+function asLimit(value, fallback) {
+    const n = Number(value);
+    return Number.isFinite(n) && n > 0 ? Math.floor(n) : fallback;
+}
+function byteLength(value) {
+    try {
+        return Buffer.byteLength(JSON.stringify(value ?? null), 'utf8');
+    }
+    catch {
+        return Number.POSITIVE_INFINITY;
+    }
+}
+/**
+ * 校验一批回流事件。逐条判定：合法的接受，非法的计 `rejected` 并给原因，
+ * 不因单条坏数据丢掉整批（但整批不可用会抛 `relay-events-invalid`）。
+ *
+ * @param {unknown} events
+ * @param {{maxBatch?:number, maxEventBytes?:number, maxPayloadBytes?:number}} [limits]
+ */
+export function validateRelayEvents(events, limits = {}) {
+    const maxBatch = asLimit(limits.maxBatch, RELAY_LIMITS.maxBatch);
+    const maxEventBytes = asLimit(limits.maxEventBytes, RELAY_LIMITS.maxEventBytes);
+    const maxPayloadBytes = asLimit(limits.maxPayloadBytes, RELAY_LIMITS.maxPayloadBytes);
+    const errors = [];
+    if (!Array.isArray(events)) {
+        return { ok: false, code: 'relay-events-invalid', errors: ['events-must-be-array'], accepted: [], rejected: [] };
+    }
+    if (events.length === 0) {
+        return { ok: false, code: 'relay-events-invalid', errors: ['events-empty'], accepted: [], rejected: [] };
+    }
+    if (events.length > maxBatch) {
+        return { ok: false, code: 'relay-events-invalid', errors: [`events-too-many(>${maxBatch})`], accepted: [], rejected: [] };
+    }
+    if (byteLength(events) > maxPayloadBytes) {
+        return { ok: false, code: 'relay-events-invalid', errors: [`payload-too-large(>${maxPayloadBytes})`], accepted: [], rejected: [] };
+    }
+    const accepted = [];
+    const rejected = [];
+    const seen = new Set();
+    for (const raw of events) {
+        const item = raw && typeof raw === 'object' ? raw : null;
+        if (!item) {
+            rejected.push({ id: null, reason: 'event-not-object' });
+            continue;
+        }
+        const id = typeof item.id === 'string' ? item.id.trim() : '';
+        if (!id) {
+            rejected.push({ id: null, reason: 'id-required' });
+            continue;
+        }
+        if (typeof item.type !== 'string' || item.type.trim() === '') {
+            rejected.push({ id, reason: 'type-required' });
+            continue;
+        }
+        if (byteLength(item) > maxEventBytes) {
+            rejected.push({ id, reason: `event-too-large(>${maxEventBytes})` });
+            continue;
+        }
+        // 同一批内重复 id 也算重复投递：只接受第一次，其余计 duplicates。
+        if (seen.has(id)) {
+            rejected.push({ id, reason: 'duplicate-in-batch' });
+            continue;
+        }
+        seen.add(id);
+        accepted.push({
+            id,
+            type: String(item.type),
+            at: Number.isFinite(Number(item.at)) ? Number(item.at) : 0,
+            payload: item.payload && typeof item.payload === 'object' ? item.payload : {},
+            meta: item.meta && typeof item.meta === 'object' ? item.meta : {},
+        });
+    }
+    return { ok: accepted.length > 0 || rejected.length === 0, errors, accepted, rejected };
+}
+/**
+ * 回流接收端（瓮城侧）的参考存储：按 event.id 幂等去重，保留有界回执环。
+ *
+ * @param {{
+ *   peerLabel?: string, role?: string, instanceId?: string,
+ *   maxRecords?: number, now?: () => number, limits?: object,
+ * }} [options]
+ */
+export function createRelayStore(options = {}) {
+    const peerLabel = String(options.peerLabel ?? 'contract-server');
+    const role = String(options.role ?? 'mother');
+    const instanceId = String(options.instanceId ?? '');
+    const maxRecords = asLimit(options.maxRecords, RELAY_LIMITS.maxRecords);
+    const limits = { ...RELAY_LIMITS, ...(options.limits && typeof options.limits === 'object' ? options.limits : {}) };
+    const now = typeof options.now === 'function' ? options.now : () => Date.now();
+    const seen = new Map();
+    const receipts = [];
+    const counters = { accepted: 0, duplicates: 0, rejected: 0, batches: 0 };
+    let cursor = 0;
+    let lastAt = 0;
+    const lastErrors = [];
+    function remember(receipt) {
+        receipts.push(receipt);
+        if (receipts.length > maxRecords)
+            receipts.shift();
+    }
+    /** @param {{events?: unknown, batchId?: string, taskId?: string}} [params] */
+    function publish(params = {}) {
+        const validated = validateRelayEvents(params?.events, limits);
+        if (validated.ok === false) {
+            const error = new Error(validated.errors.join(', ') || 'relay-events-invalid');
+            error.code = 'relay-events-invalid';
+            error.retryable = false;
+            throw error;
+        }
+        counters.batches += 1;
+        const acceptedIds = [];
+        let duplicates = 0;
+        for (const event of validated.accepted) {
+            if (seen.has(event.id)) {
+                duplicates += 1;
+                continue;
+            }
+            seen.set(event.id, { at: nowMs(now), cursor: cursor + 1 });
+            cursor += 1;
+            counters.accepted += 1;
+            acceptedIds.push(event.id);
+            remember({ id: event.id, type: event.type, at: event.at, cursor });
+            lastAt = nowMs(now);
+        }
+        counters.duplicates += duplicates;
+        for (const item of validated.rejected) {
+            // 批内重复计入 duplicates；其余非法条目计入 rejected 并留原因（有界）。
+            if (item.reason === 'duplicate-in-batch') {
+                duplicates += 1;
+                counters.duplicates += 1;
+                continue;
+            }
+            counters.rejected += 1;
+            if (lastErrors.length < 50)
+                lastErrors.push({ id: item.id, reason: item.reason });
+        }
+        const batchId = String(params?.batchId ?? `batch-${counters.batches}`);
+        const receipt = Object.freeze({
+            ok: true,
+            batchId,
+            taskId: params?.taskId === undefined ? null : String(params.taskId),
+            accepted: acceptedIds.length,
+            duplicates,
+            rejected: validated.rejected.length - duplicates,
+            cursor,
+            acceptedIds,
+            peer: peerLabel,
+            at: nowMs(now),
+        });
+        if (seen.size > maxRecords * 4) {
+            // 幂等窗口有界：按插入顺序淘汰最老的一半，避免长跑进程无界增长。
+            const overflow = seen.size - maxRecords * 2;
+            let removed = 0;
+            for (const key of seen.keys()) {
+                if (removed >= overflow)
+                    break;
+                seen.delete(key);
+                removed += 1;
+            }
+        }
+        return receipt;
+    }
+    function status() {
+        return Object.freeze({
+            ok: true,
+            available: true,
+            peer: peerLabel,
+            role,
+            instanceId,
+            contractVersion: CONTRACT_VERSION,
+            cursor,
+            accepted: counters.accepted,
+            duplicates: counters.duplicates,
+            rejected: counters.rejected,
+            batches: counters.batches,
+            lastAt,
+            limits: { ...limits },
+            lastErrors: [...lastErrors],
+        });
+    }
+    function describe() {
+        return Object.freeze({ peerLabel, records: receipts.length, seen: seen.size, ...counters, cursor });
+    }
+    return Object.freeze({ publish, status, describe, receipts: () => [...receipts] });
+}
+/**
+ * 把回流 store 包成契约 handler 表（挂到 `createContractServer({handlers})`）。
+ * @param {{publish:Function, status:Function}} store
+ */
+export function relayHandlers(store) {
+    if (!store || typeof store.publish !== 'function' || typeof store.status !== 'function') {
+        throw new Error('relayHandlers requires a relay store with publish/status');
+    }
+    return {
+        [METHODS.RELAY_PUBLISH]: (params) => store.publish(params ?? {}),
+        [METHODS.RELAY_STATUS]: () => store.status(),
+    };
+}
+/**
+ * 便捷构造：带回流能力的契约服务端（瓮城侧挂载用）。
+ * `peerLabel` 是**自报**标识，房主侧据此记录“对端是谁”，不参与鉴权。
+ */
+export function createRelayContractServer(options = {}) {
+    const { peerLabel = 'contract-server', role = 'mother', instanceId = '', now, limits, maxRecords, extraHandlers = {}, ...rest } = options;
+    const store = createRelayStore({ peerLabel, role, instanceId, now, limits, maxRecords });
+    const server = createContractServer({
+        role,
+        instanceId,
+        handlers: { ...relayHandlers(store), ...(extraHandlers && typeof extraHandlers === 'object' ? extraHandlers : {}) },
+        ...rest,
+    });
+    return { server, store };
+}

package/dist-host/cost/attribution.js

@@ -0,0 +1,183 @@
+// 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 系统层 · attribution（归因，设计 §5.4）。
+ *
+ * 三条硬规则：
+ *   1. **每条 savedTokens 必须带 moduleId**（缺失 ⇒ `module-missing`，不猜、不默认）；
+ *   2. 差额进 `unattributed`，报表**单列**——未归因收益不得算作任何模块收益；
+ *   3. 归因算法（工具面）：`baselineOutputTokens(toolName, 长度) − actualOutputTokens`，
+ *      baseline 由 A1 固定拟合式给出（`worker/baseline-fit.ts`，参数在 docs §5.4.1 冻结）。
+ *
+ * 另守 §5.3 口径：`shadow` 只累计「本可节省」，`enforce` 才写入 execution 账本且
+ * `totalTokens=0`（不重复计入已消耗 token）。
+ */
+import { COST_MODULES } from "./types.js";
+function finiteNonNegative(value) {
+    const n = Number(value);
+    return Number.isFinite(n) && n >= 0 ? Math.floor(n) : null;
+}
+/**
+ * @param {{ledger: {append: Function}, now?: () => number}} options
+ */
+export function createAttribution(options = {}) {
+    const ledger = options.ledger;
+    if (!ledger || typeof ledger.append !== 'function')
+        throw new Error('attribution requires a ledger');
+    const now = typeof options.now === 'function' ? options.now : () => Date.now();
+    const allowed = new Set(COST_MODULES);
+    const modules = new Map();
+    const tasks = new Map();
+    const moduleRow = (module) => {
+        if (!modules.has(module))
+            modules.set(module, { module, events: 0, projectedTokens: 0, enforceSavedTokens: 0 });
+        return modules.get(module);
+    };
+    const taskRow = (taskId, module) => {
+        const key = `${taskId ?? ''}|${module}`;
+        if (!tasks.has(key))
+            tasks.set(key, { key, taskId: taskId === undefined ? null : String(taskId), module, events: 0, projectedTokens: 0, enforceSavedTokens: 0 });
+        return tasks.get(key);
+    };
+    /**
+     * @param {{taskId?: string, module: string, savedTokens: number, mode?: string, meta?: object,
+     *          forkId?: string, sessionId?: string}} input
+     */
+    function attribute(input = {}) {
+        const saved = finiteNonNegative(input.savedTokens);
+        if (saved === null)
+            return { ok: false, code: 'saved-tokens-invalid', message: 'savedTokens must be a non-negative number' };
+        // §5.4-1：moduleId 必填，缺失不猜默认值。
+        if (input.module === undefined || input.module === null || String(input.module).trim() === '') {
+            return { ok: false, code: 'module-missing', message: 'every savedTokens must carry a moduleId' };
+        }
+        const module = String(input.module);
+        if (!allowed.has(module))
+            return { ok: false, code: 'module-invalid', message: `module must be one of ${COST_MODULES.join('/')}` };
+        const enforce = String(input.mode ?? 'shadow') === 'enforce';
+        const row = moduleRow(module);
+        const perTask = taskRow(input.taskId, module);
+        if (!enforce) {
+            row.events += 1;
+            row.projectedTokens += saved;
+            perTask.events += 1;
+            perTask.projectedTokens += saved;
+            return {
+                ok: true,
+                mode: 'shadow',
+                module,
+                projectedTokens: saved,
+                shadow: { events: row.events, projectedTokens: row.projectedTokens, appliedTokens: row.enforceSavedTokens },
+                at: now(),
+            };
+        }
+        const appended = ledger.append({
+            account: 'execution',
+            module,
+            source: 'tool',
+            phase: 'tool',
+            taskId: input.taskId === undefined ? null : String(input.taskId),
+            forkId: input.forkId,
+            sessionId: input.sessionId,
+            step: input.step,
+            turn: input.turn,
+            totalTokens: 0,
+            savedTokens: saved,
+            meta: { kind: 'attribution', ...(input.meta && typeof input.meta === 'object' ? input.meta : {}), mode: 'enforce' },
+        });
+        if (!appended.ok)
+            return { ok: false, code: appended.code, message: appended.message };
+        row.events += 1;
+        row.enforceSavedTokens += saved;
+        perTask.events += 1;
+        perTask.enforceSavedTokens += saved;
+        return {
+            ok: true,
+            mode: 'enforce',
+            module,
+            savedTokens: saved,
+            ledger: { id: appended.entry.id },
+            shadow: { events: row.events, projectedTokens: row.projectedTokens, appliedTokens: row.enforceSavedTokens },
+            at: now(),
+        };
+    }
+    /**
+     * §5.4-2：按「总额 − 各模块之和」结算，差额自动进 `unattributed`。
+     * 任何未提供 moduleId 的条目都会被拒绝（模块收益不得凭空出现）。
+     *
+     * @param {{taskId?: string, totalSavedTokens: number, items?: Array<{module: string, savedTokens: number}>,
+     *          mode?: string, forkId?: string, sessionId?: string}} input
+     */
+    function attributeTotal(input = {}) {
+        const total = finiteNonNegative(input.totalSavedTokens);
+        if (total === null)
+            return { ok: false, code: 'saved-tokens-invalid', message: 'totalSavedTokens must be a non-negative number' };
+        const items = Array.isArray(input.items) ? input.items : [];
+        let attributed = 0;
+        const applied = [];
+        for (const item of items) {
+            const out = attribute({
+                taskId: input.taskId,
+                module: item?.module,
+                savedTokens: item?.savedTokens,
+                mode: input.mode,
+                forkId: input.forkId,
+                sessionId: input.sessionId,
+                meta: { kind: 'module-share' },
+            });
+            if (!out.ok)
+                return out;
+            attributed += finiteNonNegative(item?.savedTokens) ?? 0;
+            applied.push({ module: String(item.module), savedTokens: finiteNonNegative(item?.savedTokens) ?? 0 });
+        }
+        if (attributed > total) {
+            return { ok: false, code: 'attribution-overflow', message: `attributed ${attributed} exceeds total ${total}` };
+        }
+        const residual = total - attributed;
+        if (residual > 0) {
+            const out = attribute({
+                taskId: input.taskId,
+                module: 'unattributed',
+                savedTokens: residual,
+                mode: input.mode,
+                forkId: input.forkId,
+                sessionId: input.sessionId,
+                meta: { kind: 'residual' },
+            });
+            if (!out.ok)
+                return out;
+        }
+        return { ok: true, totalSavedTokens: total, attributedTokens: attributed, unattributedTokens: residual, items: applied, at: now() };
+    }
+    function snapshot() {
+        const moduleRows = [...modules.values()]
+            .map((item) => Object.freeze({ ...item }))
+            .sort((a, b) => b.projectedTokens + b.enforceSavedTokens - (a.projectedTokens + a.enforceSavedTokens));
+        const taskRows = [...tasks.values()]
+            .map((item) => Object.freeze({ ...item }))
+            .sort((a, b) => b.projectedTokens + b.enforceSavedTokens - (a.projectedTokens + a.enforceSavedTokens));
+        const named = moduleRows.filter((row) => row.module !== 'unattributed');
+        const unattributed = moduleRows.filter((row) => row.module === 'unattributed');
+        const sum = (rows, key) => rows.reduce((total, row) => total + row[key], 0);
+        return Object.freeze({
+            ok: true,
+            modules: moduleRows,
+            tasks: taskRows,
+            /** 模块收益（不含 unattributed）——报表只能把这一项当「模块业绩」。 */
+            attributedSavedTotal: sum(named, 'enforceSavedTokens'),
+            attributedProjectedTotal: sum(named, 'projectedTokens'),
+            /** 未归因收益：单列，永不并入上面的模块业绩。 */
+            unattributedSavedTotal: sum(unattributed, 'enforceSavedTokens'),
+            unattributedProjectedTotal: sum(unattributed, 'projectedTokens'),
+            projectedTotal: sum(moduleRows, 'projectedTokens'),
+            enforceSavedTotal: sum(moduleRows, 'enforceSavedTokens'),
+        });
+    }
+    function reset() {
+        modules.clear();
+        tasks.clear();
+        return { ok: true };
+    }
+    return Object.freeze({ attribute, attributeTotal, snapshot, reset });
+}