@bjornpagen/bumbledb-log 0.19.2 → 0.20.0

package/src/errors.ts

@@ -4,10 +4,13 @@
  * causes carried as data properties read back with the `*Of` accessors —
  * never by message-string matching. There is deliberately no
  * `ErrAlreadyApplied`: the state it would name is absorbed by idempotent
- * replay (L10) and never surfaces. ManifestMissing, Ambiguous, OverWidth,
- * Exhausted, and SlotRetired are named sums of their own: a replica
- * without a manifest, an unproved conditional write, a draw past the
- * lease width or the u64 ceiling, and a below-floor create.
+ * replay (L10) and never surfaces. ManifestMissing, OverWidth,
+ * RefillNeeded, Exhausted, and SlotRetired are named sums of their own: a
+ * replica without a manifest, a draw past the lease width, a cached id
+ * block too short for the draw, the u64 ceiling, and a below-floor
+ * create. Exhaustion means the id space is spent — a refill is never an
+ * exhaustion. An unproved conditional write is the store verbs' own
+ * `ambiguous` outcome arm, never an error identity.
  */
 
 import * as errors from "@superbuilders/errors"
@@ -26,9 +29,6 @@ const ErrSpanningCommit = errors.new(
 	"bumbledb-log spanningCommit: the recorded ops span braids — commitSplit is the explicit verb"
 )
 
