berry-agent 0.1.0-alpha.1

package/dist/sdk/security.js

@@ -0,0 +1,116 @@
+/**
+ * sdk/security — HTTP 面三防线判定器与 token 生成（批 13e-1；10.4 回环钉死
+ * 条款同律复用引证 + 03 §10.6 差异面④⑤ 扩集谓词）。
+ *
+ * 纯函数件：判定器零 IO 零依赖（传输实装 13e-2 在 node:http 挂点位消费），
+ * 词面单源如下——
+ * - 回环白名单三形：`127.0.0.1` / `localhost` / `[::1]`（带可选 `:port`）；
+ * - 非回环绑定形态 Host 扩集（差异面④）：校验值域与配置绑定地址匹配——
+ *   Host 主机部须恰等于绑定 host（大小写不敏感；IPv6 括号形同归一），
+ *   **不接受任意 Host**（DNS rebinding 防线原义保留——attacker 域名 ≠ 绑定
+ *   地址字面即拒）；回环绑定形态值域不变；
+ * - Origin 硬防线（10.4③）：带 Origin 且非同源三形 = 403；**无 Origin 头
+ *   放行**（防线判浏览器跨源，不判非浏览器客户端——SDK 调用方恒无 Origin）。
+ */
+import { createHash, randomBytes, timingSafeEqual } from 'node:crypto';
+/** 回环白名单主机三形（10.4② 值域穷举字面——回环绑定形态恒用此值域） */
+const LOOPBACK_HOSTS = new Set(['127.0.0.1', 'localhost', '[::1]']);
+/** 归一 Host 头主机部：剥可选 `:port`（IPv6 括号形内冒号不剥）+ 小写归一 */
+export function hostPartOf(hostHeader) {
+    const lower = hostHeader.toLowerCase();
+    // 括号 IPv6 形 `[::1]:7860` —— 只剥闭括号后的端口段
+    if (lower.startsWith('[')) {
+        const close = lower.indexOf(']');
+        if (close !== -1)
+            return lower.slice(0, close + 1);
+        return lower;
+    }
+    const colon = lower.indexOf(':');
+    return colon === -1 ? lower : lower.slice(0, colon);
+}
+/** 判定 host 是否回环三形之一（`::1` 裸形归一 `[::1]` 同判） */
+export function isLoopbackHost(host) {
+    const normalized = host.toLowerCase() === '::1' ? '[::1]' : host.toLowerCase();
+    return LOOPBACK_HOSTS.has(normalized);
+}
+/**
+ * Host 头白名单判定（三防线②——10.4 同律 + 差异面④ 扩集）。
+ * @param hostHeader 请求 Host 头原值（缺席/空串 = 拒——HTTP/1.1 Host 必在场）
+ * @param bindHost 配置绑定地址（回环三形或显式非回环地址）
+ */
+export function judgeHostHeader(hostHeader, bindHost) {
+    if (hostHeader === undefined || hostHeader === '') {
+        return { ok: false, reason: 'Host 头缺席（HTTP/1.1 必在场）' };
+    }
+    const part = hostPartOf(hostHeader);
+    if (isLoopbackHost(bindHost)) {
+        // 回环绑定形态：值域 = 回环穷举字面（差异面④「回环绑定形态值域不变」）
+        if (LOOPBACK_HOSTS.has(part))
+            return { ok: true };
+        return { ok: false, reason: `回环绑定形态只受回环 Host（收 ${part}）` };
+    }
+    // 非回环绑定形态：扩集谓词 = Host 主机部恰等于绑定地址（地址族匹配的严格形）
+    const bindNormalized = bindHost.toLowerCase() === '::1' ? '[::1]' : bindHost.toLowerCase();
+    const bindBracketed = bindNormalized.includes(':') && !bindNormalized.startsWith('[') ? `[${bindNormalized}]` : bindNormalized;
+    if (part === bindNormalized || part === bindBracketed)
+        return { ok: true };
+    return { ok: false, reason: `非回环绑定形态只受绑定地址 Host（收 ${part} 期 ${bindNormalized}）` };
+}
+/**
+ * Origin 硬防线判定（三防线③——10.4 同律）。同源三形 = 监听回环三形 +
+ * 监听端口（sdk 面 scheme 恒 http）；**无 Origin 放行**（程序调用方）。
+ */
+export function originAllowed(origin, listenHost, listenPort) {
+    if (origin === undefined || origin === '')
+        return true; // 防线判浏览器跨源
+    // 回环绑定形态：同源三形 = 回环穷举（值域与 Host 白名单对称——10.4③）
+    const sameOrigin = new Set([
+        `http://127.0.0.1:${listenPort}`,
+        `http://localhost:${listenPort}`,
+        `http://[::1]:${listenPort}`,
+    ]);
+    if (isLoopbackHost(listenHost) && sameOrigin.has(origin))
+        return true;
+    // 非回环绑定形态：同源 = scheme://绑定地址:端口 恰等（与 Host 扩集同族）
+    const host = listenHost.toLowerCase();
+    const bracketed = host === '::1' ? '[::1]' : host.includes(':') && !host.startsWith('[') ? `[${host}]` : host;
+    return origin === `http://${bracketed}:${listenPort}`;
+}
+/**
+ * 生成一次性 token（10.4 token 鉴权件本体保证同律：32 字节随机 hex、只存
+ * 内存不落盘——披露面归宿主形态）。
+ */
+export function generateToken() {
+    return randomBytes(32).toString('hex');
+}
+/**
+ * token 常时验换（18a-1'——03 §10.6 路由扩展位 helper `verifyToken` 执法位）：
+ * sha256 摘要恒长 + timingSafeEqual——任意长度输入先归一到 32 字节摘要再比对，
+ * 码位长度泄露面封死（`/v1/*` Bearer 判由此自字符串直比升常时比对——有意
+ * 行为增强注记，同条款）。
+ */
+export function verifyTokenConstantTime(actual, expected) {
+    const a = createHash('sha256').update(actual).digest();
+    const b = createHash('sha256').update(expected).digest();
+    return timingSafeEqual(a, b);
+}
+/**
+ * 启动断言（三防线①——差异面③ fail-closed 拒启律不豁免）：非回环 TCP 绑定
+ * 必配预置凭证；违例即拒启（daemon 形退 2——07 §5 定名注）。收整个开面配置
+ * 形（socketPath 无关判定——只审 TCP 侧与凭证位）。TCP 侧单形/数组归一逐项
+ * 判（18a-1' 多监听并存——一票非回环无凭证即整面拒启）。
+ */
+export function judgeListenConfig(config) {
+    if (config.tcp === undefined)
+        return { ok: true };
+    const specs = Array.isArray(config.tcp) ? config.tcp : [config.tcp];
+    for (const spec of specs) {
+        if (!isLoopbackHost(spec.host) && (config.token === undefined || config.token === '')) {
+            return {
+                ok: false,
+                reason: `非回环绑定（${spec.host}）必配鉴权凭证 BERRY_AGENT_SDK_TOKEN——fail-closed 拒启（03 §10.6 差异面③）`,
+            };
+        }
+    }
+    return { ok: true };
+}

