berry-agent 0.1.0-alpha.1

package/dist/memory/cite.js

@@ -0,0 +1,131 @@
+import { MEMORY_CITE_RE } from './inject.js';
+import { MEMORY_LAST_ASSISTANT_TEXT_LRU } from './types.js';
+/* ---------------- 文本面提取 ---------------- */
+/**
+ * assistant/message durable data 文本提取（wiring 落 data.content =
+ * (text|thinking 块)[]——toolCall 块不内联；引用只发生在 text 块呈现面，
+ * thinking 块天然排除）。坏形返回 null（消费侧静默跳过——尽力而为）。
+ * 导出面（§4 回看缓存共用——「紧邻前一条 assistant 文本」的取数单源）。
+ */
+export function assistantTextOf(data) {
+    if (typeof data !== 'object' || data === null)
+        return null;
+    const content = data.content;
+    if (typeof content === 'string')
+        return content;
+    if (!Array.isArray(content))
+        return null;
+    return content
+        .filter((b) => {
+        const block = b;
+        return typeof block === 'object' && block !== null && block.type === 'text' && typeof block.text === 'string';
+    })
+        .map((b) => b.text)
+        .join('\n');
+}
+/* ---------------- 引用解析 ---------------- */
+/**
+ * 文本面引用短 id 解析（同消息同短 id 去重——一条消息对一条记忆计一次；
+ * 首现序保序）。/g 正则共享——进入与离开双复位（scan.ts 无状态纪律同律）。
+ */
+export function parseCitations(text) {
+    MEMORY_CITE_RE.lastIndex = 0;
+    const shortIds = [];
+    const seen = new Set();
+    let m;
+    while ((m = MEMORY_CITE_RE.exec(text)) !== null) {
+        const short = m[1];
+        if (!seen.has(short)) {
+            seen.add(short);
+            shortIds.push(short);
+        }
+    }
+    MEMORY_CITE_RE.lastIndex = 0;
+    return shortIds;
+}
+/** 建引用回写挂件（装配面挂会话事件流——消费 idiom 同 18c-5 周期路） */
+export function createCiteRecorder(deps) {
+    const warn = deps.warn ?? (() => { });
+    return {
+        onEvent(sessionId, type, data) {
+            if (type !== 'assistant/message')
+                return;
+            try {
+                const text = assistantTextOf(data);
+                if (text === null || text === '')
+                    return;
+                const shorts = parseCitations(text);
+                if (shorts.length === 0)
+                    return;
+                // 前缀归责三态：零命中不进 shorts；多命中 = 歧义全部忽略；恰一命中 = 唯一归属
+                const fullIds = [];
+                for (const short of shorts) {
+                    const matches = deps.dao.resolveShortId(short);
+                    if (matches.length === 1)
+                        fullIds.push(matches[0]);
+                }
+                if (fullIds.length > 0)
+                    deps.dao.markUsed(fullIds, sessionId);
+            }
+            catch (err) {
+                warn(`[memory] 引用回写尽力而为止步：${err instanceof Error ? err.message : String(err)}`);
+            }
+        },
+    };
+}
+/**
+ * 纠正负效用回写（§4 即时路第二动作——§6 解析面**全复用**）：对被纠正回答的
+ * 文本面解析引用标记（MEMORY_CITE_RE + 同消息同短 id 去重 = 守卫④「同事件
+ * 一次」的物理承载）→ 前缀归责三态（与 cite 正账同律）→ dao.markCorrected
+ * 批量（corrected_count+1 + op='corrected-cite' 流水带**纠正发生会话**键——
+ * 守卫①③归 dao 语句本体）。尽力而为：全程 try/catch warn（计量面写点不
+ * 反噬提取主路——两动作失败路径分立的回写侧保障）。
+ */
+export function recordCorrectedCites(dao, sessionId, assistantText, warn = () => { }) {
+    try {
+        const shorts = parseCitations(assistantText);
+        if (shorts.length === 0)
+            return;
+        const fullIds = [];
+        for (const short of shorts) {
+            const matches = dao.resolveShortId(short);
+            if (matches.length === 1)
+                fullIds.push(matches[0]);
+        }
+        if (fullIds.length > 0)
+            dao.markCorrected(fullIds, sessionId);
+    }
+    catch (err) {
+        warn(`[memory] 纠正负效用回写尽力而为止步：${err instanceof Error ? err.message : String(err)}`);
+    }
+}
+/**
+ * per-session 最近 assistant 文本回看缓存（§4 回看位实现——装配面同一
+ * session/event 消费点内喂入，零新事件通道零宿主改动；LRU 帽族同 §6 epochs）。
+ * **紧邻前一条语义忠实**：每次 assistant/message 到达即覆写该会话条目——
+ * 空文本面（纯 toolCall/thinking 消息）同覆写为 ''，回看自然空手（跨条回看
+ * 无判据不发明）。读即触位（紧随其后的纠正回看高频——保热会话不被挤）。
+ */
+export function createLastAssistantTextCache(capacity = MEMORY_LAST_ASSISTANT_TEXT_LRU) {
+    const cache = new Map();
+    return {
+        observe(sessionId, data) {
+            const text = assistantTextOf(data) ?? '';
+            cache.delete(sessionId); // 先删再插 = 触位到 Map 尾（最近）
+            cache.set(sessionId, text);
+            if (cache.size > capacity) {
+                const oldest = cache.keys().next().value;
+                if (oldest !== undefined)
+                    cache.delete(oldest);
+            }
+        },
+        get(sessionId) {
+            const text = cache.get(sessionId);
+            if (text === undefined)
+                return null;
+            cache.delete(sessionId);
+            cache.set(sessionId, text);
+            return text;
+        },
+    };
+}

