@morlay/session-rdb 0.0.11 → 0.0.13

package/src/testing/helpers.ts

@@ -0,0 +1,20 @@
+import { Context } from "@deepseek-ai/cordis";
+import { SettingsProvider, type SettingsNamespace } from "@deepseek-ai/dsh-settings";
+
+export class EmptySettings extends SettingsProvider {
+  constructor(ctx: Context) {
+    super(ctx);
+  }
+
+  get writable(): boolean {
+    return true;
+  }
+
+  protected async load(): Promise<Record<string, unknown>> {
+    return {};
+  }
+
+  protected persist(_ns: SettingsNamespace, _section: Record<string, unknown>): Promise<void> {
+    return Promise.resolve();
+  }
+}

package/src/testing.ts

@@ -0,0 +1,12 @@
+// 测试支撑（跨包测试共享）：helpers / contract / coordinator-contract。
+// 仅供 vitest 测试引用；不进入运行时 bundle。
+export { EmptySettings } from "./testing/helpers.ts";
+export type { ContractBackend } from "./testing/contract.ts";
+export {
+  appendLog,
+  meta,
+  oneTurnLog,
+  runPersistenceContract,
+} from "./testing/contract.ts";
+export type { CoordinatorFixture } from "./testing/coordinator-contract.ts";
+export { runCoordinatorContract } from "./testing/coordinator-contract.ts";

package/src/write-guard.ts

@@ -0,0 +1,27 @@
+import type { SessionId } from "@deepseek-ai/dsh-session";
+
+export class WriteGuard {
+  private readonly headSeqs = new Map<SessionId, number>();
+
+  confirmHead(id: SessionId, head: number): void {
+    this.headSeqs.set(id, head);
+  }
+
+  assertNoConcurrentWriter(id: SessionId, storedHead: number): void {
+    const known = this.headSeqs.get(id);
+    if (known === undefined) {
+      if (storedHead !== -1) {
+        throw new Error(
+          `session "${id}" has a persisted log this instance has not read; another writer may own it — load the session first`,
+        );
+      }
+      return;
+    }
+    if (known !== storedHead) {
+      throw new Error(
+        `session "${id}" was modified by another writer (stored head ${storedHead}, this instance last confirmed head ${known}); ` +
+          "concurrent writers on one session are not supported",
+      );
+    }
+  }
+}

package/lib/index.d.mts

@@ -1,558 +0,0 @@
-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;
-  /**
-   * 截断后同步 coordinator 的 ownerless 状态（cold 分支）：把 `states` 条目
-   * 的 `cursor` 对齐到新尾部。与 {@link setCoordinatorCursor} 的区别是
-   * **不要求条目已存在**——cold 会话可能从未被 adopt（无 states 条目），
-   * 此时创建 ownerless 条目（meta 来自截断后快照），使下一次 append 走
-   * 标准路径而非 `adopt`（adopt 会经 `prepareCore` 补 closers 撤销截断）。
-   */
-  setCoordinatorState(id: SessionId, cursor: number, meta: SessionHeader): 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>;
-  /**
-   * 读取会话的**原始**事件（不含 coordinator 补记的合成 closers）。
-   *
-   * `persistence.inspect` 走 coordinator 的 `prepareCore`，会给未闭合 log
-   * 补 `interruptedTurnClosers`（合成 step/end + turn/end）——对普通读取
-   * （客户端历史）这是正确的逻辑视图，但对分支编排是误导：未闭合轮次被
-   * closers 掩盖成闭合，编辑未闭合轮次的 user 消息会走错边界。这里用
-   * `loadStored`（backend hook，scanRows 只做 torn-tail 切割、不补 closers）
-   * 读原始事件，使未闭合状态真实可见。
-   */
-  readRawEvents(id: SessionId, signal?: AbortSignal): Promise<{
-    meta: SessionHeader;
-    events: readonly SessionEvent[];
-  }>;
-  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>;
-  /**
-   * 读取会话的**原始**事件（不含 coordinator 补记的合成 closers）。
-   * 编排层用它识别未闭合轮次（inspect 会把未闭合 log 补成闭合）。
-   */
-  readRawEvents(id: SessionId, signal?: AbortSignal): Promise<{
-    meta: SessionHeader;
-    events: readonly SessionEvent[];
-  }>;
-  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

@@ -1 +0,0 @@
-{"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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"}