@zhushanwen/session-core 0.11.0 → 0.13.0

package/README.md

@@ -6,13 +6,13 @@ Coding-agent session 的 canonical 模型与纯 JSONL 原语基座。**零运行
 
 「把某个 coding-agent 的 session 读成统一结构」的唯一落点：session-reader（pi 会话读取）、runtime 导入、未来的 coding-agent source 包共用本基座，取代各自为政的字节层副本（首行读取、entry 解析、id 归一化）。
 
-## 导出面
+## 导出清单
 
 | 导出 | 说明 |
 |------|------|
 | `Entry` / `ParseResult` / `SessionHeader` / `NormalizedSession` | canonical 模型（D1）：严格 Entry 树，坏行丢弃不占位 |
-| `parseSessionContent(content)` | JSONL 文本 → `ParseResult`（坏行计 `skippedLines`，末行半行记 `lastLinePartial`） |
-| `parseSessionFile(path)` | `parseSessionContent` 的 async 文件版（ENOENT 等按 fs 原生错误抛出） |
+| `parseSessionContent(content)` | JSONL 文本 → `ParseResult`（坏行计 `skippedLines`；message 存在但 role 不在词表时整文件抛 `UnknownMessageRoleError`——fail-fast，不静默丢内容） |
+| `parseSessionFile(path)` | `parseSessionContent` 的 async 文件版（ENOENT 等按 fs 原生错误抛出；非法 role 同样抛 `UnknownMessageRoleError`） |
 | `serializeSession(entries)` | `Entry[]` → JSONL，与 pi 产物逐字节兼容（`JSON.stringify(entry) + '\n'`） |
 | `readFirstJsonlLine(path)` / `readFirstJsonlLineSync(path)` | 首行字节原语（async/sync 双形态）：只读首行、处理 CRLF/LF、跨块多字节安全；空文件/纯空白 → `undefined`；IO 错误上抛由消费方分流 |
 | `sessionIdFromFileName(fileName)` | 文件名不变量：剥 `.jsonl` 后最后一个 `_` 之后的尾段；提取不出 → `undefined` |

package/dist/index.d.ts

@@ -14,8 +14,16 @@
  * 冻结接口未列的 per-type 附加字段不在此暴露；消费方需要时先扩展本接口——解析层
  * 不私自保留未知字段，保证「读到的就是模型声明的」。
  */
