@happyvertical/smrt-core 0.44.0 → 0.45.0

package/dist/change-feed.js

@@ -5,7 +5,7 @@ import { resolveDispatchTenantScope } from "./dispatch/tenant-resolver.js";
 import { isEmbeddedDatabase, withEmbeddedWriteQueue } from "./embedded-write-queue.js";
 import { GlobalInterceptors } from "./interceptors.js";
 import { detectEngine } from "./schema/ddl/index.js";
-import { CREATE_SMRT_CHANGES_TABLE, ENSURE_POSTGRES_CHANGE_FEED_APPEND_FUNCTION, ENSURE_POSTGRES_CHANGE_FEED_SCHEMA, FRAMEWORK_OPERATIONAL_TABLES, POSTGRES_CHANGE_FEED_APPEND_FUNCTION_IDENTITY, POSTGRES_CHANGE_FEED_APPEND_FUNCTION_NAME, REPLACE_POSTGRES_CHANGE_FEED_APPEND_FUNCTION, RETIRED_SYSTEM_TABLES } from "./system/schema.js";
+import { CREATE_SMRT_CHANGES_TABLE, ENSURE_POSTGRES_CHANGE_FEED_APPEND_FUNCTION, ENSURE_POSTGRES_CHANGE_FEED_SCHEMA, FRAMEWORK_OPERATIONAL_TABLES, POSTGRES_CHANGE_FEED_APPEND_FUNCTION_IDENTITY, POSTGRES_CHANGE_FEED_APPEND_FUNCTION_NAME, POSTGRES_CHANGE_FEED_DRAIN_FUNCTION_IDENTITY, POSTGRES_CHANGE_FEED_DRAIN_FUNCTION_NAME, POSTGRES_CHANGE_FEED_HELPER_MARKER, POSTGRES_CHANGE_FEED_PENDING_TABLE, REPLACE_POSTGRES_CHANGE_FEED_APPEND_FUNCTION, RETIRED_SYSTEM_TABLES } from "./system/schema.js";
 import { SYSTEM_TABLE_NAMES } from "./schema/system-table-shapes.js";
 import { createLogger } from "@happyvertical/logger";
 //#region src/change-feed.ts
@@ -49,6 +49,46 @@ import { createLogger } from "@happyvertical/logger";
 * auto-increment mechanism exists in the system-table schema path either;
 * see `system/schema.ts`.)
 *
+* ## Staged appends inside caller transactions (PostgreSQL, #2649)
+*
+* `MAX+1` allocation costs a *wait*: two appends that pick the same value
+* conflict on the primary key, and the loser waits for the winner's
+* transaction to end. Under autocommit that is one statement. Inside a
+* caller-managed transaction it is the whole transaction — and a long write
+* transaction that appends and then keeps taking row locks forms a genuine
+* lock cycle with any writer that took those row locks first and then
+* appended. PostgreSQL detects it (`40P01`) and aborts one side, so an
+* ordinary concurrent request could abort a legitimate long write.
+*
+* PostgreSQL appends issued inside a caller transaction are therefore
+* **staged**: `_smrt_append_change` inserts into `_smrt_changes_pending`,
+* whose identity key conflicts with nothing, so the append never waits on
+* another transaction and the cycle cannot form. The staged row is still
+* fate-shared with the caller (a rollback removes it). {@link drainChangeFeed}
+* — run by {@link getChangesSince} before it reads, and (throttled) by the
+* append path itself — moves *committed* staged rows into `_smrt_changes`
+* under a try-only advisory lock, numbering them `MAX(seq) + row_number()` in
+* staged order. Draining is driven from JavaScript rather than inside the
+* append helper so that every sequenced entry also gets its live `_events`
+* signal: an entry sequenced invisibly server-side would be skipped for good
+* by a subscriber whose `Last-Event-ID` came from a later, higher sequence.
+* Signals for drained entries are published only once the drain is proven
+* committed, so a rollback can never advertise a sequence another appender
+* then reuses.
+*
+* The cursor guarantee is unchanged, because sequences are still allocated by
+* exactly one `MAX+1` writer at a time and only ever for already-committed
+* work: committed sequences stay contiguous, and no entry can appear at or
+* below a horizon a reader already observed. What a staged append gives up is
+* *promptness*, not durability or order: its entry becomes visible one drain
+* after its transaction commits, and its position in the log is its drain
+* order rather than its statement order. An autocommit append drains before
+* allocating whenever its throttle allows, so staged work usually keeps its
+* place ahead of later writes.
+*
+* SQLite and DuckDB keep the direct `MAX+1` insert unchanged — SQLite
+* serializes writers outright, so the defect is unreachable there.
+*
 * Contention note: appends serialize on the head of the log. Each append is
 * one small INSERT (issued from the write path *after* the user's row was
 * written), so the serialization window is one statement; conflicts resolve
