@optimystic/db-core 0.25.1 → 0.26.0

package/src/network/struct.ts

@@ -125,12 +125,12 @@ export type BlockContentDigest = {
 export type BlockContentDigests = Record<BlockId, BlockContentDigest>;
 
 export type CommitRequest = ActionBlocks & {
-	/** The header block of the collection, if this is a new collection. Nominally "commit first" —
-	 *  but see the NOTE in `NetworkTransactor.commit`: the header-first step is unreachable from the
-	 *  only production producer of this field, so today it only affects hand-built requests. */
+	/** The header block of the collection, present only when this commit creates the collection
+	 *  (the header is a fresh insert). Collection-identifying metadata, not an ordering signal —
+	 *  the header commits inside the ordinary sweep, after the tail, like any other touched block.
+	 *  Consumed by dispute reporting (`dispute-service.ts`) as a fallback to name the collection. */
 	headerId?: BlockId;
-	/** The tail block of the log.  Nominally "commit next"; since the header-first step above never
-	 *  fires in production, this is in practice the FIRST block committed, which is the ordering
+	/** The tail block of the log. Unconditionally the first block committed — the ordering
 	 *  `Collection.bootstrapContext` relies on. */
 	tailId: BlockId;
 	/** The new revision for the committed action */

package/src/testing/index.ts

@@ -1,2 +1,3 @@
 export * from './test-transactor.js';
 export * from './async-wait.js';
+export * from './refresh-probe.js';

package/src/testing/refresh-probe.ts

@@ -0,0 +1,52 @@
+import type { Collection } from '../collection/collection.js';
+
+/** Yield the event loop through the MACROTASK queue `turns` times, so a refresh that is free to
+ *  proceed gets every chance to run its (await-heavy) course before a gate opens. A microtask
+ *  drain would not be enough: `Collection.update()` awaits real transactor reads.
+ *
+ *  NOTE: the turn count is what gives {@link releaseRefresh}'s `blocked()` assertions their teeth
+ *  — an unlatched `Collection.update()` has to be able to run to COMPLETION within these turns,
+ *  or "still pending" stops distinguishing "blocked on the latch" from "merely slow". Ten is a
+ *  ~10x margin today: with the coordinator's latch reverted locally, the refreshes in
+ *  `coordinator-latch-interleaving.spec.ts` completed on macrotask turn 1 against
+ *  `TestTransactor`. If `update()` ever grows a deeper await chain — or a caller moves onto a
+ *  transactor with real I/O — raise this rather than letting the assertion quietly weaken into a
+ *  tautology. */
+export async function drainMacrotasks(turns = 10): Promise<void> {
+	for (let i = 0; i < turns; i++) {
+		await new Promise(r => setTimeout(r, 0));
+	}
+}
+
+/** The handle {@link releaseRefresh} returns: `blocked()` reports whether the refresh is still
+ *  pending, `settle()` awaits it and rethrows whatever it rejected with. */
+export type RefreshProbe = {
+	/** Await the refresh, rethrowing its failure (captured at start time — see the note there). */
+	settle: () => Promise<void>;
+	/** True while the refresh has neither resolved nor rejected. */
+	blocked: () => boolean;
+};
+
+/** Start a refresh on `collection` and report — via the returned `blocked()` — whether it is
+ *  STILL pending.
+ *
+ *  A final-state assertion alone would also pass if the refresh had simply run to completion
+ *  harmlessly, so on its own it never proves the latch is what protected the state. This does:
+ *  checked after {@link drainMacrotasks} but before a parked commit's gate opens, a still-pending
+ *  refresh is a refresh queued behind the commit's held latch. */
+export function releaseRefresh<TAction>(collection: Collection<TAction>): RefreshProbe {
+	let done = false;
+	let failure: unknown;
+	// Both handlers attach SYNCHRONOUSLY, and the rethrowing promise is built only when the caller
+	// asks for it. The refresh sits unawaited across drainMacrotasks, so a rejection reaching the
+	// end of a turn with no handler would be a fatal unhandled rejection — killing the process
+	// instead of failing the case. Captured here, rethrown at `settle()`.
+	const captured = collection.update().then(
+		() => { done = true; },
+		(e: unknown) => { done = true; failure = e; },
+	);
+	return {
+		settle: () => captured.then(() => { if (failure !== undefined) throw failure; }),
+		blocked: () => !done,
+	};
+}

package/src/testing/test-transactor.ts

@@ -4,6 +4,7 @@ import { Latches } from "../utility/latches.js";
 import { applyTransform, blockIdsForTransforms, transformForBlockId, emptyTransforms, concatTransform, transformsFromTransform } from "../transform/index.js";
 import { Tree } from "../collections/tree/tree.js";
 import type { TreeReplaceAction } from "../collections/tree/struct.js";
+import type { Collection } from "../collection/collection.js";
 
 type RevisionNumber = number;
 
@@ -496,10 +497,10 @@ export class FlakyCommitTransactor extends DelegatingTransactor {
 
 /**
  * Commits durably on the inner {@link TestTransactor}, then reports a stale failure anyway —
- * the exact observable shape of `NetworkTransactor.commit`'s TORN ACTION: the collection header
- * and log tail are committed BEFORE the sweep of the remaining blocks, so a later sweep block
- * coming back as a confirmed conflict returns a stale failure over an action whose log entry is
- * already durable.
+ * the exact observable shape of `NetworkTransactor.commit`'s TORN ACTION: the collection's log
+ * tail is committed BEFORE the sweep of the remaining blocks, so a later sweep block coming back
+ * as a confirmed conflict returns a stale failure over an action whose log entry is already
+ * durable.
  *
  * Safe against the inner transactor's bookkeeping because `TransactorSource.transact` cancels
  * the pend on the reported failure and {@link TestTransactor.cancel} only deletes PENDING records
@@ -617,6 +618,101 @@ export class CompetingWriterTransactor extends DelegatingTransactor {
 	}
 }
 
+type Deferred = { promise: Promise<void>; resolve: () => void };
+
+function deferred(): Deferred {
+	let resolve!: () => void;
+	const promise = new Promise<void>(r => { resolve = r; });
+	return { promise, resolve };
+}
+
+/**
+ * Parks the commit AFTER the inner transactor has made it durable and BEFORE the result gets back
+ * to the coordinator — precisely the window in which storage already holds the new revision but
+ * the caller's local fold (`Collection.recordCommitted`) has not run.
+ *
+ * Everything else delegates, so the pend/commit round trip is otherwise the real one.
+ *
+ * Parks only the FIRST commit call and delegates every later one: a multi-collection commit issues
+ * one `commit` per participant, and parking all of them would mean the span never completes.
+ */
+export class GatedCommitTransactor extends DelegatingTransactor {
+	/** The `rev` carried on each pend request seen, in call order. */
+	readonly pendRevs: (number | undefined)[] = [];
+	/** The `rev` carried on each commit request seen, in call order. */
+	readonly commitRevs: number[] = [];
+	/** Resolves once a commit has landed durably in the inner transactor and is parked. */
+	readonly commitParked: Promise<void>;
+	private readonly parked = deferred();
+	private readonly gate = deferred();
+	private parkedOnce = false;
+
+	constructor(inner: TestTransactor) {
+		super(inner);
+		this.commitParked = this.parked.promise;
+	}
+
+	override async pend(request: PendRequest): Promise<PendResult> {
+		this.pendRevs.push(request.rev);
+		return this.inner.pend(request);
+	}
+
+	override async commit(request: CommitRequest): Promise<CommitResult> {
+		this.commitRevs.push(request.rev);
+		const result = await this.inner.commit(request);	// durable FIRST
+		if (!this.parkedOnce) {
+			this.parkedOnce = true;
+			this.parked.resolve();
+			await this.gate.promise;
+		}
+		return result;
+	}
+
+	openGate(): void { this.gate.resolve(); }
+}
+
+/**
+ * Parks the FIRST pend BEFORE it reaches the inner transactor, so a rival can durably take the
+ * revision while the coordinator is already committed to a set of transforms it captured at the
+ * log append.
+ *
+ * Snapshots the pair `(what was handed to the network, what the collection's tracker held)` at
+ * DELEGATION time — after the gate — for every pend, so a refresh that swapped the tracker's
+ * transforms object out from under the coordinator shows up as a divergent pair.
+ */
+export class GatedPendTransactor<TAction> extends DelegatingTransactor {
+	/** One entry per delegated pend, in call order. */
+	readonly snapshots: { pended: Transforms; staged: Transforms }[] = [];
+	/** Resolves once a pend is parked and has NOT yet reached the inner transactor. */
+	readonly pendParked: Promise<void>;
+	/** The collection under test. Assigned after construction — the collection is built over this
+	 *  wrapper, so it cannot be a constructor argument. */
+	collection?: Collection<TAction>;
+	private readonly parked = deferred();
+	private readonly gate = deferred();
+	private parkedOnce = false;
+
+	constructor(inner: TestTransactor) {
+		super(inner);
+		this.pendParked = this.parked.promise;
+	}
+
+	override async pend(request: PendRequest): Promise<PendResult> {
+		if (!this.parkedOnce) {
+			this.parkedOnce = true;
+			this.parked.resolve();
+			await this.gate.promise;
+		}
+		this.snapshots.push({
+			pended: structuredClone(request.transforms),
+			staged: structuredClone(this.collection!.tracker.transforms),
+		});
+		return this.inner.pend(request);
+	}
+
+	openGate(): void { this.gate.resolve(); }
+}
+
 /**
  * Durably commit a conflicting change to a tree collection: opens a SECOND {@link Tree} over the
  * same transactor + collection id and replaces `entries` through it, producing a real log entry