@zhushanwen/zcode-session-source 0.2.7 → 0.2.9

package/README.md

@@ -1,6 +1,6 @@
 # @zhushanwen/zcode-session-source
 
-zcode subagent 会话库（SQLite）的唯一只读读取基座。三个消费面：session-reader 扩展
+zcode subagent 会话库（SQLite）的唯一只读读取基座。三个消费方：session-reader 扩展
 （bun 宿主）、runtime 会话导入薄包装（node 侧）、未来新增的 coding-agent source。
 
 ## 内容
@@ -15,16 +15,16 @@ zcode subagent 会话库（SQLite）的唯一只读读取基座。三个消费
     `src/__tests__/platform-matrix.ts`）
   - L3 小库快照兜底（db 拷 mkdtemp 固定前缀 `taiji-zcode-snap-` + 自建 0 字节
     `-wal` → 开库后验证 `sqlite_master` 表集合含 `session/message/part`；规模门
-    256MB 拒拷；读后 finally 清理。**$TMPDIR 治理面**：快照属「读快照」非对话数据
+    256MB 拒拷；读后 finally 清理。**$TMPDIR 治理范围**：快照属「读快照」非对话数据
     存放——源库只读零触碰、副本即弃，taiji 侧登记为 data-source-registry §4 ⑰
     〔ADR-0063 I2 的登记例外〕，详见 recovery.ts 头注）
-  - L4 错误面（`SqliteUnreadableError`，`attempted` 记录已尝试级别，供上层映射
+  - L4 错误范围（`SqliteUnreadableError`，`attempted` 记录已尝试级别，供上层映射
     消费侧错误码——本包不私建错误码词表）
   - 拷贝集唯一定义：db only + 自建 0 字节 `-wal`；`-wal`/`-shm` 在场绝不自动拷贝
     （防静默回滚），`-shm` 永不进拷贝集。
 - **sqlite-access**：行集查询（`getSessionTranscript`：session → message → part
-  三级表，联合序）、schema 版本已知集闸门（`KNOWN_ZCODE_SCHEMA_VERSIONS`）、
-  库路径投影与白名单集合（路径段常量同源 `@zhushanwen/subagent-engine-sdk`，
+  三级表，联合序）、schema 版本已知集门禁（`KNOWN_ZCODE_SCHEMA_VERSIONS`）、
+  库路径派生视图与白名单集合（路径段常量同源 `@zhushanwen/subagent-engine-sdk`，
   `dataDir` 由调用方传入，本包不做宿主路径推导）。
 
 ## 测试（D3 源级双跑）

package/dist/index.d.ts

@@ -14,8 +14,8 @@ import { NormalizedSession } from '@zhushanwen/session-core';
  *   L3 小库快照兜底（罕见）：immutable 也失败 → db 拷 mkdtemp（固定前缀
  *      taiji-zcode-snap-）+ 自建 0 字节 -wal → 开库后验证 sqlite_master 表集合含
  *      session/message/part（防「开库成功但缺表」半残态）→ 通过才读。
- *      规模门：db 文件 > 256MB 不拷 → 直接错误面。
- *   L4 错误面：SqliteUnreadableError（attempted 记录已尝试的等级、跳过原因并入
+ *      规模门：db 文件 > 256MB 不拷 → 直接错误范围。
+ *   L4 错误范围：SqliteUnreadableError（attempted 记录已尝试的等级、跳过原因并入
  *      message，供上层映射 zcode_db_unreadable——错误码词表属消费侧，本包不私建）。
  *
  *   拷贝集唯一定义：db only + 自建 0 字节 -wal；-wal/-shm 在场绝不自动拷贝
@@ -30,10 +30,10 @@ import { NormalizedSession } from '@zhushanwen/session-core';
  * os.tmpdir() 由 OS 回收，前缀可人工识别。不为此新增清理器（新机制新义务，超出
  * 读取链职责——设计 §3.4 CANTOPEN 四要素「恢复路径」节）。
  *
- * $TMPDIR 治理面登记（2026-09-23 review round 1 MF-1-4）：L3 快照把会话库整库拷入
+ * $TMPDIR 治理范围登记（2026-09-23 review round 1 MF-1-4）：L3 快照把会话库整库拷入
  * $TMPDIR 属「读快照」非「对话数据存放」——源库只读零触碰、副本即弃（OS 清空
