berry-agent 0.1.0-alpha.1

package/dist/obs/session-view.js

@@ -0,0 +1,225 @@
+/** 树判定上溯帽深（防环/防长链——超帽 = 不可判 = 跨树 fail-closed） */
+const LINEAGE_MAX_DEPTH = 64;
+/** session_list 进程内清单帽（装配侧投影帽之外的服务侧二道帽） */
+const LIST_CAP = 100;
+/** session_read 尾窗缺省条数与硬帽（03 §10.8 e-2 定形注） */
+const TAIL_LIMIT_DEFAULT = 50;
+const TAIL_LIMIT_MAX = 200;
+/** session_trace 尾窗定值（「当前进行态」固定窗——无参数面） */
+const TRACE_WINDOW = 20;
+/**
+ * 尾条推导回扫窗（03 §10.8 obs-b 例外注）：压缩族词（compaction/*）是
+ * run 收场后的后台任务审计面——落账不改变会话粗状态，尾条为压缩族词时
+ * 回扫窗内最近一条非压缩族事件按其映射定档。窗 20 条 = 防御帽（真实流
+ * 压缩族连发至多数条——fire 前提是 settled，连续压缩族词间必夹 turn 事件）。
+ */
+const STATE_SCAN_WINDOW = 20;
+/** 呈现摘要文本截断帽（单行 200 字符——模型消费面有界） */
+const SUMMARY_MAX_CHARS = 200;
+/** request/header 尾查页帽（initial/resume/change 少量词——防御帽） */
+const HEADER_SCAN_LIMIT = 100;
+/** createSessionView 工厂（装载面/测试唯一入口） */
+export function createSessionView(deps) {
+    const workspaceRoot = deps.workspaceRoot ?? (() => undefined);
+    /**
+     * 尾条推导（lastSeq 精确定位——fromSeq 含边界取 1 条即尾行）。obs-b 例外
+     * （03 §10.8）：尾行为压缩族词时回扫窗内最近一条非压缩族事件——压缩审计
+     * 落账不改变粗状态（skip 的 cooldown/pending 门每轮收场可落，不回扫则
+     * idle 恒误报 running）；尾行非压缩族时行为与例外前逐字一致（write-behind
+     * 滞后 → undefined → idle 的保守语义不变）。窗内全压缩族（防御极端形）→
+     * undefined 兜底 idle。
+     */
+    const tailEvent = (row) => {
+        if (row.lastSeq < 0)
+            return undefined; // 零事件会话
+        const exact = deps.events.queryEvents({ sessionId: row.id, fromSeq: row.lastSeq, limit: 1 });
+        const tail = exact.events.at(-1);
+        if (tail === undefined || !tail.type.startsWith('compaction/'))
+            return tail;
+        const fromSeq = Math.max(0, row.lastSeq - (STATE_SCAN_WINDOW - 1));
+        const window = deps.events.queryEvents({ sessionId: row.id, fromSeq, limit: STATE_SCAN_WINDOW });
+        for (let i = window.events.length - 1; i >= 0; i -= 1) {
+            if (!window.events[i].type.startsWith('compaction/'))
+                return window.events[i];
+        }
+        return undefined;
+    };
+    /** 粗状态映射（文件头映射表的执法位——paused 档 u-3 落码：置于「其余一切 running」兜底前〔03 §10.8 u-1 定形注〕，唤醒消息落账尾条翻位即恢复 running——零推导面特判） */
+    const deriveLiveState = (tail) => {
+        if (tail === undefined)
+            return 'idle';
+        if (tail.type === 'turn/end')
+            return 'idle';
+        if (tail.type === 'approval/asked')
+            return 'waiting-approval';
+        if (tail.type === 'session/paused')
+            return 'paused';
+        return 'running';
+    };
+    /** 会话行 + 尾条推导合并态（list/selfStatus/trace 共用） */
+    const derivedState = (sessionId) => {
+        const row = deps.sessions.getSessionRow(sessionId);
+        if (row === undefined)
+            return { row: undefined, live: 'idle' }; // 零事件新会话（进程内在管无 durable 行）
+        return { row, live: deriveLiveState(tailEvent(row)) };
+    };
+    /** model 尾查（最后一条 request/header 的 config.model——防御读取） */
+    const lastModel = (sessionId) => {
+        const result = deps.events.queryEvents({ sessionId, types: ['request/header'], limit: HEADER_SCAN_LIMIT });
+        for (let i = result.events.length - 1; i >= 0; i -= 1) {
+            const data = result.events[i].data;
+            const model = data && typeof data === 'object' ? data.config?.model : undefined;
+            if (typeof model === 'string' && model.length > 0)
+                return model;
+        }
+        return undefined;
+    };
+    /** 尾窗读（fromSeq 精确定位——升序取帽值条，零全表扫） */
+    const tailWindow = (row, count) => {
+        const from = Math.max(0, row.lastSeq - count + 1);
+        const result = deps.events.queryEvents({ sessionId: row.id, fromSeq: from, limit: count });
+        return result.events;
+    };
+    /** 单事件呈现摘要（事件型感知提取——text/name/reason 优先，兜底 JSON 截断） */
+    const summarize = (event) => {
+        const data = event.data;
+        if (data !== null && typeof data === 'object') {
+            const record = data;
+            // 消息类：content 块数组或裸文本——取文本块拼接
+            const content = record.content ?? record.text;
+            if (typeof content === 'string')
+                return clip(content);
+            if (Array.isArray(content)) {
+                const text = content
+                    .map((block) => block !== null && typeof block === 'object' && typeof block.text === 'string'
+                    ? block.text
+                    : '')
+                    .join(' ')
+                    .trim();
+                if (text.length > 0)
+                    return clip(text);
+            }
+            // 工具类：name 优先（tool/call 携工具名）
+            if (typeof record.name === 'string')
+                return clip(`name=${record.name}`);
+            // turn 边界：reason
+            if (typeof record.reason === 'string')
+                return clip(`reason=${record.reason}`);
+        }
+        return clip(safeJson(data));
+    };
+    const toTailItem = (event) => ({
+        seq: event.seq,
+        time: event.time,
+        type: event.type,
+        summary: summarize(event),
+    });
+    /** 进程内在管判定（exists 语义：进程内 ∪ durable 任一在场） */
+    const inActive = (sessionId) => deps.liveSessions.listActive().find((info) => info.sessionId === sessionId);
+    return {
+        listSessions() {
+            const active = deps.liveSessions.listActive().slice(0, LIST_CAP);
+            return active.map((info) => {
+                const { row, live } = derivedState(info.sessionId);
+                return {
+                    id: info.sessionId,
+                    // 行缺席（零事件新会话）：origin 兜底进程内记录、updatedAt 兜底 0
+                    title: row?.title,
+                    origin: row?.origin ?? info.origin,
+                    parentId: row?.parentId,
+                    live,
+                    model: row === undefined ? undefined : lastModel(info.sessionId),
+                    updatedAt: row?.updatedAt ?? 0,
+                };
+            });
+        },
+        readTail(sessionId, opts) {
+            const limit = Math.min(Math.max(1, opts?.limit ?? TAIL_LIMIT_DEFAULT), TAIL_LIMIT_MAX);
+            const row = deps.sessions.getSessionRow(sessionId);
+            const exists = row !== undefined || inActive(sessionId) !== undefined;
+            if (row === undefined)
+                return { exists, items: [] }; // 零事件或不在场——空窗
+            return { exists, items: tailWindow(row, limit).map(toTailItem) };
+        },
+        trace(sessionId) {
+            const row = deps.sessions.getSessionRow(sessionId);
+            const exists = row !== undefined || inActive(sessionId) !== undefined;
+            if (row === undefined) {
+                return { sessionId, exists, live: 'idle', recent: [], inflightTools: [] };
+            }
+            const window = tailWindow(row, TRACE_WINDOW);
+            // 在飞工具 = 尾窗内 tool/call 无后续同 toolCallId 的 tool/result
+            // （call → result 配对收敛；result 按到达序覆盖——后见胜出）
+            const settled = new Set();
+            const calls = new Map(); // toolCallId → name
+            for (const event of window) {
+                const data = event.data;
+                const callId = data && typeof data === 'object' && typeof data.toolCallId === 'string' ? data.toolCallId : undefined;
+                if (event.type === 'tool/result') {
+                    if (callId !== undefined)
+                        settled.add(callId);
+                }
+                else if (event.type === 'tool/call') {
+                    const name = data && typeof data === 'object' && typeof data.name === 'string' ? data.name : (callId ?? 'unknown');
+                    if (callId !== undefined)
+                        calls.set(callId, name);
+                }
+            }
+            const inflightTools = [...calls.entries()].filter(([callId]) => !settled.has(callId)).map(([, name]) => name);
+            return {
+                sessionId,
+                exists,
+                live: deriveLiveState(tailEvent(row)),
+                recent: window.map(toTailItem),
+                inflightTools,
+            };
+        },
+        selfStatus(sessionId) {
+            const { row, live } = derivedState(sessionId);
+            const info = inActive(sessionId);
+            return {
+                sessionId,
+                origin: row?.origin ?? info?.origin ?? 'conversation',
+                parentId: row?.parentId,
+                workspaceRoot: workspaceRoot(),
+                live,
+                model: row === undefined ? undefined : lastModel(sessionId),
+            };
+        },
+        isSameTree(a, b) {
+            if (a === b)
+                return true; // self 特例（同 id 天然含）
+            const rootA = rootOf(a);
+            const rootB = rootOf(b);
+            return rootA !== undefined && rootA === rootB;
+        },
+    };
+    /** 根求解（parent_id 链上溯——帽深 64；行缺席/链断/超帽 = undefined） */
+    function rootOf(sessionId) {
+        let current = sessionId;
+        for (let depth = 0; depth < LINEAGE_MAX_DEPTH; depth += 1) {
+            const row = deps.sessions.getSessionRow(current);
+            if (row === undefined)
+                return undefined; // 链中段缺席——不可判
+            if (row.parentId === undefined)
+                return row.id; // 无父 = 根
+            current = row.parentId;
+        }
+        return undefined; // 超帽——不可判（fail-closed 跨树）
+    }
+}
+/** 文本截断（含省略号——单行有界） */
+function clip(text) {
+    const normalized = text.replace(/\s+/g, ' ').trim();
+    return normalized.length > SUMMARY_MAX_CHARS ? `${normalized.slice(0, SUMMARY_MAX_CHARS)}…` : normalized;
+}
+/** JSON 兜底摘要（坏形不炸——截断呈现） */
+function safeJson(data) {
+    try {
+        const text = JSON.stringify(data) ?? String(data);
+        return text;
+    }
+    catch {
+        return '(unserializable)';
+    }
+}

