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

package/README.md

@@ -2,8 +2,8 @@
 
 RDB（SQLite / PostgreSQL）持久会话后端（`ctx.sessionPersistence`）：实现上游
 `SessionHandle` 模型（`create`/`open`/`flush`/`stat`/`list`），支持配置选择
-SQLite 或 PostgreSQL 后端。设计细节（表结构、原样存储、并发写、方言差异、
-仓库结构）见 [docs/design.md](docs/design.md)。
+SQLite 或 PostgreSQL 后端。表结构、原样存储与各条流程的设计见
+[设计总览](.agents/designs/20260917-设计总览.md)，决策见 [`.agents/adrs/`](.agents/adrs)。
 
 ## 配置
 
@@ -50,45 +50,73 @@ type Config =
       type: "postgres";
       /** node-postgres 连接串；首次打开自动建表并写入 store 身份。 */
       connectionString: string;
-      /** 目标 schema（默认 public，必须已存在）；见 docs/schema.md。 */
+      /** 目标 schema（默认 public，必须已存在）。 */
       schema?: string;
     };
 ```
 
 ## 分支能力（session-branch 闭环）
 
-除 `ctx.sessionPersistence` 外，本包还实现 `@morlay/session-branch` 的
-provider 抽象并**随插件自动注册 `ctx.sessionBranch`**（`SessionBranchRdb`），
-在不修改上游代码的前提下提供 `rewind / retry / fork` 的持久化闭环：
-
-- `forkFrom`：纯 append 从闭合边界派生新会话（事件行复用，不复制）；
-- `rewind`：直接操作后端事务截断（只删桥接行），支持 live 与 cold 会话；
-- `timeline`：lineage 版本树投影。
-
-三个原语的完整语义（含 live 同步步骤、事件行复用机制、坐标论证与已知限制）
-见 [docs/branch.md](docs/branch.md)。
+除 `ctx.sessionPersistence` 外，本包还实现 `@morlay/session-branch` 的 provider
+抽象并**随插件自动注册 `ctx.sessionBranch`**（`SessionBranchRdb`），在不修改上游
+代码的前提下提供 `rewind / retry / fork` 的持久化闭环（原语：`forkFrom` 纯 append
+派生、`rewind` 后端事务截断、`timeline` 版本树投影）——语义、坐标论证与已知限制见
+[分支能力](.agents/designs/20260917-分支能力.md)。
 
 上层编排（edit / reroll / retry / rewind / fork 完整功能）由
 `@morlay/ui-conversation-message-actions` 提供，或直接在 `ctx.sessionBranch` /
 `ctx.sessionEditor` 之上编程。
 
+## 会话删除（仅已归档）
+
+delete 面由本包自持：`deleteSession(id)` 只允许删除**已归档**会话（未归档报
+`SESSION_NOT_ARCHIVED`），live（有打开的 handle 或未 materialize）报 `SESSION_LIVE`。
+删除只落该会话的行（桥接行、workspace 归属行、投影 checkpoint、会话行）——被删会话的事件行
+成为**孤儿**留在 `t_events`，不影响删除后的可见性，回收见下节。
+
+web 模式经 `POST /api/session.delete`（body `{ sessionId }`）暴露，状态映射：
+200 已删除 / 404 不存在 / 409 未归档或 live。决策与边界见
+[ADR-会话删除仅限已归档且硬删](.agents/adrs/20260917-会话删除仅限已归档且硬删.md) 与
+[ADR-删除不再清孤儿与vacuum独立成gc通道](.agents/adrs/20260918-删除不再清孤儿与vacuum独立成gc通道.md)。
+
+## 导出
+
+`POST /api/session.export`（body `{ sessionId }`）直接把会话日志打成 zip **响应体**：
+`content-type: application/zip` + `Content-Disposition` 文件名，包内 artifact 与导入通道读的
+是同一份（`readRaw` 的 `session.vN.jsonl`）。会话不存在 404，body 非法 400。只读，不限归档状态。
+
+## 孤儿回收与 VACUUM（GC）
+
+`POST /api/session.gc` 一次做完四件事：让所有运行中的 agent 退场
+（`ctx.agents.list()` 逐个 cancel 并等 `whenIdle`）→ `collectOrphanSessions()` 回收**父已不存在的
+subagent 会话**（`origin = 'subagent'`、父不在表里；有 open handle / pending 的跳过）→
+`collectOrphans()` 回收已无桥接行引用的事件行 → `vacuum()`（SQLite `VACUUM`、Postgres
+`VACUUM ANALYZE`，均不得在事务内执行）。顺序上先删会话再清事件行，被删会话独占的事件行才刚成为孤儿。
+响应 `{ orphanSessions, orphanEvents, stoppedAgents, vacuumed }`。
+
+为什么独立成通道（而不是删除时顺带做）：实测删除的成本大头就是那句全库孤儿清理
+（1 万行会话：545ms → 加孤儿清理后 2.3s），且它无法让库文件变小。代价是删除后库体积不降，
+直到执行 GC；入口在「对话管理」页，执行期间阻塞界面。
+
+## 用量统计
+
+`POST /api/session.usage` 一次回报三份数据：`totals`（含 `subagent` / `human` 拆分）、按
+天 × provider/model × subagent 的桶、按会话的行。
+
+用量写在**专用表 `t_event_usage`**（写路径顺带记录，一条 `assistant/message` 事件行一行），统计只读它，
+不再逐行解析事件 JSON——真实库实测 **1.6s → ~140ms**。老库在首次打开时**一次性回填**（表为空才跑，
+约 2.2s / 1.99 万行），两种 `f_data` 结构都认。口径不变：只算被会话引用的事件行（fork 共享行计一次、
+孤儿行不计），GC 顺带回收不再有事件行的用量行。口径与取舍见
+[ADR-用量统计走专用用量日志表](.agents/adrs/20260918-用量统计走专用用量日志表.md)。
+
 ## storages 接管（workspace 与投影缓存）
 
 `$DSH_HOME/storages` 不再产生文件：官方 `storage-json` 与
-`session-projection-cache` 由 `@morlay/better-session` 的 patch 禁用，数据落本包
-的语义专用表（表结构见 [docs/schema.md](docs/schema.md)，决策见
-[docs/adr/0009](docs/adr/0009-接管storages到rdb语义表.md)）：
-
-- **workspace 域**：官方 `workspace` 插件保留，本包在 storage hub 注册 `rdb`
-  KV 后端（`storage-domain` 的 backend 路由为 `rdb`），记录、归属、显示顺序
-  与归档分别落 `t_workspaces` / `t_workspace_sessions` / `t_workspace_state`
-  与 `t_sessions.f_archived_at`；
-- **投影 checkpoint**：本包提供 `ctx.sessionProjectionCache` 服务（替换官方
-  插件，API 与语义逐一对齐），每个投影 key 一行落 `t_session_projcache_row`
-  （identity 直接复用 `t_sessions` 的会话行）；SQLite 下读路径**直接查表**
-  （进程内不再维护 checkpoint 镜像），PostgreSQL 因驱动异步保留写穿镜像。
-- **会话标题是会话数据**：`t_sessions.f_title` 由 rdb 按 `session/title` 事件
-  维护（rewind 截断后重算），列表消费在没有 checkpoint 行时直接取该列。
+`session-projection-cache` 由 `@morlay/better-session` 的 patch 禁用，数据落本包的
+语义专用表——workspace 域经本包注册的 `rdb` KV 后端，投影 checkpoint 经本包的
+`ctx.sessionProjectionCache` 服务。表结构见
+[表结构](.agents/designs/20260917-表结构.md)，决策见
+[ADR-接管storages到rdb语义表](.agents/adrs/20260917-接管storages到rdb语义表.md)。
 
 写节流参数（默认 200 / 5000，与官方 base 装配一致）可经 settings 覆盖：
 
@@ -101,9 +129,9 @@ session-rdb:
     writeIntervalMs: 5000
 ```
 