package/dist/memory/codes.js

@@ -0,0 +1,50 @@
+/**
+ * memory 域错误码注册（06 §8.1/§3/§5/§7——MEMORY_ 前缀族；02 §5.3 批 18c-1
+ * 明列两码 + 批 18c-2 工具面扩三码，本仓新立）。
+ *
+ * 码语义分层：MEMORY_SECRET_DETECTED 管写前 secret 扫描命中拒写（DAO 入库
+ * 单点执法——四写点物理汇入同一入库面，没有绕过扫描的写入方；诊断 log-only
+ * 不回写疑似密钥本体）；MEMORY_ENTRY_INVALID 管候选/写请求坏形拒（闭集/
+ * 形状/越界判据——18c-2 扩 promotedToSkill 词法与 ttl days 形两判据）；
+ * MEMORY_NOT_FOUND / MEMORY_FROZEN / MEMORY_REVISION_NOT_FOUND 管持有面
+ * 工具动词守卫（作用行缺席 / 撞冻结行 / 版本缺席）。本文件由模块公开面
+ * index.ts 引入（注册纪律：import 发生才注册）。
+ */
+import { registerErrorCodes } from '../contracts/index.js';
+registerErrorCodes([
+    {
+        code: 'MEMORY_SECRET_DETECTED',
+        module: 'memory',
+        description: '写前 secret 扫描命中拒写——DAO 入库单点执法（即时路/周期路/memory_write/导入直插四写点汇入同一入库面）；诊断 log-only 不回写疑似密钥本体（报 pattern 名，不落命中文本）',
+    },
+    {
+        code: 'MEMORY_ENTRY_INVALID',
+        module: 'memory',
+        description: '候选/写请求坏形拒——kind 非七值闭集、owner_key 形违例（global | project:<根路径哈希> 两形外）、confidence 越界 [0,1]、summary/content 空、source_refs 元素坏形、promotedToSkill 技能名词法违例（^[a-z0-9]+(?:-[a-z0-9]+)*$ 且 ≤64）、ttl days 形违例（非正整数且非 null）',
+    },
+    {
+        code: 'MEMORY_NOT_FOUND',
+        module: 'memory',
+        description: '工具动词作用行缺席——forget/restore/freeze/unfreeze/ttl 携 id 在库缺席响亮拒（GOAL_NOT_FOUND 同构守卫）',
+    },
+    {
+        code: 'MEMORY_FROZEN',
+        module: 'memory',
+        description: '持有面写动词撞冻结行拒——forget（含 promotedToSkill 搬家）/ttl/restore 带 revision 内容回滚腿；frozen 免覆写执法，解冻-再写唯一路径',
+    },
+    {
+        code: 'MEMORY_REVISION_NOT_FOUND',
+        module: 'memory',
+        description: 'restore 带 revision 而版本缺席——无链条目带版本拒、revision 越界同码（带版本 ⊃ 状态复活）',
+    },
+    {
+        code: 'MEMORY_EXPORT_ROOT_DENIED',
+        module: 'memory',
+        description: '导出落盘路径越界可写根拒（批 18c-8）——/memory-export 命令 handler 内显式 isInsideRoot 判定（守门管道对插件内文件写不可见、memory 件无 safety 拓扑边；同律先例 SKILLS_WRITE_ROOT_DENIED / FS_OUTSIDE_WRITABLE_ROOTS——越界拒、边界分隔符守卫同款）',
+    },
+    {
+        code: 'MEMORY_IMPORT_FORMAT_INVALID',
+        module: 'memory',
+        description: '导入文件首行 header 坏形整文件拒（批 18c-8）——magic 串 berry-agent-memory 不符或 formatVersion ≠ 1；行级坏形不入此码（行级宽容分账 rejectedMalformed——恢复式运维动词不弃批）',
+    },
+]);