package/dist/sdk/types.js

@@ -0,0 +1,32 @@
+/** HTTP 端点路由词面（03 §10.6 差异面①/批 13e 定形：程序调用面五 POST/GET + SSE 建立位） */
+export const SDK_HTTP_ENDPOINTS = {
+    /** POST——prompt 新发（sessionId 缺席即新建） */
+    prompt: '/v1/prompt',
+    /** POST——interrupt（无应答档 HTTP 形 = 204 空体） */
+    interrupt: '/v1/interrupt',
+    /** POST——审批应答（跨入口竞速回执） */
+    decide: '/v1/decide',
+    /** POST——断线对账读面（since 窗口 (since, 高水位]） */
+    entries: '/v1/entries',
+    /** GET——会话清单 */
+    sessions: '/v1/sessions',
+    /** GET SSE——事件流建立位（即 hello 动词的 HTTP 承载：sessionId/after/noDelta 入查询参） */
+    events: '/v1/events',
+};
+/** 协议版本头名（HTTP 无连接级 hello 位——每请求携版本，不符即 400 SDK_PROTOCOL_MISMATCH） */
+export const SDK_PROTOCOL_HEADER = 'x-sdk-protocol';
+/** 鉴权头（10.4「监听 ⇒ 鉴权」恒在场——Bearer 形携 token） */
+export const SDK_AUTH_HEADER = 'authorization';
+/** 心跳看门狗节拍（10.4 同律：SSE 注释行 ping 每 30s + 写侧 90s 判死） */
+export const SDK_SSE_PING_INTERVAL_MS = 30_000;
+/** SSE 写侧看门狗判死窗（ping 写失败或写超时即 reap 连接——读侧判死不可实施） */
+export const SDK_SSE_WRITE_TIMEOUT_MS = 90_000;
+/* ---------------- 路由扩展位契约（18a-1'；03 §10.6 路由扩展位段——2026-09-07 webui 插件化批） ---------------- */
+/**
+ * open 档合法语义位闭集（射界枚举钉死——注册期白名单校验、越界即拒 fail-loud，
+ * 代码可执法非仅冷读审读）：
+ * - `liveness`——探活（GET /api/health 形：零敏感面应答）；
+ * - `auth-exchange`——鉴权换证（POST /api/auth 形：token 换 cookie 桥）；
+ * - `static-shell`——静态壳（SPA 静态面 + fallback：壳先于鉴权必须可载）。
+ */
+export const SDK_ROUTE_OPEN_PURPOSES = ['liveness', 'auth-exchange', 'static-shell'];

