@optimystic/db-p2p 0.24.1 → 0.25.0

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

@@ -1,10 +1,11 @@
 import type { BlockId, ActionId } from "@optimystic/db-core";
+import type { StoreIdentity } from "./store-identity.js";
 
 /**
  * Bytes-valued, per-logical-store driver surface. Each backend implements the
- * five block-storage stores (metadata, revisions, pending, transactions,
- * materialized) over its native mechanism (LevelDB tag-ranges, five SQLite
- * tables, five IndexedDB object stores, five filesystem subdirectories, five
+ * six block-storage stores (metadata, revisions, pending, transactions,
+ * materialized, proofs) over its native mechanism (LevelDB tag-ranges, six SQLite
+ * tables, six IndexedDB object stores, six filesystem subdirectories, six
  * in-memory maps). `KvRawStorage` layers all JSON serialization and call
  * orchestration on top — drivers never (de)serialize values and never see the
  * `BlockMetadata`/`Transform`/`IBlock` types. Drivers speak only
@@ -56,6 +57,23 @@ export interface RawStoreDriver {
 	getTransaction(blockId: BlockId, actionId: ActionId): Promise<Uint8Array | undefined>;
 	putTransaction(blockId: BlockId, actionId: ActionId, value: Uint8Array): Promise<void>;
 
+	/**
+	 * proofs store — keyed by (blockId, rev), the same key shape as the revisions
+	 * store. A revision's `BlockCommitProof` lives here and NOWHERE in the
+	 * transactions store: an action id is chosen by whoever originates a write
+	 * (a client's `pend`, a peer's restore archive) and is never re-derived or
+	 * format-checked, so any reserved action-id convention could be collided with
+	 * by an ordinary write. Separate keyspaces make the collision unrepresentable.
+	 *
+	 * There is deliberately NO `deleteProof`: a proof lives and dies with its
+	 * REVISION record, and no revision-delete site exists today (`RawStoreDriver`
+	 * has no revision delete at all — invalidations write compensating FORWARD
+	 * revisions). Whatever ever deletes a revision record must delete its proof;
+	 * until such a site exists this is a contract note, not a wired path.
+	 */
+	getProof(blockId: BlockId, rev: number): Promise<Uint8Array | undefined>;
+	putProof(blockId: BlockId, rev: number, value: Uint8Array): Promise<void>;
+
 	// materialized store — keyed by (blockId, actionId)
 	getMaterialized(blockId: BlockId, actionId: ActionId): Promise<Uint8Array | undefined>;
 	putMaterialized(blockId: BlockId, actionId: ActionId, value: Uint8Array): Promise<void>;
@@ -71,6 +89,30 @@ export interface RawStoreDriver {
 	 */
 	promote(blockId: BlockId, actionId: ActionId): Promise<void>;
 
+	/**
+	 * Optional — a stable, process-scoped string naming what this driver is backed by (a
+	 * resolved directory, an open database handle). Passed through by the kernel and by every
+	 * wrapper, so a cache and the storage it fronts name the same store.
+	 *
+	 * Contract — note it is ONE-DIRECTIONAL; read both halves before consuming it:
+	 * - Two drivers over DIFFERENT locations MUST NOT return equal strings. So **equality
+	 *   proves sameness**, and a consumer may merge on it. (The fs driver documents one exotic
+	 *   Windows exception at its own site.)
+	 * - Two drivers over the SAME location SHOULD return equal strings, but this is
+	 *   best-effort and several backends knowingly under-approximate: two handles opened over
+	 *   one database, or two spellings of one directory that cannot be collapsed synchronously,
+	 *   read as two identities. So **inequality proves nothing** — never treat it as evidence
+	 *   that two drivers are distinct stores. Each backend's `NOTE:` states its own gaps.
+	 * - Every string is scheme-prefixed so backends cannot collide: `file:`, `sqlite-handle:`,
+	 *   `idb-handle:`, `leveldb-handle:`. Compared for equality only — never parsed.
+	 * - Stable for the driver object's whole life; fixed at construction.
+	 * - OPTIONAL BY DESIGN. A driver that cannot honour the contract omits the method entirely
+	 *   and callers fall back to per-object behavior. Never install a stub that returns
+	 *   `undefined` — feature-detection (`typeof driver.storeIdentity === 'function'`) must see
+	 *   the driver's true capability.
+	 * - It identifies the STORE, not its contents.
+	 */
+	storeIdentity?(): StoreIdentity;
 	/** 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. */