@optimystic/db-p2p 0.24.1 → 0.25.0

package/src/reputation/types.ts

@@ -20,7 +20,9 @@ export enum PenaltyReason {
 	FalseApproval = 'false-approval',
 	/** Challenger lost a dispute (their rejection was wrong) */
 	DisputeLost = 'dispute-lost',
-	/** Peer reported a block latest (rev/actionId) or served content contradicted by a cluster quorum during restoration */
+	/** Peer served provably-bad restoration evidence: a latest claim naming a different action at the
+	 *  quorum-agreed revision, served content contradicted by a cluster quorum, or a cohort commit
+	 *  proof that provably lies or does not cover the claim it was attached to (replay) */
 	InvalidRestoration = 'invalid-restoration',
 }
 

package/src/rn.ts

@@ -1,23 +1,46 @@
+// React Native / browser entry point. `package.json` routes the `react-native` condition on `.`
+// here, plus the explicit `./rn` subpath.
+//
+// NOTE: this entry re-exports exactly the same module set as `./index.js`, with
+// `./libp2p-node.js` -> `./libp2p-node-rn.js` as the single substitution. Because the module set
+// is identical, a class obtained from either entry is the *same* class object on Node, so
+// `instanceof` holds across them; downstream code (e.g. sereus' `cached-storage.ts`) relies on
+// that. Enforced from this side by `test/entry-parity.spec.ts` — keep the two files in step, and
+// keep every line here a plain `export * from '...'` so that spec can compare them.
+
 export * from './cluster/client.js';
-export * from './cluster/cluster-policy.js';
+export * from './cluster/client-signature-verifier.js';
 export * from './cluster/cluster-repo.js';
+export * from './cluster/cluster-policy.js';
+export * from './cluster/commit-cert.js';
+export * from './cluster/commit-proof.js';
 export * from './cluster/service.js';
+export * from './cluster/rebalance-monitor.js';
+export * from './cluster/spread-on-churn.js';
+export * from './cluster/block-transfer.js';
+export * from './cluster/block-transfer-service.js';
+export * from './inbound-authorization.js';
 export * from './protocol-client.js';
 export * from './repo/client.js';
 export * from './repo/cluster-coordinator.js';
 export * from './repo/coordinator-repo.js';
+export * from './repo/served-repo-proxy.js';
 export * from './repo/service.js';
 export * from './storage/block-storage.js';
+export * from './storage/block-latch.js';
+export * from './storage/store-identity.js';
 export * from './storage/raw-store-driver.js';
 export * from './storage/kv-raw-storage.js';
 export * from './storage/shared-cache-pool.js';
 export * from './storage/cached-store-driver.js';
 export * from './storage/cached-raw-storage.js';
+export * from './storage/with-read-cache.js';
 export * from './storage/memory-store-driver.js';
 export * from './storage/memory-storage.js';
 export * from './storage/i-block-storage.js';
 export * from './storage/i-raw-storage.js';
 export * from './storage/struct.js';
+export * from './storage/block-archive.js';
 export * from './storage/storage-repo.js';
 export * from './storage/restoration-coordinator.js';
 export * from './storage/ring-selector.js';
@@ -34,6 +57,13 @@ export * from './routing/responsibility.js';
 export * from './routing/libp2p-known-peers.js';
 export * from './network/network-manager-service.js';
 export * from './network/get-network-manager.js';
-// Browser-safe peer signing seam. The rest of ./cohort-topic pulls node-heavy host.js,
-// so only peer-sig (@noble/curves + peer-id) is surfaced through the RN/browser entry.
-export * from './cohort-topic/peer-sig.js';
+export * from './reputation/index.js';
+export * from './dispute/index.js';
+export * from './cohort-topic/index.js';
+export * from './matchmaking/index.js';
+export * from './reactivity/index.js';
+export * from './cluster/i-transaction-state-store.js';
+export * from './cluster/memory-transaction-state-store.js';
+export * from './cluster/persistent-transaction-state-store.js';
+export * from './storage/i-kv-store.js';
+export * from './storage/memory-kv-store.js';

