@optimystic/db-core 0.24.1 → 0.25.0

package/src/index.ts

@@ -1,23 +1,24 @@
-export * from "./blocks/index.js";
-export * from "./btree/index.js";
-export * from "./chain/index.js";
-export * from "./cluster/index.js";
-export * from "./cohort-topic/index.js";
-export * from "./collection/index.js";
-export * from "./collections/index.js";
-export * from "./log/index.js";
-export * from "./matchmaking/index.js";
-export * from "./network/index.js";
-export * from "./reactivity/index.js";
-export * from "./transaction/index.js";
-export * from "./transactor/index.js";
-export * from "./transform/index.js";
-export * from "./utility/groupby.js";
-export * from "./utility/hash-string.js";
-export * from "./utility/latches.js";
-export * from "./utility/nameof.js";
-export * from "./utility/ensured.js";
-export * from "./utility/pending.js";
-export * from "./utility/block-id-to-bytes.js";
-export * from "./utility/lru-map.js";
-export * from "./utility/backoff.js";
+export * from "./blocks/index.js";
+export * from "./btree/index.js";
+export * from "./chain/index.js";
+export * from "./cluster/index.js";
+export * from "./cohort-topic/index.js";
+export * from "./collection/index.js";
+export * from "./collections/index.js";
+export * from "./log/index.js";
+export * from "./matchmaking/index.js";
+export * from "./network/index.js";
+export * from "./reactivity/index.js";
+export * from "./transaction/index.js";
+export * from "./transactor/index.js";
+export * from "./transform/index.js";
+export * from "./utility/canonical-json.js";
+export * from "./utility/groupby.js";
+export * from "./utility/hash-string.js";
+export * from "./utility/latches.js";
+export * from "./utility/nameof.js";
+export * from "./utility/ensured.js";
+export * from "./utility/pending.js";
+export * from "./utility/block-id-to-bytes.js";
+export * from "./utility/lru-map.js";
+export * from "./utility/backoff.js";

package/src/network/i-repo.ts

