@optimystic/db-core 1.0.0-beta.3 → 1.0.0

package/dist/src/utility/structural-equals.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Deep structural equality over the JSON-shaped values this codebase stores and transports:
+ * primitives, plain objects, arrays, and `Uint8Array` (compared by bytes — a byte array survives
+ * `structuredClone`, which is the in-process transport the test transactors use).
+ *
+ * Written for the tree's `unchanged` entry guard (`TreeEntryGuard` in
+ * `packages/db-core/src/collections/tree/struct.ts`), which must decide whether the entry
+ * currently committed at a key is still the one a staged write read — where one side has
+ * usually round-tripped through the log's encoding and the other has not. The three rules
+ * that follow from that:
+ *
+ * - **Object key ORDER is irrelevant.** An encoder may sort keys (see `canonicalJson`); the
+ *   value did not change because the bytes were reordered.
+ * - **A key whose value is `undefined` counts as ABSENT**, matching what JSON does to it, so
+ *   `{ a: 1, b: undefined }` and `{ a: 1 }` compare equal. Without this, an entry carrying an
+ *   explicit `undefined` property would refuse itself the moment it crossed a JSON boundary.
+ * - **`NaN` equals `NaN`.** A guard that can never accept its own value is a trap, not a check.
+ *
+ * NOTE: values outside that shape — `Date`, `Map`, `Set`, class instances — fall through to the
+ * plain-object arm and are compared by their own enumerable properties, which for two distinct
+ * `Date`s (no own properties) reports EQUAL. Entries are JSON-shaped by contract (they are
+ * serialized into the log), so nothing reaches that path today; if a richer entry type is ever
+ * introduced, this function needs a type tag before it can judge it.
+ *
+ * NOTE: the `Uint8Array` arm is correct but currently unreachable across the REAL transport. The
+ * peer-to-peer repo protocol is JSON both directions (`JSON.stringify` in
+ * `packages/db-p2p/src/protocol-client.ts`, `JSON.parse` in `packages/db-p2p/src/repo/service.ts`),
+ * and JSON turns a `Uint8Array` into an index-keyed object — which the arm below deliberately
+ * reports as NOT equal to the bytes it came from. So an entry type that is genuinely byte-shaped
+ * would make an `unchanged` guard refuse an honest write forever, not just once. No such entry
+ * type exists: the one candidate is the plugin's `EncodedRow` under `msgpack`, and that encoder
+ * throws `not yet implemented` (`packages/quereus-plugin-optimystic/src/schema/row-codec.ts`);
+ * under the `json` encoding BLOB columns are base64 strings before they ever reach a tree entry.
+ * If a byte-shaped entry type is ever introduced, the guard's `expected` needs a transport-stable
+ * encoding (base64, or a tagged wrapper) BEFORE this comparison can be trusted over the wire.
+ */
+export declare function structuralEquals(a: unknown, b: unknown): boolean;
+//# sourceMappingURL=structural-equals.d.ts.map

package/dist/src/utility/structural-equals.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"structural-equals.d.ts","sourceRoot":"","sources":["../../../src/utility/structural-equals.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,wBAAgB,gBAAgB,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC,EAAE,OAAO,GAAG,OAAO,CAOhE"}

package/dist/src/utility/structural-equals.js