package/dist/session/budget.js

@@ -0,0 +1,159 @@
+/** 内容腿预算（字节）：60KiB——05 §1.2 步 4 单级设计（berry-agent 规范再设计，非 berry 两级） */
+export const EVENT_BUDGET_BYTES = 60 * 1024;
+/** errorMessage 腿小帽（字节）：与 content 腿各自独立计帽——防同源双载叠加击穿（05 §1.1 assistant/message 表注） */
+export const ERROR_MESSAGE_BUDGET_BYTES = 2 * 1024;
+/** 字符串的护栏同尺体积（与 jsonBytes 同式：JSON.stringify 的转义后字节——两把尺同单位） */
+export function escapedBytes(text) {
+    return Buffer.byteLength(JSON.stringify(text), 'utf8');
+}
+/**
+ * 字符串按「护栏同尺」字节预算截断（超预算加尾标记；不超原样返回）。
+ * 尾标记形态 = `…[truncated N chars]`（N = 截掉字符数——05 §1.2 步 4 字面）。
+ */
+export function budgetString(text, budget = EVENT_BUDGET_BYTES) {
+    if (escapedBytes(text) <= budget)
+        return text;
+    // 转义只增不减：原文截到 budget 字节是安全上界（转义后 ≤ 原文 × 截点）
+    let sliced = Buffer.from(text, 'utf8').subarray(0, budget).toString('utf8');
+    // 收敛循环：截段+尾标记的转义体积压进预算。按超限比例收缩（几何收敛——
+    // 控制字符 6x 形态一轮即近界），近界后逐字符兜底（subarray 可能切在多字节
+    // 字符中间，toString 对坏尾替换 U+FFFD——可接受且不影响收敛）
+    while (escapedBytes(sliced) + escapedBytes(marker(text.length - sliced.length)) > budget) {
+        sliced = sliced.slice(0, Math.max(sliced.length - 1, 0));
+        if (sliced.length === 0)
+            break;
+    }
+    return sliced + marker(text.length - sliced.length);
+}
+/** 截断尾标记（N = 截掉的 UTF-16 码点数） */
+function marker(truncatedChars) {
+    return `…[truncated ${truncatedChars} chars]`;
+}
+/** 单块体积（截断预算的计量单位；image 按 base64 字符串长度近似——base64 字母表无转义字符，转义前后等长） */
+function blockBytes(block) {
+    switch (block.type) {
+        case 'text':
+            return escapedBytes(block.text);
+        case 'thinking':
+            return escapedBytes(block.thinking);
+        case 'image':
+            return block.data.length;
+    }
+}
+/**
+ * 内容腿截断（块数组形态：逐块累加判断——多腿同源叠加击穿的防线；text/thinking
+ * 块按剩余预算截字节加尾标记，image 块放不下剩余预算时落 image-blob-dropped
+ * 占位——base64 动辄超帽，保留语义不保像素，05 §1.2 步 4）。
+ * 纯字符串形态（user 消息）：整串按字节截。
+ */
+export function truncateContent(content, budget = EVENT_BUDGET_BYTES) {
+    if (typeof content === 'string') {
+        return budgetString(content, budget);
+    }
+    // 快路径：总字节在预算内直接通过（绝大多数消息零开销）
+    let total = 0;
+    for (const block of content) {
+        total += blockBytes(block);
+    }
+    if (total <= budget)
+        return content;
+    const out = [];
+    let remaining = budget;
+    for (const block of content) {
+        if (block.type === 'image') {
+            if (block.data.length <= remaining) {
+                // 预算容得下：保留像素（快路径外的少数小图）
+                out.push(block);
+                remaining -= block.data.length;
+                continue;
+            }
+            // 放不下 → 占位（事件日志是审计面非媒体库）
+            out.push({ type: 'text', text: '[image-blob-dropped: durable budget]' });
+            remaining = 0;
+            continue;
+        }
+        // text / thinking：按剩余预算截字节（度量与判定同尺——转义后体积）
+        const text = block.type === 'text' ? block.text : block.thinking;
+        const size = escapedBytes(text);
+        if (size <= remaining) {
+            out.push(block);
+            remaining -= size;
+            continue;
+        }
+        if (remaining > 0) {
+            const marked = budgetString(text, remaining);
+            out.push(block.type === 'text' ? { type: 'text', text: marked } : { type: 'thinking', thinking: marked });
+            remaining = 0;
+        }
+        // 预算耗尽后的剩余 text/thinking 块整块丢弃（尾标记已声明截断事实）
+    }
+    return out;
+}
+/**
+ * append 流水线步 4 入口：按事件类型分派裁腿（单遍、只查不改原值）。
+ * 分派表（05 §1.2 步 4）：
+ *  - user/message / assistant/message：截 content（块数组逐块累加）；
+ *  - assistant/message 的 errorMessage 腿独立 2KiB 小帽；
+ *  - tool/call：截 arguments（原始字符串）；
+ *  - tool/result：截 content；
+ *  - 其余类型超帽：data 整体截断加尾标记（序列化为带尾标记的字符串——最后
+ *    手段的可观测降级，优先保可读）。
+ */
+export function applyEventBudget(type, data) {
+    if (data === null || typeof data !== 'object') {
+        // 原始值形态（含空对象快照类）：整体体积由护栏语义覆盖，无腿可裁——原样过
+        return { data, truncated: false };
+    }
+    const record = data;
+    switch (type) {
+        case 'user/message':
+        case 'tool/result': {
+            const content = record.content;
+            if (typeof content === 'string' || Array.isArray(content)) {
+                const clipped = truncateContent(content);
+                return clipped === content
+                    ? { data, truncated: false }
+                    : { data: { ...record, content: clipped }, truncated: true };
+            }
+            return { data, truncated: false };
+        }
+        case 'assistant/message': {
+            let changed = false;
+            const next = { ...record };
+            if (typeof record.content === 'string' || Array.isArray(record.content)) {
+                const clipped = truncateContent(record.content);
+                if (clipped !== record.content) {
+                    next.content = clipped;
+                    changed = true;
+                }
+            }
+            // errorMessage 腿独立小帽（与 content 各自计帽——同源双载防线）
+            if (typeof record.errorMessage === 'string') {
+                const clipped = budgetString(record.errorMessage, ERROR_MESSAGE_BUDGET_BYTES);
+                if (clipped !== record.errorMessage) {
+                    next.errorMessage = clipped;
+                    changed = true;
+                }
+            }
+            return { data: changed ? next : data, truncated: changed };
+        }
+        case 'tool/call': {
+            const args = record.arguments;
+            if (typeof args === 'string') {
+                const clipped = budgetString(args);
+                return clipped === args
+                    ? { data, truncated: false }
+                    : { data: { ...record, arguments: clipped }, truncated: true };
+            }
+            return { data, truncated: false };
+        }
+        default: {
+            // 其余类型：data 整体截断（序列化字符串 + 尾标记——保留前段可读）
+            const serialized = JSON.stringify(data);
+            if (serialized === undefined || escapedBytes(serialized) <= EVENT_BUDGET_BYTES) {
+                return { data, truncated: false };
+            }
+            return { data: budgetString(serialized), truncated: true };
+        }
+    }
+}

