@harperfast/harper 5.3.2 → 5.3.3

package/resources/Resource.ts

@@ -1099,7 +1099,7 @@ export function allowedMethods(resource: any) {
  */
 function selectFromObject(object, propertyResolvers, context) {
 	// TODO: eventually we will do aggregate functions here
-	const record = object.getRecord?.();
+	const record = typeof object.getRecord === 'function' ? object.getRecord() : undefined;
 	if (record) {
 		const ownData = object.getChanges?.();
 		return (property) => {
@@ -1109,25 +1109,36 @@ function selectFromObject(object, propertyResolvers, context) {
 			}
 			if (ownData && property in ownData) {
 				return ownData[property];
-			} else if ((resolver = propertyResolvers?.[property])) {
+			} else if (
+				propertyResolvers &&
+				Object.hasOwn(propertyResolvers, property) &&
+				(resolver = propertyResolvers[property])
+			) {
 				return resolver(object, context);
 			} else return record[property];
 		};
 	} else if (propertyResolvers) {
 		return (property) => {
-			const resolver = propertyResolvers[property];
-			return resolver ? resolver(object, context) : object[property];
+			const resolver = Object.hasOwn(propertyResolvers, property) ? propertyResolvers[property] : undefined;
+			if (resolver) return resolver(object, context);
+			const value = object[property];
+			return typeof value === 'function' ? undefined : value;
+		};
+	} else
+		return (property) => {
+			const value = object[property];
+			return typeof value === 'function' ? undefined : value;
 		};
-	} else return (property) => object[property];
 }
 export function transformForSelect(select, resource) {
-	const propertyResolvers = resource.propertyResolvers;
-	const context = resource.getContext?.();
+	const propertyResolvers = resource?.propertyResolvers;
+	const context = resource?.getContext?.();
 	let subTransforms;
 	if (typeof select === 'string')
 		// if select is a single string then return property value
 		return function transform(object) {
-			if (object.then) return object.then(transform);
+			if (object == null || (!resource && typeof object !== 'object')) return object;
+			if (typeof object.then === 'function') return object.then(transform);
 			if (Array.isArray(object)) return object.map(transform);
 			return selectFromObject(object, propertyResolvers, context)(select);
 		};
@@ -1135,7 +1146,8 @@ export function transformForSelect(select, resource) {
 		// if it is an array, return an array
 		if (select.asArray)
 			return function transform(object) {
-				if (object.then) return object.then(transform);
+				if (object == null || (!resource && typeof object !== 'object')) return object;
+				if (typeof object.then === 'function') return object.then(transform);
 				if (Array.isArray(object)) return object.map(transform);
 				const results = [];
 				const getProperty = handleProperty(selectFromObject(object, propertyResolvers, context));
@@ -1145,18 +1157,27 @@ export function transformForSelect(select, resource) {
 				return results;
 			};
 		const forceNulls = select.forceNulls;
+		const selectsPrototype = select.some((property) => (property.name || property) === '__proto__');
 		return function transform(object) {
-			if (object.then) return object.then(transform);
+			if (object == null || (!resource && typeof object !== 'object')) return object;
+			if (typeof object.then === 'function') return object.then(transform);
 			if (Array.isArray(object))
 				return object.map((value) => (value && typeof value === 'object' ? transform(value) : value));
 			// finally the case of returning objects
 			const selectedData = {};
 			const getProperty = handleProperty(selectFromObject(object, propertyResolvers, context));
+			if (selectsPrototype)
+				Object.defineProperty(selectedData, '__proto__', {
+					value: undefined,
+					writable: true,
+					enumerable: true,
+					configurable: true,
+				});
 			let promises;
 			for (const property of select) {
 				let value = getProperty(property);
 				if (value === undefined && forceNulls) value = null;
-				if (value?.then) {
+				if (typeof value?.then === 'function') {
 					if (!promises) promises = [];
 					promises.push(value.then((value) => (selectedData[property.name || property] = value)));
 				} else selectedData[property.name || property] = value;
@@ -1172,14 +1193,18 @@ export function transformForSelect(select, resource) {
 			} else if (typeof property === 'object') {
 				// TODO: Handle aggregate functions
 				if (property.name) {
-					if (!subTransforms) subTransforms = {};
+					const value = getProperty(property.name);
+					if (!value || typeof value !== 'object' || value instanceof Date) return value;
+					if (!subTransforms) subTransforms = Object.create(null);
 					// TODO: Get the resource, cache this transform, and apply above
 					let transform = subTransforms[property.name];
 					if (!transform) {
-						const resource = propertyResolvers[property.name]?.definition?.tableClass;
+						const resource =
+							propertyResolvers && Object.hasOwn(propertyResolvers, property.name)
+								? propertyResolvers[property.name]?.definition?.tableClass
+								: undefined;
 						transform = subTransforms[property.name] = transformForSelect(property.select || property, resource);
 					}
-					const value = getProperty(property.name);
 					return transform(value);
 				} else return getProperty(property);
 			} else return property;

package/resources/RocksTransactionLogStore.ts

@@ -167,6 +167,7 @@ export class RocksTransactionLogStore extends EventEmitter {
 			};
 		}
 		log.addEntry(entryBinary, options.transaction.id);
+		options.transaction.hasStagedLog = true;
 	}
 
 	/** A log holds one origin, which keeps `txnLogKey` unique within it; see resources/DESIGN.md. */

package/resources/Table.ts

@@ -4331,7 +4331,9 @@ export function makeTable(options): TableResourceClass {
 			return this;
 		}
 		/**
-		 * Release the lock this instance holds. Resolves true when this call cleared the native key lock.
+		 * Release the lock this instance holds. Resolves true when this call cleared the native key lock;
+		 * false when it was already released, or when a commit of this lock's writes is still in flight
+		 * and the native key is returned once that commit settles.
 		 * Works for both held (`{ hold: true }`) and transaction-scoped locks. After unlock() the
 		 * instance is no longer lock-writable; writes through it require a fresh lock.
 		 */
@@ -4639,7 +4641,13 @@ export function makeTable(options): TableResourceClass {
 					}
 				},
 				before: writeToSource(),
-				commit: (txnTime: number, existingEntry: Entry, retry: boolean, transaction: any) => {
+				commit: (
+					txnTime: number,
+					existingEntry: Entry,
+					retry: boolean,
+					transaction: any,
+					committedBy?: DatabaseTransaction
+				) => {
 					// Whether a prior attempt of THIS write appended its own audit entry (sticky, set in
 					// save(); log entries are not part of the aborted rocks transaction, so they survive).
 					// Only such a write can find its own orphaned entry in the dedup lookups below and must
@@ -4730,6 +4738,19 @@ export function makeTable(options): TableResourceClass {
 						let belowAuditFloor = false;
 						let dedupVersionCouldBeRetained: (version: number) => boolean;
 						if (audit) {
+							if (
+								stagedOwnAuditEntry &&
+								committedBy?.sourceApply &&
+								isRocksDB &&
+								!replaying &&
+								precedesExisting === 0 &&
+								txnLogKey === txnTime &&
+								(existingEntry.nodeId ?? 0) === (options?.nodeId ?? getThisNodeId(auditStore)) &&
+								!existingEntry.additionalAuditRefs?.length
+							) {
+								write.skipped = true;
+								return;
+							}
 							// A re-delivered out-of-order write (full-copy audit-replay re-delivers writes) must not have
 							// its commutative ops re-folded. additionalAuditRefs is the record's own list of folded
 							// out-of-order versions, read with read-your-writes consistency, so this skips the duplicate up
@@ -7932,6 +7953,7 @@ export function makeTable(options): TableResourceClass {
 				},
 			};
 			propertyResolvers.$highlights.directReturn = true;
+			primaryKeyAttribute = undefined;
 			for (const attribute of this.attributes) {
 				if (attribute.isPrimaryKey) primaryKeyAttribute = attribute;
 				attribute.resolve = null; // reset this

package/resources/analytics/DESIGN.md

@@ -36,3 +36,20 @@ Still open: `findLastAggregationTime` seeds both markers after a restart from th
 analytics record, whose `time` is an end-of-cycle stamp, so a restart mid-drain can skip the rest of
 the backlog; and `storeMetric` discards `table.put()`'s result, so the cursor advances past raw
 records whose aggregate rows failed to commit. Both need a cursor persisted with the rows.
+
+## Aggregation folds each measure over only the samples that carry it (`resources/analytics/write.ts`)
+
+A key's raw samples need not carry the same measures: callback metrics (`recordAction(fn)`) and
+analytics listeners report whatever fields they have, and a raw backlog can come from another
+version. `aggregation()` keeps, per fold target (an action, or one thread's record for `byThread`
+metrics), the count of samples that carried each measure in the cycle-local `measureCounts` map —
+not on the action, which `storeMetric` persists and aggregate listeners receive. A measure's first
+sample seeds it, `max[A-Z]`-named measures fold with `Math.max`, and the rest are a running mean
+weighted by that count. A measure in every sample has a count equal to the target's `count`, so it
+folds exactly as before; keep the running mean, since sum-then-divide rounds differently.
+
+The `byThread` combination sums every thread record's numeric fields into the entry, so a measure
+the key's first sample lacked, or that only some threads carry, is kept. That holds only while a
+thread record carries nothing but measures and its `count`, which the thread count then replaces:
+the fold keeps `total`/`ratio` on non-thread actions only, so a `ratio` on a thread record is
+always a caller's measure.

package/resources/analytics/write.ts

@@ -967,6 +967,8 @@ async function aggregation(fromPeriod, toPeriod = 60000) {
 	const aggregateActions = new Map();
 	const distributions = new Map();
 	const threadsToAverage = [];
+	// A measure's weight is the count of only the samples that carried it, per action or thread record.
+	const measureCounts = new Map<object, Record<string, number>>();
 	let lastTime: number | undefined;
 	let stoppedAtWindowEdge = false;
 	for (const { key, value } of rawAnalyticsTable.primaryStore.getRange({
@@ -992,7 +994,8 @@ async function aggregation(fromPeriod, toPeriod = 60000) {
 			if (type !== undefined) key += '-' + type;
 			let action = aggregateActions.get(key);
 			if (action) {
-				if (action.threads) {
+				const byThread = Boolean(action.byThread);
+				if (byThread) {
 					const actionForThread = action.threads[threadId];
 					if (actionForThread) action = actionForThread;
 					else {
@@ -1001,17 +1004,27 @@ async function aggregation(fromPeriod, toPeriod = 60000) {
 					}
 				}
 				if (!action.count) action.count = 1;
-				const previousCount = action.count;
+				let counts = measureCounts.get(action);
+				if (!counts) {
+					// Until its first fold, a target holds only its first sample.
+					counts = Object.create(null);
+					for (const measureName in action) {
+						if (typeof action[measureName] === 'number') counts[measureName] = action.count;
+					}
+					measureCounts.set(action, counts);
+				}
 				for (const measureName in measures) {
 					const value = measures[measureName];
-					if (typeof value === 'number') {
-						action[measureName] = MAX_MEASURE_NAME.test(measureName)
-							? Math.max(action[measureName], value)
-							: (action[measureName] * previousCount + value * count) / (previousCount + count);
-					}
+					if (typeof value !== 'number') continue;
+					const measureCount = counts[measureName];
+					if (measureCount === undefined) action[measureName] = value;
+					else if (MAX_MEASURE_NAME.test(measureName)) action[measureName] = Math.max(action[measureName], value);
+					else action[measureName] = (action[measureName] * measureCount + value * count) / (measureCount + count);
+					counts[measureName] = (measureCount ?? 0) + count;
 				}
 				action.count += count;
-				if (total >= 0) {
+				// A thread's record is built from measures alone, so it has no total to add to.
+				if (total >= 0 && !byThread) {
 					action.total += total;
 					action.ratio = action.total / action.count;
 				}
@@ -1043,15 +1056,15 @@ async function aggregation(fromPeriod, toPeriod = 60000) {
 		let { path, method, type, metric, count, total, distribution, threads, ...measures } = entry;
 		threads = threads.filter((thread) => thread);
 		for (const measureName in measures) {
-			if (typeof entry[measureName] !== 'number') continue;
-			let total = 0;
-			for (const thread of threads) {
+			if (typeof entry[measureName] === 'number') entry[measureName] = 0;
+		}
+		// A thread can carry measures the entry's first sample lacked.
+		for (const thread of threads) {
+			for (const measureName in thread) {
 				const value = thread[measureName];
-				if (typeof value === 'number') {
-					total += value;
-				}
+				if (typeof value === 'number')
+					entry[measureName] = (typeof entry[measureName] === 'number' ? entry[measureName] : 0) + value;
 			}
-			entry[measureName] = total;
 		}
 		entry.count = threads.length;
 		delete entry.threads;

package/resources/databases.ts

@@ -654,6 +654,21 @@ const DROPPED_ROW_PREFIX = '/dropped/';
 function droppedRowKey(tableName: string): string {
 	return DROPPED_ROW_PREFIX + tableName;
 }
+/**
+ * Whether a catalog row names its table's primary store: one flagged `isPrimaryKey`, or the nameless bare
+ * `<table>/` row of a keyless table, which can lose the flag while its store still holds primary records.
+ */
+export function isPrimaryCatalogRow(key: unknown, value: any): boolean {
+	if (value?.isPrimaryKey) return true;
+	// exactly one slash, at the end: initStores reads `<table>/<attribute>` by splitting on the first slash
+	return (
+		value != null &&
+		value.name == null &&
+		typeof key === 'string' &&
+		key.length > 1 &&
+		key.indexOf('/') === key.length - 1
+	);
+}
 /**
  * Once a name has been dropped, later creates of it take a generation even after the retirement journal is
  * reclaimed. Keep the row untimed and shaped `{ table, tableId }`: later versions read it as an untimed drop
@@ -1325,7 +1340,7 @@ function initStores(
 		definedTables?.add(tableName);
 		let tableDef = tablesToLoad.get(tableName);
 		if (!tableDef) tablesToLoad.set(tableName, (tableDef = { attributes: [] }));
-		if (attribute_name == null || value.isPrimaryKey) tableDef.primary = value;
+		if (isPrimaryCatalogRow(key, value)) tableDef.primary = value;
 		if (value.dropping) tableDef.tombstone = value;
 		if (attribute_name != null) tableDef.attributes.push(value);
 		Object.defineProperty(value, 'key', { value: key, configurable: true });
@@ -1505,7 +1520,8 @@ function initStores(
 				(attributesDbi as any).putSync(NEXT_TABLE_ID, tableId + 1);
 				(attributesDbi as any).putSync(primaryAttribute.key, primaryAttribute);
 			}
-			const dbiInit = createOpenDBIObject(!primaryAttribute.isPrimaryKey, primaryAttribute.isPrimaryKey);
+			// primary by selection, not by its flag (isPrimaryCatalogRow)
+			const dbiInit = createOpenDBIObject(false, true);
 			dbiInit.compression = primaryAttribute.compression;
 			if (dbiInit.compression) {
 				const compressionThreshold =
@@ -3671,6 +3687,25 @@ function declareTable<TableResourceType>(target: TableTarget, tableDefinition: T
 			if (Table.primaryStore.rootStore.status === 'closed') {
 				throw new Error(`Can not use a closed data store from ${tableName} class`);
 			}
+			if (Table.primaryKey == null) {
+				// a keyless table cannot adopt a key without re-keying its records
+				for (const attribute of attributes) {
+					if (!attribute.isPrimaryKey) continue;
+					if (origin === 'cluster')
+						logger.warn(
+							`Ignoring peer redefinition of ${databaseName}.${tableName}.${attribute.name} ` +
+								`(isPrimaryKey: local table has no primary key, peer true)`
+						);
+					else if (schemaDefinedExplicit)
+						logger.error(
+							`Table '${databaseName}.${tableName}' has no primary key, so its declared primary key ` +
+								`'${attribute.name}' is ignored and the table stays keyless. Recreate the table with that ` +
+								`primary key, or migrate its records, to use it.`
+						);
+					delete attribute.isPrimaryKey;
+					if (properties?.[attribute.name]) delete properties[attribute.name].primaryKey;
+				}
+			}
 			// Reject moving the primary key to a different attribute on a table that already has records.
 			// The storage key (Table.primaryKey) is never re-pointed here, so honoring the change would
 			// leave describe reporting the new attribute while every record — old and newly inserted — stays
@@ -5736,7 +5771,8 @@ function completeInterruptedDrop(
 	}>;
 	const bareEntry = catalogRows.find(({ key }) => key === tableName + '/');
 	const primaryEntry =
-		(bareEntry?.value?.isPrimaryKey ? bareEntry : undefined) ?? catalogRows.find(({ value }) => value?.isPrimaryKey);
+		catalogRows.find(({ value }) => value?.isPrimaryKey) ??
+		(bareEntry && isPrimaryCatalogRow(bareEntry.key, bareEntry.value) ? bareEntry : undefined);
 	const tombstoneEntry = bareEntry ?? primaryEntry;
 	if (rootStore instanceof RocksDatabase && !fullTextRetired) {
 		const names = [
@@ -5795,7 +5831,7 @@ function completeInterruptedDrop(
 		// recreate silently inherit the previous table's records.
 		for (const { key, value } of catalogRows) {
 			const objectStorage =
-				value?.isPrimaryKey || (value?.indexed?.type && CUSTOM_INDEXES[value.indexed.type]?.useObjectStore);
+				isPrimaryCatalogRow(key, value) || (value?.indexed?.type && CUSTOM_INDEXES[value.indexed.type]?.useObjectStore);
 			const store = (rootStore as any).openDB(key, createOpenDBIObject(!objectStorage, objectStorage) as any);
 			try {
 				// dropSync (not drop): this function is synchronous, and its callers rely on

package/resources/record-locks.md

@@ -37,14 +37,24 @@ Consequences that shape the code:
   no-op. The key is `lockAttemptKey(tableId, id)` = `[LOCK_KEY_PREFIX, tableId, ...id]`, distinct from
   `getFromSource`'s bare-id single-flight lock.
 - **`RecordLockHandle`** (`recordLock.ts`) carries `store`, `key`, `keyId`, `acquiredAt`, `expiresAt`,
-  `hold`, `released`, and `expired`. `release()` is synchronous: it sets `released`, clears the lease
-  timer, and calls `store.unlock(key)`. A lease timer sets `expired = true` then calls `store.unlock()`
-  on fire; any write staged through an expired or released handle throws 409 in
-  `DatabaseTransaction.save()` before the write reaches the store — from `lockNotHeldError()`, which
-  names the actual cause, since an expired lease and a handle already released (by `unlock()` or by
-  the commit) send a caller after different bugs. `acquireRecordKey` loops
-  `tryLock` → await wake → retry until acquired or `waitMs` elapsed (then 423). The contender wait
-  timer uses `.unref()` so it does not prevent process exit.
+  `hold`, `released`, and `expired`. `release()` sets `released` and clears the lease timer; a lease
+  timer sets `expired = true` and `released = true` on fire. When no native commit is holding the
+  handle, both immediately call `store.unlock(key)` and emit `onRelease` (and `release()` returns `true`).
+  While a submitted native `RocksTransaction` is in flight (`retainForCommit(holdDeadlineMono)` called at
+  first native submission in `DatabaseTransaction.performCommit()`), `store.unlock(key)` and `onRelease`
+  are deferred (and `release()` returns `false`) until `releaseCommitHold()` releases the last commit
+  hold — at local commit landing (immediately before `releaseRecordLocks()`), in `commitOutcome`'s
+  rejection handler on any unlogged give-up, or at the commit-conflict budget boundary via
+  `noteOverdueLoggedCommit` or the handle's own hold-deadline timer when a native commit never settles
+  (harper#3236) — so a logged commit that retries past its lease cannot be overtaken by a same-node
+  contender or emit an early `LOCK_RELEASE` while within its conflict budget. `isExpired()` flips
+  immediately when the timer fires or `revokeLease()`/`release()` runs (while `isLeaseExpired()` reflects
+  only lease expiry or `revokeLease()`, not `release()`), so any new write staged through an expired or
+  released handle (and any unlogged conflict retry) throws 409 in `DatabaseTransaction.save()` or
+  `performCommit()` — from `lockNotHeldError()`, which names the actual cause, since an expired lease and
+  a handle already released (by `unlock()` or by the commit) send a caller after different bugs.
+  `acquireRecordKey` loops `tryLock` → await wake → retry until acquired or `waitMs` elapsed (then 423).
+  The contender wait timer uses `.unref()` so it does not prevent process exit.
 - **Re-entrancy is per-transaction.** `DatabaseTransaction.recordLocks` is a lazily allocated
   `Map<store, Map<keyId, handle>>` (O(1) lookup). `registerRecordLock`, `recordLockFor`, and
   `unregisterRecordLock` manage it. `lock()` consults it before calling `tryLock`; a re-entrant call
@@ -53,7 +63,8 @@ Consequences that shape the code:
 - **Release.** Every handle — scoped or hold — is registered in `link.recordLocks` and kept on the
   locked instance as `#lockHandle`; every commit or abort calls `releaseRecordLocks()`, which calls
   `handle.release()` on each non-hold handle, so a `{ hold: true }` handle outlives the transaction.
-  `unlock()` calls `handle.release()` directly (synchronous, returns false if already released).
+  `unlock()` calls `handle.release()` directly (synchronous; returns false if already released, or
+  while a commit hold defers the native unlock until the in-flight commit settles).
   `unlock()` also accepts scoped handles: it calls `release()` early and unregisters the handle so the transaction commit does
   not release it again. After any `unlock()` call `#lockWritable` is cleared so writes through the
   instance are no longer accepted. In an explicit transaction with no staged writes and no open
@@ -1066,9 +1077,12 @@ feature that has not yet been measured.
 >
 > **§2's exclusion invariant is wider than what (1) and (2) leave.** It requires a successor to
 > exclude every predecessor capability that can still admit _or commit_; what ships excludes
-> admission, and the commit half holds only up to the pre-submission expiry fence
-> (the `hasLeaseProtectedWrite` fence in `DatabaseTransaction.performCommit()`) — a native commit that clears that fence and settles
-> afterwards is limitation (2)'s third route.
+> admission, and the commit half holds up to the pre-submission expiry fence
+> (the `hasLeaseProtectedWrite` fence in `DatabaseTransaction.performCommit()`) plus, on the local
+> node and for clean recall drain, `KeyLockHandle`'s per-handle commit hold (`retainForCommit()` /
+> `releaseCommitHold()`, harper#3236) up to `commitConflictBudget()` — a native commit that clears the
+> pre-submission fence and settles past `commitConflictBudget()` (or after the home's own monotonic
+> delegation lease expires on a peer) is limitation (2)'s third route.
 >
 > **There is no caller-side mitigation for (2) — the obvious candidate is unreachable and, where it
 > is reachable, makes things worse.** `X-Replicate-To` / `confirm=` is meant to be super-user only —
@@ -1306,11 +1320,14 @@ drain and caps, §§5/6/8, plus the three inherited substrate defects in §11) a
 machine is gone, and the home ring, the delegation table, recall with §6 steps 1, 2 and 4, ordered
 fencing tokens, the caps, the §4.3 restart quarantine, the generation monotonicity floor and the
 transport-swap grant fence are in place, with all three inherited defects fixed. **§6 step 3 —
-settlement — is not implemented**: a recall revokes capability and then writes the release without
-waiting for a native commit already submitted to complete. That is exactly limitation (2)'s third
-route in §10, which the contract already states, so the gap is disclosed rather than hidden — but §6
-must not be read as fully implemented. Closing it means hanging the release hook off
-logical-transaction settlement rather than off the last admission unlocking. harper-pro#822 supplies
+settlement — is bounded by the commit-conflict budget (`retainForCommit(holdDeadlineMono)` /
+`releaseCommitHold()`, harper#3236)**: a submitted native `RocksTransaction` retains a commit hold
+on each write's `KeyLockHandle` until local commit landing (or `commitOutcome` rejection), so
+`revokeLease()` defers `store.unlock(key)` and `onRelease` (`LOCK_RELEASE` emission) while the
+commit is within `commitConflictBudget()`. Past `commitConflictBudget()`, `KeyLockHandle`'s
+`#holdTimer` (as well as `noteOverdueLoggedCommit` between retry attempts) releases the hold so a
+wedged conflict cannot pin the key forever, and a peer's own monotonic delegation lease (§5.2) can
+still expire first — which is limitation (2)'s third route in §10. harper-pro#822 supplies
 the operator-agreed home map and `establishLockFreshness()`; the feature is opt-in
 (`replication.recordLocks: true`). A `lockRelease` that reaches a non-coordinating thread is handed
 to the transport's `relayControlEntry` (harper-pro#977). Without the hook, a thread that has a

package/resources/recordLock.ts

@@ -52,10 +52,11 @@ export interface ResolvedRecordLockOptions {
 
 /**
  * The handle returned by `lock()` and held by each gated write until its transaction completes.
- * `release()` is synchronous: it calls `store.unlock(key)` which is ownerless and fires any
- * waiting callbacks cross-thread. The `expired` flag is set in the holder thread by the lease
- * timer, so a stale holder cannot accidentally call unlock after its lease already fired and
- * released the key to a new holder.
+ * `release()` is synchronous: it calls `store.unlock(key)` (or defers it while a commit hold
+ * acquired via `retainForCommit` is still active), which is ownerless and fires any waiting
+ * callbacks cross-thread. The lease timer sets `expired` in the holder thread when it fires
+ * (while a commit hold is active, only the native unlock is deferred), so a stale holder cannot
+ * accidentally call unlock after its lease already fired and released the key to a new holder.
  */
 export interface RecordLockHandle {
 	store: any;
@@ -107,7 +108,11 @@ export interface RecordLockHandle {
 	 * version has been noted; otherwise advances by the minimum monotonic step from the recorded floor.
 	 */
 	nextHolderVersion(): number;
+	/** True when this call returned the native key; false if already released, or while a commit hold defers the unlock. */
 	release(): boolean;
+	/** Defer `store.unlock(key)` until an in-flight native commit settles or `holdDeadlineMono` expires. */
+	retainForCommit?(holdDeadlineMono?: number): void;
+	releaseCommitHold?(): void;
 	/**
 	 * Flip this handle to hold mode and reset its lease timer. Used during scoped→hold upgrades
 	 * so all instances that reference this handle object remain valid (no retire + replace).
@@ -192,6 +197,10 @@ class KeyLockHandle implements RecordLockHandle {
 	// an NTP step nor a manual clock change can extend a lease past what peers assumed.
 	#deadlineMono: number | undefined;
 	#onRelease: (() => void) | undefined;
+	#commitHolds = 0;
+	#deferredUnlock = false;
+	#holdDeadlineMono: number | undefined;
+	#holdTimer: ReturnType<typeof setTimeout> | undefined;
 
 	constructor(store: any, key: any[], keyId: unknown, lease?: number, hold = false, acquiredAt?: number) {
 		this.store = store;
@@ -238,8 +247,9 @@ class KeyLockHandle implements RecordLockHandle {
 	// bound and the key may belong to someone else.
 	#leaseLapsed(): boolean {
 		if (this.#deadlineMono === undefined || performance.now() < this.#deadlineMono) return false;
-		// Finish the expiry rather than only reporting it: the native key must actually go back so a
-		// stalled holder does not keep a key every participant has already written off.
+		// Finish the expiry rather than only reporting it: once no in-flight commit holds the handle,
+		// the native key must go back so a stalled holder does not keep a key every participant has
+		// already written off.
 		if (!this.released) this.#onLeaseExpire();
 		return true;
 	}
@@ -259,8 +269,8 @@ class KeyLockHandle implements RecordLockHandle {
 		// no-op in the one state it was written for.
 		this.expired = true;
 		if (this.released) {
-			// The native key is already back and `onRelease` already fired; only the fence flag and the
-			// lease timer are left to settle.
+			// `release()` already ran (returning the native key or deferring the unlock onto an active
+			// commit hold); only the fence flag and the lease timer are left to settle.
 			clearTimeout(this.#timer);
 			return;
 		}
@@ -294,22 +304,84 @@ class KeyLockHandle implements RecordLockHandle {
 		return next;
 	}
 
-	#onLeaseExpire() {
-		if (this.released) return;
-		this.released = true;
-		this.expired = true;
-		clearTimeout(this.#timer);
+	retainForCommit(holdDeadlineMono?: number): void {
+		if (this.released && !this.#deferredUnlock) return;
+		this.#commitHolds++;
+		if (holdDeadlineMono !== undefined && Number.isFinite(holdDeadlineMono)) {
+			this.#holdDeadlineMono = Math.max(this.#holdDeadlineMono ?? holdDeadlineMono, holdDeadlineMono);
+			if (this.#deferredUnlock) this.#armHoldTimer();
+		}
+	}
+
+	releaseCommitHold(): void {
+		if (this.#commitHolds <= 0) return;
+		if (--this.#commitHolds === 0) {
+			clearTimeout(this.#holdTimer);
+			this.#holdTimer = undefined;
+			this.#holdDeadlineMono = undefined;
+			if (this.#deferredUnlock) {
+				this.#deferredUnlock = false;
+				this.#unlockAndEmitRelease('record lock deferred release failed (store may have been dropped)');
+			}
+		}
+	}
+
+	// True when the native key went back now; false when the unlock waits on the commit hold.
+	#deferOrFlushUnlock(warningMessage: string): boolean {
+		if (this.#holdDeadlineMono !== undefined && performance.now() >= this.#holdDeadlineMono) {
+			this.#commitHolds = 0;
+			this.#deferredUnlock = false;
+			this.#holdDeadlineMono = undefined;
+			clearTimeout(this.#holdTimer);
+			this.#holdTimer = undefined;
+			this.#unlockAndEmitRelease(warningMessage);
+			return true;
+		}
+		this.#deferredUnlock = true;
+		this.#armHoldTimer();
+		return false;
+	}
+
+	#armHoldTimer() {
+		clearTimeout(this.#holdTimer);
+		this.#holdTimer = undefined;
+		if (!this.#deferredUnlock || this.#holdDeadlineMono === undefined) return;
+		const remaining = Math.max(0, Math.ceil(this.#holdDeadlineMono - performance.now()));
+		this.#holdTimer = setTimeout(() => {
+			this.#holdTimer = undefined;
+			this.#commitHolds = 0;
+			this.#holdDeadlineMono = undefined;
+			if (this.#deferredUnlock) {
+				this.#deferredUnlock = false;
+				this.#unlockAndEmitRelease('record lock commit hold timer failed (store may have been dropped)');
+			}
+		}, remaining).unref();
+	}
+
+	#unlockAndEmitRelease(warningMessage: string) {
 		try {
 			this.store.unlock(this.key);
 		} catch (err) {
 			if (!warnedLeaseTimerStores.has(this.store)) {
 				warnedLeaseTimerStores.add(this.store);
-				harperLogger.warn?.('record lock lease timer failed (store may have been dropped)', err);
+				harperLogger.warn?.(warningMessage, err);
 			}
 		}
 		this.#emitRelease();
 	}
 
+	#onLeaseExpire() {
+		if (this.released) return;
+		this.released = true;
+		this.expired = true;
+		clearTimeout(this.#timer);
+		if (this.#commitHolds > 0) {
+			this.#deferOrFlushUnlock('record lock lease timer failed (store may have been dropped)');
+			return;
+		}
+		this.#unlockAndEmitRelease('record lock lease timer failed (store may have been dropped)');
+	}
+
 	// The cluster release is a durability optimization, not the safety mechanism — peers expire the
 	// hold on their own lease bound — so neither a throw nor a rejected promise may escape here. This
 	// runs from a lease timer and from post-commit cleanup, where an escaping rejection would take
@@ -331,15 +403,10 @@ class KeyLockHandle implements RecordLockHandle {
 		if (this.released) return false;
 		this.released = true;
 		clearTimeout(this.#timer);
-		try {
-			this.store.unlock(this.key);
-		} catch (err) {
-			if (!warnedLeaseTimerStores.has(this.store)) {
-				warnedLeaseTimerStores.add(this.store);
-				harperLogger.warn?.('record lock release failed (store may have been dropped)', err);
-			}
+		if (this.#commitHolds > 0) {
+			return this.#deferOrFlushUnlock('record lock release failed (store may have been dropped)');
 		}
-		this.#emitRelease();
+		this.#unlockAndEmitRelease('record lock release failed (store may have been dropped)');
 		return true;
 	}