package/dist/obs/tool.js

@@ -0,0 +1,97 @@
+/**
+ * obs — obs_query 只读工具件（03 §10.8；fetch 工具同款薄包装先例）。
+ *
+ * 参数面 typebox schema（07 schema 层宿主件直用同律）+ 回执文本表格
+ * （usage 行主计费桶与 cache 分列——模型可见）。effect 'read'：聚合查询
+ * 是模型读观测面动作，零写权。装载归批 12 装配面（createObsQueryTool
+ * 工厂——与 createFetchTool 同款接线位）。
+ */
+import { BaseError } from '../contracts/index.js';
+import { Type } from 'typebox';
+/** 桶起点格式化（ISO UTC 整点/整日——存储客观、呈现换算的第一面） */
+function formatBucket(bucket) {
+    return new Date(bucket).toISOString().replace('.000Z', 'Z');
+}
+/** 用量行文本（列对齐——主计费桶与 cache 桶分列 + 命中率派生列〔RP5〕） */
+function usageLine(row) {
+    const main = row.input + row.output;
+    return [
+        formatBucket(row.bucket),
+        `calls=${row.calls}`,
+        `main(in+out)=${main}`,
+        `cache_read=${row.cacheRead}`,
+        `cache_write=${row.cacheWrite}`,
+        `cache_write_1h=${row.cacheWrite1h}`,
+        `reasoning=${row.reasoning}`,
+        // 命中率呈现：null = 桶内无 token 流（诚实缺席）；有值取两位百分比
+        `hit_rate=${row.hitRate === null ? 'n/a' : `${(row.hitRate * 100).toFixed(2)}%`}`,
+    ].join('  ');
+}
+/** 事件计数行文本 */
+function eventsLine(row) {
+    return `${formatBucket(row.bucket)}  ${row.eventType}  count=${row.count}`;
+}
+/**
+ * obs_query 工具定义工厂（装载批由装配根经插件注册面挂入工具注册表）。
+ * @param service obs 服务句柄（与告警/摄取同一实例）
+ */
+export function createObsQueryTool(service) {
+    return {
+        name: 'obs_query',
+        description: '查询观测聚合（durable 事件流的小时/日桶统计）。metric=events 返回各事件类型' +
+            '计数（eventType 支持尾通配 <族前缀>/*——如 compaction/* 族计数一次可达；' +
+            '非任意 glob）；metric=usage 返回 LLM token 用量聚合（input/output 主计费桶与 cache 桶' +
+            '分列，token 原始值——不折算货币；hit_rate = 缓存命中率派生列 cacheRead/' +
+            '(input+cacheRead+cacheWrite) 桶内聚合比值，n/a = 桶内无 token 流）。桶时刻 ' +
+            'UTC 对齐。窗口 from/to 为 epoch 毫秒（含边界）；行上限缺省 100、硬帽 1000，' +
+            '按时间正序返回。',
+        parameters: Type.Object({
+            granularity: Type.Union([Type.Literal('hour'), Type.Literal('day')], {
+                description: '粒度：hour = 小时桶；day = 日桶（仅含已闭合日）',
+            }),
+            metric: Type.Optional(Type.Union([Type.Literal('events'), Type.Literal('usage')], {
+                description: '指标：events = 事件计数（缺省）；usage = LLM 用量聚合',
+            })),
+            from: Type.Optional(Type.Number({ description: '窗口下界（epoch 毫秒，含）' })),
+            to: Type.Optional(Type.Number({ description: '窗口上界（epoch 毫秒，含）' })),
+            eventType: Type.Optional(Type.String({
+                // 尾通配一形（03 §10.8 u-1 RP5——u-4 落码）：无 '*' 精确匹配，或恰
+                // 一个尾 '/*'；其余 glob 形（中缀 '*'、空前缀 '/*'、'**'、裸 '*'）
+                // schema 段前置拒——04 §7 段 1 既有码 TOOL_INVALID_ARGS（零新码）
+                pattern: '^[^*]+(/\\*)?$',
+                description: '事件类型过滤（仅 metric=events 有效）：精确匹配或尾通配 <族前缀>/*（如 compaction/* 族计数一次可达；非任意 glob）',
+            })),
+            limit: Type.Optional(Type.Number({ description: '行上限（缺省 100、硬帽 1000）' })),
+        }, { additionalProperties: false }),
+        effect: 'read',
+        execute: async (args) => {
+            try {
+                const rows = service.query({
+                    granularity: args.granularity === 'day' ? 'day' : 'hour',
+                    metric: args.metric === 'usage' ? 'usage' : 'events',
+                    ...(typeof args.from === 'number' ? { from: args.from } : {}),
+                    ...(typeof args.to === 'number' ? { to: args.to } : {}),
+                    ...(typeof args.eventType === 'string' ? { eventType: args.eventType } : {}),
+                    ...(typeof args.limit === 'number' ? { limit: args.limit } : {}),
+                });
+                if (rows.length === 0) {
+                    return { content: [{ type: 'text', text: '（窗口内无聚合行）' }] };
+                }
+                const header = args.metric === 'usage'
+                    ? 'bucket  calls  main(in+out)  cache_read  cache_write  cache_write_1h  reasoning  hit_rate'
+                    : 'bucket  event_type  count';
+                const lines = rows.map((row) => ('eventType' in row ? eventsLine(row) : usageLine(row)));
+                return { content: [{ type: 'text', text: [header, ...lines].join('\n') }] };
+            }
+            catch (error) {
+                // 一切失败编码为 isError 数据面（03 §2.3）——BaseError 携码前置披露
+                const code = error instanceof BaseError ? error.code : undefined;
+                const message = error instanceof Error ? error.message : String(error);
+                return {
+                    content: [{ type: 'text', text: code ? `[${code}] ${message}` : message }],
+                    isError: true,
+                };
+            }
+        },
+    };
+}

