@morlay/session-rdb 0.0.9

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 morlay
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,93 @@
+# @morlay/session-rdb
+
+RDB（SQLite / PostgreSQL）持久会话后端（`ctx.sessionPersistence`）：通过 drizzle
+实现 `PersistenceBackend<number>`，复用上游 `PersistenceCoordinator` 与契约测试套件，
+支持配置选择 SQLite 或 PostgreSQL 后端。设计细节（表结构、delta 过滤、并发写、
+方言差异、仓库结构）见 [docs/design.md](docs/design.md)。
+
+## 安装
+
+包发布在 GitHub Packages，按包名安装到 dsh profile（示例：web；`dsh plugin
+add` 把参数原样转发给 pnpm，版本号按发布版本调整）。registry 必须限定在
+`@morlay` scope（`--config.@morlay:registry=…`），不要用全局 `--registry`，
+否则依赖（`@deepseek-ai/*` 等）也会被指到 GitHub Packages 而解析失败：
+
+```sh
+dsh plugin --profile=web add "@morlay/session-rdb"
+```
+
+GitHub Packages 的 registry 要求认证（公开包也一样）：profile 的 `.npmrc`
+需为 `npm.pkg.github.com` 配置访问 token（如
+`//npm.pkg.github.com/:_authToken=<token>`），详见
+[GitHub 文档](https://docs.github.com/packages/working-with-a-github-packages-registry/working-with-the-npm-registry)。
+
+## 配置
+
+配置写在 `${DSH_HOME}/settings.yaml`，settings namespace 为插件短名
+`session-rdb`（与 cordis 插件 `name` 一致）：
+
+```yaml
+session-rdb:
+  type: sqlite
+  # path 省略时回落 cordis.patch.yml 的默认（$DSH_HOME/sessions/sessions.sqlite，
+  # 由 bundle patch 的 !!js 表达式求值）；自定义路径请用绝对路径字符串。
+  path: /absolute/path/to/sessions.sqlite
+  journalMode: wal
+  busyTimeout: 5000
+```
+
+> settings.yaml 是纯 YAML（settings-local 用 `yaml` 库解析），**不支持 `!!js`
+> JS 表达式**——`!!js dshHomePath(...)` 会被当作字面字符串。`!!js` 只在
+> `cordis.patch.yml`（bundle patch 层，loader 求值）有效。
+
+字段即 Config 判别联合（见下）；未写出的字段回落到 bundle patch / cordis.yml 的
+config 默认值。PostgreSQL：
+
+```yaml
+session-rdb:
+  type: postgres
+  connectionString: postgres://user:pass@localhost:5432/sessions
+```
+
+Config 类型：
+
+```ts
+type Config =
+  | {
+      type: "sqlite";
+      /** SQLite 数据库文件路径；`:memory:` 用于测试。 */
+      path: string;
+      /** journal_mode：`wal`（默认）/ `delete` / `truncate` / `persist`。 */
+      journalMode?: "wal" | "delete" | "truncate" | "persist";
+      /** 写锁竞争等待毫秒数（默认 5000）。 */
+      busyTimeout?: number;
+    }
+  | {
+      type: "postgres";
+      /** node-postgres 连接串；首次打开自动建表并写入 store 身份。 */
+      connectionString: string;
+    };
+```
+
+## 分支能力（session-branch 闭环）
+
+除 `ctx.sessionPersistence` 外，本包还实现 `@morlay/session-branch` 的
+provider 抽象并**随插件自动注册 `ctx.sessionBranch`**（`SessionBranchRdb`），
+在不修改上游代码的前提下提供 `rewind / retry / fork` 的持久化闭环：
+
+- **`forkFrom`**：走标准 coordinator 路径（`create` + `append`）从闭合边界
+  派生新会话（纯 append，`parentSession` / `seedLength` lineage）；
+- **`rewind`**：直接操作后端事务截断到闭合边界（DELETE 尾部 + head 回退 +
+  revision bump），随后重新 `load` 同步 coordinator 状态，并更新并发写
+  检测 head；**支持 live 会话**（`ctx.sessions` 有 owner 时同样就地工作：
+  先 flush write-behind 缓冲 → 截断 RDB → 截断 live 内存 log 并复位
+  surface/header/context/derived 派生缓存 → 重置 agent 请求头标记 →
+  同步 coordinator cursor；不调用 `load`——live 时 load 会先 flush 撤销
+  截断）；
+- **`timeline`**：`parentSession` + `seedLength` 版本树投影（live 会话含
+  版本效果；cold 会话因版本事件携带 `ignorable` 不进 canonical log 而只有
+  lineage 骨架）。
+
+上层编排（edit / reroll / retry / rewind / fork 完整功能）由
+`@morlay/ui-conversation-message-actions` 提供，或直接在 `ctx.sessionBranch` /
+`ctx.sessionEditor` 之上编程。

package/cordis.patch.yml

@@ -0,0 +1,13 @@
+# @morlay/session-rdb bundle patch.
+#
+# 在 profile 的 dsh.profile.bundles 中列出本包后，本 patch 在 base 层之后
+# 生效，插入 RDB 持久化后端插件行（默认 SQLite，库文件放
+# $DSH_HOME/sessions/sessions.sqlite）。用户可在 profile 的 cordis.patch.yml 中
+# 按 id 覆盖 config（例如切到 PostgreSQL）。
+
+- insert:
+    - id: session-rdb
+      name: "@morlay/session-rdb"
+      config:
+        type: sqlite
+        path: !!js dshHomePath('sessions', 'sessions.sqlite')

package/lib/index.d.mts

@@ -0,0 +1,528 @@
+import { Context } from "@deepseek-ai/cordis";
+import z from "@deepseek-ai/schemastery";
+import { PersistenceBackend, SessionLocation, SessionPersistence, SessionPersistenceRevision, SessionPersistenceSnapshot, StoredPrefix, StoredSuffix } from "@deepseek-ai/dsh-session-persistence";
+import { Session, SessionEvent, SessionHeader, SessionId } from "@deepseek-ai/dsh-session";
+import { BranchAnchorMode, BranchBoundary, ForkFromOptions, SessionBranch, SessionBranchProvider } from "@morlay/session-branch";
+//#region src/backend.d.ts
+/**
+ * 与方言无关的 `t_sessions` 行投影。SQLite / PostgreSQL 的 drizzle
+ * `InferSelectModel` 均结构兼容（各自多出的自增主键列不影响赋值）。
+ */
+interface SessionRow {
+  fSessionId: string;
+  /** Empty string means no head (fresh session or rewound to empty). */
+  fHeadEventId: string;
+  fHeadSequence: number;
+  fVersion: number;
+  fCreatedAt: number;
+  fCwd: string | null;
+  fParentSession: string | null;
+  fSeedLength: number | null;
+  fOrigin: string | null;
+  fDelegationDepth: number | null;
+  /** Stable identity assigned when this log is materialized. */
+  fIncarnation: string;
+  /** Monotonic log-change token incremented in each mutating transaction. */
+  fRevision: number;
+}
+/**
+ * 一次事件插入的完整列值（`t_events` 一行），由存储层按事件构造、后端落库。
+ */
+interface EventInsert {
+  fEventId: string;
+  fParentId: string;
+  fKind: string;
+  fRole: string;
+  fName: string;
+  fActionId: string;
+  fEncoding: string;
+  fData: string;
+  fCreatedAt: number;
+  fOriginalSeq: number;
+  fSourceEventSeqs: string | null;
+  fSurfaceOp: string | null;
+}
+/**
+ * 一个 joined `t_session_events` + `t_events` 行：按 session 本地 `f_sequence`
+ * 寻址的持久化事件（`f_data` 为 JSON 文本，surface 列为 JSON 文本或 null）。
+ */
+interface EventRow {
+  /** `t_session_events.f_sequence` — the dense persisted seq. */
+  fSequence: number;
+  /** `t_events.f_original_seq` — the upstream seq before delta filtering. */
+  fOriginalSeq: number;
+  /** `t_events.f_kind` — the upstream `SessionEvent.type`. */
+  fKind: string;
+  /** `t_events.f_created_at` — the upstream `SessionEvent.time`. */
+  fCreatedAt: number;
+  /** `t_events.f_data` — JSON-encoded event data. */
+  fData: string;
+  /** JSON-encoded `number[]` — the event's sourceEventSeqs (upstream seqs), or null. */
+  fSourceEventSeqs: string | null;
+  /** JSON-encoded `SurfaceOp` — how the event entered the surface, or null. */
+  fSurfaceOp: string | null;
+}
+/**
+ * 事务内可用的数据访问原语。后端保证这些调用落在同一个数据库事务里
+ * （SQLite 单连接隐式满足；PostgreSQL 绑定到 drizzle 的事务句柄）。
+ */
+interface BackendTx {
+  /** Insert-or-replace the session's metadata row (initial head cursor). */
+  upsertSession(meta: SessionHeader, incarnation: string): Promise<void>;
+  /** Fetch the head cursor; the caller materialized the row first. */
+  getHead(id: SessionId): Promise<Pick<SessionRow, "fHeadEventId" | "fHeadSequence">>;
+  /**
+   * Insert event rows in ONE multi-row INSERT. Callers pass non-empty arrays;
+   * the implementation may no-op on an empty input.
+   */
+  insertEvents(events: EventInsert[]): Promise<void>;
+  /**
+   * Insert session↔event bridge rows in ONE multi-row INSERT. Callers pass
+   * non-empty arrays; the implementation may no-op on an empty input.
+   */
+  insertBridges(rows: Array<{
+    fSessionId: SessionId;
+    fEventId: string;
+    fSequence: number;
+  }>): Promise<void>;
+  /** Move the head cursor forward. */
+  updateHead(id: SessionId, headEventId: string, headSequence: number): Promise<void>;
+  /** Increment the session's revision by one. */
+  bumpRevision(id: SessionId): Promise<void>;
+  /** Delete bridge rows with `f_sequence >= fromSequence` (torn-tail truncate). */
+  deleteBridgeTail(id: SessionId, fromSequence: number): Promise<void>;
+  /** The bridge row just below `sequence` (the surviving head anchor), if any. */
+  getPrevBridge(id: SessionId, sequence: number): Promise<{
+    fEventId: string;
+    fSequence: number;
+  } | undefined>;
+  /** The highest bridge row (the physical tail anchor), if any. */
+  getLastBridge(id: SessionId): Promise<{
+    fEventId: string;
+    fSequence: number;
+  } | undefined>;
+  /**
+   * Update an event's mutable columns in place (used by the per-session
+   * provenance cleanse, which rewrites surface/provenance JSON into the dense
+   * seq space). Undefined fields are left untouched; null clears the column.
+   */
+  updateEventFields(id: SessionId, sequence: number, fields: {
+    fSourceEventSeqs?: string | null;
+    fSurfaceOp?: string | null;
+    fData?: string;
+  }): Promise<void>;
+}
+/**
+ * 存储后端：连接生命周期 + store 身份 + 事务外读取。`storeIdentity` 仅在
+ * {@link open} 完成后有效。
+ */
+interface Backend {
+  readonly kind: "sqlite" | "postgres";
+  /** Source-qualified store identity (revision 前缀)，open 后可用。 */
+  readonly storeIdentity: string;
+  /** 连接 + 建表 + 版本/身份校验 + 读取 store id；失败时抛错（不迁移）。 */
+  open(): Promise<void>;
+  /** Fetch a session's row, or undefined if absent. */
+  getSession(id: SessionId): Promise<SessionRow | undefined>;
+  /** Lightweight two-column upstream→persisted seq map source. */
+  getSeqMapRows(id: SessionId): Promise<Array<{
+    fSequence: number;
+    fOriginalSeq: number;
+    fKind: string;
+  }>>;
+  /** Joined event rows for one session, dense seq ascending (optionally from a seq). */
+  getEventRows(id: SessionId, fromSequence?: number): Promise<EventRow[]>;
+  /** All materialized sessions' rows. */
+  listSessions(): Promise<SessionRow[]>;
+  /** Run `fn` inside one durable transaction. */
+  transaction<T>(fn: (tx: BackendTx) => Promise<T>): Promise<T>;
+  /** Close the connection (awaited by the coordinator's dispose, post-drain). */
+  close(): Promise<void>;
+}
+//#endregion
+//#region src/write-guard.d.ts
+/**
+ * The write-authority state machine for one backend instance. Not part of the
+ * {@link Backend} seam: it guards the orchestration layer's own invariants and
+ * lives entirely in memory.
+ */
+declare class WriteGuard {
+  /**
+   * Last CONFIRMED dense head per session — the head this instance itself
+   * wrote or observed via `loadStored`. `-1` records a confirmed absence (no
+   * row). `undefined` (absent from the map) means this instance never read or
+   * wrote the session.
+   */
+  private readonly headSeqs;
+  /**
+   * Upstream seqs of delta events dropped per session. Mirrors `headSeqs` in
+   * shape: the concurrent-writer guarantee limits each session to one writer,
+   * so this instance is the only authority for its dropped seqs.
+   */
+  private readonly filteredSeqs;
+  /**
+   * Record a head this instance actually observed or wrote.
+   * @param id - the session id.
+   * @param head - the confirmed dense head, or `-1` for a confirmed absence
+   *   (a fresh session this instance has read about — a later append to a
+   *   session that meanwhile got a row must reject).
+   */
+  confirmHead(id: SessionId, head: number): void;
+  /**
+   * Fail loud when the on-disk head no longer matches this instance's last
+   * confirmed head for the session. `undefined` (never read/written here) is
+   * only acceptable for a session with NO row: a row written by someone else
+   * means this instance's coordinator cursor is not the log's authority.
+   * @param id - the session id.
+   * @param storedHead - the on-disk head cursor, read inside the append
+   *   transaction before any re-numbering happens.
+   */
+  assertNoConcurrentWriter(id: SessionId, storedHead: number): void;
+  /**
+   * Record the upstream seqs of events dropped for a session (delta events and
+   * ignorable events), so a later batch's `assistant/message` can prune
+   * `sourceEventSeqs` references to events that never got a persisted row.
+   * @param id - the session id.
+   * @param seqs - the dropped events' upstream seqs (pure-delta batches included).
+   */
+  noteDropped(id: SessionId, seqs: Iterable<number>): void;
+  /**
+   * Prune `sourceEventSeqs` references that hit this session's dropped-delta
+   * seq set. `undefined`-like state (no dropped seqs recorded for the session)
+   * leaves the list untouched, matching the write path's "no known drops →
+   * keep verbatim" semantics (repair closers, which never carry provenance,
+   * call through the identity path).
+   *
+   * The predicate is THIS INSTANCE's view (see
+   * {@link pruneSourceEventSeqs}): only seqs it knows were dropped are
+   * pruned — references to rows persisted by another instance (e.g. a resume
+   * seed segment) must survive, so the disk-wide view used by the one-shot
+   * repair script is not applicable here.
+   * @param id - the session id.
+   * @param refs - the event's `sourceEventSeqs` (upstream seqs).
+   * @returns the pruned list; identical content when nothing was dropped.
+   */
+  pruneRefs(id: SessionId, refs: readonly number[]): number[];
+}
+//#endregion
+//#region src/schema.d.ts
+/**
+ * The on-disk schema version. Bumped only on a breaking change to the table
+ * layout; orthogonal to a session's own `version` (which versions the EVENT
+ * vocabulary, stored per session in the `t_sessions` row).
+ */
+declare const SCHEMA_VERSION = 1;
+/**
+ * Event types whose CONTENT is not persisted: the backend drops these rows
+ * entirely and re-numbers the surviving events to a dense persisted seq.
+ * Mirrors the persistence proposal's "ephemeral events never enter the
+ * canonical log" split.
+ */
+declare const EPHEMERAL_EVENT_TYPES: readonly ["assistant/chunk"];
+/**
+ * Journal modes the backend will run under. `wal` is the default and the
+ * durability model the persistence ADR records; the rollback-journal modes
+ * (`delete`/`truncate`/`persist`) exist for filesystems where WAL's
+ * shared-memory files do not work (network mounts). `memory`/`off` are
+ * excluded: dropping journal durability silently contradicts what this
+ * backend promises.
+ */
+type JournalMode = "wal" | "delete" | "truncate" | "persist";
+//#endregion
+//#region src/branch.d.ts
+/**
+ * 定位 `atSeq` 锚定的闭合 `turn/end` 边界 seq。见
+ * {@link SessionBranchProvider.readBranchPrefix} 的锚定语义说明。
+ * @param events - 完整（或前缀）事件列表，seq 连续。
+ * @param atSeq - 锚定 seq（inclusive）；省略取最后闭合轮次。
+ * @param mode - `"after"`（默认）或 `"before"`。
+ * @returns 边界事件 seq；`"before"` 模式下 atSeq 之前无闭合轮次时返回 -1
+ *   （空前缀）。
+ */
+declare function locateTurnEnd(events: readonly SessionEvent[], atSeq?: number, mode?: BranchAnchorMode): number;
+/**
+ * live rewind 所需的「live 会话/agent」最小访问面。上游 `Session` 是
+ * append-only、缓存增量式对象，无公开截断方法；`PersistenceCoordinator`
+ * 的 `states` 是私有 Map。这些是**运行时最小侵入**（不改上游源码，仅在
+ * 编排层操作编译后对象字段），由 `SessionBranchRdb` 注入。
+ */
+interface LiveSessionHooks {
+  /** 查当前 live 会话（`ctx.sessions.get`）。 */
+  getSession(id: SessionId): Session | undefined;
+  /** 查当前 live agent（`ctx.agents?.get`，agents 服务可选）。 */
+  getAgent(id: SessionId): LiveAgentLike | undefined;
+  /** 立即落盘 live 会话的 write-behind 缓冲（`ctx.sessions.flush`）。 */
+  flush(session: Session): Promise<boolean>;
+  /**
+   * 截断后同步 coordinator 的会话内存状态：把 `states` 条目的 `cursor`
+   * 对齐到新的尾部（= boundary + 1），使下一次 append 的 seq 连续性校验
+   * 通过。**不能**删除 `states` 条目——live 会话的下一次 append 若走
+   * `adopt` 会经 `SessionStore.prepare` 构造 detached session，与 store 中
+   * 的 live entry 冲突。
+   */
+  setCoordinatorCursor(id: SessionId, cursor: number): void;
+}
+/** agent 的最小 live 形态：持有同一会话 + 可重置请求头日志标记。 */
+interface LiveAgentLike {
+  session: Session;
+  /** 编译后字段：是否已 append 过首个 `request/header`（截断后需重置）。 */
+  requestHeaderLogged?: boolean;
+}
+/**
+ * RDB 分支数据层实现（`SessionBranchProvider`）。与 `SessionPersistenceRdb`
+ * 共享同一数据库连接（`Backend`）与 coordinator 写路径。
+ */
+declare class SessionBranchRdbProvider implements SessionBranchProvider {
+  private readonly persistence;
+  /** live 会话/agent 访问面（rewind 支持 live session 时使用）。 */
+  private readonly live;
+  readonly name = "session-rdb";
+  constructor(persistence: SessionPersistenceRdb,
+  /** live 会话/agent 访问面（rewind 支持 live session 时使用）。 */
+  live?: LiveSessionHooks);
+  readBranchPrefix(id: SessionId, atSeq?: number, mode?: BranchAnchorMode, signal?: AbortSignal): Promise<BranchBoundary>;
+  forkFrom(sourceId: SessionId, options?: ForkFromOptions, signal?: AbortSignal): Promise<SessionId>;
+  rewind(id: SessionId, toBoundary: number, signal?: AbortSignal): Promise<SessionPersistenceSnapshot>;
+}
+/**
+ * RDB 的 `ctx.sessionBranch` 服务：组合 {@link SessionBranchRdbProvider} 的
+ * 数据层原语与共享版本树投影。插件把本类注册为 `sessionBranch` 服务后，
+ * 编排层即可通过统一服务面完成 rewind / retry / fork。
+ */
+declare class SessionBranchRdb extends SessionBranch {
+  static inject: string[];
+  constructor(ctx: import("@deepseek-ai/cordis").Context);
+  private readonly provider;
+  readBranchPrefix(id: SessionId, atSeq?: number, mode?: BranchAnchorMode, signal?: AbortSignal): Promise<BranchBoundary>;
+  forkFrom(sourceId: SessionId, options?: ForkFromOptions, signal?: AbortSignal): Promise<SessionId>;
+  rewind(id: SessionId, toBoundary: number, signal?: AbortSignal): Promise<SessionPersistenceSnapshot>;
+  /**
+   * 清洗一个 session 的 surface/provenance 坐标到稠密空间（持久化层透传）。
+   * 旧数据（rewind 前写入）的 sourceEventSeqs / surfaceOp / shadowedRange
+   * 是上游坐标,读取时每次都要对齐;清洗一次性写回稠密坐标,之后读取无需
+   * 对齐。返回实际变更的事件数。
+   */
+  cleanseSession(sessionId: SessionId, signal?: AbortSignal): Promise<{
+    changed: number;
+  }>;
+  /**
+   * 同步 live 会话的 coordinator 内存 cursor，跳过 ignorable 占位事件。
+   * 编排层在 rewind 后把 ignorable 版本效果 push 进 live log（不发布、不
+   * 进缓冲）——它占用一个上游 seq，但 coordinator 的 cursor（rewind 设到
+   * 截断后长度）看不见它；不跳过的话，flush 的 `appendLiveBatch` 会以
+   * `e.seq >= cursor` 过滤掉 cursor 之前的事件（manualTurn 永远不落盘），
+   * 或 `appendCore` 的 seq 连续性校验错位。这里把 cursor 从当前值起跳过
+   * 连续的 ignorable 事件，对齐到下一个待持久化事件的 seq。
+   */
+  syncLiveCursor(sessionId: SessionId): void;
+  timeline(sessionId: SessionId, signal?: AbortSignal): Promise<import("@morlay/session-branch").BranchTimeline>;
+}
+//#endregion
+//#region src/index.d.ts
+/**
+ * 同包分支 provider（rewind / forkFrom）访问 `SessionPersistenceRdb` 内部
+ * 能力的窄接口。避免把 backend / writeGuard 暴露成公开 API，同时让
+ * {@link SessionBranchRdbProvider} 与持久化后端共享同一连接与写路径。
+ * @internal
+ */
+interface SessionPersistenceRdbInternals {
+  readonly backend: Backend;
+  readonly writeGuard: WriteGuard;
+  create(meta: SessionHeader): Promise<void>;
+  append(id: SessionId, events: readonly SessionEvent[]): Promise<void>;
+  load(id: SessionId): Promise<import("@deepseek-ai/dsh-session-persistence").SessionInspection>;
+  inspect(id: SessionId, signal?: AbortSignal): Promise<import("@deepseek-ai/dsh-session-persistence").SessionInspection>;
+  readFrom(id: SessionId, fromSeq: number, signal?: AbortSignal): Promise<{
+    meta: SessionHeader;
+    events: SessionEvent[];
+  }>;
+  listSnapshots(signal?: AbortSignal): Promise<SessionPersistenceSnapshot[]>;
+  readStoredRevision(id: SessionId, signal?: AbortSignal): Promise<import("@deepseek-ai/dsh-session-persistence").SessionPersistenceRevision | undefined>;
+}
+/**
+ * Plugin configuration — a discriminated union on `type`. The SQLite arm keeps
+ * the file path plus the SQLite-specific pragmas; the PostgreSQL arm takes a
+ * `node-postgres` connection string.
+ */
+type Config = {
+  type: "sqlite";
+  /**
+   * Filesystem path to the SQLite database file. The special value `:memory:`
+   * opens an in-process database (tests). On filesystems with POSIX modes,
+   * missing directories and databases are created owner-only; existing path
+   * modes are preserved.
+   */
+  path: string;
+  /**
+   * SQLite `journal_mode` pragma. `wal` (the default) is the recorded
+   * durability model; pick a rollback-journal mode (`delete`/`truncate`/
+   * `persist`) on filesystems where WAL's shared-memory files do not work
+   * (network mounts). See {@link JournalMode}.
+   */
+  journalMode?: JournalMode;
+  /**
+   * Milliseconds to wait for a contended write lock before failing. SQLite
+   * fails immediately by default, so a second process sharing this database
+   * would lose every append that meets an in-flight commit; a nonzero wait
+   * turns the contention window into a queue. `0` restores fail-fast.
+   */
+  busyTimeout?: number;
+} | {
+  type: "postgres";
+  /**
+   * `node-postgres` connection string (e.g.
+   * `postgres://user:pass@host:5432/db`). The database must be reachable;
+   * the backend creates its tables and identity on first open.
+   */
+  connectionString: string;
+};
+/**
+ * The persistence backend. Load as a plugin; it registers as
+ * `ctx.sessionPersistence` and (via the coordinator) installs the write-path
+ * listeners. Its torn-tail marker is the persisted seq to delete from.
+ *
+ * Configuration resolution: `$DSH_HOME/settings.yaml` 的
+ * `session-rdb` namespace（settings 服务）覆盖 cordis 层 entry
+ * config，见 {@link installSettingsSection}。
+ */
+declare class SessionPersistenceRdb extends SessionPersistence implements PersistenceBackend<number> {
+  config: Config;
+  static inject: string[];
+  static Config: z<Config>;
+  /** settings namespace：`$DSH_HOME/settings.yaml` 的 `session-rdb` section。 */
+  static readonly settingsNs: import("@deepseek-ai/dsh-settings").SettingsNamespace;
+  /**
+   * Backend label for the coordinator's dispose diagnostics. Intentionally
+   * shadows cordis `Service.name` (set to `'sessionPersistence'` by the base);
+   * see the JSONL backend for why this does not affect service resolution.
+   */
+  readonly name = "session-rdb";
+  /** One RDB database holds every session; there is no per-session raw artifact. */
+  readonly supportsRawArtifacts = false;
+  private readonly backend;
+  private storeIdentity;
+  private readonly ready;
+  private readonly coordinator;
+  /**
+   * Write-authority state: the confirmed dense head per session (concurrent-
+   * writer detection) and the dropped delta seqs per session (provenance
+   * pruning). See {@link WriteGuard} for the timing contract.
+   */
+  private readonly writeGuard;
+  constructor(ctx: Context, config: Config,
+  /**
+   * @internal Test injection: use a pre-built backend (e.g. a drizzle PG
+   * instance over an in-memory pglite) instead of {@link createBackend}.
+   */
+  injectedBackend?: Backend);
+  private init;
+  /** The backend has one database, not an independent local artifact per session. */
+  locate(_meta: SessionHeader): SessionLocation | undefined;
+  create(meta: SessionHeader): Promise<void>;
+  append(id: SessionId, events: readonly SessionEvent[]): Promise<void>;
+  load(id: SessionId): Promise<{
+    meta: SessionHeader;
+    events: readonly SessionEvent[];
+  }>;
+  inspect(id: SessionId, signal?: AbortSignal): Promise<{
+    meta: SessionHeader;
+    events: readonly SessionEvent[];
+  }>;
+  readFrom(id: SessionId, fromSeq: number, signal?: AbortSignal): Promise<{
+    meta: SessionHeader;
+    events: SessionEvent[];
+  }>;
+  /** Read a stored prefix by id (ids are globally unique — no scope to scan). */
+  loadStored(id: SessionId, signal?: AbortSignal): Promise<StoredPrefix<number> | undefined>;
+  /**
+   * Seek-capable suffix read: the backend selects `f_sequence >= fromSeq`
+   * directly, so the read scales with the suffix, not the log. Provenance
+   * remapping still needs every row's upstream seq, so a lightweight
+   * two-column map is read alongside. Torn rows past the preserved region are
+   * dropped, never repaired (non-mutating read).
+   */
+  loadStoredFrom(id: SessionId, fromSeq: number, signal?: AbortSignal): Promise<StoredSuffix | undefined>;
+  /**
+   * Read a session's row + ordered events into a {@link StoredPrefix}. The
+   * torn-tail marker is the persisted seq from which a never-committed tail
+   * must be deleted (`scanRows` already returns it as `number | undefined`).
+   * Records the confirmed dense head (or confirmed absence) so a later
+   * `appendBatch` can detect a second writer that advanced the log.
+   */
+  private readPrefix;
+  /**
+   * Read the current source-qualified revision for one stored session without
+   * loading its event log. Returns `undefined` when the identity is absent.
+   * The representation matches {@link loadStored}'s `revision` and
+   * {@link listSnapshots} — the coordinator compares them with `===`.
+   */
+  readStoredRevision(id: SessionId, signal?: AbortSignal): Promise<SessionPersistenceRevision | undefined>;
+  /**
+   * Shared read pipeline: session row → meta, event rows → preserved prefix.
+   * A whole-log read (`fromSeq` absent) builds the seq map from the same rows;
+   * a suffix read keeps the backend's lightweight two-column seq-map source so
+   * the query still scales with the suffix, not the log.
+   */
+  private readLog;
+  /**
+   * Durably append a batch in ONE transaction: materialize the sessions row (if
+   * lazy) and INSERT every persisted event (plus its bridge row), or roll back
+   * entirely. Delta events and events the writer marked `ignorable` are dropped
+   * and the surviving events are re-numbered densely from the session's head
+   * cursor; a batch that contains only dropped events is a no-op (no row
+   * materialization, no revision bump). Dropped events' upstream seqs are
+   * recorded per session so a later batch's surface provenance can prune
+   * references to them (see {@link surfaceBindings}).
+   * The transaction is the atomicity + durability boundary, so a mid-batch
+   * failure (a UNIQUE violation on a duplicated seq) leaves the stored log
+   * untouched.
+   *
+   * SQLite acquires the write lock up front (`BEGIN IMMEDIATE`, queued behind
+   * `busy_timeout`); PostgreSQL relies on the transaction's row locks and the
+   * `UNIQUE (f_session_id, f_sequence)` constraint to reject a colliding batch.
+   * Either way {@link assertNoConcurrentWriter} rejects a second writer before
+   * re-numbering — a session has exactly one writer per log, and a second
+   * writer fails loud instead of corrupting the log.
+   *
+   * The row upsert runs UNCONDITIONALLY, not only when `!isMaterialized`: a
+   * delta-only batch leaves the coordinator's materialized flag true while no
+   * row exists, so the flag cannot be trusted as the row's existence signal.
+   * The upsert keeps an existing row's head cursor (only header columns are
+   * refreshed on conflict), so a fresh row still starts at the initial head.
+   */
+  appendBatch(meta: SessionHeader, events: readonly SessionEvent[], _isMaterialized: boolean): Promise<void>;
+  /**
+   * Make a crash repair durable in ONE transaction: DELETE the torn tail (from
+   * `tornMarker`), rewind the head cursor to the last surviving event, INSERT
+   * the synthetic `closers`, and bump the revision once. After COMMIT the
+   * stored rows == the balanced log.
+   */
+  commitRepair(meta: SessionHeader, tornMarker: number | undefined, closers: readonly SessionEvent[]): Promise<void>;
+  /**
+   * 一次性清洗一个 session 的 surface/provenance 坐标到稠密空间并写回。
+   *
+   * 旧数据（rewind 前的代码写入）的 `sourceEventSeqs`、`surfaceOp` replace
+   * range 与 compaction `shadowedRange` 是上游坐标，读取时每次都要做坐标
+   * 解析对齐；清洗用与读取完全相同的解析（稠密优先 + 上游映射 + 剪枝 +
+   * replace provenance 补全）把它们重写为稠密坐标，之后读取无需再对齐
+   * （对已清洗数据解析恒为恒等）。torn tail 片段不参与（读取路径也不会
+   * 保留它们）。返回实际变更的事件数。
+   */
+  cleanseSession(id: SessionId, signal?: AbortSignal): Promise<{
+    changed: number;
+  }>;
+  /** List all materialized sessions' metadata (every row is a materialized session). */
+  list(signal?: AbortSignal): Promise<SessionHeader[]>;
+  /** List metadata with a source-qualified monotonic revision per session. */
+  listSnapshots(signal?: AbortSignal): Promise<SessionPersistenceSnapshot[]>;
+  /** Close the database connection (awaited by the coordinator's dispose, post-drain). */
+  close(): Promise<void>;
+  /**
+   * 同包分支 provider 的内部访问面（rewind / forkFrom 共享后端与写路径）。
+   * @internal 仅供 `SessionBranchRdbProvider` 使用；不是公开 API。
+   */
+  internals(): SessionPersistenceRdbInternals;
+}
+//#endregion
+export { Config, EPHEMERAL_EVENT_TYPES, SCHEMA_VERSION, SessionBranchRdb, SessionBranchRdbProvider, SessionPersistenceRdb, SessionPersistenceRdb as default, SessionPersistenceRdbInternals, locateTurnEnd };
+//# sourceMappingURL=index.d.mts.map

package/lib/index.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.mts","names":[],"sources":["../src/backend.ts","../src/write-guard.ts","../src/schema.ts","../src/branch.ts","../src/index.ts"],"mappings":"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"}