@bjornpagen/bumbledb-log 0.19.2 → 0.20.0

package/src/manifest.ts

@@ -1,17 +1,22 @@
 /**
- * The protocol's one mutable object: a v:3 binary record — version
- * byte 3, a branded Digest32 fingerprint, an optional branded Digest32
- * checkpoint. The checkpoint record is digest-keyed and immutable:
- * version byte 3, a count-bounded braid roster (id, g, hash, ts) in
- * ascending id order, catalog digest, writer, optional prev. Every
- * digest field is Digest32. The content address is blake3 of the
- * record bytes. Seed audits the catalog claim when a checkpoint is
- * present.
+ * The protocol's one mutable object and its checkpoint, as typed
+ * payloads. The byte grammar has one implementation —
+ * `crates/bumbledb-log` behind the napi bridge — so parse and render
+ * here are marshal walks: branded `Digest32` and `Braid` values in,
+ * bridge-tagged payloads across, never a second reader of the bytes.
+ * The vector algebra over checkpoint heads and the seed transition's
+ * catalog audit are machine logic and stay here.
  */
 
-import * as errors from "@superbuilders/errors"
+import type { LogCheckpointDoc, LogCheckpointKind, LogCodecHandle, LogManifestKind } from "@bjornpagen/bumbledb"
+import {
+	internalLogParseCheckpoint,
+	internalLogParseManifest,
+	internalLogRenderCheckpoint,
+	internalLogRenderManifest
+} from "@bjornpagen/bumbledb"
 import type { Digest32 } from "#bytes.ts"
-import { ByteReader, ByteWriter, bytesEqual, hex32 } from "#bytes.ts"
+import { bytesEqual, digest32, hex32 } from "#bytes.ts"
 import type { Braid } from "#descriptor.ts"
 import { braidHex } from "#descriptor.ts"
 import { refuse } from "#errors.ts"
@@ -19,66 +24,32 @@ import type { Generation } from "#keys.ts"
 import { generation } from "#keys.ts"
 import { Vector } from "#vector.ts"
 
-const DOC_VERSION = 3
-const U32_MAX = 0xffffffffn
-/** braid u32 + g u64 + hash 32 + ts u64 */
-const MIN_HEAD_BYTES = 52n
-
 interface Manifest {
 	readonly fingerprint: Digest32
 	readonly checkpoint: Digest32 | null
 }
 
