@bjornpagen/bumbledb-log 0.17.0

package/src/errors.ts

@@ -0,0 +1,150 @@
+/**
+ * The driver's error identities, on the SDK's `@superbuilders/errors`
+ * idiom: exported sentinel values checked with `errors.is`, structured
+ * 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.
+ */
+
+import * as errors from "@superbuilders/errors"
+
+/**
+ * Typed refusal of a protocol object before any apply: batch shape,
+ * version, fingerprint, manifest shape, checkpoint braid-set drift —
+ * one identity, cause data per site.
+ */
+const ErrRefused = errors.new("bumbledb-log refused")
+
+/** `commit` recorded ops in more than one braid; `commitSplit` is the verb. */
+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"
+)
+
+/** The chain discipline, one identity with three proved causes. */
+const ErrChainMismatch = errors.new("bumbledb-log chainMismatch: the batch violates the braid's chain discipline")
+
+/** Bounded live-tip losses exhausted — an operational signal, not an outcome arm. */
+const ErrContention = errors.new("bumbledb-log contention: consecutive live-tip losses exhausted the bound")
+
+/** The vendor channel: I/O and store infrastructure failures. */
+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.
+ */
+type RefusalCause =
+	| { readonly kind: "Truncated"; readonly at: string }
+	| { 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: string }
+	| { 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: "ManifestShape" }
+	| { readonly kind: "ManifestVersion"; readonly version: number }
+	| { readonly kind: "CheckpointShape" }
+	| { readonly kind: "CheckpointBraids"; readonly carried: readonly string[]; readonly derived: readonly string[] }
+	| { readonly kind: "CheckpointDigest"; readonly expected: string; readonly computed: string }
+	| { readonly kind: "NoOpSlot"; readonly braid: string; readonly slot: bigint; readonly writer: bigint }
+
+type ChainCause = "prev" | "slot" | "timestamp"
+
+interface ChainMismatchData {
+	readonly cause: ChainCause
+	readonly braid: string
+	readonly slot: bigint
+	readonly writer: bigint
+}
+
+type ContentionCause =
+	| {
+			readonly kind: "hot-key"
+			readonly statement: string
+			readonly determinants: ReadonlyArray<Readonly<Record<string, unknown>>>
+	  }
+	| { readonly kind: "slot-race"; readonly tip: bigint }
+
+interface ContentionData {
+	readonly braid: string
+	readonly cause: ContentionCause
+}
+
+const refusalData = new WeakMap<Error, RefusalCause>()
+const chainData = new WeakMap<Error, ChainMismatchData>()
+const contentionData = new WeakMap<Error, ContentionData>()
+
+function refuse(cause: RefusalCause, detail: string): never {
+	const error = errors.wrap(ErrRefused, detail)
+	refusalData.set(error, cause)
+	throw error
+}
+
+function refuseChain(data: ChainMismatchData, detail: string): never {
+	const error = errors.wrap(ErrChainMismatch, detail)
+	chainData.set(error, data)
+	throw error
+}
+
+function throwContention(data: ContentionData, detail: string): never {
+	const error = errors.wrap(ErrContention, detail)
+	contentionData.set(error, data)
+	throw error
+}
+
+function refusalOf(error: Error): RefusalCause | undefined {
+	return refusalData.get(error)
+}
+
+function chainMismatchOf(error: Error): ChainMismatchData | undefined {
+	return chainData.get(error)
+}
+
+function contentionOf(error: Error): ContentionData | undefined {
+	return contentionData.get(error)
+}
+
+/** Every store failure wraps the exported sentinel itself, so
+ *  `errors.is(e, ErrStore)` matches by identity; the vendor error's
+ *  message rides the detail verbatim. */
+function wrapStore(inner: Error, detail: string): Error {
+	return errors.wrap(ErrStore, `${detail}: ${inner.message}`)
+}
+
+export type { ChainCause, ChainMismatchData, ContentionCause, ContentionData, RefusalCause }
+export {
+	chainMismatchOf,
+	contentionOf,
+	ErrChainMismatch,
+	ErrContention,
+	ErrGapDetected,
+	ErrRefused,
+	ErrReplayDiverged,
+	ErrSpanningCommit,
+	ErrStore,
+	refusalOf,
+	refuse,
+	refuseChain,
+	throwContention,
+	wrapStore
+}

