@optimystic/db-core 0.24.2 → 0.25.1

package/src/cluster/membership.ts

@@ -1,85 +1,87 @@
-import type { RepoMessage } from "../network/repo-protocol.js";
-import type { ClusterPeers, ClusterRecord, Signature } from "./structs.js";
-import { sha256 } from "multiformats/hashes/sha2";
-import { base58btc } from "multiformats/bases/base58";
-import { toString as uint8ArrayToString } from "uint8arrays/to-string";
-
-/**
- * Membership-binding version a new coordinator emits. A record at this version folds a
- * {@link membershipDigest} of its peer set into `messageHash` / `promiseHash` / `commitHash`, so the
- * responsible peer set is covered by every signature (see `docs/correctness.md` §2). Absent or `1` marks
- * a legacy *unbound* record (pre-binding history) whose hashes must verify byte-identically to before
- * this change.
- */
-export const CURRENT_MEMBERSHIP_VERSION = 2 as const;
-
-/** Deterministic JSON: sorts object keys so the hash is independent of key insertion order. */
-function canonicalJson(value: unknown): string {
-	return JSON.stringify(value, (_, v) =>
-		v && typeof v === 'object' && !Array.isArray(v)
-			? Object.keys(v).sort().reduce((o: Record<string, unknown>, k) => { o[k] = v[k]; return o; }, {})
-			: v
-	);
-}
-
-/**
- * Canonical membership digest for a peer set: `base64url(SHA256(canonicalJson(sorted peer-id list)))`.
- *
- * Derived from the sorted peer-id list ONLY — not multiaddrs or public keys. Multiaddrs churn and a
- * peer's public key is already a function of its id, so folding either in would make identity unstable
- * without adding agreement value. The set of ids IS the membership. The digest is therefore independent
- * of peer-map key insertion order and of multiaddr / pubkey contents; adding or removing one id changes
- * it. `membershipDigest({})` (the empty set) is a fixed constant.
- */
-export async function membershipDigest(peers: ClusterPeers): Promise<string> {
-	const ids = Object.keys(peers ?? {}).sort();
-	const bytes = new TextEncoder().encode(canonicalJson(ids));
-	const hash = await sha256.digest(bytes);
-	return uint8ArrayToString(hash.digest, 'base64url');
-}
-
-/**
- * The membership digest that participates in a record's hashes, or `undefined` for a legacy (v1 /
- * unversioned) record. `undefined` selects the pre-binding hashing (empty-string concat is a no-op), so
- * a v1 record hashes byte-identically to before this change. A v2 record folds in its declared
- * `membershipDigest`.
- */
-export function recordMembershipDigest(record: Pick<ClusterRecord, 'membershipVersion' | 'membershipDigest'>): string | undefined {
-	return record.membershipVersion === 2 ? record.membershipDigest : undefined;
-}
-
-/**
- * `messageHash` = `base58btc(SHA256(canonicalJson(message) + digest))`.
- *
- * `digest` `undefined` → legacy v1 preimage (`canonicalJson(message)` only); passing the membership
- * digest folds the peer set in (v2). Empty-string concat means the v1 image is byte-identical to the
- * pre-binding implementation.
- */
-export async function computeClusterMessageHash(message: RepoMessage, digest?: string): Promise<string> {
-	const bytes = new TextEncoder().encode(canonicalJson(message) + (digest ?? ''));
-	const hash = await sha256.digest(bytes);
-	return base58btc.encode(hash.digest);
-}
-
-/**
- * `promiseHash` = `base64url(SHA256(messageHash + canonicalJson(message) + digest))`.
- *
- * `digest` `undefined` → legacy v1 preimage; passing it folds the peer set in (v2).
- */
-export async function computeClusterPromiseHash(messageHash: string, message: RepoMessage, digest?: string): Promise<string> {
-	const bytes = new TextEncoder().encode(messageHash + canonicalJson(message) + (digest ?? ''));
-	const hash = await sha256.digest(bytes);
-	return uint8ArrayToString(hash.digest, 'base64url');
-}
-
-/**
- * `commitHash` = `base64url(SHA256(messageHash + canonicalJson(message) + digest + canonicalJson(promises)))`.
- *
- * `digest` `undefined` → legacy v1 preimage; passing it folds the peer set in (v2). The digest sits
- * between the message and the promises image, matching the v2 layout in `docs/correctness.md`.
- */
-export async function computeClusterCommitHash(messageHash: string, message: RepoMessage, promises: Record<string, Signature>, digest?: string): Promise<string> {
-	const bytes = new TextEncoder().encode(messageHash + canonicalJson(message) + (digest ?? '') + canonicalJson(promises));
-	const hash = await sha256.digest(bytes);
-	return uint8ArrayToString(hash.digest, 'base64url');
-}
+import type { RepoMessage } from "../network/repo-protocol.js";
+import type { ClusterPeers, ClusterRecord, Signature } from "./structs.js";
+import { sha256 } from "multiformats/hashes/sha2";
+import { base58btc } from "multiformats/bases/base58";
+import { toString as uint8ArrayToString } from "uint8arrays/to-string";
+import { canonicalJson } from "../utility/canonical-json.js";
+
+/**
+ * Membership-binding version a new coordinator emits. A record at this version folds a
+ * {@link membershipDigest} of its peer set into `messageHash` / `promiseHash` / `commitHash`, so the
+ * responsible peer set is covered by every signature (see `docs/correctness.md` §2). Absent or `1` marks
+ * a legacy *unbound* record (pre-binding history) whose hashes must verify byte-identically to before
+ * this change.
+ */
+export const CURRENT_MEMBERSHIP_VERSION = 2 as const;
+
+/**
+ * Canonical membership digest for a peer set: `base64url(SHA256(canonicalJson(sorted peer-id list)))`.
+ *
+ * Derived from the sorted peer-id list ONLY — not multiaddrs or public keys. Multiaddrs churn and a
+ * peer's public key is already a function of its id, so folding either in would make identity unstable
+ * without adding agreement value. The set of ids IS the membership. The digest is therefore independent
+ * of peer-map key insertion order and of multiaddr / pubkey contents; adding or removing one id changes
+ * it. `membershipDigest({})` (the empty set) is a fixed constant.
+ */
+export async function membershipDigest(peers: ClusterPeers): Promise<string> {
+	return membershipDigestFromIds(Object.keys(peers ?? {}));
+}
+
+/**
+ * Canonical membership digest for an explicit peer-id list — the same digest {@link membershipDigest}
+ * derives from a peer map's keys. ONE implementation, so a verifier reading a stored `peerIds` list
+ * (e.g. a persisted block commit proof) and a coordinator reading live `ClusterPeers` can never
+ * disagree. Sorts a copy; the caller's array is not mutated.
+ */
+export async function membershipDigestFromIds(ids: readonly string[]): Promise<string> {
+	const sorted = [...ids].sort();
+	const bytes = new TextEncoder().encode(canonicalJson(sorted));
+	const hash = await sha256.digest(bytes);
+	return uint8ArrayToString(hash.digest, 'base64url');
+}
+
+/**
+ * The membership digest that participates in a record's hashes, or `undefined` for a legacy (v1 /
+ * unversioned) record. `undefined` selects the pre-binding hashing (empty-string concat is a no-op), so
+ * a v1 record hashes byte-identically to before this change. A v2 record folds in its declared
+ * `membershipDigest`.
+ */
+export function recordMembershipDigest(record: Pick<ClusterRecord, 'membershipVersion' | 'membershipDigest'>): string | undefined {
+	return record.membershipVersion === 2 ? record.membershipDigest : undefined;
+}
+
+/**
+ * `messageHash` = `base58btc(SHA256(canonicalJson(message) + digest))`.
+ *
+ * `digest` `undefined` → legacy v1 preimage (`canonicalJson(message)` only); passing the membership
+ * digest folds the peer set in (v2). Empty-string concat means the v1 image is byte-identical to the
+ * pre-binding implementation.
+ */
+export async function computeClusterMessageHash(message: RepoMessage, digest?: string): Promise<string> {
+	const bytes = new TextEncoder().encode(canonicalJson(message) + (digest ?? ''));
+	const hash = await sha256.digest(bytes);
+	return base58btc.encode(hash.digest);
+}
+
+/**
+ * `promiseHash` = `base64url(SHA256(messageHash + canonicalJson(message) + digest))`.
+ *
+ * `digest` `undefined` → legacy v1 preimage; passing it folds the peer set in (v2).
+ */
+export async function computeClusterPromiseHash(messageHash: string, message: RepoMessage, digest?: string): Promise<string> {
+	const bytes = new TextEncoder().encode(messageHash + canonicalJson(message) + (digest ?? ''));
+	const hash = await sha256.digest(bytes);
+	return uint8ArrayToString(hash.digest, 'base64url');
+}
+
+/**
+ * `commitHash` = `base64url(SHA256(messageHash + canonicalJson(message) + digest + canonicalJson(promises)))`.
+ *
+ * `digest` `undefined` → legacy v1 preimage; passing it folds the peer set in (v2). The digest sits
+ * between the message and the promises image, matching the v2 layout in `docs/correctness.md`.
+ */
+export async function computeClusterCommitHash(messageHash: string, message: RepoMessage, promises: Record<string, Signature>, digest?: string): Promise<string> {
+	const bytes = new TextEncoder().encode(messageHash + canonicalJson(message) + (digest ?? '') + canonicalJson(promises));
+	const hash = await sha256.digest(bytes);
+	return uint8ArrayToString(hash.digest, 'base64url');
+}

