@optimystic/db-p2p 0.25.1 → 0.26.0

package/src/libp2p-node-base.ts

@@ -140,14 +140,17 @@ const wiringLog = createLogger('node-wiring');
 /**
  * Factory function or instance for creating raw storage. The node puts the write-through read
  * cache in front of the resolved instance (`withReadCache`, unless it is a `MemoryRawStorage` or
- * already cached) under a lease, and releases THAT LEASE when it stops; the instance you supplied
- * is never disposed. The cache is shared per backing store: two concurrently running nodes handed
+ * already read-cached) under a lease, and releases THAT LEASE when it stops; the instance you
+ * supplied is never disposed. The cache is shared per backing store: two concurrently running nodes handed
  * one uncached instance — or two instances that report the same `getStoreIdentity()`, such as two
  * `FileRawStorage` over one directory — read and write through ONE cache, which is cleared and
  * unregistered only when the last of them stops. Sequential reuse (a restart over the same
  * instance) starts cold once the previous node's lease has released. What remains unguarded is
- * the cross-process case (Invariant 5 in `packages/db-p2p/docs/storage.md`). A host that builds
- * its own `CachedRawStorage` and hands it in keeps owning it; the node never releases it.
+ * the cross-process case (Invariant 5 in `packages/db-p2p/docs/storage.md`). A host that attaches
+ * its own read cache and hands the result in keeps owning it; the node never releases it. Either
+ * documented cache construction is accepted here — `new CachedRawStorage(inner)` or
+ * `new KvRawStorage(new CachedStoreDriver(driver))`, the latter preferred when the backend's
+ * driver is reachable. Both report `IRawStorage.readCached`, which is what the seam checks.
  */
 export type RawStorageProvider = IRawStorage | (() => IRawStorage);
 
