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

package/src/collections/tree/tree.ts

@@ -1,8 +1,88 @@
 import { Collection, type CollectionInitOptions, type CollectionId, type CollectionSnapshot, type ReadViewOptions } from "../../collection/index.js";
-import type { ITransactor, BlockId, BlockStore, IBlock, ActionId } from "../../index.js";
+import type { ITransactor, BlockId, BlockStore, IBlock, ActionId, WriteDurability } from "../../index.js";
 import { BTree, type Path, type KeyRange } from "../../btree/index.js";
 import { CollectionTrunk } from "./collection-trunk.js";
-import { TreeHeaderBlockType, TreeKeyTakenError, TreeRangeTakenError, type TreeReplaceAction } from "./struct.js";
+import { structuralEquals } from "../../utility/structural-equals.js";
+import {
+	TreeHeaderBlockType, TreeDeleteGuardKindError, TreeEntryChangedError, TreeKeyTakenError,
+	TreeRangeTakenError, type TreeEntryGuard, type TreeReplaceAction,
+} from "./struct.js";
+
+/**
+ * Enforce a guard carried by an UPSERT element against the CURRENT content of `actionTree` —
+ * the same Atomic store the upsert writes to, so it sees what earlier elements of this same
+ * replay already staged or deleted (an UPDATE's delete-old half runs before its guarded insert
+ * half). Throws the guard's refusal, which discards the whole action's staged writes.
+ *
+ * @returns `'skip'` when the element must be left unwritten (`keepExisting` found the key
+ * 	occupied — the INSERT OR IGNORE disposition), `'proceed'` otherwise.
+ */
+async function enforceUpsertGuard<TKey, TEntry>(
+	actionTree: BTree<TKey, TEntry>,
+	id: CollectionId,
+	key: TKey,
+	guard: TreeEntryGuard<TKey, TEntry>,
+	keyFromEntry: (entry: TEntry) => TKey,
+	compare: (a: TKey, b: TKey) => number,
+): Promise<'proceed' | 'skip'> {
+	switch (guard.kind) {
+		case 'absentRange': {
+			// Secondary-UNIQUE: the claimed range (a unique index's framed value prefix) must hold
+			// no entry other than this action's own key. Two short descents (range start and end)
+			// plus an early-exit walk. The guard is plain data (it is serialized into the log with
+			// its action), and BTree.range reads the range's fields only — so a KeyRange that has
+			// round-tripped through JSON is scanned exactly like a live instance.
+			for await (const path of actionTree.range(guard.range)) {
+				const occupant = actionTree.at(path);
+				if (occupant === undefined) continue;
+				const occupantKey = keyFromEntry(occupant);
+				if (compare(occupantKey, key) === 0) continue;	// self-exclusion
+				throw new TreeRangeTakenError(id, key, guard.range, occupantKey);
+			}
+			return 'proceed';
+		}
+		case 'unchanged': {
+			assertEntryUnchanged(id, key, guard.expected, actionTree.at(await actionTree.find(key)));
+			return 'proceed';
+		}
+		case 'absent':
+		case 'keepExisting': {
+			if (!(await actionTree.find(key)).on) return 'proceed';
+			if (guard.kind === 'absent') throw new TreeKeyTakenError(id, key);
+			// keepExisting: leave the present (rival's) entry in place and skip this element.
+			return 'skip';
+		}
+	}
+}
+
+/** The lost-update check shared by guarded upserts and guarded deletes: the committed entry must
+ *  be present AND structurally equal to what the staged write read. Absence counts as changed —
+ *  see {@link TreeUnchangedGuard} for why that is the contract on both dispositions. */
+function assertEntryUnchanged<TKey, TEntry>(
+	id: CollectionId,
+	key: TKey,
+	expected: TEntry,
+	actual: TEntry | undefined,
+): void {
+	if (actual === undefined || !structuralEquals(actual, expected)) {
+		throw new TreeEntryChangedError(id, key, expected, actual);
+	}
+}
+
+/** Narrow a DELETE element's guard to the only kind a delete can act on. The element type already
+ *  says this ({@link TreeDeleteElement}), but a replayed log entry is deserialized data that no
+ *  type policed, so the handler re-checks it and throws {@link TreeDeleteGuardKindError} rather
+ *  than silently ignoring a guard the writer believed was being enforced. */
+function deleteGuardExpected<TKey, TEntry>(
+	id: CollectionId,
+	key: TKey,
+	guard: TreeEntryGuard<TKey, TEntry>,
+): TEntry {
+	if (guard.kind !== 'unchanged') {
+		throw new TreeDeleteGuardKindError(id, key, guard.kind);
+	}
+	return guard.expected;
+}
 
 /**
  * Read-only surface of a tree: every navigation/lookup method a reader needs, with
@@ -106,44 +186,42 @@ export class Tree<TKey, TEntry> implements TreeReadView<TKey, TEntry> {
 						nodeCapacity,	// keep the write btree's fan-out in lock-step with the read btree
 					);
 					for (const [key, entry, guard] of actions) {
+						// NOTE: an element is a DELETE when its entry slot is falsy, not when it is
+						// strictly `undefined`. That is deliberate and load-bearing: JSON encodes the
+						// empty slot of `[key, undefined]` as `null`, so a replayed log entry arrives
+						// as `[key, null]` and a `!== undefined` test would upsert `null` over the row.
+						// JSON really is the live encoding, not just a hypothetical: the p2p repo
+						// protocol stringifies and parses every message (`protocol-client.ts` and
+						// `repo/service.ts` in `packages/db-p2p/src/`). The in-process test transactors
+						// use `structuredClone`, which preserves `undefined` — so no test that goes
+						// only through them can reach this shape; the round-trip spec below stages the
+						// JSON shape explicitly for that reason.
+						// The cost is that a falsy-but-real entry (`''`, `0`, `false`) reads as a
+						// delete. No entry type in this repo is falsy today (rows encode to a non-empty
+						// string or Uint8Array; index entries are arrays); if one ever is, this needs an
+						// explicit delete marker in the tuple rather than a tighter comparison.
 						if (entry) {
 							// Enforce the entry's guard (if any) on EVERY handler run — initial staging
-							// and every conflict replay — so the uniqueness decision is re-made against
-							// the newest adopted committed state, not just the stage-time snapshot.
-							// A throw here discards the whole action's staged writes (Atomic wrapper).
-							if (guard !== undefined) {
-								if (guard.kind === 'absentRange') {
-									// Secondary-UNIQUE: the claimed range (a unique index's framed
-									// value prefix) must hold no entry other than this action's own
-									// key. Two short descents (range start and end) plus an early-exit
-									// walk, over the SAME store the upsert below writes to, so it sees entries earlier
-									// actions of this replay already staged or deleted (an UPDATE's
-									// delete-old half runs before its guarded insert half). The guard
-									// is plain data (it is serialized into the log with its action), and
-									// BTree.range reads the range's fields only — so a KeyRange that has
-									// round-tripped through JSON is scanned exactly like a live instance.
-									for await (const path of actionTree.range(guard.range)) {
-										const occupant = actionTree.at(path);
-										if (occupant === undefined) continue;
-										const occupantKey = keyFromEntry(occupant);
-										if (compare(occupantKey, key) === 0) continue;	// self-exclusion
-										throw new TreeRangeTakenError(id, key, guard.range, occupantKey);
-									}
-								} else {
-									const found = await actionTree.find(key);
-									if (found.on) {
-										if (guard.kind === 'absent') {
-											throw new TreeKeyTakenError(id, key);
-										}
-										// keepExisting: leave the present (rival's) entry in place and
-										// skip this entry silently — the INSERT OR IGNORE disposition.
-										continue;
-									}
-								}
+							// and every conflict replay — so the decision is re-made against the newest
+							// adopted committed state, not just the stage-time snapshot. A throw here
+							// discards the whole action's staged writes (Atomic wrapper).
+							// Truthiness, not `!== undefined`, for the same round-trip reason as the entry
+							// slot above: an explicitly-passed `undefined` guard (the shape every unguarded
+							// index write stages) comes back from JSON as `null`, and reading `.kind` off it
+							// would throw a TypeError mid-replay instead of meaning "no guard".
+							if (guard
+								&& await enforceUpsertGuard(actionTree, id, key, guard, keyFromEntry, compare) === 'skip') {
+								continue;
 							}
 							await actionTree.upsert(entry);
 						} else {
-							await actionTree.deleteAt((await actionTree.find(key)));
+							// The path is found once and reused: the guard check reads it and `deleteAt`
+							// consumes it, with no mutation in between to invalidate it.
+							const path = await actionTree.find(key);
+							if (guard) {
+								assertEntryUnchanged(id, key, deleteGuardExpected(id, key, guard), actionTree.at(path));
+							}
+							await actionTree.deleteAt(path);
 						}
 					}
 					// Mutations landed in `trx`, not the read btree, so its version counter never moved.
@@ -184,9 +262,18 @@ export class Tree<TKey, TEntry> implements TreeReadView<TKey, TEntry> {
 		return new Tree<TKey, TEntry>(collection, held.btree, keyFromEntry, compare);
 	}
 
-	async replace(data: TreeReplaceAction<TKey, TEntry>): Promise<void> {
-			await this.collection.act({ type: "replace", data });
-			await this.collection.updateAndSync();
+	/** Stage a mutation and flush it. Forwards the collection's answer verbatim — see
+	 * {@link Collection.sync} for what `undefined` means and why a torn commit's `torn` list must
+	 * survive the trip. This layer never interprets the value.
+	 *
+	 * A call that throws leaves nothing staged (see {@link Collection.actAndSync}), so the mutation
+	 * cannot ride along with a later `replace`. Whether it reached STORAGE is what the error says:
+	 * a `TornActionError` with `final: true` means it did not and submitting it again stores it
+	 * once; `final: false` means that could not be established. A `SyncRetryExhaustedError` is not
+	 * a promise either way — the write path's last budgeted attempt, and a deadline, are not
+	 * followed by the refresh that would have settled it (see `Collection.syncAttempts`). */
+	async replace(data: TreeReplaceAction<TKey, TEntry>): Promise<WriteDurability | undefined> {
+			return await this.collection.actAndSync([{ type: "replace", data }]);
 	}
 
 	/** Stage a mutation into the collection's tracker WITHOUT flushing it to the
@@ -201,8 +288,8 @@ export class Tree<TKey, TEntry> implements TreeReadView<TKey, TEntry> {
 
 	/** Flush all staged (and any other pending) changes to the transactor.
 	 * Equivalent to the flush half of {@link replace}. */
