@optimystic/db-core 0.21.0 → 0.24.0

package/src/network/i-peer-network.ts

@@ -5,4 +5,21 @@ export type IPeerNetwork = {
    * Dial a peer and establish a protocol stream
    */
   connect(peerId: PeerId, protocol: string, options?: AbortOptions): Promise<Stream>;
+
+  /**
+   * Optionally teach the dialer how to reach `peerId`, from addresses carried by an
+   * application-level message (a cluster record's peer map, a redirect payload).
+   *
+   * This exists because libp2p only propagates a peer's addresses to peers it is
+   * DIRECTLY connected to. A cohort here is chosen by key position, so a member
+   * routinely shares a cohort with a relay-only peer it has never met and holds an
+   * empty address list for it — a dial by peer id alone then fails immediately. Our
+   * own protocol messages already carry the addresses; this is the seam that lets a
+   * recipient keep them.
+   *
+   * Addresses are multiaddr strings (matching `ClusterPeers` / `RedirectPayload`), so
+   * db-core needs no multiaddr dependency. Implementations without an address book
+   * omit this method.
+   */
+  recordPeerAddresses?(peerId: PeerId, multiaddrs: string[]): void;
 }

package/src/network/stale-failure.ts

@@ -1,43 +1,43 @@
-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 { 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;
+}

package/src/network/struct.ts

@@ -154,8 +154,22 @@ export type BlockUnavailableReason =
 	/** Records for this block exist here but it cannot be reconstructed locally — a
 	 *  revision was received with no base to apply it to, or its history is truncated. */
 	| 'unmaterializable'
-	/** Nothing is held locally and the cohort could not be consulted to confirm it. */
-	| 'peers-unreachable';
+	/** Nothing is held locally; PART of the cohort answered and part could not be asked.
+	 *  A silent peer could be the sole holder, so the absence is a guess — but other
+	 *  coordinators are reachable, so asking one of them can still settle it. Also the
+	 *  fallback when the consult could not run at all (the cohort lookup itself failed):
+	 *  a routing failure says nothing about how many cohort members were reachable. */
+	| 'peers-unreachable'
+	/** Nothing is held locally and NO cohort member outside the answering node could be
+	 *  asked at all. Distinct from `peers-unreachable` in exactly the way that matters to
+	 *  a caller: there is no better-connected coordinator to re-ask, so the answer will
+	 *  not improve until that node's connectivity does. Its local view is all there is. */
+	| 'cohort-unreachable'
+	/** Nothing is held locally, but a cohort peer positively CLAIMED a revision of this
+	 *  block, and the answering node could neither corroborate that claim to a quorum nor
+	 *  acquire the content. The block is known to exist somewhere; reporting it absent
+	 *  would be a lie regardless of whether anyone was silent. */
+	| 'claimed-elsewhere';
 
 export type GetBlockResult = {
 	/** The retrieved block - undefined if the block was deleted	 */
@@ -179,6 +193,16 @@ export type GetBlockResult = {
 	 *  guess, not an authoritative absent. Every producer that omits it (including
 	 *  TestTransactor) keeps meaning "authoritative". */
 	unavailable?: BlockUnavailableReason;
+	/** Set when this repo served committed content it could NOT confirm is current: its
+	 *  freshness consult did not converge AND a cohort peer claimed a strictly higher
+	 *  revision than the one served, within the view the caller asked for (unpinned, or
+	 *  pinned at or above the claim). Carries that claimed revision. The claim did not
+	 *  drive a successful repair — it failed the read-repair corroboration quorum, or was
+	 *  corroborated but the content could not be acquired — so it is evidence of DOUBT,
+	 *  never a revision to adopt. Distinct from `unavailable`, which is about EXISTENCE:
+	 *  the content here is real, it may just be behind. Absent = confirmed, so every
+	 *  producer that omits it keeps its meaning. */
+	unconfirmedAheadRev?: number;
 };
 
 /**
@@ -194,6 +218,21 @@ export class BlockUnavailableError extends Error {
 	}
 }
 
+/**
+ * Thrown by an unpinned ("give me latest") block read whose surviving answer carries
+ * {@link GetBlockResult.unconfirmedAheadRev}: every reachable coordinator served content
+ * it could not confirm is current, while a cohort peer claimed a strictly higher revision
+ * nothing could corroborate or refute. Sibling of {@link BlockUnavailableError} — that one
+ * is about EXISTENCE (blockless answer, could not find out), this one about CURRENCY (real
+ * content, possibly behind). Not a StaleFailure: `Collection.sync` does not retry it.
+ */
+export class BlockPossiblyStaleError extends Error {
+	constructor(readonly blockId: BlockId, readonly claimedRev: number) {
+		super(`Block ${blockId} may be stale: a cohort peer claimed rev ${claimedRev} that no reachable coordinator could confirm or refute`);
+		this.name = 'BlockPossiblyStaleError';
+	}
+}
+
 export type GetBlockResults = Record<BlockId, GetBlockResult>;
 
 /**

package/src/network/types.ts

@@ -1,37 +1,37 @@
-/**
- * Portable type aliases for peer networking.
- *
- * These minimal structural types decouple db-core from any concrete
- * networking library (e.g. libp2p).  Concrete implementations in
- * transport packages (db-p2p) satisfy these structurally.
- */
-
-/** Minimal peer identifier — structurally compatible with libp2p's PeerId. */
-export type PeerId = {
-	toString(): string;
-	equals(other: unknown): boolean;
-};
-
-/** Opaque network stream — db-core never accesses stream internals. */
-export type Stream = {
-	close(): Promise<void>;
-};
-
-/** Options for abortable operations. */
-export type AbortOptions = {
-	signal?: AbortSignal;
-};
-
-/** Create a lightweight PeerId from its string representation. */
-export function peerIdFromString(id: string): PeerId {
-	return {
-		toString: () => id,
-		equals: (other: unknown) =>
-			other != null
-			&& typeof other === 'object'
-			&& 'toString' in other
-			&& typeof (other as PeerId).toString === 'function'
-			&& (other as PeerId).toString() === id,
-	};
-}
-
+/**
+ * Portable type aliases for peer networking.
+ *
+ * These minimal structural types decouple db-core from any concrete
+ * networking library (e.g. libp2p).  Concrete implementations in
+ * transport packages (db-p2p) satisfy these structurally.
+ */
+
+/** Minimal peer identifier — structurally compatible with libp2p's PeerId. */
+export type PeerId = {
+	toString(): string;
+	equals(other: unknown): boolean;
+};
+
+/** Opaque network stream — db-core never accesses stream internals. */
+export type Stream = {
+	close(): Promise<void>;
+};
+
+/** Options for abortable operations. */
+export type AbortOptions = {
+	signal?: AbortSignal;
+};
+
+/** Create a lightweight PeerId from its string representation. */
+export function peerIdFromString(id: string): PeerId {
+	return {
+		toString: () => id,
+		equals: (other: unknown) =>
+			other != null
+			&& typeof other === 'object'
+			&& 'toString' in other
+			&& typeof (other as PeerId).toString === 'function'
+			&& (other as PeerId).toString() === id,
+	};
+}
+