dsh-prime-memory 0.18.2 → 0.19.0

package/dist/hooks/capture-recovery.d.ts

@@ -0,0 +1,59 @@
+/**
+ * §A 崩溃恢复 · 折叠纯函数(memorax-absorb Wave 1 / task_6)。
+ *
+ * 宿主在 turn 中途崩溃时,插件的内存缓冲丢失、该轮永不落 L0——但事件日志就在
+ * 宿主持久化层里,且 persistence 会在 reload 时给崩溃孤儿轮补写
+ * `turn/end{reason:'interrupted'}` 闭合标记(运行期实证:本机 98 处,
+ * 见计划 evidence/probe-runtime.json)。resume 时对账 `(水位线, 末尾]` 内
+ * bracket 完整的 turn,经 capture 的正常路径落 L0 + 蒸馏。
+ *
+ * 本模块只做**纯折叠**:events in → bracket 列表 out,零 I/O、零时钟、零随机。
+ * 幂等(水位线 + 逐 turn 存在性检查)与 off 档排除在调用方(capture.ts 接线层)。
+ *
+ * 切片语义与 CaptureBuffers.takeTurn 对齐:含 turn/end、不含 turn/start
+ * (turn/start 与 turn/end 本身不产消息,与既有转换器的类型过滤一致)。
+ */
+import type { SessionEvent } from '@deepseek-ai/dsh-session';
+/** 一个可恢复的完整轮次括号;events 为 (startSeq, endSeq] 切片。 */
+export interface RecoveredTurn {
+    turn: number;
+    startSeq: number;
+    endSeq: number;
+    events: SessionEvent[];
+}
+export interface FoldOptions {
+    /** 最多恢复的轮数(取最靠尾的 N 个);缺省 2——只补尾轮,非历史倾倒。 */
+    maxTurns?: number;
+}
+/**
+ * 从持久化事件日志折叠出可恢复轮次。
+ *
+ * - **bracket 完整性**:只有 `turn/start(T) … turn/end(T)` 成对(任意 reason——
+ *   interrupted 与 completed 同等对待,插件停机期间宿主正常完成的轮次同样缺 L0)才入选;
+ *   未闭合 tail 跳过(宿主 reload 补闭合后,下次 resume 自然纳入)。
+ * - **水位线窗口**:只取 `turn > watermark`(watermark=undefined 视为会话 L0 全空,
+ *   全部入选)。
+ * - **上限**:按 turn 取最靠尾的 `maxTurns`(缺省 2)个,返回按 startSeq 升序
+ *   (调用方按序落 L0,保持时序)。
+ * - **防御**:输入乱序时按 seq 稳定排序;同 turn 重复 bracket(代际文件重叠等畸形)
+ *   保留 endSeq 更晚的一个;`data.turn` 非有限数字的括号一律不折叠。
+ */
+export declare function foldRecoverableTurns(events: readonly SessionEvent[], watermark: number | undefined, opts?: FoldOptions): RecoveredTurn[];
+/**
+ * 宿主读日志服务的最小结构形状。真实类型随宿主版本漂移(compat 0.1.1-rc.2 与
+ * 检出主线已是两代 API),故只做**结构探针**——方法存在才调,逐级 try/catch。
+ */
+export interface HostRecoveryServices {
+    sessionQuery?: unknown;
+    sessionPersistence?: unknown;
+}
+/**
+ * task_8 降级链:`agent.session.events` 不可得时,依次尝试
+ * ① `ctx.sessionQuery.readSession(id)`(live 或 persisted 均可,返回完整原始日志);
+ * ② `ctx.sessionPersistence.readFrom(id, 0)`(按 seq 范围读,0 = 从头取全量——
+ *    水位线以 turn 计,无 seq 对应,全量交由 fold + 上限 2 收敛)。
+ *
+ * 返回 undefined = 两级均不可用/均失败(调用方走一次性提示 + 维持现状)。
+ * 守卫纪律与 recall.ts 的 loadStored 探针一致:不假设方法存在,失败静默降级。
+ */
+export declare function readPersistedEventsViaServices(svcs: HostRecoveryServices, sessionId: string): SessionEvent[] | undefined;

package/dist/hooks/capture-recovery.js