@@ -1,46 +1,59 @@
-import type { ActionBlocks, CommitResult, GetBlockResults, PendResult, PendRequest, BlockGets, BlockId, ActionId } from "../index.js";
-
-export type MessageOptions = {
-	expiration?: number;
-	signal?: AbortSignal;
-	/**
-	 * Per-peer dial deadline in ms. Bounds only the dial portion of a call, so
-	 * an unreachable peer fails fast and the caller's retry loop can re-pick
-	 * a different coordinator. Independent of `expiration` (the overall budget):
-	 * a 30s transaction with `dialTimeoutMs: 3000` can afford ten 3s dial
-	 * attempts against different peers. Once a dial succeeds, the response wait
-	 * is bound by the remaining `expiration` budget. Undefined means "do not
-	 * impose a separate dial cap; the overall budget is the cap".
-	 */
-	dialTimeoutMs?: number;
-	/**
-	 * Blocks this coordinator is responsible for driving through consensus. Threaded
-	 * from {@link NetworkTransactor.pend}'s batch (which consolidates several blocks
-	 * onto one coordinating peer) into {@link CoordinatorRepo.pend}, which uses it to
-	 * pick the cluster anchor. Absent on bare per-block paths, which fall back to the
-	 * transforms' own block ids.
-	 */
-	coordinatingBlockIds?: BlockId[];
-}
-
-export type RepoCommitRequest = {
-	blockIds: BlockId[];
-	actionId: ActionId;
-	rev: number;
-	/**
-	 * The collection's chain tail block id (the {@link CommitRequest.tailId}). Optional on the per-block
-	 * repo operation: the transactor threads the committing collection's tail through every per-block
-	 * commit so the coordinator carries it into the consensus commit op, letting the committing node's
-	 * `StorageRepo.commit` stamp it onto the emitted `CollectionChangeEvent` (the reactivity topic anchor
-	 * `H(tailId ‖ "reactivity")`). Absent on bare per-block paths (e.g. churn replication), which never
-	 * originate reactivity.
-	 */
-	tailId?: BlockId;
-};
-
-export type IRepo = {
-	get(blockGets: BlockGets, options?: MessageOptions): Promise<GetBlockResults>;
-	pend(request: PendRequest, options?: MessageOptions): Promise<PendResult>;
-	cancel(actionRef: ActionBlocks, options?: MessageOptions): Promise<void>;
-	commit(request: RepoCommitRequest, options?: MessageOptions): Promise<CommitResult>;
-}
+import type { ActionBlocks, BlockContentDigests, CommitResult, GetBlockResults, PendResult, PendRequest, BlockGets, BlockId, ActionId } from "../index.js";
+
+export type MessageOptions = {
+	expiration?: number;
+	signal?: AbortSignal;
+	/**
+	 * Per-peer dial deadline in ms. Bounds only the dial portion of a call, so
+	 * an unreachable peer fails fast and the caller's retry loop can re-pick
+	 * a different coordinator. Independent of `expiration` (the overall budget):
+	 * a 30s transaction with `dialTimeoutMs: 3000` can afford ten 3s dial
+	 * attempts against different peers. Once a dial succeeds, the response wait
+	 * is bound by the remaining `expiration` budget. Undefined means "do not
+	 * impose a separate dial cap; the overall budget is the cap".
+	 */
+	dialTimeoutMs?: number;
+	/**
+	 * Blocks this coordinator is responsible for driving through consensus. Threaded
+	 * from {@link NetworkTransactor.pend}'s batch (which consolidates several blocks
+	 * onto one coordinating peer) into {@link CoordinatorRepo.pend}, which uses it to
+	 * pick the cluster anchor. Absent on bare per-block paths, which fall back to the
+	 * transforms' own block ids.
+	 */
+	coordinatingBlockIds?: BlockId[];
+}
+
+export type RepoCommitRequest = {
+	blockIds: BlockId[];
+	actionId: ActionId;
+	rev: number;
+	/**
+	 * The collection's chain tail block id (the {@link CommitRequest.tailId}). Optional on the per-block
+	 * repo operation: the transactor threads the committing collection's tail through every per-block
+	 * commit so the coordinator carries it into the consensus commit op, letting the committing node's
+	 * `StorageRepo.commit` stamp it onto the emitted `CollectionChangeEvent` (the reactivity topic anchor
+	 * `H(tailId ‖ "reactivity")`). Absent on bare per-block paths (e.g. churn replication), which never
+	 * originate reactivity.
+	 */
+	tailId?: BlockId;
+	/**
+	 * Per-block content declarations for this batch (see {@link BlockContentDigests}).
+	 * The transactor narrows its action-wide {@link CommitRequest.blockDigests} to this request's own
+	 * `blockIds` before sending, so a cohort only ever declares for the blocks it is driving —
+	 * `RepoClient.commit` wraps this whole request into the `RepoMessage`, and the coordinator places
+	 * the received request into the consensus message, so the digests land inside every cohort
+	 * signature's preimage. Absent when no block in this batch could be digested (each undeclared
+	 * block falls back to corroboration).
+	 */
+	// NOTE: accepted tradeoff — optional by necessity, and NOT free: an undeclared block retains no
+	// durable commit proof and so cannot gain holders by push. Full rationale and the measured cost of
+	// making it required live at {@link CommitRequest.blockDigests} in `struct.ts`; keep the two in sync.
+	blockDigests?: BlockContentDigests;
+};
+
+export type IRepo = {
+	get(blockGets: BlockGets, options?: MessageOptions): Promise<GetBlockResults>;
+	pend(request: PendRequest, options?: MessageOptions): Promise<PendResult>;
+	cancel(actionRef: ActionBlocks, options?: MessageOptions): Promise<void>;
+	commit(request: RepoCommitRequest, options?: MessageOptions): Promise<CommitResult>;
+}

package/src/network/stale-failure.ts