package/dist/session/codes.js

@@ -0,0 +1,40 @@
+/**
+ * session 模块域错误码注册（05 篇会话与存储——append 流水线/遮蔽/导入/fork 各执法点）。
+ *
+ * contracts CORE_ERROR_CODES 已含三枚（第一批）：SESSION_UNKNOWN_EVENT_TYPE
+ * （词汇检查）/ SESSION_EVENT_OVER_BUDGET（预算刀身份码——裁腿不抛、warn 落账
+ * 带码标识）/ SESSION_CORE_TYPE_FORBIDDEN（核心词身份双闸）。本文件补域内五枚。
+ */
+import { registerErrorCodes } from '../contracts/index.js';
+registerErrorCodes([
+    // 05 §1.2 步 3：data 单遍校验——非法载荷 fail-loud（undefined 织进载荷/类实例/循环引用等）
+    {
+        code: 'SESSION_EVENT_DATA_INVALID',
+        module: 'session',
+        description: '事件 data 非法（非纯 JSON 值：undefined/function/symbol/bigint/NaN·Infinity/类实例/循环引用）',
+    },
+    // 05 §2.1 边缘纪律五条执法：appendWithSurfaceOp 与 compaction 内部同一码
+    {
+        code: 'SESSION_SURFACE_OP_INVALID',
+        module: 'session',
+        description: '遮蔽指令非法（区间越界/溯源不完整/切在 tool 配对中间/二次遮蔽/嵌套遮蔽）',
+    },
+    // 05 §5.1 身份闸：导入文件自描述不认识即拒载
+    {
+        code: 'SESSION_IMPORT_BAD_FORMAT',
+        module: 'session',
+        description: '导入文件格式不认识（自描述格式版本/导出器标识缺或未知）',
+    },
+    // 05 §5.1 洪水闸：会话增生限流（首版 100/分钟）——码名已裁（2026-09-05 拍板题 15：沿用此名，改名收益不抵扫引成本）
+    {
+        code: 'SESSION_SPAWN_RATE_LIMIT',
+        module: 'session',
+        description: '会话增生限流触发（单进程单位时间导入/fork 新建会话数超帽）',
+    },
+    // 05 §5.1：persist:false（内存会话）上调 forkSession/导入——fork 语义需要物理新会话
+    {
+        code: 'SESSION_PERSISTENCE_REQUIRED',
+        module: 'session',
+        description: '该操作需要持久化会话（内存会话不支持 fork/导入——静默降级为拷贝 = 语义谎言）',
+    },
+]);