package/src/routing/libp2p-known-peers.ts

@@ -1,26 +1,31 @@
-import type { Libp2p } from 'libp2p'
-import type { PeerId } from '@libp2p/interface'
-import type { KnownPeer } from './responsibility.js'
-
-export function buildKnownPeers(libp2p: Libp2p): KnownPeer[] {
-  const self: KnownPeer = {
-    id: libp2p.peerId as unknown as PeerId,
-    addrs: libp2p.getMultiaddrs().map(ma => ma.toString())
-  }
-
-  const connections = libp2p.getConnections()
-  const byPeer: Record<string, { id: PeerId, addrs: Set<string> }> = {}
-
-  for (const c of connections) {
-    const pid = c.remotePeer
-    const key = pid.toString()
-    const entry = byPeer[key] ?? (byPeer[key] = { id: pid as unknown as PeerId, addrs: new Set() })
-    const addrStr = c.remoteAddr?.toString?.()
-    if (addrStr) entry.addrs.add(addrStr)
-  }
-
-  const others: KnownPeer[] = Object.values(byPeer).map(e => ({ id: e.id, addrs: Array.from(e.addrs) }))
-  return [self, ...others]
-}
-
-
+import type { Libp2p } from 'libp2p'
+import type { PeerId } from '@libp2p/interface'
+import type { KnownPeer } from './responsibility.js'
+
+export function buildKnownPeers(libp2p: Libp2p): KnownPeer[] {
+  const self: KnownPeer = {
+    id: libp2p.peerId as unknown as PeerId,
+    addrs: libp2p.getMultiaddrs().map(ma => ma.toString())
+  }
+
+  const connections = libp2p.getConnections()
+  const byPeer: Record<string, { id: PeerId, addrs: Set<string> }> = {}
+
+  for (const c of connections) {
+    const pid = c.remotePeer
+    const key = pid.toString()
+    const entry = byPeer[key] ?? (byPeer[key] = { id: pid as unknown as PeerId, addrs: new Set() })
+    // NOTE: this takes every connection's remoteAddr regardless of direction, so an inbound
+    // connection contributes the far side's ephemeral source socket. Harmless today: nothing in
+    // this repo calls buildKnownPeers, and responsibility.ts reads only `id`. But this is a public
+    // export — if a caller ever hands KnownPeer.addrs to a THIRD party (a record, a redirect, a
+    // discovery reply), route it through `publishableConnectionAddr` in peer-address-book.ts first.
+    const addrStr = c.remoteAddr?.toString?.()
+    if (addrStr) entry.addrs.add(addrStr)
+  }
+
+  const others: KnownPeer[] = Object.values(byPeer).map(e => ({ id: e.id, addrs: Array.from(e.addrs) }))
+  return [self, ...others]
+}
+
+

package/src/storage/block-archive.ts

