berry-agent 0.1.0-alpha.1

package/dist/session/import-gates.js

@@ -0,0 +1,148 @@
+/**
+ * 导入四闸（05 篇 §5.1——金样导入/外部会话导入的统一门）。
+ *
+ * 身份闸（自描述格式）→ 词汇闸（逐事件过注册表）→ 配对闸（离线 closer 预检）
+ * → 洪水闸（会话增生限流）。四闸全过才允许建会话；洪水闸是进程态限速器，
+ * 其余三闸是文件内容的纯校验。
+ */
+import { BaseError, isKnownEventType } from '../contracts/index.js';
+/** 本实现认识的格式身份与支持版本（身份闸判据单源） */
+const KNOWN_FORMAT = 'berry-agent/session';
+const SUPPORTED_VERSION = 1;
+/**
+ * 身份闸 + 解析：导入文件文本（JSONL——首行 _meta，其后每行一条 SessionEvent）。
+ * 不认识的自描述拒载（SESSION_IMPORT_BAD_FORMAT，fail-loud 宁拒勿吞）；
+ * 行级 JSON 解析失败同码（撕裂导出文件不可静默截半）。
+ */
+export function parseImportFile(text) {
+    const lines = text.split('\n').filter((line) => line.trim().length > 0);
+    if (lines.length === 0) {
+        throw new BaseError('SESSION_IMPORT_BAD_FORMAT', '导入文件为空（缺 _meta 自描述首行）');
+    }
+    let meta;
+    try {
+        meta = JSON.parse(lines[0]);
+    }
+    catch (err) {
+        throw new BaseError('SESSION_IMPORT_BAD_FORMAT', `_meta 首行非 JSON：${String(err)}`);
+    }
+    const header = meta;
+    if (!header || typeof header !== 'object' || header.format !== KNOWN_FORMAT || header.version !== SUPPORTED_VERSION) {
+        throw new BaseError('SESSION_IMPORT_BAD_FORMAT', `导入文件自描述不认识：format=${String(header?.format)} version=${String(header?.version)}（本实现认识 ${KNOWN_FORMAT} v${SUPPORTED_VERSION}）`);
+    }
+    const events = [];
+    for (let i = 1; i < lines.length; i++) {
+        let parsed;
+        try {
+            parsed = JSON.parse(lines[i]);
+        }
+        catch (err) {
+            throw new BaseError('SESSION_IMPORT_BAD_FORMAT', `第 ${i + 1} 行非 JSON（撕裂文件）：${String(err)}`);
+        }
+        const event = parsed;
+        if (!event || typeof event !== 'object' || typeof event.type !== 'string' || typeof event.seq !== 'number') {
+            throw new BaseError('SESSION_IMPORT_BAD_FORMAT', `第 ${i + 1} 行非 SessionEvent 信封（缺 type/seq）`);
+        }
+        events.push(event);
+    }
+    return {
+        meta: { format: KNOWN_FORMAT, version: SUPPORTED_VERSION },
+        events,
+    };
+}
+/**
+ * 词汇闸：逐事件类型过词汇注册表——未知类型且未标 ignorable 的拒整批
+ * （宁拒勿吞；ignorable 事件向前兼容放行）。
+ */
+export function vocabularyGate(events) {
+    for (const event of events) {
+        if (isKnownEventType(event.type))
+            continue;
+        if (event.ignorable === true)
+            continue;
+        throw new BaseError('SESSION_UNKNOWN_EVENT_TYPE', `导入事件 seq#${event.seq} 类型 ${event.type} 未注册且未标 ignorable（拒整批）`);
+    }
+}
+/**
+ * 配对闸：turn/tool 配对完整性预检——导入前离线跑 closer 语义的反面：
+ * 「缺闭合」可合成收形（recoverClosers 能处置）；「多余闭合」（end 无 start /
+ * result 无 call / seq 断号）无法合成——拒载。seq 连续性同检（firstSeqBreak）。
+ */
+export function pairingGate(events) {
+    const breakAt = (() => {
+        for (let i = 0; i < events.length; i++) {
+            if (events[i].seq !== i)
+                return i;
+        }
+        return null;
+    })();
+    if (breakAt !== null) {
+        throw new BaseError('SESSION_IMPORT_BAD_FORMAT', `导入事件 seq 不连续：位置 ${breakAt} 期望 seq ${breakAt} 实得 ${events[breakAt].seq}`);
+    }
+    let turnDepth = 0;
+    const seenCalls = new Set();
+    for (const event of events) {
+        switch (event.type) {
+            case 'turn/start':
+                turnDepth += 1;
+                break;
+            case 'turn/end':
+                turnDepth -= 1;
+                if (turnDepth < 0) {
+                    throw new BaseError('SESSION_IMPORT_BAD_FORMAT', `导入事件 seq#${event.seq} turn/end 无对应 start（多余闭合不可合成）`);
+                }
+                break;
+            case 'tool/call': {
+                const id = event.data?.toolCallId;
+                if (typeof id === 'string')
+                    seenCalls.add(id);
+                break;
+            }
+            case 'tool/result': {
+                const id = event.data?.toolCallId;
+                if (typeof id === 'string' && !seenCalls.has(id)) {
+                    throw new BaseError('SESSION_IMPORT_BAD_FORMAT', `导入事件 seq#${event.seq} tool/result 无前置 call（${id}——多余闭合不可合成）`);
+                }
+                break;
+            }
+            default:
+                break;
+        }
+    }
+}
+/**
+ * 洪水闸（会话增生限流）：单进程滑动时间窗内导入/fork 新建会话数限速——防
+ * 失控脚本（插件 bug 或用户脚本）以 fork 洪水填库。首版 100/分钟（05 §5.1）。
+ * 超限抛 SESSION_SPAWN_RATE_LIMIT。时钟注入（测试假钟）；窗口态纯内存。
+ */
+export class SessionSpawnLimiter {
+    windowMs;
+    max;
+    clock;
+    /** 窗口内新建时间戳（滑动窗账本） */
+    stamps = [];
+    constructor(options) {
+        this.windowMs = options?.windowMs ?? 60_000;
+        this.max = options?.max ?? 100;
+        this.clock = options?.clock ?? (() => Date.now());
+    }
+    /** 尝试占一个名额（超限抛；成功即记账） */
+    acquire() {
+        const now = this.clock();
+        // 清窗：只留窗口内时间戳
+        while (this.stamps.length > 0 && now - this.stamps[0] >= this.windowMs) {
+            this.stamps.shift();
+        }
+        if (this.stamps.length >= this.max) {
+            throw new BaseError('SESSION_SPAWN_RATE_LIMIT', `会话增生限流：窗口 ${this.windowMs}ms 内新建已达 ${this.max}（防 fork 洪水填库）`);
+        }
+        this.stamps.push(now);
+    }
+}
+/** 便捷面：导入文件全闸校验（身份 → 词汇 → 配对；洪水闸由调用方在建会话位点执法） */
+export function runImportGates(text) {
+    const parsed = parseImportFile(text);
+    vocabularyGate(parsed.events);
+    pairingGate(parsed.events);
+    return parsed;
+}