@@ -362,13 +365,13 @@ export type NodeOptions = ClusterPolicyOptions & {
 /**
  * Resolve the node's raw storage and put the write-through read cache in front of it. This is
  * the single place the network node resolves its `IRawStorage`, so it is the single place the
- * cache is wired (`withReadCache` states the exclusions: memory storage and already-cached
- * storage pass through unchanged). The default is a bare `MemoryRawStorage`, deliberately not
- * routed through the helper — nothing to cache.
+ * cache is wired (`withReadCache` states the exclusions: memory storage, and storage that
+ * already reports `readCached`, pass through unchanged). The default is a bare
+ * `MemoryRawStorage`, deliberately not routed through the helper — nothing to cache.
  *
  * `lease` is this node's claim on the (possibly shared) cache, and the ONLY thing its stop path
- * may release — a host that supplied its own `CachedRawStorage` keeps owning it (see
- * {@link ResolvedReadCache}).
+ * may release — a host that supplied an already-cached storage, in either documented
+ * construction, keeps owning it (see {@link ResolvedReadCache}).
  */
 function resolveStorage(provider: RawStorageProvider | undefined, networkName: string): ResolvedReadCache {
 	if (!provider) {

package/src/storage/block-latch.ts

@@ -90,10 +90,11 @@ export type BlockWriteLatches = {
 
 /**
  * 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.
+ * than one. Three callers need it (`StorageRepo.pend`, `StorageRepo.commit` and `applyInvalidation`),
+ * and the property that keeps them from deadlocking against each other is not local to any of them:
+ * 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 the next
+ * 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

package/src/storage/block-storage.ts

@@ -4,7 +4,7 @@ import type { BlockCommitProof } from "../cluster/commit-proof.js";
 import type { BlockArchive, BlockMetadata, RestoreCallback, RevisionRange } from "./struct.js";
 import type { IRawStorage } from "./i-raw-storage.js";
 import { mergeRanges } from "./helpers.js";
-import { RevisionNotCoveredError, type IBlockStorage } from "./i-block-storage.js";
+import { RevisionNotCoveredError, PendRevisionTakenError, type IBlockStorage } from "./i-block-storage.js";
 import type { BlockWriteLatch } from "./block-latch.js";
 import { createLogger } from "../logger.js";
 
@@ -155,10 +155,18 @@ export class BlockStorage implements IBlockStorage {
 		yield* this.storage.listPendingTransactions(this.blockId);
 	}
 
-	async savePendingTransaction(actionId: ActionId, transform: Transform, latch: BlockWriteLatch): Promise<void> {
+	async savePendingTransaction(actionId: ActionId, transform: Transform, rev: number | undefined, latch: BlockWriteLatch): Promise<void> {
 		this.assertLatch(latch);
-		log('pend blockId=%s actionId=%s', this.blockId, actionId);
+		log('pend blockId=%s actionId=%s rev=%s', this.blockId, actionId, rev);
 		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.
+		// `>=` deliberately covers BOTH unpromotable cases at once — our own already-committed
+		// revision (commit partitions it as already-done) and a rival's win (commit refuses it as
+		// stale) — so this is not an `isOwnRevision` check.
+		if (rev !== undefined && meta?.latest !== undefined && meta.latest.rev >= rev) {
+			throw new PendRevisionTakenError(this.blockId, actionId, rev, meta.latest);
+		}
 		if (!meta) {
 			// A freshly-pended block holds NO committed revision, so it can reconstruct
 			// nothing yet: seed empty ranges. The first commit anchors an OPEN-ENDED span at

package/src/storage/cached-raw-storage.ts

@@ -24,11 +24,15 @@ export class RawStorageDriverAdapter implements RawStoreDriver {
 	 * Optional passthroughs wired only when the inner storage provides them, mirroring
 	 * `KvRawStorage`'s constructor: feature-detection above must observe the inner
 	 * storage's true capability. `IRawStorage` has no `close`/`approximateBytesUsed`
-	 * driver names — they map from `listBlockIds`/`getApproximateBytesUsed`.
+	 * driver names — they map from `listBlockIds`/`getApproximateBytesUsed`. `readCached`
+	 * keeps its name across the boundary; carrying it up is what lets a re-kerneled cached
+	 * storage still report itself as cached, and what makes `CachedStoreDriver`'s
+	 * redundant-wrap guard fire for `new CachedRawStorage(alreadyCachedStorage)`.
 	 */
 	listBlockIds?: () => AsyncIterable<BlockId>;
 	approximateBytesUsed?: () => Promise<number>;
 	storeIdentity?: () => StoreIdentity;
+	readCached?: true;
 
 	constructor(private readonly inner: IRawStorage) {
 		if (inner.getStoreIdentity) {
@@ -40,6 +44,9 @@ export class RawStorageDriverAdapter implements RawStoreDriver {
 		if (inner.getApproximateBytesUsed) {
 			this.approximateBytesUsed = () => inner.getApproximateBytesUsed!();
 		}
+		if (inner.readCached) {
+			this.readCached = true;
+		}
 	}
 
 	// --- metadata ---
@@ -176,6 +183,19 @@ export class RawStorageDriverAdapter implements RawStoreDriver {
 export class CachedRawStorage extends KvRawStorage {
 	private readonly cacheDriver: CachedStoreDriver;
 
+	/**
+	 * Always present here: this class is a `KvRawStorage` over a `CachedStoreDriver`, so the
+	 * base constructor's passthrough always sets it. Narrowed from the base's optional
+	 * `readCached?: true` purely for the type.
+	 *
+	 * `declare` — type-only, NO emit. `tsconfig.base.json` targets ES2022 without
+	 * `useDefineForClassFields`, which therefore defaults to true, so a plain field
+	 * declaration here would emit a `defineProperty(this, 'readCached', undefined)` that runs
+	 * AFTER `super()` and clobber what the base constructor just assigned. Same reason
+	 * `FileRawStorage` &c. use `declare getStoreIdentity: …`.
+	 */
+	declare readonly readCached: true;
+
 	constructor(inner: IRawStorage, pool?: SharedCachePool, label?: string) {
 		const cacheDriver = new CachedStoreDriver(new RawStorageDriverAdapter(inner), pool, label);
 		super(cacheDriver);

package/src/storage/cached-store-driver.ts

@@ -200,11 +200,34 @@ export class CachedStoreDriver implements RawStoreDriver, PoolEntryOwner {
 	approximateBytesUsed?: () => Promise<number>;
 	storeIdentity?: () => StoreIdentity;
 
+	/**
+	 * This driver IS the read cache, so the marker is unconditional — unlike the passthroughs
+	 * above, which mirror the inner driver's capabilities. Wrappers above (`KvRawStorage`,
+	 * `RawStorageDriverAdapter`) carry it up, which is how `withReadCache` recognises BOTH
+	 * documented cache constructions without naming a concrete class.
+	 */
+	readonly readCached: true = true;
+
 	constructor(
 		private readonly inner: RawStoreDriver,
 		private readonly pool: SharedCachePool = defaultCachePool(),
 		label?: string,
 	) {
+		// Stacked wrap — the inner driver already has a read cache at or below it, so this one
+		// would only ever read through that one. Caught HERE, and before `registerStore`, because
+		// the pool cannot tell a stacked wrap from a side-by-side pair: it sees only that the
+		// identity is claimed, and would report the (wrong, and much scarier) divergence failure.
+		// Identity-less inner drivers reach the pool's guard not at all, so without this check a
+		// stacked wrap over one of them builds silently — pure overhead, never useful.
+		if (inner.readCached) {
+			throw new Error(
+				`redundant read cache: the inner driver is already read-cached`
+				+ `${inner.storeIdentity ? ` (${JSON.stringify(inner.storeIdentity())})` : ''}, so wrapping `
+				+ `it again (label ${JSON.stringify(label ?? null)}) stacks a second bookkeeping layer that `
+				+ `can only ever read through the first — every miss pays twice and nothing is saved. `
+				+ `Use the inner cached driver as-is.`
+			);
+		}
 		// Registration is the choke point every construction path shares (this constructor, the
 		// `CachedRawStorage` wrapper, `withReadCache`), so naming the backing store here is what
 		// lets the pool refuse a second, permanently divergent view of it. Throws before anything else is

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

@@ -20,6 +20,28 @@ export class RevisionNotCoveredError extends Error {
 	}
 }
 
+/**
+ * Thrown by {@link IBlockStorage.savePendingTransaction} when the block has already committed a
+ * revision at or past the one the pending record names, so the record could never be promoted:
+ * `StorageRepo.commit` partitions such a block as already-done (`latest.rev === rev`, same action)
+ * or refuses it as stale (`latest.rev > rev`, or a rival at the same rev), and neither path runs
+ * the promotion that is the only thing removing a pending record on the success path. The record
+ * would then be reported as a conflicting in-flight action to every later writer of the block —
+ * see **Invariant P** on {@link IBlockStorage.promotePendingTransaction}.
+ *
+ * It is a throw rather than a returned status because a caller reaching it has reintroduced a
+ * check-then-act split that `StorageRepo.pend` closed by classifying and saving under one held
+ * latch; a status is a value a caller can ignore, which is the failure mode being designed out.
+ */
+export class PendRevisionTakenError extends Error {
+	constructor(readonly blockId: BlockId, readonly actionId: ActionId, readonly rev: number, readonly latest: ActionRev) {
+		super(`Block ${blockId}: cannot pend action ${actionId} at revision ${rev}; the block is `
+			+ `already committed at revision ${latest.rev} (action ${latest.actionId}), so the `
+			+ `pending record could never be promoted`);
+		this.name = 'PendRevisionTakenError';
+	}
+}
+
 /**
  * Interface for block-level storage operations.
  *
@@ -70,8 +92,27 @@ export interface IBlockStorage {
     /** Lists all pending action IDs */
     listPendingTransactions(): AsyncIterable<ActionId>;
 
-    /** Saves a pending action (seeding this block's metadata when it has none). */
-    savePendingTransaction(actionId: ActionId, transform: Transform, latch: BlockWriteLatch): Promise<void>;
+    /**
+     * Saves a pending action (seeding this block's metadata when it has none).
+     *
+     * `rev` is the revision the pend is claiming — the `rev` of the `PendRequest` this record
+     * belongs to, or `undefined` for a claim that names no revision (an insert-only pend). When it
+     * names one and the block has already committed at or past it, this REFUSES with
+     * {@link PendRevisionTakenError} and writes nothing.
+     *
+     * The question the refusal asks is **"could this record ever be promoted?"**, not "is this our
+     * own revision?" — which is why it does not use `isOwnRevision`. A single `latest.rev >= rev`
+     * comparison collapses both unpromotable cases: the writer's own already-committed revision
+     * (`===`, which `StorageRepo.commit` partitions as already-done and never promotes) and a
+     * rival's win (`>`, which `commit` refuses as stale). The error carries `latest` so the message
+     * can name which it was. `rev === undefined` names no revision, so no comparison applies.
+     *
+     * The refusal is an assertion, not a control-flow path: `StorageRepo.pend` classifies and saves
+     * 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.
+     */
+    savePendingTransaction(actionId: ActionId, transform: Transform, rev: number | undefined, latch: BlockWriteLatch): Promise<void>;
 
     /** Deletes a pending action */
     deletePendingTransaction(actionId: ActionId, latch: BlockWriteLatch): Promise<void>;
@@ -104,6 +145,10 @@ export interface IBlockStorage {
      * writes the committed one. A pending record left beside a committed one can never be promoted,
      * and is reported as a phantom conflicting action by `StorageRepo.pend` on every later write to
      * the block.
+     *
+     * The pend side of the invariant is enforced rather than merely required:
+     * {@link savePendingTransaction} refuses ({@link PendRevisionTakenError}) to write a pending
+     * record for a revision the block has already reached.
      */
     promotePendingTransaction(actionId: ActionId, latch: BlockWriteLatch): Promise<void>;
 

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

@@ -68,6 +68,23 @@ export interface IRawStorage {
 	 */
 	getStoreIdentity?(): StoreIdentity;
 
+	/**
+	 * Optional — present (and only ever `true`) when a write-through read cache
+	 * (`CachedStoreDriver`) sits BELOW this storage, whichever of the two documented
+	 * constructions built it: `new CachedRawStorage(inner)` or
+	 * `new KvRawStorage(new CachedStoreDriver(driver))`. Both contain a `CachedStoreDriver`,
+	 * and both report this marker; `withReadCache` reads it to decide whether to attach a
+	 * cache, so neither shape is misread as uncached.
+	 *
+	 * A property, not a method: there is no behavior to invoke, only a fact to report.
+	 *
+	 * OPTIONAL BY DESIGN, and typed as the literal `true` so "present and false" is
+	 * unrepresentable — truthiness IS the feature detection. Never install a `false` stub: an
+	 * uncached storage must omit the property entirely, exactly as `getStoreIdentity` /
+	 * `listBlockIds` / `getApproximateBytesUsed` are omitted when unsupported.
+	 */
+	readCached?: true;
+
 	/**
 	 * Approximate bytes currently stored by this backend.
 	 *

package/src/storage/kv-raw-storage.ts

@@ -26,11 +26,15 @@ export class KvRawStorage implements IRawStorage {
 	 * (`typeof storage.listBlockIds === 'function'`) sees the driver's true
 	 * capability instead of a stub that silently reports 0 / no seed. The same rule
 	 * governs `getStoreIdentity`: a stub returning `undefined` would make every store
-	 * look identity-less to consumers that dedupe on it.
+	 * look identity-less to consumers that dedupe on it. `readCached` follows the same rule
+	 * for the same reason: it is set only when the driver reports a read cache at or below
+	 * itself, so `withReadCache` sees whether this composition is REALLY already cached
+	 * rather than inferring it from a concrete class name (see {@link IRawStorage.readCached}).
 	 */
 	listBlockIds?: () => AsyncIterable<BlockId>;
 	getApproximateBytesUsed?: () => Promise<number>;
 	getStoreIdentity?: () => StoreIdentity;
+	readCached?: true;
 
 	constructor(private readonly driver: RawStoreDriver) {
 		if (driver.storeIdentity) {
@@ -42,6 +46,9 @@ export class KvRawStorage implements IRawStorage {
 		if (driver.approximateBytesUsed) {
 			this.getApproximateBytesUsed = () => driver.approximateBytesUsed!();
 		}
+		if (driver.readCached) {
+			this.readCached = true;
+		}
 	}
 
 	// --- Metadata ---

package/src/storage/raw-store-driver.ts

@@ -113,10 +113,36 @@ export interface RawStoreDriver {
 	 * - It identifies the STORE, not its contents.
 	 */
 	storeIdentity?(): StoreIdentity;
+
+	/**
+	 * Optional — present (and only ever `true`) when a write-through read cache
+	 * (`CachedStoreDriver`) sits AT or BELOW this driver, so a composition seam can ask
+	 * "is this already read-cached?" of the composition itself instead of guessing from a
+	 * concrete class name. Set unconditionally by `CachedStoreDriver` (it *is* the cache) and
+	 * passed up by every wrapper that fronts a driver, the same way `storeIdentity` is.
+	 *
+	 * A property, not a method: there is no behavior to invoke, only a fact to report.
+	 *
+	 * OPTIONAL BY DESIGN, and typed as the literal `true` so "present and false" is
+	 * unrepresentable — truthiness IS the feature detection. Never install a `false` stub: an
+	 * uncached driver must omit the property entirely, exactly as `storeIdentity` /
+	 * `listBlockIds` / `approximateBytesUsed` are omitted when unsupported.
+	 */
+	readCached?: true;
+
 	/** Optional — enumerate block ids with durable metadata (startup seed). Passed through by the kernel. */
 	listBlockIds?(): AsyncIterable<BlockId>;
 	/** Optional — best cheap byte estimate. Passed through by the kernel. */
 	approximateBytesUsed?(): Promise<number>;
 	/** Optional — release the underlying handle. */
 	close?(): Promise<void>;
+
+	// NOTE: forwarding each optional above is a WRITTEN contract for wrapper drivers, not an
+	// enforced one — a wrapper that forgets one silently reports the composition as less capable
+	// than it is, and for `readCached` that means a seam attaches a redundant second cache. Fine
+	// today: the only two wrapper drivers in the tree are `CachedStoreDriver` and
+	// `RawStorageDriverAdapter`, both forward deliberately (`CachedStoreDriver` withholds `close`
+	// on purpose, and says why at its site), and each has direct tests. If a THIRD wrapper driver
+	// appears, replace the per-wrapper tests with one shared conformance check that asserts
+	// forwarding of each optional, with an explicit per-wrapper exception list.
 }

package/src/storage/shared-cache-pool.ts

@@ -227,6 +227,11 @@ export class SharedCachePool {
 	 * a log line is not a way to notice. A registration with no identity is unaffected: it
 	 * registers exactly as it always did.
 	 *
+	 * This catches the SIDE-BY-SIDE pair only. A cache stacked over an already-cached inner is a
+	 * different (merely redundant) failure and is refused earlier, in `CachedStoreDriver`'s
+	 * constructor, so it never reaches here with the wrong story — see the two `readCached`
+	 * guards in `packages/db-p2p/docs/storage.md`.
+	 *
 	 * The check runs BEFORE any mutation, so a refused registration leaves the pool exactly as it
 	 * was — no store row, no consumed id, no claim.
 	 *
@@ -239,7 +244,7 @@ export class SharedCachePool {
 				`two caches over one backing store never converge: ${JSON.stringify(identity)} is already `
 				+ `cached (label ${JSON.stringify(claimed.label ?? null)}); this registration `
 				+ `(label ${JSON.stringify(label ?? null)}) would be a second, independent view. Share one `
-				+ `CachedRawStorage — withReadCache does this for you — or dispose the first.`
+				+ `read cache — withReadCache does this for you — or dispose the first.`
 			);
 		}
 		const handle = new CacheStoreHandle(`s${++this.storeCounter}`, label, identity);