@harperfast/harper 5.2.4 → 5.2.6

package/resources/DatabaseTransaction.ts

@@ -16,6 +16,8 @@ import type { Entry } from './RecordEncoder.ts';
 import { toBufferKey } from 'ordered-binary';
 
 const trackedTxns = new Set<DatabaseTransaction>();
+// Read options for a rotated generation's native transactions; shared because they never vary.
+const SNAPSHOT_FREE = Object.freeze({ disableSnapshot: true });
 // Logical transactions the monitor supervises for their WRITES, kept apart from trackedTxns because the
 // two have different units and different consumers: trackedTxns is per-link, bounds a read snapshot, and
 // is what the read-queue-depth metric counts, while this holds one entry per logical transaction — the
@@ -259,7 +261,9 @@ export type TransactionWrite = {
 	before?: () => void | Promise<void>;
 	beforeIntermediate?: () => void | Promise<void>;
 	commit?: (txnTime: number, existingEntry: Partial<Entry>, retry: boolean, transaction: any) => MaybePromise<void>;
-	validate?: (txnTime: number) => void;
+	// Once a write has been taken over, the transaction committing it is not the one that staged it, and
+	// overload accounting, the replay marker and a no-op write's removal all belong to the committer.
+	validate?: (txnTime: number, committedBy: DatabaseTransaction) => void;
 	fullUpdate?: boolean;
 	saved?: boolean;
 	deferSave?: boolean;
@@ -276,6 +280,10 @@ export type TransactionWrite = {
 	// sticky: a non-isRetry staging of this write appended its audit entry (set in save(); the retry
 	// dedup guards in the commit handler read it to ignore the write's own orphaned entry)
 	appendedAuditEntry?: boolean;
+	// the transaction holding this write in its `writes` (set in addWrite). A deferred write's save() is
+	// only its trigger, so it can be triggered after the context has moved on to another transaction;
+	// this is who commits it when the transaction current at that point is not a scope (#2292).
+	stagedIn?: DatabaseTransaction;
 	// the preceding write to the same store and key in this transaction, if any (linked in addWrite)
 	priorWrite?: TransactionWrite;
 	// set only by a write that BOTH reads priorStagedWrite() and publishes stagedEntry; addWrite orders
@@ -331,6 +339,15 @@ type RocksTransactionWithRetry = RocksTransaction & { isRetry?: boolean };
 
 export class DatabaseTransaction implements Transaction {
 	#context: Context;
+	// Whether a resources/transaction.ts scope owns this instance — i.e. a final commit or abort is
+	// guaranteed to follow. Only such a transaction may be rotated to a new generation by a mid-scope
+	// commit (see rotateAfterMidScopeCommit); anything else must commit each later write immediately,
+	// because nothing would commit staged ones. Settable only at construction, so it cannot be turned on
+	// for a transaction that is already attached to a context and running.
+	#scopeOwned: boolean;
+	constructor(options?: { scopeOwned?: boolean }) {
+		this.#scopeOwned = options?.scopeOwned === true;
+	}
 	writes: TransactionWrite[] = []; // the set of writes to commit if the conditions are met
 	// the last staged write per store and key, used to chain repeat writes to the same key (linkWrite)
 	declare writesByKey?: Map<any, Map<unknown, TransactionWrite>>;
@@ -350,6 +367,11 @@ export class DatabaseTransaction implements Transaction {
 	timeoutBudget = 0;
 	// save() only stages here; ImmediateTransaction overrides it to commit, which addWrite must not defer
 	saveCommits = false;
+	// True where save() puts the write into this transaction's native handle, which is what lets a scope
+	// take over a write staged in another transaction's `writes` (Table.ts's #saveOperation).
+	// LMDBTransaction's save() is a no-op — its commit applies `writes` — so there a write can only be
+	// committed by the transaction that holds it.
+	stagesWriteOnSave = true;
 	validated = 0;
 	timestamp = 0;
 	retries = 0;
@@ -391,6 +413,11 @@ export class DatabaseTransaction implements Transaction {
 	// Set once the retained read handle's write intents have been released (see commit()'s
 	// outstanding-iterators branch), so a retry round cannot re-fire the release.
 	declare writesAbandoned?: boolean;
+	// Set once a mid-scope commit has rotated this instance to a new generation: every native
+	// transaction it opens from then on reads WITHOUT a snapshot. Committing mid-scope is how a handler
+	// asks to stop reading a pinned snapshot, so re-pinning one for the rest of the scope would take
+	// back what it asked for.
+	snapshotFree = false;
 
 	getReadTxn(disableSnapshot?: boolean): ReadTransaction {
 		this.readTxnRefCount = (this.readTxnRefCount || 0) + 1;
@@ -417,7 +444,12 @@ export class DatabaseTransaction implements Transaction {
 		// snapshot that blocks compaction. Only applied when creating the transaction fresh; an
 		// already-open transaction keeps whatever snapshot mode it was created with.
 		// `coordinatedRetry` signals IsBusy write conflicts as RETRY_NOW rather than ERR_BUSY.
-		this.attachOwnedTransaction(new RocksTransaction(this.db.store, { coordinatedRetry: true, disableSnapshot }));
+		this.attachOwnedTransaction(
+			new RocksTransaction(this.db.store, {
+				coordinatedRetry: true,
+				disableSnapshot: disableSnapshot || this.snapshotFree,
+			})
+		);
 
 		if (this.timestamp) {
 			this.transaction.setTimestamp(this.timestamp);
@@ -569,11 +601,47 @@ export class DatabaseTransaction implements Transaction {
 		writesForStore.set(keyId, operation);
 	}
 
+	/**
+	 * Drop a staged write from this transaction, and from its per-key chain, so the transaction taking it
+	 * over becomes its only owner (Table.ts's #saveOperation).
+	 */
+	detachWrite(operation: TransactionWrite): void {
+		const index = this.writes.indexOf(operation);
+		if (index > -1) this.writes[index] = null;
+		if (operation.key === undefined) return;
+		const writesForStore = this.writesByKey?.get(operation.store);
+		if (!writesForStore) return;
+		const keyId = writeKeyId(operation.key);
+		// Membership, not `stagedIn`, which every commit handler clears and so cannot tell a takeover from a
+		// write done in place; a prior already taken over must not become this transaction's basis again.
+		let prior = operation.priorWrite;
+		while (prior && !this.writes.includes(prior)) prior = prior.priorWrite;
+		const tail = writesForStore.get(keyId);
+		if (tail === operation) {
+			if (prior) writesForStore.set(keyId, prior);
+			else writesForStore.delete(keyId);
+			return;
+		}
+		// A successor left chained to it would take its merge basis and index diff from a record another
+		// transaction owns and may roll back (harper#1968's failure class).
+		for (let successor = tail; successor; successor = successor.priorWrite) {
+			if (successor.priorWrite === operation) {
+				successor.priorWrite = prior;
+				return;
+			}
+		}
+	}
+
 	/**
 	 * Discard the staged write set (committed or aborted); the per-key chain must go with it so a
 	 * reused transaction never bases a write on a previous batch's staged state.
 	 */
 	clearWrites(): void {
+		// A deferred write's `stagedIn` must not outlive this transaction's ability to commit it: save() can
+		// fire after a commit or abort, and routing it back here would revive a write this transaction
+		// already rolled back — whose blobs abort() has reclaimed. Cleared here, save() resolves the
+		// context's current transaction as it did before `stagedIn` existed.
+		for (const write of this.writes) if (write?.stagedIn === this) write.stagedIn = undefined;
 		this.writes = [];
 		this.writesByKey = undefined;
 	}
@@ -708,6 +776,7 @@ export class DatabaseTransaction implements Transaction {
 		this.writeTimeout = this.timeout;
 		this.linkWrite(operation);
 		this.writes.push(operation);
+		operation.stagedIn = this;
 		// Hold this write back while any earlier same-key write has not run — out of staging order both
 		// diff against the pre-transaction record (harper#2211, DESIGN.md). The whole chain, not just the
 		// immediate link: an eager non-chaining write in between would otherwise launder the deferral.
@@ -743,7 +812,10 @@ export class DatabaseTransaction implements Transaction {
 		if (!transaction && this.open === TRANSACTION_STATE.OPEN) transaction = this.transaction;
 		let immediateCommit = false;
 		if (!transaction) {
-			transaction = new RocksTransaction(operation.store.store as RocksStore);
+			transaction = new RocksTransaction(
+				operation.store.store as RocksStore,
+				this.snapshotFree ? SNAPSHOT_FREE : undefined
+			);
 			if (operation.store.rootStore !== this.db.rootStore) {
 				harperLogger.warn?.('Created new transaction in save, but the store does match existing store', transaction.id);
 			}
@@ -783,7 +855,7 @@ export class DatabaseTransaction implements Transaction {
 		if (!operation.saved) {
 			operation.saved = true;
 			// immediately execute in this transaction
-			if ((operation.validate?.(txnTime) as any) === false) {
+			if ((operation.validate?.(txnTime, this) as any) === false) {
 				operation.commit = () => {}; // noop if we try again
 				return;
 			}
@@ -831,6 +903,13 @@ export class DatabaseTransaction implements Transaction {
 					// check just in case we got any more transactions while we were waiting, if so just recursively continue to finish the additional writes now
 					return this.commit(options);
 				}
+				// The save loop above can be what opened this transaction's native handle — save() attaches
+				// one when it had none, which is every ImmediateTransaction commit since its getReadTxn
+				// opens none — leaving the local captured before the loop empty while that handle holds
+				// every staged write, for the detach below to drop uncommitted (issue #2288). Only when
+				// the local is empty: a truthy one is what the loop staged into, and the retained-handle
+				// and replay branches below deliberately commit a handle other than this.transaction.
+				if (!transaction) transaction = this.transaction;
 				this.open = TRANSACTION_STATE.CLOSED;
 				// RocksTransaction.commit() resolves with RETRY_NOW_VALUE (a number) under
 				// coordinatedRetry, or void on a normal commit/abort.
@@ -1024,15 +1103,27 @@ export class DatabaseTransaction implements Transaction {
 							// now reset transactions tracking; this transaction be reused and committed again
 							this.retries = 0; // reset per-native-transaction retry counter so a reused DatabaseTransaction's next batch starts fresh
 							this.clearWrites();
+							if (options.doneWriting) this.endScopeOwnership();
 							this.releaseContext(!!options.doneWriting);
-							this.next = null;
 							let txnTime = this.timestamp;
 							this.timestamp = 0; // reset the timestamp as well
-							return Promise.all(completions).then(() => {
-								return {
-									txnTime,
-								};
-							});
+							return Promise.all(completions).then(
+								() => {
+									// Only once the chained store's commit has settled, as on the synchronous path: a
+									// partially failed mid-scope commit must not leave the scope resumable.
+									this.completeMidScopeCommit(options);
+									return {
+										txnTime,
+									};
+								},
+								(error) => {
+									// As on the synchronous path: a completion that failed (a chained store's commit,
+									// a replication confirmation) leaves this commit partly landed, so ownership goes
+									// with it rather than letting a later commit rotate on top.
+									this.endScopeOwnership();
+									throw error;
+								}
+							);
 						},
 						(error) => {
 							// Coordinated transactions surface conflicts as RETRY_NOW (handled in the
@@ -1110,6 +1201,9 @@ export class DatabaseTransaction implements Transaction {
 								// back-reference here too, or transaction.ts's onComplete() (which has no
 								// rejection handler of its own) would leave a long-lived context pinning this
 								// CLOSED wrapper forever.
+								// A failed commit must never be followed by a resumed segment: this generation is
+								// finished and its durability is unknown, so ownership goes with it.
+								this.endScopeOwnership();
 								this.releaseContext(!!options.doneWriting);
 								throw error;
 							}
@@ -1121,6 +1215,7 @@ export class DatabaseTransaction implements Transaction {
 						cleanupUnusedBlobs(write.savedBlobs, collectRetainedFileIds(write.store.getEntry(write.key)?.value));
 				}
 				this.clearWrites();
+				if (options.doneWriting) this.endScopeOwnership();
 				this.releaseContext(!!options.doneWriting);
 				const txnResolution: CommitResolution = {
 					txnTime: this.timestamp,
@@ -1129,16 +1224,39 @@ export class DatabaseTransaction implements Transaction {
 					// now run any other transactions
 					options.timestamp = this.timestamp;
 					// as above: the next store must not inherit this store's explicit native transaction
-					const nextResolution = this.next?.commit(
-						options.transaction ? { ...options, transaction: undefined } : options
-					);
+					let nextResolution;
+					try {
+						nextResolution = this.next?.commit(options.transaction ? { ...options, transaction: undefined } : options);
+					} catch (error) {
+						// A synchronous throw reaches neither rejection handler below, and the head has already
+						// committed — surrender ownership here too, or the scope stays resumable on top of a
+						// half-landed multi-store commit.
+						this.endScopeOwnership();
+						throw error;
+					}
 					if ((nextResolution as any)?.then)
-						return (nextResolution as any)?.then((nextResolution) => ({
-							txnTime: this.timestamp,
-							next: nextResolution,
-						}));
+						return (nextResolution as any)?.then(
+							(nextResolution) => {
+								// Only once the chained store's own commit has SETTLED: rotating first would leave the
+								// scope resumable after a partially failed mid-scope commit.
+								this.completeMidScopeCommit(options);
+								return {
+									txnTime: this.timestamp,
+									next: nextResolution,
+								};
+							},
+							(error) => {
+								// A chained store's commit failed, so this multi-store commit half-landed. Surrender
+								// ownership as the head's own failure branch does: a handler that catches this and
+								// commits again must not rotate on top of it, and must not have the failed link
+								// dropped from the chain before its abort can clean up its blobs.
+								this.endScopeOwnership();
+								throw error;
+							}
+						);
 					txnResolution.next = nextResolution as any;
 				}
+				this.completeMidScopeCommit(options);
 				return txnResolution;
 			},
 			(error) => {
@@ -1147,6 +1265,44 @@ export class DatabaseTransaction implements Transaction {
 			}
 		);
 	}
+	/**
+	 * A successful commit that is NOT the scope's final one leaves the scope still running and still
+	 * responsible for a commit. Rotate to a fresh OPEN generation so the rest of the scope's writes
+	 * stage into it and are committed — or rolled back — as one unit, instead of each committing itself
+	 * the moment it is made. Every dispatch path keeps its plain `open === OPEN` check; CLOSED never
+	 * gains a second meaning.
+	 *
+	 * Deliberately not rotated when: the scope is finished (`doneWriting`), nothing owns this instance,
+	 * a timeout poisoned it, or a commit failed — a failed or uncertain commit must never be followed by
+	 * a resumed segment that can commit on its own. Nor when read iterators still hold the native
+	 * handle: that handle belongs to them until they drain, so there is nothing to rotate into and those
+	 * writes keep today's immediate-commit path.
+	 */
+	/**
+	 * Finish a commit: the chain goes with it, then the scope may rotate. A link left attached and CLOSED
+	 * would be reused by txnForContext for the next write to that database and commit itself, surviving a
+	 * rollback of the rotated head — the cross-store leftover this rotation exists to prevent. Every
+	 * commit path must run this, and none may do one half without the other.
+	 */
+	/** Both scope flags leave together, so no exit can clear one and keep the other. */
+	private endScopeOwnership(): void {
+		this.#scopeOwned = false;
+		this.snapshotFree = false;
+	}
+
+	private completeMidScopeCommit(options: CommitOptions): void {
+		this.next = null;
+		this.rotateAfterMidScopeCommit(options);
+	}
+
+	/** See completeMidScopeCommit, which is the only caller and carries the reasoning. */
+	private rotateAfterMidScopeCommit(options: CommitOptions): void {
+		if (options.doneWriting || this.timedOut || this.transaction || !this.#scopeOwned) return;
+		this.open = TRANSACTION_STATE.OPEN;
+		this.snapshotFree = true;
+		this.writesAbandoned = false;
+	}
+
 	abort(): void {
 		while (this.readTxnsUsed > 0) this.doneReadTxn(); // release the read snapshot when we abort, we assume we don't need it
 		// Defensively release any native handle whose reference bookkeeping was already consumed.
@@ -1159,6 +1315,7 @@ export class DatabaseTransaction implements Transaction {
 					cleanupUnusedBlobs(write.savedBlobs, collectRetainedFileIds(write.store.getEntry(write.key)?.value));
 			}
 		} finally {
+			this.endScopeOwnership(); // the scope is over; nothing may rotate this instance again
 			this.clearWrites();
 			// A timeout-poisoned abort (abortDueToTimeout()) is the one abort that is NOT "reuse-free":
 			// Resource.ts's dispatcher deliberately keeps joining a `timedOut` transaction (instead of
@@ -1382,6 +1539,19 @@ export function isReleasedTransaction(value: unknown): boolean {
 	return value === RELEASED_TRANSACTION;
 }
 
+/**
+ * Whether this transaction can be joined as the atomic scope resources/transaction.ts promises. OPEN is
+ * not sufficient: an ImmediateTransaction commits every write as it is made, so a caller that joined one
+ * would get per-write autocommit with no final commit or abort to roll back to. txnForContext installs
+ * one in a context slot that is empty or holds the released placeholder, where it reports OPEN with
+ * nothing owning a commit for it (#2292). Ownership itself is deliberately not the test — a context
+ * pre-seeded with an externally driven DatabaseTransaction (replayLogs.ts) still owns the writes it is
+ * given, and its own commit/abort still governs them.
+ */
+export function isJoinableScope(transaction: DatabaseTransaction | null | undefined): boolean {
+	return transaction?.open === TRANSACTION_STATE.OPEN && !transaction.saveCommits;
+}
+
 let timer;
 
 /**

package/resources/LMDBTransaction.ts

@@ -25,6 +25,7 @@ export function replicationConfirmation(callback) {
 }
 
 export class LMDBTransaction extends DatabaseTransaction {
+	stagesWriteOnSave = false;
 	#context: Context;
 	writes: TransactionWrite[] = []; // the set of writes to commit if the conditions are met
 	validated = 0;
@@ -97,6 +98,9 @@ export class LMDBTransaction extends DatabaseTransaction {
 			const immediateTxn = new ImmediateTransaction(this.db);
 			immediateTxn.addWrite(operation);
 			const result = immediateTxn.commit({});
+			// Nothing may be sent back to this throwaway: the write is already committed, and its
+			// durability is the promise below.
+			operation.stagedIn = undefined;
 			if (result?.then) {
 				operation.promise = result;
 			} else {
@@ -107,6 +111,7 @@ export class LMDBTransaction extends DatabaseTransaction {
 
 		this.linkWrite(operation);
 		this.writes.push(operation); // standard path, add to current transaction
+		operation.stagedIn = this;
 	}
 
 	removeWrite(operation: TransactionWrite) {
@@ -133,7 +138,7 @@ export class LMDBTransaction extends DatabaseTransaction {
 				this.validated = this.writes.length;
 				for (let i = start; i < this.validated; i++) {
 					const write = this.writes[i];
-					write?.validate?.(this.timestamp);
+					write?.validate?.(this.timestamp, this);
 				}
 				let hasBefore;
 				for (let i = start; i < this.validated; i++) {
@@ -342,6 +347,7 @@ export class LMDBTransaction extends DatabaseTransaction {
 }
 
 export class ImmediateTransaction extends LMDBTransaction {
+	saveCommits = true;
 	constructor(db: RootDatabaseKind) {
 		super();
 		this.db = db;

package/resources/Resource.ts

@@ -12,8 +12,8 @@ import {
 import { randomUUID } from 'crypto';
 import {
 	DatabaseTransaction,
+	isJoinableScope,
 	isReleasedTransaction,
-	TRANSACTION_STATE,
 	type Transaction,
 } from './DatabaseTransaction.ts';
 import { IterableEventQueue } from './IterableEventQueue.ts';
@@ -769,9 +769,10 @@ function transactional(
 			if (isCollection) resourceOptions.isCollection = true;
 		} else resourceOptions = options;
 		const loadAsInstance = this.loadAsInstance;
-		// Only join an existing transaction if it is still genuinely OPEN (mirrors the reuse check
-		// resources/transaction.ts's transaction() helper already applies to itself). A `context`
-		// object can carry a *stale* `.transaction` left over from an earlier, unrelated call that
+		// Only join an existing transaction that can actually be a scope (isJoinableScope: OPEN, and it
+		// stages its writes rather than committing each one — the same gate resources/transaction.ts's
+		// transaction() helper applies to itself). Beyond that, a `context` object can carry a *stale*
+		// `.transaction` left over from an earlier, unrelated call that
 		// already ran to completion: ambient contexts obtained via contextStorage.getStore() are
 		// no longer guaranteed to be fresh, one-shot objects now that processLocalTransaction (#1591/
 		// #1592) installs one shared, long-lived context for the lifetime of an entire operation
@@ -795,7 +796,7 @@ function transactional(
 		//    starting fresh) makes the write throw transactionOpenTooLongError via addWrite()/commit()'s
 		//    poison check, correctly propagating the abort to the caller. See
 		//    integrationTests/resources/txn-overtime-atomicity.test.ts.
-		if (context?.transaction?.open === TRANSACTION_STATE.OPEN || context?.transaction?.timedOut) {
+		if (isJoinableScope(context?.transaction) || context?.transaction?.timedOut) {
 			// we are already in a transaction (or it was poisoned by a timeout abort and must fail), proceed
 			const resource = this.getResource(query, context, resourceOptions);
 			return resource.then

package/resources/ResourceInterface.ts

@@ -75,6 +75,26 @@ export interface Context {
 	 * so code that commits mid-handler can keep using its context. LMDBTransaction does not release,
 	 * so there the completed transaction itself stays in the slot — also safe to call, but retained.
 	 * `null` was the previous released marker and is still accepted defensively.
+	 *
+	 * A read that resolves a transaction without going through the static-API wrappers (an instance load,
+	 * for one) replaces a released or never-set slot with an ImmediateTransaction, which commits every
+	 * write as it is made. `transaction()` and the static API start their own scope rather than joining
+	 * that, so an explicit `transaction()` is atomic on a released slot as it is on a fresh one.
+	 *
+	 * A transaction its own handler commits mid-scope is rotated to a fresh open generation, so the rest
+	 * of that scope's writes are committed — or rolled back — with the scope's final commit rather than
+	 * each committing itself immediately. Two cases keep the older per-write behavior: a commit made
+	 * while a read iterator still holds the transaction's handle (that handle is the iterator's until it
+	 * drains), and a commit that failed. LMDB has always behaved this way; the RocksDB path now matches.
+	 *
+	 * The engines still differ on reads. A rotated RocksDB generation is snapshot-free, so the rest of
+	 * the scope keeps seeing other writers' committed data — which is what committing mid-scope asks for.
+	 * LMDB cannot open a snapshot-free read transaction, so there the scope keeps its snapshot.
+	 *
+	 * Because the writes after a mid-scope commit stage rather than commit one at a time, a single
+	 * mid-scope commit does not bound how much a long handler holds in memory. A handler streaming a
+	 * large volume should keep committing (a checkpoint every N records), which commits each batch and
+	 * rotates again.
 	 */
 	transaction?: DatabaseTransaction | null;
 	/**	 If the operation that will be performed with this context should check user authorization	 */

package/resources/Table.ts

@@ -36,6 +36,7 @@ import {
 	DatabaseTransaction,
 	ImmediateTransaction,
 	priorStagedWrite,
+	isJoinableScope,
 	isReleasedTransaction,
 	TRANSACTION_STATE,
 	writeKeyId,
@@ -1873,7 +1874,28 @@ export function makeTable(options) {
 		}
 		#saveOperation(operation: any) {
 			const transaction = txnForContext(this.getContext());
-			if (transaction.save) return transaction.save(operation) || operation.promise || operation.result;
+			const holder = operation.stagedIn;
+			// never-drop-on-conflict lives on the transaction and would not travel with the write, so an
+			// apply or a replay keeps it (harper-pro#348)
+			const holderOwnsPolicy = holder?.sourceApply || holder?.isReplay;
+			// stagesWriteOnSave: LMDBTransaction's addWrite never runs the write (its commit applies
+			// `writes`), so handing it one is a dead end
+			if (
+				holder &&
+				holder !== transaction &&
+				!holderOwnsPolicy &&
+				transaction.stagesWriteOnSave &&
+				isJoinableScope(transaction)
+			) {
+				holder.detachWrite(operation);
+				// The basis chain belongs to the holder: derived from a write this scope cannot commit, the
+				// merge and index diff would be relative to a record that may never land.
+				operation.priorWrite = undefined;
+				operation.deferSave = false;
+				return when(transaction.addWrite(operation), () => operation.promise ?? operation.result);
+			}
+			const owner = holder ?? transaction;
+			if (owner.save) return owner.save(operation) || operation.promise || operation.result;
 		}
 
 		addTo(property: any, value: any) {
@@ -2314,11 +2336,11 @@ export function makeTable(options) {
 				nodeName: (context as any)?.nodeName,
 				fullUpdate,
 				deferSave: true,
-				validate: (txnTime) => {
+				validate: (txnTime, committedBy = transaction) => {
 					if (!recordUpdate) recordUpdate = this.#changes;
 					if (fullUpdate || (recordUpdate && hasChanges(this.#changes === recordUpdate ? this : recordUpdate))) {
 						if (!(context as any)?.source) {
-							transaction.checkOverloaded();
+							committedBy.checkOverloaded();
 							// A record must be a plain object. Reject primitive, string/number, bare-binary,
 							// and bare-array roots — e.g. a raw Buffer from an application/octet-stream PUT, a
 							// JSON string/number body, or a top-level JSON array. Such roots carry no primary
@@ -2356,7 +2378,7 @@ export function makeTable(options) {
 							// by replayLogs). Records were valid when originally written; post-crash schema
 							// evolution (e.g. newly required fields) must not prevent replaying them
 							// (harper#1316, facet b).
-							if (!transaction.isReplay) this.validate(recordUpdate, !fullUpdate);
+							if (!committedBy.isReplay) this.validate(recordUpdate, !fullUpdate);
 							if (updatedTimeProperty) {
 								recordUpdate[updatedTimeProperty.name] =
 									updatedTimeProperty.type === 'Date'
@@ -2391,7 +2413,7 @@ export function makeTable(options) {
 							// TODO: else freeze after we have applied the changes
 						}
 					} else {
-						(transaction as any).removeWrite?.(write);
+						(committedBy as any).removeWrite?.(write);
 						return false;
 					}
 				},
@@ -2434,6 +2456,7 @@ export function makeTable(options) {
 					let incrementalUpdateToApply: boolean;
 
 					this.#savingOperation = null;
+					write.stagedIn = undefined; // nothing may pin this write's transaction past its commit
 					let omitLocalRecord = false;
 					// we use optimistic locking to only commit if the existing record state still holds true.
 					// this is superior to using an async transaction since it doesn't require JS execution
@@ -5645,10 +5668,33 @@ export function makeTable(options) {
 				// See if this is a transaction for our database and if so, use it
 				if (transaction.db?.path === primaryStore.path) return transaction;
 				// try the next one:
-				const nextTxn = transaction.next;
+				let nextTxn = transaction.next;
+				// A self-committing link is CLOSED once it has committed, and a further write through it
+				// commits on a native handle nothing awaits (#2323). Spent — closed, handle detached, none of
+				// its OWN writes left (hasPendingWrites walks successors, which is not this question) — it
+				// holds nothing, so drop it. A run of them can be spent, hence the loop. A timeout-poisoned
+				// link is kept: reusing it is what makes the rest of the operation fail atomically (#1411).
+				while (
+					nextTxn?.saveCommits &&
+					nextTxn.open !== TRANSACTION_STATE.OPEN &&
+					!nextTxn.timedOut &&
+					!nextTxn.transaction &&
+					!nextTxn.writes.some((write) => write)
+				) {
+					transaction.next = nextTxn.next;
+					nextTxn = transaction.next;
+				}
 				if (!nextTxn) {
 					// no next one, then add our database
-					transaction.next = isRocksDB ? new DatabaseTransaction() : new LMDBTransaction();
+					// A staging link under a self-committing head is committed only if the head's own database
+					// is written again and cascades the chain, so a handler writing this one last loses it (#2292).
+					transaction.next = transaction.saveCommits
+						? ((isRocksDB
+								? new ImmediateTransaction(primaryStore as any)
+								: new ImmediateLMDBTransaction(primaryStore as any)) as any)
+						: isRocksDB
+							? new DatabaseTransaction()
+							: new LMDBTransaction();
 					// The chain root, so a link that only ever receives a blind write is supervised by the
 					// long-transaction monitor as part of its logical transaction rather than as its own
 					// timeout root (issue #2231).
@@ -5667,8 +5713,14 @@ export function makeTable(options) {
 					// commit is tracked with its own identity (DatabaseTransaction.ts's trackOutstandingCommit),
 					// so a wedged second-store commit is named just as precisely as a wedged first one.
 					transaction.next.startedFrom = transaction.startedFrom;
-					if (transaction.open === TRANSACTION_STATE.CLOSED) {
+					// A second database joined after a mid-scope commit belongs to the same snapshot-free
+					// generation as the head, or its reads would re-pin what the commit just unpinned.
+					transaction.next.snapshotFree = transaction.snapshotFree;
+					if (transaction.open === TRANSACTION_STATE.CLOSED && !transaction.next.saveCommits) {
 						// if the current transaction is already closed, we need to retain that state on new databases we work with
+						// Never onto a self-committing link: CLOSED is what routes its first write through the
+						// commit re-entry that drops the native commit promise (#2323), and it commits per write
+						// regardless of this state.
 						transaction.next.open = TRANSACTION_STATE.CLOSED;
 					}
 					transaction = transaction.next;