package/dist/memory/command.js

@@ -0,0 +1,71 @@
+/**
+ * /memory-export · /memory-import 命令处理器（批 18c-8——06 §3/§7：用户
+ * 命令面非模型工具面——操作者运维动词〔备份/迁移〕，模型可发起的全量明文
+ * 记忆落盘 = 可诱导批量外泄路径，故不入工具面）。
+ *
+ * 形态律同 /goal /rewind /tick（命令件先例）：argv → 人读文本；服务面守卫错
+ * （BaseError）折文本不抛——命令面是用户面不是异常面。TUI 命令注册归批 12
+ * host 装配批（corePlugins 注册表现空）。
+ *
+ * 可写根判定：导出落盘路径越界拒 MEMORY_EXPORT_ROOT_DENIED（装配闭包注入
+ * 可写根列表 + handler 内显式 isWithinRoots 判定——06 §3：守门管道对插件内
+ * 文件写不可见、memory 件无 safety 拓扑边）；**导入读面无根判定**（读取任意
+ * 路径是用户显式动词，写入面才受可写根约束——同 skills loadFace 读面先例）。
+ */
+import { readFileSync, writeFileSync } from 'node:fs';
+import { BaseError } from '../contracts/index.js';
+import { buildMemoryExport, isWithinRoots, runMemoryImport } from './port.js';
+export const MEMORY_EXPORT_USAGE = '用法：/memory-export <path> [owner] —— 记忆导出为 JSONL 明文文件（owner 省略 = 全 owner；路径须在可写根内）';
+export const MEMORY_IMPORT_USAGE = '用法：/memory-import <path> —— 从 JSONL 文件恢复式导入（按 id 幂等：已有条目跳过、零合并零覆写）';
+/** /memory-export 处理器（argv = [path, owner?] → 人读文本；守卫错折文本） */
+export async function runMemoryExportCommand(argv, deps) {
+    const [target, owner] = argv;
+    try {
+        if (!target)
+            return `缺路径。\n${MEMORY_EXPORT_USAGE}`;
+        // 落盘路径判定（越界拒——isWithinRoots 同律复用引证〔skills 先例函数体拷贝 + 注记互证〕）
+        if (!isWithinRoots(target, deps.writableRoots())) {
+            throw new BaseError('MEMORY_EXPORT_ROOT_DENIED', `导出落盘路径不在可写根内：${target}`);
+        }
+        const text = buildMemoryExport(deps.dao, {
+            ownerKey: owner,
+            ownerRoots: deps.ownerRoots(),
+            now: deps.now(),
+        });
+        writeFileSync(target, text, 'utf8');
+        const count = text.trimEnd().split('\n').length - 1; // 首行 header 外即数据行数
+        const scope = owner === undefined ? '全部 owner' : `owner ${owner}`;
+        return [
+            `已导出 ${count} 条记忆（${scope}）→ ${target}`,
+            '警示：导出文件含全部记忆明文——按敏感数据保管、勿提交进仓库。',
+        ].join('\n');
+    }
+    catch (err) {
+        // 守卫错折文本（命令面是用户面——BaseError 码与人读原因直呈）
+        if (err instanceof BaseError)
+            return `${err.code}：${err.message}`;
+        throw err;
+    }
+}
+/** /memory-import 处理器（argv = [path] → 人读文本；header 坏形整文件拒折文本） */
+export async function runMemoryImportCommand(argv, deps) {
+    const [target] = argv;
+    try {
+        if (!target)
+            return `缺路径。\n${MEMORY_IMPORT_USAGE}`;
+        const text = readFileSync(target, 'utf8');
+        const r = runMemoryImport(text, deps.dao);
+        if (r.inserted + r.skippedExisting + r.rejectedSecret + r.rejectedMalformed === 0) {
+            return '导入完成：文件内无数据行（仅 header）。';
+        }
+        return [
+            `导入完成：新插 ${r.inserted} 条 · 已在跳过 ${r.skippedExisting} 条`,
+            `　　　　secret 拒写 ${r.rejectedSecret} 条 · 坏形跳过 ${r.rejectedMalformed} 条（恢复式幂等——零合并零覆写）`,
+        ].join('\n');
+    }
+    catch (err) {
+        if (err instanceof BaseError)
+            return `${err.code}：${err.message}`;
+        throw err;
+    }
+}