@@ -1,43 +1,67 @@
-import type { StaleFailure } from "./struct.js";
-
-/**
- * The single rule for "is this non-success retryable after a re-read?" Both write paths and the
- * transactor's aggregation call this — no consumer re-derives it.
- *
- * {@link StaleFailure.conflict} is authoritative when present. The `missing`/`pending` fallback
- * covers producers that have not been taught the field, including a remote peer on an older build
- * (the repo protocol is plain JSON, so an unset field simply arrives absent).
- */
-export function isConflictFailure(failure: StaleFailure): boolean {
-	return failure.conflict ?? Boolean(failure.missing?.length || failure.pending?.length);
-}
-
-/**
- * The single rule for picking one {@link StaleFailure.staleAt} out of several candidates.
- *
- * Highest `rev` wins: the losing writer's next request has to clear EVERY holder, so the largest
- * confirmed revision is the binding constraint and any smaller one understates it. Ties keep the
- * earlier candidate. Undefined entries (a block or batch with no confirmed number, or a peer that
- * predates the field) contribute nothing, and an all-undefined input yields undefined so callers
- * can omit the key rather than emit `staleAt: undefined`.
- *
- * Every site that has more than one candidate calls this — the producers scanning several blocks
- * (`StorageRepo.pend`/`.commit`, `CoordinatorRepo.classifyStaleRejection`) as well as
- * `NetworkTransactor` rebuilding one response from many per-batch ones. Uniformity is what makes
- * the transactor's aggregate meaningful: if a producer reported an arbitrary block instead of its
- * highest, taking the max across producers would still understate the constraint.
- *
- * NOTE: comparing revisions across blocks is only meaningful because one pend covers one
- * collection, so every candidate comes from the same revision counter. If a pend is ever allowed
- * to span collections, these numbers come from unrelated counters and selection must become
- * per-collection.
- */
-export function highestStaleAt(candidates: readonly StaleFailure['staleAt'][]): StaleFailure['staleAt'] {
-	let best: StaleFailure['staleAt'];
-	for (const candidate of candidates) {
-		if (candidate !== undefined && (best === undefined || candidate.rev > best.rev)) {
-			best = candidate;
-		}
-	}
-	return best;
-}
+import type { ActionId, ActionRev } from "../collection/action.js";
+import type { StaleFailure } from "./struct.js";
+
+/**
+ * The single rule for "is this non-success retryable after a re-read?" Both write paths and the
+ * transactor's aggregation call this — no consumer re-derives it.
+ *
+ * {@link StaleFailure.conflict} is authoritative when present. The `missing`/`pending` fallback
+ * covers producers that have not been taught the field, including a remote peer on an older build
+ * (the repo protocol is plain JSON, so an unset field simply arrives absent).
+ */
+export function isConflictFailure(failure: StaleFailure): boolean {
+	return failure.conflict ?? Boolean(failure.missing?.length || failure.pending?.length);
+}
+
+/**
+ * The single rule for picking one {@link StaleFailure.staleAt} out of several candidates.
+ *
+ * Highest `rev` wins: the losing writer's next request has to clear EVERY holder, so the largest
+ * confirmed revision is the binding constraint and any smaller one understates it. Ties keep the
+ * earlier candidate. Undefined entries (a block or batch with no confirmed number, or a peer that
+ * predates the field) contribute nothing, and an all-undefined input yields undefined so callers
+ * can omit the key rather than emit `staleAt: undefined`.
+ *
+ * Every site that has more than one candidate calls this — the producers scanning several blocks
+ * (`StorageRepo.pend`/`.commit`, `CoordinatorRepo.classifyStaleRejection`) as well as
+ * `NetworkTransactor` rebuilding one response from many per-batch ones. Uniformity is what makes
+ * the transactor's aggregate meaningful: if a producer reported an arbitrary block instead of its
+ * highest, taking the max across producers would still understate the constraint.
+ *
+ * NOTE: comparing revisions across blocks is only meaningful because one pend covers one
+ * collection, so every candidate comes from the same revision counter. If a pend is ever allowed
+ * to span collections, these numbers come from unrelated counters and selection must become
+ * per-collection.
+ */
+export function highestStaleAt(candidates: readonly StaleFailure['staleAt'][]): StaleFailure['staleAt'] {
+	let best: StaleFailure['staleAt'];
+	for (const candidate of candidates) {
+		if (candidate !== undefined && (best === undefined || candidate.rev > best.rev)) {
+			best = candidate;
+		}
+	}
+	return best;
+}
+
+/**
+ * The single rule for "is the action holding this revision OUR OWN?" — true only when `latest`
+ * names exactly the revision being requested AND the same action requesting it.
+ *
+ * A write touching several blocks is committed one group at a time, so it can end up with some
+ * blocks durable and the rest refused (a *torn action*). The retry reuses the same `actionId`, so
+ * every revision check meets the writer's own durable half and must treat it as a no-op rather
+ * than as a rival's win — otherwise the writer is refused by its own committed work, forever.
+ *
+ * Deliberately `===` only. At `latest.rev > rev` this returns false even for our own action: the
+ * follow-on commit is refused as stale anyway (`StorageRepo.commit`'s `missedCommits` branch), so
+ * approving would only defer the refusal by a round trip, and `latest` alone can no longer name
+ * who holds `rev` — that needs the revision index (see `IRevisionActionReader`).
+ *
+ * Every revision-vs-action check calls this: the pend tier (`StorageRepo.pend`,
+ * `ClusterMember.validatePendOperations`, `CoordinatorRepo.classifyStaleRejection`) and the commit
+ * tier (`StorageRepo.commit`'s `alreadyDone` partition, `ClusterMember.validateCommitRevisions`).
+ * Single-sourcing it is what makes "all the tiers agree" a fact rather than a comment.
+ */
+export function isOwnRevision(latest: ActionRev | undefined, rev: number | undefined, actionId: ActionId): boolean {
+	return latest !== undefined && rev !== undefined && latest.rev === rev && latest.actionId === actionId;
+}