package/src/index.ts

@@ -0,0 +1,38 @@
+/**
+ * @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`, 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.
+ */
+
+export type { Braid } from "#braids.ts"
+export { braidsOf, serialAtStatementsOf } from "#braids.ts"
+export type { BatchHeader, BatchOp, ChainPosition, DecodedBatch } from "#codec.ts"
+export { decodeBatch, encodeBatch, verifyChain } from "#codec.ts"
+export type { LogDescriptor, LogTheory, SerialStatement } from "#descriptor.ts"
+export { descriptorOf } from "#descriptor.ts"
+export type { ChainCause, ChainMismatchData, ContentionCause, ContentionData, RefusalCause } from "#errors.ts"
+export {
+	chainMismatchOf,
+	contentionOf,
+	ErrChainMismatch,
+	ErrContention,
+	ErrGapDetected,
+	ErrRefused,
+	ErrReplayDiverged,
+	ErrSpanningCommit,
+	ErrStore,
+	refusalOf
+} from "#errors.ts"
+export type { OpenReplicaOptions, Replica } from "#replica.ts"
+export { openReplica } from "#replica.ts"
+export type { Create, Fetched, ObjectStore, Poll, Swap } from "#store.ts"
+export { fsStore } from "#store.ts"
+export type { OpenTenantsOptions, Tenants } from "#tenants.ts"
+export { openTenants } from "#tenants.ts"
+export type { LogInterval, LogValue } from "#value.ts"
+export type { BraidOutcome, Commit, CommitSplit, Durability, LogBatch, Writer } from "#writer.ts"
+export { openWriter } from "#writer.ts"

package/src/keys.ts

@@ -0,0 +1,34 @@
+/**
+ * The key layout (10): generation numbers zero-padded lowercase hex,
+ * 16 chars; a prefix is a store; a tenant is a prefix under `t/`.
+ */
+
+function hex16(g: bigint): string {
+	return g.toString(16).padStart(16, "0")
+}
+
+function manifestKey(prefix: string): string {
+	return `${prefix}/manifest.json`
+}
+
+function logKey(prefix: string, braid: string, g: bigint): string {
+	return `${prefix}/log/${braid}/${hex16(g)}`
+}
+
+function checkpointMdbKey(prefix: string, digest: string): string {
+	return `${prefix}/ckpt/${digest}.mdb`
+}
+
+function checkpointJsonKey(prefix: string, digest: string): string {
+	return `${prefix}/ckpt/${digest}.json`
+}
+
+function idsKey(prefix: string, relation: number, field: number): string {
+	return `${prefix}/ids/${relation.toString(16).padStart(8, "0")}/${field.toString(16).padStart(4, "0")}`
+}
+
+function tenantPrefix(root: string, tenant: string): string {
+	return `${root}/t/${tenant}`
+}
+
+export { checkpointJsonKey, checkpointMdbKey, hex16, idsKey, logKey, manifestKey, tenantPrefix }

package/src/manifest.ts

