@optimystic/db-p2p 1.0.0-beta.2 → 1.0.0

package/src/rn.ts

@@ -1,69 +1,74 @@
-// 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/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';
-export * from './storage/storage-monitor.js';
-export * from './storage/arachnode-fret-adapter.js';
-export * from './sync/protocol.js';
-export * from './sync/client.js';
-export * from './sync/service.js';
-export * from './it-utility.js';
-export * from './libp2p-key-network.js';
-export * from './libp2p-node-rn.js';
-export * from './optimystic-node.js';
-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';
-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';
+// 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/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/i-under-replication-ledger.js';
+export * from './repo/kv-under-replication-ledger.js';
+export * from './repo/under-replication-drain.js';
+export * from './repo/responsibility.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/pending-claim.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';
+export * from './storage/storage-monitor.js';
+export * from './storage/arachnode-fret-adapter.js';
+export * from './sync/protocol.js';
+export * from './sync/client.js';
+export * from './sync/service.js';
+export * from './it-utility.js';
+export * from './libp2p-key-network.js';
+export * from './libp2p-node-rn.js';
+export * from './optimystic-node.js';
+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';
+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/storage/block-latch.ts

@@ -34,8 +34,9 @@ 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.
+ * the constructor is private and the module-scoped minter is assigned from a static field
+ * initializer, 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
@@ -54,10 +55,12 @@ export class BlockWriteLatch {
 		return this.#live;
 	}
 
-	static {
+	// A static field initializer, not a `static { }` block: React Native's Metro/Babel bundling cannot
+	// transform static blocks, and this module ships in the RN bundle (lint enforces it).
+	static #wired = (() => {
 		mint = (blockId) => new BlockWriteLatch(blockId);
 		expire = (latch) => { latch.#live = false; };
-	}
+	})();
 }
 
 /**

package/src/storage/block-storage.ts

@@ -1,4 +1,4 @@
-import type { BlockId, IBlock, Transform, ActionId, ActionRev, ActionTransform } from "@optimystic/db-core";
+import type { BlockId, IBlock, Transform, ActionId, ActionRev, ActionTransform, BlockLineage } from "@optimystic/db-core";
 import { applyTransform, canonicalJson, hashString } from "@optimystic/db-core";
 import type { BlockCommitProof } from "../cluster/commit-proof.js";
 import type { BlockArchive, BlockMetadata, RestoreCallback, RevisionRange } from "./struct.js";
@@ -6,6 +6,7 @@ import type { IRawStorage } from "./i-raw-storage.js";
 import { mergeRanges } from "./helpers.js";
 import { RevisionNotCoveredError, PendRevisionTakenError, type IBlockStorage } from "./i-block-storage.js";
 import type { BlockWriteLatch } from "./block-latch.js";
+import type { PendingClaim } from "./pending-claim.js";
 import { createLogger } from "../logger.js";
 
 const log = createLogger('block-storage');
@@ -155,9 +156,39 @@ export class BlockStorage implements IBlockStorage {
 		yield* this.storage.listPendingTransactions(this.blockId);
 	}
 
-	async savePendingTransaction(actionId: ActionId, transform: Transform, rev: number | undefined, latch: BlockWriteLatch): Promise<void> {
+	async listPendingClaims(): Promise<PendingClaim[]> {
+		const meta = await this.storage.getMetadata(this.blockId);
+		const claims: PendingClaim[] = [];
+		for await (const actionId of this.storage.listPendingTransactions(this.blockId)) {
+			claims.push(BlockStorage.claimOf(meta, actionId));
+		}
+		return claims;
+	}
+
+	async pendingClaimOf(actionId: ActionId): Promise<PendingClaim | undefined> {
+		// Joined against the record, exactly as the listing is: a metadata entry whose record is gone
+		// is inert (see BlockMetadata.pendingRevs) and must not read as a live claim.
+		if (await this.storage.getPendingTransaction(this.blockId, actionId) === undefined) {
+			return undefined;
+		}
+		return BlockStorage.claimOf(await this.storage.getMetadata(this.blockId), actionId);
+	}
+
+	/** The claim `meta` describes for `actionId`'s (existing) record: its slot and its base, each
+	 * present only when on file. */
+	private static claimOf(meta: BlockMetadata | undefined, actionId: ActionId): PendingClaim {
+		const rev = meta?.pendingRevs?.[actionId];
+		const baseRev = meta?.pendingBases?.[actionId];
+		return {
+			actionId,
+			...(rev === undefined ? {} : { rev }),
+			...(baseRev === undefined ? {} : { baseRev })
+		};
+	}
+
+	async savePendingTransaction(actionId: ActionId, transform: Transform, rev: number | undefined, baseRev: number | undefined, latch: BlockWriteLatch): Promise<void> {
 		this.assertLatch(latch);
-		log('pend blockId=%s actionId=%s rev=%s', this.blockId, actionId, rev);
+		log('pend blockId=%s actionId=%s rev=%s baseRev=%s', this.blockId, actionId, rev, baseRev);
 		let meta = await this.storage.getMetadata(this.blockId);
 		// Refuse a record that could never be promoted (see IBlockStorage.savePendingTransaction).
 		// The metadata read above is unconditional anyway, so this costs one comparison and no I/O.
@@ -177,8 +208,15 @@ export class BlockStorage implements IBlockStorage {
 			// This read-then-seed is exactly the window a concurrent replica used to land in (the
 			// seed then erased its `latest`); the latch the caller holds is what closes it.
 			meta = { latest: undefined, ranges: [] };
-			await this.storage.saveMetadata(this.blockId, meta);
 		}
+		// Record the slot the record claims (see BlockMetadata.pendingRevs) and the base it was computed
+		// against (`pendingBases`) in the same metadata write that seeds a fresh block, BEFORE the record
+		// itself: a crash between the two leaves an inert entry with no record, whereas the other order
+		// would leave a record with no claim — which every reader treats as the strongest kind and would
+		// refuse rivals on more than it should — and with no base, which the read-driven promotion
+		// would then decline to apply. A redelivered pend for the same action overwrites all three.
+		BlockStorage.recordClaim(meta, actionId, { rev, baseRev });
+		await this.storage.saveMetadata(this.blockId, meta);
 		await this.storage.savePendingTransaction(this.blockId, actionId, transform);
 	}
 