package/dist/session/derive.js

@@ -0,0 +1,180 @@
+/** 新建空 fold 状态（增量缓存的起点；全量 fold 内部同用） */
+export function createFoldState() {
+    return { messages: [], chars: 0, openAssistant: null, pendingCalls: new Map() };
+}
+/**
+ * 单事件步进（就地修改 state）——全量 fold 与增量缓存共用的唯一转换函数。
+ * 遮蔽指令事件（携带 surfaceOp 的 compaction/surface 等）不在此处理：全量路
+ * 由 deriveMessages 以 occludedSeqs 预滤；增量路由 applyOcclusion 回溯摘除
+ * （见下——两路对遮蔽的处置不同但摘除语义单源于 occludedSeqs 的区间定义）。
+ */
+export function stepFold(state, event) {
+    switch (event.type) {
+        case 'user/message': {
+            // 遇用户输入先冲刷打开中的 assistant（消息序保真：assistant 在 user 前）
+            flushAssistant(state);
+            const data = event.data;
+            pushMessage(state, {
+                type: 'user',
+                seq: event.seq,
+                content: data.content,
+                ...(data.source !== undefined ? { source: data.source } : {}),
+            });
+            return;
+        }
+        case 'assistant/message': {
+            // 同一 turn 内多条 assistant/message：先冲刷上一条（罕见，容错处理）
+            flushAssistant(state);
+            const data = event.data;
+            state.openAssistant = {
+                seq: event.seq,
+                content: data.content,
+                usage: data.usage,
+                stopReason: data.stopReason,
+                ...(data.errorMessage !== undefined ? { errorMessage: data.errorMessage } : {}),
+                toolCalls: [],
+            };
+            return;
+        }
+        case 'tool/call': {
+            const data = event.data;
+            // 工具调用归属同响应的 assistant 消息；若无打开缓冲（日志残缺），补一个空缓冲兜底
+            if (!state.openAssistant) {
+                state.openAssistant = { seq: event.seq, content: [], toolCalls: [] };
+            }
+            state.openAssistant.toolCalls.push({
+                type: 'toolCall',
+                toolCallId: data.toolCallId,
+                toolName: data.name,
+                arguments: data.arguments,
+            });
+            state.pendingCalls.set(data.toolCallId, { name: data.name, arguments: data.arguments });
+            return;
+        }
+        case 'tool/result': {
+            // 工具结果消息排在 assistant（含其全部 toolCall 块）之后
+            flushAssistant(state);
+            const data = event.data;
+            const call = state.pendingCalls.get(data.toolCallId);
+            state.pendingCalls.delete(data.toolCallId);
+            pushMessage(state, {
+                type: 'toolResult',
+                seq: event.seq,
+                toolCallId: data.toolCallId,
+                toolName: call?.name ?? '',
+                ...(call ? { arguments: call.arguments } : {}),
+                output: data.content,
+                isError: data.error !== undefined,
+            });
+            return;
+        }
+        default:
+            // turn 边界 / request/header / todo/write / log-only 全部不产出消息：
+            // todo/write 的模型可见性走「跨 turn 每轮注入当前全表」通道（04 篇），
+            // 此处落日志供 UI 投影与注入器读取。
+            return;
+    }
+}
+/** 折出消息入 state（chars 同步累加——可加性的写入点） */
+function pushMessage(state, message) {
+    state.messages.push(message);
+    state.chars += JSON.stringify(message).length;
+}
+/** 冲刷打开中的 assistant 缓冲为一条投影消息（无缓冲则无事发生） */
+function flushAssistant(state) {
+    if (!state.openAssistant) {
+        return;
+    }
+    const buf = state.openAssistant;
+    pushMessage(state, {
+        type: 'assistant',
+        seq: buf.seq,
+        content: buf.content,
+        toolCalls: [...buf.toolCalls],
+        usage: buf.usage,
+        stopReason: buf.stopReason,
+        ...(buf.errorMessage !== undefined ? { errorMessage: buf.errorMessage } : {}),
+    });
+    state.openAssistant = null;
+}
+/**
+ * 投影快照发布：拷贝 state.messages + 把 pending assistant 缓冲折成消息
+ * **追加进拷贝**——活态零改动（缓冲继续接收迟到 tool/call，下次推进自然冲刷
+ * 进活数组）。返回独立新数组，调用方可安全持有。
+ */
+export function snapshotProjection(state) {
+    const snapshot = [...state.messages];
+    if (state.openAssistant) {
+        const buf = state.openAssistant;
+        snapshot.push({
+            type: 'assistant',
+            seq: buf.seq,
+            content: buf.content,
+            toolCalls: [...buf.toolCalls],
+            usage: buf.usage,
+            stopReason: buf.stopReason,
+            ...(buf.errorMessage !== undefined ? { errorMessage: buf.errorMessage } : {}),
+        });
+    }
+    return snapshot;
+}
+/**
+ * 增量遮蔽摘除（05 §3.1「append 加、遮蔽减」的减法腿）：surfaceOp 指令事件
+ * append 后对活体 FoldState 的回溯处置——摘除 messages 中 seq ∈ [start,end]
+ * 的消息并回退 chars；pendingCalls / openAssistant 中锚在区间内的一并清理
+ * （边缘纪律保证遮蔽只落已闭合 turn，活缓冲理应为空——防御性自足）。
+ * 摘除消息的 chars 回退用同式 JSON.stringify——与 pushMessage 同一把尺。
+ */
+export function applyOcclusion(state, op) {
+    const inRange = (seq) => seq >= op.start && seq <= op.end;
+    if (state.messages.length > 0) {
+        const kept = [];
+        for (const message of state.messages) {
+            if (inRange(message.seq)) {
+                state.chars -= JSON.stringify(message).length;
+            }
+            else {
+                kept.push(message);
+            }
+        }
+        state.messages = kept;
+    }
+    if (state.openAssistant && inRange(state.openAssistant.seq)) {
+        state.openAssistant = null;
+    }
+    // pendingCalls 的 id 与事件 seq 的对应关系在 fold 内部无账——区间摘除后配对表
+    // 可能残留区间内 call 的条目（对应 tool/result 已摘，不会再被消费）；残留
+    // 条目不影响投影正确性（只是死键），会话重建（fork/恢复）时自然清零。
+}
+/** 计算被遮蔽的 seq 集合：遍历所有 surfaceOp 的 [start,end] 区间取并集 */
+export function occludedSeqs(events) {
+    const occluded = new Set();
+    for (const event of events) {
+        if (event.surfaceOp) {
+            for (let seq = event.surfaceOp.start; seq <= event.surfaceOp.end; seq++) {
+                occluded.add(seq);
+            }
+        }
+    }
+    return occluded;
+}
+/**
+ * 模型历史投影（05 §3.1）：日志减被遮蔽节点后 fold 出 ProjectedMessage 序列。
+ * 纯函数——同输入同输出；未配对的 tool/call（正常路径不存在——恢复协议保证
+ * 闭合）容错丢弃：其 toolCall 块保留在 assistant 消息内，但不产出悬空 toolResult。
+ */
+export function deriveMessages(events) {
+    const occluded = occludedSeqs(events);
+    const state = createFoldState();
+    for (const event of events) {
+        if (!occluded.has(event.seq)) {
+            stepFold(state, event);
+        }
+    }
+    flushAssistant(state);
+    return state.messages;
+}
+/** 投影字符数（阈值兜底判据的查询面——FoldState.chars 的只读读出） */
+export function projectedJsonChars(state) {
+    return state.chars;
+}