@@ -0,0 +1,77 @@
+/**
+ * Deep structural equality over the JSON-shaped values this codebase stores and transports:
+ * primitives, plain objects, arrays, and `Uint8Array` (compared by bytes — a byte array survives
+ * `structuredClone`, which is the in-process transport the test transactors use).
+ *
+ * Written for the tree's `unchanged` entry guard (`TreeEntryGuard` in
+ * `packages/db-core/src/collections/tree/struct.ts`), which must decide whether the entry
+ * currently committed at a key is still the one a staged write read — where one side has
+ * usually round-tripped through the log's encoding and the other has not. The three rules
+ * that follow from that:
+ *
+ * - **Object key ORDER is irrelevant.** An encoder may sort keys (see `canonicalJson`); the
+ *   value did not change because the bytes were reordered.
+ * - **A key whose value is `undefined` counts as ABSENT**, matching what JSON does to it, so
+ *   `{ a: 1, b: undefined }` and `{ a: 1 }` compare equal. Without this, an entry carrying an
+ *   explicit `undefined` property would refuse itself the moment it crossed a JSON boundary.
+ * - **`NaN` equals `NaN`.** A guard that can never accept its own value is a trap, not a check.
+ *
+ * NOTE: values outside that shape — `Date`, `Map`, `Set`, class instances — fall through to the
+ * plain-object arm and are compared by their own enumerable properties, which for two distinct
+ * `Date`s (no own properties) reports EQUAL. Entries are JSON-shaped by contract (they are
+ * serialized into the log), so nothing reaches that path today; if a richer entry type is ever
+ * introduced, this function needs a type tag before it can judge it.
+ *
+ * NOTE: the `Uint8Array` arm is correct but currently unreachable across the REAL transport. The
+ * peer-to-peer repo protocol is JSON both directions (`JSON.stringify` in
+ * `packages/db-p2p/src/protocol-client.ts`, `JSON.parse` in `packages/db-p2p/src/repo/service.ts`),
+ * and JSON turns a `Uint8Array` into an index-keyed object — which the arm below deliberately
+ * reports as NOT equal to the bytes it came from. So an entry type that is genuinely byte-shaped
+ * would make an `unchanged` guard refuse an honest write forever, not just once. No such entry
+ * type exists: the one candidate is the plugin's `EncodedRow` under `msgpack`, and that encoder
+ * throws `not yet implemented` (`packages/quereus-plugin-optimystic/src/schema/row-codec.ts`);
+ * under the `json` encoding BLOB columns are base64 strings before they ever reach a tree entry.
+ * If a byte-shaped entry type is ever introduced, the guard's `expected` needs a transport-stable
+ * encoding (base64, or a tagged wrapper) BEFORE this comparison can be trusted over the wire.
+ */
+export function structuralEquals(a, b) {
+    if (a === b)
+        return true; // identical reference, or identical primitive
+    if (typeof a === 'number' && typeof b === 'number')
+        return Number.isNaN(a) && Number.isNaN(b);
+    if (a === null || b === null || typeof a !== 'object' || typeof b !== 'object')
+        return false;
+    if (a instanceof Uint8Array || b instanceof Uint8Array)
+        return bytesEqual(a, b);
+    if (Array.isArray(a) || Array.isArray(b))
+        return arraysEqual(a, b);
+    return objectsEqual(a, b);
+}
+/** Byte-wise comparison. A `Uint8Array` is only equal to another `Uint8Array` — a plain array or
+ *  object with the same numeric indices is a DIFFERENT encoding of the value, and treating it as
+ *  equal would let an encoding change slip past a guard unnoticed. */
+function bytesEqual(a, b) {
+    if (!(a instanceof Uint8Array) || !(b instanceof Uint8Array) || a.length !== b.length)
+        return false;
+    return a.every((byte, i) => byte === b[i]);
+}
+/** Element-wise comparison; position is meaning, so order matters here (unlike object keys). */
+function arraysEqual(a, b) {
+    if (!Array.isArray(a) || !Array.isArray(b) || a.length !== b.length)
+        return false;
+    return a.every((value, i) => structuralEquals(value, b[i]));
+}
+/** Compares the DEFINED own properties of two plain objects, order-independently. Equal counts of
+ *  defined keys plus a recursive match on each of `a`'s is sufficient: a key present in `b` but
+ *  not `a` would push `b`'s count higher, and a key `a` defines that `b` leaves undefined fails
+ *  the recursive compare. */
+function objectsEqual(a, b) {
+    const keys = definedKeys(a);
+    if (keys.length !== definedKeys(b).length)
+        return false;
+    return keys.every(key => structuralEquals(a[key], b[key]));
+}
+function definedKeys(value) {
+    return Object.keys(value).filter(key => value[key] !== undefined);
+}
+//# sourceMappingURL=structural-equals.js.map

