@bjornpagen/bumbledb-log 0.19.2 → 0.20.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bjornpagen/bumbledb-log",
-  "version": "0.19.2",
+  "version": "0.20.0",
   "description": "Braided object-store replication for bumbledb: the command codec, theory-derived braids, and replica/writer over five store verbs",
   "type": "module",
   "exports": {
@@ -37,7 +37,7 @@
     "arkregex": "^0.0.8"
   },
   "peerDependencies": {
-    "@bjornpagen/bumbledb": "^0.19.2"
+    "@bjornpagen/bumbledb": "^0.20.0"
   },
   "devDependencies": {
     "@biomejs/biome": "2.5.4",

package/src/braids.ts

@@ -1,8 +1,10 @@
 /**
- * Braid derivation as data (10): connected components of the statement
- * graph over ordinary relations, the braid id the smallest RelationId in
- * the component rendered `c{id:08x}`. Assignment is a pure function of
- * the descriptor, pinned cross-language by the codec goldens.
+ * Braid derivation as data (10/20): connected components of the
+ * statement graph over ordinary relations, the braid id the smallest
+ * RelationId in the component rendered `c{id:08x}`. The one derivation
+ * lives in `crates/bumbledb-log` and reaches the descriptor parse
+ * through the engine bridge (`internalLogBraidsOf`); this façade names
+ * that derivation in the driver's vocabulary.
  */
 
 import type { Braid, SerialStatement, Theory } from "#descriptor.ts"
@@ -26,8 +28,8 @@ function braidsOf(theory: Theory): ReadonlyMap<string, Braid> {
 /**
  * The degenerate-serial roster (15): key or capacity statements whose
  * determinant projection is empty name one global group, so their braid
- * serializes at that statement. Typed data beside the braid map, one
- * question per verb.
+ * serializes at that statement. The statement ids are the log core's
+ * own roster, read off the descriptor's derivation.
  */
 function serialAtStatementsOf(theory: Theory): readonly SerialStatement[] {
 	return descriptorOf(theory).serialAtStatements

package/src/bytes.ts

@@ -1,19 +1,14 @@
 /**
- * Little-endian byte primitives shared by the codec and the
- * fingerprint mirror, plus the hex grammar every document digest
- * walks. Every multi-byte integer on the batch wire is little-endian;
- * the fingerprint's canonical literal encoding is the engine's
- * big-endian order-preserving form; a digest is 32 bytes, rendered as
- * 64 lowercase hex characters. Integer order and hex width live here
- * so no third spelling can appear.
+ * Byte primitives beside the one grammar: the hex spelling every
+ * document digest walks (32 bytes, 64 lowercase hex characters), the
+ * `Digest32` brand, byte equality, and the u64 arithmetic the vector
+ * and lease algebras share. The wire's own cursors live in
+ * `crates/bumbledb-log`; nothing here reads or writes protocol bytes.
  */
 
 import * as errors from "@superbuilders/errors"
 
 const U64_MAX = 0xffffffffffffffffn
-const I64_MIN = -0x8000000000000000n
-const I64_MAX = 0x7fffffffffffffffn
-const I64_SIGN_BIT = 0x8000000000000000n
 
 const utf8Encoder = new TextEncoder()
 /** Fatal UTF-8. ignoreBOM is true: a leading U+FEFF is a character, not a stripped BOM. */
@@ -22,174 +17,6 @@ const utf8StrictDecoder = new TextDecoder("utf-8", { fatal: true, ignoreBOM: tru
 declare const digest32Brand: unique symbol
 type Digest32 = Uint8Array & { readonly [digest32Brand]: typeof digest32Brand }
 
-class ByteWriter {
-	private buf: Uint8Array
-	private len = 0
-
-	constructor(capacity = 256) {
-		this.buf = new Uint8Array(capacity)
-	}
-
-	private grow(need: number): void {
-		if (this.len + need <= this.buf.length) {
-			return
-		}
-		let capacity = this.buf.length * 2
-		while (capacity < this.len + need) {
-			capacity *= 2
-		}
-		const next = new Uint8Array(capacity)
-		next.set(this.buf.subarray(0, this.len))
-		this.buf = next
-	}
-
-	u8(value: number): void {
-		this.grow(1)
-		this.buf[this.len] = value
-		this.len += 1
-	}
-
-	bytes(raw: Uint8Array): void {
-		this.grow(raw.length)
-		this.buf.set(raw, this.len)
-		this.len += raw.length
-	}
-
-	array32(value: Digest32): void {
-		this.bytes(value)
-	}
-
-	u16le(value: number): void {
-		this.grow(2)
-		this.buf[this.len] = value & 0xff
-		this.buf[this.len + 1] = (value >>> 8) & 0xff
-		this.len += 2
-	}
-
-	u32le(value: number): void {
-		this.grow(4)
-		this.buf[this.len] = value & 0xff
-		this.buf[this.len + 1] = (value >>> 8) & 0xff
-		this.buf[this.len + 2] = (value >>> 16) & 0xff
-		this.buf[this.len + 3] = (value >>> 24) & 0xff
-		this.len += 4
-	}
-
-	u64le(value: bigint): void {
-		if (value < 0n || value > U64_MAX) {
-			throw errors.new(`u64 out of range: ${value}`)
-		}
-		this.grow(8)
-		let v = value
-		for (let i = 0; i < 8; i++) {
-			this.buf[this.len + i] = Number(v & 0xffn)
-			v >>= 8n
-		}
-		this.len += 8
-	}
-
-	i64le(value: bigint): void {
-		if (value < I64_MIN || value > I64_MAX) {
-			throw errors.new(`i64 out of range: ${value}`)
-		}
-		this.u64le(value & U64_MAX)
-	}
-
-	u64be(value: bigint): void {
-		if (value < 0n || value > U64_MAX) {
-			throw errors.new(`u64 out of range: ${value}`)
-		}
-		this.grow(8)
-		let v = value
-		for (let i = 7; i >= 0; i--) {
-			this.buf[this.len + i] = Number(v & 0xffn)
-			v >>= 8n
-		}
-		this.len += 8
-	}
-
-	/** The engine's sign-flipped big-endian i64 (lexicographic = numeric). */
-	i64beFlipped(value: bigint): void {
-		if (value < I64_MIN || value > I64_MAX) {
-			throw errors.new(`i64 out of range: ${value}`)
-		}
-		this.u64be((value & U64_MAX) ^ I64_SIGN_BIT)
-	}
-
-	finish(): Uint8Array {
-		return this.buf.slice(0, this.len)
-	}
-}
-
-interface ReadFailure {
-	fail(what: string): never
-}
-
-class ByteReader {
-	private readonly buf: Uint8Array
-	private pos = 0
-	private readonly refusal: ReadFailure
-
-	constructor(buf: Uint8Array, refusal: ReadFailure) {
-		this.buf = buf
-		this.refusal = refusal
-	}
-
-	remaining(): number {
-		return this.buf.length - this.pos
-	}
-
-	private take(count: number, what: string): Uint8Array {
-		if (this.pos + count > this.buf.length) {
-			this.refusal.fail(what)
-		}
-		const out = this.buf.subarray(this.pos, this.pos + count)
-		this.pos += count
-		return out
-	}
-
-	u8(what: string): number {
-		const raw = this.take(1, what)
-		const byte = raw[0]
-		if (byte === undefined) {
-			this.refusal.fail(what)
-		}
-		return byte
-	}
-
-	bytes(count: number, what: string): Uint8Array {
-		return new Uint8Array(this.take(count, what))
-	}
-
-	array32(what: string): Digest32 {
-		return digest32(this.take(32, what))
-	}
-
-	u16le(what: string): number {
-		const raw = this.take(2, what)
-		return (raw[0] ?? 0) | ((raw[1] ?? 0) << 8)
-	}
-
-	u32le(what: string): number {
-		const raw = this.take(4, what)
-		return (((raw[0] ?? 0) | ((raw[1] ?? 0) << 8) | ((raw[2] ?? 0) << 16)) + (raw[3] ?? 0) * 0x1000000) >>> 0
-	}
-
-	u64le(what: string): bigint {
-		const raw = this.take(8, what)
-		let value = 0n
-		for (let i = 7; i >= 0; i--) {
-			value = (value << 8n) | BigInt(raw[i] ?? 0)
-		}
-		return value
-	}
-
-	i64le(what: string): bigint {
-		const unsigned = this.u64le(what)
-		return unsigned > I64_MAX ? unsigned - (U64_MAX + 1n) : unsigned
-	}
-}
-
 function bytesEqual(a: Uint8Array, b: Uint8Array): boolean {
 	if (a.length !== b.length) {
 		return false
@@ -202,17 +29,6 @@ function bytesEqual(a: Uint8Array, b: Uint8Array): boolean {
 	return true
 }
 
-function bytesCompare(a: Uint8Array, b: Uint8Array): number {
-	const shared = Math.min(a.length, b.length)
-	for (let i = 0; i < shared; i++) {
-		const delta = (a[i] ?? 0) - (b[i] ?? 0)
-		if (delta !== 0) {
-			return delta
-		}
-	}
-	return a.length - b.length
-}
-
 const HEX_DIGITS = "0123456789abcdef"
 
 function hexNibble(byte: number): number | undefined {
@@ -285,17 +101,12 @@ function checkedAddU64(a: bigint, b: bigint): bigint | undefined {
 
 export type { Digest32 }
 export {
-	ByteReader,
-	ByteWriter,
-	bytesCompare,
 	bytesEqual,
 	checkedAddU64,
 	digest32,
 	digest32FromHex,
 	fromHex,
 	hex32,
-	I64_MAX,
-	I64_MIN,
 	saturatingAddU64,
 	toHex,
 	U64_MAX,

package/src/chain.ts

@@ -1,19 +1,21 @@
 /**
- * The chain sidecar in `dir/chain`: a floor cache of chain
- * position, written atomically (temp + rename, fsync). The chain is
- * Settled or Pending — generation is the vector sum, plus one exactly
- * when the value is Pending. The document is a binary v:3 record:
- * version byte 3, counted roster of braid / g / prev / ts, pending
- * tag. Wire pending is the batch bytes. The content address is blake3
- * of those bytes. Every integer is little-endian.
+ * The chain sidecar in `dir/chain`: a floor cache of chain position,
+ * written atomically (temp + rename, fsync). The chain is Settled or
+ * Pending — generation is the vector sum, plus one exactly when the
+ * value is Pending. The byte grammar has one implementation —
+ * `crates/bumbledb-log` behind the napi bridge — so parse and render
+ * are marshal walks over the sealed codec handle; the file IO half
+ * lives here. The content address is blake3 of the rendered bytes.
  */
 
 import * as crypto from "node:crypto"
 import * as fs from "node:fs/promises"
 import * as path from "node:path"
+import type { LogChain, LogCodecHandle, LogSidecarKind } from "@bjornpagen/bumbledb"
+import { internalLogParseSidecar, internalLogRenderSidecar } from "@bjornpagen/bumbledb"
 import * as errors from "@superbuilders/errors"
-import { ByteReader, ByteWriter, saturatingAddU64, U64_MAX } from "#bytes.ts"
-import type { ChainEntry } from "#codec.ts"
+import type { Digest32 } from "#bytes.ts"
+import { digest32, saturatingAddU64, U64_MAX } from "#bytes.ts"
 import type { Braid } from "#descriptor.ts"
 import { braidHex } from "#descriptor.ts"
 import { refuse } from "#errors.ts"
@@ -24,15 +26,17 @@ import { Vector } from "#vector.ts"
 /** The sidecar's file name inside a replica directory. */
 const CHAIN_FILE = "chain"
 
-const VERSION = 3
-const SETTLED = 0
-const PENDING = 1
-/** u32 braid + u64 g + 32 prev + u64 ts. */
-const ENTRY_BYTES = 52n
+/** One braid's chain coordinate: the applied count, the applied
+ *  batch's content address, its timestamp. */
+interface ChainEntry {
+	readonly g: Generation
+	readonly prev: Digest32
+	readonly ts: bigint
+}
 
 interface Pending {
 	readonly braid: Braid
-	readonly gen: Generation
+	readonly slot: Generation
 	readonly bytes: Uint8Array
 }
 
@@ -72,114 +76,66 @@ function chainGeneration(chain: Chain): bigint {
 	return chain.tag === "settled" ? sum : saturatingAddU64(sum, 1n)
 }
 
-/** A declared count the remaining bytes cannot open is Malformed
- *  before the loop. */
-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`)
+/**
+ * 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). The raw braid id of an `UnknownBraid` rides the
+ * message.
+ */
+function refuseBridged(kind: LogSidecarKind, 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 "Malformed":
+			return refuse({ kind: "Malformed", at: bytes.length }, message)
 	}
 }
 
-function renderSidecar(chain: Chain): Uint8Array {
-	const out = new ByteWriter(64)
-	out.u8(VERSION)
-	const braids = [...chain.entries.keys()].sort()
-	if (braids.length > 0xffffffff) {
-		throw errors.new("sidecar chain count exceeds u32")
-	}
-	out.u32le(braids.length)
-	for (const id of braids) {
-		const entry = chain.entries.get(id)
-		if (entry === undefined) {
-			throw errors.new(`sidecar chain lost braid ${id}`)
-		}
-		out.u32le(braidIdOf(id))
-		out.u64le(entry.g)
-		out.bytes(entry.prev)
-		out.u64le(entry.ts)
-	}
-	if (chain.tag === "settled") {
-		out.u8(SETTLED)
-		return out.finish()
-	}
-	out.u8(PENDING)
-	out.u32le(braidIdOf(chain.batch.braid))
-	out.u64le(chain.batch.gen)
-	if (chain.batch.bytes.length > 0xffffffff) {
-		throw errors.new("sidecar pending exceeds u32 length")
-	}
-	out.u32le(chain.batch.bytes.length)
-	out.bytes(chain.batch.bytes)
-	return out.finish()
+function renderSidecar(codec: LogCodecHandle, chain: Chain): Uint8Array {
+	const entries = [...chain.entries.entries()]
+		.sort(function ascending(a, b) {
+			return braidIdOf(a[0]) - braidIdOf(b[0])
+		})
+		.map(function entryOf([id, entry]) {
+			return { braid: braidIdOf(id), g: entry.g, prev: entry.prev, ts: entry.ts }
+		})
+	const doc: LogChain =
+		chain.tag === "settled"
+			? { entries }
+			: {
+					entries,
+					pending: { braid: braidIdOf(chain.batch.braid), slot: chain.batch.slot, bytes: chain.batch.bytes }
+				}
+	return internalLogRenderSidecar(codec, doc)
 }
 
-function parseSidecar(bytes: Uint8Array, known?: ReadonlySet<Braid>): Chain {
-	const reader = new ByteReader(bytes, {
-		fail(what: string): never {
-			refuse({ kind: "Malformed", at: bytes.length }, `sidecar truncated at ${what}`)
-		}
-	})
-	const at = function offset(): number {
-		return bytes.length - reader.remaining()
-	}
-	const version = reader.u8("version")
-	if (version !== VERSION) {
-		refuse({ kind: "Version", version }, `sidecar version ${version}, consumers refuse ≠ ${VERSION}`)
+function parseSidecar(codec: LogCodecHandle, bytes: Uint8Array): Chain {
+	const parsed = internalLogParseSidecar(codec, bytes)
+	if (!parsed.ok) {
+		refuseBridged(parsed.kind, parsed.message, bytes)
 	}
-	const count = BigInt(reader.u32le("chain count"))
-	refuseUnbacked(count, reader.remaining(), ENTRY_BYTES, "chain count")
 	const entries = new Map<Braid, ChainEntry>()
-	let last: Braid | undefined
-	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 }, `sidecar cites unknown braid ${name}`)
-		}
-		const g = reader.u64le("g")
-		const prev = reader.array32("prev")
-		const ts = reader.u64le("ts")
-		if (last !== undefined && last >= name) {
-			refuse({ kind: "Malformed", at: at() }, "sidecar chain is not strictly ascending")
-		}
-		entries.set(name, { g: generation(g), prev, ts })
-		last = name
-	}
-	if (typeof vectorOf(entries).sum() !== "bigint") {
-		refuse({ kind: "Overflow" }, "sidecar chain sum overflows u64")
+	for (const entry of parsed.value.entries) {
+		entries.set(braidHex(entry.braid), { g: generation(entry.g), prev: digest32(entry.prev), ts: entry.ts })
 	}
-	const tag = reader.u8("pending")
-	if (tag === SETTLED) {
-		if (reader.remaining() !== 0) {
-			refuse({ kind: "Malformed", at: reader.remaining() }, `${reader.remaining()} trailing bytes after the sidecar`)
-		}
+	const pending = parsed.value.pending
+	if (pending === undefined) {
 		return { tag: "settled", entries }
 	}
-	if (tag !== PENDING) {
-		refuse({ kind: "Malformed", at: at() - 1 }, `sidecar pending tag ${tag}`)
-	}
-	const raw = reader.u32le("pending braid")
-	const name = braidHex(raw)
-	if (known !== undefined && !known.has(name)) {
-		refuse({ kind: "UnknownBraid", braid: raw }, `sidecar pending cites unknown braid ${name}`)
-	}
-	const slot = reader.u64le("pending generation")
-	const length = reader.u32le("pending length")
-	const body = reader.bytes(length, "pending bytes")
-	if (reader.remaining() !== 0) {
-		refuse({ kind: "Malformed", at: reader.remaining() }, `${reader.remaining()} trailing bytes after the sidecar`)
-	}
 	return {
 		tag: "pending",
 		entries,
-		batch: { braid: name, gen: generation(slot), bytes: body }
+		batch: { braid: braidHex(pending.braid), slot: generation(pending.slot), bytes: pending.bytes }
 	}
 }
 
-async function readSidecar(file: string, known?: ReadonlySet<Braid>): Promise<SidecarRead> {
+async function readSidecar(codec: LogCodecHandle, file: string): Promise<SidecarRead> {
 	const read = await errors.try(fs.readFile(file))
 	if (read.error) {
 		if (codeOf(read.error) === "ENOENT") {
@@ -188,7 +144,7 @@ async function readSidecar(file: string, known?: ReadonlySet<Braid>): Promise<Si
 		return { tag: "fault", io: read.error }
 	}
 	const parsed = errors.trySync(function parse() {
-		return parseSidecar(read.data, known)
+		return parseSidecar(codec, read.data)
 	})
 	if (parsed.error) {
 		return { tag: "corrupt", parse: parsed.error }
@@ -196,14 +152,14 @@ async function readSidecar(file: string, known?: ReadonlySet<Braid>): Promise<Si
 	return { tag: "read", chain: parsed.data }
 }
 
-async function writeSidecar(file: string, chain: Chain): Promise<void> {
+async function writeSidecar(codec: LogCodecHandle, file: string, chain: Chain): Promise<void> {
 	const dir = path.dirname(file)
 	await fs.mkdir(dir, { recursive: true })
 	const temp = path.join(dir, `.chain-${process.pid}-${crypto.randomBytes(4).toString("hex")}`)
 	const handle = await fs.open(temp, "wx")
 	const written = await errors.try(
 		(async function writeAll() {
-			await handle.writeFile(renderSidecar(chain))
+			await handle.writeFile(renderSidecar(codec, chain))
 			await handle.sync()
 		})()
 	)
@@ -221,5 +177,5 @@ async function writeSidecar(file: string, chain: Chain): Promise<void> {
 	}
 }
 
-export type { Chain, ChainEntry, Pending, SidecarRead }
+export type { Chain, ChainEntry, Pending }
 export { CHAIN_FILE, chainGeneration, chainSum, parseSidecar, readSidecar, renderSidecar, writeSidecar }