berry-agent 0.1.0-alpha.1

package/dist/compaction/service.js

@@ -0,0 +1,422 @@
+import { DEFAULT_COMPACTION_CONFIG } from './types.js';
+import { buildSummaryPrompt, evaluateThreshold, planFromRange, planSegment, previousSummaryText, SUMMARY_PREFIX, summaryBudgetFor, validateAdjustedRange, } from './policy.js';
+import { ccrDirectoryOf, ccrHashOf, withCcrSection } from './ccr.js';
+/** 空闲态逐出帽（在飞/排队态不逐——只逐空闲） */
+const IDLE_STATES_CAP = 256;
+/** 三振阈值（05 §2.1 回落三律第 3 律——同一 pluginId 进程级连续 3 次失败停用） */
+const STRIKE_LIMIT = 3;
+/** fallback 词错误摘要截断长度（防单条爆账——审计面够诊断即可） */
+const FALLBACK_ERROR_MAX = 500;
+/** 算法执行段超时标记（fallback stage='timeout' 判型用） */
+class AlgoTimeoutError extends Error {
+}
+/** 插件路空文本产物标记（fallback stage='rejected' 判型用——同宿主通道失败律计入三振） */
+class AlgoEmptyTextError extends Error {
+}
+/** fallback 词统一落账形（05 §1.1——回落三律第 3 律响亮记账；circuit 位末次记三振停用） */
+function appendFallback(log, source, stage, error, circuit = false) {
+    log.append('compaction/fallback', {
+        source,
+        stage,
+        error: String(error).slice(0, FALLBACK_ERROR_MAX),
+        ...(circuit ? { circuit: true } : {}),
+    });
+}
+/**
+ * obs-b 五门 skip 统一落账形（05 §1.1 compaction/skip + §2.1 判序定形注）：
+ * fire 而被门挡才落（below 恒不落）；basis 五件 = fire 判据快照（与 start
+ * 同律——触发时刻判据素材）；remainMs 仅 cooldown 门随行（窗余值）；五门
+ * 均不动冷却锚（skip 非 completed——下轮触发照常参与判阈）。
+ */
+function appendSkip(log, gate, basis, remainMs) {
+    log.append('compaction/skip', {
+        gate,
+        ...basis,
+        ...(remainMs !== undefined ? { remainMs } : {}),
+    });
+}
+/**
+ * 组装压缩服务。五步骨架两事件形（05 §2.1 步 3 勘正）：摘要 user/message
+ * 普通 append（不带 surfaceOp——孤儿摘要处置条款依赖此形）；遮蔽指令
+ * compaction/surface 经 appendWithSurfaceOp 正门独携信封。
+ */
+export function createCompactionService(options = {}) {
+    const channel = options.channel;
+    // 配置晚绑定：getConfig seam 优先（U4 配置槽）；缺省 = 装配时常量合并
+    const defaultConfig = { ...DEFAULT_COMPACTION_CONFIG, ...options.config };
+    const getConfig = options.getConfig ?? (() => defaultConfig);
+    const getProvider = options.getProvider;
+    const onBeforeCompact = options.onBeforeCompact;
+    const algoTimeoutMs = options.algoTimeoutMs ?? 60_000;
+    const now = options.now ?? Date.now;
+    const warn = options.warn ?? ((message) => process.stderr.write(`${message}\n`));
+    /** per-session 防抖分账（插入序即逐出序——Map 迭代序保真） */
+    const states = new Map();
+    /** 全局串行链尾（并发上限 1 的单点；链身永不 reject——尾接吞异常） */
+    let chain = Promise.resolve();
+    /** 通道缺席告警旗（只告警一次——缺配是装配错误不是运行抖动） */
+    let warnedNoChannel = false;
+    /**
+     * 三振表（进程级）：按 pluginId 合并计数——接管缝声明者与 provider 槽注册
+     * 者同账；复位 = 同 pluginId 任一路成功即清（「连续」的合并计数语义）。
+     * 熔断复位走进程重启（05 §2.1 回落三律第 3 律）。
+     */
+    const strikes = new Map();
+    const isTripped = (pluginId) => (strikes.get(pluginId) ?? 0) >= STRIKE_LIMIT;
+    /** 全局串行入队：前序成败不阻断后继；result 即刻挂 handler 防 unhandledRejection */
+    function enqueue(body) {
+        const result = chain.then(body, body);
+        chain = result.then(() => undefined, () => undefined);
+        return result;
+    }
+    /** 取（或建）per-session 状态；建前按帽逐出空闲态 */
+    function stateOf(sessionId) {
+        let state = states.get(sessionId);
+        if (state === undefined) {
+            // 帽前逐出：只逐空闲态（在飞/排队的删了会破防重入账）；全在飞时暂超帽
+            // 可接受——帽执法不破在飞正确性
+            if (states.size >= IDLE_STATES_CAP) {
+                for (const [key, value] of states) {
+                    if (states.size < IDLE_STATES_CAP)
+                        break;
+                    if (!value.pending)
+                        states.delete(key);
+                }
+            }
+            state = { lastCompactAt: null, pending: false };
+            states.set(sessionId, state);
+        }
+        return state;
+    }
+    /** 末条 compaction/end 的 seq（-1 = 从未压缩）——溢出路「他路已缩量」对账锚 */
+    function lastEndSeq(log) {
+        const ends = log.eventsOfType('compaction/end');
+        return ends.length > 0 ? ends[ends.length - 1].seq : -1;
+    }
+    /** 宿主通道执行（直选路与回落位共用）：五段结构 prompt + 迭代链前次摘要 + 字符制预算 */
+    async function runHost(log, plan) {
+        const response = await channel.complete({
+            prompt: buildSummaryPrompt({
+                occluded: plan.occluded,
+                previousSummary: previousSummaryText(log.events()),
+                maxChars: summaryBudgetFor(plan.occludedChars, getConfig()),
+            }),
+            maxChars: summaryBudgetFor(plan.occludedChars, getConfig()),
+        });
+        // 空摘要 = 通道质量异常——按通道失败收口（把内容遮在空摘要后是静默信息丢失）
+        if (response.text.trim().length === 0)
+            throw new Error('摘要通道返回空文本');
+        return response.text;
+    }
+    /** 算法执行段预算帽（超时后原 promise 仍在跑——SummarizerFn 无 abort 面，产物弃用不采信） */
+    function withTimeout(p, ms) {
+        return new Promise((resolve, reject) => {
+            const timer = setTimeout(() => reject(new AlgoTimeoutError(`算法执行段超预算 ${ms}ms`)), ms);
+            p.then((r) => {
+                clearTimeout(timer);
+                resolve(r);
+            }, (e) => {
+                clearTimeout(timer);
+                reject(e);
+            });
+        });
+    }
+    /**
+     * 算法执行（U4）：host 直选失败原样上抛；插件路三段执法——60s 预算 → 失败
+     * fallback 记账 + 三振推进 → 回落直达宿主（不串联试下一层）。回落成功记
+     * summarizer='host'（谁失败由 fallback 词承载——05 §1.1 词表）；回落失败
+     * 上抛（失败终局恒宿主通道失败）。
+     */
+    async function runAlgo(log, plan, algo) {
+        if (algo.kind === 'host') {
+            return { text: await runHost(log, plan), summarizer: 'host' };
+        }
+        try {
+            const response = await withTimeout(algo.fn({
+                sessionId: log.sessionId,
+                occluded: plan.occluded,
+                previousSummary: previousSummaryText(log.events()) ?? undefined,
+                maxChars: summaryBudgetFor(plan.occludedChars, getConfig()),
+                plan,
+            }), algoTimeoutMs);
+            // 空文本产物同宿主通道失败律（fiveStep 既有）——计入三振
+            if (response.text.trim().length === 0)
+                throw new AlgoEmptyTextError('插件算法返回空文本');
+            strikes.delete(algo.pluginId); // 复位：同 pluginId 任一路成功即清
+            return { text: response.text, summarizer: `plugin:${algo.pluginId}` };
+        }
+        catch (err) {
+            // 失败三形态判型：超预算 / 空文本产物 / 抛错（stage 词面 05 §1.1）
+            const stage = err instanceof AlgoTimeoutError ? 'timeout' : err instanceof AlgoEmptyTextError ? 'rejected' : 'throw';
+            const count = (strikes.get(algo.pluginId) ?? 0) + 1;
+            const circuit = count >= STRIKE_LIMIT;
+            strikes.set(algo.pluginId, count);
+            appendFallback(log, `plugin:${algo.pluginId}`, stage, err, circuit);
+            // 回落不失败：当轮直达宿主通道继续完成（策略可崩、机制不塌——三律第 1 律）
+            return { text: await runHost(log, plan), summarizer: 'host' };
+        }
+    }
+    /**
+     * 五步骨架（05 §2.1）：算法解析先行 → start（携 summarizer 归因终局值）→
+     * 摘要普通 append → compaction/surface 经正门携信封 → end。失败即 end-failed
+     * 闭段（防孤 start 悬挂）后原样上抛——上层按路收口（阈值路 warn、溢出路
+     * 'failed'）。start 后置于算法解析：归因位随执行终局定形（插件路成功记
+     * plugin:<id>、回落后记 'host'；失败闭段归因恒 'host'——一切失败终局都是
+     * 宿主通道失败，插件失败已由 fallback 词承载）。
+     */
+    async function fiveStep(log, reason, plan, basis, algo = { kind: 'host' }) {
+        // 步 2 前置（算法解析——U4）：willRetry 语义不变（阈值路失败后下轮触发自然
+        // 重做，溢出路一次性）
+        let text;
+        let summarizer;
+        try {
+            ({ text, summarizer } = await runAlgo(log, plan, algo));
+        }
+        catch (err) {
+            // 失败即时闭段（防孤 start 悬挂——§4 恢复协议按未完成压缩重做）
+            log.append('compaction/start', {
+                reason,
+                willRetry: reason === 'threshold',
+                ...(basis ?? {}),
+                summarizer: 'host',
+            });
+            log.append('compaction/end', { reason: 'failed', error: String(err) });
+            throw err;
+        }
+        // 步 1：压缩意图与判据快照（basis 五件仅阈值路落账——RP4 扩值含 cache 两桶）+ 归因位
+        log.append('compaction/start', {
+            reason,
+            willRetry: reason === 'threshold',
+            ...(basis ?? {}),
+            summarizer,
+        });
+        // 步 3：摘要落账——两事件形：普通 append、不带 surfaceOp（孤儿摘要按普通
+        // user/message 同视的处置条款依赖此形）；载体前缀防注入。
+        // CCR 标记段（05 §2.1 压缩可逆性）：宿主追加非算法产物——当次标记行 +
+        // 目录恒链（此前历次 surface 事件全量：旧载体被遮蔽后历史哈希仍可达）
+        const hash = ccrHashOf(plan.occluded);
+        const directory = [
+            ...ccrDirectoryOf(log.events()),
+            { hash, messages: plan.occludedMessages, chars: plan.occludedChars },
+        ];
+        const summaryEvent = log.append('user/message', {
+            content: `${SUMMARY_PREFIX} ${withCcrSection(text, directory)}`,
+            source: 'compaction',
+        });
+        // 步 4：遮蔽指令——正门独携信封；溯源 = 区间全部 seq + 摘要事件 seq；
+        // ccrHash = 归档映射位（本事件即「哈希 → 区间原文」映射记录——events 表
+        // 即归档 store，检索面 ccr_retrieve 的匹配键）
+        const sourceEventSeqs = [];
+        for (let seq = plan.start; seq <= plan.end; seq++)
+            sourceEventSeqs.push(seq);
+        sourceEventSeqs.push(summaryEvent.seq);
+        log.appendWithSurfaceOp('compaction/surface', {
+            summarySeq: summaryEvent.seq,
+            occludedMessages: plan.occludedMessages,
+            occludedChars: plan.occludedChars,
+            ccrHash: hash,
+        }, { op: 'replace', start: plan.start, end: plan.end }, sourceEventSeqs);
+        // 步 5：完成收尾（载荷 = 规模审计对账面）
+        log.append('compaction/end', {
+            reason: 'completed',
+            occludedMessages: plan.occludedMessages,
+            occludedChars: plan.occludedChars,
+        });
+    }
+    /**
+     * 接管缝裁决（U4——宿主检查序，05 §2.1 位间裁决）：veto 先检（在场即否决
+     * 收场，余位不问）→ takeover 次之（在场即接管；接管输入 = 管线终值 plan，
+     * 先行监听者的有效调整自然随值链传入；熔断者忽略 = 资格除名后重选）→
+     * 调整位（引用变即校验 + 素材重算；非法调整 = 忽略 + fallback 记账 +
+     * 宿主原案续跑）。返回当轮算法与生效区间；veto 收场返回 null。
+     */
+    async function dispatchBeforeCompact(log, plan, basis, messages) {
+        const { value, lastAdjustedBy } = await onBeforeCompact({
+            sessionId: log.sessionId,
+            reason: 'threshold',
+            plan,
+            basis,
+        });
+        // veto 先检：一票否决收场（判阈触发过是审计面事实——落 start+end 对可查、
+        // 无声取消不可观测；意见位无三振）
+        if (value.veto !== undefined) {
+            log.append('compaction/start', { reason: 'threshold', willRetry: true, ...basis });
+            log.append('compaction/end', { reason: 'vetoed' });
+            return null;
+        }
+        let algo = { kind: 'host' };
+        // takeover 次之：熔断者忽略（资格除名——当轮按生效序落 provider/host，
+        // 非失败回落不走「直达宿主」条款；钩子本身不停派——veto/调整仍有效）
+        if (value.takeover !== undefined) {
+            const pid = value.takeover.pluginId ?? 'unknown';
+            if (isTripped(pid))
+                warn(`[COMPACTION_CIRCUIT_IGNORE] takeover 位被熔断忽略: ${pid}`);
+            else
+                algo = { kind: 'plugin', pluginId: pid, fn: value.takeover.summarize };
+        }
+        // 调整位：值链改写必新建对象（引用比较）；生效区间素材三件宿主重算（区间
+        // 主权 = 唯一采用面，不信载荷）；越宿主原案界 / 区间内无投影消息 = 非法调整
+        if (value.plan !== plan) {
+            const accepted = validateAdjustedRange(value.plan, plan) &&
+                planFromRange(value.plan.start, value.plan.end, messages).occludedMessages >= 1;
+            if (accepted) {
+                plan = planFromRange(value.plan.start, value.plan.end, messages);
+            }
+            else {
+                appendFallback(log, lastAdjustedBy !== undefined ? `plugin:${lastAdjustedBy}` : 'host', 'rejected', `非法调整区间 [${value.plan.start}, ${value.plan.end}]（越宿主原案界或区间内无投影消息）`);
+                // 宿主原案续跑（忽略该调整）
+            }
+        }
+        return { algo, plan };
+    }
+    return {
+        handleRunSettled(input) {
+            // —— obs-b 判序定形（05 §2.1）：阈值评估先行（纯函数零副作用）——
+            //    below 不落任何账（判据素材可后算，不为 below 防 durable 膨胀落
+            //    skip）；fire 而被门挡才落 compaction/skip（五门词 05 §1.1）。
+            // 判阈双源：真 token 主判（usage.input）、投影字符兜底（chars/4）
+            const cfg = getConfig();
+            const verdict = evaluateThreshold({
+                usageInput: input.usage?.input ?? null,
+                contextWindow: input.usage?.contextWindow,
+                projectedChars: input.log.projectedChars(),
+                config: cfg,
+            });
+            if (verdict === null || !verdict.fire)
+                return;
+            // basis 五件（RP4 扩值）：fire 判据快照——触发时刻判据素材（与 start
+            // 同律；cache 两桶从主 loop 真值笔同笔透传，estimate 兜底路恒缺省不落）
+            const basis = {
+                basis: verdict.basis,
+                estTokens: verdict.estTokens,
+                effectiveWindow: verdict.effectiveWindow,
+                ...(input.usage?.cacheRead !== undefined ? { cacheRead: input.usage.cacheRead } : {}),
+                ...(input.usage?.cacheWrite !== undefined ? { cacheWrite: input.usage.cacheWrite } : {}),
+            };
+            // 门① no-channel（装配级永久门最先呈报最诊断）：通道缺席——首触落
+            // 一条 skip 后静默（与 warn-once 同锚——缺配是装配错误不是运行抖动）
+            if (channel === undefined) {
+                if (!warnedNoChannel) {
+                    warnedNoChannel = true;
+                    warn('[COMPACTION_NO_CHANNEL] 摘要通道缺席——阈值压缩停用（溢出面将报 failed）');
+                    appendSkip(input.log, 'no-channel', basis);
+                }
+                return;
+            }
+            const state = stateOf(input.log.sessionId);
+            // 门② pending：防重入挡（进行中/已排队期重复 fire 可观测）
+            if (state.pending) {
+                appendSkip(input.log, 'pending', basis);
+                return;
+            }
+            // 门③ cooldown：冷却窗挡（判据与 policy.inCooldown 同式就地展开——
+            // remainMs 窗余值需要差值，单一 now() 采样点保证两值同账。2026-09-13
+            // 复盘发现 ⑰：修前判据与余值各采一次——挂钟跨采样推进可出负余值
+            // （判据说「窗内」而回执窗余为负，不同账），就此单采样）
+            const nowMs = now();
+            if (state.lastCompactAt !== null && nowMs - state.lastCompactAt < cfg.cooldownMs) {
+                appendSkip(input.log, 'cooldown', basis, cfg.cooldownMs - (nowMs - state.lastCompactAt));
+                return;
+            }
+            state.pending = true;
+            // fire-and-forget：排队体内部全收口（不外抛）；冷却锚只在成功时推进
+            void enqueue(async () => {
+                try {
+                    // 锁内复评（幻影触发闸）：全局串行链排队期间判据面可能已变（投影
+                    // 被他路压缩改写 / 配置槽翻值）；原 usage 笔不重放——真 token 计量
+                    // 是请求事实非投影派生，token-basis 复评不受投影影响
+                    const freshVerdict = evaluateThreshold({
+                        usageInput: input.usage?.input ?? null,
+                        contextWindow: input.usage?.contextWindow,
+                        projectedChars: input.log.projectedChars(),
+                        config: getConfig(),
+                    });
+                    if (freshVerdict === null || !freshVerdict.fire) {
+                        // 门④ retracted：入队时 fire、锁内已不 fire——幻影触发可查（basis
+                        // 用原 verdict 快照——触发时刻判据，非复评时刻）
+                        appendSkip(input.log, 'retracted', basis);
+                        return; // 不动冷却锚（skip 非 completed）
+                    }
+                    // 锁内新投影（全局串行链 = 互斥锁——排队期间他路压缩可能已改写投影，
+                    // 规划与落账同账零迟滞窗）
+                    const messages = input.log.projection();
+                    const plan = planSegment({
+                        events: input.log.events(),
+                        messages,
+                        tailKeep: getConfig().tailKeep,
+                    });
+                    if (plan === null) {
+                        // 门⑤ no-segment：fire 但区间规划无合法段（head+tail 全兜的薄会话形）
+                        appendSkip(input.log, 'no-segment', basis);
+                        return; // 不动冷却锚——诚实无操作可观测
+                    }
+                    // —— 接管缝（U4）：阈值路排队体内、区间规划后、start 落账前派发 ——
+                    let algo = { kind: 'host' };
+                    let effectivePlan = plan;
+                    if (onBeforeCompact !== undefined) {
+                        const dispatched = await dispatchBeforeCompact(input.log, plan, basis, messages);
+                        if (dispatched === null)
+                            return; // veto 收场（冷却锚不推进——否决非完成）
+                        ({ algo, plan: effectivePlan } = dispatched);
+                    }
+                    // provider 槽（常设注册——takeover 缺席/被熔断忽略时顶上；熔断视为空；
+                    // 只作用阈值路——溢出 路 compactForOverflow 不经此段）
+                    if (algo.kind === 'host' && getProvider !== undefined) {
+                        const provider = getProvider();
+                        if (provider !== undefined) {
+                            if (isTripped(provider.pluginId)) {
+                                warn(`[COMPACTION_CIRCUIT_IGNORE] provider 槽被熔断视为空: ${provider.pluginId}`);
+                            }
+                            else {
+                                algo = { kind: 'plugin', pluginId: provider.pluginId, fn: provider.fn };
+                            }
+                        }
+                    }
+                    await fiveStep(input.log, 'threshold', effectivePlan, basis, algo);
+                    state.lastCompactAt = now();
+                }
+                catch (err) {
+                    // fiveStep 已落 end-failed 闭段——此处只兜五步之外的意外（可观测不静默）
+                    warn(`[COMPACTION_FAILED] ${input.log.sessionId}: ${String(err)}`);
+                }
+                finally {
+                    state.pending = false;
+                }
+            });
+        },
+        async compactForOverflow(log) {
+            // 门三道之三（归驱动执法面）：通道不可用直接终态——无摘要则无压缩
+            if (channel === undefined)
+                return 'failed';
+            // 入队锚：等待期间他路压缩若已落账，缩量已达成（归因不问路——恢复目标
+            // 是「缩了可续入」，谁压的不重要；FIFO 链保证本任务在他路之后执行）
+            const endSeqAtEntry = lastEndSeq(log);
+            return enqueue(async () => {
+                if (lastEndSeq(log) !== endSeqAtEntry)
+                    return 'compacted';
+                const plan = planSegment({
+                    events: log.events(),
+                    messages: log.projection(),
+                    tailKeep: getConfig().tailKeep, // 两路同生效（数值系宿主机制参数非策略算法）
+                });
+                if (plan === null)
+                    return 'nothing'; // 区间不足（应急档也压无可压）
+                try {
+                    // 溢出 路：恒宿主缺省算法、不派发接管缝（应急自救通道不让渡策略层）
+                    await fiveStep(log, 'overflow', plan);
+                }
+                catch {
+                    return 'failed'; // fiveStep 已落 end-failed 闭段——诚实报败，重试编舞归驱动
+                }
+                // 溢出压缩同样推进冷却锚：防紧随的阈值触发对刚压过的区间重复开工
+                stateOf(log.sessionId).lastCompactAt = now();
+                return 'compacted';
+            });
+        },
+        async drain() {
+            // 快照语义：等此刻前已入队/在飞的一切（chain 永不 reject——尾接吞异常）；
+            // 等待期间新入队的不在本方法承诺内
+            await chain;
+        },
+    };
+}