-	async sync(): Promise<void> {
-			await this.collection.updateAndSync();
+	async sync(): Promise<WriteDurability | undefined> {
+			return await this.collection.updateAndSync();
 	}
 
 	/** Whether {@link sync} has anything to push — see

package/src/index.ts

@@ -18,8 +18,8 @@ export * from "./utility/groupby.js";
 export * from "./utility/hash-string.js";
 export * from "./utility/latches.js";
 export * from "./utility/nameof.js";
+export * from "./utility/structural-equals.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/matchmaking/wire.ts

@@ -184,7 +184,10 @@ export interface AggregateBucketV1 {
 // --- matchmaking-local wire state (generic validation primitives live in cohort-topic/wire/primitives.js) ---
 
 const utf8Encoder = new TextEncoder();
-const utf8Decoder = new TextDecoder("utf-8", { fatal: true });
+// Built on first use, not at module load: Hermes (React Native) has no native `TextDecoder`, so a
+// module-scope construction fails the import itself whenever it runs ahead of the host's polyfill.
+let utf8DecoderInstance: TextDecoder | undefined;
+const utf8Decoder = (): TextDecoder => utf8DecoderInstance ??= new TextDecoder("utf-8", { fatal: true });
 
 /** Ceiling for an opaque app payload (provider/seeker), guarding decode allocation. */
 export const DEFAULT_MAX_APP_PAYLOAD_BYTES = 64 * 1024;
@@ -295,9 +298,12 @@ function parseJsonBytes(bytes: Uint8Array, maxBytes: number, what: string): unkn
 	if (bytes.length > maxBytes) {
 		fail(`${what}: payload ${bytes.length} exceeds max ${maxBytes} bytes`);
 	}
+	// Fetched outside the try, so a missing `TextDecoder` polyfill surfaces as itself rather than as
+	// "not valid UTF-8".
+	const decoder = utf8Decoder();
 	let text: string;
 	try {
-		text = utf8Decoder.decode(bytes);
+		text = decoder.decode(bytes);
 	} catch {
 		fail(`${what}: payload is not valid UTF-8`);
 	}

package/src/network/durability.ts

@@ -0,0 +1,123 @@
+import type { BlockId } from "../index.js";
+import type { DurabilityQuorum, WriteDurability } from "./struct.js";
+
+/**
+ * The ONLY "this write is completely saved" test. `quorum === 'full'` alone is not enough: a torn
+ * action can have a fully-held tail and blocks that were abandoned and cancelled (`torn`), and a
+ * consumer that compared the class by hand would show such a write as saved. Every place that wants
+ * to present a change as saved calls this rather than reading the fields.
+ */
+export function isFullyDurable(d: WriteDurability): boolean {
+	return d.quorum === 'full' && (d.torn === undefined || d.torn.length === 0);
+}
+
+/** Total order on quorum classes: unrouted < local < majority < full. */
+export function durabilityRank(q: DurabilityQuorum): number {
+	switch (q) {
+		case 'unrouted': return 0;
+		case 'local': return 1;
+		case 'majority': return 2;
+		case 'full': return 3;
+	}
+}
+
+/**
+ * Merge per-cohort reports into one action-level report: the weakest becomes the scalar answer and
+ * the rest become `otherCohorts`, so a consumer that reads only the scalar fields is reading the
+ * binding constraint. `torn` is the union across the inputs — an abandoned block is abandoned
+ * whichever cohort it ran on. Reports that already carry `otherCohorts` are flattened first, so
+ * merging a merge is the same as merging its inputs. Identical reports collapse to one: a commit
+ * sends the tail and the sweep as separate batches, so ONE cohort routinely answers twice for one
+ * action, and without this a healthy single-cohort commit would list its own cohort under
+ * `otherCohorts`.
+ * NOTE: only structurally identical reports collapse. One cohort answering differently for two
+ * batches (a member confirmed one block and not the other) appears twice, once per answer, which
+ * is the truthful shape. If a consumer ever needs exactly one entry per cohort, fold same-cohort
+ * reports here by unioning `unconfirmed`; do not dedupe by `cohortPeerIds` alone.
+ *
+ * THROWS on an empty input: an action always ran on at least one cohort, and fabricating an answer
+ * for one that ran on none is exactly the plain-success ambiguity the durability field removes.
+ */
+export function mergeDurability(reports: readonly WriteDurability[]): WriteDurability {
+	const flat = distinctReports(reports.flatMap(flattenDurability));
+	if (flat.length === 0) {
+		throw new Error('mergeDurability: no durability reports to merge — an action always ran on at least one cohort');
+	}
+	const ranked = [...flat].sort((a, b) => durabilityRank(a.quorum) - durabilityRank(b.quorum));
+	const weakest = ranked[0]!;
+	const others = ranked.slice(1);
+	// Over the ORIGINAL reports: flattening strips `torn` (it is action-level), so the union must
+	// be taken before that or a torn input merges to an untorn answer.
+	const torn = unionTorn(reports);
+	return {
+		...stripMergedFields(weakest),
+		...(others.length === 0 ? {} : { otherCohorts: others.map(stripMergedFields) }),
+		...(torn.length === 0 ? {} : { torn })
+	};
+}
+
+/**
+ * Clamp an action-level report below `full` when the action abandoned blocks. A cohort can hold
+ * every block it was asked to commit and the action still be incomplete — the blocks the sweep
+ * never reached are on nobody. Never raises the class; a report already below `full` keeps it.
+ * Idempotent, and a no-op for an empty `torn`.
+ */
+export function withTornBlocks(d: WriteDurability, torn: readonly BlockId[]): WriteDurability {
+	if (torn.length === 0) return d;
+	const allTorn = Array.from(new Set([...(d.torn ?? []), ...torn]));
+	return {
+		...d,
+		quorum: d.quorum === 'full' ? 'majority' : d.quorum,
+		torn: allTorn
+	};
+}
+
+/** The single-node answer: this node holds it and knows nothing about a cohort beyond itself. */
+export function localDurability(selfPeerId?: string): WriteDurability {
+	return {
+		quorum: 'local',
+		confirmed: 1,
+		cohort: 1,
+		...(selfPeerId === undefined ? {} : { unconfirmed: [], cohortPeerIds: [selfPeerId] })
+	};
+}
+
+/**
+ * The no-cohort answer: this node holds it and could not establish where it belongs. Takes no
+ * reason on purpose: the producing site logs WHY the cohort did not resolve (`CohortResolution.reason`),
+ * and the result says only `unrouted`, so no consumer is tempted to branch on prose.
+ */
+export function unroutedDurability(): WriteDurability {
+	return { quorum: 'unrouted', confirmed: 1, cohort: 0 };
+}
+
+/** A merged report's own scalar view plus every `otherCohorts` entry, each as a standalone report. */
+function flattenDurability(d: WriteDurability): WriteDurability[] {
+	return [stripMergedFields(d), ...(d.otherCohorts ?? [])];
+}
+
+/** The per-cohort fields only — `otherCohorts` and `torn` are action-level and re-derived by the merge. */
+function stripMergedFields(d: WriteDurability): WriteDurability {
+	const { otherCohorts: _otherCohorts, torn: _torn, ...cohortReport } = d;
+	return cohortReport;
+}
+
+/**
+ * First occurrence of each structurally identical per-cohort report, input order kept. Peer lists
+ * compare as SETS: `findCluster` orders a cohort by routing distance to the block's key, so one
+ * cohort answering for two blocks lists the same members in two orders.
+ */
+function distinctReports(reports: readonly WriteDurability[]): WriteDurability[] {
+	const seen = new Set<string>();
+	const sorted = (ids: readonly string[] | undefined): string[] | null => ids === undefined ? null : [...ids].sort();
+	return reports.filter(r => {
+		const key = JSON.stringify([r.quorum, r.confirmed, r.cohort, sorted(r.unconfirmed), sorted(r.cohortPeerIds)]);
+		if (seen.has(key)) return false;
+		seen.add(key);
+		return true;
+	});
+}
+
+function unionTorn(reports: readonly WriteDurability[]): BlockId[] {
+	return Array.from(new Set(reports.flatMap(r => r.torn ?? [])));
+}

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

@@ -1,52 +1,60 @@
-import type { PeerId } from "./types.js";
-import type { ClusterPeers } from "../cluster/structs.js";
-
-/**
- * What a caller intends to do with the coordinator it is asking for.
- *
- * The distinction matters only when a node is isolated and the only candidate left is
- * itself. A read served from this node's own replica is at worst STALE — and the layers
- * below already say so (a self-only cohort answers conclusively; an unreachable cohort
- * comes back flagged unavailable). A write coordinated alone can instead diverge from the
- * rest of the network, so it is held to the stricter bar.
- */
-export type CoordinatorIntent = 'read' | 'write';
-
-export type FindCoordinatorOptions = {
-	/** Peers that have already been tried (and failed) */
-	excludedPeers?: PeerId[];
-	/**
-	 * What the caller intends to do with the coordinator. A read may fall back to this
-	 * node's own replica when the network is unreachable; a write may not do so on the
-	 * strength of the same evidence. Defaults to `'write'` (the conservative behavior)
-	 * when unset, so callers that don't set it are unchanged.
-	 */
-	intent?: CoordinatorIntent;
-};
-
-
-export type IKeyNetwork = {
-	/**
-	 * Find a coordinator node responsible for a given key and establish connection
-	 * @param key The key to find coordinator for
-	 * @returns Promise resolving to ID of coordinator node
-	 */
-	findCoordinator(key: Uint8Array, options?: Partial<FindCoordinatorOptions>): Promise<PeerId>;
-
-	/**
-	 * Find the peers in the cluster responsible for a given key
-	 * @param key The key to find peers for
-	 * @returns Promise resolving to the peers in the cluster
-	 */
-	findCluster(key: Uint8Array): Promise<ClusterPeers>;
-
-	/**
-	 * Optionally cache a resolved coordinator for a key, so a follow-up operation
-	 * (e.g. commit after pend) reuses the same peer. Implementations that don't
-	 * cache coordinators simply omit this. `ttlMs` bounds how long the hint lives.
-	 * @param key The key the coordinator was resolved for
-	 * @param peerId The coordinating peer
-	 * @param ttlMs Optional time-to-live for the cached hint, in ms
-	 */
-	recordCoordinator?(key: Uint8Array, peerId: PeerId, ttlMs?: number): void;
-}
+import type { PeerId } from "./types.js";
+import type { ClusterPeers } from "../cluster/structs.js";
+import type { RoutingKey } from "./routing-key.js";
+
+/**
+ * What a caller intends to do with the coordinator it is asking for.
+ *
+ * The distinction matters only when a node is isolated and the only candidate left is
+ * itself. A read served from this node's own replica is at worst STALE — and the layers
+ * below already say so (a self-only cohort answers conclusively; an unreachable cohort
+ * comes back flagged unavailable). A write coordinated alone can instead diverge from the
+ * rest of the network, so it is held to the stricter bar.
+ */
+export type CoordinatorIntent = 'read' | 'write';
+
+export type FindCoordinatorOptions = {
+	/** Peers that have already been tried (and failed) */
+	excludedPeers?: PeerId[];
+	/**
+	 * What the caller intends to do with the coordinator. A read may fall back to this
+	 * node's own replica when the network is unreachable; a write may not do so on the
+	 * strength of the same evidence. Defaults to `'write'` (the conservative behavior)
+	 * when unset, so callers that don't set it are unchanged.
+	 */
+	intent?: CoordinatorIntent;
+};
+
+
+/**
+ * Maps a block to the peers responsible for it.
+ *
+ * Every key is a {@link RoutingKey} minted by `routingKeyForBlock`. Implementations hash it into a ring
+ * coordinate themselves, so a caller must never pre-hash: the writer and the servers agree on a
+ * block's cohort only because both hand over the same bytes and exactly one hash is applied to them.
+ */
+export type IKeyNetwork = {
+	/**
+	 * Find a coordinator node responsible for a given key and establish connection
+	 * @param key The block's routing key
+	 * @returns Promise resolving to ID of coordinator node
+	 */
+	findCoordinator(key: RoutingKey, options?: Partial<FindCoordinatorOptions>): Promise<PeerId>;
+
+	/**
+	 * Find the peers in the cluster responsible for a given key
+	 * @param key The block's routing key
+	 * @returns Promise resolving to the peers in the cluster
+	 */
+	findCluster(key: RoutingKey): Promise<ClusterPeers>;
+
+	/**
+	 * Optionally cache a resolved coordinator for a key, so a follow-up operation
+	 * (e.g. commit after pend) reuses the same peer. Implementations that don't
+	 * cache coordinators simply omit this. `ttlMs` bounds how long the hint lives.
+	 * @param key The routing key the coordinator was resolved for — the same key a later `findCoordinator` looks it up by
+	 * @param peerId The coordinating peer
+	 * @param ttlMs Optional time-to-live for the cached hint, in ms
+	 */
+	recordCoordinator?(key: RoutingKey, peerId: PeerId, ttlMs?: number): void;
+}

package/src/network/index.ts

@@ -1,7 +1,10 @@
-export * from "./i-key-network.js";
-export * from "./i-peer-network.js";
-export * from "./i-repo.js";
-export * from "./repo-protocol.js";
-export * from "./stale-failure.js";
-export * from "./struct.js";
-export * from "./types.js";
+export * from "./i-key-network.js";
+export * from "./i-peer-network.js";
+export * from "./durability.js";
+export * from "./i-repo.js";
+export * from "./lineage.js";
+export * from "./repo-protocol.js";
+export * from "./routing-key.js";
+export * from "./stale-failure.js";
+export * from "./struct.js";
+export * from "./types.js";

package/src/network/lineage.ts

@@ -0,0 +1,80 @@
+import type { ActionRev } from "../collection/action.js";
+import type { BlockLineage, WriteDurability } from "./struct.js";
+
+/** One cohort member's answer to {@link BlockGets.lineageOf} for one block. A member that could not
+ *  be asked, or predates the question, is listed with `unknown` — it still counts as a member. */
+export type MemberLineage = {
+	peerId: string;
+	lineage: BlockLineage;
+	/** The newest revision the member holds for the block, as it reported it. */
+	latest?: ActionRev;
+};
+
+/** A block's cohort-level lineage answer, with who holds the write when the answer is `contains`. */
+export type CohortLineage = {
+	lineage: BlockLineage;
+	durability?: WriteDurability;
+};
+
+/**
+ * The single rule for turning a cohort's per-member lineage answers into one answer for the block.
+ *
+ * A member can only vouch for history it derived itself, so a member that took a later revision as
+ * a replica answers `unknown` even when that replica was built from the write. Such a member is
+ * counted WITH a member that did answer when the two hold the same latest revision under the same
+ * action: a revision's content is what the cohort agreed on at commit, so two members holding the
+ * same one hold the same lineage.
+ *
+ * - `contains` — a strict majority of the cohort holds content built from the write, the same bar
+ *   a commit must meet to be acknowledged. Fewer than that is `unknown`, not a smaller `contains`:
+ *   the write may yet spread from the members that hold it, or be overwritten by the ones that do
+ *   not, and the writer must not be told either.
+ * - `excludes` — at least one member proves it, and EVERY member is accounted for as excluding it
+ *   or not having reached it. One unaccounted member could be where the write survives.
+ * - `behind` — every member answered that it has not reached the revision.
+ * - `unknown` — anything else, including members that contradict each other (one proves the write
+ *   is in its content, another that it is not): the block's content has forked, which is a fault
+ *   this answer must not paper over in either direction.
+ *
+ * An empty cohort is `unknown`.
+ */
+export function judgeCohortLineage(members: readonly MemberLineage[]): CohortLineage {
+	const provers = members.filter(m => m.lineage === 'contains');
+	const refuters = members.filter(m => m.lineage === 'excludes');
+	if (members.length === 0 || (provers.length > 0 && refuters.length > 0)) {
+		return { lineage: 'unknown' };
+	}
+	if (provers.length > 0) {
+		const holders = withSameLatest(members, provers);
+		if (holders.length * 2 <= members.length) {
+			return { lineage: 'unknown' };
+		}
+		const held = new Set(holders.map(m => m.peerId));
+		const unconfirmed = members.filter(m => !held.has(m.peerId)).map(m => m.peerId);
+		return {
+			lineage: 'contains',
+			durability: {
+				quorum: unconfirmed.length === 0 ? 'full' : 'majority',
+				confirmed: holders.length,
+				cohort: members.length,
+				unconfirmed,
+				cohortPeerIds: members.map(m => m.peerId)
+			}
+		};
+	}
+	if (refuters.length > 0) {
+		const excluding = new Set(withSameLatest(members, refuters).map(m => m.peerId));
+		return members.every(m => excluding.has(m.peerId) || m.lineage === 'behind')
+			? { lineage: 'excludes' }
+			: { lineage: 'unknown' };
+	}
+	return { lineage: members.every(m => m.lineage === 'behind') ? 'behind' : 'unknown' };
+}
+
+/** `decided`, plus every `unknown` member holding the same latest revision as one of them. */
+function withSameLatest(members: readonly MemberLineage[], decided: readonly MemberLineage[]): MemberLineage[] {
+	const sameRevision = (a: ActionRev | undefined, b: ActionRev | undefined): boolean =>
+		a !== undefined && b !== undefined && a.rev === b.rev && a.actionId === b.actionId;
+	return members.filter(m => decided.includes(m)
+		|| (m.lineage === 'unknown' && decided.some(d => sameRevision(d.latest, m.latest))));
+}

package/src/network/routing-key.ts

@@ -0,0 +1,27 @@
+import type { BlockId } from "../blocks/structs.js";
+
+declare const routingKeyBrand: unique symbol;
+
+/**
+ * The bytes a block is routed on — what `IKeyNetwork.findCluster` and `IKeyNetwork.findCoordinator`
+ * are handed for that block.
+ *
+ * Branded so the only way to obtain one is {@link routingKeyForBlock}. Every party that asks "who is
+ * responsible for this block" (the writer's `NetworkTransactor`, a coordinator's responsibility check,
+ * a cohort member re-deriving its cluster, `RepoService`'s redirect check) must land on the same ring
+ * position, and they only do if they hand the key network the same bytes. When the writer pre-hashed
+ * the id and the servers did not, every network wider than one cohort sent writers to the wrong
+ * machines — and no fixture was wide enough to notice, because a cohort holding every peer is the same
+ * set from any coordinate.
+ */
+export type RoutingKey = Uint8Array & { readonly [routingKeyBrand]: true };
+
+const utf8 = new TextEncoder();
+
+/**
+ * A block's routing key: the raw utf8 bytes of its id. Deliberately NOT hashed here — the key network
+ * hashes the key once into a ring coordinate, and that is the only hash between a block id and its cohort.
+ */
+export function routingKeyForBlock(blockId: BlockId): RoutingKey {
+	return utf8.encode(blockId) as RoutingKey;
+}

package/src/network/stale-failure.ts

@@ -58,7 +58,11 @@ export function highestStaleAt(candidates: readonly StaleFailure['staleAt'][]):
  * 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`).
+ * who holds `rev` — that needs the revision index (see `IRevisionActionReader`). Nor would the
+ * index settle what the writer actually needs to know there, which is whether the content now held
+ * was BUILT FROM its revision; that is a separate question with its own answer
+ * (`IBlockStorage.lineageOf`, asked by the writer through `ITransactor.getLineage` once its re-send
+ * has been refused), not a widening of this one.
  *
  * Every revision-vs-action check calls this: the pend tier (`StorageRepo.pend`,
  * `ClusterMember.validatePendOperations`, `CoordinatorRepo.classifyStaleRejection`) and the commit