@@ -0,0 +1,242 @@
+import type { ActionContext, ActionRev, BlockId, IBlock, IRepo } from "@optimystic/db-core";
+import type { BlockArchive } from "./struct.js";
+import { proofClaimsCommit, type BlockCommitProof } from "../cluster/commit-proof.js";
+import { createLogger } from "../logger.js";
+
+const log = createLogger('block-archive');
+
+/**
+ * The archive shape every block-repair path exchanges: ONE revision — the one being served —
+ * carrying its action, the block itself when the serving repo materialized it, and the cohort's
+ * commit proof for that revision when the serving repo retained one.
+ *
+ * One function rather than the shape re-typed at each site, because three sites had already drifted
+ * while each claimed to mirror the others: the sync service served `block: undefined` for a block
+ * with no materialized content, the mesh test harness served no archive at all for that same repo
+ * state (turning a corroborable revision claim into a phantom non-holder), and the reconcile unit
+ * spec's stand-in emitted a third shape again. `createReconcileBlock` reads
+ * `revisions[rev].action.actionId` and `revisions[rev].block`, and the difference between "absent
+ * block" and "absent archive" decides whether a peer votes in the revision quorum at all — so the
+ * shape is a contract, not a detail.
+ *
+ * `block` stays optional on purpose: a revision whose content the serving repo cannot materialize
+ * (a deleted block — see `GetBlockResult.block`) is still a revision that peer legitimately claims.
+ * It votes on `(rev, actionId)` and abstains from the content quorum, which is exactly the evidence
+ * it holds.
+ *
+ * `proof` is optional for the same kind of reason (see `ArchiveRevisions.proof`): a pre-proof
+ * revision, a diverged member, or an un-upgraded peer serves none, and every consumer must behave
+ * exactly as it did before proofs existed when it is absent.
+ *
+ * NOTE: the `range` emitted here is a COMPATIBILITY CONTRACT with `BlockStorage.vetRestoredArchive`,
+ * which refuses an archive whose declared range does not start at its lowest revision, end past its
+ * highest, or which is open-ended. `[rev, rev + 1]` around a single revision satisfies all three
+ * trivially, and this is currently the ONLY producer of an archive that crosses the restore wire —
+ * which is why no test drives a refusal end to end through `RestorationCoordinator`. If a second
+ * producer ever appears (a multi-revision or sparse archive, say), that contract stops being
+ * trivially true and needs a test pinning the two ends together.
+ */
+export function singleRevisionArchive(
+	blockId: BlockId,
+	source: ActionRev,
+	block: IBlock | undefined,
+	proof?: BlockCommitProof
+): BlockArchive {
+	return {
+		blockId,
+		revisions: {
+			[source.rev]: {
+				action: { actionId: source.actionId, transform: { insert: block } },
+				...(block ? { block } : {}),
+				...(proof ? { proof } : {})
+			}
+		},
+		range: [source.rev, source.rev + 1]
+	};
+}
+
+/**
+ * A peer's answer to the latest-revision consult: the `(rev, actionId)` it claims, plus the cohort's
+ * commit proof for that revision when it retained one.
+ *
+ * Defined HERE, alongside the archive shape, rather than beside the callback that returns it
+ * (`ClusterLatestCallback` in `repo/coordinator-repo.ts`, which re-exports this name): a remote
+ * peer's answer IS a projection of the archive it served, so keeping the two in one file is what
+ * stops the projection from drifting from the shape — the same reason `singleRevisionArchive` is a
+ * function rather than a shape re-typed at each site.
+ *
+ * The proof is OPTIONAL and means nothing until a consumer verifies it. A pre-proof revision, a
+ * diverged member, and an un-upgraded peer all legitimately answer without one, and a peer is free
+ * to attach whatever it likes — verification, never presence, is what makes a proof evidence.
+ */
+export type CertifiedActionRev = ActionRev & { proof?: BlockCommitProof };
+
+/**
+ * Highest revision an archive covers, or `undefined` when it covers none.
+ *
+ * ONE implementation for every site that asks an untrusted archive this question — the two repair
+ * wires ({@link latestClaimFromArchive}) and the reconcile pass (`cluster/reconcile-block.ts`) — for
+ * the same reason {@link singleRevisionArchive} is one function: two copies is how one of them ends
+ * up without the guards below.
+ *
+ * Both guards matter on input a remote peer chose. `Object.keys` on a JSON-parsed archive yields
+ * strings, so a non-numeric key coerces to `NaN` and is skipped rather than poisoning the maximum.
+ * And the fold is deliberate rather than `Math.max(...keys)`: the spread passes one ARGUMENT per
+ * revision, which throws `RangeError: Maximum call stack size exceeded` past ~125k arguments —
+ * comfortably inside the 8 MiB `MAX_BLOCK_MESSAGE_BYTES` a sync response may carry (130k minimal
+ * revision entries serialize to ~6.3 MiB), so a peer could otherwise choose to make this throw.
+ */
+export function maxArchiveRevision(revisions: BlockArchive['revisions'] | undefined): number | undefined {
+	let max: number | undefined;
+	for (const key of Object.keys(revisions ?? {})) {
+		const rev = Number(key);
+		if (Number.isFinite(rev) && (max === undefined || rev > max)) max = rev;
+	}
+	return max;
+}
+
+/**
+ * The highest-revision claim an archive carries, or `undefined` when it holds no usable revision.
+ * `undefined` is the peer having ANSWERED without data — an absent claim, never silence (see
+ * `ClusterLatestCallback`'s three-way contract).
+ *
+ * The proof is read from the SAME revision entry as the `(rev, actionId)`, so a serving peer cannot
+ * pair a genuine proof with a revision it does not certify by choosing a different layout. Nothing
+ * here verifies anything: the result is the peer's unverified assertion until a caller checks it.
+ */
+export function latestClaimFromArchive(archive: BlockArchive): CertifiedActionRev | undefined {
+	const maxRev = maxArchiveRevision(archive.revisions);
+	if (maxRev === undefined) return undefined;
+	const entry = archive.revisions[maxRev];
+	if (!entry?.action) return undefined;
+	return {
+		actionId: entry.action.actionId,
+		rev: maxRev,
+		...(entry.proof ? { proof: entry.proof } : {})
+	};
+}
+
+/**
+ * What {@link serveBlockArchive} needs of the repo it reads: `IRepo`, plus — OPTIONALLY — the
+ * revision-keyed commit-proof accessor `StorageRepo` implements.
+ *
+ * Optional rather than required so the unit-test doubles and any other plain `IRepo` that serves
+ * archives keep compiling and keep working (they simply serve no proof). A repo that CAN serve
+ * proofs and does not is not a type error here — it is the pre-proof behaviour, which stays valid.
+ */
+export type ArchiveServingRepo = IRepo & {
+	getBlockProof?(blockId: BlockId, rev: number): Promise<BlockCommitProof | undefined>;
+};
+
+/**
+ * An {@link ArchiveServingRepo} that definitely CAN serve proofs — the accessor required rather
+ * than optional.
+ *
+ * The optionality above exists for a serving repo that legitimately has no proofs (a test double, a
+ * plain-`IRepo` embedder). It is the wrong default for a node's OWN store: forgetting the accessor
+ * there degrades every archive it serves to proof-less, silently and without a type error. Naming
+ * the stronger shape lets a composition root demand it (`createServedRepoProxy`).
+ */
+export type ProofRetainingRepo = IRepo & Required<Pick<ArchiveServingRepo, 'getBlockProof'>>;
+
+/**
+ * Serve `blockId` out of a local repo as a {@link singleRevisionArchive} — what a peer answers a
+ * block-repair fetch with. `undefined` when the repo holds no revision of the block at all, which
+ * callers report as "holds nothing" (`ReconcileBlockDeps.fetchArchive`'s contract folds
+ * "unreachable" into that same answer).
+ *
+ * The read skips the cluster deliberately: a peer answering a repair fetch reports what IT holds,
+ * and one that re-asked its own cohort would launder another peer's claim as its own.
+ *
+ * `rev` pins the read: `StorageRepo.get` materializes the highest committed revision of the block
+ * at or below it and reports that revision as `GetBlockResult.materialized`, which is what the
+ * archive is labelled with — its revision number, its action id, and its proof all belong to the
+ * bytes actually served. `state.latest` (the repo's NEWEST revision) is never the label: a caller
+ * asking for an older revision (`RestorationCoordinator` is the one that does) is answered with
+ * that revision as itself, or with nothing. Never with old bytes under a newer label — that pairing
+ * is what a receiver keyed by action id writes over its own good copy of the newer revision.
+ *
+ * The proof served is looked up for the revision ACTUALLY served, never for one chosen
+ * independently, so the archive can never publish a proof paired with a revision it does not
+ * certify. (A newer revision's proof over older bytes would pass `verifyBlockCommitProofClaim` and
+ * fail `verifyBlockCommitProofContent` — strictly worse than no proof.)
+ *
+ * NOTE: a single-revision archive's proof is a rounding error against the wire cap. A sync
+ * *response* is bounded by `MAX_BLOCK_MESSAGE_BYTES` (8 MiB — `SyncClient.requestBlock` sets the
+ * response decoder's `maxDataLength`; the 1 MiB `MAX_CONTROL_MESSAGE_BYTES` bounds the inbound
+ * REQUEST, not this). A proof's serialized size is dominated by two signatures plus a peer id per
+ * cohort member: a whole proof-carrying single-revision archive measured 4801 bytes at a 10-peer
+ * cohort and 8851 bytes at 20 (`test/block-archive-proof.spec.ts`, "far below the sync response
+ * cap", which prints both), i.e. ~405 bytes per additional peer. Reaching 8 MiB would take a cohort in the tens of thousands, so
+ * no plausible cluster size puts this near the cap — the block bytes the archive already carries
+ * are the term that matters. Revisit only if a proof ever grows a per-peer payload beyond its two
+ * signatures.
+ */
+export async function serveBlockArchive(repo: ArchiveServingRepo, blockId: BlockId, rev?: number): Promise<BlockArchive | undefined> {
+	// `ActionContext` is `{ committed, rev, actionId? }` — nothing else. `committed: []` claims no
+	// uncommitted-but-known action, and omitting `actionId` is what keeps this off `StorageRepo`'s
+	// pending-overlay path, so the read is purely "the highest COMMITTED revision at or below `rev`".
+	const context: ActionContext | undefined = rev !== undefined ? { rev, committed: [] } : undefined;
+	const result = await repo.get({ blockIds: [blockId], context }, { skipClusterFetch: true } as any);
+	const entry = result[blockId];
+	const latest = entry?.state?.latest;
+	if (!latest) return undefined;
+	// The revision the content in hand IS. A repo that reports `materialized` (`StorageRepo`) has
+	// served the highest committed revision at or below the pin, and that — never `state.latest`,
+	// the repo's NEWEST revision — is the archive's label. A repo that does not report it (a plain
+	// `IRepo`) can only be describing its latest.
+	const served = entry.materialized ?? latest;
+	// Fail closed rather than mislabel. A served revision ABOVE the pin is never a right answer:
+	// either the repo could not say what it materialized and its latest is newer than what was
+	// asked for (so the bytes may be pinned or may not — and the only label in hand is wrong for
+	// one of them), or the repo misreported. Labelling old bytes with a newer revision's number and
+	// action id is what the asker's `saveRestored` — keyed by action id — then writes over the good
+	// copy it already holds. Serve nothing instead: every caller already handles "holds nothing",
+	// and `restoreRevision` turns it into a loud "not found during restore attempt". A served
+	// revision AT OR BELOW the pin is the block unchanged since the pin, served exactly as before.
+	if (rev !== undefined && served.rev > rev) {
+		log('serve:skip blockId=%s served=%d requested=%d latest=%d (pinned read — refusing to mislabel content)',
+			blockId, served.rev, rev, latest.rev);
+		return undefined;
+	}
+	const proof = await servableProof(repo, blockId, served);
+	return singleRevisionArchive(blockId, served, entry.block, proof);
+}
+
+/**
+ * The stored proof for the revision being served, or `undefined` — including whenever anything is
+ * off about it. Serving no proof is always safe (every consumer must already handle its absence),
+ * so this fails closed on all three unhappy paths:
+ *
+ *  - the repo has no proof accessor at all (a plain `IRepo`, a test double);
+ *  - the lookup throws — a storage fault must not turn a servable archive into "holds nothing",
+ *    because that would recreate the phantom-non-holder bug the archive shape exists to prevent;
+ *  - the stored proof's own message does not name this `(blockId, rev, actionId)`. That is a local
+ *    storage-integrity fault, not a peer's doing, and publishing a mis-paired proof would hand
+ *    every receiver an artifact that cannot verify. Logged loudly, because it means a proof was
+ *    written under a key its content contradicts.
+ *
+ * Exported for the SAME reason {@link singleRevisionArchive} is: the mesh test harness answers the
+ * latest-revision consult out of a sibling's repo directly rather than over the sync protocol, and
+ * a harness that attached proofs by a different rule than a real peer would let every mesh-tier
+ * test silently exercise a path production does not have.
+ */
+export async function servableProof(
+	repo: ArchiveServingRepo, blockId: BlockId, latest: ActionRev
+): Promise<BlockCommitProof | undefined> {
+	if (typeof repo.getBlockProof !== 'function') return undefined;
+	let proof: BlockCommitProof | undefined;
+	try {
+		proof = await repo.getBlockProof(blockId, latest.rev);
+	} catch (error) {
+		log('serve:proof-lookup-failed blockId=%s rev=%d error=%s', blockId, latest.rev,
+			error instanceof Error ? error.message : String(error));
+		return undefined;
+	}
+	if (!proof) return undefined;
+	if (!proofClaimsCommit(proof, { blockId, rev: latest.rev, actionId: latest.actionId })) {
+		log('serve:proof-claim-mismatch blockId=%s rev=%d actionId=%s', blockId, latest.rev, latest.actionId);
+		return undefined;
+	}
+	return proof;
+}