package/dist/compaction/slots.js

@@ -0,0 +1,121 @@
+/**
+ * compaction 席位容器 + 接管缝归因铸造件（U4-3 装配批——05 §2.1 槽位化三层的
+ * 装载面装配件；动词词面真源 03 §2.2 第十二面/§2.7 两动词行）。
+ *
+ * 三件产物：
+ *  - **席位容器**（createCompactionSlots）：配置槽 + 摘要 provider 槽的单席位
+ *    状态机（先到占 / 他插件后到拒 / 同席位者可更新 / 卸载回收）。host 装配根
+ *    单真身：conversation-stack 消费 getConfig/getProvider（服务面三 seam 之
+ *    二的容器位），plugin-boot 逐插件 fork 绑定 bindForPlugin 产物（经
+ *    ctx.get("compaction") 消费）。本模块零 context 边——窗口真源由装配层注入
+ *    （inLoadWindow 回调，绑本插件 handle）。
+ *  - **归因箱 + 记名/铸造两律**（BEFORE_COMPACT_ATTRIB / mark / forge）：
+ *    session_before_compact 值链的逐跳归因机制件——plugin-context 钩子包装层
+ *    消费（值链改写者记名 + takeover.pluginId 强制覆写，冒名结构性不存在）；
+ *    conversation-stack 派发包装层种子箱读末位。symbol 键经对象 spread 天然
+ *    随值链传播（改写必新建对象——引用比较判改写的服务面约定同源）。
+ */
+import { BaseError } from '../contracts/index.js';
+import { DEFAULT_COMPACTION_CONFIG } from './types.js';
+/**
+ * 归因箱值链键（unique symbol——模块外不可字面伪造）：宿主种子在载荷对象上，
+ * 插件改写值必经 spread/新建（「值链改写必新建对象」律），spread 复制 symbol
+ * 键属性 → 箱引用沿链共享。非接管缝的 waterfall 值不携带本键——记名/铸造
+ * 两律对其零接触（通用包装层的机制件消费位判据）。
+ */
+export const BEFORE_COMPACT_ATTRIB = Symbol('session-before-compact-attribution');
+/**
+ * 记名律：监听者改写值链时记末位改写者（plugin-context 钩子包装层逐跳调用）。
+ * 箱缺席 = 非接管缝值链——no-op（通用 waterfall 不受影响）。残余面：插件在
+ * handler 体内直改箱内容而不改值可伪记他名——末位真改写者必覆写之，且该
+ * 归因仅 fallback 记账审计面（非权限面），残余可受。
+ */
+export function markBeforeCompactRewrite(value, pluginId) {
+    if (typeof value !== 'object' || value === null)
+        return;
+    const box = value[BEFORE_COMPACT_ATTRIB];
+    if (typeof box === 'object' && box !== null) {
+        box.lastAdjustedBy = pluginId;
+    }
+}
+/**
+ * 铸造律：takeover.pluginId 由宿主钩子包装层强制覆写为本监听者（03 §2.4 行
+ * 「归因铸造」/05 §2.1——e-4 caller 闭包同律，插件自填被覆写）。执法判据 =
+ * **接管位引用换**（produced.takeover !== received.takeover——「值链改写必
+ * 新建对象」律同源）：本监听者新置/重建接管位才覆写；原引用透传（含改写
+ * 他位而保留接管对象引用的 spread 形）不覆写——防下游误夺上游接管归因。
+ * 只在携带归因箱的值上执法（非接管缝值链零接触）；takeover 位缺席 = 纯改
+ * 写/放行，原值直返不改引用。
+ */
+export function forgeBeforeCompactIdentity(produced, received, pluginId) {
+    if (typeof produced !== 'object' || produced === null)
+        return produced;
+    const record = produced;
+    if (record[BEFORE_COMPACT_ATTRIB] === undefined)
+        return produced; // 非接管缝值链——零接触
+    const takeover = record['takeover'];
+    if (typeof takeover !== 'object' || takeover === null)
+        return produced; // 无接管位——原值直返
+    // 上游接管位原引用透传——非本监听者所置，不覆写
+    const prev = typeof received === 'object' && received !== null
+        ? received['takeover']
+        : undefined;
+    if (takeover === prev)
+        return produced;
+    return { ...record, takeover: { ...takeover, pluginId } };
+}
+/**
+ * 组装席位容器（host 装配根单真身）。状态进程级内存态：/reload 卸载序经
+ * releaseFor 回收、重启清零——压缩配置非 durable 语义（缺省恒在场兜底）。
+ */
+export function createCompactionSlots(options = {}) {
+    const baseConfig = options.baseConfig ?? DEFAULT_COMPACTION_CONFIG;
+    let configSeat;
+    let providerSeat;
+    return {
+        getConfig() {
+            return { ...baseConfig, ...(configSeat?.partial ?? {}) };
+        },
+        getProvider() {
+            return providerSeat;
+        },
+        bindForPlugin({ pluginId, inLoadWindow }) {
+            /** 装载窗闸（严于通律——回调窗延伸不适用；窗真源 = 本插件 handle） */
+            const assertLoadWindow = (verb) => {
+                if (inLoadWindow())
+                    return;
+                throw new BaseError('PLUGIN_WINDOW_CLOSED', `注册动词 ${verb} 在装载窗口外被拒（插件 ${pluginId}——03 §2.2 第十二面：压缩策略面两动词装载窗 only 严于通律，回调窗延伸不适用〔装配期配置/注册动作非回调场景动作〕）`);
+            };
+            return {
+                setConfig(partial) {
+                    assertLoadWindow('ctx.compaction.setConfig');
+                    if (configSeat !== undefined && configSeat.pluginId !== pluginId) {
+                        throw new BaseError('COMPACTION_CONFIG_TAKEN', `数值配置槽已被插件 ${configSeat.pluginId} 占据（插件 ${pluginId} 后到拒——单席位先到占；配置主权单源，两插件各设阈值 = 用户装配面错误，fail-loud 拒不静默 last-wins）`);
+                    }
+                    configSeat = { pluginId, partial };
+                    return () => {
+                        if (configSeat?.pluginId === pluginId)
+                            configSeat = undefined; // 幂等：只摘自己（后设者不误伤）
+                    };
+                },
+                registerSummarizer(fn) {
+                    assertLoadWindow('ctx.compaction.registerSummarizer');
+                    if (providerSeat !== undefined && providerSeat.pluginId !== pluginId) {
+                        throw new BaseError('COMPACTION_SUMMARIZER_TAKEN', `摘要 provider 槽已被插件 ${providerSeat.pluginId} 占据（插件 ${pluginId} 后到拒——单席位先到占；溢出兜底恒宿主缺省算法，槽不可及）`);
+                    }
+                    providerSeat = { pluginId, fn };
+                    return () => {
+                        if (providerSeat?.pluginId === pluginId)
+                            providerSeat = undefined;
+                    };
+                },
+            };
+        },
+        releaseFor(pluginId) {
+            if (configSeat?.pluginId === pluginId)
+                configSeat = undefined;
+            if (providerSeat?.pluginId === pluginId)
+                providerSeat = undefined;
+        },
+    };
+}