@@ -0,0 +1,113 @@
+/**
+ * The protocol's one mutable object (10): canonical single-line UTF-8
+ * JSON, strict parse, field order fixed — strictness is proved by
+ * re-rendering the parse and demanding byte equality, so a
+ * non-canonical manifest is a typed refusal, never a tolerated variant.
+ * The checkpoint json beside it is immutable and digest-keyed.
+ */
+
+import * as errors from "@superbuilders/errors"
+import { utf8Encoder, utf8StrictDecoder } from "#bytes.ts"
+import { refuse } from "#errors.ts"
+
+interface Manifest {
+	readonly fingerprint: string
+	readonly checkpoint: string | null
+}
+
+const HEX64 = /^[0-9a-f]{64}$/
+
+function renderManifest(manifest: Manifest): Uint8Array {
+	const checkpoint = manifest.checkpoint === null ? "null" : `"${manifest.checkpoint}"`
+	return utf8Encoder.encode(`{"v":2,"fingerprint":"${manifest.fingerprint}","checkpoint":${checkpoint}}`)
+}
+
+function parseManifest(bytes: Uint8Array): Manifest {
+	const decoded = errors.trySync(function decodeText() {
+		return utf8StrictDecoder.decode(bytes)
+	})
+	if (decoded.error) {
+		refuse({ kind: "ManifestShape" }, "manifest is not UTF-8")
+	}
+	const parsed = errors.trySync(function parseJson() {
+		return JSON.parse(decoded.data) as unknown
+	})
+	if (parsed.error || typeof parsed.data !== "object" || parsed.data === null) {
+		refuse({ kind: "ManifestShape" }, "manifest is not a JSON object")
+	}
+	const record = parsed.data as Record<string, unknown>
+	if (typeof record.v !== "number") {
+		refuse({ kind: "ManifestShape" }, "manifest carries no version")
+	}
+	if (record.v !== 2) {
+		refuse({ kind: "ManifestVersion", version: record.v }, `manifest version ${record.v}, consumers refuse ≠ 2`)
+	}
+	const fingerprint = record.fingerprint
+	const checkpoint = record.checkpoint
+	if (typeof fingerprint !== "string" || !HEX64.test(fingerprint)) {
+		refuse({ kind: "ManifestShape" }, "manifest fingerprint is not 64 hex")
+	}
+	if (checkpoint !== null && (typeof checkpoint !== "string" || !HEX64.test(checkpoint))) {
+		refuse({ kind: "ManifestShape" }, "manifest checkpoint is neither null nor 64 hex")
+	}
+	const manifest: Manifest = { fingerprint, checkpoint: checkpoint === null ? null : checkpoint }
+	const canonical = renderManifest(manifest)
+	if (canonical.length !== bytes.length || utf8StrictDecoder.decode(canonical) !== decoded.data) {
+		refuse({ kind: "ManifestShape" }, "manifest is not the canonical single-line rendering")
+	}
+	return manifest
+}
+
+interface CheckpointHead {
+	readonly g: bigint
+	readonly hash: string
+	readonly ts: bigint
+}
+
+interface CheckpointFacts {
+	readonly braids: ReadonlyMap<string, CheckpointHead>
+	readonly catalog: string
+	readonly writer: bigint
+	readonly prev: string | null
+}
+
+function parseCheckpoint(bytes: Uint8Array): CheckpointFacts {
+	const parsed = errors.trySync(function parseJson() {
+		return JSON.parse(utf8StrictDecoder.decode(bytes)) as unknown
+	})
+	if (parsed.error || typeof parsed.data !== "object" || parsed.data === null) {
+		refuse({ kind: "CheckpointShape" }, "checkpoint json is not an object")
+	}
+	const record = parsed.data as Record<string, unknown>
+	const rawBraids = record.braids
+	if (typeof rawBraids !== "object" || rawBraids === null) {
+		refuse({ kind: "CheckpointShape" }, "checkpoint json carries no braids map")
+	}
+	const braids = new Map<string, CheckpointHead>()
+	for (const [braid, head] of Object.entries(rawBraids as Record<string, unknown>)) {
+		if (typeof head !== "object" || head === null) {
+			refuse({ kind: "CheckpointShape" }, `checkpoint braid ${braid} head is not an object`)
+		}
+		const headRecord = head as Record<string, unknown>
+		const g = headRecord.g
+		const hash = headRecord.hash
+		const ts = headRecord.ts
+		if (typeof g !== "number" || typeof ts !== "number" || typeof hash !== "string" || !HEX64.test(hash)) {
+			refuse({ kind: "CheckpointShape" }, `checkpoint braid ${braid} head is malformed`)
+		}
+		braids.set(braid, { g: BigInt(g), hash, ts: BigInt(ts) })
+	}
+	const catalog = record.catalog
+	const writer = record.writer
+	const prev = record.prev
+	if (typeof catalog !== "string" || !HEX64.test(catalog) || typeof writer !== "number") {
+		refuse({ kind: "CheckpointShape" }, "checkpoint json catalog or writer is malformed")
+	}
+	if (prev !== null && (typeof prev !== "string" || !HEX64.test(prev))) {
+		refuse({ kind: "CheckpointShape" }, "checkpoint json prev is neither null nor a digest")
+	}
+	return { braids, catalog, writer: BigInt(writer), prev: prev === null ? null : prev }
+}
+
+export type { CheckpointFacts, CheckpointHead, Manifest }
+export { parseCheckpoint, parseManifest, renderManifest }