package/dist/session/index.js

@@ -0,0 +1,18 @@
+/**
+ * session 模块公开面（L1 会话事件日志——02 §2.2 席 9；机制真源 05 篇）。
+ *
+ * 本批落码：append 七步流水线（词汇/信封/快照冻结/预算刀/尾部追加/入队回调）
+ * + surfaceOp 遮蔽（appendWithSurfaceOp 正门 + 边缘纪律执法）+ 投影（derive/
+ * FoldState 增量/occludedSeqs）+ 崩溃恢复（recoverClosers 合成）+ fork 前缀
+ * 种子（forkPrefix/slicePrefix/ensureSeeded）+ 导入四闸。
+ * 物理落盘（write-behind 批落/SQLite）在 persist（L2，依赖本模块）；ctx.sessions
+ * 只读服务面随 host 装配批接线。
+ */
+import './codes.js';
+export { SessionLog } from './session.js';
+export * from './snapshot.js';
+export * from './budget.js';
+export { createFoldState, stepFold, snapshotProjection, applyOcclusion, occludedSeqs, deriveMessages, projectedJsonChars, } from './derive.js';
+export { recoverClosers, firstSeqBreak, TOOL_NOT_STARTED, TOOL_OUTCOME_UNKNOWN } from './recover.js';
+export { forkPrefix, slicePrefix, isSeededPrefix } from './fork.js';
+export { parseImportFile, vocabularyGate, pairingGate, SessionSpawnLimiter, runImportGates } from './import-gates.js';

package/dist/session/recover.js

