@optimystic/db-p2p 0.21.0 → 0.24.0

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

@@ -0,0 +1,186 @@
+import type { BlockId, ActionId } from "@optimystic/db-core";
+import type { RawStoreDriver } from "./raw-store-driver.js";
+import { SharedCachePool, type PoolEntry, type PoolEntryOwner } from "./shared-cache-pool.js";
+/**
+ * Write-through coherent cache over any {@link RawStoreDriver}, bounded by a shared
+ * {@link SharedCachePool}. Wrap a backend's driver with this before handing it to
+ * `KvRawStorage` and every read the kernel issues is served from memory while the entry
+ * stays resident in the pool — the pool's 2Q admission keeps hot per-store entries
+ * protected while one-off bulk scans die in probation (see the pool's class doc).
+ *
+ * **Coherence, not eviction policy.** Every save stores its value INTO the cache as it writes
+ * the inner driver, rather than invalidating. The cache therefore always holds the last
+ * durable value for resident entries and never needs to re-read a key it has seen while that
+ * entry survives. This is what a plain invalidate-on-write memo cannot achieve at this seam:
+ * the hot reads exist to observe the writes, so invalidation lands between nearly every read
+ * pair (measured: only a 23% cut).
+ *
+ * **Why this is sound** — the invariants in `docs/storage.md` ("Invariants", 1–5):
+ * 1. every backend write funnels through `IRawStorage` (and thus this driver) in-process, so
+ *    the cache sees every mutation;
+ * 2. every writer of `meta.latest` holds the per-block commit latch, and each cache update is
+ *    synchronous with its inner write (no `await` between the inner call resolving and the
+ *    cache mutation), so latch-protected read-after-write sees the new value exactly as a
+ *    driver read would;
+ * 3. committed revisions and materializations are append-only.
+ *
+ * **Precondition: one process owns the store** (Invariant 5). A second process writing the
+ * same backend bypasses this wrapper and makes cached values stale in ways that feed
+ * consensus decisions. Not enforced in code — see docs/storage.md.
+ *
+ * **The cache is always clean, never dirty.** No write is deferred, reordered, or coalesced;
+ * the inner driver's durable state never depends on cache contents. Eviction of ANY entry at
+ * ANY instant is therefore correct — the next read falls through — which is precisely what
+ * lets the shared pool evict freely, without pins, dirty tracking, or an exhaustion error.
+ * Keep it that way: if a change here ever needs a dirty or pinned entry, the design has gone
+ * wrong — stop and reconsider.
+ *
+ * **Pool discipline** (the one rule new code here must follow): mutate this wrapper's own
+ * state FIRST, then make the pool call (`admit`/`updated`/`touch`/`drop`) LAST, and never
+ * touch cache state after the pool call — pool mutations can synchronously evict any entry,
+ * including the one just written. The eviction callback ({@link onPoolEvict}) removes only
+ * the wrapper's reference and never calls back into the pool.
+ *
+ * **Values are cached as bytes**, exactly the encoded value the kernel wrote or the driver
+ * returned. The kernel decodes fresh objects from those bytes on every read, so the
+ * clone-on-read/clone-on-write discipline stays structural (same argument as the codec
+ * boundary itself), and an entry's byte size feeds the pool's budget directly.
+ * NOTE: every cache hit still pays one JSON.parse in the kernel; if decode ever shows up hot
+ * on large materialized blocks, cache decoded objects plus an explicit clone instead.
+ *
+ * **Do not wrap `MemoryStoreDriver`.** The memory driver already holds the same byte
+ * references in maps; wrapping it duplicates every map entry (the bytes themselves are
+ * shared, so no byte copy — but the bookkeeping is pure overhead with nothing to save).
+ */
+export declare class CachedStoreDriver implements RawStoreDriver, PoolEntryOwner {
+    private readonly inner;
+    private readonly pool;
+    private readonly blocks;
+    private readonly store;
+    /**
+     * Optional passthroughs are wired only when the inner driver provides them, mirroring
+     * `KvRawStorage`'s constructor: feature-detection above this wrapper must observe the
+     * inner driver's true capability. `listBlockIds` deliberately bypasses the cache — it
+     * enumerates the inner metadata keyspace, which funnelled writes keep authoritative.
+     * `close` is the deliberate exception (a real method below): releasing the store's pool
+     * registration is THIS wrapper's own capability, needed whether or not the inner driver
+     * has anything to close.
+     */
+    listBlockIds?: () => AsyncIterable<BlockId>;
+    approximateBytesUsed?: () => Promise<number>;
+    constructor(inner: RawStoreDriver, pool?: SharedCachePool, label?: string);
+    /**
+     * Drop every cached entry (releasing their pool residency) and this store's ghost keys —
+     * pre-clear recency must not fast-track post-clear refills into the protected queue.
+     * Always safe (the cache is clean — see class doc); the next read of each key re-consults
+     * the inner driver. In-flight enumerations notice the identity change of their entry
+     * objects and decline to claim completeness.
+     */
+    clear(): void;
+    /**
+     * Release this store entirely: drop all entries, unregister from the pool (the store id
+     * is never reused), and close the inner driver if it can be closed. A departed workspace
+     * that skips this leaks only cold entries the pool will evict under pressure — but call
+     * it; on a long-lived provider node the polite release is what keeps occupancy honest.
+     */
+    close(): Promise<void>;
+    /** This store's live pool occupancy; pool-wide numbers come from `SharedCachePool.stats()`. */
+    storeStats(): {
+        id: string;
+        label: string | undefined;
+        bytes: number;
+        entries: number;
+    };
+    /**
+     * Pool eviction callback: remove OUR reference to the entry (identity-checked, so a stale
+     * callback can never delete a successor) and reap the block state if that emptied it.
+     * Runs synchronously inside a pool mutation — must not call back into the pool.
+     */
+    onPoolEvict(entry: PoolEntry): void;
+    /**
+     * NOTE: this allocates an entry for EVERY block id touched, including ids that turn out
+     * not to exist (the proven-absent negative is the point). The shared pool charges those
+     * negatives — and the bare bookkeeping of empty container entries — against its budget
+     * (`ENTRY_BASE` + key), and {@link dropIfEmpty} reaps block states whose last entry is
+     * gone, so a remote peer streaming probes for nonexistent blocks (`StorageRepo.get` is
+     * reachable with an arbitrary block-id list) churns the probation queue instead of
+     * growing this map without bound.
+     */
+    private state;
+    /** Reap a block state holding no entries, so evictions and declined fills leave nothing behind. */
+    private dropIfEmpty;
+    /**
+     * An inner read threw after {@link state} allocated: reap the (uncharged) empty state so
+     * a stream of probes against a throwing backend cannot grow `blocks` for free.
+     */
+    private reapOnThrow;
+    /**
+     * Install or update a point entry (meta / pending / tx / mat) as the LAST step of a write
+     * or read-miss fill. Handles the pool's large-value bypass: an over-limit value is not
+     * cached, and an existing entry growing over the limit is dropped to unknown (holding the
+     * stale prior value would be wrong; holding the oversized one would defeat the bypass).
+     */
+    private cachePoint;
+    /**
+     * Cache a read-miss result into one of the map-backed entry classes, under BOTH fill
+     * guards. `started` is the state object the read began on:
+     *
+     * - **value guard** — fill only while the entry is still unknown, so a newer funnelled
+     *   write that landed during the inner read is not clobbered by this older value;
+     * - **identity guard** — decline entirely if `clear()` (or the empty-state reaper)
+     *   swapped the state object during the inner read. Without it a resumed read reinstalls
+     *   its pre-clear value into the fresh state, and the newer write that superseded it went
+     *   out with the old state — so the stale value would then be served forever. The
+     *   revision and pending-list paths make the same identity check against their own pool
+     *   entries.
+     */
+    private fillMiss;
+    getMetadata(blockId: BlockId): Promise<Uint8Array | undefined>;
+    putMetadata(blockId: BlockId, value: Uint8Array): Promise<void>;
+    /**
+     * Get or eagerly admit the block's revision-map entry. Eager (before any inner await) so
+     * the fill guards have a stable identity to check across the await; the empty container
+     * is charged its base cost, so probe streams pay for their bookkeeping. Returns
+     * `undefined` when the pool bypasses even the base charge (absurdly small budget) — the
+     * callers then pass straight through to the inner driver, uncached.
+     */
+    private ensureRevs;
+    getRevision(blockId: BlockId, rev: number): Promise<Uint8Array | undefined>;
+    putRevision(blockId: BlockId, rev: number, value: Uint8Array): Promise<void>;
+    rangeRevisions(blockId: BlockId, lo: number, hi: number, reverse: boolean): AsyncIterable<[number, Uint8Array]>;
+    /** Same eager-admission shape (and bypass fallback) as {@link ensureRevs}, for the pending-id set. */
+    private ensurePendList;
+    /** Mirror a funnelled pend into the id set, if one is resident. Re-reads the entry — the write that preceded this call may have evicted it. */
+    private notePendListAdd;
+    private notePendListRemove;
+    /** Failed pending write: the affected value entry AND the id set drop to unknown. */
+    private dropPendingState;
+    getPending(blockId: BlockId, actionId: ActionId): Promise<Uint8Array | undefined>;
+    putPending(blockId: BlockId, actionId: ActionId, value: Uint8Array): Promise<void>;
+    deletePending(blockId: BlockId, actionId: ActionId): Promise<void>;
+    listPendingActionIds(blockId: BlockId): AsyncIterable<ActionId>;
+    getTransaction(blockId: BlockId, actionId: ActionId): Promise<Uint8Array | undefined>;
+    putTransaction(blockId: BlockId, actionId: ActionId, value: Uint8Array): Promise<void>;
+    getMaterialized(blockId: BlockId, actionId: ActionId): Promise<Uint8Array | undefined>;
+    putMaterialized(blockId: BlockId, actionId: ActionId, value: Uint8Array): Promise<void>;
+    deleteMaterialized(blockId: BlockId, actionId: ActionId): Promise<void>;
+    /** Error-path invalidation of one map-backed entry (write failed → unknown). */
+    private dropMapEntry;
+    /**
+     * The inner driver performs the atomic pending → committed move; this wrapper then mirrors
+     * it as one synchronous cache mutation sequence. When the pending transform was never
+     * cached — pended before this wrapper attached, or its entry EVICTED by the pool — the
+     * committed entry is INVALIDATED rather than synthesized: fabricating it would recreate
+     * exactly the phantom-record class Invariant P exists to prevent. Invalidation also
+     * removes any cached negative for the committed entry, which the promote has just made
+     * stale.
+     *
+     * Eviction landing between the three coupled mutations is safe by construction: the inner
+     * atomic move has already resolved before the first cache mutation, so each of the three
+     * entries (pending value, pending-id set, committed value) steps from one individually
+     * coherent state to another — an eviction merely turns one of those steps into "unknown,
+     * fall through", never into a fabricated value.
+     */
+    promote(blockId: BlockId, actionId: ActionId): Promise<void>;
+}
+//# sourceMappingURL=cached-store-driver.d.ts.map

package/dist/src/storage/cached-store-driver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cached-store-driver.d.ts","sourceRoot":"","sources":["../../../src/storage/cached-store-driver.ts"],"names":[],"mappings":"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"}