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

package/src/transaction/errors.ts

@@ -5,6 +5,14 @@ import type { CollectionId } from "../collection/index.js";
  * fails AFTER at least one collection has already DURABLY committed through the
  * distributed consensus path (GATHER/PEND/COMMIT).
  *
+ * A collection counts as committed whether an attempt committed it or the refresh
+ * between attempts saved it (an attempt reported a loss, but the collection's log
+ * entry was stored, and the refresh finished the rest of its blocks). Once either has
+ * happened, EVERY way the commit can still fail is reported as this error, with the
+ * failure that ended it as {@link reason} — a torn sibling (`TornActionError`), a
+ * sibling that kept losing until the retry budget ran out
+ * ({@link CoordinatorStaleLossError}), an abort, an expiry, a hard error.
+ *
  * ## Why this exists (and why we can't just "roll back")
  *
  * The COMMIT phase commits each collection's pended blocks independently (see
@@ -44,11 +52,17 @@ import type { CollectionId } from "../collection/index.js";
  */
 export class CoordinatorPartialCommitError extends Error {
 	constructor(
-		/** Collections durably committed via consensus before the failure (NOT rolled back). */
+		/** Collections durably committed before the failure (NOT rolled back) — by an attempt, or
+		 * by the refresh between attempts finishing the collection's own log entry. */
 		public readonly committedCollections: readonly CollectionId[],
-		/** Collections that never committed this attempt (local state reverted for retry). */
+		/** Collections of this transaction that never committed (local state reverted for retry —
+		 * their staged actions are still in place). Can be empty when the failure came after every
+		 * collection was already saved. */
 		public readonly failedCollections: readonly CollectionId[],
-		/** The underlying commit-phase failure that aborted the commit. */
+		/** The failure that ended the commit: the attempt's commit-phase reason (a string) when an
+		 * attempt half-landed on a hard failure, otherwise the error that escaped after a collection
+		 * was committed or saved — a {@link CoordinatorStaleLossError} when the failed collection's
+		 * refusal never cleared within the retry budget (its own `reason` names the last refusal). */
 		public readonly reason?: unknown,
 	) {
 		super(
@@ -69,11 +83,20 @@ export class CoordinatorPartialCommitError extends Error {
  * in which NOTHING durably committed, so every participating collection's local tracker was
  * restored to its pre-append state and the transaction is safe to re-drive.
  *
+ * "Nothing durably committed" holds across the WHOLE commit, not only the last attempt. Inside
+ * the coordinator this is also the signal for a retryable ATTEMPT: one that half-landed on
+ * returned refusals (a lagging member, a rival that took a revision slot) throws it after
+ * recording its committed siblings as saved, and one whose refresh saved a participant carries on
+ * under the same budget. In both cases the coordinator reports the budget running out as a
+ * {@link CoordinatorPartialCommitError} carrying this error as its `reason`, so this error only
+ * ever escapes bare when a re-drive is genuinely safe.
+ *
  * This is the retryable counterpart to {@link CoordinatorPartialCommitError}: a partial landing
- * cannot be blindly retried (it would double-apply the durable half), but a clean loss can. The
- * coordinator's built-in backoff+jitter retry catches this internally and re-drives after re-reading
- * fresh revisions; it only escapes to the caller once the retry budget (`maxAttempts` / `deadlineMs`)
- * is exhausted, at which point it signals "gave up after a clean loss" rather than a partial split.
+ * cannot be blindly retried by a CALLER (it would double-apply the durable half), but a clean loss
+ * can, and the coordinator's own retry re-drives only what is still staged. Its built-in
+ * backoff+jitter retry catches this internally and re-drives after re-reading fresh revisions; it
+ * only escapes to the caller once the retry budget (`maxAttempts` / `deadlineMs`) is exhausted, at
+ * which point it signals "gave up after a clean loss" rather than a partial split.
  */
 export class CoordinatorStaleLossError extends Error {
 	constructor(
@@ -82,9 +105,11 @@ export class CoordinatorStaleLossError extends Error {
 		/** The underlying stale/conflict reason surfaced by the failed pend/commit phase. */
 		public readonly reason?: string,
 	) {
+		// Deliberately does not assert that nothing committed: this is also the internal signal a
+		// half-landed attempt retries on, and it then surfaces as a partial error's `reason`.
 		super(
-			`Multi-collection commit failed on a clean stale loss (no collection durably committed) ` +
-			`for [${failedCollections.join(', ')}]` + (reason ? ` — ${reason}` : '')
+			`Multi-collection commit lost a stale race for [${failedCollections.join(', ')}]` +
+			(reason ? ` — ${reason}` : '')
 		);
 		this.name = 'CoordinatorStaleLossError';
 	}

package/src/transaction/index.ts

@@ -34,6 +34,7 @@ export {
 
 export { ReadDependencyCollector } from './read-dependency-collector.js';
 export { TransactionCoordinator } from './coordinator.js';
+export type { CoordinatorOptions, PendValidationMode } from './coordinator.js';
 export { CoordinatorConcurrentStampError, CoordinatorPartialCommitError, CoordinatorStaleLossError } from './errors.js';
 export { TransactionSession } from './session.js';
 export { TransactionValidator } from './validator.js';

package/src/transactor/block-floors.ts

@@ -0,0 +1,105 @@
+import type { ActionContext, ActionId, BlockId } from "../index.js";
+
+/** The lowest revision a block may be served at, and the action that set it.
+ *
+ * A refresh walks the log entries that landed since the collection last looked. Each entry says
+ * "action `actionId`, committed at revision `rev`, changed these blocks", and every block an action
+ * changes is committed at that action's revision. So once an entry has been walked, a read of a
+ * block it names — made at a context at or above `rev` — must come back materialized at `rev` or
+ * later; anything lower is provably not the view that was asked for. The FLOOR of a block is that
+ * bound: the revision and action id of the newest walked entry naming it. */
+export type BlockFloor = {
+	readonly rev: number;
+	readonly actionId: ActionId;
+};
+
+/** A BELOW-FLOOR ANSWER: a block served at a revision under the floor that applied to the read. */
+export type BelowFloorAnswer = {
+	blockId: BlockId;
+	floor: BlockFloor;
+	/** The revision the served content actually is (`servedRevision` of the answer). */
+	servedRev: number;
+};
+
+/** What a read source needs from a collection's floors: which floor applies to a read, and whether
+ * an answer fell under it. The narrow face of {@link BlockFloors} that `TransactorSource` holds. */
+export interface BlockFloorCheck {
+	/** The floor a read of `blockId` at `context` must meet, or `undefined` when none applies.
+	 *
+	 * A floor applies only to a view that should CONTAIN the entry that set it: an unpinned read, or
+	 * one pinned at or above the floor's revision. A read pinned strictly below it legitimately asks
+	 * for an older view and is served — and remembered — exactly as if there were no floor. (The same
+	 * at-or-above test `answeredBlock` applies to `unconfirmedAheadRev`.) */
+	applicableTo(blockId: BlockId, context: ActionContext | undefined): BlockFloor | undefined;
+
+	/** Weighs a served block against the floor that applies to the read that fetched it.
+	 *
+	 * @param servedRev the revision the served content is — `servedRevision` of the answer.
+	 * @returns `true` for a below-floor answer, which the caller hands on but must not let any cache
+	 * remember (see `TransactorSource.describeServed`). */
+	answeredBelowFloor(blockId: BlockId, context: ActionContext | undefined, servedRev: number): boolean;
+}
+
+/** The floors of one collection handle, shared by EVERY read source that handle builds — its own
+ * and each pinned read view's — the way the `ReadDependencyCollector` is shared. Held on one
+ * source only, a view created right after a refresh would fetch the changed block through a source
+ * that knows no floor.
+ *
+ * Raised where log entries are consumed (`Collection.updateInternal`) and checked where answers
+ * arrive (`TransactorSource.tryGet`). A floor, once raised, STANDS for the life of the handle: an
+ * answer that meets it does not remove it.
+ *
+ * Why a met floor is not dropped. The source that judges an answer cannot know whether any cache
+ * went on to keep it, and "an answer met the floor" is not "the cache now holds that answer": the
+ * cache drops an answer that was overtaken while in flight (`CacheSource.stillWanted`), and evicts
+ * kept content under pressure (128 blocks). Either way the next read of the block goes back to
+ * storage, where nothing says the same machine answers twice — and with the floor gone, a too-old
+ * answer to THAT read is judged against nothing and kept for good, which is the defect floors exist
+ * to prevent. Reproduced with the floor dropped when met: a too-old answer, then a current one that
+ * the cache dropped as overtaken (but which removed the floor), then a too-old one — kept, and
+ * served after storage had caught up (`refresh-below-floor.spec.ts`, "a current answer the cache
+ * dropped..."). A standing floor costs one map lookup per fetched block and is always true of a
+ * correct answer: a block never goes back below a revision it was committed at.
+ *
+ * NOTE: the map is never pruned, so it holds one small entry per distinct block named by entries
+ * this handle walked — the same ids, and so the same bound, as `CacheSource`'s never-pruned
+ * `generations` map, which `clear(entry.blockIds)` populates beside every `raise`. If that ever
+ * grows large enough to matter, prune the two together (oldest floors first); a dropped floor only
+ * forfeits the check for that block, it never serves anything wrong by itself. */
+export class BlockFloors implements BlockFloorCheck {
+	private readonly floors = new Map<BlockId, BlockFloor>();
+
+	/** @param onBelowFloor told about every below-floor answer, from any source sharing these floors
+	 * — the collection reports them as `collection:block-below-floor`. */
+	constructor(private readonly onBelowFloor?: (answer: BelowFloorAnswer) => void) {}
+
+	/** Record that the walked entry `floor` describes changed `blockIds`. Highest revision wins, so
+	 * entries may be walked in any order and re-walked harmlessly. */
+	raise(blockIds: readonly BlockId[], floor: BlockFloor): void {
+		for (const blockId of blockIds) {
+			const held = this.floors.get(blockId);
+			if (held === undefined || floor.rev > held.rev) {
+				this.floors.set(blockId, floor);
+			}
+		}
+	}
+
+	applicableTo(blockId: BlockId, context: ActionContext | undefined): BlockFloor | undefined {
+		const floor = this.floors.get(blockId);
+		return floor !== undefined && (context === undefined || context.rev >= floor.rev) ? floor : undefined;
+	}
+
+	answeredBelowFloor(blockId: BlockId, context: ActionContext | undefined, servedRev: number): boolean {
+		const floor = this.applicableTo(blockId, context);
+		if (floor === undefined || servedRev >= floor.rev) {
+			return false;
+		}
+		this.onBelowFloor?.({ blockId, floor, servedRev });
+		return true;
+	}
+
+	/** How many blocks have a floor. */
+	get size(): number {
+		return this.floors.size;
+	}
+}

package/src/transactor/change-notifier.ts

@@ -1,80 +1,129 @@
-import type { BlockId, CollectionId } from '../index.js';
-import type { ActionId } from '../collection/action.js';
-
-/** A commit landed on this node mutating one collection's blocks. */
-export type CollectionChangeEvent = {
-	/** Header/collection id of the affected collection (block.header.collectionId). */
-	readonly collectionId: CollectionId;
-	/** Blocks within that collection mutated by this commit. */
-	readonly blockIds: readonly BlockId[];
-	readonly actionId: ActionId;
-	readonly rev: number;
-	/**
-	 * The collection's chain tail block id at the time of this commit (the `CommitRequest.tailId`).
-	 * Anchors the rotating reactivity topic `H(tailId ‖ "reactivity")`. Present on commit-driven
-	 * events; `undefined` on read-driven promotions (the `StorageRepo.get` path has no commit tail —
-	 * those never originate anyway, and are cert-gated out downstream).
-	 */
-	readonly tailId?: BlockId;
-	/**
-	 * `true` iff this change event is a durable **invalidation** — a compensating revision + appended
-	 * `InvalidationEntry` reversing a previously-committed action proven invalid by dispute
-	 * (`docs/right-is-right.md` §Durable Invalidation), rather than an ordinary commit. An invalidation
-	 * is a committed collection change like any other, so it flows through the same notification path;
-	 * this flag lets a subscriber distinguish it (drop derived results + resubmit) from a plain commit
-	 * (refresh). A hint only — correctness never depends on it: the subscriber always re-reads the
-	 * authoritative reverted state. Absent (falsy) on ordinary commits.
-	 */
-	readonly invalidation?: boolean;
-	/**
-	 * When {@link invalidation} is set, the `actionId` of the original committed action that was
-	 * reversed (the `InvalidationEntry.invalidatedActionId`). Lets an invalidation-aware client
-	 * dedup/coalesce multiple cascade notifications by the action they reverse, and resubmit exactly
-	 * the affected work. Absent on ordinary commits.
-	 */
-	readonly invalidatedActionId?: ActionId;
-};
-
-export type CollectionChangeListener = (event: CollectionChangeEvent) => void;
-
-/**
- * The cluster-consensus commit certificate for a committed action — the **authoritative** proof
- * that the cohort agreed the commit. It is the cross-package currency the local change-notifier
- * bridge forwards into the cohort-topic substrate (`CohortTopicService.onLocalCommit`) so reactivity
- * can originate notifications **without re-signing**: a notification's signature is bit-for-bit this
- * `thresholdSig`. The bridge and every downstream consumer treat the bytes as opaque and pass them
- * through unchanged — only the cluster layer that produced consensus ever mints one.
- *
- * Peer ids are carried as their string form (the cluster keys signatures by peer-id string); db-core
- * stays cross-platform and never references a libp2p `PeerId` type here.
- */
-export type CommitCert = {
-	/** Threshold signature bytes proving `signers` agreed the commit. Forwarded UNCHANGED; never re-signed. */
-	readonly thresholdSig: Uint8Array;
-	/** Peer-id strings whose signatures compose {@link thresholdSig} (a distinct set of size ≥ {@link minSigs}). */
-	readonly signers: readonly string[];
-	/** Threshold the signer set satisfies (the cluster super-majority / cohort `k − x`). */
-	readonly minSigs: number;
-	/**
-	 * The exact byte preimage each `signers[i]` signed to produce its 64-byte chunk of
-	 * {@link thresholdSig} — the cluster's per-member commit-vote payload `utf8(commitHash + ":approve")`,
-	 * identical across all approving signers. Reactivity sets a notification's `digest` to
-	 * base64url(signedPayload) so a subscriber's threshold-verify over `digest` reproduces the exact
-	 * signed image. Opaque to db-core; minted only by the cluster layer.
-	 */
-	readonly signedPayload: Uint8Array;
-};
-
-export interface IBlockChangeNotifier {
-	/**
-	 * Subscribe to commits that mutate the given collection. Returns an
-	 * idempotent unsubscribe. Listeners are invoked AFTER the commit's critical
-	 * section (locks released), synchronously in commit order; a throwing
-	 * listener must not break the commit or other listeners (log + continue).
-	 */
-	onCollectionChange(collectionId: CollectionId, listener: CollectionChangeListener): () => void;
-}
-
-export function isBlockChangeNotifier(x: unknown): x is IBlockChangeNotifier {
-	return !!x && typeof (x as IBlockChangeNotifier).onCollectionChange === 'function';
-}
+import type { BlockId, CollectionId } from '../index.js';
+import type { ActionId } from '../collection/action.js';
+
+/** A commit landed on this node mutating one collection's blocks. */
+export type CollectionChangeEvent = {
+	/** Header/collection id of the affected collection (block.header.collectionId). */
+	readonly collectionId: CollectionId;
+	/** Blocks within that collection mutated by this commit. */
+	readonly blockIds: readonly BlockId[];
+	readonly actionId: ActionId;
+	readonly rev: number;
+	/**
+	 * The collection's chain tail block id at the time of this commit (the `CommitRequest.tailId`).
+	 * Anchors the rotating reactivity topic `H(tailId ‖ "reactivity")`. Present on commit-driven
+	 * events; `undefined` on read-driven promotions (the `StorageRepo.get` path has no commit tail —
+	 * those never originate anyway, and are cert-gated out downstream).
+	 */
+	readonly tailId?: BlockId;
+	/**
+	 * `true` iff this change event is a durable **invalidation** — a compensating revision + appended
+	 * `InvalidationEntry` reversing a previously-committed action proven invalid by dispute
+	 * (`docs/right-is-right.md` §Durable Invalidation), rather than an ordinary commit. An invalidation
+	 * is a committed collection change like any other, so it flows through the same notification path;
+	 * this flag lets a subscriber distinguish it (drop derived results + resubmit) from a plain commit
+	 * (refresh). A hint only — correctness never depends on it: the subscriber always re-reads the
+	 * authoritative reverted state. Absent (falsy) on ordinary commits.
+	 */
+	readonly invalidation?: boolean;
+	/**
+	 * When {@link invalidation} is set, the `actionId` of the original committed action that was
+	 * reversed (the `InvalidationEntry.invalidatedActionId`). Lets an invalidation-aware client
+	 * dedup/coalesce multiple cascade notifications by the action they reverse, and resubmit exactly
+	 * the affected work. Absent on ordinary commits.
+	 */
+	readonly invalidatedActionId?: ActionId;
+};
+
+export type CollectionChangeListener = (event: CollectionChangeEvent) => void;
+
+/**
+ * The cluster-consensus commit certificate for a committed action — the **authoritative** proof
+ * that the cohort agreed the commit. It is the cross-package currency the local change-notifier
+ * bridge forwards into the cohort-topic substrate (`CohortTopicService.onLocalCommit`) so reactivity
+ * can originate notifications **without re-signing**: a notification's signature is bit-for-bit this
+ * `thresholdSig`. The bridge and every downstream consumer treat the bytes as opaque and pass them
+ * through unchanged — only the cluster layer that produced consensus ever mints one.
+ *
+ * Peer ids are carried as their string form (the cluster keys signatures by peer-id string); db-core
+ * stays cross-platform and never references a libp2p `PeerId` type here.
+ */
+export type CommitCert = {
+	/** Threshold signature bytes proving `signers` agreed the commit. Forwarded UNCHANGED; never re-signed. */
+	readonly thresholdSig: Uint8Array;
+	/** Peer-id strings whose signatures compose {@link thresholdSig} (a distinct set of size ≥ {@link minSigs}). */
+	readonly signers: readonly string[];
+	/** Threshold the signer set satisfies (the cluster super-majority / cohort `k − x`). */
+	readonly minSigs: number;
+	/**
+	 * The exact byte preimage each `signers[i]` signed to produce its 64-byte chunk of
+	 * {@link thresholdSig} — the cluster's per-member commit-vote payload `utf8(commitHash + ":approve")`,
+	 * identical across all approving signers. Reactivity sets a notification's `digest` to
+	 * base64url(signedPayload) so a subscriber's threshold-verify over `digest` reproduces the exact
+	 * signed image. Opaque to db-core; minted only by the cluster layer.
+	 */
+	readonly signedPayload: Uint8Array;
+};
+
+export interface IBlockChangeNotifier {
+	/**
+	 * Subscribe to commits that mutate the given collection. Returns an
+	 * idempotent unsubscribe. Listeners are invoked AFTER the commit's critical
+	 * section (locks released), synchronously in commit order; a throwing
+	 * listener must not break the commit or other listeners (log + continue).
+	 */
+	onCollectionChange(collectionId: CollectionId, listener: CollectionChangeListener): () => void;
+}
+
+export function isBlockChangeNotifier(x: unknown): x is IBlockChangeNotifier {
+	return !!x && typeof (x as IBlockChangeNotifier).onCollectionChange === 'function';
+}
+
+/**
+ * One or more blocks reached FULL replication: every member of their cohort is now confirmed to
+ * hold the revision. The complement of the durability class on the write's own result — a write
+ * acknowledged below `full` (`WriteDurability.quorum`) is pending until these events cover its
+ * blocks, at which point a host can move it from "pending" to "saved".
+ *
+ * **Keyed by block, deliberately, never by action.** The node's record of what is still owed (the
+ * under-replication ledger) keeps ONE entry per block, at the block's highest under-replicated
+ * revision: a block written again by a LATER action replaces the earlier entry, so the earlier
+ * action's shortfall is cleared by the later action's copies and reported under the later
+ * action's `actionId` — the earlier action never fires an event of its own. A host that keys its
+ * pending state by action alone therefore waits forever for a superseded write. Hold the block ids
+ * the write's result names (`PendSuccess.blockIds`) and clear each as an event covers it; `rev`
+ * and `actionId` say which write's copies did the covering.
+ */
+export type BlockDurabilityReachedEvent = {
+	/** Blocks that reached full replication in this round. Today's producer reports one block per
+	 *  event; the list shape lets a producer report several blocks of one action together. */
+	readonly blockIds: readonly BlockId[];
+	/** The revision every cohort member now holds — the block's highest under-replicated revision,
+	 *  which supersedes every lower one. */
+	readonly rev: number;
+	/** The action whose recorded shortfall cleared. See the note above on superseded writes. */
+	readonly actionId: ActionId;
+	/** Best-effort; absent when the collection could not be resolved from the block's header. */
+	readonly collectionId?: CollectionId;
+};
+
+export type BlockDurabilityListener = (event: BlockDurabilityReachedEvent) => void;
+
+/**
+ * The seam a host watches for "and now it is really saved": the SAME object that emits
+ * {@link CollectionChangeEvent}s for commits (`StorageRepo` implements both), so a host has one
+ * subscription point for change events, not two.
+ */
+export interface IBlockDurabilityNotifier {
+	/**
+	 * Subscribe to full-replication events. Returns an idempotent unsubscribe. Same listener
+	 * discipline as {@link IBlockChangeNotifier.onCollectionChange}: a throwing listener is logged
+	 * and the rest still run. An event fires only AFTER the node's own record of the shortfall is
+	 * gone, so a listener that re-reads that record sees a consistent picture.
+	 */
+	onBlockDurabilityReached(listener: BlockDurabilityListener): () => void;
+}
+
+export function isBlockDurabilityNotifier(x: unknown): x is IBlockDurabilityNotifier {
+	return !!x && typeof (x as IBlockDurabilityNotifier).onBlockDurabilityReached === 'function';
+}

package/src/transactor/index.ts

@@ -1,3 +1,4 @@
+export * from "./block-floors.js";
 export * from "./change-notifier.js";
 export * from "./network-transactor.js";
 export * from "./transactor-source.js";