@@ -0,0 +1,103 @@
+/** 孤儿 tool/call 的占位语义码（05 §4——按「崩溃前是否已开始执行」二分） */
+export const TOOL_NOT_STARTED = 'TOOL_NOT_STARTED';
+export const TOOL_OUTCOME_UNKNOWN = 'TOOL_OUTCOME_UNKNOWN';
+/**
+ * 配对扫描 + closer 合成（单遍从头扫——05 §4 步 5「配对完整性是全日志属性，
+ * 不设窗口；增量恢复优化不做，正确性面前不省这点」）：
+ *  - 孤儿 tool/call（有 call 无 result）：合成 tool/result——执行证据 =
+ *    守门 gate/decision 是否在场（在场 = 已开始执行 OUTCOME_UNKNOWN / 缺席 =
+ *    NOT_STARTED）。gate/decision 按全日志 toolCallId 索引（决策可能晚于崩溃
+ *    前最后一刻才落——全日志扫描是保守完备面）；
+ *  - 未闭合压缩对（compaction/start 无 end）：合成 compaction/end
+ *    （reason='aborted'）——孤 start 与孤儿摘要（摘要已落、遮蔽指令未落）
+ *    两子形态都收形；孤儿摘要是合法 surface 事件无需处置（按普通
+ *    user/message 同视）；
+ *  - 未闭合 turn：合成 turn/end（reason='interrupted'）——嵌套场景按深度
+ *    补 N 条（05 §4 步 4 深度计数）。
+ * 合成序：result 们 → compaction/end 们 → turn/end 们（日志合法性：turn
+ * 闭合必后于其内一切内容）。
+ */
+export function recoverClosers(events) {
+    // gate/decision 的 toolCallId 索引（执行证据位——按 data.toolCallId 字段）
+    const gatedCallIds = new Set();
+    // tool 配对状态：call 出现序记录 id；result 到达即摘
+    const pendingCallIds = [];
+    const settledCallIds = new Set();
+    // 压缩对状态：start 计数（end 到达减计；嵌套压缩不合法但容错计数）
+    let compactionDepth = 0;
+    // turn 深度计数
+    let turnDepth = 0;
+    for (const event of events) {
+        switch (event.type) {
+            case 'tool/call': {
+                const id = event.data?.toolCallId;
+                if (typeof id === 'string')
+                    pendingCallIds.push(id);
+                break;
+            }
+            case 'tool/result': {
+                const id = event.data?.toolCallId;
+                if (typeof id === 'string')
+                    settledCallIds.add(id);
+                break;
+            }
+            case 'gate/decision': {
+                const id = event.data?.toolCallId;
+                if (typeof id === 'string')
+                    gatedCallIds.add(id);
+                break;
+            }
+            case 'compaction/start':
+                compactionDepth += 1;
+                break;
+            case 'compaction/end':
+                if (compactionDepth > 0)
+                    compactionDepth -= 1;
+                break;
+            case 'turn/start':
+                turnDepth += 1;
+                break;
+            case 'turn/end':
+                if (turnDepth > 0)
+                    turnDepth -= 1;
+                break;
+            default:
+                break;
+        }
+    }
+    // time 基准：最后一条真实事件的 time（日志空则 0——空日志无 closer 可言，防御位）
+    const lastTime = events.length > 0 ? events[events.length - 1].time : 0;
+    const drafts = [];
+    // ① 孤儿 tool/call → 合成 tool/result（对模型诚实占位——防 provider 拒绝未配对 tool_use）
+    for (const id of pendingCallIds) {
+        if (settledCallIds.has(id))
+            continue;
+        const outcome = gatedCallIds.has(id) ? TOOL_OUTCOME_UNKNOWN : TOOL_NOT_STARTED;
+        drafts.push({
+            type: 'tool/result',
+            data: { toolCallId: id, content: `${outcome}: session recovered before completion`, error: true },
+            time: lastTime,
+        });
+    }
+    // ② 未闭合压缩对 → 按深度合成 compaction/end（reason='aborted'——视为未发生，下次触发重做）
+    for (let i = 0; i < compactionDepth; i++) {
+        drafts.push({ type: 'compaction/end', data: { reason: 'aborted' }, time: lastTime });
+    }
+    // ③ 未闭合 turn → 按深度补 N 条 turn/end（reason='interrupted'）
+    for (let i = 0; i < turnDepth; i++) {
+        drafts.push({ type: 'turn/end', data: { reason: 'interrupted' }, time: lastTime });
+    }
+    return drafts;
+}
+/**
+ * 日志完整性预检（05 §4 步 1 的纯函数半边——seq 连续性；尾部残行 JSON 检测
+ * 属物理层读侧，persist 落码时接线）。撕裂尾截断由调用方按本函数结果处置。
+ * @returns 首个断点 seq（该位置事件 seq ≠ 期望值）——null = 连续
+ */
+export function firstSeqBreak(events) {
+    for (let i = 0; i < events.length; i++) {
+        if (events[i].seq !== i)
+            return i;
+    }
+    return null;
+}