- * $TMPDIR 无任何权威数据丢失面），已按此语义登记为 data-source-registry §4 ⑰
- * （ADR-0063 I2「对话数据禁入 $TMPDIR」的登记例外，taiji 侧消费面经该条豁免
+ * $TMPDIR 无任何权威数据丢失风险），已按此语义登记为 data-source-registry §4 ⑰
+ * （ADR-0063 I2「对话数据禁入 $TMPDIR」的登记例外，taiji 侧消费方经该条豁免
  * review MUST「会话内容入 $TMPDIR」）。迁移 dataDir scratch 的长期方向与代价
  * 见该条目处置列——跨包 API 变更，另批裁决。
  */
@@ -52,7 +52,7 @@ declare class SqliteUnreadableError extends Error {
 
 /**
  * zcode 会话库只读访问层（自 runtime services/session/zcode-import/sqlite-access.ts
- * 迁入改造；runtime 侧旧文件已随共享基座实施收口删除（git 可追溯），本包为其唯一现行承载）。
+ * 迁入改造；runtime 侧旧文件已随共享基座实施收敛删除（git 可追溯），本包为其唯一现行承载）。
  *
  * 访问模式（沿用既有先例）：
  * - 只读连接（readonly 语义 = WAL 只读不阻塞宿主写入）；转换/查询全程不写库；
@@ -63,7 +63,7 @@ declare class SqliteUnreadableError extends Error {
  * - 开库统一走四级恢复阶梯（recovery.ts，设计 §3.5 单一规格）——runtime（node）
  *   侧直开从来可用（F24），阶梯主要服务 bun 宿主侧的静息态 CANTOPEN（darwin bun；
  *   linux bun 静息态直开同样可用——bun 平台分叉矩阵登记在 __tests__/platform-matrix.ts）；
- * - schema 版本从「best-effort 诊断」升级为已知集闸门（KNOWN_ZCODE_SCHEMA_
+ * - schema 版本从「best-effort 诊断」升级为已知集门禁（KNOWN_ZCODE_SCHEMA_
  *   VERSIONS，版本超出已知集抛 ZcodeSchemaDriftError——错误码词表属消费侧，
  *   本包不私建 zcode_* 码）。
  *
@@ -84,7 +84,7 @@ declare function zcodeIsolatedDbPath(dataDir: string): string;
 /**
  * zcode 会话库白名单集合（封闭集合）：`[隔离库（现役）, 宿主库（仅存量兼容）]`。
  * 与引擎侧 zcodeDbPathAllowlist 同构——wire 帧 / session 数据里的 dbPath 来自
- * 不可信面，仅放行集合内精确绝对路径。集合形态（而非 `||` 列表）使未来第三个
+ * 不可信来源，仅放行集合内精确绝对路径。集合形态（而非 `||` 列表）使未来第三个
  * 合法路径只需改本函数。
  * @param dataDir taiji 数据根（getDataDir() 产物，由调用方传入）
  */
@@ -116,7 +116,7 @@ interface ZcodeTranscriptMessageRow {
     data: Record<string, unknown>;
     parts: Array<Record<string, unknown>>;
 }
-/** 只读查询面：候选行 / 单会话行 / 字节聚合 / schema 版本诊断。 */
+/** 只读查询范围：候选行 / 单会话行 / 字节聚合 / schema 版本诊断。 */
 interface ZcodeReadonlyDb {
     /**
      * 候选会话行（排除 subagent_child；time_updated 降序）。
@@ -146,7 +146,7 @@ interface ZcodeReadonlyDb {
     /** 关闭连接（吞错语义见模块头注；幂等无害——重复 close 由驱动抛错吞掉）。 */
     close(): void;
 }
-/** openZcodeSessionDb 产物：查询面 + 实际命中的阶梯级别 + 统一收尾。 */
+/** openZcodeSessionDb 产物：查询范围 + 实际命中的阶梯级别 + 统一收尾。 */
 interface ZcodeSessionDbHandle {
     db: ZcodeReadonlyDb;
     /** 实际命中的四级恢复阶梯级别（恢复成功非静默事件：调用方记结构化日志）。 */
@@ -156,7 +156,7 @@ interface ZcodeSessionDbHandle {
 }
 /**
  * 打开 zcode 会话库只读连接（编排入口：存在性检查 → 四级恢复阶梯 → schema 已知集
- * 闸门）。dbPath 不存在直接抛 Error（调用方映射「库不存在」语义）；阶梯耗尽抛
+ * 门禁）。dbPath 不存在直接抛 Error（调用方映射「库不存在」语义）；阶梯耗尽抛
  * SqliteUnreadableError（attempted 含已尝试级别）；schema 超出已知集抛
  * ZcodeSchemaDriftError。其余查询期错误原样上抛（驱动错误 / data 列 JSON 非法等），
  * 调用方按消费侧错误规格映射。
@@ -166,13 +166,13 @@ declare function openZcodeSessionDb(dbPath: string): Promise<ZcodeSessionDbHandl
 /**
  * zcode → canonical session 转换器（自 runtime services/session/zcode-import/converter.ts
  * 迁入改造，session-reader-shared-core 设计 §3.3 D1 + §5 Phase 2；runtime 侧旧文件已
- * 随共享基座实施收口删除（git 可追溯），本包为其唯一现行承载）。
+ * 随共享基座实施收敛删除（git 可追溯），本包为其唯一现行承载）。
  *
  * 输入 = 单会话全量行集（message 按 sequence、part 按 (message.sequence, part.sequence)
  * 联合序，sqlite-access.getSessionTranscript）；输出 = canonical `Entry[]`（session-core
  * 严格 Entry 模型，parentId 顺序链完整）。三层映射：
- * ① 消息级投影分派——逐条消息先经 classifyMessage()（projection.ts，asar 移植体）判定
- *    六策略之一（或 unclassified），按消息投影对齐设计 §7.3 映射表落点（三类丢弃整条不产
+ * ① 消息派生视图分派——逐条消息先经 classifyMessage()（projection.ts，asar 移植体）判定
+ *    六策略之一（或 unclassified），按消息派生视图对齐设计 §7.3 映射表落点（三类丢弃整条不产
  *    entry + L1/L2 聚合降级，unclassified 丢弃 + 独立告警码）；② part 级映射——消息内部
  *    按 session-import-unified 设计 §3.4 权威映射表逐条实现：T1 header/session_info /
  *    T2 user / T3 assistant 按 step-finish 切段 / T3b 工具名映射 / T3c stopReason 映射 /
@@ -180,18 +180,18 @@ declare function openZcodeSessionDb(dbPath: string): Promise<ZcodeSessionDbHandl
  *    D2 完整规格（三路关联判据 + 单条 compaction entry + firstKeptEntryId 三级锚悬空门 +
  *    1:N 最早联合序锚 + 孤儿二分），关联在发射前预扫描趟建立（compaction.ts）。
  *
- * 来源注记：消息投影分派 / 结构化降级（ImportDegradation 五码闭集）/ compaction D2 全规格 /
+ * 来源注记：消息派生视图分派 / 结构化降级（ImportDegradation 五码闭集）/ compaction D2 全规格 /
  * usage RT-5#1 缺省语义 / 时间戳 RT-5#8 不伪造 1970，均自 runtime zcode-import dev 演进版
  * 移植（git 可追溯）；dev 版内部的降级通道（孤儿/悬空/summary 不可用 → custom +
  * compaction_unlinked）随规格一并移植。
  *
  * 相对 dev 版的改造（canonical 契约，设计 D1「canonical 模型 = pi 形态的严格 Entry 树」）：
- * - emitEntry 不再 stringify 落 JSONL 行，改产 Entry 对象（toCanonicalEntry 收口，键序仍按
+ * - emitEntry 不再 stringify 落 JSONL 行，改产 Entry 对象（toCanonicalEntry 收敛，键序仍按
  *   `{type, id, parentId, timestamp, ...payload}` 构造——serializeSession 的字节契约
  *   责任在构造方，导入侧薄包装拼 header 行 + serializeSession 即得与旧产物逐字节
  *   兼容的 JSONL）；message 内 pi 透传字段（timestamp/provider/model/usage/stopReason、
  *   toolResult 的 details/isError、session_info 的 name）是 canonical Entry 冻结接口外
- *   的合法载荷字段——经宽形态构造 + 边界收口守卫承载，序列化原样落盘、reader 渲染链
+ *   的合法载荷字段——经宽形态构造 + 边界收敛检查承载，序列化原样落盘、reader 渲染链
  *   可直接消费，不做有损裁剪。
  * - entry id 生成收敛基座单点：normalizeZcodeRowId（8-hex 零填充，与 pi 自身
  *   randomUUID().slice(0,8) 同形态；pi 侧对 entry id 仅作 opaque map key 消费）。
@@ -200,12 +200,12 @@ declare function openZcodeSessionDb(dbPath: string): Promise<ZcodeSessionDbHandl
  *   read.ts——converter 聚焦纯转换映射，开库→查询→转换→dispose 组合编排在彼）。
  *   header 由库内 session 行构造：id 归一化（normalizeZcodeSessionId）、timestamp 取
  *   session 创建时间、cwd 缺省留空——zcode 会话无 cwd 概念，不伪造（D1）。
- *   首行 `{type:'session', version:3, ...header}` 不由本模块产出（属序列化装配面：
+ *   首行 `{type:'session', version:3, ...header}` 不由本模块产出（属序列化装配逻辑：
  *   导入薄包装 / reader 侧各自拼装）。
  * - 时间不可解不伪造（RT-5#8）：session.timeCreated / message.time.created 不可解时
  *   timestamp 键缺省（header.timestamp / entry.timestamp / message.timestamp 均可选），
  *   降级登记一次，不以 0 产出 1970 假时间戳污染排序与按日统计。
- * - 错误面归消费侧（§1.5 契约第 4 条）：session 行不存在、归一化失败、查询/JSON
+ * - 错误范围归消费侧（§1.5 契约第 4 条）：session 行不存在、归一化失败、查询/JSON
  *   解析失败均抛普通 Error 原样上抛——reader 侧映射 zcode_* 词表、runtime 导入侧
  *   映射 import_* 词表，本包不私建错误码与恢复话术（dev 版的 convertZcodeSession
  *   db 组合 + ImportServiceError 不移植）。
@@ -261,26 +261,26 @@ declare function convertZcodeTranscript(messages: ZcodeMessageInput[], session:
 /**
  * 读单会话并转换为 NormalizedSession（zcode source 包对外主函数，D1）。
  *
- * 契约面说明：现生产消费方（reader 扩展 / runtime 导入薄包装）均走
+ * 契约范围说明：现生产消费方（reader 扩展 / runtime 导入薄包装）均走
  * openZcodeSessionDb + convertZcodeTranscript 组合形态（各自持有分相位错误映射），
  * 本函数当前无生产调用方——保留导出是设计 §1.5 声明的对外主函数（未来第三源契约锚），
- * 第二源落地前的契约面。
+ * 第二源落地前的契约范围。
  *
  * 开库走 sqlite-access 的 openZcodeSessionDb（存在性 → 四级恢复阶梯 → schema 已知集
- * 闸门）；返回值三键 {header, entries, degradations}（NormalizedSession，session-core
+ * 门禁）；返回值三键 {header, entries, degradations}（NormalizedSession，session-core
  * 类型强制）。db 行存在性在查询阶段复查（定位校验与会话读取间的竞态窗口）。
  *
- * 错误面（归消费侧，调用方按各自词表映射——reader → zcode_* / runtime 导入 → import_*）：
+ * 错误范围（归消费侧，调用方按各自词表映射——reader → zcode_* / runtime 导入 → import_*）：
  * - db 文件不存在 / 恢复阶梯耗尽 → Error（sqlite-access 抛出，消息含路径与已尝试级别）
  * - schema 版本超出已知集 → ZcodeSchemaDriftError（观测版本在 observedVersion 字段）
- * - session 行不存在（zcode 侧 GC / 从未落库）→ Error，消息含 sessionId 与事实归因
+ * - session 行不存在（zcode 侧 GC / 从未写入该库）→ Error，消息含 sessionId 与事实归因
  * - 行 data 列 JSON 非法（schema 漂移域）→ 原始 Error 上抛（sqlite-access 不静默跳过）
  */
 declare function readZcodeSession(dbPath: string, sessionId: string): Promise<NormalizedSession>;
 
 /**
  * zcode session id 归一化（自 runtime services/session/zcode-import/normalize.ts 迁入
- * 改造；runtime 侧旧文件已随共享基座实施收口删除（git 可追溯），本包为其唯一现行承载。
+ * 改造；runtime 侧旧文件已随共享基座实施收敛删除（git 可追溯），本包为其唯一现行承载。
  * 设计 §1.5「id 归一化
  * 收敛为基座/source 单点」——候选打标与转换 header 两个调用点 import 同源实现，
  * 各内联一份则单边漂移、打标失配即幂等失效）。
@@ -294,7 +294,7 @@ declare function readZcodeSession(dbPath: string, sessionId: string): Promise<No
  * assertValidSessionId 允许集的真子集，收紧方向安全；锚点
  * dist/core/session-manager.js assertValidSessionId 正则字面量（语义登记 PS-52，verifiedWith 以该登记为准））。
  *
- * 相对 runtime 旧版的改造（设计 §1.5 source 包契约第 4 条「错误面归消费侧」）：不再
+ * 相对 runtime 旧版的改造（设计 §1.5 source 包契约第 4 条「错误范围归消费侧」）：不再
  * 抛 runtime services 层的 ImportServiceError（本包不私建 import_* / zcode_* 错误码），
  * 归一化失败抛普通 Error——消费方（session-reader 路由 / runtime 导入薄包装）按各自
  * 错误词表映射（reader → zcode_param_invalid；runtime → import_invalid_session）。

package/dist/index.js

@@ -904,7 +904,7 @@ function convertMessageByPolicy(msg, policy, createdMs, createdIso, emitForMessa
       break;
     default: {
       const exhaustive = policy;
-      throw new Error(`\u672A\u5904\u7406\u7684\u6295\u5F71\u7B56\u7565\uFF1A${String(exhaustive)}`);
+      throw new Error(`\u672A\u5904\u7406\u7684\u6D3E\u751F\u89C6\u56FE\u7B56\u7565\uFF1A${String(exhaustive)}`);
     }
   }
 }
@@ -974,7 +974,7 @@ function convertAssistantMessage(msg, data, createdMs, createdIso, emitEntry, de
         ...modelId !== void 0 && { model: modelId },
         // 产物不变量门：usage 恒在场（缺 → 零值兜底，zeroUsage 注释）
         usage: usage ?? zeroUsage(),
-        // 段有 step-finish 收口 → 采信其 finish；未收口段（取消/失败尾段）→ 消息级
+        // 段有 step-finish 收尾 → 采信其 finish；未收尾段（取消/失败尾段）→ 消息级
         // data.error 优先，无 error 证据才 'stop' 保底（T3c 事故补强）
         stopReason: finishReason !== void 0 ? mapStopReason(finishReason) : unsealedStopReason(data)
       }
@@ -1106,7 +1106,7 @@ async function readZcodeSession(dbPath, sessionId) {
     const row = handle.db.getSessionRow(sessionId);
     if (!row) {
       throw new Error(
-        `\u8BE5\u4F1A\u8BDD\u5DF2\u4E0D\u5728 zcode \u5E93\u4E2D\uFF08sessionId=${sessionId}\uFF09\uFF1A\u8BE5 id \u53EF\u80FD\u5DF2\u88AB zcode \u4FA7\u56DE\u6536\u6216\u4ECE\u672A\u843D\u5E93`
+        `\u8BE5\u4F1A\u8BDD\u5DF2\u4E0D\u5728 zcode \u5E93\u4E2D\uFF08sessionId=${sessionId}\uFF09\uFF1A\u8BE5 id \u53EF\u80FD\u5DF2\u88AB zcode \u4FA7\u56DE\u6536\u6216\u4ECE\u672A\u5199\u5165\u8BE5\u5E93`
       );
     }
     const transcript = handle.db.getSessionTranscript(sessionId);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhushanwen/zcode-session-source",
-  "version": "0.2.7",
+  "version": "0.2.9",
   "type": "module",
   "description": "Read-only zcode session database source: bun/node dual sqlite driver with a four-level CANTOPEN recovery ladder, transcript row queries, and schema version gate",
   "main": "dist/index.mjs",
@@ -19,7 +19,7 @@
   "license": "MIT",
   "dependencies": {
     "@zhushanwen/session-core": "0.12.0",
-    "@zhushanwen/subagent-engine-sdk": "0.10.1"
+    "@zhushanwen/subagent-engine-sdk": "0.12.1"
   },
   "devDependencies": {
     "@vitest/coverage-v8": "^4.1.9",
@@ -30,6 +30,6 @@
   "scripts": {
     "build": "tsup",
     "typecheck": "tsc --noEmit",
-    "test": "vitest run"
+    "test": "vitest run --pool=threads"
   }
 }