-function readerOf(bytes: Uint8Array): ByteReader {
-	return new ByteReader(bytes, {
-		fail(what: string): never {
-			refuse({ kind: "Malformed", at: bytes.length }, `document truncated at ${what}`)
-		}
-	})
-}
-
-function finish(reader: ByteReader, at: string): void {
-	if (reader.remaining() !== 0) {
-		refuse({ kind: "Malformed", at: reader.remaining() }, `${reader.remaining()} trailing bytes after ${at}`)
-	}
-}
-
-function refuseUnbacked(count: bigint, remaining: number, minItem: bigint, at: string): void {
-	if (count === 0n) {
-		return
-	}
-	if (minItem === 0n || BigInt(remaining) / minItem < count) {
-		refuse({ kind: "Malformed", at: remaining }, `declared ${at} ${count} outruns the remaining ${remaining} bytes`)
-	}
-}
-
-function writeOptionalDigest(out: ByteWriter, digest: Digest32 | null): void {
-	if (digest === null) {
-		out.u8(0)
-		return
-	}
-	out.u8(1)
-	out.array32(digest)
-}
-
-function readOptionalDigest(reader: ByteReader, at: string): Digest32 | null {
-	const tag = reader.u8(at)
-	if (tag === 0) {
-		return null
-	}
-	if (tag === 1) {
-		return reader.array32(at)
-	}
-	refuse({ kind: "Flags", flags: tag }, `${at} presence is not 0 or 1`)
-}
-
-function readVersion(reader: ByteReader, at: string): void {
-	const version = reader.u8("version")
-	if (version !== DOC_VERSION) {
-		refuse(
-			{ kind: "Version", version },
-			`${at} version ${version}, consumers refuse every version other than ${DOC_VERSION}`
-		)
+/**
+ * Remints a bridge refusal row as the driver's typed refusal. The
+ * boundary carries `{ kind, message }` only: the kind is the log
+ * core's own identity string, so the cause payload holds the data this
+ * side owns — the document's length, its version byte (byte 0 of every
+ * v:3 document) — and nothing invented. The raw braid id of an
+ * `UnknownBraid` rides the message; the drifted set of a `BraidSet`
+ * rides the message the same way.
+ */
+function refuseBridged(kind: LogManifestKind | LogCheckpointKind, message: string, bytes: Uint8Array): never {
+	switch (kind) {
+		case "Version":
+			return refuse({ kind: "Version", version: bytes[0] ?? 0 }, message)
+		case "Overflow":
+			return refuse({ kind: "Overflow" }, message)
+		case "UnknownBraid":
+			return refuse({ kind: "UnknownBraid" }, message)
+		case "BraidSet":
+			return refuse({ kind: "BraidSet" }, message)
+		case "Malformed":
+			return refuse({ kind: "Malformed", at: bytes.length }, message)
 	}
 }
 
@@ -87,20 +58,22 @@ function braidIdOf(id: Braid): number {
 }
 
 function renderManifest(manifest: Manifest): Uint8Array {
-	const out = new ByteWriter(66)
-	out.u8(DOC_VERSION)
-	out.array32(manifest.fingerprint)
-	writeOptionalDigest(out, manifest.checkpoint)
-	return out.finish()
+	return internalLogRenderManifest(
+		manifest.checkpoint === null
+			? { fingerprint: manifest.fingerprint }
+			: { fingerprint: manifest.fingerprint, checkpoint: manifest.checkpoint }
+	)
 }
 
 function parseManifest(bytes: Uint8Array): Manifest {
-	const reader = readerOf(bytes)
-	readVersion(reader, "manifest")
-	const fingerprint = reader.array32("fingerprint")
-	const checkpoint = readOptionalDigest(reader, "checkpoint")
-	finish(reader, "the manifest")
-	return { fingerprint, checkpoint }
+	const parsed = internalLogParseManifest(bytes)
+	if (!parsed.ok) {
+		refuseBridged(parsed.kind, parsed.message, bytes)
+	}
+	return {
+		fingerprint: digest32(parsed.value.fingerprint),
+		checkpoint: parsed.value.checkpoint === undefined ? null : digest32(parsed.value.checkpoint)
+	}
 }
 
 interface CheckpointHead {
@@ -129,64 +102,43 @@ function checkpointVector(facts: CheckpointFacts): Vector {
 	return vectorOfHeads(facts.braids)
 }
 
-function renderCheckpoint(facts: CheckpointFacts): Uint8Array {
-	const braids = [...facts.braids.keys()].sort()
-	const count = BigInt(braids.length)
-	if (count > U32_MAX) {
-		throw errors.new(`checkpoint braid count ${count} exceeds u32`)
-	}
-	const out = new ByteWriter(1 + 4 + braids.length * 52 + 32 + 8 + 1 + 32)
-	out.u8(DOC_VERSION)
-	out.u32le(Number(count))
-	for (const id of braids) {
-		const head = facts.braids.get(id)
-		if (head === undefined) {
-			throw errors.new(`checkpoint lost braid ${id}`)
-		}
-		out.u32le(braidIdOf(id))
-		out.u64le(head.g)
-		out.array32(head.hash)
-		out.u64le(head.ts)
+function renderCheckpoint(codec: LogCodecHandle, facts: CheckpointFacts): Uint8Array {
+	const braids = [...facts.braids.entries()]
+		.sort(function ascending(a, b) {
+			return braidIdOf(a[0]) - braidIdOf(b[0])
+		})
+		.map(function headOf([id, head]) {
+			return { braid: braidIdOf(id), g: head.g, hash: head.hash, ts: head.ts }
+		})
+	const doc: LogCheckpointDoc =
+		facts.prev === null
+			? { braids, catalog: facts.catalog, writer: facts.writer }
+			: { braids, catalog: facts.catalog, writer: facts.writer, prev: facts.prev }
+	return internalLogRenderCheckpoint(codec, doc)
+}
+
+function parseCheckpoint(codec: LogCodecHandle, bytes: Uint8Array): CheckpointFacts {
+	const parsed = internalLogParseCheckpoint(codec, bytes)
+	if (!parsed.ok) {
+		refuseBridged(parsed.kind, parsed.message, bytes)
 	}
-	out.array32(facts.catalog)
-	out.u64le(facts.writer)
-	writeOptionalDigest(out, facts.prev)
-	return out.finish()
-}
-
-function parseCheckpoint(bytes: Uint8Array, known?: ReadonlySet<Braid>): CheckpointFacts {
-	const reader = readerOf(bytes)
-	readVersion(reader, "checkpoint")
-	const count = BigInt(reader.u32le("braid count"))
-	refuseUnbacked(count, reader.remaining(), MIN_HEAD_BYTES, "braid count")
 	const braids = new Map<Braid, CheckpointHead>()
-	for (let i = 0n; i < count; i++) {
-		const raw = reader.u32le("braid")
-		const name = braidHex(raw)
-		if (known !== undefined && !known.has(name)) {
-			refuse({ kind: "UnknownBraid", braid: raw }, `checkpoint cites unknown braid ${name}`)
-		}
-		const g = reader.u64le("generation")
-		const hash = reader.array32("hash")
-		const ts = reader.u64le("timestamp")
-		const last = [...braids.keys()].at(-1)
-		if (last !== undefined && last >= name) {
-			refuse(
-				{ kind: "Malformed", at: bytes.length - reader.remaining() },
-				"checkpoint braid roster is not strictly ascending"
-			)
-		}
-		braids.set(name, { g: generation(g), hash, ts })
+	for (const head of parsed.value.braids) {
+		braids.set(braidHex(head.braid), { g: generation(head.g), hash: digest32(head.hash), ts: head.ts })
 	}
-	const catalog = reader.array32("catalog")
-	const writer = reader.u64le("writer")
-	const prev = readOptionalDigest(reader, "prev")
-	finish(reader, "the checkpoint")
+	/** The core refuses `Overflow` at parse; the narrowing here is the
+	 *  derived sum's own type gate over the same heads. */
 	const summed = vectorOfHeads(braids).sum()
 	if (typeof summed !== "bigint") {
 		refuse({ kind: "Overflow" }, "checkpoint vector sum overflows u64")
 	}
-	return { braids, catalog, writer, prev, sum: summed }
+	return {
+		braids,
+		catalog: digest32(parsed.value.catalog),
+		writer: parsed.value.writer,
+		prev: parsed.value.prev === undefined ? null : digest32(parsed.value.prev),
+		sum: summed
+	}
 }
 
 /** The seed transition's catalog claim: a present checkpoint
@@ -205,5 +157,5 @@ function auditCatalog(facts: CheckpointFacts | null, computed: Digest32): void {
 	)
 }
 
-export type { CheckpointFacts, CheckpointHead, Manifest }
-export { auditCatalog, checkpointVector, DOC_VERSION, parseCheckpoint, parseManifest, renderCheckpoint, renderManifest }
+export type { CheckpointFacts, CheckpointHead }
+export { auditCatalog, checkpointVector, parseCheckpoint, parseManifest, renderCheckpoint, renderManifest }

package/src/replica.ts

@@ -10,17 +10,17 @@
 
 import * as fs from "node:fs/promises"
 import * as path from "node:path"
-import type { Db, Fact, MemberRelation, Schema, SchemaRelations, WriteOutcome } from "@bjornpagen/bumbledb"
-import { internalBlake3, Db as SdkDb } from "@bjornpagen/bumbledb"
+import type { Db, MemberRelation, Schema, SchemaRelations, WriteOutcome } from "@bjornpagen/bumbledb"
+import { factOf, internalBlake3, Db as SdkDb } from "@bjornpagen/bumbledb"
 import * as errors from "@superbuilders/errors"
 import { parse } from "#braids.ts"
 import type { Digest32 } from "#bytes.ts"
-import { bytesEqual, digest32, hex32, saturatingAddU64, toHex } from "#bytes.ts"
+import { bytesEqual, digest32, hex32, saturatingAddU64 } from "#bytes.ts"
 import type { Chain, ChainEntry, Pending } from "#chain.ts"
 import { chainGeneration, chainSum, readSidecar, writeSidecar } from "#chain.ts"
 import type { Op } from "#codec.ts"
 import { decodeBatch, encodeBatch, verifyChain } from "#codec.ts"
-import type { Braid, Descriptor, RelationInfo } from "#descriptor.ts"
+import type { Braid, Descriptor } from "#descriptor.ts"
 import { descriptorOf } from "#descriptor.ts"
 import { ErrRefused, ErrReplayDiverged, refuse, refuseManifestMissing, wrapStore } from "#errors.ts"
 import type { Generation } from "#keys.ts"
@@ -38,7 +38,6 @@ import {
 import type { CheckpointFacts } from "#manifest.ts"
 import { auditCatalog, parseCheckpoint, parseManifest } from "#manifest.ts"
 import type { Etag, ObjectStore } from "#store.ts"
-import type { Value } from "#value.ts"
 import { Vector } from "#vector.ts"
 
 const ZERO_HASH = digest32(new Uint8Array(32))
@@ -46,8 +45,9 @@ const ZERO_HASH = digest32(new Uint8Array(32))
 /** The gc-safety heartbeat cadence: every N-th pass re-reads the manifest. */
 const HEARTBEAT_PASSES = 16
 
-/** The re-poll cadence of waitFor, its one consumer. */
-const WAIT_FOR_POLL_MS = 20
+/** The re-poll cadence of waitFor, its one consumer — the
+ *  machine-constants table's `wait_for_poll_ms` fact. */
+const WAIT_FOR_POLL_MS = 10
 
 type ReplicaState =
 	| { readonly tag: "bootstrapped" }
@@ -66,6 +66,13 @@ type Step =
 	| { readonly tag: "wedged"; readonly braid: Braid; readonly cause: string }
 	| { readonly tag: "reseed"; readonly cause: string }
 
+/** The full waitFor sum: a wedged braid the target needs is an
+ *  outcome, never an infinite poll. */
+type Waited =
+	| { readonly tag: "reached"; readonly vector: ReadonlyMap<Braid, Generation> }
+	| { readonly tag: "wedged"; readonly braid: Braid; readonly cause: string }
+	| { readonly tag: "refused"; readonly detail: string }
+
 type ApplyPhase = "open" | "steady"
 
 type SlotApply = { readonly tag: "applied"; readonly generation: bigint } | { readonly tag: "discard" }
@@ -81,7 +88,7 @@ interface Replica<Rels extends SchemaRelations> extends AsyncDisposable {
 	readonly db: Db<Rels>
 	readonly vector: ReadonlyMap<Braid, Generation>
 	refresh(braid?: Braid): Promise<ReadonlyMap<Braid, Generation>>
-	waitFor(vector: ReadonlyMap<Braid, Generation>): Promise<void>
+	waitFor(vector: ReadonlyMap<Braid, Generation>): Promise<Waited>
 }
 
 interface Core<Rels extends SchemaRelations> {
@@ -130,10 +137,6 @@ function withGate<Rels extends SchemaRelations, R>(core: Core<Rels>, body: () =>
 	return run
 }
 
-function blake3Hex(bytes: Uint8Array): string {
-	return toHex(new Uint8Array(internalBlake3(bytes)))
-}
-
 function blake3Digest(bytes: Uint8Array): Digest32 {
 	return digest32(new Uint8Array(internalBlake3(bytes)))
 }
@@ -162,7 +165,7 @@ function braidOf(theory: Schema<SchemaRelations> | Schema<never>, raw: Braid): B
 	const id = Number.parseInt(raw.slice(1), 16)
 	const parsed = parse(theory, id)
 	if (parsed === undefined) {
-		refuse({ kind: "UnknownBraid", braid: Number.isFinite(id) ? id : 0 }, `unknown braid ${raw}`)
+		refuse({ kind: "UnknownBraid" }, `unknown braid ${raw}`)
 	}
 	return parsed
 }
@@ -194,40 +197,25 @@ function generationOf<Rels extends SchemaRelations>(core: Core<Rels>): bigint {
 	})
 }
 
-function digestOfCatalog(raw: unknown): Digest32 {
-	if (raw instanceof Uint8Array) {
-		return digest32(raw)
-	}
-	throw errors.new(`catalogDigest is not a digest: ${typeof raw}`)
-}
-
-/** The opened store's catalog digest. The SDK may expose it on the
- *  handle or on the read instance; either spelling is the computed claim. */
+/** The opened store's catalog digest — the engine handle's computed claim. */
 function catalogDigestOf<Rels extends SchemaRelations>(core: Core<Rels>): Digest32 {
-	const handle = core.db as unknown as { catalogDigest?: () => unknown }
-	if (typeof handle.catalogDigest === "function") {
-		return digestOfCatalog(handle.catalogDigest())
-	}
-	return core.db.read(function readCatalog(instance) {
-		const carrier = instance as { catalogDigest?: unknown }
-		if (typeof carrier.catalogDigest === "function") {
-			return digestOfCatalog(carrier.catalogDigest())
-		}
-		throw errors.new("the opened store does not expose catalogDigest")
-	})
-}
-
-function chainOf<Rels extends SchemaRelations>(core: Core<Rels>): Chain {
-	return core.chain
+	return digest32(core.db.catalogDigest())
 }
 
-/** Pending-arm payload: recorded ops ride on the batch, not a third
- *  Option beside the vector. Wire Pending is {braid,gen,bytes}; ops is
- *  the in-memory field of that arm (§30). */
-type HeldBatch = Pending & { readonly ops: readonly Op[] | null }
+/** Pending-arm payload: recorded ops and the batch header's timestamp
+ *  ride on the batch, not a third Option beside the vector. Wire
+ *  Pending is {braid,gen,bytes}; ops/ts are the in-memory fields of
+ *  that arm (§30) — null on a batch adopted as bytes the seat has not
+ *  decoded. */
+type HeldBatch = Pending & { readonly ops: readonly Op[] | null; readonly ts: bigint | null }
 
-function holdPending<Rels extends SchemaRelations>(core: Core<Rels>, batch: Pending, ops: readonly Op[] | null): void {
-	const held: HeldBatch = { braid: batch.braid, gen: batch.gen, bytes: batch.bytes, ops }
+function holdPending<Rels extends SchemaRelations>(
+	core: Core<Rels>,
+	batch: Pending,
+	ops: readonly Op[] | null,
+	ts: bigint | null
+): void {
+	const held: HeldBatch = { braid: batch.braid, slot: batch.slot, bytes: batch.bytes, ops, ts }
 	core.chain = { tag: "pending", entries: entriesOf(core), batch: held }
 }
 
@@ -258,7 +246,7 @@ function atCheckpointFloor<Rels extends SchemaRelations>(core: Core<Rels>): bool
 }
 
 async function persistSidecar<Rels extends SchemaRelations>(core: Core<Rels>): Promise<void> {
-	await writeSidecar(sidecarPath(core), chainOf(core))
+	await writeSidecar(core.descriptor.codec, sidecarPath(core), core.chain)
 }
 
 /** Writes the checkpoint store file and fsyncs the file and its parent
@@ -312,9 +300,10 @@ function adoptChain<Rels extends SchemaRelations>(core: Core<Rels>, chain: Chain
 	if (chain.tag === "pending") {
 		const held: HeldBatch = {
 			braid: braidOf(core.theory, chain.batch.braid),
-			gen: chain.batch.gen,
+			slot: chain.batch.slot,
 			bytes: chain.batch.bytes,
-			ops: null
+			ops: null,
+			ts: null
 		}
 		core.chain = { tag: "pending", entries, batch: held }
 	} else {
@@ -322,47 +311,20 @@ function adoptChain<Rels extends SchemaRelations>(core: Core<Rels>, chain: Chain
 	}
 }
 
-/** Positional decoded row → the SDK's named fact, handles lifted for closed refs. */
-function factOf<Rels extends SchemaRelations>(
-	core: Core<Rels>,
-	relation: RelationInfo,
-	row: readonly Value[]
-): Record<string, unknown> {
-	const fact: Record<string, unknown> = {}
-	relation.fields.forEach(function liftCell(field, ordinal) {
-		const value = row[ordinal]
-		if (value === undefined) {
-			throw errors.new(`relation ${relation.name}: decoded row cell ${ordinal} absent`)
-		}
-		if (field.closedRef !== undefined && typeof value === "bigint") {
-			const roster = core.descriptor.relationByName.get(field.closedRef)
-			const handle = roster?.handles[Number(value)]
-			if (handle === undefined) {
-				throw errors.new(
-					`relation ${relation.name}.${field.name}: id ${value} is outside the ${field.closedRef} roster`
-				)
-			}
-			fact[field.name] = handle
-			return
-		}
-		fact[field.name] = value
-	})
-	return fact
-}
-
-/** One `db.write` applying ops in listed order, rows in listed order. */
+/** One `db.write` applying ops in listed order, rows in listed order.
+ *  The positional row → named fact lift is the engine's `factOf` —
+ *  closed-ref handles included. */
 function applyOps<Rels extends SchemaRelations>(core: Core<Rels>, ops: readonly Op[]): WriteOutcome<Rels, number> {
 	return core.db.write(function applyBatch(tx) {
 		for (const op of ops) {
-			const info = core.descriptor.relationByName.get(op.relation)
 			const member = core.theory.relations[op.relation]
-			if (info === undefined || member === undefined) {
+			if (member === undefined) {
 				throw errors.new(`batch op cites unknown relation ${op.relation}`)
 			}
 			const relation = member as MemberRelation<Rels>
 			const facts = op.rows.map(function liftRow(row) {
-				return factOf(core, info, row)
-			}) as unknown as Iterable<Fact<MemberRelation<Rels>>>
+				return factOf(relation, row)
+			})
 			if (op.op === "insert") {
 				tx.insert(relation, facts)
 			} else {
@@ -503,7 +465,7 @@ async function stepBraid<Rels extends SchemaRelations>(
 		return { tag: "tip" }
 	}
 	const chain = core.chain
-	if (chain.tag === "pending" && id === chain.batch.braid && next === chain.batch.gen) {
+	if (chain.tag === "pending" && id === chain.batch.braid && next === chain.batch.slot) {
 		if (!bytesEqual(fetched.bytes, chain.batch.bytes)) {
 			return { tag: "reseed", cause: "lost-pending-fork" }
 		}
@@ -599,16 +561,9 @@ async function adoptManifest<Rels extends SchemaRelations>(
 		if (facts === null) {
 			throw errors.new(`manifest points at absent checkpoint ${hex32(manifest.checkpoint)}`)
 		}
-		const checkpoint = parseCheckpoint(facts.bytes)
-		for (const id of checkpoint.braids.keys()) {
-			braidOf(core.theory, id)
-		}
-		const carried = [...checkpoint.braids.keys()].sort()
-		const derived = [...core.descriptor.braidMembers.keys()].sort()
-		if (carried.join(",") !== derived.join(",")) {
-			refuse({ kind: "CheckpointBraids", carried, derived }, "checkpoint braid set drifted from the derived braids")
-		}
-		core.checkpoint = checkpoint
+		// The codec-backed parseCheckpoint judges the braid set against the
+		// sealed handle — an unknown or drifted braid refuses at parse.
+		core.checkpoint = parseCheckpoint(core.descriptor.codec, facts.bytes)
 		core.checkpointDigest = manifest.checkpoint
 	}
 	// The pointer is adopted only after the checkpoint it names is in
@@ -798,7 +753,7 @@ async function resolvePendingAtOpen<Rels extends SchemaRelations>(core: Core<Rel
 			generationOf(core),
 			null,
 			chain.batch.bytes,
-			belowFloor(core, chain.batch.braid, chain.batch.gen)
+			belowFloor(core, chain.batch.braid, chain.batch.slot)
 		).tag === "below-floor"
 	) {
 		await settle(core)
@@ -823,7 +778,7 @@ async function resolvePendingAtOpen<Rels extends SchemaRelations>(core: Core<Rel
 		await settle(core)
 		return
 	}
-	holdPending(core, chain.batch, decoded.data.ops)
+	holdPending(core, chain.batch, decoded.data.ops, decoded.data.header.timestamp)
 }
 
 /**
@@ -837,7 +792,7 @@ async function resolvePendingAtOpen<Rels extends SchemaRelations>(core: Core<Rel
 async function resolveColdPending<Rels extends SchemaRelations>(core: Core<Rels>, pending: Pending): Promise<void> {
 	const braid = braidOf(core.theory, pending.braid)
 	if (
-		foldPending(chainSum(core.chain), generationOf(core), null, pending.bytes, belowFloor(core, braid, pending.gen))
+		foldPending(chainSum(core.chain), generationOf(core), null, pending.bytes, belowFloor(core, braid, pending.slot))
 			.tag === "below-floor"
 	) {
 		await settle(core)
@@ -859,7 +814,7 @@ async function resolveColdPending<Rels extends SchemaRelations>(core: Core<Rels>
 	const before = generationOf(core)
 	const outcome = applyOps(core, decoded.data.ops)
 	if (outcome.tag === "accepted" && outcome.value.generation > before) {
-		holdPending(core, { ...pending, braid }, decoded.data.ops)
+		holdPending(core, { ...pending, braid }, decoded.data.ops, decoded.data.header.timestamp)
 		await readdressPending(core, decoded.data.ops, decoded.data.header.writer)
 	}
 }
@@ -892,23 +847,16 @@ async function openCore<Rels extends SchemaRelations>(options: OpenReplicaOption
 	await adoptManifest(core, fetched.bytes, fetched.etag)
 
 	const existing = await newestStoreDir(core.dir)
-	const sidecar = await readSidecar(sidecarPath(core))
+	const sidecar = await readSidecar(descriptor.codec, sidecarPath(core))
 	let opened = false
 	let coldPending: Pending | null = null
 	if (sidecar.tag === "fault") {
 		throw wrapStore(sidecar.io, `read sidecar ${sidecarPath(core)}`)
 	}
-	if (sidecar.tag === "read") {
-		for (const id of sidecar.chain.entries.keys()) {
-			braidOf(core.theory, id)
-		}
-		if (sidecar.chain.tag === "pending") {
-			braidOf(core.theory, sidecar.chain.batch.braid)
-		}
-	}
-	if (sidecar.tag === "corrupt") {
-		coldPending = null
-	} else if (existing !== null && sidecar.tag === "read") {
+	// The codec-backed readSidecar judges every braid against the sealed
+	// handle — a foreign braid is a corrupt sidecar, and a corrupt
+	// sidecar is discarded cache (the disposable law), never adopted.
+	if (existing !== null && sidecar.tag === "read") {
 		core.storeName = existing
 		const openedDb = await errors.try(SdkDb.open(storePath(core), options.theory))
 		if (openedDb.error === undefined) {
@@ -921,7 +869,6 @@ async function openCore<Rels extends SchemaRelations>(options: OpenReplicaOption
 	if (!opened) {
 		if (sidecar.tag === "read" && sidecar.chain.tag === "pending") {
 			coldPending = sidecar.chain.batch
-			braidOf(core.theory, coldPending.braid)
 		}
 		await initializeStore(core)
 	}
@@ -989,7 +936,6 @@ async function readdressPending<Rels extends SchemaRelations>(
 	const bytes = encodeBatch(
 		core.descriptor,
 		{
-			fingerprint: digest32(core.descriptor.fingerprintBytes),
 			braid,
 			braidGen: generation(entry.g + 1n),
 			prev: entry.prev,
@@ -998,7 +944,7 @@ async function readdressPending<Rels extends SchemaRelations>(
 		},
 		ops
 	)
-	holdPending(core, { braid, gen: generation(entry.g + 1n), bytes }, ops)
+	holdPending(core, { braid, slot: generation(entry.g + 1n), bytes }, ops, timestamp)
 	await persistSidecar(core)
 }
 
@@ -1024,19 +970,33 @@ async function refreshPass<Rels extends SchemaRelations>(core: Core<Rels>, braid
 	return outcome
 }
 
-/** waitFor is refresh with a predicate: the same pass, then the check. */
-async function refreshUntil<Rels extends SchemaRelations>(core: Core<Rels>, predicate: () => boolean): Promise<void> {
+/** waitFor is refresh with a verdict: the same pass, then the full
+ *  Waited sum. A braid the target needs that is wedged below it returns
+ *  Wedged — no refresh will ever reach the target — and a heartbeat
+ *  refusal returns Refused. */
+async function waitForVector<Rels extends SchemaRelations>(
+	core: Core<Rels>,
+	target: ReadonlyMap<Braid, Generation>
+): Promise<Waited> {
 	for (;;) {
 		disposed(core)
-		if (predicate()) {
-			return
+		const have = vectorOf(core)
+		for (const [braid, wanted] of target) {
+			const cause = core.wedged.get(braid)
+			const at = have.get(braid)
+			if (cause !== undefined && at !== undefined && at < wanted) {
+				return { tag: "wedged", braid, cause }
+			}
 		}
-		await withGate(core, async function waitPass() {
+		if (Vector.from(have).dominates(Vector.from(target))) {
+			return { tag: "reached", vector: have }
+		}
+		const outcome = await withGate(core, async function waitPass() {
 			disposed(core)
-			await refreshPass(core)
+			return refreshPass(core)
 		})
-		if (predicate()) {
-			return
+		if (outcome.tag === "refused") {
+			return { tag: "refused", detail: outcome.detail }
 		}
 		await new Promise(function later(resolve) {
 			setTimeout(resolve, WAIT_FOR_POLL_MS)
@@ -1062,12 +1022,11 @@ async function openReplica<Rels extends SchemaRelations>(options: OpenReplicaOpt
 			})
 		},
 		async waitFor(vector) {
-			for (const braid of vector.keys()) {
-				chainEntry(core, braid)
+			const target = new Map<Braid, Generation>()
+			for (const [braid, wanted] of vector) {
+				target.set(braidOf(core.theory, braid), wanted)
 			}
-			await refreshUntil(core, function reached() {
-				return Vector.from(vectorOf(core)).dominates(Vector.from(vector))
-			})
+			return waitForVector(core, target)
 		},
 		async [Symbol.asyncDispose]() {
 			await withGate(core, async function disposeBody() {
@@ -1080,14 +1039,11 @@ async function openReplica<Rels extends SchemaRelations>(options: OpenReplicaOpt
 	return replica
 }
 
-export type { ApplyPhase, Core, OpenReplicaOptions, PendingFold, RefreshOutcome, Replica, ReplicaState, SlotApply }
+export type { Core, OpenReplicaOptions, RefreshOutcome, Replica, Waited }
 export {
 	applyOps,
-	applySlot,
 	belowFloor,
-	blake3Hex,
 	chainEntry,
-	chainOf,
 	clearPending,
 	coreOf,
 	discardAndReopen,
@@ -1100,8 +1056,6 @@ export {
 	pendingOf,
 	persistSidecar,
 	readdressPending,
-	vectorOf,
-	wholenessHolds,
 	withGate,
 	ZERO_HASH
 }