@bjornpagen/bumbledb-log 0.17.0 → 0.18.0

package/README.md

@@ -1,8 +1,8 @@
 # @bjornpagen/bumbledb-log
 
 Braided object-store replication for [bumbledb](https://github.com/bjornpagen/bumbledb):
-a thin peer of `@bjornpagen/bumbledb` (peer dependency, 0.17.x lockstep).
-The package is three things:
+a thin peer of `@bjornpagen/bumbledb` (peer `^0.18.0`). The package is
+three things:
 
 1. **The mirrored pure pair**, byte-exact against the Rust driver and
    pinned by cross-language goldens: `encodeBatch`/`decodeBatch` (the
@@ -10,20 +10,30 @@ The package is three things:
    `braidsOf(descriptor)` (the schema's own shard map, as data — with
    `serialAtStatementsOf` naming the degenerate-serial statements beside it).
 2. **The five-verb object store** — `get`, `getIfChanged`, `putCreate`,
-   `putSwap`, `delete` — with `fsStore` as the tier-1 local-directory
-   implementation (deployment case 5's production backend, not a dev
-   double). The S3/R2/OCI store rides `aws4fetch` and is not yet in this
-   build (the dependency was unfetchable offline).
+   `putSwap`, `delete` — taking a branded `StoreKey` parsed once by
+   `storeKey`. `fsStore` is the tier-1 local-directory implementation;
+   `memStore` is the same five verbs over one in-process map
+   (single-process only; third `Etag` producer, blake3 like `fsStore`);
+   `s3Store` is the five verbs over S3-compatible storage (the official
+   `@aws-sdk/client-s3` client signs and talks; R2 rides region `auto`).
 3. **Replica and writer** composed from the engine SDK's existing verbs:
    `openReplica` hands out the SDK's own `Db`; `openWriter` adds the
    right to create log objects; `openTenants` is an LRU of per-tenant
    replicas. No engine surface is duplicated.
 
+The package `engines` and the `.ts` test runner require Node >=24.
+
+The exported vocabulary reads as English at the call site: `Value`,
+`Interval`, `Batch`, `Theory`, `Descriptor`, `Op`, `Pending`,
+`ChainEntry`, plus the branded scalars `StoreKey`, `Generation`,
+`Etag`, and `Braid` (`storeKey`, `generation`, `etag`, `braid` parse
+at the boundary; the verbs take the proof).
+
 Async ⟺ network: `openReplica`, `refresh`, `waitFor`, `commit`,
 `commitSplit`, and disposal await store verbs; everything on
 `replica.db`, the `batch.*` recorders, and the pure pair are synchronous.
 
-## The Vercel recipe (documented example, not framework code)
+## A Fluid host
 
 ```ts
 // lib/db.ts — module scope; Fluid shares this across the instance's requests
@@ -33,7 +43,7 @@ export const replica = await openReplica({ store: s3(env), prefix: "prod/main",
 export const writer = openWriter(replica)
 
 // route handler
-const out = await writer.commit((b) => b.insert(Booking, [row]))
+const out = await writer.commit((batch) => batch.insert(Booking, [row]))
 if (out.tag === "accepted") ctx.waitUntil(replica.refresh(out.braid))
 ```
 
@@ -42,7 +52,7 @@ if (out.tag === "accepted") ctx.waitUntil(replica.refresh(out.braid))
   leaf-blob pattern keeps metadata stores in the tens of MB. Per-tenant
   fleets get the same gate through `openTenants({ budgetBytes, maxOpen })`.
 - **Cross-instance read-your-writes**: a commit returns
-  `(braid, generation)`; a session token is the pointwise max of every
+  `{ braid, generation }`; a session token is the pointwise max of every
   pair a flow has seen; `replica.waitFor(vector)` refreshes until the
   local vector dominates it. The committing instance always reads its
   own writes without waiting. A singleton map is the single-braid form.
@@ -54,15 +64,12 @@ if (out.tag === "accepted") ctx.waitUntil(replica.refresh(out.braid))
   row — the schema idiom) or resident mode. `{ kind: "slot-race", tip }`
   means the terminal losses were accepted but out-raced: an operational
   signal to shard the theory into more braids or move the hot braid to
-  a resident Rust writer, whose group commit batches the queue. This
-  package ships no group commit of its own; the recorded reopen trigger
-  is a measured TS deployment at Turso-density write rates where a
-  deliberate batching delay would amortize many writers into one PUT.
+  a resident Rust writer, whose group commit batches the queue.
 
-## The local-fleet recipe (deployment case 5)
+## A local fleet
 
 ```ts
-// one process per scope loop; all processes share one FsStore prefix
+// one process per scope loop; all processes share one fsStore prefix
 import { fsStore, openReplica, openWriter } from "@bjornpagen/bumbledb-log"
 
 const replica = await openReplica({

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bjornpagen/bumbledb-log",
-  "version": "0.17.0",
+  "version": "0.18.0",
   "description": "Braided object-store replication for bumbledb: the command codec, theory-derived braids, and replica/writer over five store verbs",
   "type": "module",
   "exports": {
@@ -32,10 +32,11 @@
   },
   "homepage": "https://github.com/bjornpagen/bumbledb#readme",
   "dependencies": {
+    "@aws-sdk/client-s3": "^3.1116.0",
     "@superbuilders/errors": "^4.0.2"
   },
   "peerDependencies": {
-    "@bjornpagen/bumbledb": "^0.17.1"
+    "@bjornpagen/bumbledb": "^0.18.0"
   },
   "devDependencies": {
     "@biomejs/biome": "2.5.4",

package/src/braids.ts

@@ -5,14 +5,11 @@
  * the descriptor, pinned cross-language by the codec goldens.
  */
 
-import type { LogTheory, SerialStatement } from "#descriptor.ts"
-import { descriptorOf } from "#descriptor.ts"
-
-/** Braid id: `c{smallest RelationId:08x}`, scoped to the schema fingerprint. */
-type Braid = string
+import type { Braid, SerialStatement, Theory } from "#descriptor.ts"
+import { braid, descriptorOf } from "#descriptor.ts"
 
 /** The schema's own shard map: ordinary relation name → braid id. */
-function braidsOf(theory: LogTheory): ReadonlyMap<string, Braid> {
+function braidsOf(theory: Theory): ReadonlyMap<string, Braid> {
 	const descriptor = descriptorOf(theory)
 	const out = new Map<string, Braid>()
 	for (const relation of descriptor.relations) {
@@ -30,9 +27,9 @@ function braidsOf(theory: LogTheory): ReadonlyMap<string, Braid> {
  * serializes at that statement. Typed data beside the braid map, one
  * question per verb.
  */
-function serialAtStatementsOf(theory: LogTheory): readonly SerialStatement[] {
+function serialAtStatementsOf(theory: Theory): readonly SerialStatement[] {
 	return descriptorOf(theory).serialAtStatements
 }
 
 export type { Braid }
-export { braidsOf, serialAtStatementsOf }
+export { braid, braidsOf, serialAtStatementsOf }

package/src/bytes.ts

@@ -1,6 +1,6 @@
 /**
- * Little-endian byte primitives shared by the codec, the footprint keys,
- * and the fingerprint mirror. Every multi-byte integer on the batch wire
+ * Little-endian byte primitives shared by the codec and the
+ * fingerprint mirror. 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 — both live here so no third
  * spelling can appear.

package/src/chain.ts

@@ -12,22 +12,21 @@ import * as fs from "node:fs/promises"
 import * as path from "node:path"
 import * as errors from "@superbuilders/errors"
 import { utf8StrictDecoder } from "#bytes.ts"
+import type { ChainEntry } from "#codec.ts"
+import type { Braid } from "#descriptor.ts"
+import { braid } from "#descriptor.ts"
+import type { Generation } from "#keys.ts"
+import { generation } from "#keys.ts"
 
-interface ChainEntry {
-	readonly g: bigint
-	readonly prev: string
-	readonly ts: bigint
-}
-
-interface PendingBatch {
-	readonly braid: string
-	readonly gen: bigint
+interface Pending {
+	readonly braid: Braid
+	readonly gen: Generation
 	readonly bytes: Uint8Array
 }
 
 interface Sidecar {
-	readonly chain: ReadonlyMap<string, ChainEntry>
-	readonly pending: PendingBatch | null
+	readonly chain: ReadonlyMap<Braid, ChainEntry>
+	readonly pending: Pending | null
 }
 
 function renderSidecar(sidecar: Sidecar): string {
@@ -57,16 +56,16 @@ function parseSidecar(text: string): Sidecar {
 	if (parsed.v !== 2 || typeof parsed.chain !== "object" || parsed.chain === null) {
 		throw errors.new("sidecar is not a v2 chain file")
 	}
-	const chain = new Map<string, ChainEntry>()
-	for (const [braid, entry] of Object.entries(parsed.chain)) {
-		chain.set(braid, { g: BigInt(entry.g), prev: entry.prev, ts: BigInt(entry.ts) })
+	const chain = new Map<Braid, ChainEntry>()
+	for (const [name, entry] of Object.entries(parsed.chain)) {
+		chain.set(braid(name), { g: generation(BigInt(entry.g)), prev: entry.prev, ts: BigInt(entry.ts) })
 	}
 	const pending =
 		parsed.pending === null
 			? null
 			: {
-					braid: parsed.pending.braid,
-					gen: BigInt(parsed.pending.gen),
+					braid: braid(parsed.pending.braid),
+					gen: generation(BigInt(parsed.pending.gen)),
 					bytes: new Uint8Array(Buffer.from(parsed.pending.bytes, "base64"))
 				}
 	return { chain, pending }
@@ -105,5 +104,5 @@ async function writeSidecar(file: string, sidecar: Sidecar): Promise<void> {
 	}
 }
 
-export type { ChainEntry, PendingBatch, Sidecar }
+export type { ChainEntry, Pending, Sidecar }
 export { readSidecar, renderSidecar, writeSidecar }

package/src/codec.ts

@@ -9,26 +9,28 @@
 
 import * as errors from "@superbuilders/errors"
 import { ByteReader, ByteWriter, bytesEqual, fromHex, toHex, utf8Encoder } from "#bytes.ts"
-import type { LogTheory } from "#descriptor.ts"
+import type { Braid, Theory } from "#descriptor.ts"
 import { braidHex, descriptorOf } from "#descriptor.ts"
 import { refuse, refuseChain } from "#errors.ts"
-import type { LogValue, TaggedRefusal } from "#value.ts"
+import type { Generation } from "#keys.ts"
+import { generation } from "#keys.ts"
+import type { TaggedRefusal, Value } from "#value.ts"
 import { readTagged, writeTagged } from "#value.ts"
 
 const MAGIC = utf8Encoder.encode("BDBL")
 const VERSION = 2
 const OP_KIND = { insert: 1, delete: 2 } as const
 
-interface BatchOp {
+interface Op {
 	readonly op: "insert" | "delete"
 	readonly relation: string
-	readonly rows: ReadonlyArray<readonly LogValue[]>
+	readonly rows: ReadonlyArray<readonly Value[]>
 }
 
 interface BatchHeader {
 	readonly fingerprint: string
-	readonly braid: string
-	readonly braidGen: bigint
+	readonly braid: Braid
+	readonly braidGen: Generation
 	readonly prev: string
 	readonly writer: bigint
 	readonly timestamp: bigint
@@ -36,15 +38,11 @@ interface BatchHeader {
 
 interface DecodedBatch {
 	readonly header: BatchHeader
-	readonly ops: readonly BatchOp[]
+	readonly ops: readonly Op[]
 }
 
-function braidIdOf(braid: string): number {
-	const match = /^c([0-9a-f]{8})$/.exec(braid)
-	if (match === null || match[1] === undefined) {
-		throw errors.new(`not a braid id: ${braid}`)
-	}
-	return Number.parseInt(match[1], 16)
+function braidIdOf(id: Braid): number {
+	return Number.parseInt(id.slice(1), 16)
 }
 
 /**
@@ -52,7 +50,7 @@ function braidIdOf(braid: string): number {
  * the object is published under; every op relation must belong to the
  * header's braid — a spanning batch is unencodable.
  */
-function encodeBatch(theory: LogTheory, header: BatchHeader, ops: readonly BatchOp[]): Uint8Array {
+function encodeBatch(theory: Theory, header: BatchHeader, ops: readonly Op[]): Uint8Array {
 	const descriptor = descriptorOf(theory)
 	if (header.fingerprint !== descriptor.fingerprint) {
 		throw errors.new(`encode fingerprint ${header.fingerprint} is not the descriptor's ${descriptor.fingerprint}`)
@@ -105,7 +103,7 @@ function encodeBatch(theory: LogTheory, header: BatchHeader, ops: readonly Batch
 }
 
 /** Full parse of a batch object; refusals are typed, never partial reads. */
-function decodeBatch(theory: LogTheory, bytes: Uint8Array): DecodedBatch {
+function decodeBatch(theory: Theory, bytes: Uint8Array): DecodedBatch {
 	const descriptor = descriptorOf(theory)
 	const reader = new ByteReader(bytes, {
 		fail(what: string): never {
@@ -138,13 +136,13 @@ function decodeBatch(theory: LogTheory, bytes: Uint8Array): DecodedBatch {
 	if (members === undefined) {
 		refuse({ kind: "UnknownBraid", braid: braidId }, `batch braid ${braid} is not derived from this descriptor`)
 	}
-	const braidGen = reader.u64le("braid generation")
+	const braidGen = generation(reader.u64le("braid generation"))
 	const prev = toHex(reader.bytes(32, "prev"))
 	const writer = reader.u64le("writer")
 	const timestamp = reader.u64le("timestamp")
 
 	const opCount = reader.u32le("op count")
-	const ops: BatchOp[] = []
+	const ops: Op[] = []
 	for (let opIndex = 0; opIndex < opCount; opIndex++) {
 		const kind = reader.u8("op kind")
 		if (kind !== OP_KIND.insert && kind !== OP_KIND.delete) {
@@ -174,9 +172,9 @@ function decodeBatch(theory: LogTheory, bytes: Uint8Array): DecodedBatch {
 			)
 		}
 		const rowCount = reader.u32le("row count")
-		const rows: LogValue[][] = []
+		const rows: Value[][] = []
 		for (let rowIndex = 0; rowIndex < rowCount; rowIndex++) {
-			const row: LogValue[] = []
+			const row: Value[] = []
 			relation.fields.forEach(function readCell(field) {
 				const at = { relation: relation.name, row: rowIndex, field: field.name }
 				const where = `relation ${relation.name} row ${rowIndex} field ${field.name}`
@@ -217,8 +215,8 @@ function decodeBatch(theory: LogTheory, bytes: Uint8Array): DecodedBatch {
 	}
 }
 
-interface ChainPosition {
-	readonly g: bigint
+interface ChainEntry {
+	readonly g: Generation
 	readonly prev: string
 	readonly ts: bigint
 }
@@ -231,7 +229,7 @@ interface ChainPosition {
  * names the misbehaving writer, and the refusal data names the fetched
  * braid.
  */
-function verifyChain(header: BatchHeader, braid: string, slot: bigint, chain: ChainPosition): void {
+function verifyChain(header: BatchHeader, braid: Braid, slot: Generation, chain: ChainEntry): void {
 	if (header.braid !== braid || header.braidGen !== slot) {
 		refuseChain(
 			{ cause: "slot", braid, slot, writer: header.writer },
@@ -252,5 +250,5 @@ function verifyChain(header: BatchHeader, braid: string, slot: bigint, chain: Ch
 	}
 }
 
-export type { BatchHeader, BatchOp, ChainPosition, DecodedBatch }
+export type { BatchHeader, ChainEntry, DecodedBatch, Op }
 export { decodeBatch, encodeBatch, verifyChain }