@@ -68,7 +108,7 @@ import { createLogger } from "@happyvertical/logger";
 * JavaScript only throws/logs after PostgreSQL has restored the caller's
 * transaction, so a swallowed append failure cannot surface later as 25P02.
 * The append still joins a caller-managed transaction on the same handle and
-* shares its fate (a rollback removes the change row with the data row).
+* shares its fate (a rollback removes the staged row with the data row).
 *
 * ## Known gaps (documented in the PRD)
 *
@@ -120,6 +160,7 @@ var CHANGE_FEED_TABLE = "_smrt_changes";
 */
 var CHANGE_FEED_EXCLUDED_TABLES = /* @__PURE__ */ new Set([
 	...SYSTEM_TABLE_NAMES,
+	POSTGRES_CHANGE_FEED_PENDING_TABLE,
 	...FRAMEWORK_OPERATIONAL_TABLES,
 	...RETIRED_SYSTEM_TABLES
 ]);
@@ -144,6 +185,83 @@ var MAX_CHANGES_LIMIT = 5e3;
 * blocking transaction commits, so a small bound is ample.
 */
 var MAX_APPEND_ATTEMPTS = 20;
+/**
+* Maximum bounded drain batches one {@link drainChangeFeed} call sequences.
+* A cap rather than "until empty" so a pathological writer cannot make one
+* reader drain forever; the remainder is picked up by the next drain.
+*/
+var MAX_DRAIN_PASSES = 50;
+/** Cap on signals held for a handle that keeps draining without committing. */
+var MAX_DEFERRED_SIGNALS = 5e3;
+/**
+* Per-handle low-water mark of sequences a drain allocated but has not proven
+* committed (#2649).
+*
+* The hold-back has to outlive the drain call that created it. A caller
+* transaction can drain in one statement and read in the next — the second
+* read's own drain allocates nothing (the server-side helper refuses once the
+* transaction has an id), yet the transaction still sees the first drain's
+* uncommitted rows and would serve them. Keyed on the handle object, which is
+* the transaction's identity for its whole life, so every later read on the
+* same transaction keeps holding back from the same mark.
+*
+* The mark is recorded unconditionally and *used* only while a transaction id
+* is still assigned at read time. Under autocommit the drain committed as its
+* own transaction, so the next read clears the mark and serves the rows.
+*/
+var uncommittedDrainMarks = /* @__PURE__ */ new WeakMap();
+/**
+* How often the append path drains on its own behalf, per database.
+*
+* The append helper deliberately does not drain server-side: sequences it
+* assigned there would never reach JavaScript, so no `_events` signal would be
+* published for them while this append's own signal carries a higher sequence
+* — and an EventSource resuming from that `Last-Event-ID` would skip them for
+* good. Draining from here instead keeps every sequenced entry signalled, in
+* ascending order, and keeps a deployment whose writers never read the feed
+* from accumulating staged entries indefinitely. Throttled because it is a
+* liveness convenience, not a correctness requirement: cursor readers drain
+* for themselves, and `getTableVersion()` already counts staged entries.
+*/
+var APPEND_DRAIN_INTERVAL_MS = 250;
+/** dbKey → last time the append path drained for it. */
+var lastAppendDrain = /* @__PURE__ */ new Map();
+/** dbKeys that staged an append since this process last drained them. */
+var stagedSinceLastDrain = /* @__PURE__ */ new Set();
+function noteStagedAppend(db) {
+	try {
+		stagedSinceLastDrain.add(resolveDbCacheKey(db));
+	} catch {}
+}
+async function drainBeforeAppend(db) {
+	if (getEngine(db) !== "postgres") return [];
+	let dbKey;
+	try {
+		dbKey = resolveDbCacheKey(db);
+	} catch {
+		return [];
+	}
+	const now = Date.now();
+	const last = lastAppendDrain.get(dbKey);
+	if (!stagedSinceLastDrain.has(dbKey) && last !== void 0 && now - last < APPEND_DRAIN_INTERVAL_MS) return [];
+	stagedSinceLastDrain.delete(dbKey);
+	lastAppendDrain.set(dbKey, now);
+	try {
+		return (await drainChangeFeedDetailed(db, {
+			settle: false,
+			maxPasses: 1
+		})).unsettledSignals;
+	} catch (error) {
+		warnDrainFailureOnce(db, error);
+		return [];
+	}
+}
+function recordUncommittedDrainMark(db, firstAllocatedSeq) {
+	if (firstAllocatedSeq === null) return;
+	const key = db;
+	const existing = uncommittedDrainMarks.get(key);
+	if (existing === void 0 || firstAllocatedSeq < existing) uncommittedDrainMarks.set(key, firstAllocatedSeq);
+}
 var VALID_OPERATIONS = /* @__PURE__ */ new Set([
 	"create",
 	"update",
@@ -199,14 +317,37 @@ function isUniqueViolation(error) {
 * framework already have the table via the system-table bootstrap.
 */
 var ensuredHandles = /* @__PURE__ */ new WeakSet();
-async function postgresChangeFeedAppendFunctionExists(db) {
-	const rows = getQueryRows(await db.query(`SELECT to_regprocedure('${POSTGRES_CHANGE_FEED_APPEND_FUNCTION_IDENTITY}') AS function_name`));
-	return Boolean(rows[0]?.function_name);
+/**
+* SQL fragment that reports a helper as present ONLY when its body is current.
+*
+* `to_regprocedure()` alone answers "a function of this name and signature
+* exists", which is not the same question: an install can hold a helper whose
+* body predates a fix, and an existence probe would call it current and never
+* replace it. Matching {@link POSTGRES_CHANGE_FEED_HELPER_MARKER} against
+* `pg_proc.prosrc` makes the probe version-aware, so bumping the marker is all
+* a future helper change needs to reach existing databases.
+*/
+function currentHelperProbe(identity) {
+	return `(
+    SELECT p.oid
+    FROM pg_proc AS p
+    WHERE p.oid = to_regprocedure('${identity}')
+      AND p.prosrc LIKE '%${POSTGRES_CHANGE_FEED_HELPER_MARKER}%'
+  )`;
+}
+async function postgresChangeFeedHelpersCurrent(db) {
+	const rows = getQueryRows(await db.query(`SELECT
+         ${currentHelperProbe(POSTGRES_CHANGE_FEED_APPEND_FUNCTION_IDENTITY)} AS function_name,
+         ${currentHelperProbe(POSTGRES_CHANGE_FEED_DRAIN_FUNCTION_IDENTITY)} AS drain_function_name,
+         to_regclass('${POSTGRES_CHANGE_FEED_PENDING_TABLE}') AS pending_table_name`));
+	return Boolean(rows[0]?.function_name && rows[0]?.drain_function_name && rows[0]?.pending_table_name);
 }
 async function getPostgresChangeFeedSchemaState(db) {
 	const rows = getQueryRows(await db.query(`SELECT
          to_regclass('${CHANGE_FEED_TABLE}') AS table_name,
-         to_regprocedure('${POSTGRES_CHANGE_FEED_APPEND_FUNCTION_IDENTITY}') AS function_name,
+         ${currentHelperProbe(POSTGRES_CHANGE_FEED_APPEND_FUNCTION_IDENTITY)} AS function_name,
+         to_regclass('${POSTGRES_CHANGE_FEED_PENDING_TABLE}') AS pending_table_name,
+         ${currentHelperProbe(POSTGRES_CHANGE_FEED_DRAIN_FUNCTION_IDENTITY)} AS drain_function_name,
          (
            SELECT data_type
            FROM information_schema.columns
@@ -217,6 +358,8 @@ async function getPostgresChangeFeedSchemaState(db) {
 	return {
 		tableExists: Boolean(rows[0]?.table_name),
 		functionExists: Boolean(rows[0]?.function_name),
+		pendingTableExists: Boolean(rows[0]?.pending_table_name),
+		drainFunctionExists: Boolean(rows[0]?.drain_function_name),
 		createdAtType: rows[0]?.created_at_type ? String(rows[0].created_at_type) : null
 	};
 }
@@ -239,18 +382,45 @@ async function ensurePostgresChangeFeedAppendFunction(db, options = {}) {
 	if (getEngine(db, options.typeHint) !== "postgres") return;
 	assertPostgresChangeFeedTimestampCurrent(await getPostgresChangeFeedSchemaState(db));
 	if (options.replaceExisting === false) {
-		if (await postgresChangeFeedAppendFunctionExists(db)) return;
+		if (await postgresChangeFeedHelpersCurrent(db)) return;
 		await db.query(ENSURE_POSTGRES_CHANGE_FEED_APPEND_FUNCTION);
 		return;
 	}
 	await db.query(REPLACE_POSTGRES_CHANGE_FEED_APPEND_FUNCTION);
 }
+/**
+* Refresh the PostgreSQL change-feed helpers on an already-initialized
+* database (issue #2649).
+*
+* `bootstrapSystemTables()` installs the helpers only while applying a system
+* schema version, and #2649 changes the helper body without changing the
+* portable system DDL — so a database already stamped with the current version
+* would keep the pre-#2649 append function, and its `40P01` deadlock, until
+* some feed route happened to call {@link ensureChangeFeedTable}. Ordinary
+* model writes never do. Bootstrap therefore calls this before its
+* version fast-return; it is one catalog probe when the helpers are current.
+*
+* Databases whose `_smrt_changes.created_at` is still the legacy
+* timezone-naive column are left alone: they need their audited
+* `migratePostgresSystemTimestamps()` pass first, and failing bootstrap on
+* them here would be a new, unrelated break.
+*
+* @internal
+*/
+async function ensurePostgresChangeFeedHelpers(db, typeHint) {
+	if (getEngine(db, typeHint) !== "postgres") return;
+	const state = await getPostgresChangeFeedSchemaState(db);
+	if (!state.tableExists) return;
+	if (state.createdAtType !== "timestamp with time zone") return;
+	if (state.functionExists && state.pendingTableExists && state.drainFunctionExists) return;
+	await db.query(ENSURE_POSTGRES_CHANGE_FEED_SCHEMA);
+}
 async function ensureChangeFeedTable(db) {
 	if (ensuredHandles.has(db)) return;
 	if (getEngine(db) === "postgres") {
 		const state = await getPostgresChangeFeedSchemaState(db);
 		assertPostgresChangeFeedTimestampCurrent(state);
-		if (state.tableExists && state.functionExists && state.createdAtType === "timestamp with time zone") {
+		if (state.tableExists && state.functionExists && state.pendingTableExists && state.drainFunctionExists && state.createdAtType === "timestamp with time zone") {
 			ensuredHandles.add(db);
 			return;
 		}
@@ -273,6 +443,14 @@ async function ensureChangeFeedTable(db) {
 * conflicts or on any non-conflict database error; the framework's
 * interceptor catches and logs instead of failing the user's write.
 *
+* **Returns `null` for a staged append** (PostgreSQL, #2649): an append issued
+* inside a caller-managed transaction is written to `_smrt_changes_pending`
+* and receives its sequence from the next {@link drainChangeFeed} after that
+* transaction commits, so no sequence exists to return yet. The entry is
+* durable and ordered — it simply is not numbered at this instant. Callers
+* that need the sequence (an SSE event id, say) must treat `null` as "not
+* available yet", never as a failure: a failure still throws.
+*
 * **PostgreSQL transaction safety (#2026).** The INSERT runs inside the
 * framework-owned `_smrt_append_change` PL/pgSQL function. Its exception
 * handler is a PostgreSQL subtransaction: a failed attempt is rolled back
@@ -297,6 +475,27 @@ async function appendChange(db, input) {
 		input.tenantId ?? null,
 		(/* @__PURE__ */ new Date()).toISOString()
 	];
+	const drainedSignals = await drainBeforeAppend(db);
+	/**
+	* Settle the pre-append drain's signals from what this append revealed.
+	*
+	* A drain that allocated anything assigned a transaction id, so if this
+	* append then took the DIRECT path — `pg_current_xact_id_if_assigned()` was
+	* still null at its entry — that id is already gone, which can only mean the
+	* drain committed as its own autocommit transaction. Publishing here is
+	* therefore proven safe AND correctly ordered: these sequences are below the
+	* one this append is about to take, and the interceptor publishes that one
+	* only after this call returns. A deferred append proves nothing, so its
+	* signals go to the queue.
+	*/
+	const settleDrainedSignals = (appended) => {
+		if (drainedSignals.length === 0) return;
+		if (appended === null) {
+			queueDeferredSignals(db, drainedSignals);
+			return;
+		}
+		publishSignals(db, drainedSignals);
+	};
 	for (let attempt = 1; attempt <= MAX_APPEND_ATTEMPTS; attempt++) try {
 		const row = getQueryRows(await withEmbeddedWriteQueue(db, isEmbeddedDatabase(db), () => db.query(sql, ...params)))[0];
 		if (!row) throw new Error("Change feed append returned no result row");
@@ -305,13 +504,223 @@ async function appendChange(db, input) {
 			error.code = String(row.error_code);
 			throw error;
 		}
-		return toSeqNumber(engine === "postgres" ? row.allocated_seq : row.seq);
+		if (engine === "postgres" && row.allocated_seq == null) {
+			noteStagedAppend(db);
+			settleDrainedSignals(null);
+			return null;
+		}
+		const seq = toSeqNumber(engine === "postgres" ? row.allocated_seq : row.seq);
+		settleDrainedSignals(seq);
+		if (engine === "postgres") recordUncommittedDrainMark(db, seq);
+		return seq;
 	} catch (error) {
-		if (!isUniqueViolation(error) || attempt === MAX_APPEND_ATTEMPTS) throw error;
+		if (!isUniqueViolation(error) || attempt === MAX_APPEND_ATTEMPTS) {
+			queueDeferredSignals(db, drainedSignals);
+			throw error;
+		}
 	}
 	throw new Error("appendChange exhausted retries without allocating a seq");
 }
 /**
+* Sequence change-feed entries staged inside caller-managed transactions
+* (issue #2649). PostgreSQL only; a no-op on every other engine.
+*
+* A `save()`/`delete()`/{@link appendChange} issued inside a caller
+* transaction cannot allocate `MAX(seq) + 1` there: the allocation waits for
+* any competing appender's transaction to end, and a long write transaction
+* that goes on to take row locks the waiter holds closes a real lock cycle
+* (`40P01`). Such appends are staged instead, and this call moves every
+* **committed** staged entry into `_smrt_changes` with contiguous sequences,
+* in staged order, under a try-only advisory lock.
+*
+* It runs by itself on the paths that matter — every autocommit append drains
+* server-side before allocating its own sequence, and {@link getChangesSince}
+* drains before it reads — so applications do not normally need to call it. A
+* drain issued from inside a transaction that has already written is skipped
+* server-side: allocating there would hold sequences uncommitted for the rest
+* of that transaction, which is the wait this fix removes.
+* Call it explicitly from a scheduled job when a deployment writes *only*
+* through transactions and reads the feed from a connection that cannot write
+* (a read replica or a read-only role), because neither self-draining path is
+* then available.
+*
+* Best-effort by the feed's failure policy: a drain that cannot run leaves the
+* staged entries in place for the next attempt and never throws into the
+* caller's write path. Nothing is lost — staged entries are durable — they are
+* simply not yet visible to cursor readers.
+*
+* @returns How many staged entries were sequenced.
+*/
+async function drainChangeFeed(db) {
+	return (await drainChangeFeedDetailed(db)).drained;
+}
+/**
+* {@link drainChangeFeed} plus the lowest sequence this call allocated.
+*
+* A drain runs on the caller's handle, so when that handle is inside a
+* caller-managed transaction the rows it just wrote are visible **to this
+* transaction only** and disappear if it rolls back. A reader that served them
+* would report entries that never committed and advance its cursor past
+* sequences a concurrent autocommit appender goes on to claim — a permanently
+* skipped change. {@link getChangesSince} therefore refuses to serve at or
+* above `firstAllocatedSeq`: everything below it was committed by somebody
+* else before this drain started, and the drain's own rows are served by the
+* next poll, once they are committed for everyone.
+*
+* @internal
+*/
+async function drainChangeFeedDetailed(db, options = {}) {
+	if (getEngine(db) !== "postgres") return {
+		drained: 0,
+		firstAllocatedSeq: null,
+		unsettledSignals: []
+	};
+	const settle = options.settle !== false;
+	if (settle) await flushDeferredSignals(db);
+	let firstAllocatedSeq = null;
+	let drained = 0;
+	const unsettledSignals = [];
+	const maxPasses = Math.max(1, options.maxPasses ?? MAX_DRAIN_PASSES);
+	for (let pass = 0; pass < maxPasses; pass++) {
+		const rows = getQueryRows(await db.query(`SELECT * FROM ${POSTGRES_CHANGE_FEED_DRAIN_FUNCTION_NAME}()`));
+		const failure = rows.find((row) => row.error_code != null);
+		if (failure) {
+			const error = new Error(String(failure.error_message || "PostgreSQL change-feed drain failed"));
+			error.code = String(failure.error_code);
+			if (isUniqueViolation(error)) continue;
+			throw error;
+		}
+		const sequenced = rows.filter((row) => row.drained_seq != null);
+		drained += sequenced.length;
+		for (const row of sequenced) {
+			const seq = toSeqNumber(row.drained_seq);
+			if (firstAllocatedSeq === null || seq < firstAllocatedSeq) firstAllocatedSeq = seq;
+		}
+		const signals = sequenced.map((row) => ({
+			table: String(row.drained_table ?? ""),
+			operation: String(row.drained_operation ?? "update"),
+			rowId: row.drained_row_id == null ? null : String(row.drained_row_id),
+			tenantId: row.drained_tenant_id == null ? null : String(row.drained_tenant_id),
+			seq: toSeqNumber(row.drained_seq)
+		}));
+		if (signals.length > 0) if (!settle) unsettledSignals.push(...signals);
+		else if (await drainCommitted(db)) publishSignals(db, signals);
+		else queueDeferredSignals(db, signals);
+		if (sequenced.length === 0) break;
+	}
+	recordUncommittedDrainMark(db, firstAllocatedSeq);
+	return {
+		drained,
+		firstAllocatedSeq,
+		unsettledSignals
+	};
+}
+/** Signals a drain produced but could not yet prove committed. */
+var deferredSignals = /* @__PURE__ */ new Map();
+function publishSignals(db, signals) {
+	for (const signal of signals) try {
+		publishChangeSignal(db, signal);
+	} catch (error) {
+		warnSignalPublishFailureOnce(db, signal.table, error);
+	}
+}
+function queueDeferredSignals(db, signals) {
+	try {
+		const dbKey = resolveDbCacheKey(db);
+		const queued = deferredSignals.get(dbKey);
+		if (queued) {
+			queued.push(...signals);
+			if (queued.length > MAX_DEFERRED_SIGNALS) queued.splice(0, queued.length - MAX_DEFERRED_SIGNALS);
+		} else deferredSignals.set(dbKey, [...signals]);
+	} catch {}
+}
+/**
+* Publish queued signals whose sequences are now committed.
+*
+* A queued entry's transaction may have rolled back, which returns its row to
+* the staging table and frees its sequence for somebody else. Each queued
+* signal is therefore verified against the committed log before it is
+* published: the sequence must still carry the same table and row.
+*
+* An entry that does not verify is **kept, not dropped**. The queue is keyed
+* per database, and every connection to that database shares it — so a second
+* connection can reach this while the transaction that queued the entry is
+* still open. Its own commit probe says "not in a transaction", but it cannot
+* see the other connection's uncommitted rows, and discarding on that basis
+* would strand a signal nobody can ever republish once that transaction
+* commits. Unverified entries therefore wait for a later flush, bounded only
+* by {@link MAX_DEFERRED_SIGNALS}, which evicts oldest-first — an entry whose
+* transaction really did roll back is re-sequenced and re-signalled by a later
+* drain regardless.
+*/
+async function flushDeferredSignals(db) {
+	let dbKey;
+	try {
+		dbKey = resolveDbCacheKey(db);
+	} catch {
+		return;
+	}
+	const queued = deferredSignals.get(dbKey);
+	if (!queued || queued.length === 0) return;
+	deferredSignals.delete(dbKey);
+	const candidates = queued;
+	let unpublished = candidates;
+	try {
+		if (!await drainCommitted(db)) return;
+		unpublished = await publishVerifiedSignals(db, candidates);
+	} finally {
+		requeueDeferredSignals(dbKey, unpublished);
+	}
+}
+/**
+* Publish the queued signals whose sequences still carry the row they were
+* drained for, and return the ones that could not be verified.
+*/
+async function publishVerifiedSignals(db, candidates) {
+	const p = placeholders(db);
+	const rows = getQueryRows(await db.query(`SELECT seq, table_name, row_id FROM ${CHANGE_FEED_TABLE} WHERE seq IN (${candidates.map((_, index) => p(index + 1)).join(", ")})`, ...candidates.map((signal) => signal.seq)));
+	const identity = (table, rowId) => `${table}\u0000${rowId ?? ""}`;
+	const committed = new Map(rows.map((row) => [toSeqNumber(row.seq), identity(String(row.table_name ?? ""), row.row_id == null ? null : String(row.row_id))]));
+	const verified = candidates.filter((signal) => committed.get(signal.seq) === identity(signal.table, signal.rowId));
+	if (verified.length === 0) return candidates;
+	const publishedSeqs = new Set(verified.map((signal) => signal.seq));
+	publishSignals(db, verified);
+	return candidates.filter((signal) => !publishedSeqs.has(signal.seq));
+}
+/** Put unpublished signals back, ahead of anything queued meanwhile. */
+function requeueDeferredSignals(dbKey, signals) {
+	if (signals.length === 0) return;
+	const queuedSince = deferredSignals.get(dbKey) ?? [];
+	const merged = [...signals, ...queuedSince];
+	deferredSignals.set(dbKey, merged.length > MAX_DEFERRED_SIGNALS ? merged.slice(merged.length - MAX_DEFERRED_SIGNALS) : merged);
+}
+/**
+* Whether the drain that just ran has committed.
+*
+* Under autocommit the drain was its own transaction and ended with its
+* statement, so no transaction id is assigned by the time this separate
+* statement runs. Inside a caller transaction the id the drain assigned is
+* still live and its rows are still uncommitted.
+*/
+async function drainCommitted(db) {
+	const committed = getQueryRows(await db.query("SELECT pg_current_xact_id_if_assigned() IS NULL AS committed"))[0]?.committed;
+	return committed === true || committed === "t";
+}
+/**
+* Drain without ever failing the caller — the read-path and prune policy.
+*
+* Any sequences it allocates are recorded on the handle's uncommitted-drain
+* mark; see {@link uncommittedDrainMarks} for why a reader must not serve at
+* or above it while the caller's transaction is still open.
+*/
+async function drainChangeFeedBestEffort(db) {
+	try {
+		await drainChangeFeedDetailed(db);
+	} catch (error) {
+		warnDrainFailureOnce(db, error);
+	}
+}
+/**
 * Manual bump escape hatch for out-of-band writers.
 *
 * Framework mutation paths feed the log automatically, but raw SQL issued
@@ -370,11 +779,17 @@ async function getChangesSince(db, options) {
 	const { since } = options;
 	if (!Number.isFinite(since) || since < 0) throw new Error(`getChangesSince requires a non-negative numeric cursor, got '${String(since)}'`);
 	const limit = Math.min(Math.max(Math.floor(options.limit ?? 500), 1), MAX_CHANGES_LIMIT);
+	await drainChangeFeedBestEffort(db);
 	const p = placeholders(db);
-	const boundsRows = getQueryRows(await db.query(`SELECT MIN(seq) AS floor, MAX(seq) AS horizon FROM ${CHANGE_FEED_TABLE}`));
+	const boundsRows = getQueryRows(await db.query(getEngine(db) === "postgres" ? `SELECT MIN(seq) AS floor, MAX(seq) AS horizon, pg_current_xact_id_if_assigned() IS NOT NULL AS in_transaction FROM ${CHANGE_FEED_TABLE}` : `SELECT MIN(seq) AS floor, MAX(seq) AS horizon FROM ${CHANGE_FEED_TABLE}`));
 	const floor = toSeqNumber(boundsRows[0]?.floor);
 	const horizon = toSeqNumber(boundsRows[0]?.horizon);
-	if (horizon === 0) return since === 0 ? {
+	const inCallerTransaction = boundsRows[0]?.in_transaction === true || boundsRows[0]?.in_transaction === "t";
+	const handleKey = db;
+	if (!inCallerTransaction) uncommittedDrainMarks.delete(handleKey);
+	const drainMark = inCallerTransaction ? uncommittedDrainMarks.get(handleKey) : void 0;
+	const servedHorizon = drainMark === void 0 ? horizon : Math.min(horizon, drainMark - 1);
+	if (servedHorizon === 0) return since === 0 ? {
 		changes: [],
 		cursor: 0
 	} : {
@@ -383,19 +798,19 @@ async function getChangesSince(db, options) {
 		resyncRequired: true,
 		resyncCursor: 0
 	};
-	if (since > horizon) return {
+	if (since > servedHorizon) return {
 		changes: [],
 		cursor: since,
 		resyncRequired: true,
-		resyncCursor: horizon
+		resyncCursor: servedHorizon
 	};
 	if (since < floor - 1) return {
 		changes: [],
 		cursor: since,
 		resyncRequired: true,
-		resyncCursor: horizon
+		resyncCursor: servedHorizon
 	};
-	if (horizon === since) return {
+	if (servedHorizon <= since) return {
 		changes: [],
 		cursor: since
 	};
@@ -406,7 +821,7 @@ async function getChangesSince(db, options) {
 	conditions.push(`seq > ${next()}`);
 	params.push(since);
 	conditions.push(`seq <= ${next()}`);
-	params.push(horizon);
+	params.push(servedHorizon);
 	const tables = options.tables?.filter((table) => table.trim().length > 0);
 	if (tables && tables.length > 0) {
 		conditions.push(`table_name IN (${tables.map(() => next()).join(", ")})`);
@@ -422,7 +837,7 @@ async function getChangesSince(db, options) {
 	const changes = getQueryRows(await db.query(sql, ...params)).map(rowToEntry);
 	return {
 		changes,
-		cursor: changes.length === limit ? changes[changes.length - 1].seq : horizon
+		cursor: changes.length === limit ? changes[changes.length - 1].seq : servedHorizon
 	};
 }
 /**
@@ -493,9 +908,17 @@ async function getTableVersion(db, table) {
 	if (!name) throw new Error("getTableVersion requires a non-empty table name");
 	await ensureChangeFeedTable(db);
 	const p = placeholders(db);
-	const tableVersion = getQueryRows(await db.query(`SELECT MAX(seq) AS version FROM ${CHANGE_FEED_TABLE} WHERE table_name = ${p(1)}`, name))[0]?.version;
-	if (tableVersion != null) return toSeqNumber(tableVersion);
-	return toSeqNumber(getQueryRows(await db.query(`SELECT MAX(seq) AS horizon FROM ${CHANGE_FEED_TABLE}`))[0]?.horizon);
+	const row = getQueryRows(await db.query(getEngine(db) === "postgres" ? `SELECT
+             (SELECT MAX(seq) FROM ${CHANGE_FEED_TABLE} WHERE table_name = ${p(1)}) AS version,
+             (SELECT MAX(seq) FROM ${CHANGE_FEED_TABLE}) AS horizon,
+             (SELECT COUNT(*) FROM ${POSTGRES_CHANGE_FEED_PENDING_TABLE} WHERE table_name = ${p(1)}) AS staged` : `SELECT
+             (SELECT MAX(seq) FROM ${CHANGE_FEED_TABLE} WHERE table_name = ${p(1)}) AS version,
+             (SELECT MAX(seq) FROM ${CHANGE_FEED_TABLE}) AS horizon,
+             0 AS staged`, name))[0];
+	const staged = toSeqNumber(row?.staged);
+	const tableVersion = row?.version;
+	if (tableVersion != null) return toSeqNumber(tableVersion) + staged;
+	return toSeqNumber(row?.horizon) + staged;
 }
 function toSeqNumber(value) {
 	return toSafeInteger(value ?? 0, "Change-feed sequence");
@@ -543,6 +966,7 @@ async function pruneChangeFeed(db, retention) {
 	if (maxAgeMs != null && (!Number.isFinite(maxAgeMs) || maxAgeMs < 0)) throw new Error(`pruneChangeFeed maxAgeMs must be >= 0, got ${maxAgeMs}`);
 	if (maxRows != null && (!Number.isFinite(maxRows) || maxRows < 0)) throw new Error(`pruneChangeFeed maxRows must be >= 0, got ${maxRows}`);
 	const p = placeholders(db);
+	await drainChangeFeedBestEffort(db);
 	const horizon = toSeqNumber(getQueryRows(await db.query(`SELECT MAX(seq) AS horizon FROM ${CHANGE_FEED_TABLE}`))[0]?.horizon);
 	if (horizon === 0) return { pruned: 0 };
 	let pruned = 0;
@@ -556,11 +980,9 @@ async function pruneChangeFeed(db, retention) {
 	}
 	if (maxAgeMs != null) {
 		const cutoff = new Date(Date.now() - maxAgeMs).toISOString();
-		pruned += await deleteCounted(db, `created_at < ${p(1)} AND seq < ${p(2)} AND seq > ${p(3)}`, [
-			cutoff,
-			horizon,
-			prunedThrough
-		], dryRun);
+		const firstRetained = toSeqNumber(getQueryRows(await db.query(`SELECT MIN(seq) AS first_retained FROM ${CHANGE_FEED_TABLE} WHERE created_at >= ${p(1)}`, cutoff))[0]?.first_retained);
+		const ageThrough = Math.min(firstRetained > 0 ? firstRetained - 1 : horizon - 1, horizon - 1);
+		if (ageThrough > prunedThrough) pruned += await deleteCounted(db, `seq <= ${p(1)} AND seq > ${p(2)}`, [ageThrough, prunedThrough], dryRun);
 	}
 	return { pruned };
 }
@@ -574,6 +996,8 @@ var CHANGE_FEED_WAS_PERSISTED_KEY = "_smrtChangeFeedWasPersisted";
 var warnedAppendFailures = /* @__PURE__ */ new Set();
 /** Databases we already warned about after a failed signal publish (#1763). */
 var warnedSignalPublishFailures = /* @__PURE__ */ new Set();
+/** Databases we already warned about after a failed feed drain (#2649). */
+var warnedDrainFailures = /* @__PURE__ */ new Set();
 /**
 * Register the change-feed writer with {@link GlobalInterceptors}.
 *
@@ -641,6 +1065,7 @@ async function appendForInstance(instance, operation) {
 			operation,
 			tenantId: rowTenantId
 		});
+		if (seq == null) return;
 		try {
 			publishChangeSignal(db, {
 				table,
@@ -668,6 +1093,14 @@ function warnAppendFailureOnce(db, table, error) {
 		logger.warn(`Change feed: failed to append a change entry for '${table}'. The write itself succeeded; the feed is missing this change (further failures for this database are suppressed). Consumers recover on full resync.`, { error: error instanceof Error ? error.message : String(error) });
 	} catch {}
 }
+function warnDrainFailureOnce(db, error) {
+	try {
+		const dbKey = resolveDbCacheKey(db);
+		if (warnedDrainFailures.has(dbKey)) return;
+		warnedDrainFailures.add(dbKey);
+		logger.warn("Change feed: failed to sequence entries staged inside caller transactions. Those entries are durable but stay invisible to cursor readers until a drain succeeds (further failures for this database are suppressed). A read-only handle cannot drain — schedule drainChangeFeed() on a writable connection.", { error: error instanceof Error ? error.message : String(error) });
+	} catch {}
+}
 function warnSignalPublishFailureOnce(db, table, error) {
 	try {
 		const dbKey = resolveDbCacheKey(db);
@@ -682,8 +1115,12 @@ function warnSignalPublishFailureOnce(db, table, error) {
 function resetChangeFeedWarnings() {
 	warnedAppendFailures.clear();
 	warnedSignalPublishFailures.clear();
+	warnedDrainFailures.clear();
+	lastAppendDrain.clear();
+	stagedSinceLastDrain.clear();
+	deferredSignals.clear();
 }
 //#endregion
-export { CHANGE_FEED_EXCLUDED_TABLES, CHANGE_FEED_INTERCEPTOR_NAME, CHANGE_FEED_TABLE, CHANGE_FEED_WAS_PERSISTED_KEY, DEFAULT_CHANGES_LIMIT, MAX_CHANGES_LIMIT, appendChange, bumpChangeFeed, ensureChangeFeedTable, ensurePostgresChangeFeedAppendFunction, getChangesSince, getTableVersion, getTenantScopedChangesSince, isChangeFeedObservableTable, pruneChangeFeed, recordInstanceChange, registerChangeFeedWriter, resetChangeFeedWarnings, unregisterChangeFeedWriter };
+export { CHANGE_FEED_EXCLUDED_TABLES, CHANGE_FEED_INTERCEPTOR_NAME, CHANGE_FEED_TABLE, CHANGE_FEED_WAS_PERSISTED_KEY, DEFAULT_CHANGES_LIMIT, MAX_CHANGES_LIMIT, appendChange, bumpChangeFeed, drainChangeFeed, ensureChangeFeedTable, ensurePostgresChangeFeedAppendFunction, ensurePostgresChangeFeedHelpers, getChangesSince, getTableVersion, getTenantScopedChangesSince, isChangeFeedObservableTable, pruneChangeFeed, recordInstanceChange, registerChangeFeedWriter, resetChangeFeedWarnings, unregisterChangeFeedWriter };
 
 //# sourceMappingURL=change-feed.js.map