@optimystic/db-core 1.0.0-beta.2 → 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, 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
@@ -105,11 +185,43 @@ export class Tree<TKey, TEntry> implements TreeReadView<TKey, TEntry> {
 						compare,
 						nodeCapacity,	// keep the write btree's fan-out in lock-step with the read btree
 					);
-					for (const [key, entry] of actions) {
+					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 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.
@@ -150,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
@@ -167,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

@@ -6,6 +6,7 @@ export * from "./cohort-topic/index.js";
 export * from "./collection/index.js";
 export * from "./collections/index.js";
 export * from "./log/index.js";
+export * from "./logger-registry.js";
 export * from "./matchmaking/index.js";
 export * from "./network/index.js";
 export * from "./reactivity/index.js";
@@ -17,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/logger-registry.ts

@@ -0,0 +1,224 @@
+/*
+ * One switch for every `optimystic:*` log channel, whichever copy of `debug` it lives on.
+ *
+ * Why this exists. `debug` turns namespaces on only from `process.env.DEBUG` (Node) or
+ * `localStorage.debug` (its browser build, which is the one Metro bundles). React Native has
+ * neither, so every channel is silently off there — and an empty capture reads exactly like "that
+ * code never ran". Calling `debug.enable(...)` from app code does not fix it reliably either: it
+ * reaches only the copy of `debug` the caller resolved, and each Optimystic package may resolve its
+ * own (this repo's install, `nmHoistingLimits: workspaces`, gives every package a separate copy).
+ *
+ * So each package's `src/logger.ts` registers the copy IT imported, and `enableOptimysticLogging`
+ * drives all of them. Coverage follows from every package registering, not from how the install
+ * happened to be laid out. `docs/debugging.md` § "Turning logging on" is the user-facing statement.
+ *
+ * This module imports nothing. It sits below every logger in the package, and
+ * `test/barrel-import-cycle.spec.ts` holds registry modules to zero runtime imports.
+ */
+
+/** The slice of a `debug` module this registry drives. Structural, so db-core never type-imports a particular copy. */
+export interface DebugModule {
+	enable(namespaces: string): void;
+	/** `debug` 4.x returns the namespaces that were active. */
+	disable(): string;
+	log: (...args: any[]) => any;
+	/**
+	 * `debug`'s persistence hook, which `enable` calls with every new set: it writes
+	 * `process.env.DEBUG` on Node and `localStorage.debug` in the browser build. Suppressed around
+	 * every call this registry makes — see `withoutPersisting`. Optional so a test double need not
+	 * supply one, and because `@types/debug` does not declare it.
+	 */
+	save?: (namespaces: string) => void;
+}
+
+/** Where log lines go — the same shape as `debug`'s own `log` property. */
+export type LogSink = (...args: unknown[]) => void;
+
+export interface OptimysticLoggingOptions {
+	/**
+	 * Where log lines go. Default: leave each copy's own sink (stderr on Node; `console.debug` in the
+	 * browser/RN build). Pass one when the platform hides that sink (e.g. a device log filtered above
+	 * debug level) or to collect a capture in memory.
+	 */
+	log?: LogSink;
+}
+
+export interface OptimysticLoggingReport {
+	/** The Optimystic contribution, comma-joined — empty when the call enabled nothing. */
+	namespaces: string;
+	/** One entry per distinct `debug` copy: the packages that registered it. */
+	copies: string[][];
+}
+
+interface Entry {
+	module: DebugModule;
+	owners: string[];
+	/** What this copy had enabled, and its sink, before our first touch. Unset while untouched. */
+	original?: { namespaces: string; log: DebugModule['log'] };
+}
+
+interface Pending {
+	namespaces: string;
+	log?: LogSink;
+}
+
+/*
+ * NOTE: the state lives on `globalThis`, not in module scope, so a bundle that ends up with two
+ * copies of db-core still has ONE registry — a copy of a package that registered with the other
+ * db-core would otherwise be unreachable. The cost: two DIFFERENT db-core versions in one bundle
+ * share this object, so change its shape only additively.
+ */
+const REGISTRY_KEY = Symbol.for('@optimystic/logger-registry');
+
+interface RegistryState {
+	entries: Entry[];
+	/** The last enable call's settings, applied to copies that register afterwards. Unset when off. */
+	pending?: Pending;
+}
+
+function registry(): RegistryState {
+	const holder = globalThis as unknown as Record<symbol, RegistryState | undefined>;
+	return holder[REGISTRY_KEY] ??= { entries: [] };
+}
+
+/**
+ * Run `fn` with the copy's `save` hook stubbed out, so what we enable changes this process only.
+ *
+ * Without this, on Node every `enable` would write `process.env.DEBUG` — and a copy of `debug` that
+ * loads LATER reads that variable as its own starting set, so it would arrive with our namespaces
+ * baked into what `disableOptimysticLogging` later treats as its baseline (they could never be
+ * turned off on that copy). Capturing a baseline via `disable()` would also delete the user's
+ * `DEBUG`. In a browser, it would persist our namespaces into `localStorage.debug`, leaving logging
+ * on after a reload even without this call.
+ */
+function withoutPersisting(module: DebugModule, fn: () => void): void {
+	const save = module.save;
+	if (save) module.save = () => { };
+	try {
+		fn();
+	} finally {
+		if (save) module.save = save;
+	}
+}
+
+/**
+ * Bring one copy in line with `pending`: its baseline (captured on first touch) plus ours, and
+ * `pending.log` or its original sink.
+ *
+ * NOTE: ours is appended, so a `-optimystic:…` skip already in the copy's baseline (say
+ * `DEBUG='*,-optimystic:*'`) still wins — `debug` checks skips first. That is the user's explicit
+ * exclusion, so it is left alone; if it ever confuses someone, have the confirmation line name the
+ * conflicting skip rather than overriding it.
+ *
+ * NOTE: the baseline is captured once per enable/disable cycle, so an app that calls
+ * `debug.enable(...)` on a shared copy while ours are on has that change overwritten by our next
+ * enable or disable. Fine while apps set their channels once at start-up; if one ever toggles them
+ * at run time, re-derive the baseline from the copy's live set minus our contribution instead.
+ */
+function apply(entry: Entry, pending: Pending): void {
+	const module = entry.module;
+	if (!entry.original) {
+		let namespaces = '';
+		withoutPersisting(module, () => { namespaces = module.disable(); });
+		entry.original = { namespaces, log: module.log };
+	}
+	const combined = [entry.original.namespaces, pending.namespaces].filter(Boolean).join(',');
+	withoutPersisting(module, () => module.enable(combined));
+	module.log = pending.log ?? entry.original.log;
+}
+
+function restore(entry: Entry): void {
+	const original = entry.original;
+	if (!original) return;
+	withoutPersisting(entry.module, () => entry.module.enable(original.namespaces));
+	entry.module.log = original.log;
+	entry.original = undefined;
+}
+
+/** Comma-join, trimming each entry and dropping empty ones. A string may already hold a list. */
+function normalizeNamespaces(namespaces: string | readonly string[]): string {
+	const parts = typeof namespaces === 'string' ? [namespaces] : namespaces;
+	return parts
+		.flatMap(part => part.split(','))
+		.map(part => part.trim())
+		.filter(Boolean)
+		.join(',');
+}
+
+function confirmationLine(report: OptimysticLoggingReport): string {
+	const what = report.namespaces ? `"${report.namespaces}"` : 'nothing (empty namespace list)';
+	const trailer = 'libp2p:* is separate, see docs/debugging.md';
+	if (report.copies.length === 0) {
+		return `optimystic logging on: ${what}; no debug copies registered yet, namespaces will apply as Optimystic packages load; ${trailer}`;
+	}
+	const count = report.copies.length;
+	const groups = report.copies.map(owners => owners.join(', ')).join(' | ');
+	return `optimystic logging on: ${what} across ${count} debug ${count === 1 ? 'copy' : 'copies'} [${groups}]; ${trailer}`;
+}
+
+/**
+ * Called once from each package's `src/logger.ts` at module load, with the `debug` module that file
+ * imported. Idempotent per (owner, module); several owners sharing one copy are one entry.
+ *
+ * With no prior `enableOptimysticLogging` call this touches nothing, so `DEBUG=` on Node behaves
+ * exactly as it always has. After one, the arriving copy gets the same namespaces and sink at once
+ * (its own baseline captured first), silently — the enable call already confirmed.
+ */
+export function registerDebugModule(owner: string, module: DebugModule): void {
+	const state = registry();
+	const existing = state.entries.find(entry => entry.module === module);
+	if (existing) {
+		if (!existing.owners.includes(owner)) existing.owners.push(owner);
+		return;
+	}
+	const entry: Entry = { module, owners: [owner] };
+	state.entries.push(entry);
+	if (state.pending) apply(entry, state.pending);
+}
+
+/**
+ * Turn on the given namespaces on every registered `debug` copy, now and for copies that register
+ * later — the way to enable Optimystic logging on any runtime, React Native included, without
+ * environment variables.
+ *
+ * Adds to each copy's existing namespaces rather than replacing them, so an app's own channels
+ * sharing a copy stay on. A second call replaces the first call's namespaces and `log`, and does not
+ * accumulate. An empty list enables nothing of ours (and is not an error).
+ *
+ * Always writes one confirmation line — through `options.log` if given, else the first registered
+ * copy's sink, else `console.log` — because silence is exactly what cannot be told apart from "the
+ * code never ran". No line: this was not called, or the sink is swallowed. A line and no events: the
+ * code did not run, or the filter does not match. Events: it works.
+ */
+export function enableOptimysticLogging(
+	namespaces: string | readonly string[],
+	options?: OptimysticLoggingOptions,
+): OptimysticLoggingReport {
+	const state = registry();
+	const pending: Pending = { namespaces: normalizeNamespaces(namespaces), log: options?.log };
+	state.pending = pending;
+	for (const entry of state.entries) apply(entry, pending);
+
+	const report: OptimysticLoggingReport = {
+		namespaces: pending.namespaces,
+		copies: state.entries.map(entry => [...entry.owners]),
+	};
+	const line = confirmationLine(report);
+	const sink = options?.log ?? state.entries[0]?.module.log;
+	if (sink) {
+		sink(line);
+	} else {
+		// No Optimystic package has loaded yet, so there is no debug sink to write through — and the
+		// confirmation line must never be skipped (see above).
+		// eslint-disable-next-line no-console
+		console.log(line);
+	}
+	return report;
+}
+
+/** Undo it: every copy goes back to what it had enabled before the first enable call, and its original sink. Safe to call when nothing is enabled. */
+export function disableOptimysticLogging(): void {
+	const state = registry();
+	for (const entry of state.entries) restore(entry);
+	state.pending = undefined;
+}

package/src/logger.ts

@@ -1,7 +1,11 @@
 import debug from 'debug'
+import { registerDebugModule } from './logger-registry.js'
 
 const BASE_NAMESPACE = 'optimystic:db-core'
 
+// So `enableOptimysticLogging` reaches this package's copy of `debug`, which may be no one else's.
+registerDebugModule('db-core', debug)
+
 export function createLogger(subNamespace: string): debug.Debugger {
 	return debug(`${BASE_NAMESPACE}:${subNamespace}`)
 }

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 ?? [])));
+}