@@ -0,0 +1,88 @@
+function turnOf(event) {
+    const t = event.data?.turn;
+    return typeof t === 'number' && Number.isFinite(t) ? t : undefined;
+}
+/**
+ * 从持久化事件日志折叠出可恢复轮次。
+ *
+ * - **bracket 完整性**:只有 `turn/start(T) … turn/end(T)` 成对(任意 reason——
+ *   interrupted 与 completed 同等对待,插件停机期间宿主正常完成的轮次同样缺 L0)才入选;
+ *   未闭合 tail 跳过(宿主 reload 补闭合后,下次 resume 自然纳入)。
+ * - **水位线窗口**:只取 `turn > watermark`(watermark=undefined 视为会话 L0 全空,
+ *   全部入选)。
+ * - **上限**:按 turn 取最靠尾的 `maxTurns`(缺省 2)个,返回按 startSeq 升序
+ *   (调用方按序落 L0,保持时序)。
+ * - **防御**:输入乱序时按 seq 稳定排序;同 turn 重复 bracket(代际文件重叠等畸形)
+ *   保留 endSeq 更晚的一个;`data.turn` 非有限数字的括号一律不折叠。
+ */
+export function foldRecoverableTurns(events, watermark, opts) {
+    const maxTurns = opts?.maxTurns ?? 2;
+    const sorted = [...events].sort((a, b) => (a.seq ?? 0) - (b.seq ?? 0));
+    const open = new Map();
+    const brackets = [];
+    for (let i = 0; i < sorted.length; i++) {
+        const event = sorted[i];
+        if (event.type === 'turn/start') {
+            const turn = turnOf(event);
+            if (turn !== undefined)
+                open.set(turn, { startSeq: event.seq, startIdx: i });
+        }
+        else if (event.type === 'turn/end') {
+            const turn = turnOf(event);
+            const start = turn !== undefined ? open.get(turn) : undefined;
+            if (turn === undefined || start === undefined)
+                continue;
+            open.delete(turn);
+            brackets.push({
+                turn,
+                startSeq: start.startSeq,
+                endSeq: event.seq,
+                events: sorted.slice(start.startIdx + 1, i + 1),
+            });
+        }
+    }
+    const eligible = brackets.filter((b) => watermark === undefined || b.turn > watermark);
+    const byTurn = new Map();
+    for (const b of eligible) {
+        const prev = byTurn.get(b.turn);
+        if (prev === undefined || b.endSeq >= prev.endSeq)
+            byTurn.set(b.turn, b);
+    }
+    return [...byTurn.values()].sort((a, b) => a.turn - b.turn).slice(-maxTurns).sort((a, b) => a.startSeq - b.startSeq);
+}
+/**
+ * task_8 降级链:`agent.session.events` 不可得时,依次尝试
+ * ① `ctx.sessionQuery.readSession(id)`(live 或 persisted 均可,返回完整原始日志);
+ * ② `ctx.sessionPersistence.readFrom(id, 0)`(按 seq 范围读,0 = 从头取全量——
+ *    水位线以 turn 计,无 seq 对应,全量交由 fold + 上限 2 收敛)。
+ *
+ * 返回 undefined = 两级均不可用/均失败(调用方走一次性提示 + 维持现状)。
+ * 守卫纪律与 recall.ts 的 loadStored 探针一致:不假设方法存在,失败静默降级。
+ */
+export function readPersistedEventsViaServices(svcs, sessionId) {
+    const accepts = (r) => r !== null && typeof r === 'object' && Array.isArray(r.events) &&
+        r.events.length > 0;
+    const q = svcs.sessionQuery;
+    if (q !== null && typeof q === 'object' && typeof q.readSession === 'function') {
+        try {
+            const result = q.readSession(sessionId);
+            if (accepts(result))
+                return result.events;
+        }
+        catch {
+            /* 落到下一级 */
+        }
+    }
+    const p = svcs.sessionPersistence;
+    if (p !== null && typeof p === 'object' && typeof p.readFrom === 'function') {
+        try {
+            const result = p.readFrom(sessionId, 0);
+            if (accepts(result))
+                return result.events;
+        }
+        catch {
+            /* 均不可用 */
+        }
+    }
+    return undefined;
+}

package/dist/hooks/capture.js

@@ -6,7 +6,32 @@
  */
 import { randomBytes } from 'node:crypto';
 import { blocksToText } from '../util/text.js';
+import { redactSecrets } from '../util/redact.js';
 import { sanitizeText, shouldCaptureL0, stripCodeBlocks } from '../util/sanitize.js';
