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

package/src/collection/struct.ts

@@ -1,4 +1,4 @@
-import type { IBlock, BlockId, Action } from "../index.js";
+import type { IBlock, BlockId, Action, WriteDurability } from "../index.js";
 import type { IChainHeader } from "../chain/chain-nodes.js";
 import type { RandFn } from "../utility/backoff.js";
 
@@ -48,7 +48,12 @@ export interface SyncOptions {
 
 /** Thrown by {@link ICollection.sync} / {@link ICollection.updateAndSync} when the retry budget
  * (attempt count or deadline) is exhausted while the transactor keeps returning stale failures.
- * Catchable so callers can surface a clear "gave up syncing" condition instead of hanging. */
+ * Catchable so callers can surface a clear "gave up syncing" condition instead of hanging.
+ *
+ * It says the write was NOT SAVED; it does not prove nothing was stored. A write's log tail is
+ * committed before its other blocks, and the attempt that spent the budget is not followed by a
+ * refresh, so that attempt's log entry may be standing in the log with none of its data — the state
+ * {@link TornActionError} names when a refresh does get to see it. */
 export class SyncRetryExhaustedError extends Error {
 	constructor(
 		readonly collectionId: CollectionId,
@@ -111,6 +116,91 @@ export class SyncRevisionStalledError extends SyncRetryExhaustedError {
 	}
 }
 
+/** Why a half-landed write could not be finished (see {@link TornActionError}). This is the CAUSE
+ * of giving up; whether the write is then definitely not saved is a separate fact, carried by
+ * {@link TornActionError.final} — every reason can arrive with either value.
+ *
+ * - `rival-holds-revision` — finishing was refused because a DIFFERENT action holds a revision past
+ *   the one the write needed on some block. That alone does NOT mean the write is lost: a later
+ *   revision is often built ON the write (a rival that read it and added to it), and a write every
+ *   block of which was built upon is reported SAVED, never by this error. It is raised only once
+ *   the blocks' own history was asked (`ITransactor.getLineage`) and did not vouch for every block.
+ * - `completion-refused` — finishing was attempted and refused for a cause that can clear on its
+ *   own (another write in flight on the block, the revision not yet held by a majority). The write
+ *   paths retry this inside their own budget, so seeing it means that budget ran out.
+ * - `transforms-not-held` — the write's own log entry was found with blocks still missing, but this
+ *   collection no longer holds the transforms that would finish them. */
+export type TornActionReason = 'rival-holds-revision' | 'completion-refused' | 'transforms-not-held';
+
+/** Thrown when a write HALF-LANDED and was not finished: its log entry is stored, but at least one
+ * of the other blocks that entry names is not known to hold the write.
+ *
+ * A write's log tail is committed before the rest of its blocks, so a write can be refused AFTER the
+ * tail was stored (see `NetworkTransactor.commit`). The writer's retry then finds its own log entry.
+ * That entry proves only that the tail landed; the write is saved only once EVERY block the entry
+ * names holds the write — at the write's own revision, or at a later revision that was built from
+ * it — so the retry finishes the remaining blocks at the same action id and revision (see
+ * `Collection.completeOwnEntry`). This error is what it raises when it could not — {@link reason}
+ * says why, and {@link final} says what that leaves the caller able to do.
+ *
+ * **{@link final} is the field to act on.** An application's only safe reaction to a failed write
+ * is to submit it again, and that is only safe when the first one can never show up:
+ *
+ * - `final: true` — the write is NOT saved and never will be. Every block it still needed answered
+ *   for its whole cohort that it does not hold the write (its history passed the write's revision
+ *   without it, or it never reached that revision), and the write's pending records were confirmed
+ *   cancelled first, so nothing is left that could land it. Submitting the same change again stores
+ *   it once.
+ * - `final: false` — that could NOT be established. The write may already be saved, or may still
+ *   land (a block's cohort did not all answer, members contradicted each other, fewer than a
+ *   majority hold it, or the cancel could not be confirmed). Submitting again can store the change
+ *   twice; read the data back first.
+ *
+ * It is deliberately not a {@link SyncRetryExhaustedError}: that error says the write never landed,
+ * whereas here the log already holds an entry for it. Finishing needs the original action id and
+ * the transforms it sent, and both are gone once this escapes. Re-driving under a NEW revision
+ * records the same actions in the log twice, so nothing here does that on the caller's behalf. The
+ * staged actions are left in place on the collection, so at this level "submit again" is calling
+ * `sync()` again, and abandoning the write is the caller's to do (`Collection.restorePending`).
+ * `Tree.replace` and `Diary.append` do abandon it — they own both the staging and the flush, and a
+ * failed call that left its action staged would ride along, unasked, with the caller's next write.
+ *
+ * Raised out of {@link ICollection.sync} / {@link ICollection.updateAndSync}, and out of the
+ * refresh `TransactionCoordinator.commit` runs between attempts (`Collection.refreshInFlight`).
+ * The coordinator passes it on bare only when no other participant of the commit is saved; when
+ * one is, it arrives as the `reason` of a `CoordinatorPartialCommitError` that names the saved
+ * participants. */
+export class TornActionError extends Error {
+	constructor(
+		readonly collectionId: CollectionId,
+		/** The half-landed write's action id. */
+		readonly actionId: string,
+		/** The revision its log entry landed at — the revision every block it names had to take. */
+		readonly rev: number,
+		/** The blocks the entry names that are not known to hold the write. */
+		readonly blockIds: BlockId[],
+		/** Why finishing failed — see {@link TornActionReason}. Says nothing about {@link final}. */
+		readonly reason: TornActionReason,
+		/** Whether the write is definitely not saved and can never land — see the class comment.
+		 * `false` means "not established", never "it landed". */
+		readonly final: boolean,
+		/** The refusal in the responder's own words, for a log line. Never branch on it. */
+		readonly detail: string,
+		/** The confirmed revision a responder reported holding under ANOTHER action, when the refusal
+		 * carried one (see `StaleFailure.staleAt`). */
+		readonly staleAt?: { blockId: BlockId; rev: number },
+	) {
+		super(`collection ${collectionId}: action ${actionId} is torn at rev ${rev} — its log entry is stored `
+			+ `but block(s) ${blockIds.join(', ') || '(unknown)'} are not known to hold it, and the write cannot be `
+			+ `finished: ${detail}`
+			+ (staleAt ? ` (block ${staleAt.blockId} is at rev ${staleAt.rev})` : '')
+			+ (final
+				? ' — the write is not saved and cannot land; it is safe to submit again'
+				: ' — whether the write is saved could not be established; it may be saved already or land later'));
+		this.name = 'TornActionError';
+	}
+}
+
 /** Thrown when a collection that already holds a committed revision reads its own header
  * block as authoritatively absent.
  *
@@ -147,8 +237,13 @@ export interface ICollection<TAction> {
 	readonly id: CollectionId;
 	act(...actions: Action<TAction>[]): Promise<void>;
 	update(): Promise<void>;
-	sync(options?: SyncOptions): Promise<void>;
-	updateAndSync(options?: SyncOptions): Promise<void>;
+	/** Push staged changes. Resolves to who holds what was committed, or `undefined` when NOTHING WAS
+	 * WRITTEN — nothing was staged, so there was no pend and no commit and there is no durability to
+	 * report. A write that never landed throws ({@link SyncRetryExhaustedError}) rather than returning
+	 * a class. Decide "is this saved" with `isFullyDurable`, never by comparing `quorum`. */
+	sync(options?: SyncOptions): Promise<WriteDurability | undefined>;
+	/** Refresh, then {@link sync}. Same return contract. */
+	updateAndSync(options?: SyncOptions): Promise<WriteDurability | undefined>;
 	selectLog(forward?: boolean): AsyncIterableIterator<Action<TAction>>;
 }
 

package/src/collections/diary/diary.ts

@@ -1,68 +1,71 @@
-import { Collection } from "../../collection/collection.js";
-import type { ITransactor, Action, BlockId, BlockStore, IBlock, CollectionInitOptions, CollectionId } from "../../index.js";
-import { registerCollectionType } from "../../collection/collection-type-registry.js";
-import { DiaryHeaderBlockType } from "./struct.js";
-
-/** A diary keeps every entry in the log itself, so the header block is the whole structure
- *  and the "append" handler has no blocks to touch. */
-function diaryInit<TEntry>(): CollectionInitOptions<TEntry> {
-	return {
-		modules: {
-			"append": async (_action, _trx) => {
-				// Append-only diary doesn't need to modify any blocks
-				// All entries are stored in the log
-			}
-		},
-		createHeaderBlock: (id: BlockId, store: BlockStore<IBlock>) => ({
-			header: store.createBlockHeader(DiaryHeaderBlockType, id)
-		})
-	};
-}
-
-export class Diary<TEntry> {
-    private constructor(
-			private readonly collection: Collection<TEntry>
-		) {
-    }
-
-    /** Open an existing diary, or stage a fresh empty one when nothing has ever been committed
-     *  under this id. Attach-or-create — see {@link Collection.createOrOpen}. */
-    static async createOrOpen<TEntry>(network: ITransactor, id: CollectionId): Promise<Diary<TEntry>> {
-        const collection = await Collection.createOrOpen(network, id, diaryInit<TEntry>());
-        return new Diary<TEntry>(collection);
-    }
-
-    /** Open an EXISTING diary, or resolve to `undefined` when no header block has ever been
-     *  committed under this id. Never brings a diary into existence — see {@link Collection.open}. */
-    static async open<TEntry>(network: ITransactor, id: CollectionId): Promise<Diary<TEntry> | undefined> {
-        const collection = await Collection.open(network, id, diaryInit<TEntry>());
-        return collection ? new Diary<TEntry>(collection) : undefined;
-    }
-
-    async append(data: TEntry): Promise<void> {
-        const action: Action<TEntry> = {
-            type: "append",
-            data: data
-        };
-
-        await this.collection.act(action);
-        await this.collection.updateAndSync();
-    }
-
-    /** Fetch the latest state from the network */
-    async update(): Promise<void> {
-        await this.collection.update();
-    }
-
-    async *select(forward = true): AsyncIterableIterator<TEntry> {
-        for await (const entry of this.collection.selectLog(forward)) {
-            yield entry.data;
-        }
-    }
-}
-
-registerCollectionType({
-	blockType: DiaryHeaderBlockType,
-	name: "Diary",
-	createOrOpen: (transactor, id) => Collection.createOrOpen(transactor, id, diaryInit<unknown>()),
-});
+import { Collection } from "../../collection/collection.js";
+import type { ITransactor, Action, BlockId, BlockStore, IBlock, CollectionInitOptions, CollectionId, WriteDurability } from "../../index.js";
+import { registerCollectionType } from "../../collection/collection-type-registry.js";
+import { DiaryHeaderBlockType } from "./struct.js";
+
+/** A diary keeps every entry in the log itself, so the header block is the whole structure
+ *  and the "append" handler has no blocks to touch. */
+function diaryInit<TEntry>(): CollectionInitOptions<TEntry> {
+	return {
+		modules: {
+			"append": async (_action, _trx) => {
+				// Append-only diary doesn't need to modify any blocks
+				// All entries are stored in the log
+			}
+		},
+		createHeaderBlock: (id: BlockId, store: BlockStore<IBlock>) => ({
+			header: store.createBlockHeader(DiaryHeaderBlockType, id)
+		})
+	};
+}
+
+export class Diary<TEntry> {
+    private constructor(
+			private readonly collection: Collection<TEntry>
+		) {
+    }
+
+    /** Open an existing diary, or stage a fresh empty one when nothing has ever been committed
+     *  under this id. Attach-or-create — see {@link Collection.createOrOpen}. */
+    static async createOrOpen<TEntry>(network: ITransactor, id: CollectionId): Promise<Diary<TEntry>> {
+        const collection = await Collection.createOrOpen(network, id, diaryInit<TEntry>());
+        return new Diary<TEntry>(collection);
+    }
+
+    /** Open an EXISTING diary, or resolve to `undefined` when no header block has ever been
+     *  committed under this id. Never brings a diary into existence — see {@link Collection.open}. */
+    static async open<TEntry>(network: ITransactor, id: CollectionId): Promise<Diary<TEntry> | undefined> {
+        const collection = await Collection.open(network, id, diaryInit<TEntry>());
+        return collection ? new Diary<TEntry>(collection) : undefined;
+    }
+
+    /** Append one entry and flush it. Forwards the collection's answer verbatim — see
+     *  {@link Collection.sync} for what `undefined` means. This layer never interprets the value.
+     *  An append that throws leaves nothing staged (see {@link Collection.actAndSync}), so a caller
+     *  that appends it again records it once, not twice. */
+    async append(data: TEntry): Promise<WriteDurability | undefined> {
+        const action: Action<TEntry> = {
+            type: "append",
+            data: data
+        };
+
+        return await this.collection.actAndSync([action]);
+    }
+
+    /** Fetch the latest state from the network */
+    async update(): Promise<void> {
+        await this.collection.update();
+    }
+
+    async *select(forward = true): AsyncIterableIterator<TEntry> {
+        for await (const entry of this.collection.selectLog(forward)) {
+            yield entry.data;
+        }
+    }
+}
+
+registerCollectionType({
+	blockType: DiaryHeaderBlockType,
+	name: "Diary",
+	createOrOpen: (transactor, id) => Collection.createOrOpen(transactor, id, diaryInit<unknown>()),
+});

package/src/collections/tree/struct.ts

@@ -26,7 +26,10 @@ export const rootId$ = nameof<TreeCollectionHeaderBlock>("rootId");
  *
  * - `absent` — the key must not exist (SQL INSERT): a hit throws {@link TreeKeyTakenError},
  *   discarding the whole action's staged writes.
- * - `keepExisting` — if the key exists, skip this entry silently (SQL INSERT OR IGNORE).
+ * - `keepExisting` — if the key exists, skip this entry silently. No SQL statement stages
+ *   it any more (INSERT OR IGNORE is guarded `absent`, because skipping only the main-table
+ *   entry would leave the statement's index entries beside a rival's row — see the
+ *   `unchanged` paragraph in docs/internals.md); kept as a serialized log form.
  * - `absentRange` — no entry OTHER THAN this action's own key may exist in `range`
  *   (secondary-UNIQUE enforcement, where uniqueness is a property of a framed key
  *   PREFIX rather than one exact key: an index tree keys `indexKey ‖ primaryKey`, so
@@ -34,47 +37,125 @@ export const rootId$ = nameof<TreeCollectionHeaderBlock>("rootId");
  *   foreign hit throws {@link TreeRangeTakenError}. The entry being staged lands inside
  *   its own range, so the scan excludes its exact key — otherwise every guarded
  *   re-stage of a present key (a replay after a clean refresh) would refuse itself.
+ * - `unchanged` — see {@link TreeUnchangedGuard}: the only kind that says something must
+ *   still BE here, rather than that nothing may be.
  *
  * MIXED VERSIONS: a peer running a build that predates guards destructures `[key, entry]`
  * and ignores the third slot — its replays revert to today's silent overwrite. No version
  * gating exists yet (see backlog ticket `debt-mixed-version-identify-incompatibility`).
  */
-export type TreeEntryGuard<TKey> =
+export type TreeEntryGuard<TKey, TEntry = unknown> =
 	| { kind: 'absent' }
 	| { kind: 'keepExisting' }
-	| { kind: 'absentRange', range: KeyRange<TKey> };
+	| { kind: 'absentRange', range: KeyRange<TKey> }
+	| TreeUnchangedGuard<TEntry>;
 
-/** Represents a unit of change to a tree collection. */
-export type TreeReplaceAction<TKey, TEntry> = [
-	// The key to replace
+/**
+ * "The entry I am replacing must still be exactly the one I read" — the optimistic-concurrency
+ * (lost-update) guard, and the only {@link TreeEntryGuard} kind that also applies to a DELETE.
+ * The entry at the key must be PRESENT and structurally equal to `expected` (`structuralEquals`
+ * in `packages/db-core/src/utility/structural-equals.ts`); otherwise the handler throws
+ * {@link TreeEntryChangedError}.
+ *
+ * ABSENT COUNTS AS CHANGED. The staged effect was computed from an entry image that no longer
+ * exists, so re-applying it is never right: an upsert would resurrect a row a rival deleted, and
+ * a delete would be the second of two racing deletes. Refusing both is the optimistic answer —
+ * the writer read a row that is now gone, and an application-level retry then affects zero rows
+ * sequentially. If tolerating absence on deletes is ever genuinely wanted, add a separate
+ * `unchangedOrAbsent` kind rather than weakening this one's contract.
+ *
+ * `expected` is the entry AS STORED, not a digest: a guard rides in the log beside its action
+ * under the same encoding entries already use, so a full copy round-trips by construction and no
+ * digest scheme has to be invented, versioned, or kept in sync with the entry encoding.
+ *
+ * NOTE: that choice roughly doubles the row bytes of every guarded log entry (the new entry plus
+ * a full copy of the old one). If log volume ever becomes the binding constraint, replace
+ * `expected` with a content digest — the block-digest utilities under
+ * `packages/db-core/src/transaction/` are the starting point — and accept the versioning burden
+ * that comes with it.
+ */
+export type TreeUnchangedGuard<TEntry = unknown> = {
+	kind: 'unchanged',
+	/** The entry image the staged write read, as stored. */
+	expected: TEntry,
+};
+
+/** An element that writes (inserts or replaces) an entry. Any {@link TreeEntryGuard} kind is
+ *  meaningful here. */
+export type TreeUpsertElement<TKey, TEntry> = [
+	// The key to write at
+	key: TKey,
+	// The entry to write
+	entry: TEntry,
+	// Optional intent, re-checked on every handler run (see TreeEntryGuard). Absent = plain
+	// upsert, so existing callers and previously committed log entries deserialize and replay
+	// unchanged.
+	guard?: TreeEntryGuard<TKey, TEntry>,
+];
+
+/** An element that deletes the entry at a key. Only {@link TreeUnchangedGuard} says anything a
+ *  delete can act on — the other kinds all assert that nothing is present, which would make the
+ *  delete a no-op by construction. The handler rejects any other kind at runtime too, since a
+ *  replayed log entry is deserialized data that this type never policed. */
+export type TreeDeleteElement<TKey, TEntry> = [
+	// The key to delete
 	key: TKey,
-	// The new entry to replace the old entry with (if not provided, the key is deleted)
-	entry?: TEntry,
-	// Optional uniqueness intent, re-checked on every handler run (see TreeEntryGuard).
-	// Absent = plain upsert, so existing callers and previously committed log entries
-	// deserialize and replay unchanged.
-	guard?: TreeEntryGuard<TKey>,
-][];
+	// Always empty: the absent entry is what marks this element a delete
+	entry?: undefined,
+	// Optional lost-update guard: refuse the delete unless the entry is still the one that was read
+	guard?: TreeUnchangedGuard<TEntry>,
+];
+
+/** Represents a unit of change to a tree collection. */
+export type TreeReplaceAction<TKey, TEntry> = (
+	| TreeUpsertElement<TKey, TEntry>
+	| TreeDeleteElement<TKey, TEntry>
+)[];
 
 /**
- * Thrown by the tree `replace` handler when an entry guarded `absent` finds its key
- * already present — at initial staging, or (the load-bearing case) at conflict replay
- * after a rival writer's commit was adopted. The throw discards the whole action's
- * staged writes (the handler runs inside an all-or-nothing Atomic wrapper) and
- * propagates out of the sync/commit retry loops: it is not a StaleFailure, so no
- * retry absorbs it, and it must never be downgraded to a retryable condition.
+ * Base of every refusal a {@link TreeEntryGuard} raises out of the tree `replace` handler — at
+ * initial staging, or (the load-bearing case) at conflict replay after a rival writer's commit
+ * was adopted. One contract, stated once for every subclass:
+ *
+ * - The throw **discards the whole action's staged writes** — the handler runs inside an
+ *   all-or-nothing Atomic wrapper, so not one entry of a multi-entry action lands.
+ * - It is **not a `StaleFailure`**, so neither `Collection.sync`'s retry loop nor
+ *   `TransactionCoordinator.commit`'s stale-loss re-drive absorbs it; it propagates out of the
+ *   losing commit, and it must never be downgraded to a retryable condition.
+ *
+ * Subclasses split by WHAT was refused, because consumers map them differently: a
+ * {@link TreeKeyTakenError} is a uniqueness violation (the Quereus bridge renders it as
+ * `UNIQUE constraint failed`), while a {@link TreeEntryChangedError} is a lost update. Catch
+ * this base to treat any guard refusal uniformly; catch a subclass to say which happened.
  */
-export class TreeKeyTakenError<TKey = unknown> extends Error {
+export class TreeGuardRefusedError<TKey = unknown> extends Error {
 	constructor(
 		/** The collection whose tree refused the entry. */
 		public readonly collectionId: CollectionId,
+		/** The key whose staged entry was refused. */
+		public readonly key: TKey,
+		message: string,
+	) {
+		super(message);
+		this.name = 'TreeGuardRefusedError';
+	}
+}
+
+/**
+ * Thrown when an entry guarded `absent` finds its key already present: a duplicate-key
+ * refusal. See {@link TreeGuardRefusedError} for the contract every guard refusal shares.
+ */
+export class TreeKeyTakenError<TKey = unknown> extends TreeGuardRefusedError<TKey> {
+	constructor(
+		collectionId: CollectionId,
 		/** The key some other writer already committed (for the `absentRange` subclass: the
 		 * key this action was staging, whose claimed range a rival occupies). */
-		public readonly key: TKey,
+		key: TKey,
 		/** Subclass override of the rendered message; the default names the exact-key refusal. */
 		message?: string,
 	) {
-		super(message ?? `Tree collection ${collectionId}: key ${renderKey(key)} is already taken by a committed entry`);
+		super(collectionId, key,
+			message ?? `Tree collection ${collectionId}: key ${renderKey(key)} is already taken by a committed entry`);
 		this.name = 'TreeKeyTakenError';
 	}
 }
@@ -107,9 +188,60 @@ export class TreeRangeTakenError<TKey = unknown> extends TreeKeyTakenError<TKey>
 	}
 }
 
+/**
+ * The {@link TreeUnchangedGuard} refusal: the entry at `key` is no longer the one the staged
+ * write read — a rival committed a different entry there, or removed it (`actual` is
+ * `undefined`). A lost update, NOT a uniqueness violation, which is why this deliberately does
+ * NOT subclass {@link TreeKeyTakenError}: the Quereus bridge renders every `TreeKeyTakenError`
+ * as that collection's registered `UNIQUE constraint failed` message (`mapCommitRefusal` in
+ * `packages/quereus-plugin-optimystic/src/optimystic-adapter/txn-bridge.ts`), and reporting a
+ * concurrent-update refusal as a uniqueness failure would mislead every client that reads it.
+ * The shared contract lives on {@link TreeGuardRefusedError}.
+ */
+export class TreeEntryChangedError<TKey = unknown, TEntry = unknown> extends TreeGuardRefusedError<TKey> {
+	constructor(
+		collectionId: CollectionId,
+		/** The key whose entry the staged write was replacing or deleting. */
+		key: TKey,
+		/** The entry image the staged write read, as carried by its guard. */
+		public readonly expected: TEntry,
+		/** What is committed at `key` now; `undefined` when the entry is gone entirely. */
+		public readonly actual: TEntry | undefined,
+	) {
+		super(collectionId, key,
+			`Tree collection ${collectionId}: the entry at key ${renderKey(key)} was `
+			+ `${actual === undefined ? 'removed' : 'changed'} by another writer since this change read it`);
+		this.name = 'TreeEntryChangedError';
+	}
+}
+
+/**
+ * A DELETE element carries a guard kind no delete can act on. NOT a concurrency refusal and
+ * deliberately not a {@link TreeGuardRefusedError}: every other kind asserts that nothing is
+ * present, which would make the delete a no-op by construction, so this is a malformed action —
+ * a caller bug, or a log entry written by a build whose element types disagree with this one.
+ * The handler raises it rather than ignoring the guard (the pre-guard behaviour) so a writer
+ * never believes an unenforceable guard is being enforced.
+ */
+export class TreeDeleteGuardKindError<TKey = unknown> extends Error {
+	constructor(
+		/** The collection whose tree rejected the element. */
+		public readonly collectionId: CollectionId,
+		/** The key the malformed delete named. */
+		public readonly key: TKey,
+		/** The `kind` that was carried; only `'unchanged'` is meaningful on a delete. */
+		public readonly guardKind: string,
+	) {
+		super(`Tree collection ${collectionId}: the delete of key ${renderKey(key)} carries a `
+			+ `'${guardKind}' guard; only 'unchanged' is meaningful on a delete`);
+		this.name = 'TreeDeleteGuardKindError';
+	}
+}
+
 /** String keys render JSON-quoted so framing control bytes stay visible/escaped in logs;
  * everything else via String() — JSON.stringify would throw on a bigint key, and an error
- * constructor must never be the second failure. */
+ * constructor must never be the second failure. Module-private on purpose: every tree message
+ * renders a key the same way because every one of them is constructed in this file. */
 function renderKey(key: unknown): string {
 	return typeof key === 'string' ? JSON.stringify(key) : String(key);
 }