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

package/dist/index.mjs

@@ -1,14 +1,19 @@
-import { i as WriteGuard, r as createTablesSql, t as SqliteBackend } from "./sqlite-CG_Qcx5C.mjs";
-import { A as sessionInsertRow, D as rowToMeta, O as scanRows, T as repairSurfaceOps, _ as buildSeqMap, a as SESSION_PERSISTENCE_SQLITE_APPLICATION_ID, b as recomputeReplaceProvenance, g as toPostgresSchema, i as SCHEMA_VERSION, j as toJsonlArtifact, k as sessionConflictRow, l as isPersistedEvent, m as postgresTableDefs, n as EPHEMERAL_EVENT_TYPES, o as eventDimensions, r as EVENT_ENCODING, t as DEFAULT_BUSY_TIMEOUT_MS, w as repairOrphanInboxSplices } from "./schema-vwzwEXNE.mjs";
-import { c as SessionBranchRdb, l as SessionBranchRdbProvider, s as registerSessionImport, u as locateTurnEnd } from "./import-DFed8DBt.mjs";
+import { a as SCHEMA_VERSION, g as WriteGuard, h as toPostgresSchema, i as EVENT_ENCODING, m as postgresTableDefs, r as DEFAULT_BUSY_TIMEOUT_MS, s as eventDimensions, t as SqliteBackend } from "./sqlite-DCy4VTD8.mjs";
+import { a as repairSurfaceOps, c as scanRows, d as toJsonlArtifact, i as repairOrphanInboxSplices, l as sessionConflictRow, r as recomputeReplaceProvenance, s as rowToMeta, u as sessionInsertRow } from "./log-DTJsxMud.mjs";
+import { c as SessionBranchRdbProvider, l as locateTurnEnd, o as registerSessionImport, s as SessionBranchRdb } from "./import-CKrzjXVB.mjs";
 import z from "@deepseek-ai/schemastery";
 import { randomUUID } from "node:crypto";
 import { Pool } from "pg";
 import { drizzle } from "drizzle-orm/node-postgres";
-import { PersistenceCoordinator, SessionPersistence, SessionPersistenceRevision } from "@deepseek-ai/dsh-session-persistence";
+import { SessionAlreadyExistsError, SessionAlreadyOwnedError, SessionHandleClosedError, SessionPersistence, SessionPersistenceNotFoundError, SessionPersistenceRevision, SessionReadOnlyError, assertContiguous, assertVersion, materializeAppendBatch, materializeCreateHeader, validateStoredEvents } from "@deepseek-ai/dsh-session-persistence";
 import { SessionLogOffset } from "@deepseek-ai/dsh-session";
-import { and, desc, eq, gte, sql } from "drizzle-orm";
+import { sessionFormatCatalog } from "@deepseek-ai/dsh-session-format-catalog";
+import { and, eq, gte, sql } from "drizzle-orm";
+import { readdirSync } from "node:fs";
+import { migrate } from "drizzle-orm/node-postgres/migrator";
 //#region src/postgres.ts