package/dist/src/utility/structural-equals.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"structural-equals.js","sourceRoot":"","sources":["../../../src/utility/structural-equals.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,MAAM,UAAU,gBAAgB,CAAC,CAAU,EAAE,CAAU;IACtD,IAAI,CAAC,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC,CAAC,8CAA8C;IACxE,IAAI,OAAO,CAAC,KAAK,QAAQ,IAAI,OAAO,CAAC,KAAK,QAAQ;QAAE,OAAO,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;IAC9F,IAAI,CAAC,KAAK,IAAI,IAAI,CAAC,KAAK,IAAI,IAAI,OAAO,CAAC,KAAK,QAAQ,IAAI,OAAO,CAAC,KAAK,QAAQ;QAAE,OAAO,KAAK,CAAC;IAC7F,IAAI,CAAC,YAAY,UAAU,IAAI,CAAC,YAAY,UAAU;QAAE,OAAO,UAAU,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;IAChF,IAAI,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC;QAAE,OAAO,WAAW,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;IACnE,OAAO,YAAY,CAAC,CAA4B,EAAE,CAA4B,CAAC,CAAC;AACjF,CAAC;AAED;;sEAEsE;AACtE,SAAS,UAAU,CAAC,CAAS,EAAE,CAAS;IACvC,IAAI,CAAC,CAAC,CAAC,YAAY,UAAU,CAAC,IAAI,CAAC,CAAC,CAAC,YAAY,UAAU,CAAC,IAAI,CAAC,CAAC,MAAM,KAAK,CAAC,CAAC,MAAM;QAAE,OAAO,KAAK,CAAC;IACpG,OAAO,CAAC,CAAC,KAAK,CAAC,CAAC,IAAI,EAAE,CAAC,EAAE,EAAE,CAAC,IAAI,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;AAC5C,CAAC;AAED,gGAAgG;AAChG,SAAS,WAAW,CAAC,CAAS,EAAE,CAAS;IACxC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,MAAM,KAAK,CAAC,CAAC,MAAM;QAAE,OAAO,KAAK,CAAC;IAClF,OAAO,CAAC,CAAC,KAAK,CAAC,CAAC,KAAK,EAAE,CAAC,EAAE,EAAE,CAAC,gBAAgB,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;AAC7D,CAAC;AAED;;;6BAG6B;AAC7B,SAAS,YAAY,CAAC,CAA0B,EAAE,CAA0B;IAC3E,MAAM,IAAI,GAAG,WAAW,CAAC,CAAC,CAAC,CAAC;IAC5B,IAAI,IAAI,CAAC,MAAM,KAAK,WAAW,CAAC,CAAC,CAAC,CAAC,MAAM;QAAE,OAAO,KAAK,CAAC;IACxD,OAAO,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,EAAE,CAAC,gBAAgB,CAAC,CAAC,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;AAC5D,CAAC;AAED,SAAS,WAAW,CAAC,KAA8B;IAClD,OAAO,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC,KAAK,CAAC,GAAG,CAAC,KAAK,SAAS,CAAC,CAAC;AACnE,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@optimystic/db-core",
-  "version": "1.0.0-beta.3",
+  "version": "1.0.0",
   "type": "module",
   "description": "Core database functionality for Optimystic",
   "main": "dist/src/index.js",
@@ -50,8 +50,8 @@
     "@libp2p/crypto": "^5.1.13",
     "@libp2p/interface": "^3.2.4",
     "@libp2p/peer-id": "^6.0.4",
-    "@libp2p/peer-id-factory": "^4.2.4",
     "@multiformats/multiaddr": "^13.0.1",
+    "@noble/curves": "^2.0.1",
     "@types/chai": "^5.2.3",
     "@types/chai-as-promised": "^8.0.2",
     "@types/debug": "^4.1.12",

package/src/cluster/structs.ts

@@ -18,13 +18,33 @@ export type Signature =
 	 * counted toward the permanent-rejection threshold. `conflictWith` is the winning
 	 * transaction's messageHash: structured, signed, and readable without parsing prose.
 	 */
-	| { type: 'conflict'; signature: string; conflictWith: string };
+	| { type: 'conflict'; signature: string; conflictWith: string }
+	/**
+	 * This member refuses the transaction *for now* for the OTHER transient reason: the pend's blocks
+	 * are reserved by a different unresolved action in this member's durable storage. Retryable and
+	 * never counted toward the permanent-rejection threshold, exactly like `conflict`.
+	 *
+	 * Distinct from `conflict` because the two know different things, from different places:
+	 *  - `conflict` comes from the member's in-memory reservation table, where it holds the rival's
+	 *    whole {@link ClusterRecord} and can name its `messageHash`.
+	 *  - `held` comes from storage's pending list, which carries only an **action id** — and it fires
+	 *    precisely in the window where the rival has left the in-memory table (cleared at its
+	 *    pend-consensus) but not yet storage (cleared at its commit or cancel), so no `messageHash`
+	 *    exists to name.
+	 *
+	 * `heldBy` is therefore an action id, a different id space from `conflictWith`. Packing one into
+	 * the other would put two id spaces in a single unlabelled signed field, which is why this is its
+	 * own variant rather than a reused one. Where several rivals hold the blocks, `heldBy` names the
+	 * one the refusal returned on.
+	 */
+	| { type: 'held'; signature: string; heldBy: string };
 
 /**
  * The exact bytes a vote signature covers: `<hash>:<type>[:<extra>]`, where `extra` is the variant's
- * own payload — a reject's `rejectReason`, a conflict's `conflictWith`, nothing for an approve.
- * Folding the extra in is what makes it integrity-protected in transit rather than free-floating
- * prose.
+ * own payload — a reject's `rejectReason`, a conflict's `conflictWith`, a held's `heldBy`, nothing
+ * for an approve. Folding the extra in is what makes it integrity-protected in transit rather than
+ * free-floating prose. Each variant's extra is a single string, so the preimage needs no encoding
+ * scheme; a variant that ever needs two fields must define one rather than concatenating here.
  *
  * Producers and verifiers must both build the preimage here. It lives beside {@link Signature}
  * rather than in either consumer because a second copy that forgets a variant does not fail loudly:
@@ -42,6 +62,7 @@ export function clusterVoteVerificationPayload(hash: string, signature: Signatur
 	switch (signature.type) {
 		case 'reject': return clusterVoteSigningPayload(hash, 'reject', signature.rejectReason);
 		case 'conflict': return clusterVoteSigningPayload(hash, 'conflict', signature.conflictWith);
+		case 'held': return clusterVoteSigningPayload(hash, 'held', signature.heldBy);
 		default: return clusterVoteSigningPayload(hash, signature.type);
 	}
 }
@@ -241,11 +262,11 @@ export interface ClusterConsensusConfig {
 	 * single reset here would otherwise drop the peer and sink super-majority.
 	 */
 	promiseImmediateRetries?: number;
-	/** Read-repair behavior: 'off' (only fetch on missing — legacy), 'lazy' (fetch when local age > window), 'paranoid' (always verify against cluster on read, missing blocks included). Default 'lazy'. In 'off' and 'lazy', a missing block whose cohort is this node alone is re-consulted at most once per `readRepairWindowMs`. */
+	/** Read-repair behavior: 'off' (only fetch on missing — legacy), 'lazy' (fetch when local age > window), 'paranoid' (always verify against cluster on read). Default 'lazy'. In every mode a block missing locally consults its cohort on every read. */
 	readRepairMode?: 'off' | 'lazy' | 'paranoid';
-	/** For 'lazy' mode: read-repair triggers when (now - localEntry.lastSeenCommitMs) > this. In 'lazy' and 'off' it is also how long a settled absence is remembered. Default 10000. */
+	/** For 'lazy' mode: read-repair triggers when (now - localEntry.lastSeenCommitMs) > this. Default 10000. */
 	readRepairWindowMs?: number;
-	/** Per-read probability of a cohort check in 'lazy' mode even within the window — of a held block or a settled absence (0..1). Default 0 (no random check). */
+	/** Per-read probability of triggering read-repair in 'lazy' mode even within the window (0..1). Default 0 (no random check). */
 	readRepairSampleRate?: number;
 	/**
 	 * When FRET has no confident network-size estimate, allow an undersized cluster