package/dist/session/session.js

@@ -0,0 +1,279 @@
+/**
+ * 会话事件日志（05 篇 §1-§3——SessionLog：append 流水线/遮蔽校验/投影增量/读原语）。
+ *
+ * 纯逻辑层：物理落盘经构造注入的 onAppend 回调（write-behind 入队面——persist
+ * 实现注入，append 热路径零 I/O）；缺省回调 = 纯内存会话（CLI :memory: 诊断形态）。
+ * seq 连续性由「只在 append 尾部追加」结构保证（无独立序号分配器）。
+ */
+import { BaseError, getEventTypeMeta, isKnownEventType, } from '../contracts/index.js';
+import { applyEventBudget } from './budget.js';
+import { applyOcclusion, createFoldState, snapshotProjection, stepFold } from './derive.js';
+import { deepFreeze, snapshotJsonValue } from './snapshot.js';
+/**
+ * 会话事件日志实例（per-session）。三类写入口：
+ *  - append：普通追加（七步流水线）；
+ *  - appendSynthetic：恢复合成收形（time 复用最后真实事件——确定性标记）；
+ *  - appendWithSurfaceOp：装载面改投影历史的唯一正门（边缘纪律五条执法）。
+ */
+export class SessionLog {
+    sessionId;
+    lineage;
+    /** 日志本体（append-only；data 冻结态——外部拿到也改不动） */
+    log = [];
+    /** 增量投影状态（FoldState——投影的缓存而非第二事实源，可全量重放对账） */
+    fold = createFoldState();
+    onAppend;
+    clock;
+    warn;
+    constructor(options) {
+        this.sessionId = options.sessionId;
+        this.lineage = options.lineage;
+        this.onAppend = options.onAppend ?? (() => undefined);
+        this.clock = options.clock ?? (() => Date.now());
+        this.warn = options.warn ?? ((message) => console.error(message));
+        if (options.seed && options.seed.length > 0) {
+            // 种子前缀：重放折叠（投影增量与日志同建）；seq 连续性顺带断言
+            for (const event of options.seed) {
+                if (event.seq !== this.log.length) {
+                    throw new BaseError('SESSION_SURFACE_OP_INVALID', `种子前缀 seq 不连续：期望 ${this.log.length} 实得 ${event.seq}（裸拷贝不走正门）`);
+                }
+                this.log.push(event);
+                stepFold(this.fold, event);
+            }
+        }
+    }
+    /**
+     * append 七步流水线（05 §1.2）：
+     * ① 词汇检查（SESSION_UNKNOWN_EVENT_TYPE fail-loud）→ ② 信封注入（seq =
+     * log.length / time = clock）→ ③ data 单遍校验 + 快照拷贝 → ④ 预算刀裁腿
+     * （60KiB 内容帽 + errorMessage 2KiB 小帽；截断 warn 落账带码名义）→ ⑤ 事件
+     * 目录断言（运行测试面——两账当前合一于词汇注册表，07 篇门禁接线时拆静态
+     * 目录账，本步留结构位）→ ⑥ 尾部追加 → ⑦ write-behind 入队回调。
+     */
+    append(type, data, options) {
+        // ① 词汇检查
+        if (!isKnownEventType(type)) {
+            throw new BaseError('SESSION_UNKNOWN_EVENT_TYPE', `事件类型 ${type} 未注册（词汇注册表单源——先经核心表或 registerEventType）`);
+        }
+        // ③-a 单遍校验 + 快照拷贝（非法载荷 fail-loud）
+        const snapshot = snapshotJsonValue(data, 'data');
+        // ④ 预算刀（裁腿产新对象；原 data 不动——纯函数面）
+        const budgeted = applyEventBudget(type, snapshot);
+        if (budgeted.truncated) {
+            this.warn(`[SESSION_EVENT_OVER_BUDGET] ${this.sessionId} seq#${this.log.length} ${type} 超预算截断降级`);
+        }
+        // ③-b 冻结（裁后终态冻结——「写入后不可变」；步序上冻结在裁后语义等价）
+        const frozen = deepFreeze(budgeted.data);
+        // ② 信封注入
+        const event = {
+            type,
+            seq: this.log.length,
+            time: options?.time ?? this.clock(),
+            data: frozen,
+            ...(options?.ignorable !== undefined ? { ignorable: options.ignorable } : {}),
+            ...(options?.surfaceOp ? { surfaceOp: options.surfaceOp } : {}),
+            ...(options?.sourceEventSeqs ? { sourceEventSeqs: [...options.sourceEventSeqs] } : {}),
+        };
+        // ⑥ 尾部追加 + 投影增量步进
+        this.log.push(event);
+        stepFold(this.fold, event);
+        // ⑦ write-behind 入队
+        this.onAppend(event);
+        return event;
+    }
+    /**
+     * 恢复合成收形（05 §4）：recoverClosers 产出的草稿经此入口 append——time
+     * 复用最后真实事件（确定性标记的合成面）。其余流水线与 append 同（词汇/
+     * 校验/冻结——合成物同权入日志）。
+     */
+    appendSynthetic(draft) {
+        return this.append(draft.type, draft.data, { time: draft.time });
+    }
+    /**
+     * 装载面改投影历史的唯一正门（05 §2.1 appendWithSurfaceOp / §2.4 retry 形）：
+     * 与 compaction 内部同一校验同一码（SESSION_SURFACE_OP_INVALID）——不是绕道口。
+     * 两形在载体上分流（05 §2.4 retry 区间合法规约）：载体 = `llm/retry` 走
+     * retry 形分支（三判据换轨——起点=错误 assistant / call 尸体豁免 /
+     * 尾=高水位+含 turn/end）；其余载体走通用形。共用前置四条两形同执法
+     * （成对写序由调用方编排——compaction 五步骨架）：
+     *  - 区间合法 + 溯源完整（sourceEventSeqs 覆盖区间全部 seq 且只引用更早 seq）；
+     *  - 不遮带 surfaceOp 的事件（防嵌套遮蔽）；
+     *  - 同一位置不二次遮蔽（与既有遮蔽区间不相交）；
+     * 通用形另执法两条：
+     *  - 不遮进行中 turn（tool 配对完整性表检查——区间内每个 call 的配对 result
+     *    也在区间内、反之亦然；无对可切、放行）；
+     *  - 区间起点对齐 turn 边界（start = 0 / 首条为 turn/start / 紧接上次遮蔽终点）。
+     */
+    appendWithSurfaceOp(type, data, surfaceOp, sourceEventSeqs) {
+        this.validateSurfaceOp(type, data, surfaceOp, sourceEventSeqs);
+        const event = this.append(type, data, { surfaceOp, sourceEventSeqs });
+        // 增量遮蔽摘除（chars 减法腿）——指令事件自身在区间外（半开区间语义，
+        // 「遮蔽者不可被自己遮蔽」由不遮带 surfaceOp 事件条保证）
+        applyOcclusion(this.fold, surfaceOp);
+        return event;
+    }
+    /**
+     * 遮蔽指令校验（边缘纪律执法——appendWithSurfaceOp 与 compaction 内部共用）。
+     * 两形分流（05 §2.4）：载体 `llm/retry` 走 retry 形（三判据换轨，通用形
+     * 的起点对齐与 call 侧配对两判据对其豁免）；其余载体走通用形。共用前置
+     * 四条（区间合法 / 溯源完整 / 防嵌套 / 不二次遮蔽）在分流前同执法。
+     */
+    validateSurfaceOp(type, data, op, sourceEventSeqs) {
+        if (!(Number.isInteger(op.start) &&
+            Number.isInteger(op.end) &&
+            op.start >= 0 &&
+            op.start <= op.end &&
+            op.end < this.log.length)) {
+            throw new BaseError('SESSION_SURFACE_OP_INVALID', `遮蔽区间非法：[${op.start},${op.end}]（当前日志长度 ${this.log.length}）`);
+        }
+        // 溯源完整：sourceEventSeqs 须覆盖 [start,end] 全部 seq，且只能引用更早 seq
+        const nextSeq = this.log.length;
+        const required = new Set();
+        for (let seq = op.start; seq <= op.end; seq++)
+            required.add(seq);
+        for (const seq of sourceEventSeqs ?? []) {
+            if (!(Number.isInteger(seq) && seq >= 0 && seq < nextSeq)) {
+                throw new BaseError('SESSION_SURFACE_OP_INVALID', `溯源引用了非法 seq：${seq}（须为 0..${nextSeq - 1}）`);
+            }
+            required.delete(seq);
+        }
+        if (required.size > 0) {
+            throw new BaseError('SESSION_SURFACE_OP_INVALID', `溯源不完整：sourceEventSeqs 未覆盖被遮蔽区间 seq ${[...required].sort((a, b) => a - b).join(', ')}`);
+        }
+        // 防嵌套 + 不二次遮蔽：区间内事件不得携带 surfaceOp，且与既有遮蔽区间不相交
+        const occluded = new Set();
+        for (const event of this.log) {
+            if (event.surfaceOp) {
+                for (let seq = event.surfaceOp.start; seq <= event.surfaceOp.end; seq++)
+                    occluded.add(seq);
+            }
+        }
+        for (let seq = op.start; seq <= op.end; seq++) {
+            if (occluded.has(seq)) {
+                throw new BaseError('SESSION_SURFACE_OP_INVALID', `seq ${seq} 已被遮蔽（不二次遮蔽/不嵌套遮蔽）`);
+            }
+            if (this.log[seq].surfaceOp) {
+                throw new BaseError('SESSION_SURFACE_OP_INVALID', `seq ${seq} 自身携带 surfaceOp（遮蔽者不可被遮蔽——防嵌套）`);
+            }
+        }
+        // tool 配对位置表（两形的配对执法共用）：按 toolCallId 建 call/result
+        // 全日志位置表
+        const callAt = new Map();
+        const resultAt = new Map();
+        for (let i = 0; i < this.log.length; i++) {
+            const data = this.log[i].data;
+            const id = data && typeof data === 'object' && typeof data.toolCallId === 'string' ? data.toolCallId : undefined;
+            if (id === undefined)
+                continue;
+            if (this.log[i].type === 'tool/call')
+                callAt.set(id, i);
+            else if (this.log[i].type === 'tool/result')
+                resultAt.set(id, i);
+        }
+        const inRange = (seq) => seq >= op.start && seq <= op.end;
+        // —— retry 形分支（05 §2.4 retry 区间合法规约：载体限定 llm/retry，三判据换轨）——
+        if (type === 'llm/retry') {
+            // 相位限定：surfaceOp 只许 phase=scheduled 携带（aborted/exhausted 是
+            // 事后事实事件，不携遮蔽指令）
+            const phase = data?.phase;
+            if (phase !== 'scheduled') {
+                throw new BaseError('SESSION_SURFACE_OP_INVALID', `llm/retry 携带 surfaceOp 须 phase=scheduled（当前 ${String(phase)}）`);
+            }
+            // 起点判据：区间首条为 stopReason=error 的 assistant/message——失败 turn
+            // 的尸体起点不是 turn 边界（通用形起点对齐对本形豁免）
+            const first = this.log[op.start];
+            const firstData = first.data;
+            if (first.type !== 'assistant/message' || firstData?.stopReason !== 'error') {
+                throw new BaseError('SESSION_SURFACE_OP_INVALID', `retry 遮蔽区间起点须为 stopReason=error 的 assistant/message（seq ${op.start} 是 ${first.type}）`);
+            }
+            // 尾=高水位：区间尾为追加时点日志末条 seq——盖住失败 turn 一切残余
+            // （伴生尸体与垫底的 turn/end、零笔 llm/usage）
+            if (op.end !== this.log.length - 1) {
+                throw new BaseError('SESSION_SURFACE_OP_INVALID', `retry 遮蔽区间尾须为日志高水位 ${this.log.length - 1}（当前 ${op.end}）`);
+            }
+            // 区间含 turn/end：未结算 turn 不可遮（turn 已收形是重试判定的前置）
+            let settled = false;
+            for (let seq = op.start; seq <= op.end; seq++) {
+                if (this.log[seq].type === 'turn/end') {
+                    settled = true;
+                    break;
+                }
+            }
+            if (!settled) {
+                throw new BaseError('SESSION_SURFACE_OP_INVALID', 'retry 遮蔽区间内未含 turn/end（未结算 turn 不可遮）');
+            }
+            // 配对执法（单向）：result 侧照旧——区间内 result 的配对 call 不得在
+            // 区间外（起点不得切在配对中间）；call 侧豁免——区间内未配对 tool/call
+            // 是流中断尸体，恰是要盖住的对象
+            for (const [id, resultSeq] of resultAt) {
+                const callSeq = callAt.get(id);
+                if (inRange(resultSeq) && callSeq !== undefined && !inRange(callSeq)) {
+                    throw new BaseError('SESSION_SURFACE_OP_INVALID', `tool 配对被切断：result@${resultSeq}（${id}）的 call@${callSeq} 在区间外`);
+                }
+            }
+            return;
+        }
+        // —— 通用形：tool 配对完整性（不遮进行中 turn——切点永不落在配对中间）——
+        // 区间内每个 call 的配对 result 必在区间内、区间内每个 result 的配对
+        // call 必在区间内
+        for (const [id, callSeq] of callAt) {
+            const resultSeq = resultAt.get(id);
+            if (inRange(callSeq) && resultSeq !== undefined && !inRange(resultSeq)) {
+                throw new BaseError('SESSION_SURFACE_OP_INVALID', `tool 配对被切断：call@${callSeq}（${id}）的 result@${resultSeq} 在区间外`);
+            }
+        }
+        for (const [id, resultSeq] of resultAt) {
+            const callSeq = callAt.get(id);
+            if (inRange(resultSeq) && callSeq !== undefined && !inRange(callSeq)) {
+                throw new BaseError('SESSION_SURFACE_OP_INVALID', `tool 配对被切断：result@${resultSeq}（${id}）的 call@${callSeq} 在区间外`);
+            }
+        }
+        // 区间起点对齐 turn 单元边界：start = 0 / 首条为 turn/start（合成形）/
+        // start-1 为 turn/end（真实 driver 形——提交先落 user/message 后起 turn，
+        // 紧随闭合 turn 的切点即次 turn 单元首位；U4-3 装配批集成勘正——原两形
+        // 在真实日志形下永假致阈值路不可落账）/ 紧接上次遮蔽终点（连续压缩切点
+        // ——判据是既存遮蔽区间终点恰为 start-1，全日志扫描；prev 事件自身携带
+        // surfaceOp 的旧判据是死码：被遮蔽节点永不带遮蔽）
+        if (op.start !== 0) {
+            const first = this.log[op.start];
+            const afterTurnEnd = this.log[op.start - 1]?.type === 'turn/end';
+            const afterOcclusion = this.log.some((event) => event.surfaceOp?.end === op.start - 1);
+            if (first.type !== 'turn/start' && !afterTurnEnd && !afterOcclusion) {
+                throw new BaseError('SESSION_SURFACE_OP_INVALID', `区间起点 ${op.start} 未对齐 turn 边界（首条 ${first.type}；须 start=0 / turn/start / 紧随 turn/end / 紧接上次遮蔽终点）`);
+            }
+        }
+    }
+    /** 日志只读视图（外部不可 push——冻结数组视图语义由约定 + append-only 纪律保） */
+    events() {
+        return this.log;
+    }
+    /** 按类型过滤读（含 fromSeq 窗口参数）——插件只读面 ctx.sessions 的底层原语（05 §3.2） */
+    eventsOfType(type, opts) {
+        const from = opts?.fromSeq ?? 0;
+        return this.log.filter((event) => event.type === type && event.seq >= from);
+    }
+    /**
+     * 最后一条完整 turn 边界的 seq（05 §3.2——「进行中 turn」判定的单源：工具
+     * 配对、遮蔽边界、fork 边界共用）。词级过滤下标不得冒充位置——返回值必是
+     * 真实事件 seq；无闭合 turn 返回 -1。
+     */
+    lastClosedBoundary() {
+        for (let i = this.log.length - 1; i >= 0; i--) {
+            if (this.log[i].type === 'turn/end')
+                return this.log[i].seq;
+        }
+        return -1;
+    }
+    /** 投影快照（活缓冲折入拷贝尾——调用方可安全持有的独立数组） */
+    projection() {
+        return snapshotProjection(this.fold);
+    }
+    /** 投影字符数（阈值兜底判据查询面——FoldState.chars 读出） */
+    projectedChars() {
+        return this.fold.chars;
+    }
+    /** 事件类型元信息查询透传（诊断面——类别/归属消费） */
+    metaOf(type) {
+        return getEventTypeMeta(type);
+    }
+}