+/** drizzle-kit 生成的迁移目录（随包根 drizzle/ 发布；src/dist 形态经相对 URL 统一解析）。 */
+const postgresMigrationsDir = new URL("../drizzle/postgres/", import.meta.url).pathname;
 var PostgresBackend = class PostgresBackend {
 	db;
 	options;
@@ -21,45 +26,47 @@ var PostgresBackend = class PostgresBackend {
 		this.tables = toPostgresSchema(postgresTableDefs, this.options.schema ?? "public");
 	}
 	async open() {
+		const schema = this.options.schema ?? "public";
+		const qualifiedMeta = schema === "public" ? "t_schema_meta" : `"${schema}".t_schema_meta`;
+		if ((await this.db.execute(sql`SELECT to_regclass(${qualifiedMeta}) IS NOT NULL AS exists`)).rows[0]?.exists === true) {
+			if (await this.readMeta(this.db, "schema_version") === "2") await this.baselineV2();
+		}
+		await migrate(this.db, { migrationsFolder: postgresMigrationsDir });
 		const storeId = await this.db.transaction(async (tx) => {
-			const schema = this.options.schema ?? "public";
-			const qualifiedMeta = schema === "public" ? "t_schema_meta" : `"${schema}".t_schema_meta`;
-			const metaExists = (await tx.execute(sql`SELECT to_regclass(${qualifiedMeta}) IS NOT NULL AS exists`)).rows[0]?.exists === true;
-			for (const statement of createTablesSql("postgres", postgresTableDefs, schema)) await tx.execute(sql.raw(statement));
-			if (!metaExists) await tx.insert(this.tables["t_schema_meta"]).values([{
-				fKey: "schema_version",
-				fValue: String(2)
-			}, {
-				fKey: "application_id",
-				fValue: String(SESSION_PERSISTENCE_SQLITE_APPLICATION_ID)
-			}]).execute();
-			const version = await this.readMeta(tx, "schema_version");
-			const applicationId = await this.readMeta(tx, "application_id");
-			if (version === void 0 || applicationId === void 0) throw new Error("session database has an unversioned schema or application identity");
-			if (Number(version) !== 2) throw new Error(`session database has schema version ${version}, incompatible with this build (2)`);
-			if (Number(applicationId) !== 1146308688) throw new Error(`session database has application id ${applicationId}, expected ${SESSION_PERSISTENCE_SQLITE_APPLICATION_ID}`);
 			await tx.insert(this.tables["t_persistence_state"]).values({
 				fSingleton: 1,
 				fStoreId: randomUUID()
 			}).onConflictDoNothing().execute();
-			const storeId = (await tx.select({ fStoreId: this.tables["t_persistence_state"].fStoreId }).from(this.tables["t_persistence_state"]).where(eq(this.tables["t_persistence_state"].fSingleton, 1)).execute())[0]?.fStoreId;
-			if (storeId === void 0 || storeId.length === 0) throw new Error("session database has no valid store identity");
-			return storeId;
+			const id = (await tx.select({ fStoreId: this.tables["t_persistence_state"].fStoreId }).from(this.tables["t_persistence_state"]).where(eq(this.tables["t_persistence_state"].fSingleton, 1)).execute())[0]?.fStoreId;
+			if (id === void 0 || id.length === 0) throw new Error("session database has no valid store identity");
+			return id;
 		});
 		this.storeIdentity = `${this.options.identityBase}:store:${storeId}`;
 	}
+	/** 标记 v2 baseline 已应用（迁移表 v1 结构：id/hash/created_at/name/applied_at）。 */
+	async baselineV2() {
+		const dir = readdirSync(postgresMigrationsDir).find((name) => name.endsWith("_v2_initial"));
+		if (dir === void 0) throw new Error("missing v2 baseline migration in drizzle/postgres");
+		await this.db.execute(sql`
+      CREATE SCHEMA IF NOT EXISTS drizzle
+    `);
+		await this.db.execute(sql`
+      CREATE TABLE IF NOT EXISTS drizzle.__drizzle_migrations (
+        id SERIAL PRIMARY KEY,
+        hash text NOT NULL,
+        created_at bigint,
+        name text,
+        applied_at timestamp with time zone DEFAULT now()
+      )
+    `);
+		await this.db.execute(sql`INSERT INTO drizzle.__drizzle_migrations (hash, created_at, name) VALUES ('baseline', 0, ${dir})`);
+	}
 	async close() {
 		await this.options.close();
 	}
 	async getSession(id) {
 		return (await this.db.select().from(this.tables["t_sessions"]).where(eq(this.tables["t_sessions"].fSessionId, id)).execute())[0];
 	}
-	async getSeqMapRows(id) {
-		return this.db.select({
-			fSequence: this.tables["t_session_events"].fSequence,
-			fOriginalSeq: this.tables["t_session_events"].fOriginalSeq
-		}).from(this.tables["t_session_events"]).where(eq(this.tables["t_session_events"].fSessionId, id)).execute();
-	}
 	async getEventRows(id, fromSequence) {
 		return (fromSequence === void 0 ? this.eventRows(this.db).where(eq(this.tables["t_session_events"].fSessionId, id)) : this.eventRows(this.db).where(and(eq(this.tables["t_session_events"].fSessionId, id), gte(this.tables["t_session_events"].fSequence, fromSequence)))).orderBy(this.tables["t_session_events"].fSequence).execute();
 	}
@@ -80,8 +87,7 @@ var PostgresBackend = class PostgresBackend {
 			updateHead: (id, headEventId, headSequence) => this.updateHead(tx, id, headEventId, headSequence),
 			bumpRevision: (id) => this.bumpRevision(tx, id),
 			deleteBridgeTail: (id, fromSequence) => this.deleteBridgeTail(tx, id, fromSequence),
-			getPrevBridge: (id, sequence) => this.getPrevBridge(tx, id, sequence),
-			getLastBridge: (id) => this.getLastBridge(tx, id)
+			getPrevBridge: (id, sequence) => this.getPrevBridge(tx, id, sequence)
 		};
 	}
 	async readMeta(exec, key) {
@@ -138,17 +144,10 @@ var PostgresBackend = class PostgresBackend {
 			fSequence: this.tables["t_session_events"].fSequence
 		}).from(this.tables["t_session_events"]).where(and(eq(this.tables["t_session_events"].fSessionId, id), eq(this.tables["t_session_events"].fSequence, sequence))).execute())[0];
 	}