-/** 404 at or below the current checkpoint's vector: the tail was gc'd. */
-const ErrGapDetected = errors.new("bumbledb-log gapDetected: the log tail below the checkpoint vector was collected")
-
 /** A rejected replay on a store that passed the wholeness check. */
 const ErrReplayDiverged = errors.new(
 	"bumbledb-log replayDiverged: a published batch rejected during steady-state replay"
@@ -43,16 +43,16 @@ const ErrContention = errors.new("bumbledb-log contention: consecutive live-tip
 /** A replica (or any read-role handle) found no manifest; only the writer births a store. */
 export const ErrManifestMissing = errors.new("bumbledb-log manifestMissing: the store has no manifest")
 
-/**
- * A conditional write the transport cannot prove (S3 409, timeout, a
- * retried PUT). The machine GET-verifies; this identity is the unproved
- * arm, never a proved Exists or Moved.
- */
-const ErrAmbiguous = errors.new("bumbledb-log ambiguous: the conditional write is unproved")
-
 /** A single id draw larger than one lease width; the width is the one block size. */
 const ErrOverWidth = errors.new("bumbledb-log overWidth: the draw exceeds the lease width")
 
+/**
+ * The cached id block is too short for the draw — the writer's signal
+ * to lease a fresh block. A refill is not an exhaustion: the id space
+ * still has room; only the cache is short.
+ */
+const ErrRefillNeeded = errors.new("bumbledb-log refillNeeded: the cached id block cannot cover the draw")
+
 /** The next lease would leave u64 — the id space is spent. */
 const ErrExhausted = errors.new("bumbledb-log exhausted: the id space is spent")
 
@@ -63,34 +63,61 @@ const ErrSlotRetired = errors.new("bumbledb-log slotRetired: the slot is retired
 const ErrStore = errors.new("bumbledb-log store failure")
 
 /**
- * Decode refusal kinds carry the cross-implementation identity names the
- * Rust driver's `DecodeError::identity` pins — the conformance corpus
- * compares them string for string. The tail kinds are this driver's own
- * replica-boundary refusals.
+ * The typed causes behind `ErrRefused`, one arm per identity. Every
+ * `kind` is either a row of the generated identity table
+ * (`crates/bumbledb-log/conformance/v3/identities.json`, spelled by the
+ * core's one speller per family) or one of the three host-side kinds at
+ * the tail, which cross no bridge. The boundary carries
+ * `{ kind, message }` only, so a bridge-minted cause is the bare kind —
+ * the detail rides the message — and a payload field exists only where
+ * the minting seat owns the datum: a held document's version byte
+ * (`version`, byte 0 of every v:3 document) and length (`at`), the
+ * codec seat's own arity coordinates, the manifest audit's
+ * fingerprints, the counter object's key. The raw id of an
+ * `UnknownBraid` rides the message.
  */
 type RefusalCause =
-	| { readonly kind: "Truncated"; readonly at: string }
+	// The batch grammar's rows (`batchDecode` | `batchEncode`), bridge
+	// order. `Version` carries the version byte where a document seat
+	// holds the bytes; `FingerprintMismatch` carries both digests where
+	// the replica's manifest audit owns them; `Arity` carries its
+	// coordinates where the codec seat's pre-bridge cell gate owns them.
+	| { readonly kind: "Truncated" }
 	| { readonly kind: "BadMagic" }
-	| { readonly kind: "Version"; readonly version: number }
-	| { readonly kind: "Flags"; readonly flags: number }
-	| { readonly kind: "FingerprintMismatch"; readonly carried: string; readonly expected: string }
-	| { readonly kind: "UnknownBraid"; readonly braid: number }
-	| { readonly kind: "UnknownOpKind"; readonly op: number; readonly opKind: number }
-	| { readonly kind: "UnknownRelation"; readonly op: number; readonly relation: number }
-	| { readonly kind: "ClosedRelation"; readonly op: number; readonly relation: number }
-	| { readonly kind: "OpRelationOutsideBraid"; readonly op: number; readonly relation: number; readonly braid: Braid }
-	| { readonly kind: "TagMismatch"; readonly relation: string; readonly row: number; readonly field: string }
-	| { readonly kind: "BoolByte"; readonly relation: string; readonly row: number; readonly field: string }
-	| { readonly kind: "InvalidUtf8"; readonly relation: string; readonly row: number; readonly field: string }
-	| { readonly kind: "EmptyInterval"; readonly relation: string; readonly row: number; readonly field: string }
-	| { readonly kind: "IntervalOverflow"; readonly relation: string; readonly row: number; readonly field: string }
-	| { readonly kind: "TrailingBytes"; readonly bytes: number }
-	| { readonly kind: "DigestWidth" }
-	| { readonly kind: "Arity"; readonly op: number; readonly relation: string; readonly row: number }
+	| { readonly kind: "Version"; readonly version?: number }
+	| { readonly kind: "Flags" }
+	| { readonly kind: "FingerprintMismatch"; readonly carried?: string; readonly expected?: string }
+	| { readonly kind: "UnknownBraid" }
+	| { readonly kind: "UnknownOpKind" }
+	| { readonly kind: "UnknownRelation" }
+	| { readonly kind: "ClosedRelation" }
+	| { readonly kind: "OpRelationOutsideBraid" }
+	| { readonly kind: "TagMismatch" }
+	| { readonly kind: "BoolByte" }
+	| { readonly kind: "InvalidUtf8" }
+	| { readonly kind: "EmptyInterval" }
+	| { readonly kind: "IntervalOverflow" }
+	| { readonly kind: "TrailingBytes" }
+	| { readonly kind: "Arity"; readonly op?: number; readonly relation?: string; readonly row?: number }
+	| { readonly kind: "Value" }
+	| { readonly kind: "TooManyOps" }
+	| { readonly kind: "TooManyRows" }
+	// The document grammars' own rows (`manifest` | `checkpoint` |
+	// `sidecar`): the seat holds the refused bytes, so `Malformed`
+	// carries the document's length.
 	| { readonly kind: "Malformed"; readonly at: number }
 	| { readonly kind: "Overflow" }
-	| { readonly kind: "ManifestVersion"; readonly version: number }
-	| { readonly kind: "CheckpointBraids"; readonly carried: readonly string[]; readonly derived: readonly string[] }
+	| { readonly kind: "BraidSet" }
+	// The id-lease counter's row (`counter`): the writer's parse gate
+	// owns the counter object's key. `Exhausted` and `OverWidth` are
+	// `LeaseRefusal` arms with sentinels of their own.
+	| { readonly kind: "Counter"; readonly key: StoreKey }
+	// Host-side kinds with no table row: `DigestWidth` refuses a short
+	// digest at the seat before a value crosses corrupted (the corpus
+	// pins the name); `CheckpointDigest` and `NoOpSlot` are the replica
+	// machine's own refusals — the machines keep two executors and no
+	// bridge family.
+	| { readonly kind: "DigestWidth" }
 	| { readonly kind: "CheckpointDigest"; readonly expected: string; readonly computed: string }
 	| { readonly kind: "NoOpSlot"; readonly braid: Braid; readonly slot: Generation; readonly writer: bigint }
 
@@ -116,14 +143,13 @@ interface ContentionData {
 	readonly cause: ContentionCause
 }
 
-type AmbiguousVerb = "create" | "swap"
-
-interface AmbiguousData {
-	readonly verb: AmbiguousVerb
-	readonly key: StoreKey
+interface OverWidthData {
+	readonly requested: bigint
 }
 
-interface OverWidthData {
+interface RefillNeededData {
+	readonly relation: number
+	readonly field: number
 	readonly requested: bigint
 }
 
@@ -137,16 +163,21 @@ interface SlotRetiredData {
 	readonly slot: Generation
 }
 
-/** The id-lease algebra's refusal arms: OverWidth | Exhausted. */
+/** The id-lease algebra's refusal sum — the identity table's `counter`
+ *  family, arm for arm: Counter | Exhausted | OverWidth. `Counter`
+ *  carries the counter object's key, the datum this driver's parse gate
+ *  owns (the core's twin carries relation and field). A cache refill is
+ *  no arm: the shared algebra has none. */
 type LeaseRefusal =
-	| { readonly kind: "OverWidth"; readonly requested: bigint }
+	| { readonly kind: "Counter"; readonly key: StoreKey }
 	| { readonly kind: "Exhausted"; readonly relation: number; readonly field: number }
+	| { readonly kind: "OverWidth"; readonly requested: bigint }
 
 const refusalData = new WeakMap<Error, RefusalCause>()
 const chainData = new WeakMap<Error, ChainMismatchData>()
 const contentionData = new WeakMap<Error, ContentionData>()
-const ambiguousData = new WeakMap<Error, AmbiguousData>()
 const overWidthData = new WeakMap<Error, OverWidthData>()
+const refillNeededData = new WeakMap<Error, RefillNeededData>()
 const exhaustedData = new WeakMap<Error, ExhaustedData>()
 const slotRetiredData = new WeakMap<Error, SlotRetiredData>()
 
@@ -176,18 +207,18 @@ function isManifestMissing(error: unknown): boolean {
 	return error instanceof Error && errors.is(error, ErrManifestMissing)
 }
 
-function throwAmbiguous(data: AmbiguousData, detail: string): never {
-	const error = errors.wrap(ErrAmbiguous, detail)
-	ambiguousData.set(error, data)
-	throw error
-}
-
 function refuseOverWidth(data: OverWidthData, detail: string): never {
 	const error = errors.wrap(ErrOverWidth, detail)
 	overWidthData.set(error, data)
 	throw error
 }
 
+function throwRefillNeeded(data: RefillNeededData, detail: string): never {
+	const error = errors.wrap(ErrRefillNeeded, detail)
+	refillNeededData.set(error, data)
+	throw error
+}
+
 function refuseExhausted(data: ExhaustedData, detail: string): never {
 	const error = errors.wrap(ErrExhausted, detail)
 	exhaustedData.set(error, data)
@@ -212,14 +243,14 @@ function contentionOf(error: Error): ContentionData | undefined {
 	return contentionData.get(error)
 }
 
-function ambiguousOf(error: Error): AmbiguousData | undefined {
-	return ambiguousData.get(error)
-}
-
 function overWidthOf(error: Error): OverWidthData | undefined {
 	return overWidthData.get(error)
 }
 
+function refillNeededOf(error: Error): RefillNeededData | undefined {
+	return refillNeededData.get(error)
+}
+
 function exhaustedOf(error: Error): ExhaustedData | undefined {
 	return exhaustedData.get(error)
 }
@@ -236,8 +267,6 @@ function wrapStore(inner: Error, detail: string): Error {
 }
 
 export type {
-	AmbiguousData,
-	AmbiguousVerb,
 	ChainCause,
 	ChainMismatchData,
 	ContentionCause,
@@ -245,19 +274,18 @@ export type {
 	ExhaustedData,
 	LeaseRefusal,
 	OverWidthData,
+	RefillNeededData,
 	RefusalCause,
 	SlotRetiredData
 }
 export {
-	ambiguousOf,
 	chainMismatchOf,
 	contentionOf,
-	ErrAmbiguous,
 	ErrChainMismatch,
 	ErrContention,
 	ErrExhausted,
-	ErrGapDetected,
 	ErrOverWidth,
+	ErrRefillNeeded,
 	ErrRefused,
 	ErrReplayDiverged,
 	ErrSlotRetired,
@@ -266,6 +294,7 @@ export {
 	exhaustedOf,
 	isManifestMissing,
 	overWidthOf,
+	refillNeededOf,
 	refusalOf,
 	refuse,
 	refuseChain,
@@ -274,7 +303,7 @@ export {
 	refuseOverWidth,
 	refuseSlotRetired,
 	slotRetiredOf,
-	throwAmbiguous,
 	throwContention,
+	throwRefillNeeded,
 	wrapStore
 }

package/src/index.ts

@@ -1,11 +1,15 @@
 /**
  * @bjornpagen/bumbledb-log — braided object-store replication for
- * bumbledb, a thin peer of the engine SDK. Public surface: the pure
- * protocol pair (`encodeBatch`/`decodeBatch`, `braidsOf`) mirrored
- * byte-exactly against the Rust driver, the five-verb object store
- * with its tier-1 `fsStore`, in-process `memStore`, and the `s3Store` AWS S3 client, and `openReplica`/`openWriter`/
- * `openTenants` composed from the engine SDK's own verbs — the replica
- * hands out the SDK's `Db`, and no engine surface is duplicated.
+ * bumbledb, a thin peer of the engine SDK. The protocol grammar has one
+ * implementation, `crates/bumbledb-log`, reached through the engine
+ * bridge; this package is typed payload construction, the replica and
+ * writer machines, the five-verb object store with its tier-1 `fsStore`,
+ * in-process `memStore`, and the `s3Store` AWS S3 client, and
+ * `openReplica`/`openWriter`/`openTenants` composed from the engine
+ * SDK's own verbs — the replica hands out the SDK's `Db`, and no engine
+ * surface is duplicated. Engine types (`FactValue`, `IntervalValue`, …)
+ * are the peer `@bjornpagen/bumbledb`'s own exports, never re-exported
+ * here.
  */
 
 export type { Braid } from "#braids.ts"
@@ -20,7 +24,6 @@ export {
 	contentionOf,
 	ErrChainMismatch,
 	ErrContention,
-	ErrGapDetected,
 	ErrManifestMissing,
 	ErrRefused,
 	ErrReplayDiverged,
@@ -30,24 +33,25 @@ export {
 	refusalOf
 } from "#errors.ts"
 export type { Generation, StoreKey } from "#keys.ts"
-export {
-	CKPT_SCRATCH_LEASE,
-	encodeCkptScratch,
-	generation,
-	LEASE_NAMESPACE,
-	parseCkptScratch,
-	scratchCkptDigest,
-	scratchCkptName,
-	storeKey
-} from "#keys.ts"
-export type { OpenReplicaOptions, Replica } from "#replica.ts"
+export { generation, storeKey } from "#keys.ts"
+export type { OpenReplicaOptions, Replica, Waited } from "#replica.ts"
 export { openReplica } from "#replica.ts"
 export type { Create, Etag, Fetched, ObjectStore, Poll, S3Config, S3Credentials, Swap } from "#store.ts"
 export { etag, fsStore, memStore, s3Store } from "#store.ts"
 export type { OpenTenantsOptions, Tenants } from "#tenants.ts"
 export { openTenants } from "#tenants.ts"
-export type { Interval, Value } from "#value.ts"
-export type { CheckpointOrder, VectorParse } from "#vector.ts"
+export type { CheckpointOrder } from "#vector.ts"
 export { Overflow, Vector } from "#vector.ts"
-export type { Batch, BraidOutcome, Commit, CommitSplit, Durability, Writer } from "#writer.ts"
+export type {
+	Batch,
+	BraidOutcome,
+	Commit,
+	CommitReceipt,
+	CommitSplit,
+	Deposition,
+	Durability,
+	EmptyCommit,
+	Landing,
+	Writer
+} from "#writer.ts"
 export { openWriter } from "#writer.ts"

package/src/keys.ts

@@ -4,46 +4,61 @@
  * StoreKey is parsed here, once — the verbs take the proof and never
  * re-check. An empty prefix joins as the rest alone, so a leading
  * slash is unrepresentable. Temps and leases live under a reserved
- * tilde-family first segment no StoreKey can spell — ASCII `~` and
- * its lookalikes — so those namespaces stay disjoint from every
- * honest key. Format characters, line and paragraph separators, and
- * space separators cannot hide a reserved prefix or a `.lock` suffix.
+ * tilde-family first segment no StoreKey can spell — the generated
+ * table under `conformance/v3/keys/` is the set, read at module init
+ * — so those namespaces stay disjoint from every honest key. Format
+ * characters, line and paragraph separators, and space separators
+ * cannot hide a reserved prefix or a `.lock` suffix: a segment
+ * containing one is refused outright.
  */
 
+import * as fs from "node:fs"
+import { internalLogParseCkptScratch, internalLogRenderCkptScratch } from "@bjornpagen/bumbledb"
 import * as errors from "@superbuilders/errors"
 import { regex } from "arkregex"
 import type { Digest32 } from "#bytes.ts"
 import { digest32, hex32, U64_MAX } from "#bytes.ts"
 import type { Braid } from "#descriptor.ts"
 
-/** A segment wearing this suffix — after format characters are stripped — is not a key. */
+/** A segment wearing this suffix is not a key. */
 const LOCK_SUFFIX = ".lock"
 
 /** Reserved first-segment names no StoreKey can spell. Temps and leases live here. */
 const TEMP_NAMESPACE = "~tmp"
 const LEASE_NAMESPACE = "~lease"
 
-/** ASCII tilde and lookalikes that can spell a reserved first segment. */
-const TILDE_FAMILY = new Set([
-	"~",
-	"\u02DC",
-	"\u02F7",
-	"\u1FC0",
-	"\u2053",
-	"\u223C",
-	"\u223D",
-	"\u223F",
-	"\u2E1E",
-	"\u2E1F",
-	"\u301C",
-	"\u3030",
-	"\uFE4B",
-	"\uFE4F",
-	"\uFF5E"
-])
+/** The one tilde table both drivers consume: ASCII `~`, its lookalikes, and the NFKC preimage of U+007E. */
+const TILDE_TABLE_URL = new URL("../../crates/bumbledb-log/conformance/v3/keys/tilde-family.json", import.meta.url)
+
+const CODE_POINT_SPELLING = regex("^U\\+[0-9A-F]{4,6}$")
+
+function loadTildeFamily(): Set<string> {
+	const raw = fs.readFileSync(TILDE_TABLE_URL, "utf8")
+	const table: unknown = JSON.parse(raw)
+	if (typeof table !== "object" || table === null || !("codePoints" in table)) {
+		throw errors.new(`tilde table is not a codePoints document: ${TILDE_TABLE_URL.pathname}`)
+	}
+	const { codePoints } = table
+	if (!Array.isArray(codePoints) || codePoints.length === 0) {
+		throw errors.new(`tilde table codePoints is not a nonempty array: ${TILDE_TABLE_URL.pathname}`)
+	}
+	const family = new Set<string>()
+	for (const spelling of codePoints) {
+		if (typeof spelling !== "string" || !CODE_POINT_SPELLING.test(spelling)) {
+			throw errors.new(`tilde table entry is not a U+XXXX code point: ${String(spelling)}`)
+		}
+		family.add(String.fromCodePoint(Number.parseInt(spelling.slice(2), 16)))
+	}
+	if (!family.has("~")) {
+		throw errors.new(`tilde table does not reserve ASCII tilde: ${TILDE_TABLE_URL.pathname}`)
+	}
+	return family
+}
+
+/** First-segment code points that spell a reserved name. The table is the set; no local spelling. */
+const TILDE_FAMILY = loadTildeFamily()
 
 const FORMAT_OR_SEPARATOR = regex("[\\p{Cc}\\p{Cf}\\p{Zl}\\p{Zp}\\p{Zs}]", "u")
-const FORMAT_CHARS = regex("\\p{Cf}", "gu")
 const SLASH_TRIM = regex("^/+|/+$", "g")
 
 declare const storeKeyBrand: unique symbol
@@ -64,11 +79,7 @@ function tildeFamilyPrefix(seg: string): boolean {
 	if (first === undefined) {
 		return false
 	}
-	return TILDE_FAMILY.has(first) || first.normalize("NFKC") === "~"
-}
-
-function stripFormat(seg: string): string {
-	return seg.replace(FORMAT_CHARS, "")
+	return TILDE_FAMILY.has(first)
 }
 
 /** One path segment of a key or a tenant id: the same grammar. */
@@ -79,11 +90,7 @@ function segmentOk(seg: string): boolean {
 	if (FORMAT_OR_SEPARATOR.test(seg)) {
 		return false
 	}
-	const stripped = stripFormat(seg)
-	if (stripped.length === 0 || stripped === "." || stripped === "..") {
-		return false
-	}
-	return !tildeFamilyPrefix(stripped) && !stripped.endsWith(LOCK_SUFFIX)
+	return !tildeFamilyPrefix(seg) && !seg.endsWith(LOCK_SUFFIX)
 }
 
 function storeKey(raw: string): StoreKey {
@@ -102,10 +109,6 @@ function parsePrefix(raw: string): string {
 	return storeKey(raw.replace(SLASH_TRIM, ""))
 }
 
-function isReservedName(name: string): boolean {
-	return tildeFamilyPrefix(stripFormat(name))
-}
-
 function reservedTemp(pid: number, seq: number): string {
 	return `${TEMP_NAMESPACE}/${String(pid)}.${String(seq)}`
 }
@@ -135,30 +138,19 @@ function scratchCkptName(): string {
 	return reservedName(`${LEASE_NAMESPACE}/${CKPT_SCRATCH_LEASE}`)
 }
 
-const SCRATCH_VERSION = 3
-
-/** The scratch-lease body: version byte 3, then the 32-byte digest. */
+/** The scratch-lease body, spelled by the one grammar (`crates/bumbledb-log`). */
 function encodeCkptScratch(digest: Digest32): Uint8Array {
-	const out = new Uint8Array(33)
-	out[0] = SCRATCH_VERSION
-	out.set(digest, 1)
-	return out
+	return internalLogRenderCkptScratch(digest)
 }
 
-/** The digest a scratch-lease body names, or null. */
-function scratchCkptDigest(bytes: Uint8Array): Digest32 | null {
-	if (bytes.length !== 33) {
-		return null
-	}
-	const version = bytes[0]
-	if (version !== SCRATCH_VERSION) {
+/** The digest a scratch-lease body names, or null — the one grammar's
+ *  parse, branded; the refusal is undifferentiated by law. */
+function parseCkptScratch(bytes: Uint8Array): Digest32 | null {
+	const named = internalLogParseCkptScratch(bytes)
+	if (named === null) {
 		return null
 	}
-	return digest32(bytes.subarray(1))
-}
-
-function parseCkptScratch(bytes: Uint8Array): Digest32 | null {
-	return scratchCkptDigest(bytes)
+	return digest32(named)
 }
 
 function generation(raw: bigint): Generation {
@@ -210,11 +202,8 @@ export {
 	ckptDocKey,
 	encodeCkptScratch,
 	generation,
-	hex16,
 	idsKey,
-	isReservedName,
 	LEASE_NAMESPACE,
-	LOCK_SUFFIX,
 	logKey,
 	manifestKey,
 	parseCkptScratch,
@@ -222,9 +211,7 @@ export {
 	reservedLease,
 	reservedName,
 	reservedTemp,
-	scratchCkptDigest,
 	scratchCkptName,
-	segmentOk,
 	storeKey,
 	TEMP_NAMESPACE,
 	tenantPrefix