@optimystic/db-p2p 0.25.1 → 0.27.0

package/src/storage/with-read-cache.ts

@@ -102,8 +102,12 @@ class Lease implements ReadCacheLease {
  * Returns the storage **unchanged**, with no `lease`, when caching would not pay:
  * - `MemoryRawStorage` is already in memory; the cache would duplicate every map entry's
  *   bookkeeping with nothing to save (see `CachedStoreDriver`'s class doc).
- * - An already-cached storage (a host that wrapped before handing it over) is not wrapped twice,
- *   and stays the host's to dispose.
+ * - A storage that reports {@link IRawStorage.readCached} (a host that attached a cache before
+ *   handing it over) is not wrapped twice, and stays the host's to dispose. The capability, not
+ *   a class check: BOTH documented constructions — `new CachedRawStorage(inner)` and
+ *   `new KvRawStorage(new CachedStoreDriver(driver))` — report it, and only the first is a
+ *   `CachedRawStorage`. Checking the class instead sent the driver-level shape down the
+ *   construct path, where the pool's identity guard threw and the host's node failed to start.
  *
  * Why this is needed at all: `BlockStorage` re-reads block metadata on essentially every
  * operation and `StorageRepo` builds a fresh `BlockStorage` per block per call, so nothing above
@@ -122,9 +126,9 @@ class Lease implements ReadCacheLease {
  * unwrapped instance handed to two consumers). Identity is one-directional — equal proves
  * sameness, unequal proves nothing — so backends whose identity under-approximates (path
  * aliases, two handles over one database; each backend's `NOTE:` lists its gaps) can still end
- * up with two caches; and a host that builds its own `CachedRawStorage` never enters the
- * registry, so a second consumer wrapping a fresh instance over that store still gets a second
- * cache. What remains of Invariant 5 (`packages/db-p2p/docs/storage.md`) is the cross-process
+ * up with two caches; and a host that builds its own cache — in either construction — never
+ * enters the registry, so a second consumer wrapping a fresh instance over that store still gets
+ * a second cache. What remains of Invariant 5 (`packages/db-p2p/docs/storage.md`) is the cross-process
  * case: the filesystem driver takes no lock, and a second process's writes bypass this cache.
  *
  * On a dedupe hit the FIRST caller's `label` and `pool` stick: `pool.stats()` shows whoever
@@ -148,7 +152,13 @@ class Lease implements ReadCacheLease {
  *               dedupe hit.
  */
 export function withReadCache(storage: IRawStorage, label?: string, pool?: SharedCachePool): ResolvedReadCache {
-	if (storage instanceof MemoryRawStorage || storage instanceof CachedRawStorage) {
+	// `readCached` is a plain property read, which keeps this whole function synchronous — see
+	// the "no `await` between lookup and insert" note above; never make it an accessor that
+	// could become async. `MemoryRawStorage` never carries the marker (its driver is uncached);
+	// it is excluded for a different reason and keeps its own class check. Note a plain
+	// `KvRawStorage` over a bare `MemoryStoreDriver` is NOT a `MemoryRawStorage` and is still
+	// wrapped — deliberate, and pinned by a test.
+	if (storage instanceof MemoryRawStorage || storage.readCached) {
 		return { storage, lease: undefined };
 	}