-	async getLastBridge(exec, id) {
-		return (await exec.select({
-			fEventId: this.tables["t_session_events"].fEventId,
-			fSequence: this.tables["t_session_events"].fSequence
-		}).from(this.tables["t_session_events"]).where(eq(this.tables["t_session_events"].fSessionId, id)).orderBy(desc(this.tables["t_session_events"].fSequence)).limit(1).execute())[0];
-	}
 	eventRows(exec) {
 		return exec.select({
 			fEventId: this.tables["t_session_events"].fEventId,
 			fSequence: this.tables["t_session_events"].fSequence,
-			fOriginalSeq: this.tables["t_session_events"].fOriginalSeq,
 			fType: this.tables["t_events"].fType,
 			fKind: this.tables["t_events"].fKind,
 			fRole: this.tables["t_events"].fRole,
@@ -161,7 +160,315 @@ var PostgresBackend = class PostgresBackend {
 	}
 };
 //#endregion
+//#region src/legacy.ts
+/** 重建 v0/v1 物理 header 记录（RDB 行 → 物理 JSON 对象）。 */
+function physicalHeader(row) {
+	return {
+		type: "session",
+		version: row.fVersion,
+		id: row.fSessionId,
+		createdAt: row.fCreatedAt,
+		...row.fCwd !== null ? { cwd: row.fCwd } : {},
+		...row.fParentSession !== null ? { parentSession: row.fParentSession } : {},
+		...row.fSeedLength !== null ? { seedLength: row.fSeedLength } : {},
+		...row.fOrigin !== null ? { origin: row.fOrigin } : {},
+		delegationDepth: row.fDelegationDepth ?? 0
+	};
+}
+/** 重建一条 v0/v1 物理事件记录（桥接行 + 事件行 → 物理 JSON 对象）。 */
+function physicalEvent(row) {
+	return {
+		type: row.fType,
+		seq: row.fSequence,
+		time: row.fCreatedAt,
+		data: JSON.parse(row.fData),
+		...row.fSurfaceOp !== null ? { surfaceOp: JSON.parse(row.fSurfaceOp) } : {}
+	};
+}
+/**
+* 把旧格式（v0/v1）行转换为 v2 逻辑事件与 header。
+* @param row - 会话行（f_version < 2）。
+* @param eventRows - 已扫描保留的桥接行（稠密 seq，torn tail 已剔除）。
+* @returns v2 逻辑 header、继承前缀长度与事件。
+* @throws 迁移链拒绝（格式损坏 / 无法迁移）时原样抛出。
+*/
+function convertLegacyRows(row, eventRows) {
+	const restore = sessionFormatCatalog.createRestore(physicalHeader(row), {
+		recovery: "strict",
+		validation: "transformed"
+	});
+	for (const eventRow of eventRows) restore.decodeRow(physicalEvent(eventRow));
+	const artifact = restore.finish();
+	return {
+		meta: artifact.header,
+		inheritedEventCount: artifact.inheritedEventCount,
+		events: artifact.events
+	};
+}
+/** 会话行是否携带旧格式（v0/v1）数据。 */
+function isLegacyVersion(version) {
+	return version < 2;
+}
+//#endregion
 //#region src/index.ts
+/** 会话级写所有权与 live 路由簿记。 */
+var RdbBackendTracker = class {
+	name;
+	/** 每个 id 的活跃 write handle；`null` 表示 claim 构造中。 */
+	writers = /* @__PURE__ */ new Map();
+	pending = /* @__PURE__ */ new Map();
+	openHandles = /* @__PURE__ */ new Set();
+	counter = 0;
+	constructor(name) {
+		this.name = name;
+	}
+	registerCreated(header, inheritedEventCount) {
+		if (this.writers.has(header.id)) throw new SessionAlreadyExistsError(header.id);
+		this.writers.set(header.id, null);
+		this.pending.set(header.id, {
+			header,
+			revision: SessionPersistenceRevision(`memory:${this.name}:${++this.counter}`),
+			inheritedEventCount,
+			cursor: 0,
+			everAppended: false
+		});
+	}
+	/** 更新 pending 的 cursor / everAppended（handle append 后同步）。 */
+	updatePending(id, cursor, everAppended) {
+		const entry = this.pending.get(id);
+		if (entry === void 0) return;
+		this.pending.set(id, {
+			...entry,
+			cursor,
+			everAppended
+		});
+	}
+	claimWrite(id) {
+		if (this.writers.has(id)) throw new SessionAlreadyOwnedError(id);
+		this.writers.set(id, null);
+	}
+	releaseClaim(id) {
+		this.writers.delete(id);
+	}
+	pendingOf(id) {
+		return this.pending.get(id);
+	}
+	hasPending(id) {
+		return this.pending.has(id);
+	}
+	pendingEntries() {
+		return this.pending.entries();
+	}
+	materialized(id) {
+		this.pending.delete(id);
+	}
+	adopt(handle) {
+		this.openHandles.add(handle);
+		if (handle.access === "write") this.writers.set(handle.id, handle);
+		return handle;
+	}
+	release(handle, materialized) {
+		this.openHandles.delete(handle);
+		if (handle.access !== "write") return;
+		this.writers.delete(handle.id);
+		if (!materialized) this.pending.delete(handle.id);
+	}
+	writerOf(id) {
+		const writer = this.writers.get(id);
+		return writer === null ? void 0 : writer;
+	}
+	async flushAll() {
+		const errors = [];
+		for (const writer of this.writers.values()) {
+			if (writer === null) continue;
+			try {
+				await writer.drainLive();
+				await writer.flush();
+			} catch (error) {
+				if (error instanceof SessionHandleClosedError) continue;
+				errors.push(error);
+			}
+		}
+		if (errors.length > 0) throw new AggregateError(errors, `${this.name} flush failed`);
+	}
+	async closeAll() {
+		const errors = [];
+		for (const handle of this.openHandles) try {
+			await handle.close();
+		} catch (error) {
+			errors.push(error);
+		}
+		if (errors.length > 0) throw new AggregateError(errors, `${this.name} dispose failed`);
+	}
+};
+/** 一个打开会话的存储句柄：read / append / flush / close。 */
+var RdbSessionHandle = class RdbSessionHandle {
+	persistence;
+	id;
+	header;
+	access;
+	state;
+	chain = Promise.resolve();
+	closing;
+	/** 稠密 next-seq（输入空间计数，与旧版 coordinator cursor 同语义）。 */
+	cursor;
+	materialized;
+	/** live 路由缓冲（上游 seq 事件，drain 时过滤 delta 后重编号稠密）。 */
+	buffered = [];
+	batchTimer;
+	drainPaused = false;
+	draining;
+	/** write open 时发现的 torn tail 起点（append 前先截断）。 */
+	tornTruncateTo;
+	/** 是否调用过 append（即使全 delta 未落库）——close 时保留 pending。 */
+	everAppended = false;
+	constructor(persistence, id, header, access, state) {
+		this.persistence = persistence;
+		this.id = id;
+		this.header = header;
+		this.access = access;
+		this.state = state;
+		this.cursor = state.cursor;
+		this.materialized = state.materialized;
+		this.tornTruncateTo = state.tornTruncateTo;
+	}
+	get inheritedEventCount() {
+		return this.state.inheritedEventCount;
+	}
+	/** 输入空间 cursor（下一个待落库的上游 seq）。 */
+	get cursorValue() {
+		return this.cursor;
+	}
+	async read(offset = 0, length = Number.MAX_SAFE_INTEGER, options) {
+		this.assertOpen("read");
+		if (!Number.isSafeInteger(offset) || offset < 0) throw new TypeError(`read offset must be a non-negative safe integer, got ${String(offset)}`);
+		if (!Number.isSafeInteger(length) || length < 0) throw new TypeError(`read length must be a non-negative safe integer, got ${String(length)}`);
+		options?.signal?.throwIfAborted();
+		const log = await this.persistence.readLog(this.id, {}, options?.signal);
+		if (log === void 0) {
+			if (this.persistence.tracker.hasPending(this.id)) return {
+				eventState: "detached",
+				events: []
+			};
+			throw new SessionPersistenceNotFoundError(this.id);
+		}
+		repairSurfaceOps(log.events);
+		recomputeReplaceProvenance(log.events);
+		repairOrphanInboxSplices(log.events);
+		return {
+			eventState: "detached",
+			events: log.events.slice(offset, offset + length)
+		};
+	}
+	async append(events, options) {
+		this.assertOpen("append");
+		const batch = materializeAppendBatch(events);
+		return this.run("append", async () => {
+			options?.signal?.throwIfAborted();
+			if (this.access !== "write") throw new SessionReadOnlyError(this.id, "append");
+			if (batch.length === 0) return;
+			this.everAppended = true;
+			assertContiguous(this.id, batch, this.cursor);
+			await this.persistence.appendBatch(this.header, this.state.inheritedEventCount, batch, this.tornTruncateTo);
+			this.tornTruncateTo = void 0;
+			this.cursor += batch.length;
+			this.materialized = true;
+			this.persistence.tracker.updatePending(this.id, this.cursor, true);
+		});
+	}
+	async flush(options) {
+		return this.run("flush", async () => {
+			options?.signal?.throwIfAborted();
+			if (this.access !== "write") throw new SessionReadOnlyError(this.id, "flush");
+			if (this.materialized) return;
+			await this.persistence.materializeEmpty(this.header, this.state.inheritedEventCount);
+			this.materialized = true;
+		});
+	}
+	close() {
+		return this.closing ??= (async () => {
+			let drainFailure;
+			for (;;) {
+				try {
+					await this.drainLive();
+				} catch (error) {
+					drainFailure = error;
+					break;
+				}
+				await this.chain;
+				if (this.buffered.length === 0) break;
+			}
+			await this.chain;
+			const failures = [];
+			if (drainFailure !== void 0) failures.push(drainFailure instanceof Error ? drainFailure : new Error(JSON.stringify(drainFailure)));
+			this.persistence.tracker.release(this, this.materialized || this.everAppended);
+			if (failures.length > 1) throw new AggregateError(failures, `session "${this.id}": close failed to drain`);
+			if (failures[0] !== void 0) throw failures[0];
+		})();
+	}
+	[Symbol.asyncDispose]() {
+		return this.close();
+	}
+	/** live 路由：缓冲一个已发布事件（持久化自有副本），并启动批量窗口。 */
+	enqueueLive(event, reportBackgroundFailure) {
+		this.buffered.push(structuredClone(event));
+		if (this.batchTimer !== void 0 || this.drainPaused) return;
+		this.batchTimer = setTimeout(() => {
+			this.batchTimer = void 0;
+			this.drainLive().catch(reportBackgroundFailure);
+		}, RdbSessionHandle.LIVE_WRITE_BATCH_MAX_DELAY_MS);
+	}
+	/** rewind 截断后对齐 handle 的稠密 cursor 与继承前缀（DB 已截断）。 */
+	resetAfterRewind(cursor, inheritedEventCount) {
+		this.cursor = cursor;
+		if (inheritedEventCount !== void 0) this.state.inheritedEventCount = SessionLogOffset(inheritedEventCount);
+	}
+	/** 排空 live 缓冲（过滤 delta + 重编号稠密 + append）。 */
+	drainLive() {
+		return this.draining ??= this.drainBuffered().finally(() => {
+			this.draining = void 0;
+		});
+	}
+	async drainBuffered() {
+		if (this.batchTimer !== void 0) {
+			clearTimeout(this.batchTimer);
+			this.batchTimer = void 0;
+		}
+		this.drainPaused = false;
+		while (this.buffered.length > 0) await this.enqueueChain(async () => {
+			const batch = this.buffered.splice(0);
+			try {
+				const fresh = batch.filter((event) => event.seq >= this.cursor);
+				if (fresh.length === 0) return;
+				for (const [index, event] of fresh.entries()) if (event.seq !== this.cursor + index) throw new Error(`append seq mismatch for "${this.id}": expected ${this.cursor + index} at index ${index}, got ${event.seq}`);
+				await this.persistence.appendBatch(this.header, this.state.inheritedEventCount, fresh, this.tornTruncateTo);
+				this.tornTruncateTo = void 0;
+				this.cursor += fresh.length;
+				this.materialized = true;
+			} catch (error) {
+				this.buffered = batch.concat(this.buffered);
+				this.drainPaused = true;
+				throw error;
+			}
+		});
+	}
+	enqueueChain(op) {
+		const next = this.chain.then(op);
+		this.chain = next.catch(() => {});
+		return next;
+	}
+	async run(operation, op) {
+		this.assertOpen(operation);
+		return this.enqueueChain(async () => {
+			this.assertOpen(operation);
+			return op();
+		});
+	}
+	assertOpen(operation) {
+		if (this.closing !== void 0) throw new SessionHandleClosedError(this.id, operation);
+	}
+	static LIVE_WRITE_BATCH_MAX_DELAY_MS = 200;
+};
 var SessionPersistenceRdb = class SessionPersistenceRdb extends SessionPersistence {
 	config;
 	static inject = ["sessions", "settings"];
@@ -182,29 +489,15 @@ var SessionPersistenceRdb = class SessionPersistenceRdb extends SessionPersisten
 	})]);
 	static settingsNs = "session-rdb";
 	name = "session-rdb";
