@ai-agent-forge/plugin-memory 0.88.13 → 0.88.15

package/dist/memory/curator.js

@@ -0,0 +1,551 @@
+/**
+ * 归档会话整理器（记忆归档与整理设计 §5-§7，2026-10-22 裁决落地）：
+ * 归档即后台整理。memory 插件负责调度、切片预算、批次协议、幂等提交与
+ * 生命周期；"从会话里提炼什么"由经 `memory.curation-policy@1` 能力目录
+ * require 到的整理策略插件回答（第一方默认策略是 plugins/memory-curation，
+ * 与第三方策略走同一公共契约，本模块对两者无差别）。
+ *
+ * 与来源切割（§6 用户裁决）：整理产物是独立原子——不带 sessionRefs、不带指向
+ * 会话条目的 sourceRefs、不写 provenance；删除会话不触碰记忆原子。操作凭据
+ * 留在本侧 journal（`<agentDir>/archive/sessions/curation-journal.jsonl`，
+ * batchId + 内容 digest，不含会话原文）。
+ *
+ * 批次协议（§5.3.6/§5.3.7）：journal 是批次的可恢复事实来源——追加式 JSONL，
+ * 行带 status："open" 行先落盘（批次完整结果），全部原子提交完成后追加
+ * "committed" 事实行，同 batchId 以文件末条为准。curateSession 开始时先查
+ * 该会话的 open 批次：存在则不调策略、不读会话，直接按持久化的 statements
+ * 以相同确定性 observationId 重放提交（已提交条目去重跳过，剩余补齐），收口
+ * 后照常 reportCuration——旧批次未处理时不开始新批次，两批各自不完整的原子
+ * 不可能并存；重放发现批次实际早已全部提交（全部幂等跳过）也走完收口。
+ * 旧版无 status 字段的行等价 open（旧版在提交前一刻落盘，语义相同）。
+ *
+ * 暂停/续跑（§5.4 用户裁决）：策略抛错、超时（60s 上限）或会话中止信号触发时
+ * 返回 paused——不写 curated、不落 journal、不留部分提交；curation 维度保持
+ * 缺失，归档事件重投或启动 sweep 会自然续跑。已提交条目经确定性 memoryId
+ * （owner + `curation:<batchId>:<index>`）在 store 回查去重，同 batchId 重试
+ * 不会产生重复原子。
+ */
+import { createHash } from "node:crypto";
+import { appendFile, mkdir, readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { buildMemoryAtomV1 } from "./foundation.js";
+import { MEMORY_CONTRACT_VERSION_V2 } from "./transfer.js";
+/** 整理策略能力 id（记忆归档与整理设计 §7.2 冻结契约）。 */
+export const MEMORY_CURATION_POLICY_CAPABILITY_ID = "memory.curation-policy";
+/** 整理策略能力版本（exact version matching）。 */
+export const MEMORY_CURATION_POLICY_VERSION = 1;
+/** 每片最大条目数（有界切片，按条数）。 */
+export const CURATION_SLICE_MAX_ENTRIES = 200;
+/** 最多片数；超出截断并在 existingStatements 摘要里说明。 */
+export const CURATION_MAX_SLICES = 20;
+/** 传给策略的既有 statement 摘要条数上限（去重参考）。 */
+export const CURATION_EXISTING_STATEMENTS_LIMIT = 100;
+/** 既有 statement 摘要的每条截断长度（字符）。 */
+export const CURATION_EXISTING_STATEMENT_PREFIX_CHARS = 200;
+/** 单批 proposal 条数上限；超出部分丢弃并 warn。 */
+export const CURATION_MAX_PROPOSALS = 20;
+/** 单条 statement 上限（与 memory_write 内容契约同口径，UTF-16 单元）。 */
+export const CURATION_STATEMENT_MAX_CHARS = 700;
+/** 策略调用硬截止；超时按暂停处理（模型恢复后续跑）。 */
+export const CURATION_POLICY_TIMEOUT_MS = 60_000;
+/** 整理产物 facets 的 capability 命名空间（与 tag facet 同域 "builtin.memory"）。 */
+const CURATION_FACET_NAMESPACE = "builtin.memory";
+/** 整理产物保留档（first-party retention registry "long"，随记忆自身周期朝生暮死）。 */
+const CURATION_RETENTION_MODE_ID = "long";
+/** 整理批次 journal 路径（相对 agentDir；只含 batchId/digest/结果，无会话原文）。 */
+const CURATION_JOURNAL_RELATIVE_PATH = join("archive", "sessions", "curation-journal.jsonl");
+/**
+ * `session.archived@1`（宿主 lifecycle catalog）数据的结构化收窄——只取整理器
+ * 读的字段。订阅走 `{id, version}` 引用形式：定义归宿主 bootstrap lifecycle
+ * 插件所有，宿主未定义该事件时注册被结构性拒绝（D-028 插件装载失败，绝不会
+ * 变成会话失败）。
+ */
+export const SESSION_ARCHIVED_EVENT_REFERENCE = { id: "session.archived", version: 1 };
+/** 批次凭据：batchId = sha256(sessionId + 各 statement digest 拼接)。 */
+export function curationBatchIdOf(sessionId, statementDigests) {
+    const hash = createHash("sha256");
+    hash.update(sessionId);
+    for (const digest of statementDigests)
+        hash.update(digest);
+    return hash.digest("hex");
+}
+/** 单条 statement 的 sha256 digest（journal 与 batchId 共用）。 */
+export function curationStatementDigest(statement) {
+    return createHash("sha256").update(statement, "utf8").digest("hex");
+}
+/**
+ * open 行形状校验（journal 由本模块写出，重放前仍校验——防崩溃残行与外手改写
+ * 产生非法原子）。旧版行无 status 字段：形状同 open，等价 open 处理。
+ */
+function isOpenEntryShape(value) {
+    if (value.status !== "open" && value.status !== undefined)
+        return false;
+    if (!Array.isArray(value.statements) || !Array.isArray(value.digests))
+        return false;
+    return value.statements.every((item) => isPlainRecord(item) &&
+        typeof item.statement === "string" &&
+        item.statement !== "" &&
+        Array.isArray(item.facets) &&
+        item.facets.every((facet) => isPlainRecord(facet) && typeof facet.key === "string" && typeof facet.value === "string"));
+}
+/**
+ * 读取该会话的未完成批次（§5.3.6 崩溃重试入口，§5.3.7 新批次守卫的依据）：
+ * journal 是追加式事实流，同 batchId 以文件末条为准；末条仍为 open 即未完成。
+ * 多个 open 批次并存时（仅可能来自协议启用前的旧文件）取文件序最后一条。
+ * 文件不存在返回 undefined；JSON 解析失败的残行告警跳过（只可能是崩溃中追加
+ * 的末行，不影响更早的完整行）；不可重放的 open 行属于事实来源损坏，向上抛错
+ * ——按 §5.3.7 拒绝开始新批次，而不是在坏批次之上再开一批。
+ */
+async function readOpenCurationBatch(journalPath, sessionId, logger) {
+    let text;
+    try {
+        text = await readFile(journalPath, "utf8");
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return undefined;
+        throw error;
+    }
+    const lastLineByBatch = new Map();
+    for (const [line, raw] of text.split("\n").entries()) {
+        if (raw.trim() === "")
+            continue;
+        let parsed;
+        try {
+            parsed = JSON.parse(raw);
+        }
+        catch {
+            logger?.warn(`memory curation journal line ${line + 1} is not valid JSON; skipped`);
+            continue;
+        }
+        if (!isPlainRecord(parsed) || parsed.sessionId !== sessionId)
+            continue;
+        const batchId = parsed.batchId;
+        if (typeof batchId !== "string" || batchId === "")
+            continue;
+        if (parsed.status === "committed") {
+            lastLineByBatch.set(batchId, { line, closed: true, open: undefined });
+            continue;
+        }
+        if (!isOpenEntryShape(parsed)) {
+            logger?.warn(`memory curation journal line ${line + 1} has an unrecognized shape; skipped`);
+            continue;
+        }
+        lastLineByBatch.set(batchId, { line, closed: false, open: parsed });
+    }
+    let latest;
+    for (const record of lastLineByBatch.values()) {
+        if (record.closed || record.open === undefined)
+            continue;
+        if (latest === undefined || record.line > latest.line)
+            latest = record;
+    }
+    return latest?.open;
+}
+/** 追加 committed 事实行（open 行落盘时目录已创建，此处无需 mkdir）。 */
+async function appendCommittedJournalLine(journalPath, batchId, sessionId, now) {
+    const entry = {
+        batchId,
+        sessionId,
+        at: new Date(now()).toISOString(),
+        status: "committed",
+    };
+    await appendFile(journalPath, `${JSON.stringify(entry)}\n`, "utf8");
+}
+/**
+ * 确定性构造整理原子（记忆归档与整理设计 §5.2 冻结字段表）。不复用 buildWriteAtom——
+ * 那里 observationId 前缀写死 memory_write 会话序列。identityHash 由装配方
+ * 注入（capability.ts 的 FNV-1a，同一写入身份口径）。
+ */
+export function buildCuratedAtom(input) {
+    const observationId = `curation:${input.batchId}:${input.index}`;
+    const memoryId = `mem-${input.identityHash(`${input.owner}\u0000${observationId}`)}`;
+    const occurredAt = new Date(input.now()).toISOString();
+    return buildMemoryAtomV1({
+        memoryId,
+        contractVersion: MEMORY_CONTRACT_VERSION_V2,
+        schemaVersion: 1,
+        scope: "long-term",
+        retentionMode: CURATION_RETENTION_MODE_ID,
+        owner: input.owner,
+        profileId: input.manifestId,
+        ...(input.domain.kind === "suite" ? { suiteId: input.domain.suiteId } : {}),
+        retentionPolicyVersion: "retention@1",
+        memoryKind: "synthesis",
+        payload: { statement: input.proposal.statement },
+        occurredAt,
+        recordedAt: occurredAt,
+        // 记忆与来源会话彻底切割（§6）：无来源引用、无会话引用、无 provenance。
+        sourceRefs: [],
+        observationId,
+        sessionRefs: [],
+        agentInstanceRefs: [],
+        projectRefs: [],
+        subjectRefs: [],
+        facets: input.proposal.facets.map((facet) => ({
+            namespace: CURATION_FACET_NAMESPACE,
+            schemaVersion: 1,
+            key: facet.key,
+            value: facet.value,
+        })),
+        relations: [],
+        // 模型归纳内容（§5.2 evidenceClass derived）：保守置信与推断写入同档 0.6。
+        confidence: 0.6,
+        importance: 0.5,
+        evidenceClass: "derived",
+        contentRevision: `c-${input.identityHash(input.proposal.statement)}`,
+        writeReason: `${input.manifestId}/curation`,
+    });
+}
+/**
+ * 逐条提交批次原子（顺序照 write-face 工具路径：先账本后可见，投影埋点收尾）。
+ * 幂等判定同时看 store 与账本快照（§5.3 崩溃重试语义的提交侧，新批次与 journal
+ * 重放共用）：提交循环可能在"账本已 append、store 未 commit"的窗口被打断——
+ * 账本是持久事实，重放对该窗口内的原子只补齐 store 可见性与投影，不再 append
+ * 重复账本行；两侧都在的条目跳过，都缺的整条提交。调用方负责 journal 状态收口
+ * 与 reportCuration。
+ */
+function commitBatchAtoms(deps, accepted, batchId) {
+    const { domain, ledger } = deps.resolveDomain();
+    const ledgeredMemoryIds = new Set(ledger.atomsSnapshot().map((atom) => atom.memoryId));
+    let committed = 0;
+    let duplicates = 0;
+    for (const [index, proposal] of accepted.entries()) {
+        const atom = buildCuratedAtom({
+            proposal,
+            batchId,
+            index,
+            owner: deps.owner,
+            domain,
+            manifestId: deps.manifest.id,
+            now: deps.now,
+            identityHash: deps.identityHash,
+        });
+        const ledgered = ledgeredMemoryIds.has(atom.memoryId);
+        if (ledgered && deps.store.get(atom.memoryId, { owner: deps.owner }) !== undefined) {
+            duplicates += 1;
+            continue;
+        }
+        if (!ledgered)
+            ledger.append(atom);
+        deps.store.commit(atom);
+        deps.vectorProjection.upsertAtom(atom);
+        committed += 1;
+    }
+    return { committed, duplicates };
+}
+/** payload `{ statement }` 约定的读取投影（与 capability.statementOf 同构）。 */
+function statementTextOf(payload) {
+    if (payload !== null && typeof payload === "object" && !Array.isArray(payload)) {
+        const statement = payload.statement;
+        if (typeof statement === "string")
+            return statement;
+    }
+    return JSON.stringify(payload);
+}
+const boundedErrorText = (error) => {
+    const message = error instanceof Error ? error.message : String(error);
+    const codePoints = Array.from(message);
+    return codePoints.length <= 200 ? message : `${codePoints.slice(0, 200).join("")}…`;
+};
+const isPlainRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+/**
+ * proposals 校验（提交闸门在 memory 侧，记忆归档与整理设计 §7.2）：statement 非空且
+ * ≤700 字符、条数 ≤20（超出丢弃并 warn）、facets 形状非法整条丢弃。facets 内
+ * 单项 key/value 非空字符串校验，非法项丢弃该 facet（不连坐整条）。结果整体
+ * 非 { proposals: [...] } 形状 = 策略契约失败，返回 undefined 交由调用方暂停。
+ */
+function validateProposals(raw, logger) {
+    if (!isPlainRecord(raw) || !Array.isArray(raw.proposals))
+        return undefined;
+    const accepted = [];
+    let dropped = 0;
+    for (const [index, item] of raw.proposals.entries()) {
+        if (accepted.length >= CURATION_MAX_PROPOSALS) {
+            dropped += 1;
+            continue;
+        }
+        if (!isPlainRecord(item) || typeof item.statement !== "string") {
+            logger?.warn(`memory curation dropped proposal[${index}]: statement must be a string`);
+            dropped += 1;
+            continue;
+        }
+        const statement = item.statement;
+        if (statement.trim() === "") {
+            logger?.warn(`memory curation dropped proposal[${index}]: statement is empty`);
+            dropped += 1;
+            continue;
+        }
+        if (statement.length > CURATION_STATEMENT_MAX_CHARS) {
+            logger?.warn(`memory curation dropped proposal[${index}]: statement is ${statement.length} characters (limit ${CURATION_STATEMENT_MAX_CHARS})`);
+            dropped += 1;
+            continue;
+        }
+        if (item.facets !== undefined && !Array.isArray(item.facets)) {
+            logger?.warn(`memory curation dropped proposal[${index}]: facets must be an array when present`);
+            dropped += 1;
+            continue;
+        }
+        const facets = [];
+        for (const [facetIndex, rawFacet] of (item.facets ?? []).entries()) {
+            if (!isPlainRecord(rawFacet) ||
+                typeof rawFacet.key !== "string" ||
+                rawFacet.key.trim() === "" ||
+                typeof rawFacet.value !== "string" ||
+                rawFacet.value.trim() === "") {
+                logger?.warn(`memory curation dropped proposal[${index}] facet[${facetIndex}]: key/value must be non-empty strings`);
+                continue;
+            }
+            facets.push({ key: rawFacet.key, value: rawFacet.value });
+        }
+        accepted.push({ statement, facets });
+    }
+    if (dropped > 0) {
+        logger?.warn(`memory curation dropped ${dropped} invalid proposal(s) before committing the batch`);
+    }
+    return { accepted, dropped };
+}
+/**
+ * 策略调用竞速：`handle.result` vs 60s 硬截止 vs 会话中止信号。三个败因都收敛
+ * 为 paused 的 reason（模型不可用/挂起 → 暂停续跑语义，§5.4 用户裁决）。
+ */
+async function awaitPolicyResult(handle, signal) {
+    let timer;
+    // 中止信号 → 立即拒绝的竞速臂；dispose 摘除监听，竞速已定时不再持有信号。
+    let abortArm;
+    if (signal !== undefined) {
+        abortArm = (() => {
+            let rejectFn;
+            const onAbort = () => rejectFn?.(new Error("memory curation aborted: session abort signal fired"));
+            const promise = new Promise((_, reject) => {
+                rejectFn = reject;
+                if (signal.aborted)
+                    reject(new Error("memory curation aborted: session abort signal fired"));
+                else
+                    signal.addEventListener("abort", onAbort, { once: true });
+            });
+            return { promise, dispose: () => signal.removeEventListener("abort", onAbort) };
+        })();
+    }
+    try {
+        const value = await Promise.race([
+            handle.result,
+            new Promise((_, reject) => {
+                timer = setTimeout(() => reject(new Error(`memory curation policy did not settle within ${CURATION_POLICY_TIMEOUT_MS}ms`)), CURATION_POLICY_TIMEOUT_MS);
+                timer.unref?.();
+            }),
+            ...(abortArm === undefined ? [] : [abortArm.promise]),
+        ]);
+        return { ok: true, value };
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        if (message.includes("did not settle within"))
+            return { ok: false, reason: "policy-timeout", error };
+        if (message.includes("abort signal fired"))
+            return { ok: false, reason: "aborted", error };
+        return { ok: false, reason: "policy-error", error };
+    }
+    finally {
+        if (timer !== undefined)
+            clearTimeout(timer);
+        abortArm?.dispose();
+    }
+}
+/**
+ * 整理一个归档会话（记忆归档与整理设计 §5 批次协议）：幂等状态回查 → journal
+ * open 批次重放（有则不调策略、不读会话，按持久化结果补齐提交并收口，§5.3.6/
+ * §5.3.7）→ 策略 require → 有界分页读 → 逐片策略 propose（每片一次调用；任一
+ * 片失败/超时/中止/非法结果即整批暂停，§5.4）→ 合并候选 → journal open 行落盘
+ * → 逐条幂等提交 → journal committed 收口 → 回写 curated。任何暂停/失败路径都
+ * 不写 curated、不留部分提交。
+ */
+export async function curateSession(deps, sessionId) {
+    const { api, sessionArchive, store, owner } = deps;
+    const logger = api.logger;
+    if (sessionArchive === undefined) {
+        // 无归档面则 reportCuration 不可能：本地记录后直接返回。
+        logger?.warn(`memory curation skipped for session ${sessionId}: host exposes no session-archive face`);
+        return { status: "skipped", reason: "no-archive" };
+    }
+    // 幂等：该会话已有整理结论时不再跑批（重试链路与事件重投的自然短路）。
+    const existingStatus = await sessionArchive.curationStatus(sessionId);
+    if (existingStatus === "curated")
+        return { status: "skipped", reason: "already-curated" };
+    if (existingStatus === "skipped")
+        return { status: "skipped", reason: "already-skipped" };
+    const journalPath = join(deps.agentDir, CURATION_JOURNAL_RELATIVE_PATH);
+    // 批次协议（§5.3.6/§5.3.7）：open 批次是唯一事实来源——不调策略、不读会话，
+    // 直接按持久化的 statements 以相同确定性 observationId 重放提交（已提交条目
+    // 去重跳过，剩余补齐），全部落库后收口 committed 并 reportCuration。"旧批次
+    // 未处理时拒绝开始新批次"由此自然成立：open 批次永远优先重放，两批各自不
+    // 完整的原子不可能并存；全部幂等跳过（实际早已提交完）也走完收口。重放不
+    // 依赖策略能力——journal 不依赖策略，策略缺席不阻塞恢复。
+    const openBatch = await readOpenCurationBatch(journalPath, sessionId, logger);
+    if (openBatch !== undefined) {
+        const accepted = openBatch.statements.map((item) => ({
+            statement: item.statement,
+            facets: item.facets.map((facet) => ({ key: facet.key, value: facet.value })),
+        }));
+        const { committed, duplicates } = commitBatchAtoms(deps, accepted, openBatch.batchId);
+        await appendCommittedJournalLine(journalPath, openBatch.batchId, sessionId, deps.now);
+        logger?.info(`memory curation replayed open batch ${openBatch.batchId} for session ${sessionId}: ${committed} committed, ${duplicates} already present`);
+        await sessionArchive.reportCuration(sessionId, "curated", { batchId: openBatch.batchId });
+        return { status: "curated", batchId: openBatch.batchId, committed, duplicates };
+    }
+    // 策略 require（optional 消费模式，coding-tools requireCoordination 先例）：
+    // 未装策略 = 整理不可用，会话按 skipped 回写（宿主确认框须明示未经整理）。
+    let policyHandle;
+    try {
+        policyHandle = api.capabilities.require(MEMORY_CURATION_POLICY_CAPABILITY_ID, {
+            version: MEMORY_CURATION_POLICY_VERSION,
+        });
+    }
+    catch {
+        await sessionArchive.reportCuration(sessionId, "skipped");
+        return { status: "skipped", reason: "policy-missing" };
+    }
+    // 有界分页读（整理器读归档会话的唯一公共路径）：每片 ≤200 条，最多 20 片，
+    // 超出截断并在 existingStatements 摘要里说明。
+    const slices = [];
+    let offset;
+    for (let slice = 0; slice < CURATION_MAX_SLICES; slice += 1) {
+        const chunk = await sessionArchive.readEntries(sessionId, {
+            offset,
+            limit: CURATION_SLICE_MAX_ENTRIES,
+        });
+        if (chunk.entries.length > 0)
+            slices.push(chunk.entries);
+        offset = chunk.nextOffset;
+        if (offset === undefined)
+            break;
+    }
+    const truncated = offset !== undefined;
+    // 既有 statement 摘要（当前 store 实例内，owner 边界；≤100 条，前 200 字符）。
+    const existingSet = new Set();
+    for (const record of store.list({ owner })) {
+        if (existingSet.size >= CURATION_EXISTING_STATEMENTS_LIMIT)
+            break;
+        existingSet.add(statementTextOf(record.atom.payload).slice(0, CURATION_EXISTING_STATEMENT_PREFIX_CHARS));
+    }
+    const existingStatements = [...existingSet];
+    if (truncated) {
+        existingStatements.push(`[session input truncated after ${CURATION_MAX_SLICES} slices (${CURATION_MAX_SLICES * CURATION_SLICE_MAX_ENTRIES} entries); entries beyond this bound were not read]`);
+    }
+    // 策略调用（逐片，§5.4 单次模型调用输入有界）：每片一次 propose、顺序执行；
+    // 任一片失败/超时/中止 → 整批暂停（不写 curated、不留部分提交；curation 维度
+    // 保持缺失，重投或 sweep 自然续跑）。call 本身同步抛错（宿主分派失败/handler
+    // 同步 throw）与 result 的 rejection 同语义。
+    const accepted = [];
+    for (const [sliceIndex, slice] of slices.entries()) {
+        let callOutcome;
+        try {
+            callOutcome = await awaitPolicyResult(policyHandle.call({
+                op: "propose",
+                sessionId,
+                slices: [slice],
+                existingStatements,
+            }), api.sessionAbortSignal?.());
+        }
+        catch (error) {
+            callOutcome = { ok: false, reason: "policy-error", error };
+        }
+        if (!callOutcome.ok) {
+            logger?.warn(`memory curation paused for session ${sessionId} (${callOutcome.reason}) at slice ${sliceIndex + 1}/${slices.length}: ${boundedErrorText(callOutcome.error)}`);
+            return { status: "paused", reason: callOutcome.reason };
+        }
+        const validated = validateProposals(callOutcome.value, logger);
+        if (validated === undefined) {
+            logger?.warn(`memory curation paused for session ${sessionId}: policy returned a malformed propose result at slice ${sliceIndex + 1}/${slices.length}`);
+            return { status: "paused", reason: "invalid-result" };
+        }
+        accepted.push(...validated.accepted);
+    }
+    // 批次条数上限（§7.2 提交闸门）跨片生效：单批上限不变，超出部分丢弃并 warn。
+    if (accepted.length > CURATION_MAX_PROPOSALS) {
+        const dropped = accepted.length - CURATION_MAX_PROPOSALS;
+        accepted.splice(CURATION_MAX_PROPOSALS);
+        logger?.warn(`memory curation dropped ${dropped} proposal(s) beyond the batch limit of ${CURATION_MAX_PROPOSALS}`);
+    }
+    // 批次凭据：batchId = sha256(sessionId + 各 statement digest 拼接)；完整结果
+    // 先落 journal（可恢复的事实来源，不含会话原文），再逐条提交。
+    const digests = accepted.map((proposal) => curationStatementDigest(proposal.statement));
+    const batchId = curationBatchIdOf(sessionId, digests);
+    const journalEntry = {
+        batchId,
+        sessionId,
+        at: new Date(deps.now()).toISOString(),
+        status: "open",
+        statements: accepted.map((proposal) => ({ statement: proposal.statement, facets: proposal.facets })),
+        digests,
+    };
+    await mkdir(join(deps.agentDir, "archive", "sessions"), { recursive: true });
+    await appendFile(journalPath, `${JSON.stringify(journalEntry)}\n`, "utf8");
+    // 逐条提交（§5.3 崩溃重试语义的提交侧），完成后追加 committed 事实行收口，
+    // 再回写 curated——重试读到 committed 即不再重放该批次。
+    const { committed, duplicates } = commitBatchAtoms(deps, accepted, batchId);
+    await appendCommittedJournalLine(journalPath, batchId, sessionId, deps.now);
+    await sessionArchive.reportCuration(sessionId, "curated", { batchId });
+    return { status: "curated", batchId, committed, duplicates };
+}
+/**
+ * 装配归档整理器（记忆归档与整理设计 §5-§7）：
+ * - 启动 sweep：`sessionArchive.listArchived()` 找 curation 缺失的会话逐个整理；
+ * - `session.archived@1` 事件观察：归档即后台整理（handler 同步返回，整理在
+ *   后台跑，不阻塞事件投递）。
+ * 同一会话的整理经每会话一条 promise 链串行（sweep 与事件重投并发时天然去重）。
+ * 归档面缺席（testkit/老宿主）时两个触发都不注册，返回空注册列表。
+ */
+export function createMemoryCurator(deps) {
+    const { api, sessionArchive } = deps;
+    const logger = api.logger;
+    if (sessionArchive === undefined)
+        return { registrations: [] };
+    const chains = new Map();
+    const enqueue = (sessionId) => {
+        // 每会话一条链: 前一链的失败不阻断后续 (catch 抹平), 同会话并发触发
+        // (事件重投 + sweep) 在链上串行, 不会并发跑批。
+        const last = chains.get(sessionId) ?? Promise.resolve();
+        const next = last.catch(() => undefined).then(() => curateSession(deps, sessionId));
+        chains.set(sessionId, next);
+        void next.catch((error) => {
+            logger?.warn(`memory curation failed for session ${sessionId}: ${boundedErrorText(error)}`);
+        });
+        // 链落定后摘除表项 (守卫: 已被更新的链接手时不删)。catch 抹平后的
+        // finally 臂自身不会 reject, 无 unhandled rejection。
+        void next
+            .catch(() => undefined)
+            .finally(() => {
+            if (chains.get(sessionId) === next)
+                chains.delete(sessionId);
+        });
+    };
+    // 启动 sweep：后台串行补齐历史归档会话的整理（curation 维度已有结论的跳过）。
+    const sweep = async () => {
+        try {
+            const archived = await sessionArchive.listArchived();
+            for (const item of archived) {
+                if (item.curation !== undefined)
+                    continue;
+                enqueue(item.sessionId);
+            }
+        }
+        catch (error) {
+            logger?.warn(`memory curation startup sweep failed: ${boundedErrorText(error)}`);
+        }
+    };
+    void sweep();
+    const registrations = [];
+    // lifecycle 在 CapabilityAPI 类型上是必选成员（experimental），最小宿主可以
+    // 不带该面；事件触发缺席时启动 sweep 仍可用，与 hooks 同款降级。
+    if (api.lifecycle !== undefined) {
+        registrations.push(api.lifecycle.registerObserve(SESSION_ARCHIVED_EVENT_REFERENCE, (event) => {
+            enqueue(event.data.sessionId);
+        }));
+    }
+    else {
+        logger?.warn("memory curator: host exposes no lifecycle face; session.archived trigger is unavailable");
+    }
+    return { registrations };
+}
+//# sourceMappingURL=curator.js.map