package/src/cluster/structs.ts

@@ -66,8 +66,15 @@ export type ClusterRecord = {
 	membershipVersion?: 1 | 2;
 	/** Membership digest of {@link ClusterRecord.peers}; present iff `membershipVersion === 2`. base64url. */
 	membershipDigest?: string;
+	/**
+	 * The transaction's operations and the block the coordinator selected the cohort by
+	 * ({@link RepoMessage.coordinatingBlockIds}). There is deliberately NO top-level copy of the
+	 * coordinating block ids on the record: `messageHash` covers `message` only, so a duplicate at
+	 * this level would be outside every hash and any relaying peer could rewrite it — and the
+	 * membership admission gate derives its own cohort view from exactly that id
+	 * (`ClusterMember.deriveExpectedClusterView`). One source of truth, inside the hash.
+	 */
 	message: RepoMessage;
-	coordinatingBlockIds?: string[];
 	promises: { [peerId: string]: Signature };
 	commits: { [peerId: string]: Signature };
 	/** Sender's recommended cluster size: min(estimated network size, configured cluster size) */
@@ -183,4 +190,24 @@ export interface ClusterConsensusConfig {
 	 * single-node / local dev where you knowingly run below the safe floor.
 	 */
 	allowUnvalidatedSmallCluster?: boolean;
+	/**
+	 * What a member WITH a transaction validator does with a pend that carries no `validation`
+	 * payload. See {@link UnvalidatablePendPolicy}; default 'accept'.
+	 */
+	unvalidatablePendPolicy?: UnvalidatablePendPolicy;
 }
+
+/**
+ * What a receiver WITH a transaction checker does with a pend that carries no
+ * {@link PendRequest.validation} payload — the single-collection (`Collection.sync`) shape, which
+ * has no transaction to re-execute.
+ *
+ * - `'accept'` (default) preserves the historical behaviour: the pend is approved unchecked.
+ * - `'reject'` is the fail-closed posture for a deployment that has decided every write must be
+ *   re-checkable; it REFUSES `Collection.sync` writes, which is the point, not a bug.
+ *
+ * Irrelevant on a receiver with no checker, which never re-checks anything. Named once here and
+ * referenced by every tier that carries the knob (`ClusterConsensusConfig`, db-p2p's
+ * `ClusterPolicyOptions` and `StorageRepoOptions`) so the three cannot drift apart.
+ */
+export type UnvalidatablePendPolicy = 'accept' | 'reject';

package/src/collection/action.ts

@@ -29,3 +29,20 @@ export type ActionContext = {
 	/** Optional uncommitted pending action ID */
 	actionId?: ActionId;
 };
+
+/** The id of the action that produced `rev` within `context`'s uncheckpointed committed list,
+ * or `undefined` when the list names no action at that revision.
+ *
+ * `undefined` is legitimate, not an error, and has three causes: the revision's log slot belongs
+ * to an entry that carries no action (a CHECKPOINT or an INVALIDATION entry takes a revision of
+ * its own); `rev` predates the most recent checkpoint, which is as far back as a context read off
+ * a log reaches (`Log.getActionContext`, `Log.getFrom`); or the context was never built from a
+ * log at all. A caller printing this must carry a placeholder rather than invent an id.
+ *
+ * NOTE: linear in `committed`, which grows one entry per commit between context reads; fine now —
+ * every caller is a `debug`-gated diagnostic, so this does not run on a normal path at all. If a
+ * non-diagnostic caller ever appears, index the lookup or search from the end (the entry at the
+ * context's own `rev` is normally the last one). */
+export function actionIdAt(context: ActionContext, rev: number): ActionId | undefined {
+	return context.committed.find(entry => entry.rev === rev)?.actionId;
+}