package/dist/obs/types.js

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

package/dist/persist/audit.js

@@ -0,0 +1,63 @@
+import { BaseError, getEventTypeMeta } from '../contracts/index.js';
+/**
+ * audit_events 建表迁移项（05 §9）。占号 v8——号随注册序顺延：scheduler v2 /
+ * goal v3 / memory v4-6 / credentials v7 之后。声明 export-only：宿主装配根
+ * HOST_MIGRATION_TAIL 机械聚合（05 §6.4——声明来自件、执行在宿主）。
+ */
+export const AUDIT_MIGRATION = {
+    version: 8,
+    name: 'audit-events',
+    sql: 'CREATE TABLE audit_events (id INTEGER PRIMARY KEY, time INTEGER NOT NULL, type TEXT NOT NULL, data TEXT NOT NULL) STRICT',
+};
+/** listRecent 缺省帽（诊断/呈现面一屏量） */
+const LIST_RECENT_DEFAULT = 100;
+/**
+ * 构造审计流面。词汇闸以 contracts 事件注册表为判据（模块加载即含全部
+ * 核心词——计数随批增长以注册表为单源，此处不复述数字防漂移；插件扩展
+ * 词经 registerEventType 亦即时可达）。
+ * @param db 已开库句柄（audit_events 表须已由迁移链建就——表不在则首笔
+ *   INSERT 即 SQLite 报错，fail-loud 不静默）
+ * @param clock 挂钟注入（测试假钟；缺省 Date.now）
+ */
+export function createAuditFace(db, clock = Date.now) {
+    // 三语句构造期预编译（better-sqlite3 惯例——句柄复用免逐笔 parse）
+    const insertStmt = db.prepare('INSERT INTO audit_events (time, type, data) VALUES (?, ?, ?)');
+    const lastByTypeStmt = db.prepare('SELECT id, time, type, data FROM audit_events WHERE type = ? ORDER BY id DESC LIMIT 1');
+    const recentStmt = db.prepare('SELECT id, time, type, data FROM audit_events ORDER BY id DESC LIMIT ?');
+    /** 单行解析：data JSON 串 → 对象形；坏形 fail-loud（宁崩不误读） */
+    const parseRow = (row) => {
+        let parsed;
+        try {
+            parsed = JSON.parse(row.data);
+        }
+        catch {
+            throw new BaseError('PERSIST_DATA_CORRUPT', `审计流行 #${row.id}（${row.type}）data 非法 JSON——库文件损坏，拒误读`);
+        }
+        // JSON 合法但非对象形（串/数组/数字）同为坏形——data 词形恒为对象
+        if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
+            throw new BaseError('PERSIST_DATA_CORRUPT', `审计流行 #${row.id}（${row.type}）data 非对象形——拒误读`);
+        }
+        return { id: row.id, time: row.time, type: row.type, data: parsed };
+    };
+    return {
+        append(type, data) {
+            // 词汇闸两档（写入面前置——先于任何库操作）：
+            const meta = getEventTypeMeta(type);
+            if (meta === undefined) {
+                throw new Error(`审计流 append 词汇闸红：事件类型 ${type} 未在词汇注册表——先注册再落账（fail-loud）`);
+            }
+            if (meta.category !== 'log-only') {
+                throw new Error(`审计流 append 词汇闸红：事件类型 ${type} 类别为 ${meta.category}——审计流只收 log-only 词，surface/snapshot/structure 词归会话流管辖`);
+            }
+            insertStmt.run(clock(), type, JSON.stringify(data));
+        },
+        lastOf(type) {
+            const row = lastByTypeStmt.get(type);
+            return row === undefined ? undefined : parseRow(row);
+        },
+        listRecent(limit = LIST_RECENT_DEFAULT) {
+            const rows = recentStmt.all(limit);
+            return rows.map(parseRow);
+        },
+    };
+}

