@morlay/session-rdb 0.0.15 → 0.0.16-alpha.0

package/src/adapters/to-sqlite.ts

@@ -10,24 +10,26 @@ import {
   type AnySQLiteTable,
   type SQLiteColumnBuilder,
 } from "drizzle-orm/sqlite-core";
-import { toProperty, type ColumnDef, type TableDef } from "../entities/types.ts";
+import { toProperty, type ColumnDef, type TableDef } from "./types.ts";
 
 type TableRegistry = Record<string, AnySQLiteTable>;
 
-function buildColumn(c: ColumnDef, tables: TableRegistry): SQLiteColumnBuilder {
+function buildColumn(name: string, c: ColumnDef, tables: TableRegistry): SQLiteColumnBuilder {
   // 具体 builder 类型与基类在方法层面不兼容（泛型逆变），构建阶段用宽松
   // 类型合并，返回时收窄为基类；查询类型安全由手写行接口兜底。
   let col: any;
   switch (c.type) {
-    case "text":
-      col = text(c.name);
+    case "text": {
+      const built = text(name);
+      col = c.primaryKey ? built.primaryKey() : built;
       break;
+    }
     case "serial":
-      col = integer(c.name).primaryKey({ autoIncrement: true });
+      col = integer(name).primaryKey({ autoIncrement: true });
       break;
     case "integer":
     case "bigint": {
-      const built = integer(c.name);
+      const built = integer(name);
       col = c.primaryKey ? built.primaryKey() : built;
       break;
     }
@@ -49,20 +51,24 @@ export function toSqliteSchema(defs: readonly TableDef[]): Record<string, AnySQL
   const tables: TableRegistry = {};
   for (const def of defs) {
     const columns: Record<string, SQLiteColumnBuilder> = {};
-    for (const c of def.columns) columns[toProperty(c.name)] = buildColumn(c, tables);
+    for (const [name, c] of Object.entries(def.columns)) {
+      columns[toProperty(name)] = buildColumn(name, c, tables);
+    }
     const extra = (self: Record<string, unknown>) => [
-      ...(def.checks ?? []).map((c) => sqliteCheck(c.name, sql.raw(c.expression))),
-      ...(def.uniques ?? []).map((u) =>
-        unique(u.name).on(
-          ...(u.columns.map((name) => self[toProperty(name)] as AnySQLiteColumn) as [
+      ...Object.entries(def.checks ?? {}).map(([name, c]) =>
+        sqliteCheck(name, sql.raw(c.expression)),
+      ),
+      ...Object.entries(def.uniques ?? {}).map(([name, u]) =>
+        unique(name).on(
+          ...(u.columns.map((n) => self[toProperty(n)] as AnySQLiteColumn) as [
             AnySQLiteColumn,
             ...AnySQLiteColumn[],
           ]),
         ),
       ),
-      ...(def.indexes ?? []).map((i) =>
-        index(i.name).on(
-          ...(i.columns.map((name) => self[toProperty(name)] as AnySQLiteColumn) as [
+      ...Object.entries(def.indexes ?? {}).map(([name, i]) =>
+        index(name).on(
+          ...(i.columns.map((n) => self[toProperty(n)] as AnySQLiteColumn) as [
             AnySQLiteColumn,
             ...AnySQLiteColumn[],
           ]),

package/src/{entities → adapters}/types.ts

@@ -1,9 +1,10 @@
+/** drizzle util 层：方言无关的表结构描述（entities 与 adapters 共用）。 */
+
 export type ColumnTypeName = "serial" | "integer" | "bigint" | "text";
 
 export type DeleteAction = "cascade" | "set null" | "restrict" | "no action";
 
 export interface ColumnDef {
-  name: string;
   type: ColumnTypeName;
   notNull?: boolean;
 
@@ -21,26 +22,24 @@ export interface ColumnDef {
 }
 
 export interface CheckDef {
-  name: string;
   expression: string;
 }
 
 export interface UniqueDef {
-  name?: string;
   columns: string[];
 }
 
 export interface IndexDef {
-  name: string;
   columns: string[];
 }
 
+/** 表结构描述：columns / checks / uniques / indexes 以 Record 键为名，天然唯一。 */
 export interface TableDef {
   name: string;
-  columns: ColumnDef[];
-  checks?: CheckDef[];
-  uniques?: UniqueDef[];
-  indexes?: IndexDef[];
+  columns: Record<string, ColumnDef>;
+  checks?: Record<string, CheckDef>;
+  uniques?: Record<string, UniqueDef>;
+  indexes?: Record<string, IndexDef>;
 }
 
 export function toProperty(name: string): string {

package/src/backend.ts

@@ -37,8 +37,6 @@ export interface EventRow {
 
   fSequence: number;
 
-  fOriginalSeq: number;
-
   fType: string;
 
   fKind: string;
@@ -72,7 +70,6 @@ export interface BackendTx {
       fSessionId: SessionId;
       fEventId: string;
       fSequence: number;
-      fOriginalSeq: number;
       fSurfaceOp: string | null;
     }>,
   ): Promise<void>;
@@ -87,8 +84,6 @@ export interface BackendTx {
     id: SessionId,
     sequence: number,
   ): Promise<{ fEventId: string; fSequence: number } | undefined>;
-
-  getLastBridge(id: SessionId): Promise<{ fEventId: string; fSequence: number } | undefined>;
 }
 
 export interface Backend {
@@ -100,8 +95,6 @@ export interface Backend {
 
   getSession(id: SessionId): Promise<SessionRow | undefined>;
 
-  getSeqMapRows(id: SessionId): Promise<Array<{ fSequence: number; fOriginalSeq: number }>>;
-
   getEventRows(id: SessionId, fromSequence?: number): Promise<EventRow[]>;
 
   listSessions(): Promise<SessionRow[]>;

package/src/branch.ts

@@ -1,5 +1,6 @@
 import {
   SESSION_FORMAT_VERSION,
+  SessionLogOffset,
   type Session,
   type SessionEvent,
   type SessionHeader,
@@ -19,7 +20,6 @@ import {
 import { randomUUID } from "node:crypto";
 import type { SessionPersistenceRdb } from "./index.ts";
 import { rowToMeta } from "./log.ts";
-import { isPersistedEvent } from "./schema.ts";
 
 export function locateTurnEnd(
   events: readonly SessionEvent[],
@@ -66,12 +66,6 @@ export interface LiveSessionHooks {
   getAgent(id: SessionId): LiveAgentLike | undefined;
 
   flush(session: Session): Promise<boolean>;
-
-  setCoordinatorCursor(id: SessionId, cursor: number): void;
-
-  setCoordinatorState(id: SessionId, cursor: number, meta: SessionHeader): void;
-
-  setCoordinatorSeedLength(id: SessionId, seedLength: number): void;
 }
 
 export interface LiveAgentLike {
@@ -155,9 +149,6 @@ export class SessionBranchRdbProvider implements SessionBranchProvider {
       getSession: () => undefined,
       getAgent: () => undefined,
       flush: async () => true,
-      setCoordinatorCursor: () => {},
-      setCoordinatorState: () => {},
-      setCoordinatorSeedLength: () => {},
     },
   ) {}
 
@@ -176,7 +167,7 @@ export class SessionBranchRdbProvider implements SessionBranchProvider {
     id: SessionId,
     signal?: AbortSignal,
   ): Promise<{ meta: SessionHeader; events: readonly SessionEvent[] }> {
-    const stored = await this.persistence.loadStored(id, signal);
+    const stored = await this.persistence.readLog(id, {}, signal);
     if (stored === undefined)
       throw new SessionBranchError(`session "${id}" not found`, "SESSION_NOT_FOUND");
     return { meta: stored.meta, events: stored.events };
@@ -189,7 +180,9 @@ export class SessionBranchRdbProvider implements SessionBranchProvider {
   ): Promise<SessionId> {
     signal?.throwIfAborted();
     const { atSeq, anchorMode = "after", seedSuffix = [], childSessionId, meta = {} } = options;
-    const source = await this.persistence.inspect(sourceId, signal);
+    const source = await this.persistence.readLog(sourceId, {}, signal);
+    if (source === undefined)
+      throw new SessionBranchError(`session "${sourceId}" not found`, "SESSION_NOT_FOUND");
     const boundary = locateTurnEnd(source.events, atSeq, anchorMode);
     const prefix = source.events.slice(0, boundary + 1);
     const childId = childSessionId ?? mintSessionId();
@@ -213,20 +206,26 @@ export class SessionBranchRdbProvider implements SessionBranchProvider {
       ...(meta.delegationDepth !== undefined ? { delegationDepth: meta.delegationDepth } : {}),
     };
     const seed = [...renumber(prefix, 0), ...renumber(seedSuffix, prefix.length)];
-    // 事件行复用：前缀事件（上游 seq → 源会话已存在事件行 id）注册到写路径，
+    // 事件行复用：前缀事件（稠密 seq → 源会话已存在事件行 id）注册到写路径，
     // appendBatch 消费时复用事件行、不复制。seedSuffix 的 manualTurn 事件是
     // 新事件（无源行），不注册。
     const internals = this.persistence.internals();
     const sourceRows = await internals.backend.getEventRows(sourceId);
-    const sourceEventIds = new Map(sourceRows.map((row) => [row.fOriginalSeq, row.fEventId]));
+    const sourceEventIds = new Map(sourceRows.map((row) => [row.fSequence, row.fEventId]));
     const reuse = new Map<number, string>();
     for (const event of prefix) {
       const eventId = sourceEventIds.get(event.seq);
       if (eventId !== undefined) reuse.set(event.seq, eventId);
     }
     internals.registerReuseEventIds(childId, reuse);
-    await this.persistence.create(childMeta, prefix.length);
-    if (seed.length > 0) await this.persistence.append(childId, seed);
+    const handle = await this.persistence.create(childMeta, {
+      inheritedEventCount: SessionLogOffset(prefix.length),
+    });
+    try {
+      if (seed.length > 0) await handle.append(seed);
+    } finally {
+      await handle.close();
+    }
     return childId;
   }
 
@@ -245,11 +244,12 @@ export class SessionBranchRdbProvider implements SessionBranchProvider {
     const live = this.live.getSession(id);
     // live 会话先落盘 write-behind 缓冲，保证后续读取与后端事务同视图。
     if (live !== undefined) await this.live.flush(live);
-    // 边界校验用原始事件（loadStored，不补 closers）——inspect 会给未闭合
+    // 边界校验用原始事件（readLog，不补 closers）——inspect 会给未闭合
     // log 补合成 closers，把 user/message 边界掩盖成 turn/end，丢失 exclusive
     // 语义。
     const raw = live === undefined ? await this.readRawEvents(id, signal) : undefined;
-    const inspection = live === undefined ? undefined : await this.persistence.inspect(id, signal);
+    const inspection =
+      live === undefined ? undefined : await this.persistence.internals().inspect(id, signal);
     const events = live === undefined ? raw!.events : inspection!.events;
     const meta = live === undefined ? raw!.meta : inspection!.meta;
     const boundaryEvent = events[toBoundary];
@@ -273,12 +273,9 @@ export class SessionBranchRdbProvider implements SessionBranchProvider {
     const keepLength = balanceRewindPrefix(events.slice(0, rawKeepLength)).length;
 
     const internals = this.persistence.internals();
-    // live 视图是上游 seq（含被过滤的 delta），RDB head 是稠密 seq——live
-    // 边界须换算为前缀中 persisted 事件数 - 1；cold 视图本身已是稠密 seq。
-    const denseBoundary =
-      live === undefined
-        ? keepLength - 1
-        : events.slice(0, keepLength).filter(isPersistedEvent).length - 1;
+    // 原样存储（无过滤）：live 视图与 RDB head 同空间（上游 seq），
+    // 边界即保留前缀长度 - 1。
+    const denseBoundary = keepLength - 1;
     const newSeedLength = await internals.backend.transaction(async (tx) => {
       signal?.throwIfAborted();
       const head = await tx.getHead(id);
@@ -308,17 +305,12 @@ export class SessionBranchRdbProvider implements SessionBranchProvider {
       await tx.bumpRevision(id);
       return shrunk;
     });
-    // 同步 coordinator 的 storage.inheritedEventCount——DB 已收缩而内存不
-    // 收缩的话，下一次 append 的 upsert 会把旧值覆盖回去。
-    if (newSeedLength !== null) {
-      this.live.setCoordinatorSeedLength(id, newSeedLength);
-    }
 
     // 更新确认 head（下一次 append 的并发校验基准），与 appendBatch 同语义。
     internals.writeGuard.confirmHead(id, denseBoundary);
 
     if (live !== undefined) {
-      // live 分支：截断内存 log 并重置派生缓存；同步 coordinator cursor 与
+      // live 分支：截断内存 log 并重置派生缓存；同步 handle cursor 与
       // agent 轮次游标。不调用 load——live 时 load 会先 flush 把旧内存写回，
       // 撤销本次截断。
       truncateLiveSession(live, keepLength);
@@ -331,14 +323,12 @@ export class SessionBranchRdbProvider implements SessionBranchProvider {
         const phase = (agent as unknown as { phase?: { lastTurn?: number } }).phase;
         if (phase !== undefined) phase.lastTurn = lastTurn;
       }
-      this.live.setCoordinatorCursor(id, keepLength);
-    } else {
-      // cold 分支：user/message 边界直接同步 ownerless states 条目（load 会
-      // 补 closers 撤销截断语义）；turn/end 边界经 load 重新 adopt。
-      if (boundaryEvent?.type === "user/message") {
-        this.live.setCoordinatorState(id, keepLength, meta);
-      } else {
-        await this.persistence.load(id);
+      // DB 已截断：同步 live write handle 的 cursor 与继承前缀，使下一次
+      // append 从截断后的位置续接。handle cursor 是**上游空间**（live 内存
+      // log 截断后的长度，与 drainBuffered 的过滤/contiguity 校验同空间）。
+      const handle = this.persistence.tracker.writerOf(id);
+      if (handle !== undefined) {
+        handle.resetAfterRewind(keepLength, newSeedLength === null ? undefined : newSeedLength);
       }
     }
 
@@ -385,57 +375,6 @@ export class SessionBranchRdb extends SessionBranch {
         return agents?.get(id);
       },
       flush: (session) => this.ctx.sessions.flush(session),
-      setCoordinatorCursor: (id, cursor) => {
-        // states 是私有 Map；保留条目（owner 不能丢），仅对齐 cursor 到新尾部。
-        const persistence = this.ctx.sessionPersistence as unknown as {
-          coordinator?: {
-            states?: Map<SessionId, { cursor: number } | undefined>;
-          };
-        };
-        const state = persistence.coordinator?.states?.get(id);
-        if (state !== undefined) state.cursor = cursor;
-      },
-      setCoordinatorState: (id, cursor, meta) => {
-        // states 条目可能不存在（会话从未被 adopt）；存在则仅对齐 cursor，
-        // 不存在则创建 ownerless 条目，使下一次 append 走标准路径而非 adopt
-        // （adopt 会经 prepareCore 补 closers 撤销截断）。
-        const persistence = this.ctx.sessionPersistence as unknown as {
-          coordinator?: {
-            states?: Map<
-              SessionId,
-              { cursor: number; meta: SessionHeader; materialized: boolean } | undefined
-            >;
-          };
-        };
-        const states = persistence.coordinator?.states;
-        if (states === undefined) return;
-        const state = states.get(id);
-        if (state !== undefined) {
-          state.cursor = cursor;
-        } else {
-          states.set(id, { meta, cursor, materialized: true });
-        }
-      },
-      setCoordinatorSeedLength: (id, seedLength) => {
-        // 收缩 storage.inheritedEventCount，与 DB 事务内的收缩保持一致——
-        // 不同步的话下一次 append 的 upsert 会把旧值覆盖回去。storage 对象
-        // 可能被冻结，整体替换 state.storage 而非改字段。
-        const persistence = this.ctx.sessionPersistence as unknown as {
-          coordinator?: {
-            states?: Map<
-              SessionId,
-              | {
-                  storage?: { meta: SessionHeader; inheritedEventCount: number };
-                }
-              | undefined
-            >;
-          };
-        };
-        const state = persistence.coordinator?.states?.get(id);
-        if (state?.storage !== undefined && state.storage.inheritedEventCount > seedLength) {
-          state.storage = { ...state.storage, inheritedEventCount: seedLength };
-        }
-      },
     },
   );
 
@@ -471,26 +410,6 @@ export class SessionBranchRdb extends SessionBranch {
     return this.provider.rewind(id, toBoundary, signal);
   }
 
-  syncLiveCursor(sessionId: SessionId): void {
-    const live = this.ctx.sessions.get(sessionId);
-    if (live === undefined) return;
-    const persistence = this.ctx.sessionPersistence as unknown as {
-      coordinator?: {
-        states?: Map<SessionId, { cursor: number } | undefined>;
-      };
-    };
-    const state = persistence.coordinator?.states?.get(sessionId);
-    if (state === undefined) return;
-    let cursor = state.cursor;
-    // ignorable 是下游信封扩展（上游 SessionEvent 无此字段），结构化读取。
-    while (
-      (live.snapshotEvents()[cursor] as (SessionEvent & { ignorable?: unknown }) | undefined)
-        ?.ignorable === true
-    )
-      cursor += 1;
-    state.cursor = cursor;
-  }
-
   async timeline(sessionId: SessionId, signal?: AbortSignal) {
     const persistence = this.ctx.sessionPersistence as SessionPersistenceRdb;
     const snapshots = await persistence.listSnapshots(signal);
@@ -499,7 +418,7 @@ export class SessionBranchRdb extends SessionBranch {
     const readOwnEvents = async (id: SessionId, fromSeq: number, s?: AbortSignal) => {
       const live = this.ctx.sessions.get(id);
       if (live !== undefined) return live.snapshotEvents().slice(fromSeq);
-      return (await persistence.readFrom(id, fromSeq, s)).events;
+      return (await persistence.internals().readFrom(id, fromSeq, s)).events;
     };
     return buildTimeline(snapshots, readOwnEvents, sessionId, signal);
   }

package/src/drizzle/postgres-v2.ts

@@ -0,0 +1,11 @@
+// drizzle-kit 入口：v2 快照（PG，具名导出表对象）。
+import { toPostgresSchema } from "../adapters/to-postgres.ts";
+import { postgresTableDefsV2 } from "../entities/v2/index.ts";
+
+const tables = toPostgresSchema(postgresTableDefsV2);
+
+export const tPersistenceState = tables["t_persistence_state"]!;
+export const tSchemaMeta = tables["t_schema_meta"]!;
+export const tSessions = tables["t_sessions"]!;
+export const tEvents = tables["t_events"]!;
+export const tSessionEvents = tables["t_session_events"]!;

package/src/drizzle/postgres-v3.ts

@@ -0,0 +1,11 @@
+// drizzle-kit 入口：v3 快照（PG，具名导出表对象）。
+import { toPostgresSchema } from "../adapters/to-postgres.ts";
+import { postgresTableDefs } from "../entities/v3/index.ts";
+
+const tables = toPostgresSchema(postgresTableDefs);
+
+export const tPersistenceState = tables["t_persistence_state"]!;
+export const tSchemaMeta = tables["t_schema_meta"]!;
+export const tSessions = tables["t_sessions"]!;
+export const tEvents = tables["t_events"]!;
+export const tSessionEvents = tables["t_session_events"]!;

package/src/drizzle/sqlite-v2.ts

@@ -0,0 +1,10 @@
+// drizzle-kit 入口：v2 快照（具名导出表对象，供 generate 生成 v2 baseline）。
+import { toSqliteSchema } from "../adapters/to-sqlite.ts";
+import { sqliteTableDefsV2 } from "../entities/v2/index.ts";
+
+const tables = toSqliteSchema(sqliteTableDefsV2);
+
+export const tPersistenceState = tables["t_persistence_state"]!;
+export const tSessions = tables["t_sessions"]!;
+export const tEvents = tables["t_events"]!;
+export const tSessionEvents = tables["t_session_events"]!;

package/src/drizzle/sqlite-v3.ts

@@ -0,0 +1,11 @@
+// drizzle-kit 入口：v3 快照（具名导出表对象，供 generate 生成 v3 diff）。
+import { toSqliteSchema } from "../adapters/to-sqlite.ts";
+import { sqliteTableDefs } from "../entities/v3/index.ts";
+
+const tables = toSqliteSchema(sqliteTableDefs);
+
+export const tPersistenceState = tables["t_persistence_state"]!;
+export const tSchemaMeta = tables["t_schema_meta"]!;
+export const tSessions = tables["t_sessions"]!;
+export const tEvents = tables["t_events"]!;
+export const tSessionEvents = tables["t_session_events"]!;

package/src/entities/index.ts

@@ -1,30 +1,2 @@
-import { persistenceState } from "./persistence-state.ts";
-import { schemaMeta } from "./schema-meta.ts";
-import { sessions } from "./sessions.ts";
-import { events } from "./events.ts";
-import { sessionEvents } from "./session-events.ts";
-
-export { persistenceState };
-export { schemaMeta };
-export { sessions };
-export { events };
-export { sessionEvents };
-export type {
-  ColumnDef,
-  TableDef,
-  CheckDef,
-  UniqueDef,
-  IndexDef,
-  ColumnTypeName,
-  DeleteAction,
-} from "./types.ts";
-
-export const sqliteTableDefs = [persistenceState, sessions, events, sessionEvents] as const;
-
-export const postgresTableDefs = [
-  persistenceState,
-  schemaMeta,
-  sessions,
-  events,
-  sessionEvents,
-] as const;
+export { sqliteTableDefs, postgresTableDefs } from "./v3/index.ts";
+export { sqliteTableDefsV2, postgresTableDefsV2 } from "./v2/index.ts";

package/src/entities/v2/index.ts

@@ -0,0 +1,20 @@
+import { persistenceState } from "../v3/persistence-state.ts";
+import { schemaMeta } from "../v3/schema-meta.ts";
+import { sessions } from "../v3/sessions.ts";
+import { events } from "../v3/events.ts";
+import { sessionEvents } from "./session-events.ts";
+
+export { persistenceState };
+export { schemaMeta };
+export { sessions };
+export { events };
+export { sessionEvents };
+
+export const sqliteTableDefsV2 = [persistenceState, sessions, events, sessionEvents] as const;
+export const postgresTableDefsV2 = [
+  persistenceState,
+  schemaMeta,
+  sessions,
+  events,
+  sessionEvents,
+] as const;

package/src/entities/v2/session-events.ts

@@ -0,0 +1,11 @@
+import type { TableDef } from "../../adapters/types.ts";
+import { sessionEvents as v3SessionEvents } from "../v3/session-events.ts";
+
+/** v2 派生：v3 规格 + f_original_seq 列（原样存储前记录上游 seq 的遗留列）。 */
+export const sessionEvents: TableDef = {
+  ...v3SessionEvents,
+  columns: {
+    ...v3SessionEvents.columns,
+    f_original_seq: { type: "integer", notNull: true },
+  },
+};

package/src/entities/v3/events.ts

@@ -0,0 +1,27 @@
+import type { TableDef } from "../../adapters/types.ts";
+
+export const events: TableDef = {
+  name: "t_events",
+  columns: {
+    f_id: { type: "serial", primaryKey: true },
+    f_event_id: { type: "text", notNull: true, unique: true },
+    f_parent_id: { type: "text", notNull: true, default: "" },
+    f_type: { type: "text", notNull: true, default: "" },
+    f_kind: { type: "text", notNull: true, default: "" },
+    f_role: { type: "text", notNull: true, default: "" },
+    f_name: { type: "text", notNull: true, default: "" },
+    f_action_id: { type: "text", notNull: true, default: "" },
+    f_encoding: { type: "text", notNull: true, default: "" },
+    f_data: { type: "text", notNull: true },
+    f_created_at: { type: "bigint", notNull: true, default: 0 },
+  },
+  // 查询经 f_event_id（列级 UNIQUE 唯一索引）与 t_session_events 复合索引
+  // （按 session 过滤后回表）；f_parent_id 仅写路径构造；维度列索引为
+  // 审计/UI 过滤预留。
+  indexes: {
+    idx_events_kind: { columns: ["f_kind"] },
+    idx_events_role: { columns: ["f_role"] },
+    idx_events_name: { columns: ["f_name"] },
+    idx_events_action_id: { columns: ["f_action_id"] },
+  },
+};

package/src/entities/v3/index.ts

@@ -0,0 +1,27 @@
+import { persistenceState } from "./persistence-state.ts";
+import { schemaMeta } from "./schema-meta.ts";
+import { sessions } from "./sessions.ts";
+import { events } from "./events.ts";
+import { sessionEvents } from "./session-events.ts";
+
+export { persistenceState };
+export { schemaMeta };
+export { sessions };
+export { events };
+export { sessionEvents };
+
+export const sqliteTableDefs = [
+  persistenceState,
+  schemaMeta,
+  sessions,
+  events,
+  sessionEvents,
+] as const;
+
+export const postgresTableDefs = [
+  persistenceState,
+  schemaMeta,
+  sessions,
+  events,
+  sessionEvents,
+] as const;

package/src/entities/v3/persistence-state.ts

@@ -0,0 +1,10 @@
+import type { TableDef } from "../../adapters/types.ts";
+
+export const persistenceState: TableDef = {
+  name: "t_persistence_state",
+  columns: {
+    f_singleton: { type: "integer", primaryKey: true },
+    f_store_id: { type: "text", notNull: true },
+  },
+  checks: { ck_persistence_state_singleton: { expression: "f_singleton = 1" } },
+};

package/src/entities/v3/schema-meta.ts

@@ -0,0 +1,9 @@
+import type { TableDef } from "../../adapters/types.ts";
+
+export const schemaMeta: TableDef = {
+  name: "t_schema_meta",
+  columns: {
+    f_key: { type: "text", primaryKey: true },
+    f_value: { type: "text", notNull: true },
+  },
+};

package/src/entities/v3/session-events.ts

@@ -0,0 +1,26 @@
+import type { TableDef } from "../../adapters/types.ts";
+
+export const sessionEvents: TableDef = {
+  name: "t_session_events",
+  columns: {
+    f_id: { type: "serial", primaryKey: true },
+    f_session_id: {
+      type: "text",
+      notNull: true,
+      references: { table: "t_sessions", column: "f_session_id", onDelete: "cascade" },
+    },
+    f_event_id: {
+      type: "text",
+      notNull: true,
+      references: { table: "t_events", column: "f_event_id", onDelete: "cascade" },
+    },
+    f_sequence: { type: "integer", notNull: true },
+    f_surface_op: { type: "text" },
+  },
+  uniques: {
+    uq_session_events_session_sequence: { columns: ["f_session_id", "f_sequence"] },
+  },
+  // UNIQUE(f_session_id, f_sequence) 自动建唯一索引（按 session 过滤 + seq
+  // 范围/排序/取尾）；f_event_id 索引覆盖反向查找（孤儿事件行清理）。
+  indexes: { idx_session_events_event_id: { columns: ["f_event_id"] } },
+};

package/src/entities/v3/sessions.ts

@@ -0,0 +1,20 @@
+import type { TableDef } from "../../adapters/types.ts";
+
+export const sessions: TableDef = {
+  name: "t_sessions",
+  columns: {
+    f_id: { type: "serial", primaryKey: true },
+    f_session_id: { type: "text", notNull: true, unique: true },
+    f_head_event_id: { type: "text", notNull: true, default: "" },
+    f_head_sequence: { type: "integer", notNull: true, default: -1 },
+    f_version: { type: "integer", notNull: true },
+    f_created_at: { type: "bigint", notNull: true },
+    f_cwd: { type: "text" },
+    f_parent_session: { type: "text" },
+    f_seed_length: { type: "integer" },
+    f_origin: { type: "text" },
+    f_delegation_depth: { type: "integer" },
+    f_incarnation: { type: "text", notNull: true },
+    f_revision: { type: "integer", notNull: true },
+  },
+};