-/** pi message entry 的 role 域（窄联合：解析时值守卫收窄，非法 role 计坏行）。 */
-type SessionMessageRole = 'user' | 'assistant' | 'toolResult';
+/**
+ * pi message entry 的 role 域（窄联合：解析时值检查收窄，词表外 role 整文件解析
+ * 抛 UnknownMessageRoleError——fail-fast，不静默丢 message）。
+ *
+ * 四值闭集与 pi 1.0 AgentMessage 的 role 全集对齐（pi-ai dist/types.d.ts SystemMessage/
+ * UserMessage/AssistantMessage/ToolResultMessage）。词表外 role 意味着写入方 pi 版本
+ * 较新：显式失败优于静默丢内容（用户裁决 2026-10-30），pi 新增 role 时扩展本词表
+ *（编译期穷尽断言强制清单同步）并补行为测试。
+ */
+type SessionMessageRole = 'user' | 'assistant' | 'toolResult' | 'system';
 interface Entry {
     type: string;
     id: string;
@@ -41,8 +49,6 @@ interface ParseResult {
     /** JSON 解析失败（含缺必填结构字段）的行数 */
     skippedLines: number;
     totalBytes: number;
-    /** 最后一行疑似半行（活跃 session 写入中），区别于中间坏行 */
-    lastLinePartial: boolean;
 }
 /**
  * session header（首行 type='session' entry 的模型）。
@@ -110,15 +116,30 @@ interface NormalizedSession {
  *
  * 坏行语义（严格模型，设计 D1）：逐行 JSON.parse，语法错误或缺必填结构字段计入
  * skippedLines 并丢弃，不占位、不中断整体解析。宽松「坏行保留占位」形态是
- * core/session-trace 的私有语义（设计 D1 被否项），不进本基座。
+ * core/session-trace 的私有语义（设计 D1 不采用项），不进本基座。
+ *
+ * 非法 message role 不走坏行容错：message 存在但 role 不在 SESSION_MESSAGE_ROLES
+ * 词表时整文件解析抛 UnknownMessageRoleError（fail-fast）。词表外 role 意味着写入方
+ * pi 版本较本包词表更新，静默丢 message 会造成会话内容不可见地损失——显式失败优于
+ * 静默丢内容（用户裁决 2026-10-30），扩展词表（升级）后即恢复可读。
  */
 
+/**
+ * message.role 不在合法词表时的解析错误（fail-fast 通道）：整文件解析抛出，
+ * 不折叠进 skippedLines、不产出丢弃 message 的空壳 entry。
+ */
+declare class UnknownMessageRoleError extends Error {
+    /** 非法行所在行号（1-based，与编辑器行号一致） */
+    readonly line: number;
+    /** 该行 message.role 的原始值（缺失时为 undefined） */
+    readonly role: unknown;
+    constructor(line: number, role: unknown);
+}
 /**
  * 解析 session JSONL 文本为 entries。
  *
- * 末尾换行产生的空行忽略（不计 skipped、不计 partial）；中间空行容错跳过
- * （正常 JSONL 无空行，防御文件损坏）。最后一行 parse 失败时 lastLinePartial=true
- * （活跃 session 写到一半的半行），区别于中间坏行。
+ * 末尾换行产生的空行忽略（不计 skipped）；中间空行容错跳过
+ * （正常 JSONL 无空行，防御文件损坏）。
  */
 declare function parseSessionContent(content: string): ParseResult;
 /** 读取 session 文件并解析。文件不存在按 Node fs 原生错误抛出（ENOENT）。 */
@@ -181,4 +202,4 @@ declare function sessionIdFromFileName(fileName: string): string | undefined;
 declare const ZCODE_ROW_ID_WIDTH = 8;
 declare function normalizeZcodeRowId(rowId: number): string;
 
-export { type Entry, type ImportDegradation, type NormalizedSession, type ParseResult, type SessionHeader, type SessionMessageRole, ZCODE_ROW_ID_WIDTH, normalizeZcodeRowId, parseSessionContent, parseSessionFile, readFirstJsonlLine, readFirstJsonlLineSync, serializeSession, sessionIdFromFileName };
+export { type Entry, type ImportDegradation, type NormalizedSession, type ParseResult, type SessionHeader, type SessionMessageRole, UnknownMessageRoleError, ZCODE_ROW_ID_WIDTH, normalizeZcodeRowId, parseSessionContent, parseSessionFile, readFirstJsonlLine, readFirstJsonlLineSync, serializeSession, sessionIdFromFileName };

package/dist/index.js

@@ -1,12 +1,36 @@
 // src/parse.ts
 import { readFile } from "fs/promises";
+
+// src/types.ts
+var SESSION_MESSAGE_ROLES = [
+  "user",
+  "assistant",
+  "toolResult",
+  "system"
+];
+
+// src/parse.ts
+var UnknownMessageRoleError = class extends Error {
+  /** 非法行所在行号（1-based，与编辑器行号一致） */
+  line;
+  /** 该行 message.role 的原始值（缺失时为 undefined） */
+  role;
+  constructor(line, role) {
+    super(
+      `session JSONL \u7B2C ${line} \u884C message.role \u975E\u6CD5\uFF1A${JSON.stringify(role) ?? String(role)}\uFF08\u5408\u6CD5\u503C\uFF1A${SESSION_MESSAGE_ROLES.join("/")}\uFF09\u3002\u{1F449} \u8BE5\u884C\u5185\u5BB9\u4E0D\u4F1A\u88AB\u9759\u9ED8\u4E22\u5F03\uFF1A\u5199\u5165\u65B9 pi \u7248\u672C\u53EF\u80FD\u8F83\u65B0\uFF08\u65B0\u589E role \u800C\u672C\u5305\u8BCD\u8868\u672A\u6536\u5F55\uFF09\uFF0C\u5347\u7EA7 taiji \u540E\u91CD\u8BD5\uFF0C\u6216\u4EBA\u5DE5\u4FEE\u590D\u8BE5\u884C\u7684 role \u5B57\u6BB5\u3002`
+    );
+    this.name = "UnknownMessageRoleError";
+    this.line = line;
+    this.role = role;
+  }
+};
 function isMessageRole(v) {
-  return v === "user" || v === "assistant" || v === "toolResult";
+  return SESSION_MESSAGE_ROLES.includes(v);
 }
-function parseEntryMessage(raw) {
+function parseEntryMessage(raw, line) {
   if (raw === null || typeof raw !== "object") return void 0;
   const m = raw;
-  if (!isMessageRole(m.role)) return void 0;
+  if (!isMessageRole(m.role)) throw new UnknownMessageRoleError(line, m.role);
   const message = { role: m.role, content: m.content };
   if (Array.isArray(m.toolCalls)) message.toolCalls = m.toolCalls;
   if (typeof m.toolName === "string") message.toolName = m.toolName;
@@ -20,7 +44,7 @@ function assignOptionalFields(obj, entry) {
   if (typeof obj.cwd === "string") entry.cwd = obj.cwd;
   if (obj.summary !== void 0) entry.summary = obj.summary;
 }
-function toEntry(raw) {
+function toEntry(raw, line) {
   if (typeof raw !== "object" || raw === null) return void 0;
   const obj = raw;
   if (typeof obj.type !== "string") return void 0;
@@ -32,7 +56,7 @@ function toEntry(raw) {
     parentId: typeof obj.parentId === "string" ? obj.parentId : null
   };
   if (typeof obj.timestamp === "string") entry.timestamp = obj.timestamp;
-  const message = parseEntryMessage(obj.message);
+  const message = parseEntryMessage(obj.message, line);
   if (message !== void 0) entry.message = message;
   assignOptionalFields(obj, entry);
   return entry;
@@ -40,27 +64,23 @@ function toEntry(raw) {
 function parseSessionContent(content) {
   const entries = [];
   let skippedLines = 0;
-  let lastLinePartial = false;
   const lines = content.split("\n");
   while (lines.length > 0 && lines[lines.length - 1] === "") {
     lines.pop();
   }
   for (let i = 0; i < lines.length; i++) {
     const line = lines[i];
-    const isLast = i === lines.length - 1;
     if (line.trim() === "") continue;
     let raw;
     try {
       raw = JSON.parse(line);
     } catch {
       skippedLines++;
-      if (isLast) lastLinePartial = true;
       continue;
     }
-    const entry = toEntry(raw);
+    const entry = toEntry(raw, i + 1);
     if (entry === void 0) {
       skippedLines++;
-      if (isLast) lastLinePartial = true;
       continue;
     }
     entries.push(entry);
@@ -68,8 +88,7 @@ function parseSessionContent(content) {
   return {
     entries,
     skippedLines,
-    totalBytes: Buffer.byteLength(content, "utf8"),
-    lastLinePartial
+    totalBytes: Buffer.byteLength(content, "utf8")
   };
 }
 async function parseSessionFile(filePath) {
@@ -170,6 +189,7 @@ function normalizeZcodeRowId(rowId) {
   return rowId.toString(HEX_RADIX).padStart(ZCODE_ROW_ID_WIDTH, "0");
 }
 export {
+  UnknownMessageRoleError,
   ZCODE_ROW_ID_WIDTH,
   normalizeZcodeRowId,
   parseSessionContent,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhushanwen/session-core",
-  "version": "0.11.0",
+  "version": "0.13.0",
   "type": "module",
   "description": "Canonical session model and pure JSONL primitives shared by session readers and importers: Entry/ParseResult/SessionHeader/NormalizedSession, parse/serialize, first-line byte primitive, session id invariants. Zero runtime dependencies.",
   "main": "dist/index.mjs",
@@ -26,6 +26,6 @@
   "scripts": {
     "build": "tsup",
     "typecheck": "tsc --noEmit",
-    "test": "vitest run"
+    "test": "vitest run --pool=threads"
   }
 }