-	supportsRawArtifacts = true;
-	async readRaw(id, signal) {
-		signal?.throwIfAborted();
-		await this.ready;
-		signal?.throwIfAborted();
-		const log = await this.readLog(id, {}, signal);
-		if (log === void 0) return void 0;
-		repairSurfaceOps(log.events);
-		recomputeReplaceProvenance(log.events);
-		const inheritedEventCount = Math.min(log.inheritedEventCount, log.events.length);
-		return {
-			meta: log.meta,
-			inheritedEventCount: SessionLogOffset(inheritedEventCount),
-			filename: "session.jsonl",
-			content: toJsonlArtifact(log.meta, inheritedEventCount, log.events)
-		};
-	}
+	tracker = new RdbBackendTracker(this.name);
 	backend;
 	storeIdentity;
 	ready;
-	coordinator;
 	writeGuard = new WriteGuard();
 	reuseEventIds = /* @__PURE__ */ new Map();
+	/** live 路由：session/created 后 handle 就绪前的缓冲。 */
+	liveBuffers = /* @__PURE__ */ new Map();
+	liveReady = /* @__PURE__ */ new Map();
 	constructor(ctx, config, injectedBackend) {
 		let resolved = config;
 		const settings = ctx.reflect.get("settings");
@@ -220,7 +513,7 @@ var SessionPersistenceRdb = class SessionPersistenceRdb extends SessionPersisten
 		this.config = resolved;
 		this.backend = injectedBackend ?? createBackend(resolved);
 		this.ready = this.init();
-		this.coordinator = new PersistenceCoordinator(this.ctx, this);
+		this.installLiveRouting(ctx);
 		new SessionBranchRdb(this.ctx);
 		registerSessionImport(this.ctx, this);
 	}