+import { foldRecoverableTurns, readPersistedEventsViaServices } from './capture-recovery.js';
+import { confirmInjectionByMessageId } from './recall-ack.js';
+/** §C 一次性告警标记:脱敏自身异常时放行原文,只提示一次(不阻断捕获)。 */
+let redactWarnedOnce = false;
+/**
+ * §C 捕获单点脱敏(memorax-absorb):`capture.redactSecrets !== false` 时把
+ * 8 类密钥替换为 `[REDACTED:<KIND>]`。位置在 sanitize 之后、L0/蒸馏分发之前——
+ * 同一份 messages 覆盖 L0 JSONL/L0 SQLite/蒸馏输入三条下游,无分裂态。
+ * 红线:脱敏失败放行原文 + 一次性 warn(不阻断捕获)。
+ */
+function redactContent(content, cfg, logger) {
+    if (cfg.capture?.redactSecrets === false)
+        return content;
+    try {
+        return redactSecrets(content).text;
+    }
+    catch (err) {
+        if (!redactWarnedOnce) {
+            redactWarnedOnce = true;
+            logger.warn(`[memory] 脱敏失败,本轮放行原文(一次性提示): ${err instanceof Error ? err.message : String(err)}`);
+        }
+        return content;
+    }
+}
 /**
  * 需要进缓冲的事件类型。流式 chunk(text-delta/reasoning 等)一秒钟可达数百条,
  * 缓冲它们会把 MAX_BUFFER 撑爆、把轮次头部(turn/start + user 消息)裁掉——
@@ -70,6 +95,8 @@ export function registerCapture(ctx, cfg, runner, l0, logger, live, modes) {
         return;
     const startFloor = Date.now();
     const buffers = new CaptureBuffers();
+    // task_8 一次性提示标记:宿主读日志服务不可得时只提示一次(防每次 resume 刷屏)
+    let warnedRecoveryUnavailable = false;
     // L0 即时落盘链:turn/end 立刻写,不被蒸馏队列(慢 LLM 调用)阻塞;
     // 串行化保证同轮次顺序与单次写入(进程退出时排队中的 L0 不再依赖蒸馏完成)
     let l0Queue = Promise.resolve();
@@ -79,6 +106,15 @@ export function registerCapture(ctx, cfg, runner, l0, logger, live, modes) {
             if (!s.enabled || !s.capture)
                 return;
             const sid = String(session.id ?? session);
+            // §D 日志回执(memorax-absorb):注入消息以原样 user/message 入日志时在此确认,
+            // 才真正 dedupe.mark。**必须置于 source.kind 过滤之前**——过滤在
+            // turnEventsToMessages 内且只放行 kind='user',注入消息(kind='plugin:memory')
+            // 走不到那里;也置于 off 档返回之前(确认与档位无关,且代价是一次 Map 查找)。
+            if (event.type === 'user/message') {
+                const mid = event.data.id;
+                if (typeof mid === 'string' && mid)
+                    confirmInjectionByMessageId(mid);
+            }
             // off 档:本会话对记忆系统完全隐身(不缓冲、不写 L0、不蒸馏)
             if (modes.get(sid) === 'off')
                 return;
@@ -124,6 +160,78 @@ export function registerCapture(ctx, cfg, runner, l0, logger, live, modes) {
             logger.warn(`[memory] session/event 处理失败: ${err instanceof Error ? err.message : String(err)}`);
         }
     });
+    // ── §A 崩溃恢复(memorax-absorb Wave 1 / task_7):resume 时对账宿主持久化日志,
+    // 补收 (L0 水位线, 末尾] 内 bracket 完整的尾轮(≤2 轮)——崩溃轮在缓冲丢失后
+    // 仍可从持久化层找回(persistence 会给孤儿轮补 interrupted 闭合,探针② 实证 98 处)。
+    // fail-open 纪律:任何异常只 warn,不阻塞会话启动;幂等 = 水位线 + 逐 turn 存在性检查。
+    ctx.on('agent/created', async (payload) => {
+        try {
+            if (payload.source !== 'resume')
+                return;
+            const s = live.get();
+            if (!s.enabled || !s.capture)
+                return;
+            const session = payload.agent?.session;
+            const sid = session?.id !== undefined && session.id !== null ? String(session.id) : '';
+            if (!sid)
+                return;
+            const mode = modes.get(sid);
+            if (mode === 'off')
+                return; // off 档对记忆系统完全隐身,对齐现行为
+            let events = typeof session?.snapshotEvents === 'function' ? session.snapshotEvents() : undefined;
+            if (!events || events.length === 0) {
+                // task_8 降级链:events 不可得(宿主版本偏差)时依次试
+                // ctx.sessionQuery.readSession / ctx.sessionPersistence.readFrom(守卫探针式)
+                const get = ctx.get;
+                const svcs = typeof get === 'function'
+                    ? {
+                        sessionQuery: get.call(ctx, 'sessionQuery'),
+                        sessionPersistence: get.call(ctx, 'sessionPersistence'),
+                    }
+                    : {};
+                const degraded = readPersistedEventsViaServices(svcs, sid);
+                if (degraded === undefined) {
+                    if (!warnedRecoveryUnavailable) {
+                        warnedRecoveryUnavailable = true;
+                        logger.info('[memory] resume 恢复:宿主读日志服务不可得,跳过对账(一次性提示)');
+                    }
+                    return;
+                }
+                events = degraded;
+            }
+            const watermark = l0.maxCapturedTurn(sid);
+            const brackets = foldRecoverableTurns(events, watermark);
+            if (brackets.length === 0)
+                return;
+            let recovered = 0;
+            let skipped = 0;
+            let total = 0;
+            for (const bracket of brackets) {
+                if (l0.hasAnyL0Message(sid, bracket.turn)) {
+                    // 部分写残行:水位线只判"整轮无",存在性检查兜底——整轮跳过,宁少收不重复
+                    skipped += 1;
+                    continue;
+                }
+                const messages = turnEventsToMessages(bracket.events, cfg, logger, sid, bracket.turn);
+                if (messages.length === 0)
+                    continue;
+                recovered += 1;
+                total += messages.length;
+                const n = messages.length;
+                l0Queue = l0Queue
+                    .then(() => l0.append(sid, messages))
+                    .then(() => logger.info(`[memory] L0 恢复落盘 ${n} 条`))
+                    .catch((err) => logger.warn(`[memory] L0 恢复落盘失败: ${err instanceof Error ? err.message : String(err)}`));
+                runner.enqueue(sid, messages, mode);
+            }
+            if (recovered > 0 || skipped > 0) {
+                logger.info(`[memory] resume 对账:水位线 ${watermark ?? '无'} → 恢复 ${recovered} 轮 ${total} 条,幂等跳过 ${skipped} 轮(session=${sid})`);
+            }
+        }
+        catch (err) {
+            logger.warn(`[memory] resume 恢复失败(不阻塞会话启动): ${err instanceof Error ? err.message : String(err)}`);
+        }
+    });
     // 冲刷 = 等待串行链排空(链上每环自带 catch,永不 reject)。
     // 注:极小概率在 await 期间又入队的新消息会落到链尾——其 JSONL 事实源照写、
     // DB 写入由 upsert 内部兜底(关库后 warn),下次重建自愈。
@@ -190,7 +298,7 @@ function turnEventsToMessages(events, cfg, logger, sessionId, turn) {
                 logger.info(`[memory] L0 跳过非用户来源消息(source.kind=${msg.source?.kind ?? 'none'})`);
                 continue;
             }
-            const content = sanitizeText(blocksToText(msg.content));
+            const content = redactContent(sanitizeText(blocksToText(msg.content)), cfg, logger);
             if (shouldCaptureL0(content)) {
                 const anchor = { sessionId, turn };
                 if (currentStep !== undefined)
@@ -203,6 +311,7 @@ function turnEventsToMessages(events, cfg, logger, sessionId, turn) {
             let content = sanitizeText(blocksToText(data.message?.content));
             if (cfg.capture.stripCodeBlocks)
                 content = stripCodeBlocks(content);
+            content = redactContent(content, cfg, logger);
             if (shouldCaptureL0(content)) {
                 // 事件自带 turn/step 优先(fold 只服务于不带该字段的事件类型)
                 const evTurn = typeof data.turn === 'number' && Number.isFinite(data.turn) ? data.turn : turn;

package/dist/hooks/recall-ack.d.ts

@@ -0,0 +1,48 @@
+/**
+ * §D 注入确认——日志回执协议(memorax-absorb Wave 3 / task_20-22)。
+ *
+ * 问题:`dedupe.mark` 原在 pre-step 返回注入的瞬间执行,但宿主是否真的把该
+ * 注入消息收进会话历史,此时并未确认(pre-step 被其他插件覆盖/步骤取消时,
+ * 模型根本没看到)——误标记会把这些记忆压制整个会话。
+ *
+ * 协议(两段式):
+ *  ① recall.ts 构造注入消息后只登记 pending(messageId → 记录 id 集),不标记;
+ *  ② capture.ts 在 `session/event` 观察到该 `user/message` 真正入日志时确认,
+ *     此时才 `dedupe.mark`(与 §D 红线一致:确认匹配在 source.kind 过滤之前——
+ *     注入消息的 source.kind 是 `plugin:memory`,放过滤后永远到不了匹配)。
+ *
+ * 超时降级(task_22):pending 超 5 分钟未确认 → 照旧标记 + 一次性提示。
+ * 防确认链路自身故障导致 dedupe 永不生效、记忆每轮重注的回归;正常确认时延
+ * <2s(同进程事件循环)。未确认且未超时的 pending 过期即弃(不标记)——
+ * 模型没看到的东西不应被抑制,允许下轮重注。
+ *
+ * 进程内 volatile,容量 64 条 LRU(注入速率低,正常情况秒级确认,积压即异常)。
+ */
+export interface PendingInjection {
+    agentId: string;
+    messageId: string;
+    recordIds: string[];
+    at: number;
+}
+/** 确认后执行的实际标记动作(recall.ts 注入 = dedupe.mark 的绑定)。 */
+type InjectionMarker = (agentId: string, recordIds: string[]) => void;
+export declare const PENDING_TIMEOUT_MS: number;
+/** recall.ts 注册实际标记动作(dedupe.mark 绑定);重复注册以最后一次为准。 */
+export declare function setInjectionMarker(fn: InjectionMarker): void;
+/** ① 登记待确认注入(超容量淘汰最旧——积压到 64 条说明确认链路已异常)。 */
+export declare function registerPendingInjection(agentId: string, messageId: string, recordIds: string[], now?: number): void;
+/**
+ * ② 日志回执确认:该注入消息已真实进入会话历史。执行标记并移除 pending。
+ * @returns 是否命中一条 pending(未命中 = 与本插件注入无关的事件,静默)。
+ */
+export declare function confirmInjectionByMessageId(messageId: string): boolean;
+/**
+ * 超时清扫:超时的 pending 照旧标记(降级保连续,防 dedupe 失效回归),并移除。
+ * 未超时的不动。@returns 本次降级标记的条数(recall 侧据此前瞻性提示一次)。
+ */
+export declare function expirePendingInjections(now?: number, timeoutMs?: number): number;
+/** 诊断/测试:当前 pending 条数。 */
+export declare function pendingCount(): number;
+/** 测试隔离:清空 pending 与 marker(模块级状态,用例间互扰)。 */
+export declare function resetAckForTests(): void;
+export {};