-旧 `storages` JSON 用显式命令导入（先停掉 dsh，旧文件保留不删）：
+旧 `storages` JSON 的导入是**包内 API**（先停掉 dsh，旧文件保留不删）——没有 CLI
+入口、也不在 `exports` 里：
 
-```sh
-just import-storages --dsh-home apps/dsh-custom-next/.dsh-store \
-  --path apps/dsh-custom-next/.dsh-store/sessions/sessions.sqlite
+```ts
+await importStorages(repository, { dshHome }); // 用法见 src/import-storages.ts
 ```

package/dist/artifact.d.mts

@@ -1,4 +1,4 @@
-import { C as EventRow, w as SessionRow } from "./schema-BkQN5GyT.mjs";
+import { i as SessionRow, r as EventRow } from "./backend-DpdtxYpz.mjs";
 import { SESSION_IMPORT_PATH, SESSION_LOG_ARTIFACT_FILENAME, parseImportZip, parseJsonlArtifact, persistImport, registerSessionImport } from "./import.mjs";
 import { SessionStorageMetadata } from "@deepseek-ai/dsh-session-persistence";
 import { SessionEvent, SessionHeader } from "@deepseek-ai/dsh-session";
@@ -28,18 +28,6 @@ declare function sessionConflictRow(storage: SessionStorageMetadata): {
   fDelegationDepth: number | null;
 };
 declare function rowToEvent(row: EventRow): SessionEvent;
-/**
- * 读取时重计算 replace 的 sourceEventSeqs（sourceEventSeqs 不落库）。
- *
- * 优先采用紧邻 metering 事件（compaction/summary | compaction/prune）的
- * shadowedSeqs：它是压缩事务落库的**权威被遮蔽节点列表**（range 只是首尾
- * 边界对，压缩竞态下可能漏掉并发落地的节点——range 数值扫描会漏掉这些
- * 节点，使上游 assertProvenance 报 missing）。shadowedSeqs 已由 rowToEvent
- * 重映射到稠密坐标，与 replace 的 surfaceOp range 同空间。
- *
- * 无紧邻 metering 事件时回退到 range 数值扫描（历史数据 / 非压缩 replace，
- * 如 tool-result pruner 的旧样式），保证既有行为不变。
- */
 declare function recomputeReplaceProvenance(events: SessionEvent[]): void;
 declare function findSurfaceRepairs(events: readonly SessionEvent[]): {
   degradeToAppend: Set<number>;
@@ -48,70 +36,42 @@ declare function findSurfaceRepairs(events: readonly SessionEvent[]): {
   clampEnd: Map<number, number>;
 };
 declare function repairSurfaceOps(events: SessionEvent[]): void;
-/**
- * 读取时补全 assistant 结算字段：旧写入器不落库 `stream`（v2 才把流式记录
- * 嵌入消息），读回时缺失即补空数组——上游 seed 校验要求 turn/step/stream
- * 三者齐备，缺失会让整个会话加载失败。
- */
 declare 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 机制重建。
- */
 declare 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 的额外并发节点因此
- * 原样保留。
- */
 declare function syncMeteringRanges(events: SessionEvent[]): void;
-/**
- * 读取时把 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 对齐。
- */
 declare function renameLegacyPtcEvents(events: SessionEvent[]): void;
-/**
- * 读取视图修复总入口：形状补全（结算字段 / request header）→ PTC 词汇归一
- * → surface 语义修复 → metering 对齐 → provenance 重算 → 孤儿 inbox splice
- * 改写。全部只作用于内存视图，不落库。
- */
 declare function repairReadView(events: SessionEvent[]): void;
-/**
- * 定位无法从空状态增量重放的 agent/inbox/spliced 事件（孤儿操作）。
- *
- * 上游 Inbox 每次构造都从会话起点重放全部 inbox splice，失败即拒绝整个
- * 会话（resume / 编辑重放不可用）。rewind 截断历史轮次后若残留 splice 引用
- * 已被截断的排队消息（插入被删、消费保留，或反之），重放时越界或重复——
- * 无法独立重放。
- */
 declare function orphanInboxSpliceSeqs(events: readonly SessionEvent[]): Set<number>;
-/** 内存修复：把孤儿 inbox splice 改写为 no-op（调用方负责持久化）。 */
 declare function repairOrphanInboxSplices(events: SessionEvent[]): void;
 declare function scanRows(rows: readonly EventRow[], base?: number): {
   preserved: SessionEvent[];
   tornFrom?: number;
 };
 declare function toJsonlArtifact(meta: SessionHeader, inheritedEventCount: number, events: readonly SessionEvent[]): string;
+declare function titleOfEventData(data: string): string | undefined;
+/** 用量行的列（`t_event_usage`）。 */
+interface EventUsageRow {
+  fEventId: string;
+  fCreatedAt: number;
+  fProvider: string | null;
+  fModel: string | null;
+  fInputTokens: number;
+  fOutputTokens: number;
+  fCacheReadTokens: number;
+  fReasoningTokens: number;
+  fTotalTokens: number;
+}
 /**
- * 事件行 JSON → `session/title` 的标题文本。存储层写路径保证 `f_data` 是完整
- * 事件 JSON；形状不符（或损坏）按「无标题」处理——标题是派生显示数据。
- * @param data - `t_events.f_data` 原文。
- * @returns 标题文本，或 `undefined`。
+ * 一条事件行的用量（只有带 `usage` 的 `assistant/message` 才有）：写路径据此记录
+ * `t_event_usage`，统计因此不必逐行解析 JSON。两种 `f_data` 结构（带信封 / 老格式）都认。
+ * @param event - 待写入的事件行。
+ * @returns 用量行，或该事件没有用量时的 undefined。
  */
-declare function titleOfEventData(data: string): string | undefined;
+declare function usageRowOf(event: {
+  fEventId: string;
+  fCreatedAt: number;
+  fType: string;
+  fData: string;
+}): EventUsageRow | undefined;
 //#endregion
-export { SESSION_IMPORT_PATH, SESSION_LOG_ARTIFACT_FILENAME, findSurfaceRepairs, orphanInboxSpliceSeqs, parseImportZip, parseJsonlArtifact, persistImport, recomputeReplaceProvenance, registerSessionImport, renameLegacyPtcEvents, repairAssistantSettlement, repairOrphanInboxSplices, repairReadView, repairRequestHeaders, repairSurfaceOps, rowToEvent, rowToMeta, scanRows, sessionConflictRow, sessionInsertRow, syncMeteringRanges, titleOfEventData, toJsonlArtifact };
+export { EventUsageRow, SESSION_IMPORT_PATH, SESSION_LOG_ARTIFACT_FILENAME, findSurfaceRepairs, orphanInboxSpliceSeqs, parseImportZip, parseJsonlArtifact, persistImport, recomputeReplaceProvenance, registerSessionImport, renameLegacyPtcEvents, repairAssistantSettlement, repairOrphanInboxSplices, repairReadView, repairRequestHeaders, repairSurfaceOps, rowToEvent, rowToMeta, scanRows, sessionConflictRow, sessionInsertRow, syncMeteringRanges, titleOfEventData, toJsonlArtifact, usageRowOf };

package/dist/artifact.mjs

@@ -1,3 +1,3 @@
-import { _ as toJsonlArtifact, a as repairAssistantSettlement, c as repairRequestHeaders, d as rowToMeta, f as scanRows, g as titleOfEventData, h as syncMeteringRanges, i as renameLegacyPtcEvents, l as repairSurfaceOps, m as sessionInsertRow, n as orphanInboxSpliceSeqs, o as repairOrphanInboxSplices, p as sessionConflictRow, r as recomputeReplaceProvenance, s as repairReadView, t as findSurfaceRepairs, u as rowToEvent } from "./log-DO69NQnn.mjs";
+import { _ as toJsonlArtifact, a as repairAssistantSettlement, c as repairRequestHeaders, d as rowToMeta, f as scanRows, g as titleOfEventData, h as syncMeteringRanges, i as renameLegacyPtcEvents, l as repairSurfaceOps, m as sessionInsertRow, n as orphanInboxSpliceSeqs, o as repairOrphanInboxSplices, p as sessionConflictRow, r as recomputeReplaceProvenance, s as repairReadView, t as findSurfaceRepairs, u as rowToEvent, v as usageRowOf } from "./log-CnYct2Dv.mjs";
 import { SESSION_IMPORT_PATH, SESSION_LOG_ARTIFACT_FILENAME, parseImportZip, parseJsonlArtifact, persistImport, registerSessionImport } from "./import.mjs";
-export { SESSION_IMPORT_PATH, SESSION_LOG_ARTIFACT_FILENAME, findSurfaceRepairs, orphanInboxSpliceSeqs, parseImportZip, parseJsonlArtifact, persistImport, recomputeReplaceProvenance, registerSessionImport, renameLegacyPtcEvents, repairAssistantSettlement, repairOrphanInboxSplices, repairReadView, repairRequestHeaders, repairSurfaceOps, rowToEvent, rowToMeta, scanRows, sessionConflictRow, sessionInsertRow, syncMeteringRanges, titleOfEventData, toJsonlArtifact };
+export { SESSION_IMPORT_PATH, SESSION_LOG_ARTIFACT_FILENAME, findSurfaceRepairs, orphanInboxSpliceSeqs, parseImportZip, parseJsonlArtifact, persistImport, recomputeReplaceProvenance, registerSessionImport, renameLegacyPtcEvents, repairAssistantSettlement, repairOrphanInboxSplices, repairReadView, repairRequestHeaders, repairSurfaceOps, rowToEvent, rowToMeta, scanRows, sessionConflictRow, sessionInsertRow, syncMeteringRanges, titleOfEventData, toJsonlArtifact, usageRowOf };