package/dist/persist/aux.js

@@ -0,0 +1,39 @@
+/**
+ * persist — 派生库开库面（aux 面；03 §10.8 件身份条款 + 05 §6.4 表族入主库
+ * 迁移链例外清单〔memory/goal/scheduler〕不含 obs 的执法位）。
+ *
+ * 面向「可禁用 core: 件的派生存储」：调用方（obs 等）经本公开面拿
+ * better-sqlite3 Database 实例，自建表、自管版本（PRAGMA user_version 归
+ * 调用方——与主库 user_version 门禁分立不串档）。本函数只做物理卫生三拍：
+ * 父目录代建 + WAL 编舞（busy_timeout/WAL/synchronous=FULL——与主库开库
+ * 同一拍单源复用 store.prepareWal）+ 库文件 0600 自检修复。
+ *
+ * better-sqlite3 只准出现在 persist（02 §4.2 native 隔离律）——本面是
+ * 该律对派生库场景的延伸出口：obs 件经公开面拿实例、自身不 import
+ * better-sqlite3。
+ */
+import Database from 'better-sqlite3';
+import { mkdirSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { repairFileMode } from './paths.js';
+import { prepareWal } from './store.js';
+/**
+ * 打开派生库（物理卫生三拍；无版本门禁——schema 主权归调用方）。
+ * @param dbPath 库文件路径（':memory:' 内存形态同样支持——诊断/测试位）
+ * @returns 就绪的 Database（调用方负责建表与 close）
+ */
+export function openAuxDatabase(dbPath, options = {}) {
+    const warn = options.warn ?? ((message) => console.error(message));
+    const inMemory = dbPath === ':memory:';
+    if (!inMemory) {
+        // 库父目录须在场（better-sqlite3 不代建目录；openStore 同款）
+        mkdirSync(dirname(dbPath), { recursive: true });
+    }
+    const db = new Database(dbPath);
+    prepareWal(db, warn);
+    if (!inMemory) {
+        // 库文件 0600 自检修复（派生库同持操作者数据——权限面与主库一致）
+        repairFileMode(dbPath, '派生库文件', warn);
+    }
+    return db;
+}

package/dist/persist/codes.js

@@ -0,0 +1,35 @@
+/**
+ * persist 域错误码注册（05 篇 §6 物理存储——物理层码族 PERSIST_ 首批）。
+ *
+ * 前缀族明列见 contracts/errors.ts ERROR_CODE_PREFIXES（02 §5.3 #1；2026-09-05
+ * persist 落码批补列）。本文件由模块公开面 index.ts 引入（注册纪律：写入点
+ * 文件必须实际 import 本文件，注册才发生——与 session/codes.ts 同款）。
+ */
+import { registerErrorCodes } from '../contracts/index.js';
+registerErrorCodes([
+    {
+        code: 'PERSIST_SCHEMA_TOO_NEW',
+        module: 'persist',
+        description: '版本门禁红：库内 user_version 高于宿主迁移链 head（降级运行拒开，05 §6.4）',
+    },
+    {
+        code: 'PERSIST_SCHEMA_UNRECOGNIZED',
+        module: 'persist',
+        description: '库文件不可识别：非空库但 user_version=0（外来 SQLite 文件/损坏残卷，宁拒绝不误读）',
+    },
+    {
+        code: 'PERSIST_DATA_CORRUPT',
+        module: 'persist',
+        description: '库内数据损坏：JSON 列解析失败等外因损坏（断电半写/手编库），fail-loud 拒误读',
+    },
+    {
+        code: 'PERSIST_WRITE_EXHAUSTED',
+        module: 'persist',
+        description: 'write-behind 批级重试耗尽（首版 3 次）——进程 fail-loud（写不进库的会话继续跑 = 谎报持久化，05 §6.3）',
+    },
+    {
+        code: 'PERSIST_SECRET_UNREADABLE',
+        module: 'persist',
+        description: '凭证密文不可解读：密钥丢失/不匹配（AES-256-GCM 解密失败）——重录凭证即恢复',
+    },
+]);

package/dist/persist/index.js

@@ -0,0 +1,30 @@
+/**
+ * persist 模块公开面（L2 物理存储——02 篇模块清单席 11；机制真源 05 篇 §6/§9）。
+ *
+ * 本批落码：SQLite 单后端 WAL + v1 基线 schema（七对象）+ user_version 迁移
+ * 门禁（TOO_NEW 拒开/缺口备份迁移/冷启动单事务）+ write-behind 批落链（微任务
+ * 节流/批帽 64/指数退避/毒丸隔离·durable 标记/flush 屏障）+ Persistence 门面
+ * （SessionLog 接线/种子会话同步落库）+ 凭证密文盒（AES-256-GCM）+ 主库
+ * 归属三级梯子 + store_state LRU 治理 + session_fts 对账三档。
+ * 消费面（host 装配根/ctx.sessions 只读服务/core: 插件 DAO）随后续批接线。
+ */
+import './codes.js';
+export { APPLICATION_ID, SCHEMA_VERSION, CANONICAL_DDL } from './schema.js';
+export { normalizeMigrations } from './migrations.js';
+export { DATA_DIR_ENV, DB_PATH_ENV, DEFAULT_DATA_DIR_BASENAME, DEFAULT_DB_BASENAME, MEMORY_DB_PATH, resolveDataDir, resolveDatabasePath, resolveDatabasePathIn, ensureDataDir, } from './paths.js';
+export { SECRET_KEY_BASENAME, loadOrCreateSecretKey, encryptSecret, decryptSecret, ephemeralSecretKey, } from './secret-box.js';
+export { openStore, Store } from './store.js';
+// 进程级 durable 审计流（05 §9 audit_events——U3 落码批 U3-2）：迁移项声明
+// export-only（宿主装配根 HOST_MIGRATION_TAIL 机械聚合——同 credentials v7
+// 形）；写入面经库句柄构造，单写者 = 宿主固定件（boot 幂等 diff/高危面记账）
+export { AUDIT_MIGRATION, createAuditFace } from './audit.js';
+// 装载史 durable 载体（05 §9 load_generations——装载史批 h-2）：迁移项声明
+// export-only（宿主装配根 HOST_MIGRATION_TAIL 机械聚合——audit v8 同形）；
+// 写点 = 宿主装配根（boot 完成点 + /reload reapply 尾，h-3 接线），CLI 卸载
+// 腿只读消费（uninstall 双回执有源化，h-4 接线）
+export { LOAD_GENERATIONS_MIGRATION, createLoadHistoryFace } from './load-history.js';
+// 派生库开库面（批 18b——03 §10.8 obs 自管库文件的执法位：物理卫生三拍
+// 单源复用，schema 主权归调用方）
+export { openAuxDatabase } from './aux.js';
+export { WriteBehind } from './write-behind.js';
+export { Persistence } from './persistence.js';

package/dist/persist/load-history.js

@@ -0,0 +1,50 @@
+/**
+ * load_generations 建表迁移项（05 §9）。占号 v10——号随注册序顺延：scheduler
+ * v2 / goal v3 / memory v4-6·9 / credentials v7 / audit v8 之后。声明
+ * export-only：宿主装配根 HOST_MIGRATION_TAIL 机械聚合（05 §6.4——声明来自
+ * 件、执行在宿主；audit_events v8 同形）。
+ */
+export const LOAD_GENERATIONS_MIGRATION = {
+    version: 10,
+    name: 'load-generations',
+    sql: 'CREATE TABLE load_generations (id INTEGER PRIMARY KEY, started_at INTEGER NOT NULL, ended_at INTEGER, activated TEXT NOT NULL, skipped TEXT NOT NULL, failed TEXT NOT NULL) STRICT',
+};
+/**
+ * 构造装载史面。
+ * @param db 已开库句柄（load_generations 表须已由迁移链建就——表不在则首笔
+ *   即 SQLite 报错，fail-loud 不静默；sessions 表为 v1 基线恒在）
+ * @param clock 挂钟注入（测试假钟；缺省 Date.now——started_at 落笔与查询侧
+ *   开放窗 COALESCE 归一共用此钟）
+ */
+export function createLoadHistoryFace(db, clock = Date.now) {
+    // 三语句构造期预编译（better-sqlite3 惯例——句柄复用免逐笔 parse）
+    const closeOpenStmt = db.prepare('UPDATE load_generations SET ended_at = ? WHERE ended_at IS NULL');
+    const insertStmt = db.prepare('INSERT INTO load_generations (started_at, ended_at, activated, skipped, failed) VALUES (?, NULL, ?, ?, ?)');
+    // 时间窗 join 推算（05 §9 定形语义）：世代激活窗 [started_at,
+    // COALESCE(ended_at, :now)] ∩ 会话存活窗 [created_at, updated_at] 非空即
+    // 共现（闭区间——端点相触即计）；成员判据恒 activated——json_each 展开
+    // 三分区列比对 id（SQLite JSON1 内建，非外部依赖）。
+    const countStmt = db.prepare(`
+    SELECT COUNT(DISTINCT s.id) AS cnt
+    FROM sessions s
+    JOIN load_generations g
+      ON s.created_at <= COALESCE(g.ended_at, ?)
+     AND s.updated_at >= g.started_at
+    WHERE EXISTS (SELECT 1 FROM json_each(g.activated) m WHERE m.value ->> '$.id' = ?)
+  `);
+    // 换代双写单事务：回填与插新同成同败——半途崩不产生双开放窗或丢前代收口
+    const rotateTx = db.transaction((snapshot, now) => {
+        closeOpenStmt.run(now);
+        const info = insertStmt.run(now, JSON.stringify(snapshot.activated), JSON.stringify(snapshot.skipped), JSON.stringify(snapshot.failed));
+        return Number(info.lastInsertRowid);
+    });
+    return {
+        recordLoadGeneration(snapshot) {
+            return rotateTx(snapshot, clock());
+        },
+        querySessionsWithPlugin(pluginId) {
+            const row = countStmt.get(clock(), pluginId);
+            return row.cnt;
+        },
+    };
+}

package/dist/persist/migrations.js

@@ -0,0 +1,37 @@
+/**
+ * persist — 统一迁移框架（05 篇 §6.4）。
+ *
+ * 迁移函数注册表在 persist（宿主固定件），插件不注册迁移；core: 插件表族
+ * （memory 记忆表 / goal 表 / scheduler jobs 表）的建表/升级声明由 host 装配根
+ * **机械聚合**传入 openStore——迁移链仍是单链，声明来自插件、执行在宿主。
+ * 本批只有框架 + v1 基线；首个业务迁移项随对应插件落码批进场。
+ */
+/**
+ * 校验并排序迁移链（开库前调用一次——装配错误在任何库文件被碰之前抛出）。
+ * 规则：全部 version > 基线版本、严格递增无重复、sql 非空。
+ * @param migrations 聚合的迁移项（顺序无关，按 version 排序后返回）
+ * @param baseVersion 基线 SCHEMA_VERSION（迁移链起点）
+ * @returns 按 version 升序的迁移链
+ */
+export function normalizeMigrations(migrations, baseVersion) {
+    const seen = new Set();
+    const out = [];
+    for (const m of migrations) {
+        if (!Number.isInteger(m.version) || m.version <= baseVersion) {
+            throw new Error(`迁移项 ${m.name || '(未具名)'}：version=${m.version} 必须是大于基线 ${baseVersion} 的整数`);
+        }
+        if (!m.name || typeof m.name !== 'string') {
+            throw new Error(`迁移项 version=${m.version}：name 缺失`);
+        }
+        if (typeof m.sql !== 'string' || m.sql.trim() === '') {
+            throw new Error(`迁移项 ${m.name}（v${m.version}）：sql 为空`);
+        }
+        if (seen.has(m.version)) {
+            throw new Error(`迁移项 version=${m.version} 重复（${m.name}）——每个版本至多一项迁移`);
+        }
+        seen.add(m.version);
+        out.push(m);
+    }
+    out.sort((a, b) => a.version - b.version);
+    return out;
+}