package/dist/memory/consolidate.js

@@ -0,0 +1,219 @@
+import { tokenizeForMerge, utilityScore } from './merge.js';
+import { parseJsonPayload } from './review.js';
+import { MEMORY_CONSOLIDATION_ANCHOR_MS, MEMORY_CONSOLIDATION_STALE_DAYS, MEMORY_DECAY_FACTOR, MEMORY_DAY_MS, MEMORY_OWNER_CAPACITY, llmTextOf, } from './types.js';
+import { Type } from 'typebox';
+import { Value } from 'typebox/value';
+/* ---------------- LLM 计划 schema（TypeBox 深校验——未知字段拒收） ---------------- */
+const MERGE_SUGGESTION = Type.Object({
+    action: Type.Literal('merge'),
+    keep: Type.String(),
+    drop: Type.String(),
+    reason: Type.String(),
+}, { additionalProperties: false });
+const DECAY_SUGGESTION = Type.Object({
+    action: Type.Literal('decay'),
+    id: Type.String(),
+    reason: Type.String(),
+}, { additionalProperties: false });
+const PLAN = Type.Object({
+    merges: Type.Array(MERGE_SUGGESTION),
+    decays: Type.Array(DECAY_SUGGESTION),
+}, { additionalProperties: false });
+/* ---------------- 工厂 ---------------- */
+/** 空结果便捷构造 */
+function result(outcome, extra = {}) {
+    return { outcome, candidateCount: 0, merged: 0, decayed: 0, rejectedGroups: 0, ignoredSuggestions: 0, ...extra };
+}
+/** 整理拍系统提示词（只出 JSON 对象——护栏在执行腿） */
+const CONSOLIDATE_SYSTEM_PROMPT = [
+    '你是记忆整理器：对候选记忆条目给出深层语义合并与降权建议。',
+    '只输出一个 JSON 对象（无其他文本），形如',
+    '{"merges":[{"action":"merge","keep":"保留条目id","drop":"被并条目id","reason":"合并理由"}],"decays":[{"action":"decay","id":"条目id","reason":"降权理由"}]}',
+    '规则：只建议语义重复或互为矛盾面的合并（keep 承载合并后语义）；只对确证过时或低质条目建议降权；',
+    'reason 必须引用条目摘要中出现的关键词；无建议时输出 {"merges":[],"decays":[]}。',
+].join('\n');
+/** 建整理器（进程单例装配——实例态 = 水位基线 + anchor 时钟） */
+export function createConsolidator(deps) {
+    const { dao, llm } = deps;
+    const warn = deps.warn ?? (() => { });
+    const capacity = deps.capacity ?? MEMORY_OWNER_CAPACITY;
+    const staleDays = deps.staleDays ?? MEMORY_CONSOLIDATION_STALE_DAYS;
+    const decayFactor = deps.decayFactor ?? MEMORY_DECAY_FACTOR;
+    const anchorMs = deps.anchorMs ?? MEMORY_CONSOLIDATION_ANCHOR_MS;
+    const now = deps.now ?? Date.now;
+    // —— 实例内存态（落码定形注：重启视为有新摄入——首轮恒不水位短路）
+    let lastRunClock = null;
+    let baselineIntakeAt = null;
+    /** 候选集构造（三源并集去重；frozen 显式排——listVisible 谓词面已排 expired/终态） */
+    function buildCandidates(visible, nowMs, pollutedSessions) {
+        const candidates = new Map();
+        const add = (row) => {
+            if (row.frozen)
+                return; // frozen 免整理全档
+            candidates.set(row.id, row);
+        };
+        // 源一：老化（updated_at 超 staleDays）
+        const staleBefore = nowMs - staleDays * MEMORY_DAY_MS;
+        for (const row of visible) {
+            if (row.updatedAt < staleBefore)
+                add(row);
+        }
+        // 源二：容量溢出（owner 分组——效用综合分升序取最低分盈余差额行；frozen 不计容量）
+        const byOwner = new Map();
+        for (const row of visible) {
+            if (row.frozen)
+                continue;
+            const group = byOwner.get(row.ownerKey) ?? [];
+            group.push(row);
+            byOwner.set(row.ownerKey, group);
+        }
+        for (const group of byOwner.values()) {
+            if (group.length <= capacity)
+                continue;
+            const surplus = group.length - capacity;
+            const ranked = [...group].sort((a, b) => utilityScore(a) - utilityScore(b)); // 升序——低分先入
+            for (const row of ranked.slice(0, surplus))
+                add(row);
+        }
+        // 源三：polluted 批（§4.1——refs 命中 polluted 会话的条目进淘汰候选）
+        if (pollutedSessions.size > 0) {
+            for (const row of visible) {
+                if (row.sourceRefs.some((ref) => pollutedSessions.has(ref.sessionId)))
+                    add(row);
+            }
+        }
+        return candidates;
+    }
+    /** 理由护栏：reason 分词与摘要 token 交集 ≥1（零交集/空分词 → false 整组驳回） */
+    function reasonSupported(reason, summaries) {
+        const reasonTokens = new Set(tokenizeForMerge(reason));
+        if (reasonTokens.size === 0)
+            return false;
+        for (const summary of summaries) {
+            for (const token of tokenizeForMerge(summary)) {
+                if (reasonTokens.has(token))
+                    return true;
+            }
+        }
+        return false;
+    }
+    /** 存活重验（执行前逐条复核——missing/终态/frozen 均败） */
+    function alive(id) {
+        const row = dao.get(id);
+        return row !== undefined && row.status === 'active' && !row.frozen;
+    }
+    /** 候选清单行（LLM 可见面——id/种类/摘要/三维分原料/未变更天数） */
+    function candidateLine(row, nowMs) {
+        const ageDays = Math.floor((nowMs - row.updatedAt) / MEMORY_DAY_MS);
+        return `[${row.id}] kind=${row.kind} summary=${row.summary}（confidence=${row.confidence} evidence=${row.evidenceCount} usage=${row.usageCount} ${ageDays}d 未变更）`;
+    }
+    return {
+        async run(input) {
+            const nowMs = now();
+            // —— 护栏一（anchor 腿）：拍间最小间隔——只对真实拍（ran/empty）进位
+            if (lastRunClock !== null && nowMs - lastRunClock < anchorMs)
+                return result('skipped-anchor');
+            const visible = dao.listVisible();
+            // —— 护栏一（水位腿）：无新摄入（基线 = 拍终时钟——absorb 自身写不构成摄入）
+            const currentMax = visible.reduce((m, r) => Math.max(m, r.updatedAt), 0);
+            if (baselineIntakeAt !== null && currentMax <= baselineIntakeAt)
+                return result('skipped-watermark');
+            const polluted = new Set(input?.pollutedSessions ?? []);
+            const candidates = buildCandidates(visible, nowMs, polluted);
+            if (candidates.size === 0) {
+                // 候选面已稳定：烧 anchor + 进位基线（防同摄入面空转循环）
+                lastRunClock = nowMs;
+                baselineIntakeAt = Math.max(baselineIntakeAt ?? 0, currentMax, nowMs);
+                return result('skipped-empty');
+            }
+            // —— 护栏一（预算腿）：canAfford 拒跳过本轮（不烧 anchor——预算恢复即拍）
+            if (!llm.canAfford('background'))
+                return result('skipped-budget');
+            // —— LLM 拍
+            let plan;
+            try {
+                const completion = await llm.complete({
+                    systemPrompt: CONSOLIDATE_SYSTEM_PROMPT,
+                    messages: [
+                        {
+                            role: 'user',
+                            content: `候选记忆条目：\n${[...candidates.values()].map((r) => candidateLine(r, nowMs)).join('\n')}`,
+                        },
+                    ],
+                    priority: 'background',
+                });
+                const parsed = parseJsonPayload(llmTextOf(completion.message.content));
+                plan = parsed !== null && Value.Check(PLAN, parsed) ? parsed : null;
+            }
+            catch (error) {
+                // complete 抛（网络/预算竞态）——跳过本轮，状态零进位
+                warn(`memory consolidation 拍失败（跳过本轮）：${error instanceof Error ? error.message : String(error)}`);
+                return result('skipped-error');
+            }
+            if (plan === null)
+                return result('skipped-parse'); // 计划整体坏形——下周期重试
+            // —— 执行腿（护栏逐条执法；物理动作全走 DAO 既有路径）
+            let merged = 0;
+            let decayed = 0;
+            let rejectedGroups = 0;
+            let ignoredSuggestions = 0;
+            for (const m of plan.merges) {
+                const keep = candidates.get(m.keep);
+                const drop = candidates.get(m.drop);
+                // 幻觉护栏：集外 id 一律忽略
+                if (!keep || !drop) {
+                    ignoredSuggestions++;
+                    continue;
+                }
+                // 理由护栏：零交集整组驳回
+                if (!reasonSupported(m.reason, [keep.summary, drop.summary])) {
+                    rejectedGroups++;
+                    continue;
+                }
+                // 存活重验（拍间失活/冻结）
+                if (!alive(m.keep) || !alive(m.drop)) {
+                    ignoredSuggestions++;
+                    continue;
+                }
+                try {
+                    // 血缘继承 + drop 终态 llm:<keep> 内联；批 ev-1 reason 入链——护栏
+                    // 校验后的 LLM 建议组 reason 随版本行持久化（用完即弃 → durable 因由）
+                    dao.absorb(m.keep, m.drop, m.reason);
+                    merged++;
+                }
+                catch {
+                    ignoredSuggestions++; // 执行期拒（并发终态等）——吞不反噬
+                }
+            }
+            for (const d of plan.decays) {
+                const target = candidates.get(d.id);
+                if (!target) {
+                    ignoredSuggestions++;
+                    continue;
+                }
+                if (!reasonSupported(d.reason, [target.summary])) {
+                    rejectedGroups++;
+                    continue;
+                }
+                if (!alive(d.id)) {
+                    ignoredSuggestions++;
+                    continue;
+                }
+                try {
+                    // confidence × factor + 版本 cause='decay'；批 ev-1——decay 判据描述
+                    // （护栏校验后的 LLM 自由文本 reason）随版本行持久化
+                    dao.decay(d.id, decayFactor, d.reason);
+                    decayed++;
+                }
+                catch {
+                    ignoredSuggestions++;
+                }
+            }
+            // —— 拍终状态进位：anchor + 水位基线 = 拍终时钟（自身 absorb 写 ≤ 基线）
+            const settleClock = now();
+            lastRunClock = settleClock;
+            baselineIntakeAt = Math.max(baselineIntakeAt ?? 0, settleClock);
+            return result('ran', { candidateCount: candidates.size, merged, decayed, rejectedGroups, ignoredSuggestions });
+        },
+    };
+}

