@bjornpagen/bumbledb-log 0.18.0 → 0.19.0

package/src/writer.ts

@@ -1,48 +1,88 @@
 /**
- * The writer (60): a replica plus the right to create log objects. One
- * commit path and one loss path: a lost slot's byte-equal occupant is
- * an ambiguous PUT absorbed; anything else discards the local
- * directory, re-opens through the replica to the current tip, and
- * re-judges the recorded ops once — the verdict IS a serial execution,
- * performed. Each loop iteration races once at the then-tip, so a
- * historical loss is structurally uncountable, and bounded live-tip
- * losses surface as ErrContention carrying the terminal re-judgment's
- * own violation or the racing tip.
+ * The writer (60): a replica plus the right to create log objects. Role
+ * is a field on the handle. `openWriter(options)` births the store;
+ * `openWriter(replica)` wraps a born replica and settles an inherited
+ * pending without drawing id leases. A replica never births —
+ * ManifestMissing is its refusal. One commit path and one loss path: a
+ * lost slot's byte-equal occupant is an ambiguous PUT absorbed; anything
+ * else discards the local directory, re-opens through the replica to the
+ * current tip, and re-judges the recorded ops once — the verdict IS a
+ * serial execution, performed. Each loop iteration races once at the
+ * then-tip, so a historical loss is structurally uncountable, and bounded
+ * live-tip losses surface as ErrContention carrying the terminal
+ * re-judgment's own violation or the racing tip.
  */
 
 import * as crypto from "node:crypto"
-import type { Fact, FreshKeys, MemberRelation, SchemaRelations, Violation } from "@bjornpagen/bumbledb"
+import * as fs from "node:fs/promises"
+import * as path from "node:path"
+import {
+	type Fact,
+	type FreshKeys,
+	internalBlake3,
+	type MemberRelation,
+	type SchemaRelations,
+	type Violation
+} from "@bjornpagen/bumbledb"
 import * as errors from "@superbuilders/errors"
-import { bytesEqual, utf8Encoder, utf8StrictDecoder } from "#bytes.ts"
+import { regex } from "arkregex"
+import type { Digest32 } from "#bytes.ts"
+import { bytesEqual, checkedAddU64, digest32, digest32FromHex, utf8Encoder, utf8StrictDecoder } from "#bytes.ts"
+import { chainSum } from "#chain.ts"
 import type { Op } from "#codec.ts"
 import { decodeBatch, encodeBatch } from "#codec.ts"
 import type { Braid, RelationInfo } from "#descriptor.ts"
-import { ErrSpanningCommit, throwContention } from "#errors.ts"
+import { descriptorOf } from "#descriptor.ts"
+import { ErrSpanningCommit, refuseExhausted, refuseOverWidth, refuseSlotRetired, throwContention } from "#errors.ts"
 import type { Generation } from "#keys.ts"
-import { generation, idsKey, logKey } from "#keys.ts"
-import type { Core, Replica } from "#replica.ts"
+import {
+	CKPT_SCRATCH_LEASE,
+	checkpointMdbKey,
+	ckptDocKey,
+	encodeCkptScratch,
+	generation,
+	idsKey,
+	LEASE_NAMESPACE,
+	logKey,
+	manifestKey
+} from "#keys.ts"
+import type { CheckpointFacts } from "#manifest.ts"
+import { checkpointVector, parseCheckpoint, parseManifest, renderCheckpoint, renderManifest } from "#manifest.ts"
+import type { Core, OpenReplicaOptions, Replica } from "#replica.ts"
 import {
 	applyOps,
-	blake3Hex,
+	belowFloor,
 	chainEntry,
 	clearPending,
 	coreOf,
 	discardAndReopen,
+	entriesOf,
+	foldPending,
 	generationOf,
+	holdPending,
 	maxBigint,
+	openReplica,
+	pendingOf,
 	persistSidecar,
 	readdressPending,
 	withGate
 } from "#replica.ts"