@@ -228,103 +521,163 @@ var SessionPersistenceRdb = class SessionPersistenceRdb extends SessionPersisten
 		await this.backend.open();
 		this.storeIdentity = this.backend.storeIdentity;
 	}
-	locate(_meta) {}
-	create(meta, inheritedEventCount) {
-		return this.coordinator.create(meta, inheritedEventCount === void 0 ? void 0 : SessionLogOffset(inheritedEventCount));
-	}
-	append(id, events) {
-		return this.coordinator.append(id, events);
-	}
-	load(id) {
-		return this.coordinator.load(id);
-	}
-	inspect(id, signal) {
-		return this.coordinator.inspect(id, signal);
-	}
-	readFrom(id, fromSeq, signal) {
-		return this.coordinator.readFrom(id, fromSeq, signal);
+	async create(header, options) {
+		options?.signal?.throwIfAborted();
+		const snapshot = materializeCreateHeader(header);
+		if (snapshot.isSeeded && options?.inheritedEventCount === void 0) throw new TypeError("seeded session metadata requires an inherited event count");
+		const inheritedEventCount = SessionLogOffset(options?.inheritedEventCount ?? 0);
+		if (!snapshot.isSeeded && inheritedEventCount !== 0) throw new TypeError("unseeded session metadata inherited event count must be 0");
+		await this.ready;
+		options?.signal?.throwIfAborted();
+		if (this.tracker.hasPending(snapshot.id) || await this.backend.getSession(snapshot.id) !== void 0) throw new SessionAlreadyExistsError(snapshot.id);
+		this.tracker.registerCreated(snapshot, inheritedEventCount);
+		return this.tracker.adopt(new RdbSessionHandle(this, snapshot.id, snapshot, "write", {
+			cursor: 0,
+			materialized: false,
+			inheritedEventCount
+		}));
 	}
-	borrowSession(id, signal) {
-		return this.coordinator.borrowSession(id, signal);
+	async open(id, access, options) {
+		options?.signal?.throwIfAborted();
+		await this.ready;
+		options?.signal?.throwIfAborted();
+		const pending = this.tracker.pendingOf(id);
+		if (access === "read") {
+			if (pending !== void 0) return this.tracker.adopt(new RdbSessionHandle(this, id, pending.header, "read", {
+				cursor: 0,
+				materialized: false,
+				inheritedEventCount: pending.inheritedEventCount
+			}));
+			const log = await this.readLog(id, {}, options?.signal);
+			if (log === void 0) throw new SessionPersistenceNotFoundError(id);
+			validateStoredEvents(log.meta, log.events);
+			return this.tracker.adopt(new RdbSessionHandle(this, id, log.meta, "read", {
+				cursor: log.events.length,
+				materialized: true,
+				inheritedEventCount: SessionLogOffset(log.inheritedEventCount)
+			}));
+		}
+		this.tracker.claimWrite(id);
+		try {
+			if (pending !== void 0) return this.tracker.adopt(new RdbSessionHandle(this, id, pending.header, "write", {
+				cursor: pending.cursor,
+				materialized: false,
+				inheritedEventCount: pending.inheritedEventCount
+			}));
+			const log = await this.readLog(id, {}, options?.signal);
+			if (log === void 0) throw new SessionPersistenceNotFoundError(id);
+			validateStoredEvents(log.meta, log.events);
+			this.writeGuard.confirmHead(id, log.events.at(-1)?.seq ?? -1);
+			return this.tracker.adopt(new RdbSessionHandle(this, id, log.meta, "write", {
+				cursor: log.events.length,
+				materialized: true,
+				inheritedEventCount: SessionLogOffset(log.inheritedEventCount),
+				...log.tornFrom !== void 0 ? { tornTruncateTo: log.tornFrom } : {}
+			}));
+		} catch (error) {
+			this.tracker.releaseClaim(id);
+			throw error;
+		}
 	}
-	loadStored(id, signal) {
-		return this.readPrefix(id, signal);
+	flush() {
+		return this.tracker.flushAll();
 	}
-	async loadStoredFrom(id, fromSeq, signal) {
-		const log = await this.readLog(id, { fromSeq }, signal);
-		if (log === void 0) return void 0;
-		return {
-			meta: log.meta,
-			inheritedEventCount: SessionLogOffset(log.inheritedEventCount),
-			events: log.events
+	async stat(id, options) {
+		options?.signal?.throwIfAborted();
+		await this.ready;
+		options?.signal?.throwIfAborted();
+		const pending = this.tracker.pendingOf(id);
+		if (pending !== void 0) return {
+			header: pending.header,
+			revision: pending.revision
 		};
-	}
-	async readPrefix(id, signal) {
-		const log = await this.readLog(id, {}, signal);
-		if (log === void 0) {
-			this.writeGuard.confirmHead(id, -1);
-			return;
-		}
-		this.writeGuard.confirmHead(id, log.events.at(-1)?.seq ?? -1);
-		recomputeReplaceProvenance(log.events);
-		repairOrphanInboxSplices(log.events);
+		const row = await this.backend.getSession(id);
+		if (row === void 0) return void 0;
 		return {
-			meta: log.meta,
-			inheritedEventCount: SessionLogOffset(log.inheritedEventCount),
-			events: log.events,
-			revision: SessionPersistenceRevision(`${this.storeIdentity}:incarnation:${log.incarnation}:revision:${log.revision}`),
-			...log.tornFrom !== void 0 ? { tornMarker: log.tornFrom } : {}
+			header: rowToMeta(row),
+			revision: this.rowRevision(row)
 		};
 	}
-	async readStoredRevision(id, signal) {
+	async list(options) {
+		const signal = options?.signal;
+		const snapshots = [];
+		const listed = /* @__PURE__ */ new Set();
+		for (const [id, pending] of this.tracker.pendingEntries()) {
+			snapshots.push({
+				header: pending.header,
+				revision: pending.revision
+			});
+			listed.add(id);
+		}
 		signal?.throwIfAborted();
 		await this.ready;
 		signal?.throwIfAborted();
-		const row = await this.backend.getSession(id);
-		if (row === void 0) return void 0;
-		return SessionPersistenceRevision(`${this.storeIdentity}:incarnation:${row.fIncarnation}:revision:${row.fRevision}`);
+		const rows = await this.backend.listSessions();
+		signal?.throwIfAborted();
+		for (const row of rows) {
+			if (listed.has(row.fSessionId)) continue;
+			snapshots.push({
+				header: rowToMeta(row),
+				revision: this.rowRevision(row)
+			});
+		}
+		return snapshots;
 	}
-	async readLog(id, options = {}, signal) {
+	/** 导出 artifact（jsonl v2 文本），视图只读不落库。 */
+	async readRaw(id, signal) {
 		signal?.throwIfAborted();
 		await this.ready;
 		signal?.throwIfAborted();
-		const row = await this.backend.getSession(id);
-		if (row === void 0) return void 0;
-		const meta = rowToMeta(row);
-		let eventRows;
-		let seqMap;
-		if (options.fromSeq === void 0) {
-			eventRows = await this.backend.getEventRows(id);
-			seqMap = buildSeqMap(eventRows);
-		} else {
-			eventRows = await this.backend.getEventRows(id, options.fromSeq);
-			const seqRows = await this.backend.getSeqMapRows(id);
-			seqMap = buildSeqMap(seqRows);
-		}
-		signal?.throwIfAborted();
-		const { preserved, tornFrom } = scanRows(eventRows, options.fromSeq ?? 0, seqMap);
+		const log = await this.readLog(id, {}, signal);
+		if (log === void 0) return void 0;
+		repairSurfaceOps(log.events);
+		recomputeReplaceProvenance(log.events);
+		const inheritedEventCount = Math.min(log.inheritedEventCount, log.events.length);
 		return {
-			meta,
-			inheritedEventCount: row.fSeedLength ?? 0,
-			events: preserved,
-			incarnation: row.fIncarnation,
-			revision: row.fRevision,
-			...tornFrom !== void 0 ? { tornFrom } : {}
+			meta: log.meta,
+			inheritedEventCount,
+			filename: "session.jsonl",
+			content: toJsonlArtifact(log.meta, inheritedEventCount, log.events)
 		};
 	}
-	async appendBatch(storage, events, _isMaterialized) {
+	/** 空会话 materialize（flush 的持久化屏障）。 */
+	async materializeEmpty(meta, inheritedEventCount) {
 		await this.ready;
-		const persisted = events.filter(isPersistedEvent);
-		if (persisted.length === 0) return;
-		const meta = storage.meta;
+		await this.backend.transaction(async (tx) => {
+			await tx.upsertSession({
+				meta,
+				inheritedEventCount
+			}, randomUUID());
+			await tx.bumpRevision(meta.id);
+		});
+		this.tracker.materialized(meta.id);
+		this.writeGuard.confirmHead(meta.id, -1);
+	}
+	/** 原样 append 落库（handle 已校验 contiguity；torn tail 先截断）。
+	*  与上游 JSONL 一致：ignorable 事件原样存储，不做过滤。写路径校验 v2
+	*  形状（fail-closed）：未知类型（非 ignorable）与非法消息形状拒绝入库；
+	*  旧格式（v0/v1）数据只在读取时经 legacy 转换链动态转换，不落新库。 */
+	async appendBatch(meta, inheritedEventCount, events, tornTruncateTo) {
+		await this.ready;
+		if (events.length === 0) return false;
+		validateStoredEvents(meta, [...events]);
 		const reuse = this.reuseEventIds.get(meta.id);
 		if (reuse !== void 0) this.reuseEventIds.delete(meta.id);
 		let confirmedHead = -1;
 		await this.backend.transaction(async (tx) => {
-			await tx.upsertSession(storage, randomUUID());
+			if (tornTruncateTo !== void 0) {
+				await tx.deleteBridgeTail(meta.id, tornTruncateTo);
+				const prev = await tx.getPrevBridge(meta.id, tornTruncateTo - 1);
+				if (prev === void 0) await tx.updateHead(meta.id, "", -1);
+				else await tx.updateHead(meta.id, prev.fEventId, prev.fSequence);
+			}
+			await tx.upsertSession({
+				meta,
+				inheritedEventCount
+			}, randomUUID());
 			const head = await tx.getHead(meta.id);
 			this.writeGuard.assertNoConcurrentWriter(meta.id, head.fHeadSequence);
-			const { headEventId, headSequence } = await appendEventTail(tx, meta, persisted, {
+			const { headEventId, headSequence } = await appendEventTail(tx, meta, events, {
 				parentId: head.fHeadEventId,
 				nextSeq: head.fHeadSequence + 1
 			}, reuse);
@@ -333,51 +686,121 @@ var SessionPersistenceRdb = class SessionPersistenceRdb extends SessionPersisten
 			confirmedHead = headSequence;
 		});
 		this.writeGuard.confirmHead(meta.id, confirmedHead);
+		this.tracker.materialized(meta.id);
+		return true;
 	}
-	async commitRepair(storage, tornMarker, closers) {
-		await this.ready;
-		const meta = storage.meta;
-		const persistedClosers = closers.filter(isPersistedEvent);
-		if (tornMarker === void 0 && persistedClosers.length === 0) return;
-		await this.backend.transaction(async (tx) => {
-			if (tornMarker !== void 0) {
-				await tx.deleteBridgeTail(meta.id, tornMarker);
-				const prev = await tx.getPrevBridge(meta.id, tornMarker - 1);
-				if (prev === void 0) await tx.updateHead(meta.id, "", -1);
-				else await tx.updateHead(meta.id, prev.fEventId, prev.fSequence);
-			}
-			if (persistedClosers.length > 0) {
-				const last = await tx.getLastBridge(meta.id);
-				const { headEventId, headSequence } = await appendEventTail(tx, meta, persistedClosers, {
-					parentId: last?.fEventId ?? "",
-					nextSeq: (last?.fSequence ?? -1) + 1
-				});
-				await tx.updateHead(meta.id, headEventId, headSequence);
-			}
-			await tx.bumpRevision(meta.id);
-		});
-		const row = await this.backend.getSession(meta.id);
-		this.writeGuard.confirmHead(meta.id, row?.fHeadSequence ?? -1);
-	}
-	async list(signal) {
+	/** 读取一个会话的稠密 log（含 torn tail 检测，不含修复改写）。 */
+	async readLog(id, options = {}, signal) {
 		signal?.throwIfAborted();
 		await this.ready;
 		signal?.throwIfAborted();
-		const rows = await this.backend.listSessions();
+		const row = await this.backend.getSession(id);
+		if (row === void 0) return void 0;
+		const meta = rowToMeta(row);
+		const eventRows = options.fromSeq === void 0 ? await this.backend.getEventRows(id) : await this.backend.getEventRows(id, options.fromSeq);
 		signal?.throwIfAborted();
-		return rows.map(rowToMeta);
+		if (isLegacyVersion(row.fVersion)) {
+			const converted = convertLegacyRows(row, eventRows);
+			return {
+				meta: converted.meta,
+				inheritedEventCount: converted.inheritedEventCount,
+				events: converted.events,
+				incarnation: row.fIncarnation,
+				revision: row.fRevision
+			};
+		}
+		const { preserved, tornFrom } = scanRows(eventRows, options.fromSeq ?? 0);
+		return {
+			meta,
+			inheritedEventCount: row.fSeedLength ?? 0,
+			events: preserved,
+			incarnation: row.fIncarnation,
+			revision: row.fRevision,
+			...tornFrom !== void 0 ? { tornFrom } : {}
+		};
 	}
 	async listSnapshots(signal) {
 		signal?.throwIfAborted();
 		await this.ready;
 		signal?.throwIfAborted();
+		const snapshots = [];
+		const listed = /* @__PURE__ */ new Set();
+		for (const [id, pending] of this.tracker.pendingEntries()) {
+			snapshots.push({
+				header: pending.header,
+				revision: pending.revision,
+				inheritedEventCount: pending.inheritedEventCount
+			});
+			listed.add(id);
+		}
 		const rows = await this.backend.listSessions();
 		signal?.throwIfAborted();
-		return rows.map((row) => ({
-			header: rowToMeta(row),
-			revision: SessionPersistenceRevision(`${this.storeIdentity}:incarnation:${row.fIncarnation}:revision:${row.fRevision}`),
-			inheritedEventCount: row.fSeedLength ?? 0
-		}));
+		for (const row of rows) {
+			if (listed.has(row.fSessionId)) continue;
+			snapshots.push({
+				header: rowToMeta(row),
+				revision: this.rowRevision(row),
+				inheritedEventCount: row.fSeedLength ?? 0
+			});
+		}
+		return snapshots;
+	}
+	async readStoredRevision(id, signal) {
+		signal?.throwIfAborted();
+		await this.ready;
+		signal?.throwIfAborted();
+		const row = await this.backend.getSession(id);
+		if (row === void 0) return void 0;
+		return this.rowRevision(row);
+	}
+	/** 便捷：create + append + close（测试与导入路径共用）。 */
+	async createAndAppend(header, events, inheritedEventCount) {
+		const handle = await this.create(header, inheritedEventCount === void 0 ? void 0 : { inheritedEventCount: SessionLogOffset(inheritedEventCount) });
+		try {
+			if (events.length > 0) await handle.append(events);
+		} finally {
+			await handle.close();
+		}
+	}
+	/** 便捷：open(read) + read 全量 + close。 */
+	async load(id, signal) {
+		const handle = await this.open(id, "read", signal === void 0 ? void 0 : { signal });
+		try {
+			const { events } = await handle.read(0, void 0, signal === void 0 ? void 0 : { signal });
+			const row = await this.backend.getSession(id);
+			if (row === void 0) throw new SessionPersistenceNotFoundError(id);
+			if (isLegacyVersion(row.fVersion)) return {
+				meta: handle.header,
+				inheritedEventCount: handle.inheritedEventCount,
+				events
+			};
+			return {
+				meta: rowToMeta(row),
+				inheritedEventCount: SessionLogOffset(row.fSeedLength ?? 0),
+				events
+			};
+		} finally {
+			await handle.close();
+		}
+	}
+	/** 便捷：open(write) + append + close。 */
+	async append(id, events) {
+		const handle = await this.open(id, "write");
+		try {
+			await handle.append(events);
+		} finally {
+			await handle.close();
+		}
+	}
+	/** 便捷：readFrom（稠密后缀）。 */
+	async readFrom(id, fromSeq, signal) {
+		const log = await this.readLog(id, { fromSeq }, signal);
+		if (log === void 0) throw new SessionPersistenceNotFoundError(id);
+		return {
+			meta: log.meta,
+			inheritedEventCount: log.inheritedEventCount,
+			events: log.events
+		};
 	}
 	async close() {
 		await this.ready;
@@ -390,17 +813,116 @@ var SessionPersistenceRdb = class SessionPersistenceRdb extends SessionPersisten
 		return {
 			backend: this.backend,
 			writeGuard: this.writeGuard,
-			create: (meta, inheritedEventCount) => this.create(meta, inheritedEventCount),
+			create: (meta, inheritedEventCount) => this.create(meta, inheritedEventCount === void 0 ? void 0 : { inheritedEventCount: SessionLogOffset(inheritedEventCount) }),
 			append: (id, events) => this.append(id, events),
 			load: (id) => this.load(id),
-			inspect: (id, signal) => this.inspect(id, signal),
+			inspect: (id, signal) => this.load(id, signal),
 			readFrom: (id, fromSeq, signal) => this.readFrom(id, fromSeq, signal),
 			listSnapshots: (signal) => this.listSnapshots(signal),
 			readStoredRevision: (id, signal) => this.readStoredRevision(id, signal),
 			registerReuseEventIds: (childId, map) => this.registerReuseEventIds(childId, map)
 		};
 	}
+	rowRevision(row) {
+		return SessionPersistenceRevision(`${this.storeIdentity}:incarnation:${row.fIncarnation}:revision:${row.fRevision}`);
+	}
+	installLiveRouting(ctx) {
+		ctx.on("session/created", (session) => {
+			this.liveBuffers.set(session.id, []);
+			const ready = this.ensureLiveHandle(session);
+			this.liveReady.set(session.id, ready);
+			ready.catch((error) => {
+				ctx.logger.warn(`session-rdb: live session "${session.id}" persistence init failed: ${String(error)}`);
+			});
+		});
+		for (const session of ctx.sessions.list()) {
+			this.liveBuffers.set(session.id, []);
+			const ready = this.ensureLiveHandle(session);
+			this.liveReady.set(session.id, ready);
+			ready.catch((error) => {
+				ctx.logger.warn(`session-rdb: live session "${session.id}" persistence init failed: ${String(error)}`);
+			});
+		}
+		ctx.on("session/event", (session, event) => {
+			const handle = this.tracker.writerOf(session.id);
+			if (handle !== void 0) {
+				handle.enqueueLive(event, (error) => {
+					ctx.logger.warn(`session-rdb: background write for session "${session.id}" failed (buffered events retained): ${String(error)}`);
+				});
+				return;
+			}
+			this.liveBuffers.get(session.id)?.push(structuredClone(event));
+		});
+		ctx.on("session/flush", (session) => {
+			const handle = this.tracker.writerOf(session.id);
+			if (handle === void 0) {
+				const ready = this.liveReady.get(session.id);
+				if (ready === void 0) return void 0;
+				return ready.then(() => {
+					const settled = this.tracker.writerOf(session.id);
+					if (settled === void 0) return void 0;
+					return settled.drainLive().then(() => settled.flush());
+				});
+			}
+			return handle.drainLive().then(() => handle.flush());
+		});
+		ctx.on("session/disposed", (session) => {
+			const ready = this.liveReady.get(session.id);
+			this.liveBuffers.delete(session.id);
+			this.liveReady.delete(session.id);
+			const closeHandle = () => {
+				const handle = this.tracker.writerOf(session.id);
+				if (handle === void 0) return;
+				handle.close().catch((error) => {
+					ctx.logger.warn(`session-rdb: final drain for session "${session.id}" failed: ${String(error)}`);
+				});
+			};
+			if (ready === void 0) {
+				closeHandle();
+				return;
+			}
+			ready.then(closeHandle, closeHandle);
+		});
+		ctx.effect(() => async () => {
+			await Promise.allSettled(this.liveReady.values());
+			await this.tracker.closeAll();
+			await this.close();
+		}, `${this.name} open handles`);
+	}
+	/** session/created 后为 live 会话建立 write handle（create 或 adopt）。 */
+	async ensureLiveHandle(session) {
+		const id = session.header.id;
+		if (this.tracker.writerOf(id) !== void 0) return;
+		await this.ready;
+		const stored = await this.readLog(id, {});
+		let handle;
+		if (stored === void 0) {
+			handle = await this.create(session.header, { inheritedEventCount: session.inheritedEventCount });
+			const seed = session.snapshotEvents();
+			if (seed.length > 0) await handle.append(seed);
+		} else {
+			if (stored.meta.cwd !== session.header.cwd) throw new Error(`session "${id}" is already persisted at a different cwd (persisted: ${String(stored.meta.cwd)}, live: ${String(session.header.cwd)}) (id collision)`);
+			if (stored.inheritedEventCount !== session.inheritedEventCount) throw new Error(`session "${id}" is already persisted with a different inherited event count (id collision)`);
+			assertVersion(stored.meta);
+			const seed = session.snapshotEvents();
+			if (!seedCoversPrefix(seed, stored.events)) throw new Error(`session "${id}" already has a persisted log on disk that does not match this live session (id collision)`);
+			handle = await this.open(id, "write");
+			const suffix = seed.slice(stored.events.length);
+			if (suffix.length > 0) await handle.append(suffix);
+		}
+		const buffered = this.liveBuffers.get(id);
+		if (buffered !== void 0 && buffered.length > 0) {
+			this.liveBuffers.set(id, []);
+			for (const event of buffered) handle.enqueueLive(event, () => {});
+		}
+	}
 };
+function seedCoversPrefix(seed, prefix) {
+	return prefix.length <= seed.length && prefix.every((event, index) => {
+		const seedEvent = seed[index];
+		return seedEvent !== void 0 && JSON.stringify(seedEvent) === JSON.stringify(event);
+	});
+}
 function createBackend(config) {
 	if (config.type === "sqlite") return new SqliteBackend({
 		path: config.path,
@@ -431,6 +953,7 @@ async function appendEventTail(tx, meta, events, anchor, reuse) {
 		const eventId = reusedId ?? randomUUID();
 		if (reusedId === void 0) {
 			const { kind, role, name, actionId } = eventDimensions(event);
+			const { data, surfaceOp: _surfaceOp, sourceEventSeqs: _sourceEventSeqs, ...envelope } = event;
 			eventRows.push({
 				fEventId: eventId,
 				fParentId: parentId,
@@ -440,7 +963,10 @@ async function appendEventTail(tx, meta, events, anchor, reuse) {
 				fName: name,
 				fActionId: actionId,
 				fEncoding: EVENT_ENCODING,
-				fData: JSON.stringify(event.data),
+				fData: JSON.stringify({
+					...envelope,
+					data
+				}),
 				fCreatedAt: event.time
 			});
 		}
@@ -449,7 +975,6 @@ async function appendEventTail(tx, meta, events, anchor, reuse) {
 			fSessionId: meta.id,
 			fEventId: eventId,
 			fSequence: nextSeq,
-			fOriginalSeq: event.seq,
 			fSurfaceOp: surfaceOp
 		});
 		parentId = eventId;
@@ -463,4 +988,4 @@ async function appendEventTail(tx, meta, events, anchor, reuse) {
 	};
 }
 //#endregion
-export { EPHEMERAL_EVENT_TYPES, SCHEMA_VERSION, SessionBranchRdb, SessionBranchRdbProvider, SessionPersistenceRdb, SessionPersistenceRdb as default, locateTurnEnd };
+export { SCHEMA_VERSION, SessionBranchRdb, SessionBranchRdbProvider, SessionPersistenceRdb, SessionPersistenceRdb as default, locateTurnEnd };