package/dist/compaction/types.js

@@ -0,0 +1,10 @@
+/** 缺省配置（05 §2.1「摘要参数」+「防抖三件」+「阈值」段定值——首版实测后调） */
+export const DEFAULT_COMPACTION_CONFIG = {
+    thresholdRatio: 0.5,
+    tailKeep: 6,
+    cooldownMs: 600_000,
+    summaryRatio: 0.2,
+    summaryMinChars: 2000,
+    summaryMaxChars: 12000,
+    fallbackWindowTokens: 200_000,
+};

package/dist/context/codes.js

@@ -0,0 +1,40 @@
+/**
+ * context 模块错误码注册（02 §5.3 #2：各模块落码批经 registerErrorCodes 显式注册，
+ * 禁字符串字面量散落）。
+ *
+ * 域码族注记：EVENT_* / SCOPE_* 系 04 §6 定名的域语义命名（事件面/作用域面），
+ * 视同 CONTEXT_ 域族成员（02 §5.3 前缀族注记，2026-09-05 落码批）。
+ */
+import { registerErrorCodes } from '../contracts/index.js';
+registerErrorCodes([
+    {
+        code: 'EVENT_NOT_REGISTERED',
+        module: 'context',
+        description: 'ctx.emit/on 未注册词 fail-loud（词汇注册表单源——禁散播未声明事件名）',
+    },
+    {
+        code: 'EVENT_DUPLICATE',
+        module: 'context',
+        description: '事件词汇撞名拒静默覆盖（注册表单源执法）',
+    },
+    {
+        code: 'SCOPE_STALE',
+        module: 'context',
+        description: '作用域已回卷后的迟到操作（迟到的服务注册/disposer 登记拒绝——异步竞速收口）',
+    },
+    {
+        code: 'SCOPE_EFFECT_CAPACITY',
+        module: 'context',
+        description: 'effect 总注册帽：本作用域自有登记达 10^4 拒新登记（03 §3.4 可用性防线——失控登记不拖垮回卷序；拒在 register 回调执行前）',
+    },
+    {
+        code: 'CONTEXT_SERVICE_MISSING',
+        module: 'context',
+        description: 'get 缺席 fail-loud（拼错名立即炸，不静默 undefined 传播；可选消费走 tryGet）',
+    },
+    {
+        code: 'CONTEXT_SERVICE_DUPLICATE',
+        module: 'context',
+        description: '同作用域 provide 撞名拒（两方抢一名即装配 bug；fork 子遮蔽父合法）',
+    },
+]);