+import type { ObjectStore } from "#store.ts"
 import type { Value } from "#value.ts"
 import { checkAgainst } from "#value.ts"
 
 /** 10 owns the width: one CAS amortizes counter traffic 4096× below slot traffic. */
 const LEASE_WIDTH = 4096n
+const ID_LEASE_COUNTER = regex("^\\d+$")
 
 /** The live-loss bound (60): consecutive losses at the live tip, history never counts. */
 const LOSS_BOUND = 16
 
+/** Writer id in the fixed-layout header: magic + version + flags + fingerprint + braid + braid_gen + prev. */
+const WRITER_AT = 4 + 2 + 2 + 32 + 4 + 8 + 32
+
+const BATCH_MAGIC = utf8Encoder.encode("BDBL")
+
 type Durability = "published" | "local-pending"
 
 type Commit<Rels extends SchemaRelations, R> =
@@ -84,9 +124,20 @@ interface Batch<Rels extends SchemaRelations> {
 	): readonly bigint[]
 }
 
+/** Ownership of a slot, read from the winner's header. */
+interface Deposition {
+	readonly braid: Braid
+	readonly slot: Generation
+	readonly resident: bigint
+	readonly usurper: bigint
+}
+
 interface Writer<Rels extends SchemaRelations> {
-	commit<R>(body: (batch: Batch<Rels>) => R): Promise<Commit<Rels, R>>
-	commitSplit<R>(body: (batch: Batch<Rels>) => R): Promise<CommitSplit<Rels, R>>
+	readonly role: "writer"
+	readonly replica: Replica<Rels>
+	deposition(): Deposition | null
+	commit<R>(body: (batch: Batch<Rels>) => R | Promise<R>): Promise<Commit<Rels, R>>
+	commitSplit<R>(body: (batch: Batch<Rels>) => R | Promise<R>): Promise<CommitSplit<Rels, R>>
 }
 
 interface LeaseRange {
@@ -94,37 +145,81 @@ interface LeaseRange {
 	readonly end: bigint
 }
 
+/** The scream of an unbounded repair loop: the set of recent signatures,
+ *  a warning every eighth attempt, and an alarm the moment any
+ *  signature recurs. */
+interface Scream {
+	attempt(signature: string): void
+}
+
+function screamOf(context: string): Scream {
+	const seen = new Set<string>()
+	let attempts = 0
+	return {
+		attempt(signature) {
+			attempts += 1
+			if (seen.has(signature)) {
+				console.error(`bumbledb-log alarm: ${context} repair signature recurs: ${signature}`)
+			} else {
+				seen.add(signature)
+			}
+			if (attempts % 8 === 0) {
+				console.error(`bumbledb-log warning: ${context} repair attempt ${attempts}: ${signature}`)
+			}
+		}
+	}
+}
+
 interface WriterState {
 	readonly writerId: bigint
 	readonly pools: Map<string, LeaseRange[]>
+	readonly scream: Scream
+	deposition: Deposition | null
 }
 
-const ErrLeaseDrained = errors.new("bumbledb-log lease pool drained mid-recording")
-const leaseDemand = new WeakMap<Error, { relation: number; field: number }>()
-
 function poolKey(relation: number, field: number): string {
 	return `${relation}:${field}`
 }
 
+function remainingOf(state: WriterState, relation: number, field: number): bigint {
+	const pool = state.pools.get(poolKey(relation, field)) ?? []
+	let remaining = 0n
+	for (const range of pool) {
+		remaining += range.end - range.next
+	}
+	return remaining
+}
+
 function drawIds(state: WriterState, relation: number, field: number, count: bigint): bigint[] {
+	if (count < 0n) {
+		throw errors.new(`id-lease count is unsigned: ${count}`)
+	}
+	if (count > LEASE_WIDTH) {
+		refuseOverWidth({ requested: count }, `id-lease draw ${count} exceeds the lease width ${LEASE_WIDTH}`)
+	}
+	if (count === 0n) {
+		return []
+	}
 	const pool = state.pools.get(poolKey(relation, field)) ?? []
+	const range = pool[0]
+	if (range === undefined || range.end - range.next < count) {
+		refuseExhausted(
+			{ relation, field },
+			`id-lease relation ${relation} field ${field} cannot draw ${count} from the cached block`
+		)
+	}
+	if (checkedAddU64(range.next, count) === undefined) {
+		refuseExhausted({ relation, field }, `id-lease relation ${relation} field ${field} would leave u64`)
+	}
 	const ids: bigint[] = []
 	let remaining = count
-	while (remaining > 0n) {
-		const range = pool[0]
-		if (range === undefined) {
-			const fault = errors.wrap(ErrLeaseDrained, `relation ${relation} field ${field} needs ${remaining} more ids`)
-			leaseDemand.set(fault, { relation, field })
-			throw fault
-		}
-		while (remaining > 0n && range.next < range.end) {
-			ids.push(range.next)
-			range.next += 1n
-			remaining -= 1n
-		}
-		if (range.next >= range.end) {
-			pool.shift()
-		}
+	while (remaining > 0n && range.next < range.end) {
+		ids.push(range.next)
+		range.next += 1n
+		remaining -= 1n
+	}
+	if (range.next >= range.end) {
+		pool.shift()
 	}
 	state.pools.set(poolKey(relation, field), pool)
 	return ids
@@ -149,13 +244,17 @@ async function acquireLease<Rels extends SchemaRelations>(
 			continue
 		}
 		const body = utf8StrictDecoder.decode(fetched.bytes)
-		if (!/^\d+$/.test(body)) {
+		if (!ID_LEASE_COUNTER.test(body)) {
 			throw errors.new(`id-lease counter ${key} is not a canonical decimal: ${body}`)
 		}
 		const next = BigInt(body)
-		const swapped = await core.store.putSwap(key, utf8Encoder.encode(String(next + LEASE_WIDTH)), fetched.etag)
+		const end = checkedAddU64(next, LEASE_WIDTH)
+		if (end === undefined) {
+			refuseExhausted({ relation, field }, `id-lease relation ${relation} field ${field} would leave u64`)
+		}
+		const swapped = await core.store.putSwap(key, utf8Encoder.encode(String(end)), fetched.etag)
 		if (swapped.tag === "swapped") {
-			pushRange(state, relation, field, next, next + LEASE_WIDTH)
+			pushRange(state, relation, field, next, end)
 			return
 		}
 	}
@@ -167,6 +266,19 @@ function pushRange(state: WriterState, relation: number, field: number, next: bi
 	state.pools.set(poolKey(relation, field), pool)
 }
 
+async function ensureFreshLeases<Rels extends SchemaRelations>(core: Core<Rels>, state: WriterState): Promise<void> {
+	for (const info of core.descriptor.relations) {
+		if (info.closed) {
+			continue
+		}
+		for (const [ordinal, field] of info.fields.entries()) {
+			if (field.fresh && remainingOf(state, info.id, ordinal) === 0n) {
+				await acquireLease(core, state, info.id, ordinal)
+			}
+		}
+	}
+}
+
 interface Recording {
 	readonly ops: Op[]
 }
@@ -254,29 +366,18 @@ function recorderOf<Rels extends SchemaRelations>(
 	return { batch, recording }
 }
 
-/** Runs the recording body, refilling the id-lease pool on a drained
- *  draw and re-running — recording is pure, so a re-run before any
- *  judgment invokes nothing twice that the store could observe. */
+/** Runs the recording body exactly once. The body is awaited to
+ *  completion before the batch is sealed; reserve draws from the
+ *  cached block (OverWidth | Exhausted | Drawn). */
 async function recordWithLeases<Rels extends SchemaRelations, R>(
 	core: Core<Rels>,
 	state: WriterState,
-	body: (batch: Batch<Rels>) => R
+	body: (batch: Batch<Rels>) => R | Promise<R>
 ): Promise<{ value: R; ops: Op[] }> {
-	for (let attempt = 0; attempt < 16; attempt++) {
-		const { batch, recording } = recorderOf(core, state)
-		const ran = errors.trySync(function runBody() {
-			return body(batch)
-		})
-		if (ran.error === undefined) {
-			return { value: ran.data, ops: recording.ops }
-		}
-		const demand = leaseDemand.get(ran.error) ?? leaseDemand.get(errors.cause(ran.error))
-		if (demand === undefined) {
-			throw ran.error
-		}
-		await acquireLease(core, state, demand.relation, demand.field)
-	}
-	throw errors.new("the id-lease pool could not satisfy the recording after 16 refills")
+	await ensureFreshLeases(core, state)
+	const { batch, recording } = recorderOf(core, state)
+	const value = await body(batch)
+	return { value, ops: recording.ops }
 }
 
 function braidsTouched<Rels extends SchemaRelations>(core: Core<Rels>, ops: readonly Op[]): Map<Braid, Op[]> {
@@ -297,9 +398,48 @@ function braidsTouched<Rels extends SchemaRelations>(core: Core<Rels>, ops: read
 	return partitioned
 }
 
+function u64leAt(bytes: Uint8Array, at: number): bigint | undefined {
+	if (bytes.length < at + 8) {
+		return undefined
+	}
+	const view = new DataView(bytes.buffer, bytes.byteOffset + at, 8)
+	return view.getBigUint64(0, true)
+}
+
+/** The usurper is a fact in the header. A body that refuses to decode
+ *  does not hide the slot's owner. */
+function headerWriter(bytes: Uint8Array): bigint | undefined {
+	if (bytes.length < BATCH_MAGIC.length || !bytesEqual(bytes.subarray(0, BATCH_MAGIC.length), BATCH_MAGIC)) {
+		return undefined
+	}
+	return u64leAt(bytes, WRITER_AT)
+}
+
+function headerTimestamp(bytes: Uint8Array): bigint | undefined {
+	return u64leAt(bytes, WRITER_AT + 8)
+}
+
+/** Header prev is 32 branded bytes. */
+function digestPrev(prev: Digest32 | Uint8Array): Digest32 {
+	return digest32(prev)
+}
+
+function noteDeposition(state: WriterState, braid: Braid, slot: Generation, winnerBytes: Uint8Array): void {
+	if (state.deposition !== null) {
+		return
+	}
+	const usurper = headerWriter(winnerBytes)
+	if (usurper === undefined) {
+		return
+	}
+	state.deposition = { braid, slot, resident: state.writerId, usurper }
+}
+
 /** The terminal contention scream: the re-judgment's own rejection names
  *  the hot statement and carries the offending facts' raw values; an
- *  accepted-but-outraced terminal loss carries the racing tip. */
+ *  accepted-but-outraced terminal loss carries the racing tip. A
+ *  rejection without a violation is refused — the empty statement is
+ *  unrepresentable. */
 function screamContention<Rels extends SchemaRelations>(
 	braid: Braid,
 	rejudged:
@@ -308,13 +448,16 @@ function screamContention<Rels extends SchemaRelations>(
 ): never {
 	if (rejudged.tag === "rejected") {
 		const violation = rejudged.violations[0]
+		if (violation === undefined) {
+			throw errors.new("a rejection carries at least one violation")
+		}
 		throwContention(
 			{
 				braid,
 				cause: {
 					kind: "hot-key",
-					statement: violation === undefined ? "" : violation.canonical,
-					determinants: (violation?.facts ?? []).map(function rawOf(offending) {
+					statement: violation.canonical,
+					determinants: violation.facts.map(function rawOf(offending) {
 						return offending.fact
 					})
 				}
@@ -329,15 +472,13 @@ function screamContention<Rels extends SchemaRelations>(
 }
 
 /**
- * Publishes the applied pending batch: slot CAS, then the one loss path
- * on Exists. A byte-equal occupant is our own ambiguous PUT, absorbed.
- * Anything else carries the pending through a directory discard —
- * re-persisted into the fresh sidecar before any re-judgment, so a
- * crash mid-loss resolves it at the next open — re-opens to the
- * current tip, and re-judges the recorded ops in one db.write: publish
- * on accepted-and-state-changing, Accepted at the current generation
- * on a net no-op (the publish law), or the serial Rejected. Each
- * iteration races once at the then-tip; the bound counts iterations.
+ * Publishes the applied pending batch: refuse a below-floor create,
+ * then slot CAS, then the one loss path on Exists. A byte-equal
+ * occupant is our own ambiguous PUT, absorbed. Anything else carries
+ * the pending through a directory discard — re-persisted into the
+ * fresh sidecar before any re-judgment — re-opens to the current tip,
+ * and re-judges the recorded ops in one db.write. An occupant that
+ * then vanishes is retired, not a loop that forges the swept slot.
  */
 async function publishPending<Rels extends SchemaRelations>(
 	core: Core<Rels>,
@@ -346,31 +487,46 @@ async function publishPending<Rels extends SchemaRelations>(
 ): Promise<Commit<Rels, undefined>> {
 	let losses = 0
 	for (;;) {
-		const pending = core.pending
+		const pending = pendingOf(core)
 		if (pending === null) {
 			throw errors.new("publish reached with no pending batch")
 		}
 		const braid = pending.braid
+		// The floor is a write precondition: a slot at or below it is
+		// retired. A create must not touch the store (70/116/127).
+		if (belowFloor(core, braid, pending.gen)) {
+			refuseSlotRetired({ braid, slot: pending.gen }, "the slot is retired")
+		}
 		const created = await core.store.putCreate(logKey(core.prefix, braid, pending.gen), pending.bytes)
 		let winnerBytes: Uint8Array | null = null
-		if (created.tag === "exists") {
+		if (created.tag !== "created") {
 			const fetched = await core.store.get(logKey(core.prefix, braid, pending.gen))
 			if (fetched === null) {
-				continue
+				// Exists then null: the occupant was swept. Refuse
+				// rather than loop back into putCreate.
+				refuseSlotRetired({ braid, slot: pending.gen }, "the slot is retired")
 			}
 			if (!bytesEqual(fetched.bytes, pending.bytes)) {
 				winnerBytes = fetched.bytes
 			}
 		}
 		if (winnerBytes === null) {
-			const header = decodeBatch(core.descriptor, pending.bytes).header
-			core.chain.set(braid, { g: pending.gen, prev: blake3Hex(pending.bytes), ts: header.timestamp })
+			const timestamp = headerTimestamp(pending.bytes)
+			if (timestamp === undefined) {
+				throw errors.new("pending batch header is shorter than the fixed layout")
+			}
+			entriesOf(core).set(braid, {
+				g: pending.gen,
+				prev: digest32(new Uint8Array(internalBlake3(pending.bytes))),
+				ts: timestamp
+			})
 			await clearPending(core)
 			return { tag: "accepted", value: undefined, braid, generation: pending.gen, durability: "published" }
 		}
 
 		losses += 1
-		core.pendingApplied = false
+		state.scream.attempt("slot occupant is not ours")
+		noteDeposition(state, braid, pending.gen, winnerBytes)
 		await discardAndReopen(core)
 		const before = generationOf(core)
 		const rejudged = applyOps(core, ops)
@@ -391,6 +547,8 @@ async function publishPending<Rels extends SchemaRelations>(
 				durability: "published"
 			}
 		}
+		const tip = chainEntry(core, braid)
+		entriesOf(core).set(braid, { g: tip.g, prev: digestPrev(tip.prev), ts: tip.ts })
 		await readdressPending(core, ops, state.writerId)
 		if (losses >= LOSS_BOUND) {
 			screamContention(braid, { tag: "outraced", tip: chainEntry(core, braid).g })
@@ -398,8 +556,9 @@ async function publishPending<Rels extends SchemaRelations>(
 	}
 }
 
-/** The commit discipline (60): encode, fsync the pending, judge locally,
- *  publish only what advanced the generation. */
+/** The commit discipline (60): encode, fsync as Pending before any
+ *  apply, judge locally, publish only what advanced the generation.
+ *  Settled is written only after the verdict. */
 async function disciplineCommit<Rels extends SchemaRelations>(
 	core: Core<Rels>,
 	state: WriterState,
@@ -411,18 +570,17 @@ async function disciplineCommit<Rels extends SchemaRelations>(
 	const bytes = encodeBatch(
 		core.descriptor,
 		{
-			fingerprint: core.descriptor.fingerprint,
+			fingerprint: digest32FromHex(core.descriptor.fingerprint),
 			braid,
 			braidGen: generation(entry.g + 1n),
-			prev: entry.prev,
+			prev: digestPrev(entry.prev),
 			writer: state.writerId,
 			timestamp
 		},
 		ops
 	)
-	core.pending = { braid, gen: generation(entry.g + 1n), bytes }
-	core.pendingOps = ops
-	core.pendingApplied = false
+	// Pending → durable, before any apply.
+	holdPending(core, { braid, gen: generation(entry.g + 1n), bytes }, ops)
 	await persistSidecar(core)
 
 	const before = generationOf(core)
@@ -435,31 +593,223 @@ async function disciplineCommit<Rels extends SchemaRelations>(
 		await clearPending(core)
 		return { tag: "accepted", value: undefined, braid, generation: entry.g, durability: "published" }
 	}
-	core.pendingApplied = true
 	return publishPending(core, state, ops)
 }
 
-/** A recovered pending owed from a previous life publishes before any new commit. */
+/** An inherited pending is resolved-and-published by open. A slot the
+ *  floor already covers is published (`Clear`), not re-judged (46). */
 async function settleInheritedPending<Rels extends SchemaRelations>(
 	core: Core<Rels>,
 	state: WriterState
 ): Promise<void> {
-	if (core.pending === null || !core.pendingApplied || core.pendingOps === null) {
+	const pending = pendingOf(core)
+	if (pending === null) {
+		return
+	}
+	if (
+		foldPending(
+			chainSum(core.chain),
+			generationOf(core),
+			null,
+			pending.bytes,
+			belowFloor(core, pending.braid, pending.gen)
+		).tag === "below-floor"
+	) {
+		await clearPending(core)
 		return
 	}
-	await publishPending(core, state, core.pendingOps)
+	let ops = pending.ops
+	if (ops === null) {
+		const decoded = errors.trySync(function decodePending() {
+			return decodeBatch(core.descriptor, pending.bytes)
+		})
+		if (decoded.error) {
+			await clearPending(core)
+			return
+		}
+		ops = decoded.data.ops
+	}
+	const published = await publishPending(core, state, ops)
+	if (published.tag === "rejected") {
+		return
+	}
+}
+
+type PublishRefusal = "manifest-missing" | "manifest" | "checkpoint-doc-missing" | "checkpoint"
+
+type Published =
+	| { readonly tag: "replaced" }
+	| { readonly tag: "kept"; readonly incumbent: Digest32 }
+	| { readonly tag: "refused"; readonly reason: PublishRefusal }
+
+async function putCreateOnce(store: ObjectStore, key: ReturnType<typeof ckptDocKey>, bytes: Uint8Array): Promise<void> {
+	for (;;) {
+		const created = await store.putCreate(key, bytes)
+		if (created.tag === "created" || created.tag === "exists") {
+			return
+		}
+		const fetched = await store.get(key)
+		if (fetched !== null) {
+			return
+		}
+	}
 }
 
-function openWriter<Rels extends SchemaRelations>(replica: Replica<Rels>): Writer<Rels> {
+/** The loser deletes its own `ckpt/{digest}` and `.mdb`. */
+async function deleteOrphan(store: ObjectStore, prefix: string, digest: Digest32): Promise<void> {
+	await store.delete(ckptDocKey(prefix, digest))
+	await store.delete(checkpointMdbKey(prefix, digest))
+}
+
+function scratchPath(dir: string): string {
+	return path.join(dir, LEASE_NAMESPACE, CKPT_SCRATCH_LEASE)
+}
+
+async function claimScratch(dir: string, digest: Digest32): Promise<void> {
+	const target = scratchPath(dir)
+	await fs.mkdir(path.dirname(target), { recursive: true })
+	const handle = await fs.open(target, "w")
+	const written = await errors.try(
+		(async function writeLease() {
+			await handle.writeFile(encodeCkptScratch(digest))
+			await handle.sync()
+		})()
+	)
+	await handle.close()
+	if (written.error) {
+		await fs.rm(target, { force: true })
+		throw written.error
+	}
+}
+
+async function releaseScratch(dir: string): Promise<void> {
+	await fs.rm(scratchPath(dir), { force: true })
+}
+
+async function casPublish(
+	store: ObjectStore,
+	prefix: string,
+	known: ReadonlySet<Braid>,
+	candidate: CheckpointFacts,
+	digest: Digest32,
+	bytes: Uint8Array
+): Promise<Published> {
+	await putCreateOnce(store, ckptDocKey(prefix, digest), bytes)
+	for (;;) {
+		const fetched = await store.get(manifestKey(prefix))
+		if (fetched === null) {
+			return { tag: "refused", reason: "manifest-missing" }
+		}
+		const parsed = errors.trySync(function parse() {
+			return parseManifest(fetched.bytes)
+		})
+		if (parsed.error) {
+			return { tag: "refused", reason: "manifest" }
+		}
+		const incumbent = parsed.data.checkpoint
+		if (incumbent !== null && bytesEqual(incumbent, digest)) {
+			return { tag: "replaced" }
+		}
+		if (incumbent !== null) {
+			const doc = await store.get(ckptDocKey(prefix, incumbent))
+			if (doc === null) {
+				return { tag: "refused", reason: "checkpoint-doc-missing" }
+			}
+			const incumbentDoc = errors.trySync(function parseIncumbent() {
+				return parseCheckpoint(doc.bytes, known)
+			})
+			if (incumbentDoc.error) {
+				return { tag: "refused", reason: "checkpoint" }
+			}
+			if (checkpointVector(candidate).order(checkpointVector(incumbentDoc.data)) !== "after") {
+				return { tag: "kept", incumbent }
+			}
+		}
+		const next = renderManifest({ fingerprint: parsed.data.fingerprint, checkpoint: digest })
+		const swapped = await store.putSwap(manifestKey(prefix), next, fetched.etag)
+		if (swapped.tag === "swapped") {
+			return { tag: "replaced" }
+		}
+	}
+}
+
+/**
+ * Publishes `candidate` under the checkpoint order. The digest is the
+ * blake3 of the full bytes, `prev` included. A scratch lease
+ * `{dir}/~lease/ckpt-scratch` names the candidate for the publish
+ * window; a crash leaves that lease and a successor sweep reclaims
+ * it. `Kept` and every refused publish delete the candidate's `ckpt`
+ * pair.
+ */
+async function publishCheckpoint(
+	store: ObjectStore,
+	prefix: string,
+	dir: string,
+	known: ReadonlySet<Braid>,
+	candidate: CheckpointFacts,
+	mdb: Uint8Array
+): Promise<Published> {
+	const bytes = renderCheckpoint(candidate)
+	const digest = digest32(new Uint8Array(internalBlake3(bytes)))
+	await claimScratch(dir, digest)
+	const ran = await errors.try(
+		(async function publish() {
+			await putCreateOnce(store, checkpointMdbKey(prefix, digest), mdb)
+			return await casPublish(store, prefix, known, candidate, digest, bytes)
+		})()
+	)
+	if (ran.error) {
+		throw ran.error
+	}
+	if (ran.data.tag === "kept" || ran.data.tag === "refused") {
+		await deleteOrphan(store, prefix, digest)
+	}
+	await releaseScratch(dir)
+	return ran.data
+}
+
+/** Only the writer births a store: create-only PUT of a genesis manifest. */
+async function birthStore(store: ObjectStore, prefix: string, fingerprint: Digest32): Promise<void> {
+	const key = manifestKey(prefix)
+	for (;;) {
+		const fetched = await store.get(key)
+		if (fetched !== null) {
+			return
+		}
+		const bytes = renderManifest({ fingerprint, checkpoint: null })
+		const created = await store.putCreate(key, bytes)
+		if (created.tag === "created") {
+			return
+		}
+	}
+}
+
+function isReplica<Rels extends SchemaRelations>(
+	source: Replica<Rels> | OpenReplicaOptions<Rels>
+): source is Replica<Rels> {
+	return typeof (source as Replica<Rels>).refresh === "function"
+}
+
+/** Wrap a born replica: settle an inherited pending; do not birth; do not draw id leases. */
+async function writerOn<Rels extends SchemaRelations>(replica: Replica<Rels>): Promise<Writer<Rels>> {
 	const core = coreOf(replica)
 	const state: WriterState = {
 		writerId: crypto.randomBytes(8).readBigUInt64LE(),
-		pools: new Map()
+		pools: new Map(),
+		scream: screamOf("writer discard-and-re-pull"),
+		deposition: null
 	}
+	await withGate(core, async function openTransition() {
+		await settleInheritedPending(core, state)
+	})
 	return {
+		role: "writer",
+		replica,
+		deposition() {
+			return state.deposition
+		},
 		async commit(body) {
 			return withGate(core, async function commitBody() {
-				await settleInheritedPending(core, state)
 				const recorded = await recordWithLeases(core, state, body)
 				if (recorded.ops.length === 0) {
 					throw errors.new("commit recorded no ops — an empty transaction names no braid")
@@ -479,7 +829,6 @@ function openWriter<Rels extends SchemaRelations>(replica: Replica<Rels>): Write
 
 		async commitSplit(body) {
 			return withGate(core, async function splitBody() {
-				await settleInheritedPending(core, state)
 				const recorded = await recordWithLeases(core, state, body)
 				if (recorded.ops.length === 0) {
 					throw errors.new("commitSplit recorded no ops — an empty transaction names no braid")
@@ -505,5 +854,17 @@ function openWriter<Rels extends SchemaRelations>(replica: Replica<Rels>): Write
 	}
 }
 
-export type { Batch, BraidOutcome, Commit, CommitSplit, Durability, Writer }
-export { openWriter }
+async function openWriter<Rels extends SchemaRelations>(replica: Replica<Rels>): Promise<Writer<Rels>>
+async function openWriter<Rels extends SchemaRelations>(options: OpenReplicaOptions<Rels>): Promise<Writer<Rels>>
+async function openWriter<Rels extends SchemaRelations>(
+	source: Replica<Rels> | OpenReplicaOptions<Rels>
+): Promise<Writer<Rels>> {
+	if (isReplica(source)) {
+		return writerOn(source)
+	}
+	await birthStore(source.store, source.prefix, digest32FromHex(descriptorOf(source.theory).fingerprint))
+	return writerOn(await openReplica(source))
+}
+
+export type { Batch, BraidOutcome, Commit, CommitSplit, Deposition, Durability, Published, PublishRefusal, Writer }
+export { openWriter, publishCheckpoint }