package/dist/session/snapshot.js

@@ -0,0 +1,107 @@
+/**
+ * 事件 data 快照与冻结（05 篇 §1.2 append 流水线步 3——JSON 快照冻结）。
+ *
+ * 单遍校验 + 拷贝：递归读一次即产出快照副本（getter 双读免疫），同时确保
+ * 结果是纯 JSON 值（可被 SQLite 与任何读侧无损序列化）。deepFreeze 冻结后
+ * 任何持有者都改不动事件日志里的数据——不可变性靠语言机制，不靠约定。
+ */
+import { BaseError } from '../contracts/index.js';
+/**
+ * 单遍 JSON 校验 + 快照拷贝。
+ * 仅接受 null / boolean / number(有限) / string / 纯对象 / 数组；
+ * undefined / function / symbol / bigint / NaN·Infinity / 类实例（Date、Map 等）
+ * / 循环引用一律拒绝（SESSION_EVENT_DATA_INVALID）。
+ * @param value 待校验的载荷
+ * @param path 诊断用字段路径（顶层传 'data'——报错可读定位到 'data.items[2]'）
+ * @returns 深拷贝快照（与原值再无引用共享）
+ */
+export function snapshotJsonValue(value, path) {
+    return snap(value, path, new Set());
+}
+/** 递归实现：ancestors 记录当前路径上的祖先对象，用于循环引用检测 */
+function snap(value, path, ancestors) {
+    // 原始值：null/boolean/string 直接过；number 必须有限（JSON.stringify 会把 NaN/Infinity 变 null——静默变性不可接受）
+    if (value === null || typeof value === 'boolean' || typeof value === 'string') {
+        return value;
+    }
+    if (typeof value === 'number') {
+        if (!Number.isFinite(value)) {
+            throw dataInvalid(path, 'number 必须有限（NaN/Infinity 不可序列化）');
+        }
+        return value;
+    }
+    // undefined 单列：成因句帮定位——可选链取值/条件展开把 undefined 织进载荷是
+    // 最常见病灶；JSON.stringify 对 undefined 属性静默丢键、稀疏数组变 null，
+    // durable 事件不可走「序列化时碰运气」路线
+    if (value === undefined) {
+        throw dataInvalid(path, 'undefined（展开对象携带了未定义字段——检查可选链/条件展开）');
+    }
+    // 显式拒绝的非 JSON 类型
+    if (typeof value === 'function' || typeof value === 'symbol' || typeof value === 'bigint') {
+        throw dataInvalid(path, `不允许的值类型：${typeof value}`);
+    }
+    if (typeof value !== 'object') {
+        throw dataInvalid(path, `不允许的值类型：${typeof value}`);
+    }
+    if (ancestors.has(value)) {
+        throw dataInvalid(path, '循环引用');
+    }
+    // 类实例（Date/Map/Set/自定义类）原型非 Object/Array 原型——拒绝（先转纯 JSON 结构再落账）
+    const proto = Object.getPrototypeOf(value);
+    const isPlainObject = proto === Object.prototype || proto === null;
+    const isPlainArray = Array.isArray(value) && proto === Array.prototype;
+    if (!isPlainObject && !isPlainArray) {
+        throw dataInvalid(path, '只接受纯对象/数组（类实例请先转纯 JSON 结构）');
+    }
+    ancestors.add(value);
+    try {
+        if (Array.isArray(value)) {
+            const out = new Array(value.length);
+            for (let i = 0; i < value.length; i++) {
+                out[i] = snap(value[i], `${path}[${i}]`, ancestors);
+            }
+            return out;
+        }
+        const out = {};
+        for (const key of Object.keys(value)) {
+            // 每个属性只读一次（snap 内完成校验+拷贝），属性描述符（getter 等）不会二次触发
+            out[key] = snap(value[key], `${path}.${key}`, ancestors);
+        }
+        return out;
+    }
+    finally {
+        ancestors.delete(value);
+    }
+}
+/** 统一的非法载荷报错构造 */
+function dataInvalid(path, why) {
+    return new BaseError('SESSION_EVENT_DATA_INVALID', `事件 data 非法于 ${path}：${why}`);
+}
+/**
+ * 深冻结（返回同引用）：递归 Object.freeze 数组与纯对象。
+ * 冻结的是快照副本，外部原对象不受影响；配合快照实现「写入后不可变」。
+ * 已访问节点用 WeakSet 跳过，防环形结构死循环（快照虽拒绝循环引用，本函数
+ * 亦服务于 fork 前缀等已知纯 JSON 面——防御性自足）。
+ */
+export function deepFreeze(value) {
+    freezeWalk(value, new WeakSet());
+    return value;
+}
+function freezeWalk(value, seen) {
+    if (value === null || typeof value !== 'object') {
+        return; // 原始值无需冻结
+    }
+    const obj = value;
+    if (seen.has(obj)) {
+        return; // 已访问（共享引用），跳过
+    }
+    seen.add(obj);
+    Object.freeze(obj);
+    for (const key of Object.keys(obj)) {
+        freezeWalk(obj[key], seen);
+    }
+}
+/** 序列化字节数（体积度量用；UTF-8 真实字节，中英文案一致对待。值域已由 snapshotJsonValue 保证纯 JSON） */
+export function jsonBytes(value) {
+    return Buffer.byteLength(JSON.stringify(value) ?? 'null', 'utf8');
+}