@morlay/session-rdb 0.0.20 → 0.0.21-alpha.0

package/src/legacy.ts

@@ -1,8 +1,3 @@
-// 非当前格式（v0/v1/v2）历史数据读取转换：RDB 行 → 物理记录 → 上游迁移链 →
-// 当前逻辑事件。RDB 写路径从不持久化 sourceEventSeqs（读取时重计算），且
-// delta（assistant/chunk）落盘被过滤——v1→v2 迁移对无 chunk 引用的
-// assistant/message 走「无 pending 直接 emit」路径，生成 stream: [] 的 v2 事件。
-
 import {
   SESSION_FORMAT_VERSION,
   type SessionEvent,
@@ -13,7 +8,6 @@ import { sessionFormatCatalog } from "@deepseek-ai/dsh-session-format-catalog";
 import type { EventRow, SessionRow } from "./backend.ts";
 import { repairRequestHeaders, rowToMeta, scanRows } from "./log.ts";
 
-/** 重建 v0/v1/v2 物理 header 记录（RDB 行 → 物理 JSON 对象）。 */
 function physicalHeader(row: SessionRow): Record<string, unknown> {
   const common = {
     type: "session",
@@ -25,18 +19,15 @@ function physicalHeader(row: SessionRow): Record<string, unknown> {
     ...(row.fOrigin !== null ? { origin: row.fOrigin } : {}),
     delegationDepth: row.fDelegationDepth ?? 0,
   };
-  // v0/v1 物理 header 用 seedLength 表达继承前缀；v2 起改用 isSeeded，
-  // 前缀长度由 log 里的 session/end-seed 标记推导。
+
   return row.fVersion < 2
     ? { ...common, ...(row.fSeedLength !== null ? { seedLength: row.fSeedLength } : {}) }
     : { ...common, isSeeded: row.fSeedLength !== null };
 }
 
-/** 重建一条 v0/v1/v2 物理事件记录（桥接行 + 事件行 → 物理 JSON 对象）。 */
 function physicalEvent(row: EventRow): Record<string, unknown> {
   const stored = JSON.parse(row.fData) as unknown;
-  // 两种存储形状：当前写入器落完整事件信封（与 JSONL 每行同构），schema v2
-  // 时代只落 data 部分。迁移链要的是 payload，故信封形状取 `data`。
+
   const full =
     typeof stored === "object" &&
     stored !== null &&
@@ -52,13 +43,6 @@ function physicalEvent(row: EventRow): Record<string, unknown> {
   };
 }
 
-/**
- * 把非当前格式（v0/v1/v2）行转换为当前逻辑事件与 header。
- * @param row - 会话行（f_version < SESSION_FORMAT_VERSION）。
- * @param eventRows - 已扫描保留的桥接行（稠密 seq，torn tail 已剔除）。
- * @returns 当前逻辑 header、继承前缀长度与事件。
- * @throws 迁移链拒绝（格式损坏 / 无法迁移）时原样抛出。
- */
 export function convertLegacyRows(
   row: SessionRow,
   eventRows: readonly EventRow[],
@@ -78,29 +62,10 @@ export function convertLegacyRows(
   };
 }
 
-/** 会话行是否携带非当前格式（f_version < SESSION_FORMAT_VERSION）数据。 */
 export function isLegacyVersion(version: number): boolean {
   return version < SESSION_FORMAT_VERSION;
 }
 
-/**
- * 迁移链拒绝后，把旧格式行直接当**当前格式**事件视图采用。
- *
- * 旧写入器只在建会话时落一次 header version，之后跟随上游演进继续追加
- * 事件——同一个 log 因此可能是混合世代（v0 时代的行 + 新版本字段），不是
- * 任何单一已发布格式，严格迁移链必然拒绝。这些行的数据形状（消息包装、
- * 类型名）已经是当前格式，只需 header 版本归一到当前、按稠密 seq 读取；
- * 事件数据的补全与 surface 修复由读取视图修复（repairReadView）负责。
- *
- * 调用方须在此之后执行 `validateStoredEvents`：真正属于旧格式的类型
- * （`assistant/chunk` / `compact/*` 等）仍会被 fail-loud 拒绝。
- *
- * @param row - 会话行（f_version < SESSION_FORMAT_VERSION）。
- * @param eventRows - 该会话全部桥接行（按 f_sequence 升序）。
- * @returns 当前格式 header（version 归一到 SESSION_FORMAT_VERSION）、收缩后的
- *   继承前缀长度、稠密事件与可选 torn tail 起点。
- * @throws scanRows 的已提交区损坏错误（seq gap / 不可解析行）。
- */
 export function adoptLegacyRows(
   row: SessionRow,
   eventRows: readonly EventRow[],
@@ -111,14 +76,11 @@ export function adoptLegacyRows(
   tornFrom?: number;
 } {
   const { preserved, tornFrom } = scanRows(eventRows, 0);
-  // 旧格式 request/header 归一为当前格式：v3 起 system prompt 由 surface 上的
-  // system/message 承载，header 必须省略 system / 空 tools / 空 adapterDefaults
-  // （上游事件校验 fail loud）。归一必须发生在调用方 `validateStoredEvents`
-  // 之前，否则整个会话加载失败。
+
   repairRequestHeaders(preserved);
   return {
     meta: { ...rowToMeta(row), version: SESSION_FORMAT_VERSION },
-    // 继承前缀不得超过事件数（历史 rewind 未收缩的损坏样式），上游 load 判损坏。
+
     inheritedEventCount: Math.min(row.fSeedLength ?? 0, preserved.length),
     events: preserved,
     ...(tornFrom !== undefined ? { tornFrom } : {}),

package/src/log.ts

@@ -5,14 +5,6 @@ import { sessionFormatCatalog } from "@deepseek-ai/dsh-session-format-catalog";
 import type { SessionStorageMetadata } from "@deepseek-ai/dsh-session-persistence";
 import type { EventRow, SessionRow } from "./backend.ts";
 
-/**
- * 把桥接行列里的 replace surfaceOp 归一到当前字段名。
- *
- * v2 时代落库的 JSON 用 `start`/`end`，当前格式用 `startSeq`/`endSeq`；
- * 混合世代回退路径直接采用存储行，必须在此归一，否则上游 v3 surface 校验
- * 以「invalid replace surfaceOp」拒绝整个会话。非 replace 形状原样返回，
- * 由读取视图修复决定降级。
- */
 function normalizeSurfaceOp(value: unknown): SurfaceOp {
   if (typeof value !== "object" || value === null || Array.isArray(value)) {
     return value as SurfaceOp;
@@ -100,8 +92,7 @@ export function rowToEvent(row: EventRow): SessionEvent {
   const surfaceOp =
     row.fSurfaceOp !== null ? normalizeSurfaceOp(JSON.parse(row.fSurfaceOp) as unknown) : undefined;
   const record = JSON.parse(row.fData) as unknown;
-  // fData 形状判别：新写入的完整事件（含 ignorable 信封，与 JSONL 每行
-  // 同构）vs 旧 v2 库的纯 data 部分。完整事件必有 type/seq/time/data 四键。
+
   const full =
     typeof record === "object" &&
     record !== null &&
@@ -111,8 +102,6 @@ export function rowToEvent(row: EventRow): SessionEvent {
     typeof (record as Record<string, unknown>)["time"] === "number" &&
     "data" in (record as Record<string, unknown>);
   if (full) {
-    // seq/time 以桥接行/事件列为权威（rewind 截断后仍稠密连续）；
-    // surfaceOp 走桥接行列，sourceEventSeqs 不落库（读取时重计算）。
     return {
       ...(record as SessionEvent),
       seq: row.fSequence,
@@ -138,18 +127,6 @@ const SURFACE_EVENT_TYPES = new Set([
 
 const METERING_EVENT_TYPES = new Set(["compaction/summary", "compaction/prune"]);
 
-/**
- * 读取时重计算 replace 的 sourceEventSeqs（sourceEventSeqs 不落库）。
- *
- * 优先采用紧邻 metering 事件（compaction/summary | compaction/prune）的
- * shadowedSeqs：它是压缩事务落库的**权威被遮蔽节点列表**（range 只是首尾
- * 边界对，压缩竞态下可能漏掉并发落地的节点——range 数值扫描会漏掉这些
- * 节点，使上游 assertProvenance 报 missing）。shadowedSeqs 已由 rowToEvent
- * 重映射到稠密坐标，与 replace 的 surfaceOp range 同空间。
- *
- * 无紧邻 metering 事件时回退到 range 数值扫描（历史数据 / 非压缩 replace，
- * 如 tool-result pruner 的旧样式），保证既有行为不变。
- */
 export function recomputeReplaceProvenance(events: SessionEvent[]): void {
   for (let i = 0; i < events.length; i++) {
     const event = events[i]!;
@@ -278,19 +255,14 @@ export function findSurfaceRepairs(events: readonly SessionEvent[]): {
       isEventSeqLike(end);
     const startIdx = shapeOk ? nodes.indexOf(start as number) : -1;
     let endIdx = shapeOk ? nodes.indexOf(end as number) : -1;
-    // 旧写入器重编号事件后，存储的 range 端点可能落在旧坐标空间：end 不在
-    // 当前 surface 中，但紧邻 metering 事件的 shadowedSeqs 仍给出被遮蔽
-    // 节点数量。按数量从 start 起夹取到当前 surface 的同长区间，保住压缩
-    // 语义（否则只能降级 append，被压缩历史全部回到派生历史）。
+
     let clamped: number | undefined;
     if (shapeOk && startIdx !== -1 && endIdx === -1) {
       clamped = clampReplaceEnd(events, index, nodes, startIdx);
       if (clamped !== undefined) endIdx = nodes.indexOf(clamped);
     }
     const rangeOk = shapeOk && startIdx !== -1 && endIdx !== -1 && startIdx <= endIdx;
-    // assistant/message 的来源内嵌在 stream，上游禁止其携带 sourceEventSeqs，
-    // replace 的 provenance 因此永远无法满足 fold 校验——降级 append 是唯一
-    // 可加载形态。
+
     const provenanceOk = event.type !== "assistant/message";
     let rewriteOk = true;
     if (rangeOk && event.type === "tool/result") {
@@ -314,14 +286,6 @@ export function findSurfaceRepairs(events: readonly SessionEvent[]): {
   return { degradeToAppend, addAppendMarker, clearSurfaceOp, clampEnd };
 }
 
-/**
- * 夹取一个 end 落在旧坐标空间的 replace 的结尾。
- *
- * 仅当 replace 紧邻一个 metering 事件且其 `shadowedSeqs` 是权威数量时成立；
- * 夹取点是从 `start` 起的第 `shadowedSeqs.length` 个当前 surface 节点（不足
- * 则取当前 surface 末尾）。无法夹取（start 也不在当前 surface）时返回
- * `undefined`，由调用方降级为 append。
- */
 function clampReplaceEnd(
   events: readonly SessionEvent[],
   index: number,
@@ -365,11 +329,6 @@ export function repairSurfaceOps(events: SessionEvent[]): void {
   }
 }
 
-/**
- * 读取时补全 assistant 结算字段：旧写入器不落库 `stream`（v2 才把流式记录
- * 嵌入消息），读回时缺失即补空数组——上游 seed 校验要求 turn/step/stream
- * 三者齐备，缺失会让整个会话加载失败。
- */
 export function repairAssistantSettlement(events: SessionEvent[]): void {
   for (const event of events) {
     if (event.type !== "assistant/message" && event.type !== "assistant/attempt") continue;
@@ -378,13 +337,6 @@ export function repairAssistantSettlement(events: SessionEvent[]): void {
   }
 }
 
-/**
- * 读取时把旧格式 `request/header` 归一为当前格式：v3 起 system prompt 由
- * surface 上的 `system/message` 承载，header 必须省略 `system`，空 `tools` /
- * `adapterDefaults` 也必须省略（上游 v3 事件校验 fail loud）。混合世代回退
- * 视图直接采用存储行，不归一会让整个会话加载失败。system prompt 因此不再
- * 进入模型请求；会话下次运行由 v3 的 system/message 机制重建。
- */
 export function repairRequestHeaders(events: SessionEvent[]): void {
   for (const event of events) {
     if (event.type !== "request/header") continue;
@@ -406,17 +358,6 @@ export function repairRequestHeaders(events: SessionEvent[]): void {
   }
 }
 
-/**
- * 把紧邻 replace 的 metering 事件的 `shadowedRange` / `shadowedSeqs` 对齐到
- * replace 最终的稠密 range。
- *
- * 旧写入器重编号事件后，metering 与 replace 一起落在旧坐标空间：二者数值
- * 相等但与当前 surface 无关。夹取（或 range 本身已落在稠密空间而 metering
- * 仍是旧值）后二者不再相等，而上游 token-meter 契约要求紧邻的 metering
- * range 与 replace range 完全一致（否则报 no adjacent shadow price）。range
- * 已一致时不改写——当前写入器保证一致，shadowedSeqs 的额外并发节点因此
- * 原样保留。
- */
 export function syncMeteringRanges(events: SessionEvent[]): void {
   for (let i = 1; i < events.length; i++) {
     const metering = events[i - 1]!;
@@ -447,7 +388,6 @@ const PTC_EVENT_RENAMES: Record<string, string> = {
   "tool/code-dispatch": "tool/ptc-dispatch",
 };
 
-/** 把消息的 `tools-code-mode` 插件来源改写为 `tools-ptc`（非该来源原样返回）。 */
 function renamePtcMessageSource(message: unknown): unknown {
   if (typeof message !== "object" || message === null || Array.isArray(message)) return message;
   const record = message as Record<string, unknown>;
@@ -460,22 +400,12 @@ function renamePtcMessageSource(message: unknown): unknown {
   return { ...record, source: { ...sourceRecord, plugin: "tools-ptc" } };
 }
 
-/** 宽类型事件视图：PTC 词汇归一涉及本包 SessionEventMap 之外的插件类型。 */
 interface LegacyPtcEvent {
   type: string;
   data: unknown;
   [key: string]: unknown;
 }
 
-/**
- * 读取时把 v2 时代的 PTC 词汇归一为当前词汇。
- *
- * 上游 v2→v3 迁移把 `tool/code-dispatch(-start)` 改名为
- * `tool/ptc-dispatch(-start)`、把 `tools-code-mode` 插件来源改名为 `tools-ptc`、
- * 把 agent preset 值 `code` 改名为 `ptc`。混合世代回退视图直接采用存储行，
- * 不重命名会被上游 v3 校验以「unknown event type」拒绝整个会话。词汇改写
- * 与上游迁移链的 renamePtcEvent 对齐。
- */
 export function renameLegacyPtcEvents(events: SessionEvent[]): void {
   for (let index = 0; index < events.length; index++) {
     const event = events[index] as unknown as LegacyPtcEvent;
@@ -517,11 +447,6 @@ export function renameLegacyPtcEvents(events: SessionEvent[]): void {
   }
 }
 
-/**
- * 读取视图修复总入口：形状补全（结算字段 / request header）→ PTC 词汇归一
- * → surface 语义修复 → metering 对齐 → provenance 重算 → 孤儿 inbox splice
- * 改写。全部只作用于内存视图，不落库。
- */
 export function repairReadView(events: SessionEvent[]): void {
   repairAssistantSettlement(events);
   repairRequestHeaders(events);
@@ -539,20 +464,10 @@ interface InboxSpliceLike {
   inserted?: Array<{ id?: unknown }>;
 }
 
-/**
- * 定位无法从空状态增量重放的 agent/inbox/spliced 事件（孤儿操作）。
- *
- * 上游 Inbox 每次构造都从会话起点重放全部 inbox splice，失败即拒绝整个
- * 会话（resume / 编辑重放不可用）。rewind 截断历史轮次后若残留 splice 引用
- * 已被截断的排队消息（插入被删、消费保留，或反之），重放时越界或重复——
- * 无法独立重放。
- */
 export function orphanInboxSpliceSeqs(events: readonly SessionEvent[]): Set<number> {
   const inbox: Record<string, Array<{ id: string }>> = { "next-turn": [], "next-step": [] };
   const orphan = new Set<number>();
   for (const raw of events) {
-    // agent/inbox/spliced 属 dsh-agent 类型扩展，不在本包 SessionEventMap——
-    // 用宽类型 duck-type 读取，避免判别联合窄化到 never。
     const event = raw as unknown as { type: string; seq: number; data: InboxSpliceLike };
     if (event.type !== "agent/inbox/spliced") continue;
     const { target, start, removedCount, inserted } = event.data;
@@ -601,7 +516,6 @@ export function orphanInboxSpliceSeqs(events: readonly SessionEvent[]): Set<numb
   return orphan;
 }
 
-/** 内存修复：把孤儿 inbox splice 改写为 no-op（调用方负责持久化）。 */
 export function repairOrphanInboxSplices(events: SessionEvent[]): void {
   const orphan = orphanInboxSpliceSeqs(events);
   if (orphan.size === 0) return;
@@ -622,8 +536,6 @@ export function scanRows(
   rows: readonly EventRow[],
   base = 0,
 ): { preserved: SessionEvent[]; tornFrom?: number } {
-  // Pass 1：解析每行 data；JSON 非法的行是洞（seq/type 列即使在 data 损坏
-  // 时也存在）。
   interface Parsed {
     ok: boolean;
     event?: SessionEvent;
@@ -636,7 +548,6 @@ export function scanRows(
     }
   });
 
-  // 最后一个合法 turn/end 的索引——洞在闭合轮内一律是已提交损坏。
   let lastTurnEnd = -1;
   for (let i = parsed.length - 1; i >= 0; i--) {
     if (parsed[i]?.ok && rows[i]?.fType === "turn/end") {
@@ -645,8 +556,6 @@ export function scanRows(
     }
   }
 
-  // 保留连续前缀（含完整的中断轮）；最后一个已提交边界之前的洞抛错，
-  // 之后的洞停止（torn tail）。
   const preserved: SessionEvent[] = [];
   for (let i = 0; i < rows.length; i++) {
     const p = parsed[i];
@@ -655,19 +564,18 @@ export function scanRows(
         throw new Error(
           `corrupt session log: unparsable committed event at seq ${rows[i]?.fSequence}`,
         );
-      break; // 最后一个 turn/end 之后的 torn tail 片段——停止、容忍
+      break;
     }
     if (p.event.seq !== base + i) {
       if (i <= lastTurnEnd)
         throw new Error(
           `corrupt session log: seq gap in committed region (expected ${base + i}, got ${p.event.seq})`,
         );
-      break; // 最后一个 turn/end 之后的 seq 空洞——torn tail，停止
+      break;
     }
     preserved.push(p.event);
   }
 
-  // 保留前缀之外的行是未提交的 torn tail；其首个 seq 是物理删除起点。
   return preserved.length < rows.length
     ? { preserved, tornFrom: base + preserved.length }
     : { preserved };
@@ -696,21 +604,70 @@ export function toJsonlArtifact(
   return lines.join("\n");
 }
 
-/**
- * 事件行 JSON → `session/title` 的标题文本。存储层写路径保证 `f_data` 是完整
- * 事件 JSON；形状不符（或损坏）按「无标题」处理——标题是派生显示数据。
- * @param data - `t_events.f_data` 原文。
- * @returns 标题文本，或 `undefined`。
- */
 export function titleOfEventData(data: string): string | undefined {
   try {
-    // 当前世代：`{...envelope, data:{title}}`；旧世代（v0-v2）的 f_data 直接
-    // 平铺事件 data，title 在顶层。两者都读，避免 legacy 会话的标题被清空。
     const value = JSON.parse(data) as { data?: { title?: unknown }; title?: unknown };
     const title = value.data?.title ?? value.title;
     return typeof title === "string" ? title : undefined;
   } catch {
-    // 写路径已保证 JSON；此处只可能是损坏数据，读作无标题。
     return undefined;
   }
 }
+
+/** 用量行的列（`t_event_usage`）。 */
+export interface EventUsageRow {
+  fEventId: string;
+  fCreatedAt: number;
+  fProvider: string | null;
+  fModel: string | null;
+  fInputTokens: number;
+  fOutputTokens: number;
+  fCacheReadTokens: number;
+  fReasoningTokens: number;
+  fTotalTokens: number;
+}
+
+function numericField(value: unknown): number {
+  return typeof value === "number" && Number.isFinite(value) ? Math.max(0, Math.trunc(value)) : 0;
+}
+
+function textField(value: unknown): string | null {
+  return typeof value === "string" && value !== "" ? value : null;
+}
+
+/**
+ * 一条事件行的用量（只有带 `usage` 的 `assistant/message` 才有）：写路径据此记录
+ * `t_event_usage`，统计因此不必逐行解析 JSON。两种 `f_data` 结构（带信封 / 老格式）都认。
+ * @param event - 待写入的事件行。
+ * @returns 用量行，或该事件没有用量时的 undefined。
+ */
+export function usageRowOf(event: {
+  fEventId: string;
+  fCreatedAt: number;
+  fType: string;
+  fData: string;
+}): EventUsageRow | undefined {
+  if (event.fType !== "assistant/message") return undefined;
+  let parsed: Record<string, unknown>;
+  try {
+    parsed = JSON.parse(event.fData) as Record<string, unknown>;
+  } catch {
+    return undefined;
+  }
+  const envelope = (parsed["data"] ?? parsed) as Record<string, unknown>;
+  const usage = envelope["usage"];
+  if (typeof usage !== "object" || usage === null) return undefined;
+  const source = (envelope["message"] as { source?: Record<string, unknown> } | undefined)?.source;
+  const row: EventUsageRow = {
+    fEventId: event.fEventId,
+    fCreatedAt: event.fCreatedAt,
+    fProvider: textField(source?.["provider"]),
+    fModel: textField(source?.["model"]),
+    fInputTokens: numericField((usage as Record<string, unknown>)["inputTokens"]),
+    fOutputTokens: numericField((usage as Record<string, unknown>)["outputTokens"]),
+    fCacheReadTokens: numericField((usage as Record<string, unknown>)["cacheReadTokens"]),
+    fReasoningTokens: numericField((usage as Record<string, unknown>)["reasoningTokens"]),
+    fTotalTokens: numericField((usage as Record<string, unknown>)["totalTokens"]),
+  };
+  return row;
+}