package/dist/hooks/recall-ack.js

@@ -0,0 +1,79 @@
+/**
+ * §D 注入确认——日志回执协议(memorax-absorb Wave 3 / task_20-22)。
+ *
+ * 问题:`dedupe.mark` 原在 pre-step 返回注入的瞬间执行,但宿主是否真的把该
+ * 注入消息收进会话历史,此时并未确认(pre-step 被其他插件覆盖/步骤取消时,
+ * 模型根本没看到)——误标记会把这些记忆压制整个会话。
+ *
+ * 协议(两段式):
+ *  ① recall.ts 构造注入消息后只登记 pending(messageId → 记录 id 集),不标记;
+ *  ② capture.ts 在 `session/event` 观察到该 `user/message` 真正入日志时确认,
+ *     此时才 `dedupe.mark`(与 §D 红线一致:确认匹配在 source.kind 过滤之前——
+ *     注入消息的 source.kind 是 `plugin:memory`,放过滤后永远到不了匹配)。
+ *
+ * 超时降级(task_22):pending 超 5 分钟未确认 → 照旧标记 + 一次性提示。
+ * 防确认链路自身故障导致 dedupe 永不生效、记忆每轮重注的回归;正常确认时延
+ * <2s(同进程事件循环)。未确认且未超时的 pending 过期即弃(不标记)——
+ * 模型没看到的东西不应被抑制,允许下轮重注。
+ *
+ * 进程内 volatile,容量 64 条 LRU(注入速率低,正常情况秒级确认,积压即异常)。
+ */
+const PENDING_CAP = 64;
+export const PENDING_TIMEOUT_MS = 5 * 60_000;
+const pending = new Map();
+let marker;
+/** recall.ts 注册实际标记动作(dedupe.mark 绑定);重复注册以最后一次为准。 */
+export function setInjectionMarker(fn) {
+    marker = fn;
+}
+/** ① 登记待确认注入(超容量淘汰最旧——积压到 64 条说明确认链路已异常)。 */
+export function registerPendingInjection(agentId, messageId, recordIds, now = Date.now()) {
+    if (!messageId || recordIds.length === 0)
+        return;
+    pending.delete(messageId); // 同 id 重登记 = 刷新(置尾)
+    pending.set(messageId, { agentId, messageId, recordIds, at: now });
+    while (pending.size > PENDING_CAP) {
+        const oldest = pending.keys().next().value;
+        if (oldest === undefined)
+            break;
+        pending.delete(oldest);
+    }
+}
+/**
+ * ② 日志回执确认:该注入消息已真实进入会话历史。执行标记并移除 pending。
+ * @returns 是否命中一条 pending(未命中 = 与本插件注入无关的事件,静默)。
+ */
+export function confirmInjectionByMessageId(messageId) {
+    const entry = pending.get(messageId);
+    if (!entry)
+        return false;
+    pending.delete(messageId);
+    marker?.(entry.agentId, entry.recordIds);
+    return true;
+}
+/**
+ * 超时清扫:超时的 pending 照旧标记(降级保连续,防 dedupe 失效回归),并移除。
+ * 未超时的不动。@returns 本次降级标记的条数(recall 侧据此前瞻性提示一次)。
+ */
+export function expirePendingInjections(now = Date.now(), timeoutMs = PENDING_TIMEOUT_MS) {
+    if (pending.size === 0)
+        return 0;
+    let expired = 0;
+    for (const [key, entry] of pending) {
+        if (now - entry.at <= timeoutMs)
+            continue;
+        pending.delete(key);
+        marker?.(entry.agentId, entry.recordIds);
+        expired += 1;
+    }
+    return expired;
+}
+/** 诊断/测试:当前 pending 条数。 */
+export function pendingCount() {
+    return pending.size;
+}
+/** 测试隔离:清空 pending 与 marker(模块级状态,用例间互扰)。 */
+export function resetAckForTests() {
+    pending.clear();
+    marker = undefined;
+}