package/src/storage/block-latch.ts

@@ -0,0 +1,144 @@
+import type { BlockId } from "@optimystic/db-core";
+import { Latches } from "@optimystic/db-core";
+
+/**
+ * The ONE per-block write lock.
+ *
+ * A block's metadata is stored as a single blob — `{ latest, ranges }` — read and written whole, so
+ * any read-modify-write of it overwrites `latest` whether it meant to or not. The invariant is
+ * therefore stated over the whole blob, not over `latest`:
+ *
+ * > A block's metadata, revision records, action transforms, pending records, and stored proofs are
+ * > only ever written while holding {@link blockWriteLatchKey}`(blockId)`.
+ *
+ * This module is the single acquirer of that key. The check, which deliberately matches the call
+ * shape (the escapes keep this very comment from matching):
+ *
+ * >     grep -rnE "Latches\.acquire\(" packages/db-p2p/src
+ *
+ * That must return exactly one line — the call in `acquireBlockWriteLatch` below. A second hit
+ * anywhere means a caller has started taking the key directly and the token discipline has a hole.
+ * Every writing method on `IBlockStorage` demands a
+ * {@link BlockWriteLatch} token, which only this module can mint, so an unlatched write does not
+ * type-check rather than merely being documented as forbidden.
+ *
+ * `Latches` is a plain FIFO promise-chain mutex — no owner tracking, no re-entrancy — so a holder
+ * must never call back into something that acquires the same block's key. The token is what lets a
+ * callee prove it is already inside the latch instead of re-acquiring.
+ */
+export const blockWriteLatchKey = (blockId: BlockId): string => `Block.write:${blockId}`;
+
+let mint!: (blockId: BlockId) => BlockWriteLatch;
+let expire!: (latch: BlockWriteLatch) => void;
+
+/**
+ * Opaque proof that the bearer is executing inside {@link blockWriteLatchKey}`(blockId)`. Only
+ * {@link acquireBlockWriteLatch} (and {@link withBlockWriteLatch} through it) can construct one:
+ * the constructor is private and the module-scoped minter is assigned from a static block, where
+ * the private constructor is callable — no cast, nothing outside this module can build a token.
+ *
+ * A token is only valid while the latch it proves is actually held: releasing expires it, so a
+ * callback that stashes its token and writes after its scope closed is rejected instead of silently
+ * writing unlatched. `live` is the check; only this module can clear it.
+ *
+ * `BlockStorage` checks `latch.blockId` against its own id on every write, so a token for one block
+ * cannot be presented for another.
+ */
+export class BlockWriteLatch {
+	#live = true;
+
+	private constructor(readonly blockId: BlockId) { }
+
+	/** False once the latch this token proves has been released. */
+	get live(): boolean {
+		return this.#live;
+	}
+
+	static {
+		mint = (blockId) => new BlockWriteLatch(blockId);
+		expire = (latch) => { latch.#live = false; };
+	}
+}
+
+/**
+ * Acquire the write latch for `blockId`. The non-scoped single-block form is the building block for
+ * {@link acquireBlockWriteLatches} and for a caller that must hold one latch across control flow a
+ * callback cannot express; everything else should prefer {@link withBlockWriteLatch}. A caller that
+ * wants N latches must go through {@link acquireBlockWriteLatches}, not loop over this. The caller
+ * MUST call `release` exactly once, in a `finally`. Releasing expires the token, so a write attempted
+ * with it afterwards is rejected rather than running outside the latch.
+ */
+export async function acquireBlockWriteLatch(blockId: BlockId): Promise<{ latch: BlockWriteLatch; release: () => void }> {
+	const releaseLatch = await Latches.acquire(blockWriteLatchKey(blockId));
+	const latch = mint(blockId);
+	return {
+		latch,
+		release: () => {
+			expire(latch);
+			releaseLatch();
+		}
+	};
+}
+
+/** The N-latch hold {@link acquireBlockWriteLatches} returns: a token per block, and one release. */
+export type BlockWriteLatches = {
+	/** Token per requested block id, so each write can prove it runs inside that block's latch. */
+	readonly latches: ReadonlyMap<BlockId, BlockWriteLatch>;
+	/** Releases every latch, in reverse acquisition order. Call exactly once, in a `finally`. */
+	readonly release: () => void;
+};
+
+/**
+ * Acquire the write latches for a whole set of blocks at once — the only sanctioned way to hold more
+ * than one. Two callers need it (`StorageRepo.commit` and `applyInvalidation`), and the property that
+ * keeps them from deadlocking against each other is not local to either: it is that EVERY multi-latch
+ * holder acquires in the one global order. Owning that here makes it a property of the module that
+ * owns the key rather than a rule each call site restates and a third one could get wrong.
+ *
+ * Three things this does that a hand-rolled loop keeps getting wrong:
+ *  - **Dedups** the ids. `Latches` is a plain FIFO mutex with no re-entrancy, so a repeated id in the
+ *    request would deadlock the acquirer against itself.
+ *  - **Sorts** them, so any two multi-latch holders acquire in the same order and no cycle exists.
+ *  - **Releases what it already took** if an acquisition partway through the set throws, rather than
+ *    stranding those latches forever.
+ *
+ * The returned map is keyed by the ids actually held, so a caller that wants its own (e.g. request)
+ * ordering can iterate its own list and look each token up.
+ */
+export async function acquireBlockWriteLatches(blockIds: Iterable<BlockId>): Promise<BlockWriteLatches> {
+	const ordered = Array.from(new Set(blockIds)).sort();
+	const releases: (() => void)[] = [];
+	const release = () => {
+		for (let i = releases.length - 1; i >= 0; i--) {
+			releases[i]!();
+		}
+		releases.length = 0;
+	};
+	const latches = new Map<BlockId, BlockWriteLatch>();
+	try {
+		for (const id of ordered) {
+			const acquired = await acquireBlockWriteLatch(id);
+			releases.push(acquired.release);
+			latches.set(id, acquired.latch);
+		}
+	} catch (err) {
+		release();
+		throw err;
+	}
+	return { latches, release };
+}
+
+/**
+ * Run `fn` while holding the write latch for `blockId`, handing it the token to pass down to the
+ * storage writes it makes. Acquire/release is per call, so a caller holds at most one block latch at
+ * a time and cannot deadlock against a sorted, up-front {@link acquireBlockWriteLatches} hold — as
+ * long as `fn` does not itself acquire another block's latch (nothing in this package does).
+ */
+export async function withBlockWriteLatch<T>(blockId: BlockId, fn: (latch: BlockWriteLatch) => Promise<T>): Promise<T> {
+	const { latch, release } = await acquireBlockWriteLatch(blockId);
+	try {
+		return await fn(latch);
+	} finally {
+		release();
+	}
+}