package/dist/session/event-data.js

@@ -0,0 +1 @@
+export {};

package/dist/session/fork.js

@@ -0,0 +1,72 @@
+/**
+ * 普通前缀拷贝：[0, upToSeq] 原样拷贝（seq 不重编——结构共享，data 已冻结
+ * 天然免拷贝）。end-seed 的 append 与 flush 屏障由调用方（SessionLog/host）编排。
+ * @param events 源日志（冻结态）
+ * @param upToSeq 前缀上界（含）；调用方负责边界合法性（缺省 lastClosedBoundary）
+ */
+export function forkPrefix(events, upToSeq) {
+    const out = [];
+    for (let i = 0; i <= upToSeq && i < events.length; i++) {
+        out.push(events[i]);
+    }
+    return out;
+}
+/**
+ * 中段前缀种子（第三形态 slice，05 §5.0——goal 续跑/导出再导入的「中段取种子」）：
+ * 取 [fromSeq, toSeq] 切片并从 0 重编 seq（日志内 seq 连续性是硬约束）；遮蔽
+ * 载体随种子走——surfaceOp 区间与 sourceEventSeqs 同步平移 fromSeq。
+ *
+ * 遮蔽跨界的保守语义（本实现补全，05 篇未细写）：遮蔽区间完全落在切片外
+ * （[0, fromSeq)）的指令事件整体丢弃（被遮蔽节点不在新日志内，指令失去对象）；
+ * 跨切点的区间截断到切点（部分遮蔽——遮蔽者不可越界遮到不存在的前史）；
+ * sourceEventSeqs 中指向切片前的引用过滤（溯源悬空不如溯源精简）。
+ */
+export function slicePrefix(events, fromSeq, toSeq) {
+    const out = [];
+    for (let i = fromSeq; i <= toSeq && i < events.length; i++) {
+        const event = events[i];
+        const op = event.surfaceOp;
+        if (!op) {
+            out.push(rewriteSeq(event, i - fromSeq));
+            continue;
+        }
+        // 遮蔽区间在新坐标系的位置
+        const newStart = Math.max(op.start - fromSeq, 0);
+        const newEnd = op.end - fromSeq;
+        if (newEnd < 0) {
+            // 区间整体在切片前——指令失去对象，丢弃（不拷贝本事件）
+            continue;
+        }
+        const seqs = event.sourceEventSeqs?.map((seq) => seq - fromSeq).filter((seq) => seq >= 0);
+        out.push({
+            ...rewriteSeq(event, i - fromSeq),
+            surfaceOp: { op: 'replace', start: newStart, end: newEnd },
+            ...(seqs !== undefined ? { sourceEventSeqs: seqs } : {}),
+        });
+    }
+    return out;
+}
+/** 重编 seq 的事件拷贝（其余字段引用共享——data 冻结态不可变） */
+function rewriteSeq(event, newSeq) {
+    return { ...event, seq: newSeq };
+}
+/**
+ * ensureSeeded（05 §5.1）：导入/fork 后新会话日志必须是合法种子前缀。
+ * 校验位 = **前缀尾条**（尾界标记在场且 seq 对齐 seedLength——end-seed 位于
+ * 前缀末尾而非开头，「以 end-seed 开头」字面不成立）；裸拷贝不走正门即断言失败。
+ * 切片形态（无 end-seed 尾条）以 seedLength 锚定校验（尾条 seq 恰 = seedLength - 1）。
+ * @returns 布尔判据（调用方决定 fail-loud 形态：导入闸抛 SESSION_IMPORT_BAD_FORMAT、
+ *   fork 断言直接炸）
+ */
+export function isSeededPrefix(events, seedLength, requireEndSeed) {
+    if (events.length !== seedLength)
+        return false;
+    if (seedLength === 0)
+        return !requireEndSeed; // 空前缀：仅无尾界要求时合法（新建会话）
+    const tail = events[seedLength - 1];
+    if (!tail || tail.seq !== seedLength - 1)
+        return false;
+    if (requireEndSeed && tail.type !== 'session/end-seed')
+        return false;
+    return true;
+}