@morlay/session-rdb 0.1.10-alpha.0 → 0.1.10-alpha.2

package/dist/index.mjs

@@ -1,5 +1,1562 @@
-import { a as SESSION_ROWS_PATH } from "./routes-hZjTcX_R.mjs";
-import { i as locateTurnEnd, n as SessionBranchRdbProvider, r as liveEventsOf, t as SessionBranchRdb } from "./branch-CoPCRKer.mjs";
-import { o as SCHEMA_VERSION } from "./sqlite-BNRd1aqR.mjs";
-import { n as SessionDeletionError, r as SessionPersistenceRdb } from "./deletion-CWl89TIR.mjs";
+import { a as rowToMeta, r as toJsonlArtifact, t as scanRows } from "./export-CfJQjQfr.mjs";
+import { C as sealOwnEvents, b as repairReadView, c as convertLegacyRows, l as isLegacyVersion, n as SessionBranchRdbProvider, o as locateTurnEnd, p as needsShapeAdoption, r as liveEventsOf, s as adoptLegacyRows, t as SessionBranchRdb } from "./branch-CG1PUlO6.mjs";
+import { c as SESSION_ROWS_PATH, n as mountJsonRoute } from "./route-DpfY0zq-.mjs";
+import { COUNTED_EVENT_TYPES, addActivityCount, localDayKey, registerSessionUsage } from "./usage.mjs";
+import { t as usageRowOf } from "./usage-row-BQQM-_t6.mjs";
+import { registerSessionImport } from "./import.mjs";
+import { n as SessionDeletionError, t as registerSessionDeletion } from "./deletion-SSX7IqU8.mjs";
+import { registerSessionExport } from "./export.mjs";
+import { registerSessionOrganize } from "./organize.mjs";
+import { d as EVENT_ENCODING, f as SCHEMA_VERSION, u as DEFAULT_BUSY_TIMEOUT_MS } from "./backend-rdb-BDCntVDy.mjs";
+import { n as eventDimensions, t as WriteGuard } from "./write-guard-CYrY58GM.mjs";
+import { t as openRdbBackend } from "./open-YoyD_kah.mjs";
+import { SESSION_FORMAT_VERSION, SessionLogOffset } from "@deepseek-ai/dsh-session";
+import { randomUUID } from "node:crypto";
+import { sessionFormatLogFilename } from "@deepseek-ai/dsh-session-format";
+import { balanceRewindPrefix } from "@morlay/session-branch";
+import { SessionAlreadyExistsError, SessionAlreadyOwnedError, SessionHandleClosedError, SessionPersistence, SessionPersistenceNotFoundError, SessionPersistenceRevision, SessionReadOnlyError, assertContiguous, assertVersion, materializeAppendBatch, materializeCreateHeader, validateStoredEvents } from "@deepseek-ai/dsh-session-persistence";
+import { Service } from "@deepseek-ai/cordis";
+import z from "@deepseek-ai/schemastery";
+import { SessionQueryEngine, SessionQueryError } from "@deepseek-ai/dsh-session-query";
+import { StorageError, storageBackendServiceKey } from "@deepseek-ai/dsh-storage";
+// src/handles.ts
+var RdbBackendTracker = class {
+	name;
+	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
+		});
+	}
+	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;
+	}
+	hasOpenHandle(id) {
+		for (const handle of this.openHandles) if (handle.id === id) return true;
+		return false;
+	}
+	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`);
+	}
+};
+var RdbSessionHandle = class RdbSessionHandle {
+	persistence;
+	id;
+	header;
+	access;
+	state;
+	chain = Promise.resolve();
+	closing;
+	cursor;
+	materialized;
+	buffered = [];
+	batchTimer;
+	drainPaused = false;
+	draining;
+	tornTruncateTo;
+	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;
+	}
+	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);
+		}
+		repairReadView(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();
+	}
+	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);
+	}
+	resetAfterRewind(cursor, inheritedEventCount) {
+		this.cursor = cursor;
+		if (inheritedEventCount !== void 0) this.state.inheritedEventCount = SessionLogOffset(inheritedEventCount);
+	}
+	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;
+};
+// src/live-routing.ts
+var LiveRouting = class {
+	ctx;
+	persistence;
+	buffers = /* @__PURE__ */ new Map();
+	ready = /* @__PURE__ */ new Map();
+	failures = /* @__PURE__ */ new Map();
+	dropWarned = /* @__PURE__ */ new Set();
+	constructor(ctx, persistence) {
+		this.ctx = ctx;
+		this.persistence = persistence;
+	}
+	/** 丢掉一个会话的所有 live 记账（删除会话、孤儿会话回收时）。 */
+	forget(id) {
+		this.buffers.delete(id);
+		this.ready.delete(id);
+		this.failures.delete(id);
+		this.dropWarned.delete(id);
+	}
+	install() {
+		const ctx = this.ctx;
+		ctx.on("session/created", (session) => {
+			this.buffers.set(session.id, []);
+			const ready = this.ensureHandle(session);
+			this.ready.set(session.id, ready);
+			this.watchReady(session, ready);
+		});
+		for (const session of ctx.sessions.list()) {
+			this.buffers.set(session.id, []);
+			const ready = this.ensureHandle(session);
+			this.ready.set(session.id, ready);
+			this.watchReady(session, ready);
+		}
+		ctx.on("session/event", (session, event) => {
+			const handle = this.persistence.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;
+			}
+			if (this.failures.has(session.id)) {
+				if (!this.dropWarned.has(session.id)) {
+					this.dropWarned.add(session.id);
+					ctx.logger.warn(`session-rdb: dropping events for live session "${session.id}" because persistence failed earlier`);
+				}
+				return;
+			}
+			this.buffers.get(session.id)?.push(structuredClone(event));
+		});
+		ctx.on("session/flush", (session) => {
+			const failure = this.failures.get(session.id);
+			if (failure !== void 0) return Promise.reject(failure);
+			const handle = this.persistence.tracker.writerOf(session.id);
+			if (handle === void 0) {
+				const ready = this.ready.get(session.id);
+				if (ready === void 0) return void 0;
+				return ready.then(() => {
+					const settled = this.persistence.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.ready.get(session.id);
+			this.forget(session.id);
+			const closeHandle = () => {
+				const handle = this.persistence.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.ready.values());
+			this.buffers.clear();
+			this.ready.clear();
+			this.failures.clear();
+			this.dropWarned.clear();
+			await this.persistence.tracker.closeAll();
+			await this.persistence.close();
+		}, `${this.persistence.name} open handles`);
+	}
+	watchReady(session, ready) {
+		ready.catch((error) => {
+			const failure = error instanceof Error ? error : new Error(typeof error === "string" ? error : `live session "${session.id}" persistence failed`);
+			this.failures.set(session.id, failure);
+			this.buffers.delete(session.id);
+			this.ctx.logger.error(`session-rdb: live session "${session.id}" persistence unavailable (${failure.message}); its events will not be persisted`);
+		});
+	}
+	async ensureHandle(session) {
+		const persistence = this.persistence;
+		const id = session.header.id;
+		if (persistence.tracker.writerOf(id) !== void 0) return;
+		await persistence.ready;
+		const stored = await persistence.readLog(id, {});
+		let handle;
+		if (stored === void 0) {
+			handle = await persistence.create(session.header, { inheritedEventCount: session.inheritedEventCount });
+			const seed = liveEventsOf(session);
+			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);
+			repairReadView(stored.events);
+			const seed = liveEventsOf(session);
+			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 persistence.open(id, "write");
+			const suffix = seed.slice(stored.events.length);
+			if (suffix.length > 0) await handle.append(suffix);
+		}
+		const buffered = this.buffers.get(id);
+		if (buffered !== void 0 && buffered.length > 0) {
+			this.buffers.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);
+	});
+}
+// src/read-path.ts
+/**
+* 读侧：会话日志、原始导出、快照列表与已存储 revision。
+*
+* 这些只读 `backend.reads`，不碰写事务；`session-store.ts` 的契约方法（`load` / `open` / `readFrom`）把调用转到这里。
+*/
+function createReadPath(deps) {
+	return {
+		async readLog(id, options = {}, signal) {
+			signal?.throwIfAborted();
+			await deps.ready;
+			signal?.throwIfAborted();
+			const row = await deps.backend().reads.getSession(id);
+			if (row === void 0) return void 0;
+			const meta = rowToMeta(row);
+			const eventRows = options.fromSeq === void 0 ? await deps.backend().reads.getEventRows(id) : await deps.backend().reads.getEventRows(id, options.fromSeq);
+			signal?.throwIfAborted();
+			if (isLegacyVersion(row.fVersion)) try {
+				const converted = convertLegacyRows(row, eventRows);
+				return {
+					meta: converted.meta,
+					inheritedEventCount: converted.inheritedEventCount,
+					events: converted.events,
+					incarnation: row.fIncarnation,
+					revision: row.fRevision,
+					storedCount: eventRows.length,
+					migrated: true
+				};
+			} catch (error) {
+				deps.logger.warn(`session-rdb: session "${id}" is not a single released format; adopting its stored rows as current-format data (${error instanceof Error ? error.message : String(error)})`);
+				const adopted = adoptLegacyRows(row, eventRows);
+				return {
+					meta: adopted.meta,
+					inheritedEventCount: adopted.inheritedEventCount,
+					events: adopted.events,
+					incarnation: row.fIncarnation,
+					revision: row.fRevision,
+					storedCount: eventRows.length,
+					migrated: false,
+					...adopted.tornFrom !== void 0 ? { tornFrom: adopted.tornFrom } : {}
+				};
+			}
+			const { preserved, tornFrom } = scanRows(eventRows, options.fromSeq ?? 0);
+			if (needsShapeAdoption(preserved)) {
+				const adopted = adoptLegacyRows(row, eventRows);
+				return {
+					meta: adopted.meta,
+					inheritedEventCount: adopted.inheritedEventCount,
+					events: adopted.events,
+					incarnation: row.fIncarnation,
+					revision: row.fRevision,
+					storedCount: eventRows.length,
+					migrated: false,
+					...adopted.tornFrom !== void 0 ? { tornFrom: adopted.tornFrom } : {}
+				};
+			}
+			return {
+				meta,
+				inheritedEventCount: row.fSeedLength ?? 0,
+				events: preserved,
+				incarnation: row.fIncarnation,
+				revision: row.fRevision,
+				storedCount: eventRows.length,
+				migrated: false,
+				...tornFrom !== void 0 ? { tornFrom } : {}
+			};
+		},
+		async readRaw(id, signal) {
+			signal?.throwIfAborted();
+			await deps.ready;
+			signal?.throwIfAborted();
+			const log = await this.readLog(id, {}, signal);
+			if (log === void 0) return void 0;
+			repairReadView(log.events);
+			const events = balanceRewindPrefix(log.events, { keepOpenTail: true });
+			const inheritedEventCount = Math.min(log.inheritedEventCount, events.length);
+			return {
+				meta: log.meta,
+				inheritedEventCount,
+				filename: sessionFormatLogFilename(SESSION_FORMAT_VERSION),
+				content: toJsonlArtifact(log.meta, inheritedEventCount, events)
+			};
+		},
+		async listSnapshots(signal) {
+			signal?.throwIfAborted();
+			await deps.ready;
+			signal?.throwIfAborted();
+			const snapshots = [];
+			const listed = /* @__PURE__ */ new Set();
+			for (const [id, pending] of deps.tracker.pendingEntries()) {
+				snapshots.push({
+					header: pending.header,
+					revision: pending.revision,
+					inheritedEventCount: pending.inheritedEventCount
+				});
+				listed.add(id);
+			}
+			const rows = await deps.backend().reads.listSessions();
+			signal?.throwIfAborted();
+			for (const row of rows) {
+				if (listed.has(row.fSessionId)) continue;
+				snapshots.push({
+					header: rowToMeta(row),
+					revision: deps.revisionOf(row),
+					inheritedEventCount: row.fSeedLength ?? 0
+				});
+			}
+			return snapshots;
+		},
+		async readStoredRevision(id, signal) {
+			signal?.throwIfAborted();
+			await deps.ready;
+			signal?.throwIfAborted();
+			const row = await deps.backend().reads.getSession(id);
+			if (row === void 0) return void 0;
+			return deps.revisionOf(row);
+		}
+	};
+}
+// src/stats-fold.ts
+function sessionCountBuckets(events) {
+	const counted = /* @__PURE__ */ new Map();
+	for (const event of events) {
+		if (!COUNTED_EVENT_TYPES.includes(event.type)) continue;
+		const day = localDayKey(event.time);
+		const bucket = counted.get(day) ?? {
+			day,
+			turns: 0,
+			steps: 0,
+			userInputs: 0,
+			toolCalls: 0
+		};
+		addActivityCount(bucket, event.type, 1);
+		counted.set(day, bucket);
+	}
+	return [...counted.values()];
+}
+function sessionUsageBuckets(usageRows) {
+	const counted = /* @__PURE__ */ new Map();
+	for (const row of usageRows) {
+		const provider = row.fProvider ?? "";
+		const model = row.fModel ?? "";
+		const key = `${row.fDay}#${provider}#${model}`;
+		const bucket = counted.get(key) ?? {
+			day: row.fDay,
+			provider,
+			model,
+			inputTokens: 0,
+			outputTokens: 0,
+			cacheReadTokens: 0,
+			reasoningTokens: 0,
+			totalTokens: 0
+		};
+		bucket.inputTokens += row.fInputTokens;
+		bucket.outputTokens += row.fOutputTokens;
+		bucket.cacheReadTokens += row.fCacheReadTokens;
+		bucket.reasoningTokens += row.fReasoningTokens;
+		bucket.totalTokens += row.fTotalTokens;
+		counted.set(key, bucket);
+	}
+	return [...counted.values()];
+}
+// src/write-path.ts
+function maxEventTime(events) {
+	let max;
+	for (const event of events) {
+		const time = event.time;
+		if (typeof time !== "number") continue;
+		if (max === void 0 || time > max) max = time;
+	}
+	return max;
+}
+function describeError(error) {
+	return error instanceof Error ? error.message : "unknown error";
+}
+/**
+* 写侧：空会话物化、批量追加、统计旁路累加与重算、迁移后重写。
+*
+* 事务边界都在这里；`session-store.ts` 只负责装配与契约转发。
+*/
+function createWritePath(deps) {
+	return {
+		async materializeEmpty(meta, inheritedEventCount) {
+			await deps.ready;
+			await deps.backend().transaction(async (tx) => {
+				await tx.upsertSession({
+					meta,
+					inheritedEventCount
+				}, randomUUID());
+				await tx.bumpRevision(meta.id);
+			});
+			deps.tracker.materialized(meta.id);
+			deps.writeGuard.confirmHead(meta.id, -1);
+		},
+		async appendBatch(meta, inheritedEventCount, events, tornTruncateTo) {
+			await deps.ready;
+			if (events.length === 0) return false;
+			sealOwnEvents(events);
+			validateStoredEvents(meta, [...events]);
+			const reuse = deps.reuseEventIds.get(meta.id);
+			let confirmedHead = -1;
+			let usageRows = [];
+			await deps.backend().transaction(async (tx) => {
+				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);
+				deps.writeGuard.assertNoConcurrentWriter(meta.id, head.fHeadSequence);
+				const appended = await appendEventTail(tx, meta, events, {
+					parentId: head.fHeadEventId,
+					nextSeq: head.fHeadSequence + 1
+				}, reuse);
+				usageRows = appended.usageRows;
+				await tx.updateHeadAndRevision(meta.id, appended.headEventId, appended.headSequence, maxEventTime(events));
+				confirmedHead = appended.headSequence;
+			});
+			if (reuse !== void 0) deps.reuseEventIds.delete(meta.id);
+			deps.writeGuard.confirmHead(meta.id, confirmedHead);
+			deps.tracker.materialized(meta.id);
+			await this.recordSessionStats(meta.id, events, usageRows);
+			return true;
+		},
+		async recordSessionStats(id, events, usageRows) {
+			const usageBuckets = sessionUsageBuckets(usageRows);
+			if (usageBuckets.length > 0) try {
+				await deps.backend().incrementSessionUsage(id, usageBuckets);
+			} catch (error) {
+				deps.logger.warn(`session-rdb: token usage for "${id}" not updated (${describeError(error)})`);
+			}
+			const countBuckets = sessionCountBuckets(events);
+			if (countBuckets.length > 0) try {
+				await deps.backend().incrementSessionCounts(id, countBuckets);
+			} catch (error) {
+				deps.logger.warn(`session-rdb: activity counts for "${id}" not updated (${describeError(error)})`);
+			}
+		},
+		async rebuildSessionStats(id) {
+			await deps.ready;
+			try {
+				await deps.backend().rebuildSessionStats(id);
+			} catch (error) {
+				deps.logger.warn(`session-rdb: session stats for "${id}" not rebuilt (${describeError(error)})`);
+			}
+		},
+		async refreshEventUsageFlags(eventIds) {
+			const unique = [...new Set(eventIds)];
+			if (unique.length === 0) return;
+			try {
+				await deps.backend().refreshEventUsageFlags(unique);
+			} catch (error) {
+				deps.logger.warn(`session-rdb: usage reference flags not refreshed (${describeError(error)})`);
+			}
+		},
+		async dropSessionStats(id) {
+			try {
+				await deps.backend().deleteSessionStats(id);
+			} catch (error) {
+				deps.logger.warn(`session-rdb: session stats for "${id}" not deleted (${describeError(error)})`);
+			}
+		},
+		async rewriteMigratedLog(id, log) {
+			let removed = [];
+			await deps.backend().transaction(async (tx) => {
+				const head = await tx.getHead(id);
+				if (!deps.writeGuard.has(id)) deps.writeGuard.confirmHead(id, head.fHeadSequence);
+				deps.writeGuard.assertNoConcurrentWriter(id, head.fHeadSequence);
+				removed = await tx.deleteBridgeTail(id, 0);
+				await tx.upsertSession({
+					meta: log.meta,
+					inheritedEventCount: SessionLogOffset(log.inheritedEventCount)
+				}, randomUUID());
+				const appended = await appendEventTail(tx, log.meta, log.events, {
+					parentId: "",
+					nextSeq: 0
+				});
+				await tx.updateHead(id, appended.headEventId, appended.headSequence);
+				await tx.bumpRevision(id, maxEventTime(log.events));
+			});
+			await this.rebuildSessionStats(id);
+			await this.refreshEventUsageFlags(removed);
+		}
+	};
+}
+async function appendEventTail(tx, meta, events, anchor, reuse) {
+	let parentId = anchor.parentId;
+	let nextSeq = anchor.nextSeq;
+	const eventRows = [];
+	const usageRows = [];
+	const bridgeRows = [];
+	for (const event of events) {
+		const reusedId = reuse?.get(event.seq);
+		const eventId = reusedId ?? randomUUID();
+		if (reusedId === void 0) {
+			const { kind, role, name, actionId } = eventDimensions(event);
+			const { data, surfaceOp: _surfaceOp, sourceEventSeqs: _sourceEventSeqs, ...envelope } = event;
+			const row = {
+				fEventId: eventId,
+				fParentId: parentId,
+				fType: event.type,
+				fKind: kind,
+				fRole: role,
+				fName: name,
+				fActionId: actionId,
+				fEncoding: EVENT_ENCODING,
+				fData: JSON.stringify({
+					...envelope,
+					data
+				}),
+				fCreatedAt: event.time
+			};
+			eventRows.push(row);
+			const usageRow = usageRowOf(row, meta.origin === "subagent");
+			if (usageRow !== void 0) usageRows.push(usageRow);
+		}
+		const surfaceOp = event.surfaceOp === void 0 ? null : JSON.stringify(event.surfaceOp);
+		bridgeRows.push({
+			fSessionId: meta.id,
+			fEventId: eventId,
+			fSequence: nextSeq,
+			fSurfaceOp: surfaceOp
+		});
+		parentId = eventId;
+		nextSeq++;
+	}
+	if (eventRows.length > 0) await tx.insertEvents(eventRows, usageRows);
+	await tx.insertBridges(bridgeRows);
+	if (events.some((event) => event.type === "session/title")) await tx.refreshTitle(meta.id);
+	return {
+		headEventId: parentId,
+		headSequence: nextSeq - 1,
+		usageRows
+	};
+}
+// src/rows.ts
+const MAX_PAGE_SIZE = 200;
+const DEFAULT_PAGE_SIZE = 20;
+function registerSessionRows(ctx, getBackend) {
+	mountJsonRoute(ctx, {
+		path: SESSION_ROWS_PATH,
+		handle: async (body) => {
+			const envelope = body;
+			const page = Number.isSafeInteger(envelope.page) && (envelope.page ?? 0) > 0 ? envelope.page : 1;
+			const requested = envelope.pageSize;
+			const pageSize = Number.isSafeInteger(requested) && (requested ?? 0) > 0 ? Math.min(requested, MAX_PAGE_SIZE) : DEFAULT_PAGE_SIZE;
+			const { items, total } = await (await getBackend()).listSessionRows({
+				...envelope.query === void 0 ? {} : { query: envelope.query },
+				...envelope.includeSubagents === void 0 ? {} : { includeSubagents: envelope.includeSubagents },
+				limit: pageSize,
+				offset: (page - 1) * pageSize
+			});
+			return { body: {
+				items,
+				total,
+				page,
+				pageSize
+			} };
+		},
+		statusOfError: () => void 0
+	});
+}
+// src/session-query.ts
+var SessionQueryRdb = class extends SessionQueryEngine {
+	/**
+	* 本次装配用的冷会话观察缓存容量（由 `session-rdb` 行的 `preparedSessionCacheSize` 透传；undefined 表示沿用
+	* 上游默认）。它是**按条目数**持有完整 Session 的缓存：条目多一条就多一份完整 append-only log 驻留。
+	*/
+	preparedSessionCacheSize;
+	constructor(ctx, config = {}) {
+		super(ctx, config);
+		this.preparedSessionCacheSize = config.preparedSessionCacheSize;
+	}
+	async listSessions(signal) {
+		const records = await super.listSessions(signal);
+		const archived = await this.archivedSessionIds();
+		if (archived.size === 0) return records;
+		return records.filter((record) => !archived.has(String(record.header.id)));
+	}
+	async archivedSessionIds() {
+		const registry = this.ctx.get("workspaceRegistry");
+		if (registry !== void 0) return new Set(registry.archivedSessionIds ?? []);
+		return await this.ctx.get("sessionPersistence")?.archivedSessionIds?.() ?? /* @__PURE__ */ new Set();
+	}
+	async searchSessions() {
+		throw searchDisabled();
+	}
+	async searchEvents() {
+		throw searchDisabled();
+	}
+};
+function searchDisabled() {
+	return new SessionQueryError("session search is disabled: this deployment serves session queries from the rdb backend without a full-text index", "SESSION_QUERY_SEARCH_DISABLED");
+}
+// src/storage-takeover/projection-cache.ts
+function selects(keys, key) {
+	if (keys === void 0) return true;
+	if ("has" in keys) return keys.has(key);
+	return keys.includes(key);
+}
+const SESSION_PROJECTION_CACHE_SERVICE = "sessionProjectionCache";
+const PREDECESSOR_TITLE_KEY = "title";
+var SessionProjectionCacheRdb = class extends Service {
+	static inject = ["sessionProjections", "sessions"];
+	records = /* @__PURE__ */ new Map();
+	queued = /* @__PURE__ */ new Set();
+	repository;
+	ready;
+	openRepository;
+	constructor(ctx, options) {
+		super(ctx, SESSION_PROJECTION_CACHE_SERVICE);
+		this.openRepository = options.repository;
+		this.ready = options.ready;
+	}
+	async [Service.init]() {
+		this.installWritePath();
+		await this.ready;
+		this.repository = await this.openRepository();
+		const pruned = await this.repository.pruneStaleProjcache();
+		if (pruned > 0) this.ctx.logger.info(`session projection cache: pruned stale snapshot(s) for ${String(pruned)} session(s)`);
+		for (const entry of await this.repository.loadProjcache()) this.records.set(entry.sessionId, entry);
+	}
+	lookup(id) {
+		return this.records.get(id);
+	}
+	recordFor(id, expected) {
+		const record = this.lookup(id);
+		if (record === void 0) return void 0;
+		return identityMatches(record.identity, expected) ? record : void 0;
+	}
+	cachedSnapshot(meta, keys) {
+		const record = this.recordForLifecycle(meta);
+		const snapshot = record === void 0 ? void 0 : this.viewRecord(record, keys);
+		return this.withDirectTitle(meta.id, keys, snapshot);
+	}
+	recordForLifecycle(meta) {
+		const record = this.lookup(meta.id);
+		return record === void 0 || !identityMatches(record.identity, lifecycleIdentityOf(meta)) ? void 0 : record;
+	}
+	withDirectTitle(id, keys, snapshot) {
+		if (!selects(keys, PREDECESSOR_TITLE_KEY)) return snapshot;
+		if (snapshot?.values[PREDECESSOR_TITLE_KEY] !== void 0) return snapshot;
+		const title = this.records.get(id)?.title;
+		if (title === void 0) return snapshot;
+		const values = {
+			...snapshot?.values,
+			[PREDECESSOR_TITLE_KEY]: title.title
+		};
+		return {
+			asOfSeq: snapshot === void 0 ? title.seq : Math.min(snapshot.asOfSeq, title.seq),
+			values
+		};
+	}
+	cachedPredecessorTitle(meta) {
+		const record = this.lookup(meta.id);
+		if (record === void 0 || !predecessorIdentityMatches(record.identity, lifecycleIdentityOf(meta))) return;
+		return this.viewRecord(record, [PREDECESSOR_TITLE_KEY]);
+	}
+	viewRecord(record, keys) {
+		const values = this.ctx.sessionProjections.viewCheckpoint(record.rows, keys);
+		const servedKeys = Object.keys(values);
+		if (servedKeys.length === 0) return void 0;
+		const firstKey = servedKeys[0];
+		let asOfSeq = record.rows[firstKey].seq;
+		for (const key of servedKeys.slice(1)) {
+			const row = record.rows[key];
+			if (row.seq < asOfSeq) asOfSeq = row.seq;
+		}
+		return {
+			asOfSeq,
+			values
+		};
+	}
+	hydratePrepared(session, events) {
+		const record = this.recordFor(session.id, identityOf(session.header, session.inheritedEventCount));
+		if (record === void 0) return this.ctx.sessionProjections.hydrate(session, {}, events, SessionLogOffset(0));
+		try {
+			return this.ctx.sessionProjections.hydrate(session, record.rows, events, SessionLogOffset(0));
+		} catch {
+			return this.ctx.sessionProjections.hydrate(session, {}, events, SessionLogOffset(0));
+		}
+	}
+	async write(session) {
+		const rows = this.ctx.sessionProjections.checkpoint(session);
+		const previous = this.lookup(session.id)?.rows;
+		if (previous !== void 0 && sameCheckpoint(previous, rows)) return;
+		if (this.ctx.sessions.get(session.id) === session) try {
+			await this.ctx.sessions.flush(session);
+		} catch (error) {
+			this.ctx.logger.warn(`session projection cache: flush before checkpoint for "${session.id}" failed (checkpoint still written from the in-memory log): ${error instanceof Error ? error.message : String(error)}`);
+		}
+		const changed = changedRows(previous, rows);
+		const removedKeys = Object.keys(previous ?? {}).filter((key) => rows[key] === void 0);
+		await this.patch(session.id, identityOf(session.header, session.inheritedEventCount), changed, removedKeys);
+	}
+	async patch(id, identity, changed, removedKeys) {
+		const detachedChanged = detachJson(changed);
+		await this.repository.patchProjcache(id, detachedChanged, removedKeys);
+		const merged = {};
+		const previous = this.records.get(id)?.rows;
+		if (previous !== void 0) Object.assign(merged, previous);
+		Object.assign(merged, detachedChanged);
+		for (const key of removedKeys) delete merged[key];
+		const title = await this.repository.readSessionTitle(id);
+		this.records.set(id, {
+			sessionId: id,
+			identity,
+			rows: merged,
+			...title === void 0 ? {} : { title }
+		});
+	}
+	async truncateTo(meta, inheritedEventCount, headSeq) {
+		const identity = identityOf(meta, inheritedEventCount);
+		const record = this.recordFor(meta.id, identity);
+		if (record === void 0) return;
+		const rows = Object.fromEntries(Object.entries(record.rows).filter(([, row]) => row.seq <= headSeq));
+		await this.put(meta.id, identity, rows);
+	}
+	coldSnapshot(meta, inheritedEventCount, events) {
+		const identity = identityOf(meta, inheritedEventCount);
+		const restored = this.ctx.sessionProjections.restore(this.recordFor(meta.id, identity)?.rows ?? {}, events, SessionLogOffset(0), meta, inheritedEventCount);
+		this.put(meta.id, identity, restored.checkpoint).catch((error) => {
+			this.ctx.logger.warn(`session projection cache: cold-read write-back for "${meta.id}" failed (cache stays stale): ${String(error)}`);
+		});
+		return restored.snapshot;
+	}
+	installWritePath() {
+		this.ctx.on("session/event", (session) => {
+			this.scheduleWrite(session, "event");
+		});
+		this.ctx.on("session/created", (session) => {
+			this.flushSoft(session, "create");
+		});
+		this.ctx.on("session/disposed", (session) => {
+			this.flushSoft(session, "detach");
+			this.queued.delete(session.id);
+		});
+	}
+	scheduleWrite(session, trigger) {
+		if (this.queued.has(session.id)) return;
+		this.queued.add(session.id);
+		queueMicrotask(() => {
+			this.queued.delete(session.id);
+			this.flushSoft(session, trigger);
+		});
+	}
+	async flushSoft(session, trigger) {
+		try {
+			await this.write(session);
+		} catch (error) {
+			this.ctx.logger.warn(`session projection cache: ${trigger} write for "${session.id}" failed (cache stays stale): ${String(error)}`);
+		}
+	}
+	async put(id, identity, rows) {
+		const detached = detachJson(rows);
+		await this.repository.putProjcache(id, detached);
+		const title = await this.repository.readSessionTitle(id);
+		this.records.set(id, {
+			sessionId: id,
+			identity,
+			rows: detached,
+			...title === void 0 ? {} : { title }
+		});
+	}
+};
+function sameRow(before, after) {
+	return before.ver === after.ver && JSON.stringify(before.val) === JSON.stringify(after.val);
+}
+function changedRows(previous, next) {
+	const changed = {};
+	for (const [key, row] of Object.entries(next)) {
+		const before = previous?.[key];
+		if (before === void 0 || !sameRow(before, row)) changed[key] = row;
+	}
+	return changed;
+}
+function sameCheckpoint(previous, next) {
+	const keys = Object.keys(next);
+	if (keys.length !== Object.keys(previous).length) return false;
+	for (const key of keys) {
+		const before = previous[key];
+		const after = next[key];
+		if (before === void 0 || after === void 0) return false;
+		if (!sameRow(before, after)) return false;
+	}
+	return true;
+}
+function detachJson(rows) {
+	let text;
+	try {
+		text = JSON.stringify(rows);
+	} catch (error) {
+		throw new TypeError(`projection checkpoint is not losslessly JSON-serializable: ${String(error)}`, { cause: error });
+	}
+	if (text === void 0) throw new TypeError("projection checkpoint is not losslessly JSON-serializable");
+	return JSON.parse(text);
+}
+function lifecycleIdentityOf(header) {
+	return {
+		formatVersion: header.version,
+		createdAt: header.createdAt,
+		...header.cwd === void 0 ? {} : { cwd: header.cwd },
+		isSeeded: header.isSeeded
+	};
+}
+function identityOf(header, inheritedEventCount) {
+	const cut = SessionLogOffset(inheritedEventCount);
+	if (!header.isSeeded && cut !== 0) throw new Error("unseeded projection-cache identity inherited event count must be 0");
+	return {
+		formatVersion: header.version,
+		createdAt: header.createdAt,
+		...header.cwd === void 0 ? {} : { cwd: header.cwd },
+		isSeeded: header.isSeeded,
+		inheritedEventCount: cut
+	};
+}
+function identityMatches(stored, expected) {
+	return stored.formatVersion === expected.formatVersion && lifecycleIdentityMatches(stored, expected);
+}
+function predecessorIdentityMatches(stored, expected) {
+	return (stored.formatVersion === void 0 || stored.formatVersion < expected.formatVersion) && lifecycleIdentityMatches(stored, expected);
+}
+function lifecycleIdentityMatches(stored, expected) {
+	return stored.createdAt === expected.createdAt && stored.cwd === expected.cwd && (stored.isSeeded ?? false) === expected.isSeeded;
+}
+// src/storage-takeover/storage-backend.ts
+var RdbStorageBackend = class {
+	repository;
+	kv = { open: (descriptor) => this.openUnit(descriptor) };
+	open = /* @__PURE__ */ new Map();
+	opening = /* @__PURE__ */ new Set();
+	closed = false;
+	constructor(repository) {
+		this.repository = repository;
+	}
+	async openUnit(descriptor) {
+		if (this.closed) throw new StorageError("closed", "rdb storage backend is closed");
+		if (this.open.has(descriptor.name) || this.opening.has(descriptor.name)) throw new Error(`kv unit '${descriptor.name}' is already open (double-open is a caller bug)`);
+		this.opening.add(descriptor.name);
+		const repository = await this.repository();
+		const unit = new RdbKvUnit(repository, descriptor);
+		this.open.set(descriptor.name, unit);
+		this.opening.delete(descriptor.name);
+		try {
+			const stored = await repository.readUnitVersion(descriptor.name);
+			const accepted = stored === descriptor.version || (descriptor.compatibleVersions ?? []).includes(stored ?? -1);
+			if (stored === void 0) await repository.insertUnitVersion(descriptor.name, descriptor.version);
+			else if (!accepted) throw new StorageError("version-mismatch", `kv unit '${descriptor.name}' is stamped version ${stored} on the medium, incompatible with descriptor version ${descriptor.version}`);
+		} catch (error) {
+			this.open.delete(descriptor.name);
+			this.opening.delete(descriptor.name);
+			throw error;
+		}
+		unit.onClose(() => {
+			this.open.delete(descriptor.name);
+		});
+		return unit;
+	}
+	async close() {
+		this.closed = true;
+		const units = [...this.open.values()];
+		this.open.clear();
+		await Promise.all(units.map((unit) => unit.close()));
+	}
+};
+var TrackedKvUnit = class {
+	repository;
+	descriptor;
+	closed = false;
+	inflight = /* @__PURE__ */ new Set();
+	onClosed;
+	constructor(repository, descriptor) {
+		this.repository = repository;
+		this.descriptor = descriptor;
+	}
+	onClose(release) {
+		this.onClosed = release;
+	}
+	async close() {
+		if (this.closed) return;
+		this.closed = true;
+		while (this.inflight.size > 0) await Promise.allSettled(this.inflight);
+		this.onClosed?.();
+	}
+	async track(operation) {
+		const settled = operation.then(() => void 0, () => void 0);
+		this.inflight.add(settled);
+		try {
+			await operation;
+		} finally {
+			this.inflight.delete(settled);
+		}
+	}
+	assertOpen() {
+		if (this.closed) throw new StorageError("closed", `kv unit '${this.descriptor.name}' is closed`);
+	}
+	assertTable(table) {
+		if (!this.descriptor.tables.includes(table)) throw new Error(`unit '${this.descriptor.name}' does not declare table '${table}'`);
+	}
+};
+var RdbKvUnit = class extends TrackedKvUnit {
+	async loadAll() {
+		this.assertOpen();
+		const tables = Object.create(null);
+		for (const record of await this.repository.listDomainRecords(this.descriptor.name)) (tables[record.table] ??= {})[record.key] = record.value;
+		for (const table of this.descriptor.tables) tables[table] ??= {};
+		return {
+			tables,
+			global: this.descriptor.hasGlobal ? await this.repository.readDomainGlobal(this.descriptor.name) : null
+		};
+	}
+	async putRecord(table, key, value) {
+		this.assertOpen();
+		this.assertTable(table);
+		await this.track(this.repository.putDomainRecord(this.descriptor.name, table, key, value));
+	}
+	async deleteRecord(table, key) {
+		this.assertOpen();
+		this.assertTable(table);
+		await this.track(this.repository.deleteDomainRecord(this.descriptor.name, table, key));
+	}
+	async deleteRecords(table, keys) {
+		this.assertOpen();
+		this.assertTable(table);
+		await this.track(this.repository.deleteDomainRecords(this.descriptor.name, table, keys));
+	}
+	async setGlobal(value) {
+		this.assertOpen();
+		if (!this.descriptor.hasGlobal) throw new Error(`unit '${this.descriptor.name}' declares no global slot`);
+		await this.track(this.repository.writeDomainGlobal(this.descriptor.name, value));
+	}
+};
+// src/storage-takeover/index.ts
+function installStorageTakeover(ctx, options) {
+	ctx.inject(["storage"], (storageCtx) => {
+		const backend = new RdbStorageBackend(options.repository);
+		storageCtx.effect(() => {
+			const unregister = storageCtx.storage.backend.register("rdb", backend);
+			return async () => {
+				unregister();
+				await backend.close();
+			};
+		}, "session-rdb.storageBackend");
+		storageCtx.provide(storageBackendServiceKey("rdb"), backend);
+	});
+	ctx.plugin(SessionProjectionCacheRdb, {
+		repository: options.repository,
+		ready: options.ready
+	});
+}
+// src/session-store.ts
+const localized = (text) => text;
+const preparedSessionCacheSchema = z.number().step(1).min(1).default(1).description(localized({
+	zh: "冷会话观察缓存容量（条数，最小 1）：每个条目持一份完整会话日志；本部署默认 1，把同 id 两份日志的驻留压到最小。",
+	en: "Cold prepared-Session observation cache size (entries, minimum 1): each entry holds one complete session log. This deployment defaults to 1, minimizing duplicate per-id residency."
+}));
+var SessionPersistenceRdb = class extends SessionPersistence {
+	static inject = ["sessions"];
+	static Config = z.union([z.object({
+		type: z.const("sqlite"),
+		path: z.string().required().description(localized({
+			zh: "SQLite 数据库文件路径；`:memory:` 是内存库（进程结束即丢）。",
+			en: "SQLite database file path; `:memory:` keeps it in memory and loses it with the process."
+		})),
+		journalMode: z.union([
+			"wal",
+			"delete",
+			"truncate",
+			"persist"
+		]).default("wal").description(localized({
+			zh: "SQLite 日志模式；默认 wal（并发读最好）。",
+			en: "SQLite journal mode; `wal` by default (best concurrent reads)."
+		})),
+		busyTimeout: z.number().step(1).min(0).default(DEFAULT_BUSY_TIMEOUT_MS).description(localized({
+			zh: "写锁冲突时的忙等超时（毫秒）。",
+			en: "Busy timeout in ms while a write lock is contended."
+		})),
+		preparedSessionCacheSize: preparedSessionCacheSchema
+	}), z.object({
+		type: z.const("postgres"),
+		connectionString: z.string().required().description(localized({
+			zh: "PostgreSQL 连接串（含库名与凭证）。",
+			en: "PostgreSQL connection string (database and credentials)."
+		})),
+		schema: z.string().default("public").description(localized({
+			zh: "库内的 schema 名；默认 public。",
+			en: "Schema name inside the database; `public` by default."
+		})),
+		preparedSessionCacheSize: preparedSessionCacheSchema
+	})]).description(localized({
+		zh: "会话持久化后端：改这里的连接参数会在这一行重挂时生效（Loader 会重装被改的行）。",
+		en: "Session persistence backend: edits apply when this row is remounted (the Loader re-installs changed rows)."
+	})).volatile();
+	name = "session-rdb";
+	tracker = new RdbBackendTracker(this.name);
+	/** 打开后的后端；未打开时访问会 fail loud（装配内部、分支端口与测试共用）。 */
+	backend;
+	storeIdentity;
+	/** 后端打开完成（分支端口与 live 路由都先等它）。 */
+	ready;
+	/** 写者位点守卫（分支的 rewind 与写路径共用）。 */
+	writeGuard = new WriteGuard();
+	live;
+	readPath;
+	writePath;
+	reuseEventIds = /* @__PURE__ */ new Map();
+	config;
+	constructor(ctx, config) {
+		super(ctx);
+		this.config = config.get();
+		this.ready = this.init();
+		this.readPath = createReadPath({
+			ready: this.ready,
+			backend: () => this.backend,
+			tracker: this.tracker,
+			logger: ctx.logger,
+			revisionOf: (row) => this.rowRevision(row)
+		});
+		this.writePath = createWritePath({
+			ready: this.ready,
+			backend: () => this.backend,
+			tracker: this.tracker,
+			writeGuard: this.writeGuard,
+			reuseEventIds: this.reuseEventIds,
+			logger: ctx.logger,
+			readLog: async (id) => {
+				const log = await this.readPath.readLog(id, {});
+				return log === void 0 ? void 0 : {
+					meta: log.meta,
+					inheritedEventCount: log.inheritedEventCount,
+					events: log.events
+				};
+			}
+		});
+		this.live = new LiveRouting(ctx, this);
+		this.live.install();
+		new SessionBranchRdb(this.ctx);
+		const queryConfig = this.config.preparedSessionCacheSize === void 0 ? {} : { preparedSessionCacheSize: this.config.preparedSessionCacheSize };
+		this.ctx.plugin(SessionQueryRdb, queryConfig);
+		registerSessionImport(this.ctx, this);
+		registerSessionDeletion(this.ctx, this);
+		registerSessionExport(this.ctx, this);
+		registerSessionOrganize(this.ctx, this);
+		registerSessionUsage(this.ctx, this);
+		registerSessionRows(this.ctx, () => this.database());
+		installStorageTakeover(this.ctx, {
+			repository: () => this.database().then((backend) => backend.storage),
+			ready: this.ready
+		});
+	}
+	/** 打开完成后的 backend（所有 DB 操作的门）。 */
+	async database() {
+		await this.ready;
+		return this.backend;
+	}
+	async init() {
+		this.backend = await openRdbBackend(backendConfigOf(this.config));
+		await this.backend.open();
+		this.storeIdentity = this.backend.storeIdentity;
+	}
+	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.reads.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
+		}));
+	}
+	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.readPath.readLog(id, {}, options?.signal);
+			if (log === void 0) throw new SessionPersistenceNotFoundError(id);
+			repairReadView(log.events);
+			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.readPath.readLog(id, {}, options?.signal);
+			if (log === void 0) throw new SessionPersistenceNotFoundError(id);
+			repairReadView(log.events);
+			validateStoredEvents(log.meta, log.events);
+			if (log.migrated && log.events.length !== log.storedCount) await this.writePath.rewriteMigratedLog(id, log);
+			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;
+		}
+	}
+	flush() {
+		return this.tracker.flushAll();
+	}
+	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
+		};
+		const row = await this.backend.reads.getSession(id);
+		if (row === void 0) return void 0;
+		return {
+			header: rowToMeta(row),
+			revision: this.rowRevision(row)
+		};
+	}
+	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 rows = await this.backend.reads.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 deleteSession(id, signal) {
+		signal?.throwIfAborted();
+		await this.ready;
+		signal?.throwIfAborted();
+		const row = await this.backend.reads.getSession(id);
+		if (row === void 0) throw new SessionDeletionError(`session "${id}" not found`, "SESSION_NOT_FOUND");
+		if (row.fArchivedAt === null) throw new SessionDeletionError(`session "${id}" is not archived; only archived sessions can be deleted`, "SESSION_NOT_ARCHIVED");
+		if (this.tracker.hasPending(id) || this.tracker.hasOpenHandle(id)) throw new SessionDeletionError(`session "${id}" is live; stop it before deleting`, "SESSION_LIVE");
+		await this.unarchiveBeforeDeletion(id);
+		const referenced = await this.backend.transaction((tx) => tx.deleteSession(id));
+		this.live.forget(id);
+		this.reuseEventIds.delete(id);
+		await this.writePath.dropSessionStats(id);
+		await this.writePath.refreshEventUsageFlags(referenced);
+	}
+	/**
+	* 整理数据：回收孤儿会话与孤儿事件行，然后**整表重算**三张派生统计表，最后 VACUUM。
+	*
+	* 顺序有依赖：先清孤儿（被删会话独占的事件行才刚成为孤儿），再按事件表重算统计，
+	* 否则统计会把刚删掉的引用算回去。
+	* @returns 三项计数（孤儿会话 / 孤儿事件行 / 重建涉及的会话数）。
+	*/
+	async organize() {
+		await this.ready;
+		const orphanSessions = await this.collectOrphanSessions();
+		const orphanEvents = await this.collectOrphans();
+		const rebuiltSessions = await this.backend.rebuildAllStats();
+		await this.backend.vacuum();
+		return {
+			orphanSessions,
+			orphanEvents,
+			rebuiltSessions
+		};
+	}
+	async collectOrphans() {
+		await this.ready;
+		return this.backend.collectOrphans();
+	}
+	async collectOrphanSessions() {
+		await this.ready;
+		const deletable = (await this.backend.listOrphanSubagentSessions()).filter((id) => !this.tracker.hasPending(id) && !this.tracker.hasOpenHandle(id));
+		if (deletable.length === 0) return 0;
+		const { deleted, eventIds } = await this.backend.transaction((tx) => tx.deleteSessions(deletable));
+		for (const id of deletable) {
+			this.live.forget(id);
+			this.reuseEventIds.delete(id);
+			await this.writePath.dropSessionStats(id);
+		}
+		await this.writePath.refreshEventUsageFlags(eventIds);
+		return deleted;
+	}
+	async usageReport(sinceMs) {
+		await this.ready;
+		return this.backend.usageReport(sinceMs);
+	}
+	async vacuum() {
+		await this.ready;
+		await this.backend.vacuum();
+	}
+	/**
+	* 已归档的会话 id（`t_sessions.f_archived_at` 非空）。`session/list` 默认过滤掉它们。
+	* 读的是持久化里的归档标记，不依赖 `workspaceRegistry` 服务的就绪时机。
+	* @returns 归档过的 Session id 集。
+	*/
+	async archivedSessionIds() {
+		await this.ready;
+		const state = await this.backend.storage.readDomainGlobal("workspace");
+		return new Set((state?.archivedSessionIds ?? []).map(String));
+	}
+	async unarchiveBeforeDeletion(id) {
+		const registry = this.ctx.get("workspaceRegistry");
+		if (registry === void 0) return;
+		if (!registry.archivedSessionIds.includes(id)) return;
+		await registry.unarchiveSession(id);
+	}
+	readLog(id, options = {}, signal) {
+		return this.readPath.readLog(id, options, signal);
+	}
+	readRaw(id, signal) {
+		return this.readPath.readRaw(id, signal);
+	}
+	listSnapshots(signal) {
+		return this.readPath.listSnapshots(signal);
+	}
+	readStoredRevision(id, signal) {
+		return this.readPath.readStoredRevision(id, signal);
+	}
+	materializeEmpty(meta, inheritedEventCount) {
+		return this.writePath.materializeEmpty(meta, inheritedEventCount);
+	}
+	appendBatch(meta, inheritedEventCount, events, tornTruncateTo) {
+		return this.writePath.appendBatch(meta, inheritedEventCount, events, tornTruncateTo);
+	}
+	async close() {
+		await this.ready;
+		await this.backend.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();
+		}
+	}
+	async load(id, signal) {
+		signal?.throwIfAborted();
+		await this.ready;
+		signal?.throwIfAborted();
+		const log = await this.readPath.readLog(id, {}, signal);
+		if (log === void 0) {
+			const pending = this.tracker.pendingOf(id);
+			if (pending !== void 0) return {
+				meta: pending.header,
+				inheritedEventCount: SessionLogOffset(pending.inheritedEventCount),
+				events: []
+			};
+			throw new SessionPersistenceNotFoundError(id);
+		}
+		repairReadView(log.events);
+		validateStoredEvents(log.meta, log.events);
+		return {
+			meta: log.meta,
+			inheritedEventCount: SessionLogOffset(log.inheritedEventCount),
+			events: log.events
+		};
+	}
+	async append(id, events) {
+		const handle = await this.open(id, "write");
+		try {
+			await handle.append(events);
+		} finally {
+			await handle.close();
+		}
+	}
+	async readFrom(id, fromSeq, signal) {
+		const log = await this.readPath.readLog(id, { fromSeq }, signal);
+		if (log === void 0) throw new SessionPersistenceNotFoundError(id);
+		return {
+			meta: log.meta,
+			inheritedEventCount: log.inheritedEventCount,
+			events: log.events
+		};
+	}
+	registerReuseEventIds(childId, map) {
+		this.reuseEventIds.set(childId, new Map(map));
+	}
+	dropReuseEventIds(childId) {
+		this.reuseEventIds.delete(childId);
+	}
+	/** 分支能力的端口（见 `branch/port.ts`）：每个动词都有真实调用方，不是服务方法表的转抄。 */
+	branchPort() {
+		return {
+			ready: this.ready,
+			readLog: (id, options, signal) => this.readPath.readLog(id, options ?? {}, signal),
+			create: (meta, options) => this.create(meta, options),
+			eventRows: (id, fromSequence) => this.backend.reads.getEventRows(id, fromSequence),
+			eventTypesBefore: (id, before, limit) => this.backend.reads.getEventTypesBefore(id, before, limit),
+			sessionRow: (id) => this.backend.reads.getSession(id),
+			eventTypeAt: (id, sequence) => this.backend.reads.getEventTypeAt(id, sequence),
+			transaction: (fn) => this.backend.transaction(fn),
+			confirmHead: (id, sequence) => this.writeGuard.confirmHead(id, sequence),
+			readStoredRevision: (id) => this.readPath.readStoredRevision(id),
+			registerReuseEventIds: (childId, map) => this.registerReuseEventIds(childId, map),
+			dropReuseEventIds: (childId) => this.dropReuseEventIds(childId),
+			resetWriterAfterRewind: (id, cursor, inheritedEventCount) => {
+				this.tracker.writerOf(id)?.resetAfterRewind(cursor, inheritedEventCount);
+			}
+		};
+	}
+	rowRevision(row) {
+		return SessionPersistenceRevision(`${this.storeIdentity}:incarnation:${row.fIncarnation}:revision:${row.fRevision}`);
+	}
+};
+/** 装配层配置 → 打开后端所需的最小形状（两方言共用）。 */
+function backendConfigOf(config) {
+	return config.type === "sqlite" ? {
+		type: "sqlite",
+		path: config.path,
+		journalMode: config.journalMode ?? "wal",
+		busyTimeout: config.busyTimeout ?? 5e3
+	} : {
+		type: "postgres",
+		connectionString: config.connectionString,
+		...config.schema === void 0 ? {} : { schema: config.schema }
+	};
+}
 export { SCHEMA_VERSION, SESSION_ROWS_PATH, SessionBranchRdb, SessionBranchRdbProvider, SessionDeletionError, SessionPersistenceRdb, SessionPersistenceRdb as default, liveEventsOf, locateTurnEnd };