package/dist/hooks/recall.d.ts

@@ -41,6 +41,25 @@ export declare function isOwnRecallSource(src: {
 export declare function buildRecallQuery(messages: Array<{
     content: unknown;
 }>, tailMessages?: number, maxChars?: number): string;
+/**
+ * §E 压缩感知标记器(memorax-absorb / task_24-26):记录刚完成压缩的会话,
+ * pre-step 消费后做一次性增强召回。纯内存状态,CaptureBuffers 同款可单测导出。
+ *
+ * - `onCompactionEnd`:只认无 error 的 compaction/end(失败的压缩没有把内容逐出上下文);
+ * - `consume`:消费即清(一次性增强);容量上限淘汰最旧(积压即异常,回退路径兜底)。
+ */
+export declare class PostCompactionTracker {
+    private readonly cap;
+    private readonly map;
+    constructor(cap?: number);
+    /** @returns 是否真的置了标记(false = 非 compaction/end 或带 error)。 */
+    onCompactionEnd(sessionId: string, data?: {
+        error?: unknown;
+    }): boolean;
+    /** 消费该会话的增强标记(存在即清,返回是否存在)。 */
+    consume(sessionId: string): boolean;
+    get size(): number;
+}
 /** 单会话召回统计(悬浮卡信息区数据源;每轮 O(1) 记账,agent/disposed 清理)。
  *  口径声明:这是"注入统计"而非 bench 的离线 recall@k——运行时没有 ground truth,
  *  命中率 = hitTurns / injectedTurns。去重语义:全量压制轮计入 hitTurns

package/dist/hooks/recall.js

@@ -1,6 +1,9 @@
 import { createUserMessage } from '@deepseek-ai/dsh-llm';
+import { createHash } from 'node:crypto';
+import { trace } from '../store/trace.js';
 import { RecallDedupeStore } from '../store/recall-dedupe.js';
 import { OccupancyStore } from '../store/occupancy.js';
+import { expirePendingInjections, registerPendingInjection, setInjectionMarker, } from './recall-ack.js';
 import { scopeFilterOf } from '../workspace.js';
 import { applyRecallBudget, raceRecallTimeout, RECALL_EMBED_CAP_MS } from '../util/recall-budget.js';
 import { clearProfileShare, emptyOccupancyLedger, estimateInjectedMessageTokens, estimateStableSectionTokens, recordProfileShare, recordRecallInjection, resetForCompaction, } from '../util/context-occupancy.js';
@@ -42,6 +45,43 @@ export function buildRecallQuery(messages, tailMessages = RECALL_QUERY_TAIL_MESS
         text = text.slice(-maxChars);
     return text;
 }
+/**
+ * §E 压缩感知标记器(memorax-absorb / task_24-26):记录刚完成压缩的会话,
+ * pre-step 消费后做一次性增强召回。纯内存状态,CaptureBuffers 同款可单测导出。
+ *
+ * - `onCompactionEnd`:只认无 error 的 compaction/end(失败的压缩没有把内容逐出上下文);
+ * - `consume`:消费即清(一次性增强);容量上限淘汰最旧(积压即异常,回退路径兜底)。
+ */
+export class PostCompactionTracker {
+    cap;
+    map = new Map();
+    constructor(cap = 64) {
+        this.cap = cap;
+    }
+    /** @returns 是否真的置了标记(false = 非 compaction/end 或带 error)。 */
+    onCompactionEnd(sessionId, data) {
+        if (!sessionId || data?.error)
+            return false;
+        this.map.delete(sessionId); // 置尾刷新
+        this.map.set(sessionId, true);
+        while (this.map.size > this.cap) {
+            const oldest = this.map.keys().next().value;
+            if (oldest === undefined)
+                break;
+            this.map.delete(oldest);
+        }
+        return true;
+    }
+    /** 消费该会话的增强标记(存在即清,返回是否存在)。 */
+    consume(sessionId) {
+        if (!this.map.delete(sessionId))
+            return false;
+        return true;
+    }
+    get size() {
+        return this.map.size;
+    }
+}
 const MEMORY_TOOLS_GUIDE = `<memory-tools-guide>
 ## 记忆工具调用指南
 
@@ -160,10 +200,25 @@ export function registerRecall(ctx, cfg, stores, logger, live, modes, dataDir) {
         recallStats.delete(payload.agent.id);
         occupancyByAgent.delete(payload.agent.id);
     });
+    // §D:绑定实际标记动作 + 超时清扫挂到 pre-step 入口(见注入点注释)。
+    setInjectionMarker((agentId, recordIds) => dedupe.mark(agentId, recordIds));
+    let ackDegradeWarned = false;
+    // §E 压缩感知(memorax-absorb):宿主 `compaction/end`(无 error)→ 该会话下一轮
+    // 做一次"定向增强召回"——跳过去重压制、画像立即重注入、占用账本归零;消费即清。
+    // 会话级回退路径保留(下方 session-start source='compact' 全量重置),两者幂等。
+    // 宿主无压缩计数器(compactionId 为 per-transaction UUID),故不做 generation 对账。
+    const postCompaction = new PostCompactionTracker();
+    ctx.on('session/event', (session, event) => {
+        if (event.type !== 'compaction/end')
+            return;
+        if (postCompaction.onCompactionEnd(String(session.id ?? session))) {
+            logger.info(`[memory] compaction/end:下一轮将做一次增强召回(session=${String(session.id ?? session)})`);
+        }
+    });
     // 上下文压缩/清空 → 已注入内容从模型上下文丢失,重置该会话的去重压制
     // (resume/startup 不重置:历史仍在,已注入的记忆模型还持有)。
     // 占用账本同步全量归零(宁低勿高;轮级粒度近似)。
-    ctx.on('agent/session-start', (payload) => {
+    ctx.on('agent/created', async (payload) => {
         if (payload.source === 'compact' || payload.source === 'clear') {
             dedupe.reset(payload.agent.id);
             const led = ledgerFor(payload.agent.id);
@@ -205,6 +260,13 @@ export function registerRecall(ctx, cfg, stores, logger, live, modes, dataDir) {
     // prepend 注册 + 先 next() 再改写:不劫持其他监听器(dsh-time-context 官方范式)。
     if (cfg.recall.enabled) {
         ctx.on('agent/pre-step', async (payload, next) => {
+            // §D 超时清扫:超时未确认的注入照旧标记(降级保连续,防 dedupe 失效回归);
+            // 正常确认在秒级完成,这里只是兜底。一次性提示。
+            const expiredAcks = expirePendingInjections();
+            if (expiredAcks > 0 && !ackDegradeWarned) {
+                ackDegradeWarned = true;
+                logger.warn(`[memory] 注入确认:${expiredAcks} 条 pending 超时未回执,已降级为照常标记(一次性提示)`);
+            }
             const decision = await next();
             if (decision.kind === 'reject' || payload.signal.aborted)
                 return decision;
@@ -220,6 +282,17 @@ export function registerRecall(ctx, cfg, stores, logger, live, modes, dataDir) {
                 const hasNewUserMessage = decision.messages.some((m) => m.source?.kind === 'user');
                 if (!hasNewUserMessage)
                     return decision;
+                // §E 消费增强标记:压缩后下一轮跳过去重压制(预算/档位/门控照常),
+                // 画像 TTL 失效立即重注入,占用账本归零。消费即清(一次性)。
+                const sessionKey = String(payload.agent.session?.id ?? payload.agent.id);
+                const boosted = postCompaction.consume(sessionKey);
+                if (boosted) {
+                    invalidateProfile();
+                    const led = ledgerFor(payload.agent.id);
+                    resetForCompaction(led);
+                    occupancyStore.save(payload.agent.id, led);
+                    logger.info(`[memory] 压缩后增强召回:本轮跳过去重压制 + 画像重注入(session=${sessionKey})`);
+                }
                 const query = buildRecallQuery(payload.messages);
                 // 空查询是退化轮(无用户文本),重置命中信号但不计入统计
                 if (!query) {
@@ -227,6 +300,10 @@ export function registerRecall(ctx, cfg, stores, logger, live, modes, dataDir) {
                     degenerate.lastHits = 0;
                     return decision;
                 }
+                // §F 追踪字段:metadata-only 默认(chars+sha256 前 16),captureContent 才存原文
+                const queryChars = query.length;
+                const querySha = createHash('sha256').update(query).digest('hex').slice(0, 16);
+                const queryText = cfg.trace?.captureContent === true ? query.slice(0, 200) : undefined;
                 const st = statFor(payload.agent.id);
                 st.injectedTurns++;
                 st.lastHits = 0;
@@ -245,6 +322,11 @@ export function registerRecall(ctx, cfg, stores, logger, live, modes, dataDir) {
                 if (hits === undefined) {
                     st.timeouts++;
                     logger.warn('[memory] 召回超时,跳过本轮注入(不阻塞对话)');
+                    trace({
+                        kind: 'recall_turn', ts: Date.now(), sessionId: sessionKey, queryChars, querySha, queryText,
+                        hitIds: [], hitScores: [], injectedIds: [], suppressedCount: 0,
+                        durationMs: Date.now() - searchStart, outcome: 'timeout',
+                    });
                     return decision;
                 }
                 st.lastDurationMs = Date.now() - searchStart;
@@ -275,7 +357,8 @@ export function registerRecall(ctx, cfg, stores, logger, live, modes, dataDir) {
                 }
                 // 召回去重:同会话已注入过的记录不再重复注入(模型上下文已持有,省 token)。
                 // 纯过滤——剩几条注几条,全量压制(0 条新鲜命中)是正确状态而非未命中。
-                const seen = dedupe.seen(payload.agent.id);
+                // §E:压缩后增强轮跳过压制(压缩把已注入内容逐出了模型上下文)。
+                const seen = boosted ? new Set() : dedupe.seen(payload.agent.id);
                 const fresh = scoped.filter((h) => !seen.has(h.id));
                 const suppressed = scoped.length - fresh.length;
                 st.suppressedRecalls += suppressed;
@@ -287,13 +370,27 @@ export function registerRecall(ctx, cfg, stores, logger, live, modes, dataDir) {
                     st.hitTurns++;
                     st.totalHits += fresh.length;
                 }
-                if (fresh.length === 0)
+                if (fresh.length === 0) {
+                    // §F 追踪:全量压制轮——零注入是正确状态,如实记录
+                    trace({
+                        kind: 'recall_turn', ts: Date.now(), sessionId: sessionKey, queryChars, querySha, queryText,
+                        hitIds: scoped.map((h) => h.id), hitScores: scoped.map((h) => Number(h.score.toFixed(4))),
+                        injectedIds: [], suppressedCount: scoped.length - fresh.length,
+                        durationMs: Date.now() - searchStart, outcome: 'suppressed',
+                    });
                     return decision;
+                }
                 const lines = applyRecallBudget(fresh.map((h) => `- [${h.scene_name ? `${h.type}|${h.scene_name}` : h.type}] ${h.content}`), { maxCharsPerMemory: cfg.recall.maxCharsPerMemory, maxTotalRecallChars: cfg.recall.maxTotalRecallChars });
-                if (lines.length === 0)
+                if (lines.length === 0) {
+                    // §F 追踪:预算清零轮(截断后无完整行)
+                    trace({
+                        kind: 'recall_turn', ts: Date.now(), sessionId: sessionKey, queryChars, querySha, queryText,
+                        hitIds: fresh.map((h) => h.id), hitScores: fresh.map((h) => Number(h.score.toFixed(4))),
+                        injectedIds: [], suppressedCount: scoped.length - fresh.length,
+                        durationMs: Date.now() - searchStart, outcome: 'suppressed',
+                    });
                     return decision;
-                // 预算截断只丢尾部(前缀保留):实际注入 = fresh 的前 lines.length 条——只标记模型真实看到的
-                dedupe.mark(payload.agent.id, fresh.slice(0, lines.length).map((h) => h.id));
+                }
                 st.lastHits = lines.length;
                 const text = [
                     '<relevant-memories>',
@@ -312,6 +409,18 @@ export function registerRecall(ctx, cfg, stores, logger, live, modes, dataDir) {
                     // v3 旧行(kind:'plugin'+plugin 字段)由宿主 v3→v4 迁移升格,读侧双形状兼容。
                     source: { kind: 'plugin:memory', form: 'recall' },
                 });
+                // §D 注入确认(memorax-absorb):宿主接受 enter 后,注入消息以原样
+                // `user/message` 进入会话日志(message.id 稳定保留)——capture 侧观察到
+                // 该 id 才真正 dedupe.mark(recall-ack 两段式)。这里只登记 pending,
+                // 未确认不标记:被覆盖/取消的注入不该压制这些记忆(下轮可重注)。
+                registerPendingInjection(payload.agent.id, injection.id, fresh.slice(0, lines.length).map((h) => h.id));
+                // §F 追踪:注入轮
+                trace({
+                    kind: 'recall_turn', ts: Date.now(), sessionId: sessionKey, queryChars, querySha, queryText,
+                    hitIds: scoped.map((h) => h.id), hitScores: scoped.map((h) => Number(h.score.toFixed(4))),
+                    injectedIds: fresh.slice(0, lines.length).map((h) => h.id), suppressedCount: scoped.length - fresh.length,
+                    durationMs: Date.now() - searchStart, outcome: 'injected',
+                });
                 // 入账在成功构造注入消息之后、返回 enter 之前——任何前置抛错路径账目零扰动
                 const led = ledgerFor(payload.agent.id);
                 recordRecallInjection(led, text.length);
@@ -459,7 +568,7 @@ export function registerRecall(ctx, cfg, stores, logger, live, modes, dataDir) {
         for (const agent of agents.list())
             registerForAgent(agent);
     }
-    ctx.on('agent/created', (payload) => {
+    ctx.on('agent/created', async (payload) => {
         registerForAgent(payload.agent);
     });
     ctx.effect(() => () => {