@x-otto/persistence 0.0.1-alpha.0

package/dist/index.d.ts

@@ -0,0 +1,984 @@
+import Database from "better-sqlite3";
+
+//#region src/atomic-write.d.ts
+/**
+ * 崩溃安全的全量文件写入（RFC-088 D4）。
+ *
+ * 语义：write-temp → fsync(fd) → close → rename → fsync(dir, best-effort)。
+ * rename 在同一文件系统内原子——读者要么看到旧内容、要么看到新内容，绝不看到半写。
+ * fsync(fd) 保证 temp 内容在 rename 前已落盘（否则崩溃/断电后 rename 生效但数据丢失）；
+ * fsync(dir) 保证 rename 这一目录项变更本身落盘（best-effort——部分平台目录 fsync 不支持，忽略其错误）。
+ *
+ * 用于**全量覆写**路径（snapshot 保存、append-log 的 repair/truncate 重写），非追加热路径
+ * （追加路径用 O_DSYNC 打开，见 FileAppendLog）。
+ */
+declare function atomicWriteFile(filePath: string, data: string | Uint8Array): Promise<void>;
+//#endregion
+//#region src/types.d.ts
+interface Snapshot<T = unknown> {
+  version: number;
+  id: string;
+  data: T;
+  metadata: Metadata;
+}
+interface Metadata {
+  createdAt: number;
+  updatedAt: number;
+  tags: string[];
+  owner?: string;
+  updatedBy?: string;
+  visibility?: 'private' | 'shared';
+  [key: string]: unknown;
+}
+interface Codec<T = unknown> {
+  encode(snapshot: T): string;
+  decode(payload: string): T;
+  contentType?: string;
+}
+/**
+ * RFC-067 M114-01(A6)：持久化的**共享方法契约**单一真相源。snapshot 信封类型 `S` 与分页选项 `P`
+ * 由各域固化——`Persistence`（generic `Snapshot<T>` + 通用分页）与 @x-otto/session 的
+ * `SessionPersistence`（域信封 `SessionSnapshot<T>` + 域分页 `sortBy=lastActiveAt`）各自 `extends`
+ * 之，消除两份等同的五方法声明。
+ *
+ * **§7.3 现实修正**：RFC A6「单一 `Persistence<T>`、删 SessionPersistence 重复」过断——二者的
+ * S/P 域类型真异（envelope: entries[]/leafId/SessionMetadata vs data/Metadata；pagination
+ * sortBy: lastActiveAt|createdAt vs createdAt|updatedAt），强行塌成单一接口会**擦除 session 域
+ * 类型**。故只抽共享方法形，保留两域接口。`PaginatedResult` 早已单源（session 从本包导入）。
+ * （历史 `as unknown as SessionPersistence` cast 来自 SessionPersistenceAdapter 的 sortBy 枚举
+ * 桥，已随 M115-01 删除 @x-otto/persistence-client 整包一并消除。）
+ */
+interface PersistenceShape<S, P = PaginationOptions> {
+  save(snapshot: S): Promise<void>;
+  load(id: string): Promise<S | null>;
+  delete(id: string): Promise<boolean>;
+  list(): Promise<string[]>;
+  listPaginated(options: P): Promise<PaginatedResult<string>>;
+}
+/**
+ * RFC-108 D2：无分页的实体持久化契约——PanelState 等单资源按 id 存取的场景，
+ * 从不翻页/列表查询，不该继承 PersistenceShape 的 list/listPaginated。
+ */
+interface EntityPersistenceShape<S> {
+  save(snapshot: S): Promise<void>;
+  load(id: string): Promise<S | null>;
+  delete(id: string): Promise<boolean>;
+}
+interface Persistence<T = unknown> extends PersistenceShape<Snapshot<T>> {}
+interface PaginationOptions {
+  /** 0-based（第一页 = 0）。全部 Persistence 实现、SessionStore、StorageHost 统一此语义（F12）。 */
+  page: number;
+  pageSize?: number;
+  sortBy?: 'createdAt' | 'updatedAt';
+  order?: 'asc' | 'desc';
+}
+interface PaginatedResult<T> {
+  items: T[];
+  total: number;
+  page: number;
+  pageSize: number;
+  totalPages: number;
+  hasNext: boolean;
+  hasPrevious: boolean;
+}
+interface FileStorageOptions<T = unknown> {
+  type: 'file';
+  baseDir: string;
+  extension?: string;
+  codec?: Codec<Snapshot<T>>;
+}
+interface MemoryStorageOptions {
+  type: 'memory';
+}
+/** sqlite 后端选项（镜像 SqlitePersistenceOptions + type 判别字段，避免与 sqlite-persistence 循环依赖）。 */
+interface SqliteStorageOptions<T = unknown> {
+  type: 'sqlite';
+  dbPath: string;
+  wal?: boolean;
+  namespace: string;
+  defaultPageSize?: number;
+  codec?: Codec<Snapshot<T>>;
+}
+type StorageOptions<T = unknown> = FileStorageOptions<T> | MemoryStorageOptions | SqliteStorageOptions<T>;
+//#endregion
+//#region src/memory-persistence.d.ts
+interface MemoryPersistenceBaseOptions {
+  defaultPageSize?: number;
+  defaultSortBy?: string;
+}
+/**
+ * 抽象内存后端，与 `DiskPersistence<S>` / `RemotePersistence<S>` 对称（都是 `extractId` +
+ * 通用 `listPaginated`）。领域包用"薄子类 + extractId/getSortValue 配置"复用，无需各写一套
+ * Map+分页。原设计稿 docs/design/storage-kernel.md 已随 RFC-067 M123-03 文档收敛删除，
+ * 内容并入 packages/persistence/ARCHITECTURE.md，见 commit 5d6a9f5b。
+ */
+declare abstract class MemoryPersistenceBase<S> {
+  private readonly store;
+  protected readonly defaultPageSize: number;
+  protected readonly defaultSortBy: string;
+  constructor(options?: MemoryPersistenceBaseOptions);
+  protected abstract extractId(record: S): string;
+  /** 默认读 `record.metadata[sortBy]`；时间字段命名不同的领域可覆盖。 */
+  protected getSortValue(record: S, sortBy: string): number;
+  save(record: S): Promise<void>;
+  load(id: string): Promise<S | null>;
+  delete(id: string): Promise<boolean>;
+  list(): Promise<string[]>;
+  /**
+   * 受保护的只读快照迭代器——供领域子类（如 session 域的 `InMemorySessionPersistence`）
+   *实现自己的排序/过滤查询（如 RFC-154 D1 的 `listRecentMeta`），不在通用层硬编码领域
+   * 专属语义（如 archived 过滤）。返回浅拷贝数组，调用方不应修改 store 内容。
+   */
+  protected entries(): ReadonlyArray<readonly [string, S]>;
+  listPaginated(options: {
+    page: number;
+    pageSize?: number;
+    sortBy?: string;
+    order?: 'asc' | 'desc';
+  }): Promise<PaginatedResult<string>>;
+}
+declare class MemoryPersistence<T = unknown> extends MemoryPersistenceBase<Snapshot<T>> implements Persistence<T> {
+  protected extractId(snapshot: Snapshot<T>): string;
+}
+//#endregion
+//#region src/save-document.d.ts
+/**
+ * 信封构造单一来源（engine-nodes 范式外推）。
+ *
+ * 内核拥有信封构造：消费者只交 document + 少量选项，内核统一产出
+ * `{version, id, data, metadata{createdAt, updatedAt, tags}}` 信封 + 时间戳策略。
+ *
+ * upsert 默认保留原 createdAt（先 load 再写）；append-only 场景传 `preserveCreatedAt: false` 跳过读。
+ * 时间戳由调用方注入（`now`），内核不直调 Date.now（确定性/可注入时钟）。
+ */
+declare function saveDocument<T>(persistence: Persistence<T>, id: string, data: T, options: {
+  now: number;
+  version?: number;
+  tags?: string[];
+  preserveCreatedAt?: boolean;
+  owner?: string;
+  updatedBy?: string;
+}): Promise<void>;
+//#endregion
+//#region src/disk-persistence.d.ts
+interface DiskPersistenceOptions<S = unknown> {
+  baseDir: string;
+  extension?: string;
+  defaultPageSize?: number;
+  codec?: Codec<S>;
+}
+declare abstract class DiskPersistence<S> {
+  protected readonly baseDir: string;
+  protected readonly extension: string;
+  protected readonly defaultPageSize: number;
+  protected readonly codec: Codec<S>;
+  private initialized;
+  constructor(options: DiskPersistenceOptions<S>);
+  protected abstract extractId(snapshot: S): string;
+  save(snapshot: S): Promise<void>;
+  load(id: string): Promise<S | null>;
+  delete(id: string): Promise<boolean>;
+  list(): Promise<string[]>;
+  listPaginated(options: {
+    page: number;
+    pageSize?: number;
+    sortBy?: string;
+    order?: 'asc' | 'desc';
+  }): Promise<PaginatedResult<string>>;
+  private resolvePath;
+  private ensureDir;
+}
+//#endregion
+//#region src/panel-state.d.ts
+/** 持久化任务面板条目（内联自 @x-otto/session PersistedSessionConfig.todoList）。 */
+interface PanelStateTodoItem {
+  id?: string;
+  title?: string;
+  status?: 'pending' | 'in_progress' | 'done' | 'skipped' | 'failed';
+  turn?: number;
+}
+/** 持久化编辑文件条目（内联自 @x-otto/session PersistedSessionConfig.editedFiles）。 */
+interface PanelStateEditedFile {
+  path: string;
+  operation: 'edit' | 'write' | 'delete';
+  addedLines: number;
+  removedLines: number;
+  timestamp: number;
+  turnId?: string;
+  toolCallId?: string;
+}
+/** 持久化子代理条目（内联自 @x-otto/session SubagentEntry）。 */
+interface PanelStateSubagentEntry {
+  id: string;
+  name: string;
+  status: 'running' | 'done' | 'error' | 'killed';
+  startedAt: number;
+  turnId?: string;
+}
+/** 持久化草稿条目（内联自 @x-otto/session DraftEntry）。 */
+interface PanelStateDraftEntry {
+  id: string;
+  name: string;
+  text: string;
+  savedAt: number;
+}
+/**
+ * 持久化回合完成摘要条目（内联自 @x-otto/session TurnSummaryEntry）。
+ *
+ * 用户反馈：TUI 底部"✓ 完成 · N 个工具 · 耗时 · tokens · 模型"这行摘要此前只是
+ * `reduceToTui` 在 `prompt.end` 时从瞬时状态（ReducerState 计数器 + 当次事件字段）现算
+ * 现造的 `ChatMessage`（`role:'summary'`），从未写入 `session.messages()`（发给模型的
+ * 真实历史）也从未写入任何持久化存储——resume 时 `agentMessagesToChatMessages` 只回放
+ * user/assistant/tool_result，摘要行永久丢失。
+ *
+ * 本字段独立于 `todoList`/`editedFiles`——它是**每回合累加**（不像 editedFiles 那样
+ * `prompt.start` 清空只留当前回合），因为 resume 后需要在对话流里逐回合重现历史摘要行，
+ * 不是只留最后一条。与 messages()/AgentMessage[] 物理隔离存储，天然不会被
+ * provider 序列化层读取——满足"持久化但不发给大模型"的约束。
+ */
+interface PanelStateTurnSummary {
+  turn: number;
+  status: 'done' | 'error' | 'interrupted' | 'incomplete';
+  toolCount: number;
+  elapsedMs: number;
+  tokensUsed?: number;
+  cacheHitRatio?: number;
+  model?: string;
+  tasksDone?: number;
+  tasksTotal?: number;
+  completedAt: number;
+}
+/**
+ * RFC-108 D2：PanelState 持久化信封。
+ *
+ * `sessionId` 既是业务关联键也是持久化主键——PanelState 始终按 sessionId 一对一存取，
+ * 从不翻页/列表查询，故契约用 `EntityPersistenceShape` 而非 `PersistenceShape`。
+ */
+interface PanelStateSnapshot {
+  sessionId: string;
+  todoList?: PanelStateTodoItem[];
+  editedFiles?: PanelStateEditedFile[];
+  subagents?: PanelStateSubagentEntry[];
+  drafts?: PanelStateDraftEntry[];
+  turnSummaries?: PanelStateTurnSummary[];
+}
+/** RFC-108 D2：PanelState 持久化契约（无分页三方法）。 */
+interface PanelStatePersistence extends EntityPersistenceShape<PanelStateSnapshot> {}
+/**
+ * RFC-108 D2：PanelState 本地磁盘持久化实现。
+ *
+ * 对外仅暴露 `PanelStatePersistence` 三方法（save/load/delete），内部委托
+ * `DiskPersistence<PanelStateSnapshot>` 负责实际的磁盘 I/O。
+ *
+ * 参照 `RemoteSessionPersistence extends RemotePersistence<SessionSnapshot<T>>`
+ * 的“领域固化 PersistenceShape”模式——但此处是本地磁盘后端，用委托而非继承，因为
+ * `DiskPersistence` 承载了 `list`/`listPaginated` 等 PanelState 不需要的语义，
+ * 直接继承会泄漏与 `EntityPersistenceShape` 契约不匹配的方法。
+ */
+declare class DiskPanelStatePersistence implements PanelStatePersistence {
+  private readonly store;
+  constructor(options: {
+    baseDir: string;
+  });
+  save(snapshot: PanelStateSnapshot): Promise<void>;
+  load(id: string): Promise<PanelStateSnapshot | null>;
+  delete(id: string): Promise<boolean>;
+}
+/**
+ * RFC-345：PanelState 内存后端（影子模式）。面板态只活在进程内存，退出即释放。
+ */
+declare function createInMemoryPanelStatePersistence(): PanelStatePersistence;
+//#endregion
+//#region src/paste-state.d.ts
+/**
+ * 持久化粘贴条目（RFC-338）。
+ *
+ * **不含时间戳/序号字段**：LRU 顺序由 {@link PasteStateSnapshot.entries} 的
+ * **数组顺序**表达（头 = 最久未访问，尾 = 最近访问），与内存侧 `Map` 的插入顺序
+ * 语义一一对应（RFC-338 D2）。引入独立 `accessSeq` 会与 Map 顺序构成双真源；
+ * 引入 `Date.now()` 则违反引擎核心的确定性重放约束。
+ */
+interface PasteStateEntry {
+  /** 占位符 `[@paste:#N]` 中的 N。 */
+  id: number;
+  /** 折叠前的原文。 */
+  text: string;
+  /** utf-8 字节数（容量闸的另一维度，构造时算好避免重复计算）。 */
+  byteLength: number;
+}
+/**
+ * RFC-338：paste 缓存独立信封。
+ *
+ * `sessionId` 既是业务关联键也是持久化主键——按 sessionId 一对一存取，
+ * 从不翻页/列表查询，故契约用 `EntityPersistenceShape`（同 PanelState 的判断）。
+ */
+interface PasteStateSnapshot {
+  sessionId: string;
+  /** 有序数组 = LRU 顺序（头 = 最久未访问）。 */
+  entries: PasteStateEntry[];
+  /**
+   * id 分配游标，**单调不回退**（RFC-338 重要事项规则 1，红线）。
+   *
+   * 违反后果不是「chip 失效」而是「chip 静默展开成另一份内容并发给模型」——
+   * 内存态重启后 store 为空、旧 chip 判失效是**安全的失败**；持久化态下若
+   * 该游标回退，新粘贴会复用旧 id，历史里的 `[@paste:#7]` 就会指向错误内容。
+   */
+  nextId: number;
+}
+/** RFC-338：paste 缓存持久化契约（无分页三方法，同 PanelStatePersistence）。 */
+interface PasteStatePersistence extends EntityPersistenceShape<PasteStateSnapshot> {}
+/**
+ * RFC-338：paste 缓存本地磁盘持久化实现。
+ *
+ * **落盘位置是 `panel-state/` 下的独立子目录 `paste/`**，不是与面板态同级的
+ * `<sessionId>.paste.json`。原因（实现期实测）：`DiskPersistence` 的
+ * `list()`/`listPaginated()` 用 `endsWith(extension)` 过滤、用
+ * `slice(0, -extension.length)` 反解 id —— 若 paste 用 `.paste.json` 后缀与面板态
+ * 同目录并存，面板态那侧以 `.json` 过滤会**连带匹配到 paste 文件**，且把 id
+ * 反解成 `<sessionId>.paste`（实测 `'s1.paste.json'.endsWith('.json') === true`）。
+ * 独立子目录让两者的文件名空间物理隔离，两侧都用标准 `.json` 后缀，无需依赖
+ * 「当前恰好没人调用 list()」这种脆弱前提。
+ */
+declare class DiskPasteStatePersistence implements PasteStatePersistence {
+  private readonly store;
+  constructor(options: {
+    baseDir: string;
+  });
+  save(snapshot: PasteStateSnapshot): Promise<void>;
+  load(id: string): Promise<PasteStateSnapshot | null>;
+  delete(id: string): Promise<boolean>;
+}
+/**
+ * RFC-338 重要事项规则 1（红线）：从**不可信**的持久化快照推导安全的 `nextId`。
+ *
+ * 取 `max(1, 快照声明的 nextId, 全部 entry.id + 1)` —— 三者取最大保证游标既不
+ * 回退、也不与任何既存 id 碰撞。
+ *
+ * **边界（二轮评审 F4，已实测）**：`Math.max(...[])` 返回 `-Infinity`，故绝不能
+ * 写成 `Math.max(...ids) + 1` 的裸形式 —— entries 为空时会得到 `-Infinity`，
+ * 后续 `nextId++` 全程为 `-Infinity`，占位符变成 `[@paste:#-Infinity]`。
+ * 起始种子 `1` 同时兜住了空数组与 `nextId` 缺失两种情况。
+ *
+ * @param snapshot 可能损坏/缺字段/被手工编辑过的快照
+ */
+declare function resolvePasteNextId(snapshot: unknown): number;
+/**
+ * RFC-338 §7：把不可信快照规范化为可用状态（fail-open）。
+ *
+ * 丢弃非法 entry（缺字段/类型错/id 非有限数）而非整份拒绝——用户不该因为一条
+ * 坏记录丢掉整个会话的粘贴缓存。`byteLength` 一律按 `text` 重算，不信任存储值
+ * （手工编辑或旧版本写入的值可能与实际不符，直接影响容量闸判断）。
+ *
+ * 无论 entries 如何裁剪，`nextId` 都基于**原始**快照推导——防止「坏 entry 被丢弃
+ * → id 空间看似空出 → 新粘贴复用该 id → 历史 chip 错展开」的绕行路径。
+ */
+declare function normalizePasteSnapshot(sessionId: string, raw: unknown): PasteStateSnapshot;
+/**
+ * RFC-345：paste 缓存内存后端（影子模式）。粘贴态只活在进程内存，退出即释放。
+ */
+declare function createInMemoryPasteStatePersistence(): PasteStatePersistence;
+//#endregion
+//#region src/remote-persistence.d.ts
+interface RemotePersistenceOptions<S = unknown> {
+  baseUrl: string;
+  /**
+   * workspace 分区键(default='default');客户端 URL 拼接 wsKey。
+   * 支持惰性 getter（`() => string | undefined`）——修复（N3，resume/workspace 关联审计）：
+   * 消费方（如 App）在构造期就创建持久化实例，而 workspaceRef.key 要到 App.start() 异步
+   * resolveLocal 完成后才有真实值，与 RelationalSessionPersistence.workspaceKey 的既有
+   * 惰性 getter 模式同源同因（同一类时序错位，见 Bug1 修复记录）。静态字符串仍受支持
+   * （组件测试 / 无 workspace 概念场景）。
+   */
+  wsKey?: string | (() => string | undefined);
+  getAuth: () => Promise<{
+    token: string;
+  }>;
+  getHeaders?: () => Promise<Record<string, string>>;
+  fetch: typeof globalThis.fetch;
+  timeoutMs: number;
+  defaultPageSize?: number;
+  defaultSortBy?: string;
+  codec?: Codec<S>;
+}
+declare abstract class RemotePersistence<S> {
+  protected readonly baseUrl: string;
+  /** workspace 分区键解析器,URL 路径前缀;缺省 'default'。每次用时惰性求值。 */
+  private readonly resolveWsKey;
+  protected get wsKey(): string;
+  protected readonly getAuth: () => Promise<{
+    token: string;
+  }>;
+  protected readonly getHeaders: () => Promise<Record<string, string>>;
+  protected readonly fetch: typeof globalThis.fetch;
+  protected readonly timeoutMs: number;
+  protected readonly defaultPageSize: number;
+  protected readonly defaultSortBy: string;
+  protected readonly codec: Codec<S>;
+  /**
+   * 错误文案用的服务标签；通用基类默认中性名，领域子类覆盖（如 RemoteSessionPersistence → "会话服务"）。
+   * 修正：基类原硬编码"会话服务器"，但它同时被通用 HttpPersistence 继承 → 非会话用途报错误导。
+   */
+  protected get serviceLabel(): string;
+  /** 错误文案用的端点配置项名；领域子类覆盖（如 '--session-url'）。 */
+  protected get endpointFlag(): string;
+  constructor(options: RemotePersistenceOptions<S>);
+  /** wsKey 路径拼接:`/{wsKey}/{path}`。 */
+  private wsPath;
+  /** wsKey 路径 list: `/{wsKey}`。 */
+  protected wsListPath(): string;
+  protected abstract extractId(snapshot: S): string;
+  /**
+   * 无条件整份 PUT（兼容旧调用方）。新调用方应改用 `saveWithRevision()` 以获得 CAS 保护。
+   */
+  save(snapshot: S): Promise<void>;
+  /**
+   * CAS 写入：带 `If-Match: "<expectedRevision>"` 发起 PUT。
+   * - 成功：返回服务端分配的新 revision。
+   * - 冲突（409）：抛 `RemoteSnapshotConflictError`，`info.revision` 为服务端当前 revision。
+   * - 未提供 expectedRevision：等价于无条件写，服务端不比对；返回新 revision。
+   *
+   * `expectedRevision=0` 显式表示"期望文档尚不存在"（新建场景）。
+   */
+  saveWithRevision(snapshot: S, expectedRevision?: number): Promise<number>;
+  /**
+   * 读取快照与其 revision。revision 供下次 `saveWithRevision()` 的 `expectedRevision` 使用。
+   * 文档不存在返回 null（revision 也为 null）。
+   */
+  loadWithRevision(id: string): Promise<{
+    snapshot: S;
+    revision: number;
+  } | null>;
+  load(id: string): Promise<S | null>;
+  delete(id: string): Promise<boolean>;
+  list(): Promise<string[]>;
+  listPaginated(options: {
+    page: number;
+    pageSize?: number;
+    sortBy?: string;
+    order?: 'asc' | 'desc';
+  }): Promise<PaginatedResult<string>>;
+  protected request(path: string, init: {
+    method: string;
+    body?: string;
+  }, extraHeaders?: Record<string, string>): Promise<Response>;
+}
+//#endregion
+//#region src/file-persistence.d.ts
+interface FilePersistenceOptions<T = unknown> {
+  baseDir: string;
+  extension?: string;
+  codec?: Codec<Snapshot<T>>;
+}
+declare class FilePersistence<T = unknown> extends DiskPersistence<Snapshot<T>> implements Persistence<T> {
+  constructor(options: FilePersistenceOptions<T>);
+  protected extractId(snapshot: Snapshot<T>): string;
+}
+//#endregion
+//#region src/errors.d.ts
+declare class PersistenceError extends Error {
+  constructor(message: string, options?: {
+    cause?: unknown;
+  });
+}
+declare class RemotePersistenceError extends PersistenceError {
+  readonly statusCode: number;
+  constructor(message: string, statusCode: number, options?: {
+    cause?: unknown;
+  });
+}
+/** 409 conflict response 的可选 payload（If-Match CAS 冲突时，authority 返回当前 revision）。 */
+interface SnapshotConflictInfo {
+  /** 服务端当前 revision；可能为 null（极少数并发删除后不存在）。 */
+  revision: number | null;
+}
+/** 远端快照写入冲突（CAS 失败）——base class 上特化，调用方可显式识别并做 reload/rebase。 */
+declare class RemoteSnapshotConflictError extends RemotePersistenceError {
+  readonly info: SnapshotConflictInfo;
+  constructor(message: string, info: SnapshotConflictInfo, options?: {
+    cause?: unknown;
+  });
+}
+//#endregion
+//#region src/storage-factory.d.ts
+/**
+ * 统一存储工厂：按 `options.type` 直构造内置后端（memory/file/http/sqlite）。
+ *
+ * M91-02（RFC-057）：删 StorageBackendRegistry（零外部注册者的 Map 间接层），改内联 switch。
+ * M93-01（RFC-057 §3 D7）：`StorageOptions` 为穷尽判别联合，switch 按 type 窄化——去工厂边界
+ * `as unknown as`，恢复编译期保护（漏 case / 字段类型不符均被 typecheck 拦）。
+ */
+declare function createPersistence<T = unknown>(options: StorageOptions<T>): Persistence<T>;
+//#endregion
+//#region src/change-log.d.ts
+/**
+ * change_log 表记录：SqlitePersistence 写入，SSE 路由轮询推送。
+ */
+interface ChangeLogEntry {
+  id: number;
+  ns: string;
+  doc_id: string;
+  op: 'save' | 'delete';
+  ts: number;
+}
+//#endregion
+//#region src/append-log.d.ts
+/**
+ * append-only 日志原语（取向 B，与 snapshot 取向正交）。
+ *
+ * 与 `Persistence<Snapshot<T>>`（一份最新状态的 CRUD）不同，`AppendLog<E>` 表达
+ * “按序追加 + 范围读 + 实时 tail”的事件溯源语义。`TraceStore` 是它的领域包装
+ * （`streamId = sessionId`，`E = TraceEvent`）。原设计稿 docs/design/storage-kernel.md 已随
+ * RFC-067 M123-03 文档收敛删除，内容并入 packages/persistence/ARCHITECTURE.md，见 commit 5d6a9f5b。
+ *
+ * 单写者约束：跨进程并发写**不**保证 seq 全序（引擎进程独占写自己的 trace）。
+ */
+interface LogEntry<E> {
+  /** 单调递增序号，append 时由后端分配（从 0 起，逐 stream 独立）。等于该 stream 内的行号。 */
+  seq: number;
+  /** 分流键（如 sessionId）。 */
+  streamId: string;
+  /** 领域负载（如 TraceEvent）。 */
+  entry: E;
+}
+interface AppendRange {
+  /** seq 下界（含），默认 0。 */
+  from?: number;
+  /** seq 上界（不含），默认 +∞。 */
+  to?: number;
+}
+interface LogCodec<E> {
+  encode(entry: E): string;
+  decode(payload: string): E;
+}
+interface AppendLog<E> {
+  /** 追加一条，返回含已分配 seq 的记录。 */
+  append(streamId: string, entry: E): Promise<LogEntry<E>>;
+  /** 按 seq 升序读取（可选范围）；stream 不存在 → 空迭代，不抛。 */
+  read(streamId: string, range?: AppendRange): AsyncIterable<LogEntry<E>>;
+  /**
+   * 可选——stream 当前记录数（= 下一个待分配 seq）。宿主用于「只回放最近 N 条」的
+   * range 计算（如 inspector backfill 封顶），避免全量 decode 只为拿总数。
+   */
+  count?(streamId: string): Promise<number>;
+  /** 先回放已有，再实时跟随后续 append（实时观测底座）。 */
+  tail(streamId: string): AsyncIterable<LogEntry<E>>;
+  /**
+   * 截断到 toSeq（保留 seq < toSeq，丢弃 seq ≥ toSeq）；下次 append 从 toSeq 续号。
+   * 回滚/分叉用（trace 截到 checkpoint 的 traceSeq）。toSeq ≤ 0 等价清空该 stream；
+   * toSeq ≥ 当前长度为无操作。stream 不存在 → 无操作，不抛。
+   *
+   * 注意（单写者语义）：已在运行的 tail 迭代器持有自身 lastSeq 游标，truncate 后复用的
+   * seq 号不会被同一迭代器重新发出（避免乱序）——回滚分支应重新 tail。
+   */
+  truncate(streamId: string, toSeq: number): Promise<void>;
+  /** 删除整个 stream（回滚/分叉用）。 */
+  clear(streamId: string): Promise<void>;
+  /**
+   * 可选——释放底层资源（FileAppendLog/HttpAppendLog 实现关闭文件句柄/刷写队列；
+   * MemoryAppendLog 无需）。宿主关停时 `await store.close?.()`，取代旧 `'close' in store` 鸭子探测。
+   */
+  close?(): Promise<void>;
+}
+type AppendLogOptions<E> = {
+  type: 'memory';
+} | {
+  type: 'file';
+  baseDir: string;
+  extension?: string;
+  codec?: LogCodec<E>;
+  pollIntervalMs?: number;
+};
+declare class MemoryAppendLog<E> implements AppendLog<E> {
+  private readonly streams;
+  private readonly listeners;
+  private readonly maxRecordsPerStream;
+  private readonly onEvict?;
+  constructor(options?: {
+    maxRecordsPerStream?: number; /** 驱逐发生时的诊断回调（可选，如宿主想告警/记日志）。 */
+    onEvict?: (streamId: string, evictedSeq: number, totalDropped: number) => void;
+  });
+  private getOrCreateStream;
+  append(streamId: string, entry: E): Promise<LogEntry<E>>;
+  read(streamId: string, range?: AppendRange): AsyncIterable<LogEntry<E>>;
+  /** stream 记录数上限（= 下一个 seq，与实际保留条数无关——驱逐后二者分道，保持 seq 单调语义）。 */
+  count(streamId: string): Promise<number>;
+  tail(streamId: string): AsyncIterable<LogEntry<E>>;
+  truncate(streamId: string, toSeq: number): Promise<void>;
+  clear(streamId: string): Promise<void>;
+}
+declare class FileAppendLog<E> implements AppendLog<E> {
+  private readonly baseDir;
+  private readonly extension;
+  private readonly codec;
+  private readonly pollIntervalMs;
+  private readonly seqCounters;
+  /** 稀疏字节索引缓存（进程内，非持久化——重启后懒重建）。 */
+  private readonly byteIndexes;
+  /**
+   * RFC-145 D1：per-stream 常驻写句柄缓存。追加热路径从每条 open/stat/write/close
+   * （~8 syscalls，含 repair 探测）降到 1 次 write——profile 实证长会话进程主线程
+   * 非 idle 样本 88% 在 uv_fs 句柄生命周期回调（sample 67571，2026-07-11）。
+   * `tailByteOffset` 增量跟踪文件末尾偏移（open 时 stat 一次初始化，每写后累加），
+   * 消除 byteIndex 维护的 per-append stat。正确性前提：writeQueue 串行 + O_APPEND +
+   * 单写者。失效协议见 invalidateHandle()。
+   */
+  private readonly handles;
+  /**
+   * RFC-145 D2：进程内已执行过尾部修复的 stream 集合。单写者约束下半行只可能来自
+   * 上次进程崩溃的残留——进程存活期内自己的写不产生半行（writeFile 整行经 writeQueue
+   * 串行原子入队），故 repair 探测每 stream 只需执行一次（冷启动语义：新实例首次
+   * append 前仍会 repair）。truncate/clear 后不清除——ftruncate 原子、clear 走
+   * unlink+重建，均不产生半行。
+   */
+  private readonly repairedStreams;
+  private writeQueue;
+  private dirReady;
+  private closed;
+  constructor(options: {
+    baseDir: string;
+    extension?: string;
+    codec?: LogCodec<E>;
+    pollIntervalMs?: number;
+  });
+  append(streamId: string, entry: E): Promise<LogEntry<E>>;
+  private appendSerial;
+  /**
+   * RFC-145 D1：打开并缓存常驻写句柄。open 时 stat 一次初始化 tailByteOffset；
+   * 入缓存前执行上限驱逐（LRU）与 idle 回收（惰性，无常驻 timer）。
+   * 仅在 writeQueue 串行域内调用。
+   */
+  private openResidentHandle;
+  /**
+   * RFC-145 D1 失效协议：关闭并移除某 stream 的常驻写句柄（连同 tailByteOffset）。
+   * 四条路径在操作 stream 文件前必须调用：truncateSerial / clearSerial /
+   * repairPartialTail / close()——它们各自 open 独立句柄操作文件，缓存句柄若还活着，
+   * 后续 append 会写到被 truncate/unlink 的旧 inode（数据静默丢失）。
+   * 均在 writeQueue 串行域内执行，无并发窗口。
+   */
+  private invalidateHandle;
+  /**
+   * 索引增量维护：每 INDEX_INTERVAL 行落一个锚点，并推进 tailSeq/tailByteOffset
+   * （下次 append 据此判断能否零 IO 继续维护）。只在索引已就位（冷启动懒构建过一次）
+   * 时生效——否则每次 append 都要额外 stat 判断是否该建索引，得不偿失。
+   *
+   * 单调性守卫（`seq < index.tailSeq` 提前返回）：append 与 read() 都会推进同一 stream
+   * 的索引 tailSeq，二者不互斥（read 不在 writeQueue 内）。appendSerial 在
+   * `stat()` 到这里之间有 await 缺口，若同一窗口内一次并发 read() 已把 tailSeq 推进到
+   * 更前面，此处必须放弃写入，否则会用旧的 seq/byteOffset 把 tailSeq 拉回退——
+   * 破坏 nearestAnchor 依赖的 anchors 严格递增假设。
+   */
+  private recordIndexPoint;
+  /**
+   * 冷启动/索引缺口时的懒构建：顺序扫描一遍文件，边扫边记锚点（与 read() 的分块扫描
+   * 复用同一遍 IO，零额外开销——调用方（read）在扫描主循环里同步喂入行边界）。
+   * 返回构建后的索引（供 read() 立即复用做本次的 seek 判断）。
+   *
+   * TOCTOU 说明：并发 read() 首次访问同一 streamId 时，Map.get/set 之间无 await 缺口
+   * （本方法全同步），不存在两次并发调用互相覆盖对方索引对象的竞态——JS 单线程下
+   * 同步代码段天然原子。
+   */
+  private ensureByteIndex;
+  /** 索引中 ≤ from 的最近锚点（无锚点或 from=0 时退化为文件头，即旧行为）。 */
+  private nearestAnchor;
+  /**
+   * 尾部半行修复（崩溃恢复）：只检查/裁剪文件尾部，O(尾部) 而非 O(文件)。
+   * 旧实现全量 readFile + atomicWriteFile 全量重写——巨型 trace（数百 MB）下不可用。
+   * 现：stat + 读最后 1 字节判完整；不完整时从尾部按块回扫找最后一个 '\n'，`ftruncate`
+   * 原地截断（truncate 掉的只是半行垃圾，无崩溃安全顾虑——重复截断幂等）。
+   */
+  private repairPartialTail;
+  /**
+   * 流式逐行读取：分块读 + 增量 decode，只对范围内的行做 JSON decode。
+   * 旧实现 loadAll 全量 readFile + 全行 JSON.parse——260MB trace 下 ~1s 主线程阻塞
+   * 且峰值内存 >1.4GB；带 range 时（如 inspector backfill 只要最近 N 条）纯浪费。
+   *
+   * RFC-102 backlog T1：`range.from` 命中已建索引区间时，直接 seek 到最近锚点字节偏移
+   * （`handle.read(buf, 0, len, position)` 的 position 参数跳过前缀 IO，不只是跳过 decode）
+   * ——替代旧实现「总是从字节 0 顺序扫到 from」。真机验证（260MB/24万行存量 trace，
+   * scrubber 高频精细拖动场景）：30 次连续 range read 从 13.3s/单次最大阻塞89ms 降至毫秒级。
+   * 索引未覆盖 from（冷启动/gap）时透明退化为旧的顺序扫描，同时顺路把扫过的区间记入索引——
+   * 首次访问某区域仍是 O(距离)，但此后同区域内的精细拖动全部命中索引。
+   */
+  read(streamId: string, range?: AppendRange): AsyncIterable<LogEntry<E>>;
+  /** stream 记录数（= 下一个 seq）。优先用进程内 seq 缓存；否则字节流数行（不 decode）。 */
+  count(streamId: string): Promise<number>;
+  /**
+   * 增量轮询：只读上次字节偏移后新追加的部分、只 decode 新行。
+   * 旧实现每 poll `loadAll` 重读整个文件 + 全行 JSON.parse（O(N)/poll）——长会话下吃满 CPU/GC、
+   * 阻塞事件循环致输入卡顿（profile 实证 decode/loadAll/string_decoder 占 ~88% CPU）。现降到 O(新增)。
+   */
+  tail(streamId: string): AsyncIterable<LogEntry<E>>;
+  /**
+   * 停止所有进行中的 tail() 轮询循环——while(!closed) 在下个轮询点退出，常驻 tail 订阅随之终止。
+   * app.stop() 经可选链 store.close?.() 调用本方法（fix: /exit·Ctrl+C 退不掉）：缺此方法时，
+   * inspector 的常驻 trace tail 永久轮询，是 /exit、Ctrl+C 退不掉的近因。
+   */
+  close(): Promise<void>;
+  truncate(streamId: string, toSeq: number): Promise<void>;
+  private truncateSerial;
+  clear(streamId: string): Promise<void>;
+  private clearSerial;
+  /** 字节流数行（数 '\n'，不 decode JSON）——nextSeq/count 冷启动用，O(文件) IO 但零 parse/GC。 */
+  private countLines;
+  private nextSeq;
+  private resolvePath;
+  private ensureDir;
+}
+/**
+ * 统一日志工厂：按 `options.type` 直构造内置后端（memory/file）。
+ * `AppendLogOptions` 穷尽判别联合，switch 按 type 窄化——去 `as unknown as`。
+ */
+declare function createAppendLog<E>(options: AppendLogOptions<E>): AppendLog<E>;
+/** 内存实时旁路：订阅某 stream 的后续 append（live 观测者用，避免绕磁盘 tail 轮询）。 */
+interface LiveTap<E> {
+  /** 订阅 streamId 的后续 append；返回取消订阅函数。无订阅者时 publish 为 no-op。 */
+  subscribe(streamId: string, fn: (record: LogEntry<E>) => void): () => void;
+}
+/**
+ * 给 AppendLog 套一层内存实时旁路（L3 终局）：`append` 在写底层 store 的同时把记录 publish 给内存订阅者。
+ * live 观测者（inspector）订阅 `live` 拿实时 append，**不再 `tail` 磁盘轮询**——live 进程内数据不绕磁盘；
+ * 底层 store 仍负责持久化与「回放过去会话」的 `read`/`tail`。
+ */
+declare function createLiveTappedAppendLog<E>(inner: AppendLog<E>): {
+  store: AppendLog<E>;
+  live: LiveTap<E>;
+};
+//#endregion
+//#region src/storage-host.d.ts
+interface StorageHostOptions {
+  /** 允许的 namespace 白名单（如 ['sessions']；knowledge/archive 已退场）。 */
+  namespaces: string[];
+  /** 每 namespace 的后端工厂。 */
+  backend: (namespace: string) => Persistence<unknown>;
+  /** 时间源（信封 createdAt/updatedAt），缺省真实时钟。 */
+  now?: () => number;
+}
+declare class StorageHost {
+  private readonly namespaces;
+  private readonly backend;
+  private readonly now;
+  private readonly instances;
+  /** 每 namespace 的 append-only 日志（惰性创建）。 */
+  private readonly appendLogs;
+  constructor(options: StorageHostOptions);
+  has(namespace: string): boolean;
+  /** 返回所有注册的 namespace 列表（health 路由使用）。 */
+  listNamespaces(): string[];
+  /**
+   * workspace 分区——wsKey 前缀到文档 ID,在 namespace 内实现物理分区。
+   * wsKey = `ws_<id>`,缺省 `default`(向后兼容旧调用方)。
+   */
+  private wsId;
+  /**
+   * 追加一条 entry 到指定 stream 的 append-only 日志。
+   *
+   * 返回含已分配 seq 的 LogEntry——seq 由 AppendLog 保证单写者递增（0-based per stream）。
+   * 默认使用 MemoryAppendLog（进程内原子追加）；调用侧（service route）负责
+   * 在 append 后通过 EventBus 广播 SSE 实时通知。
+   *
+   * @param namespace 命名空间（如 'sessions'）
+   * @param wsKey     workspace 分区键（ws_<id>），前缀文档 ID 在 namespace 内物理分区
+   * @param streamId  流 ID（通常为文档/会话 ID）
+   * @param entry     要追加的条目数据
+   * @returns 含 seq、streamId、entry 的 LogEntry
+   */
+  appendEntry(namespace: string, wsKey: string | undefined, streamId: string, entry: unknown): Promise<LogEntry<unknown>>;
+  save(namespace: string, wsKey: string | undefined, id: string, document: unknown, agentId?: string): Promise<void>;
+  updateMetadata(namespace: string, wsKey: string | undefined, id: string, patch: Record<string, unknown>, agentId?: string): Promise<void>;
+  load(namespace: string, wsKey: string | undefined, id: string): Promise<unknown | null>;
+  delete(namespace: string, wsKey: string | undefined, id: string): Promise<boolean>;
+  list(namespace: string, wsKey?: string, agentId?: string, scope?: 'owned' | 'visible' | 'all'): Promise<string[]>;
+  /**
+   * 增量拉取（sync pull 数据源）。
+   *
+   * 返回自 `since` (unix ms) 以来 updated_at > since 的文档快照列表，
+   * 以及最新游标 cursor（所有文档中最大的 updated_at，供下次 pull 使用）。
+   *
+   * SQLite 后端走索引查询（O(log n)）；file/memory 后端全量加载后内存过滤。
+   */
+  getChangesSince(namespace: string, wsKey: string | undefined, since: number, ids?: string[]): Promise<{
+    documents: Map<string, unknown | null>;
+    cursor: number;
+  }>;
+  listPaginated(namespace: string, wsKey: string | undefined, options: {
+    page: number;
+    pageSize: number;
+    sortBy: string;
+    order: 'asc' | 'desc';
+  }): Promise<PaginatedResult<string>>;
+  /** 信封 metadata[sortBy] → 文档 metadata?.[sortBy] → 信封 updatedAt 兜底。 */
+  private sortValue;
+  /**
+   * 实时事件流（SSE 推送来源）。
+   *
+   * 轮询后端 change_log 并 yield 变更事件——仅 SQLite 后端支持；file/memory 后端返回空迭代。
+   * 设计决策：用鸭子类型（`getChangeLog` 方法探测）而非直接 import SqlitePersistence，
+   * 保持 StorageHost 对具体后端的零耦合。
+   *
+   * @param signal 取消信号——客户端断连时中止轮询，避免生成器泄漏。
+   */
+  streamEvents(namespace: string, wsKey: string | undefined, since: number, pollMs?: number, signal?: AbortSignal): AsyncGenerator<{
+    id: number;
+    doc_id: string;
+    op: string;
+    ts: number;
+  }, void, void>;
+  private resolve;
+}
+declare function createFileStorageHost(options: {
+  baseDir: string;
+  namespaces?: string[];
+  now?: () => number;
+}): StorageHost;
+//#endregion
+//#region src/http-append-log.d.ts
+interface HttpAppendLogOptions<E> {
+  /** remote-persistence-server base URL (e.g. https://storage.example.com). */
+  baseUrl: string;
+  /** Auth token provider (same as RemotePersistence). */
+  getAuth: () => Promise<{
+    token: string;
+  }>;
+  /** Optional extra headers (e.g. X-Agent-Id). */
+  getHeaders?: () => Promise<Record<string, string>>;
+  /** fetch impl (defaults to globalThis.fetch). */
+  fetch?: typeof globalThis.fetch;
+  /** Request timeout ms (default 30s). */
+  timeoutMs?: number;
+  /** Batch flush interval ms (default 2000). */
+  flushIntervalMs?: number;
+  /** Max batch size before immediate flush (default 100). */
+  flushAtSize?: number;
+  /** Poll interval ms for tail (default 500). */
+  pollIntervalMs?: number;
+  /** Codec for encoding/decoding entries (default JSON). */
+  codec?: LogCodec<E>;
+}
+/**
+ * HTTP AppendLog 实现 — 将 trace/checkpoint 事件推送到 remote-persistence-server。
+ *
+ * 内部批处理（定时或满批量 flush），避免每事件一次 HTTP round-trip。
+ * append 是 fire-and-forget（调用方只关心事件已入队）；flush 在后台异步完成。
+ *
+ * read/tail 直接拉取服务端已持久化数据；tail 采用轮询模式。
+ */
+declare class HttpAppendLog<E> implements AppendLog<E> {
+  private readonly baseUrl;
+  private readonly getAuth;
+  private readonly getHeaders;
+  private readonly fetchImpl;
+  private readonly timeoutMs;
+  private readonly pollIntervalMs;
+  private readonly flushAtSize;
+  private readonly codec;
+  private readonly buffer;
+  /** RFC-353: 正在 flush 的 streamId 集合——防止满批量 flush 与定时 flush 并发发同一 batch。 */
+  private readonly flushingStreams;
+  private flushTimer?;
+  private closed;
+  constructor(options: HttpAppendLogOptions<E>);
+  append(streamId: string, entry: E): Promise<LogEntry<E>>;
+  /**
+   * RFC-353: per-stream flush 串行化。若该 stream 已在 flush 中（满批量触发 + 定时触发
+   * 或两次满批量触发重叠），跳过——正在进行的 flush 完成后，新 buffer 会在下一轮
+   * 定时 flush 或下次满批量时被处理。消除并发 flushOne 同一 batch 导致服务端重复 append
+   * 与 seq 不连续。
+   */
+  private tryFlush;
+  private flushOne;
+  private flushAll;
+  read(streamId: string, range?: AppendRange): AsyncIterable<LogEntry<E>>;
+  tail(streamId: string): AsyncIterable<LogEntry<E>>;
+  /**
+   * stream 事件总数（服务端 COUNT(*) 索引扫描 + 本地未 flush 的在途 buffer 计数）。
+   * 消费端（inspector backfill）据此只拉最近 N 条，不必先 read() 全量再取 length
+   * （RFC-102 backlog T4：此前无 count() 时 `?? 0` 回退触发全量回放）。
+   */
+  count(streamId: string): Promise<number>;
+  truncate(streamId: string, toSeq: number): Promise<void>;
+  clear(streamId: string): Promise<void>;
+  /** 关闭：停止 flush 定时器，排空 buffer。 */
+  close(): Promise<void>;
+  private request;
+}
+//#endregion
+//#region src/sqlite-db-cache.d.ts
+/** 单次 schema 迁移。`version` 必须连续从小到大。 */
+interface Migration {
+  /** 迁移目标版本号（1-based）；`up` 执行后 db 的 user_version 变为该值。 */
+  version: number;
+  /** 前向迁移 DDL。幂等（建议用 `CREATE TABLE IF NOT EXISTS`）。 */
+  up: (db: Database.Database) => void;
+}
+declare function acquireDb(dbPath: string, wal?: boolean, migrationSet?: Migration[]): Database.Database;
+declare function releaseDb(db: Database.Database): void;
+//#endregion
+//#region src/sqlite-persistence.d.ts
+interface SqlitePersistenceOptions<T = unknown> {
+  /** SQLite 数据库文件路径。用 ':memory:' 做测试。 */
+  dbPath: string;
+  /** 是否启用 WAL 模式（默认 true）。 */
+  wal?: boolean;
+  /** 表内 namespace 标识（用于跨 ns 共享单个 db 文件）。 */
+  namespace: string;
+  /** 默认每页大小（默认 20）。 */
+  defaultPageSize?: number;
+  /** snapshots 表的 codec（默认 JSON）。 */
+  codec?: Codec<Snapshot<T>>;
+}
+/**
+ * SQLite 快照后端（M28-01）。
+ *
+ * 通过通用 `snapshots` 表实现 `Persistence<T>` 接口——单 db 文件多 namespace 共享，
+ * WAL 模式支持 1 写者 + N 读者并发。每次 save 自动写 `change_log` 行供 SSE 轮询。
+ *
+ * 通过 `sqlite-db-cache` 的单一连接缓存（acquireDb/releaseDb）与其他 consumer 共享同一 db 文件，
+ * 避免 WAL 锁冲突。DDL 由 `acquireDb` 的 `applyMigrations` 统一管理（M60-02）；本类不再自建表。
+ */
+declare class SqlitePersistence<T = unknown> implements Persistence<T> {
+  private readonly db;
+  private readonly ns;
+  private readonly defaultPageSize;
+  private readonly codec;
+  constructor(options: SqlitePersistenceOptions<T>);
+  /** 释放引用；相同 db 路径上所有实例都释放后才关闭物理连接。 */
+  close(): void;
+  save(snapshot: Snapshot<T>): Promise<void>;
+  load(id: string): Promise<Snapshot<T> | null>;
+  delete(id: string): Promise<boolean>;
+  list(): Promise<string[]>;
+  listPaginated(options: {
+    page: number;
+    pageSize?: number;
+    sortBy?: string;
+    order?: 'asc' | 'desc';
+  }): Promise<PaginatedResult<string>>;
+  /**
+   * 查询某个 ns 在 since (unix ms) 起的变更日志。
+   * 用 `ts >= since`（非 `>`）+ 单调 `id` 次序：同毫秒内后到的变更不会因游标落在该 ms 被跳过
+   * （消费方按 change_log.id 去重已产出项）。次序 `ts ASC, id ASC` 保证 id 单调可用作去重游标。
+   */
+  getChangeLog(ns: string, since: number, limit?: number): ChangeLogEntry[];
+  /** 增量拉取自 since 后变更的文档 ID 列表 + 最新游标（M28-05 sync pull 优化路径）。 */
+  getChangesSince(ns: string, since: number, ids?: string[]): {
+    ids: string[];
+    cursor: number;
+  };
+  /** 查询 since 后被删除的文档 ID 列表（M28-05 sync pull delete 标记）。 */
+  getDeletedSince(ns: string, since: number): string[];
+  /** 获取某个 ns 的最新 updated_at 时间戳（供 SQL cursor 初始化）。 */
+  private getLatestCursor;
+  /** 获取某个 ns 的最新变更时间戳（供 cursor 初始化）。 */
+  getLatestChangeTs(ns: string): number;
+  /** SQLite 完整性诊断信息（M34-02 doctor 使用）。 */
+  getInfo(): {
+    walEnabled: boolean;
+    snapshots: number;
+    changeLogEntries: number;
+    sessions: number;
+    integrity: string;
+  };
+}
+//#endregion
+export { type AppendLog, type AppendLogOptions, type AppendRange, type ChangeLogEntry, type Codec, DiskPanelStatePersistence, DiskPasteStatePersistence, DiskPersistence, type DiskPersistenceOptions, type EntityPersistenceShape, FileAppendLog, FilePersistence, type FilePersistenceOptions, HttpAppendLog, type HttpAppendLogOptions, type LiveTap, type LogCodec, type LogEntry, MemoryAppendLog, MemoryPersistence, MemoryPersistenceBase, type MemoryPersistenceBaseOptions, type Metadata, type Migration, type PaginatedResult, type PaginationOptions, type PanelStateDraftEntry, type PanelStateEditedFile, type PanelStatePersistence, type PanelStateSnapshot, type PanelStateSubagentEntry, type PanelStateTodoItem, type PanelStateTurnSummary, type PasteStateEntry, type PasteStatePersistence, type PasteStateSnapshot, type Persistence, PersistenceError, type PersistenceShape, RemotePersistence, RemotePersistenceError, type RemotePersistenceOptions, RemoteSnapshotConflictError, type Snapshot, type SnapshotConflictInfo, SqlitePersistence, type SqlitePersistenceOptions, StorageHost, type StorageHostOptions, type StorageOptions, acquireDb, atomicWriteFile, createAppendLog, createFileStorageHost, createInMemoryPanelStatePersistence, createInMemoryPasteStatePersistence, createLiveTappedAppendLog, createPersistence, normalizePasteSnapshot, releaseDb, resolvePasteNextId, saveDocument };
+//# sourceMappingURL=index.d.ts.map