package/dist/memory/cycle.js

@@ -0,0 +1,109 @@
+import { createConsolidator } from './consolidate.js';
+import { createPollutionTracker } from './pollution.js';
+import { runMemoryReview } from './review.js';
+import { MEMORY_REVIEW_TOOL_CALL_THRESHOLD, MEMORY_REVIEW_TURN_THRESHOLD, MEMORY_REVIEW_WINDOW_TURNS, } from './types.js';
+/* ---------------- 审阅窗切片（纯函数） ---------------- */
+/**
+ * 最近 N 个回合的事件切片（定形注——审阅窗）：自尾向前跳过最近 N 个回合的
+ * turn/end，边界取第 N+1 个 turn/end **之后**——窗口恰含最近 N 个回合（回合
+ * 事件 = 上一收尾之后至本收尾）；回合不足窗全量返回。
+ */
+export function sliceReviewWindow(events, windowTurns = MEMORY_REVIEW_WINDOW_TURNS) {
+    let seen = 0;
+    for (let i = events.length - 1; i >= 0; i--) {
+        if (events[i].type === 'turn/end') {
+            seen++;
+            if (seen === windowTurns + 1)
+                return events.slice(i + 1); // 第 N+1 个收尾之后——最近 N 回合全量
+        }
+    }
+    return events; // 回合不足窗——全量
+}
+/* ---------------- 工厂 ---------------- */
+/** 建周期路编排件（进程单例装配） */
+export function createMemoryCycle(deps) {
+    const warn = deps.warn ?? (() => { });
+    const pollution = deps.pollution ?? createPollutionTracker();
+    const consolidator = deps.consolidator ??
+        createConsolidator({ dao: deps.dao, llm: deps.llm, ...(deps.warn !== undefined ? { warn: deps.warn } : {}) });
+    const turnThreshold = deps.thresholds?.turns ?? MEMORY_REVIEW_TURN_THRESHOLD;
+    const toolCallThreshold = deps.thresholds?.toolCalls ?? MEMORY_REVIEW_TOOL_CALL_THRESHOLD;
+    const windowTurns = deps.thresholds?.windowTurns ?? MEMORY_REVIEW_WINDOW_TURNS;
+    // 会话计数器（里程表）+ due 集 + inFlight 单飞锁——全进程内存态
+    const counters = new Map();
+    const due = new Set();
+    const inFlight = new Set();
+    return {
+        pollution,
+        consolidator,
+        onDurableEvent(sessionId, event) {
+            if (event.type === 'turn/end') {
+                const c = counters.get(sessionId) ?? { turns: 0, toolCalls: 0 };
+                c.turns++;
+                counters.set(sessionId, c);
+            }
+            else if (event.type === 'tool/call') {
+                const c = counters.get(sessionId) ?? { turns: 0, toolCalls: 0 };
+                c.toolCalls++;
+                counters.set(sessionId, c);
+                // 污染标记位（§4.1——载荷携 name；坏形载荷无 name 不标记）
+                const data = event.data;
+                if (data !== null && typeof data === 'object' && typeof data.name === 'string') {
+                    pollution.markIfPolluted(sessionId, data.name);
+                }
+            }
+            else {
+                return; // 其余事件与计数无关
+            }
+            const c = counters.get(sessionId);
+            if (c.turns >= turnThreshold || c.toolCalls >= toolCallThreshold)
+                due.add(sessionId);
+        },
+        dueSessions() {
+            return [...due];
+        },
+        async fire(sessionId) {
+            // inFlight 单飞（定形注：inFlight 跳过——计数器照走里程表）
+            if (inFlight.has(sessionId)) {
+                return { outcome: 'skipped-inflight', sweptExpired: 0 };
+            }
+            inFlight.add(sessionId);
+            try {
+                // —— fire 首步：sweepExpired 同步物化（TTL 清扫 + 访问日志窗口清扫同拍
+                //    单事务——polluted 也不例外；周期报告面取 .expired 计数）
+                const sweptExpired = deps.dao.sweepExpired().expired;
+                // —— 资格检查（§4.1 两路入口同一检查——polluted 跳过 review；遗忘走
+                //    consolidation 淘汰批：polluted 会话集随轮注入）
+                const pollutedNow = pollution.isPolluted(sessionId);
+                let review;
+                if (!pollutedNow) {
+                    const window = sliceReviewWindow(deps.fetchEvents(sessionId), windowTurns);
+                    review = await runMemoryReview({ dao: deps.dao, llm: deps.llm, warn }, sessionId, window);
+                }
+                // —— consolidation 拍（polluted 会话集注入——§4.1 淘汰批圈候选）
+                const consolidation = await consolidator.run({ pollutedSessions: pollution.pollutedSessions() });
+                // —— 计数器复位（里程表——review 完成后归零；due 同清）
+                counters.delete(sessionId);
+                due.delete(sessionId);
+                return {
+                    outcome: pollutedNow ? 'skipped-polluted' : 'reviewed',
+                    sweptExpired,
+                    ...(review !== undefined ? { review } : {}),
+                    consolidation,
+                };
+            }
+            catch (error) {
+                // 尽力而为（06 §4——周期路失败不重试不反噬；进程日志是唯一观测面）
+                warn(`memory 周期路 fire 失败（尽力而为跳过）：${error instanceof Error ? error.message : String(error)}`);
+                return { outcome: pollutedNowRef(pollution, sessionId), sweptExpired: 0 };
+            }
+            finally {
+                inFlight.delete(sessionId);
+            }
+        },
+    };
+}
+/** catch 面资格回查（review 未跑——按现行资格态归类） */
+function pollutedNowRef(pollution, sessionId) {
+    return pollution.isPolluted(sessionId) ? 'skipped-polluted' : 'reviewed';
+}