@@ -186,6 +224,58 @@ export class BlockStorage implements IBlockStorage {
 		this.assertLatch(latch);
 		log('cancel blockId=%s actionId=%s', this.blockId, actionId);
 		await this.storage.deletePendingTransaction(this.blockId, actionId);
+		// Metadata is written only when the record had a claim to drop: a cancel of an absent or
+		// claim-less record (the common torn-cancel retry) stays a pure no-op on the metadata blob.
+		const meta = await this.storage.getMetadata(this.blockId);
+		if (meta && (meta.pendingRevs?.[actionId] !== undefined || meta.pendingBases?.[actionId] !== undefined)) {
+			BlockStorage.recordClaim(meta, actionId, undefined);
+			await this.storage.saveMetadata(this.blockId, meta);
+		}
+	}
+
+	/**
+	 * Set (`claim` given) or clear (`undefined`) what `meta` says about `actionId`'s pending record —
+	 * the slot it claims and the base it was computed against — keeping each map absent while it is
+	 * empty. The two are always written together, so no path can drop a record's slot and leave its
+	 * base behind, or the reverse: clearing is what every drop site calls — a delete, a promotion
+	 * (`setLatest`), a same-action forward write (`saveForwardRevision`) and the dead-claim sweep.
+	 */
+	private static recordClaim(meta: BlockMetadata, actionId: ActionId, claim: { rev?: number; baseRev?: number } | undefined): void {
+		BlockStorage.setEntry(meta, 'pendingRevs', actionId, claim?.rev);
+		BlockStorage.setEntry(meta, 'pendingBases', actionId, claim?.baseRev);
+	}
+
+	/** `meta[map][actionId] = value`, or removes the entry when `value` is undefined; the map itself
+	 * is dropped from `meta` once empty, so an idle block's metadata carries neither key. */
+	private static setEntry(meta: BlockMetadata, map: 'pendingRevs' | 'pendingBases', actionId: ActionId, value: number | undefined): void {
+		const entries = { ...meta[map] };
+		if (value === undefined) delete entries[actionId];
+		else entries[actionId] = value;
+		if (Object.keys(entries).length === 0) delete meta[map];
+		else meta[map] = entries;
+	}
+
+	/**
+	 * Every pending record claiming a revision at or below `latestRev` can never be promoted here:
+	 * promotion needs `latest.rev < rev`, and `latest` only advances. Such a record is DEAD — a rival
+	 * that lost the slot, or a torn write's leftover on a block a later commit has since moved past —
+	 * and left in place it is reported as a live conflicting action to every reader of the block.
+	 * Delete those records and drop their claims from `meta`, which the caller then saves; a record
+	 * with no claim on file is left alone (its slot is unknown, so its death is unprovable here).
+	 *
+	 * Runs under the block's write latch on every path that advances `latest`, which is the one moment
+	 * a record's death becomes provable. This is the locally decidable half of what backlog
+	 * `debt-unpromotable-pending-records-need-a-sweep` asks for; the other half — a record whose slot
+	 * the block has NOT reached, whose writer simply never came back — is not decidable from local
+	 * state and is not touched here.
+	 */
+	private async sweepDeadClaims(meta: BlockMetadata, latestRev: number): Promise<void> {
+		for (const [actionId, rev] of Object.entries(meta.pendingRevs ?? {}) as [ActionId, number][]) {
+			if (rev > latestRev) continue;
+			await this.storage.deletePendingTransaction(this.blockId, actionId);
+			BlockStorage.recordClaim(meta, actionId, undefined);
+			log('sweep-dead-claim blockId=%s actionId=%s claimedRev=%d latestRev=%d', this.blockId, actionId, rev, latestRev);
+		}
 	}
 
 	async *listRevisions(startRev: number, endRev: number): AsyncIterable<ActionRev> {
@@ -228,7 +318,31 @@ export class BlockStorage implements IBlockStorage {
 		await this.storage.promotePendingTransaction(this.blockId, actionId);
 	}
 
-	async setLatest(latest: ActionRev, latch: BlockWriteLatch): Promise<void> {
+	async lineageOf({ actionId, rev }: ActionRev): Promise<BlockLineage> {
+		const meta = await this.storage.getMetadata(this.blockId);
+		const latest = meta?.latest;
+		if (!latest || latest.rev < rev) {
+			return 'behind';
+		}
+		if (latest.rev === rev) {
+			return latest.actionId === actionId ? 'contains' : 'excludes';
+		}
+		const heldBy = await this.storage.getRevision(this.blockId, rev);
+		if (heldBy !== undefined && heldBy !== actionId) {
+			return 'excludes';
+		}
+		// Past the revision. The index alone cannot answer from here: holding the action at `rev`
+		// does not prove `latest` was built from it (a replica taken since may descend from a base
+		// below `rev`), and holding nothing at `rev` does not prove it was not (a replica taken since
+		// may descend from it). Only a history derived HERE across `rev` settles it either way.
+		const floor = meta.lineageFloor;
+		if (floor === undefined || floor > rev) {
+			return 'unknown';
+		}
+		return heldBy === actionId ? 'contains' : 'excludes';
+	}
+
+	async setLatest(latest: ActionRev, builtOnPrior: boolean, latch: BlockWriteLatch): Promise<void> {
 		this.assertLatch(latch);
 		const meta = await this.storage.getMetadata(this.blockId);
 		if (!meta) {
@@ -237,6 +351,7 @@ export class BlockStorage implements IBlockStorage {
 		// Capture the prior latest rev BEFORE overwriting: coverage anchors to the earliest held rev.
 		const prevRev = meta.latest?.rev;
 		meta.latest = latest;
+		meta.lineageFloor = BlockStorage.nextLineageFloor(meta.lineageFloor, prevRev, latest.rev, builtOnPrior);
 		// NOTE: re-sorts (mergeRanges) the whole ranges array on every commit; if a block ever
 		// accumulates many disjoint ranges and commits show as slow, keep a running merged structure.
 		// `getBlock(r)` is served by materializeBlock's DESCENDING walk (highest committed rev <= r).
@@ -252,6 +367,11 @@ export class BlockStorage implements IBlockStorage {
 		// before this call advances neither.
 		meta.ranges.unshift([prevRev ?? latest.rev]);
 		meta.ranges = mergeRanges(meta.ranges);
+		// The committing action's own record was just MOVED by `promotePendingTransaction`: drop its
+		// claim without a delete, so the sweep does not pay a raw-storage op on a record that is already
+		// gone. Any other record claiming a slot at or below the new latest is dead and swept.
+		BlockStorage.recordClaim(meta, latest.actionId, undefined);
+		await this.sweepDeadClaims(meta, latest.rev);
 		await this.storage.saveMetadata(this.blockId, meta);
 	}
 
@@ -265,6 +385,7 @@ export class BlockStorage implements IBlockStorage {
 		const currentRev = meta.latest?.rev ?? 0;
 		let maxRev = currentRev;
 		let maxActionId = meta.latest?.actionId;
+		let lineageFloor = meta.lineageFloor;
 
 		// Probe forward until we hit a gap or a revision whose action is not yet
 		// in the committed log (Crash-D2 state — retry-commit owns that advance).
@@ -273,6 +394,9 @@ export class BlockStorage implements IBlockStorage {
 			if (actionId === undefined) break;
 			const promoted = await this.storage.getTransaction(this.blockId, actionId);
 			if (promoted === undefined) break;
+			// Each recovered revision is a commit whose `setLatest` was lost, so it owes the floor
+			// exactly what that `setLatest` would have recorded.
+			lineageFloor = BlockStorage.nextLineageFloor(lineageFloor, maxRev === 0 ? undefined : maxRev, next, promoted.insert === undefined);
 			maxRev = next;
 			maxActionId = actionId;
 		}
@@ -280,6 +404,7 @@ export class BlockStorage implements IBlockStorage {
 		if (maxRev > currentRev && maxActionId !== undefined) {
 			const advanced: ActionRev = { rev: maxRev, actionId: maxActionId };
 			meta.latest = advanced;
+			meta.lineageFloor = lineageFloor;
 			// The lost setLatest would have merged each recovered revision's range; redo that
 			// here. Open-ended from currentRev+1 (see setLatest): every rev in (currentRev, maxRev]
 			// was verified present in the committed log above, and any rev > maxRev resolves via the
@@ -287,6 +412,13 @@ export class BlockStorage implements IBlockStorage {
 			// the prior [E, currentRev+1) (from the earlier setLatest) into one open-ended [E, +inf).
 			meta.ranges.unshift([currentRev + 1]);
 			meta.ranges = mergeRanges(meta.ranges);
+			// Each recovered revision's lost `setLatest` also owed this sweep. Unlike `setLatest`, it
+			// DELETES each recovered action's record rather than just dropping its claim: a pend checks
+			// only `latest`, so a same-action retry re-pended while the `setLatest` was owed leaves a
+			// pending record beside the committed one (reachable through `StorageRepo.recoverBlock`).
+			// Dropping only its claim would leave a claim-less record, the strongest kind of reservation,
+			// that nothing ever removes. Recover runs only after a crash, so the extra op costs nothing.
+			await this.sweepDeadClaims(meta, maxRev);
 			await this.storage.saveMetadata(this.blockId, meta);
 			log('recover blockId=%s advanced latest from rev=%d to rev=%d', this.blockId, currentRev, maxRev);
 			return { reconciled: true, latest: advanced };
@@ -404,11 +536,9 @@ export class BlockStorage implements IBlockStorage {
 		// record is not this writer's to delete. Both paths run under the block's write latch, so
 		// this deletion is already mutually exclusive with a live commit.
 		//
-		// NOTE: deletes only this revision's actionId, not every pending whose action is already
-		// committed. A broader sweep would repair records orphaned by routes that do not carry the
-		// committing actionId; if orphaned pendings ever show up in the field on blocks whose
-		// committing action id differs, widen to a sweep over listPendingTransactions filtered by
-		// getTransaction.
+		// This same-action delete stays explicit even though the sweep below would usually cover it:
+		// Invariant P must hold for a record that has no claim on file (pended before claims were
+		// recorded), which the sweep — which reasons from claims — cannot see.
 		await this.storage.deletePendingTransaction(this.blockId, actionId);
 
 		// Seed metadata when absent, advance latest, and merge the covered range.
@@ -416,7 +546,16 @@ export class BlockStorage implements IBlockStorage {
 		if (!meta) {
 			meta = { latest: undefined, ranges: [] };
 		}
+		// Every OTHER record claiming a slot at or below the landing revision is dead too: the
+		// orphaned records a route that does not carry the committing action id used to leave behind
+		// (the cohort reconcile of a block a member fell behind on lands a later revision under a
+		// later action, and the missed action's record would otherwise stand forever).
+		BlockStorage.recordClaim(meta, actionId, undefined);
+		await this.sweepDeadClaims(meta, rev);
 		meta.latest = { rev, actionId };
+		// Content this node did not derive: nothing here says what it was built from, so the known
+		// lineage starts over at this revision (see BlockMetadata.lineageFloor).
+		meta.lineageFloor = rev;
 		// Open-ended coverage from the earliest held rev (see setLatest): the descending walk serves
 		// any rev >= the anchor. A prior latest at prevRev (< rev per the monotonic guard) is a
 		// materialized point, so anchor at prevRev; the first write (prevRev undefined) anchors at
@@ -758,6 +897,18 @@ export class BlockStorage implements IBlockStorage {
 		}
 	}
 
+	/**
+	 * The lineage floor after a COMMIT lands `rev` on top of `prevRev` (see
+	 * {@link BlockMetadata.lineageFloor}). A revision built on the prior content extends the known
+	 * lineage downwards as far as it already reached — or, for metadata that predates the field,
+	 * to the revision it was just built on, which is all this commit can vouch for. A revision that
+	 * stands on its own (an insert replaces the block wholesale), and a block's first revision,
+	 * start the lineage at themselves.
+	 */
+	private static nextLineageFloor(floor: number | undefined, prevRev: number | undefined, rev: number, builtOnPrior: boolean): number {
+		return builtOnPrior && prevRev !== undefined ? (floor ?? prevRev) : rev;
+	}
+
 	private inRanges(rev: number, ranges: RevisionRange[]): boolean {
 		return ranges.some(range =>
 			rev >= range[0] && (range[1] === undefined || rev < range[1])

package/src/storage/i-block-storage.ts

@@ -1,6 +1,7 @@
-import type { BlockId, IBlock, Transform, ActionId, ActionRev } from "@optimystic/db-core";
+import type { BlockId, IBlock, Transform, ActionId, ActionRev, BlockLineage } from "@optimystic/db-core";
 import type { BlockCommitProof } from "../cluster/commit-proof.js";
 import type { BlockWriteLatch } from "./block-latch.js";
+import type { PendingClaim } from "./pending-claim.js";
 
 /**
  * Thrown by {@link IBlockStorage.getBlock} when the block has metadata here but the target revision
@@ -111,12 +112,44 @@ export interface IBlockStorage {
      * under one multi-block write-latch hold, so every block it saves was observed under that same
      * hold to satisfy `latest === undefined || latest.rev < rev`, and no writer can advance a block
      * without its latch. A throw here means a caller reintroduced check-then-act.
+     *
+     * The revision is also KEPT, in the block's metadata (`BlockMetadata.pendingRevs`), so the record
+     * can later be read as a claim on a specific slot — see {@link listPendingClaims}.
+     *
+     * `baseRev` is the committed revision the record's update operations were computed against — the
+     * pend's `baseRevs[blockId]` — or `undefined` when the pend named none for this block (an
+     * inserted or deleted block, or a base the author did not know). Kept beside the revision
+     * (`BlockMetadata.pendingBases`), in the same metadata write, so that every later step that
+     * applies the record can refuse to apply it to a different version of the block — see
+     * {@link pendingClaimOf}. Stored as told: whether it matches this node's `latest` is decided
+     * where the record is APPLIED (`StorageRepo.internalCommit`, and the read-driven promotion in
+     * `StorageRepo.get`), never here.
      */
-    savePendingTransaction(actionId: ActionId, transform: Transform, rev: number | undefined, latch: BlockWriteLatch): Promise<void>;
+    savePendingTransaction(actionId: ActionId, transform: Transform, rev: number | undefined, baseRev: number | undefined, latch: BlockWriteLatch): Promise<void>;
 
-    /** Deletes a pending action */
+    /** Deletes a pending action, and the revision and base it was recorded as claiming. */
     deletePendingTransaction(actionId: ActionId, latch: BlockWriteLatch): Promise<void>;
 
+    /**
+     * Every pending record on this block, each with the revision it was pended at and the base it
+     * was computed against when those are known — the pending namespace joined against
+     * `BlockMetadata.pendingRevs` and `pendingBases`. This is the view the rival-pend checks read
+     * (`StorageRepo.pend`'s apply-time scan and `ClusterMember.validatePendOperations`' promise
+     * vote), because whether a record reserves the block against a given pend depends on the slot
+     * it claims measured against the pend's revision — and, at the vote of a cohort that can leave a
+     * member out, its base (`isReservationAgainst`) — not on its mere presence. Read-only; no latch.
+     */
+    listPendingClaims(): Promise<PendingClaim[]>;
+
+    /**
+     * The claim of ONE pending record — `actionId`'s entry of {@link listPendingClaims} — or
+     * `undefined` when this block holds no pending record for the action. For the two apply sites
+     * (`StorageRepo.internalCommit` and the read-driven promotion in `StorageRepo.get`), which need
+     * one record's base on the hot commit path and must not enumerate every record to get it.
+     * Read-only; no latch of its own: both callers already hold the block's write latch.
+     */
+    pendingClaimOf(actionId: ActionId): Promise<PendingClaim | undefined>;
+
     /** Lists revisions in ascending or descending order between startRev and endRev (inclusive) */
     listRevisions(startRev: number, endRev: number): AsyncIterable<ActionRev>;
 
@@ -152,8 +185,30 @@ export interface IBlockStorage {
      */
     promotePendingTransaction(actionId: ActionId, latch: BlockWriteLatch): Promise<void>;
 
-    /** Sets the latest revision information */
-    setLatest(latest: ActionRev, latch: BlockWriteLatch): Promise<void>;
+    /**
+     * Sets the latest revision information, as the last step of committing `latest` here.
+     *
+     * Call it only after {@link promotePendingTransaction} has moved `latest.actionId`'s record: it
+     * drops that action's claim without deleting a record, so a caller that skipped promotion would
+     * leave a claim-less pending record behind (see `BlockMetadata.pendingRevs`).
+     *
+     * `builtOnPrior` says how the revision's content was produced, which is what the block's known
+     * lineage depends on (see `BlockMetadata.lineageFloor`): `true` when this node applied the
+     * revision's transform to the content of its previous revision (an update-only or delete
+     * transform); `false` when the content stands on its own because the transform carried an
+     * `insert`. Required rather than defaulted: a caller that guessed `true` for an insert would let
+     * {@link lineageOf} vouch for history the content never came from.
+     */
+    setLatest(latest: ActionRev, builtOnPrior: boolean, latch: BlockWriteLatch): Promise<void>;
+
+    /**
+     * What THIS node's records say about whether the block's content at `latest` was built from the
+     * committed `target` — see `BlockLineage` in db-core for the four answers. Local and read-only:
+     * no latch, no peer fetch, no promotion. `unknown` is the honest answer whenever this node is
+     * past `target.rev` but took later content it did not derive itself (a replica, a restore);
+     * another cohort member that applied those revisions locally can still answer.
+     */
+    lineageOf(target: ActionRev): Promise<BlockLineage>;
 
     /**
      * Persist a replica of a block received out-of-band (churn re-replication).