@bjornpagen/bumbledb-log 0.17.0 → 0.18.0

package/src/store-s3.ts

@@ -0,0 +1,222 @@
+/**
+ * `s3Store`: the five verbs over one S3-compatible target. The official
+ * `@aws-sdk/client-s3` client signs and talks; this module maps HTTP
+ * outcomes onto the sums. One storage class for every key. The vendor
+ * ETag header is the opaque token, carried verbatim. R2 rides region
+ * `auto` and a required endpoint.
+ */
+
+import { DeleteObjectCommand, GetObjectCommand, PutObjectCommand, S3Client } from "@aws-sdk/client-s3"
+import * as errors from "@superbuilders/errors"
+import { wrapStore } from "#errors.ts"
+import type { StoreKey } from "#keys.ts"
+import type { Etag, ObjectStore } from "#store.ts"
+
+interface StaticKeys {
+	readonly accessKeyId: string
+	readonly secretAccessKey: string
+	readonly sessionToken?: string
+}
+
+/** Static keys, or a caller-owned refresh the store invokes before each signed request. */
+type S3Credentials = StaticKeys | (() => StaticKeys | Promise<StaticKeys>)
+
+interface S3Config {
+	readonly endpoint?: string
+	readonly region: string
+	readonly bucket: string
+	readonly credentials: S3Credentials
+	readonly prefix?: string
+}
+
+function asEtag(raw: string): Etag {
+	return raw as Etag
+}
+
+function normalizePrefix(raw: string | undefined): string {
+	if (raw === undefined || raw.length === 0) {
+		return ""
+	}
+	const trimmed = raw.replace(/^\/+|\/+$/g, "")
+	if (trimmed.length === 0 || trimmed.split("/").some((seg) => seg.length === 0)) {
+		throw errors.new(`store prefix is not a slash path: ${raw}`)
+	}
+	return trimmed
+}
+
+function joinPrefix(prefix: string, key: string): string {
+	return prefix.length === 0 ? key : `${prefix}/${key}`
+}
+
+async function resolveKeys(credentials: S3Credentials): Promise<StaticKeys> {
+	if (typeof credentials === "function") {
+		return await credentials()
+	}
+	return credentials
+}
+
+function httpStatus(error: unknown): number | undefined {
+	if (error === null || typeof error !== "object" || !("$metadata" in error)) {
+		return undefined
+	}
+	const metadata = error.$metadata
+	if (metadata === null || typeof metadata !== "object" || !("httpStatusCode" in metadata)) {
+		return undefined
+	}
+	const status = metadata.httpStatusCode
+	return typeof status === "number" ? status : undefined
+}
+
+function asError(error: unknown): Error {
+	if (error instanceof Error) {
+		return error
+	}
+	return errors.new(String(error))
+}
+
+function etagOf(raw: string | undefined, op: string, key: StoreKey): Etag {
+	if (raw === undefined || raw.length === 0) {
+		throw wrapStore(errors.new("vendor omitted ETag"), `${op} ${key}`)
+	}
+	return asEtag(raw)
+}
+
+function s3Store(config: S3Config): ObjectStore {
+	if (config.region === "auto" && config.endpoint === undefined) {
+		throw errors.new("region auto needs an endpoint")
+	}
+	const prefix = normalizePrefix(config.prefix)
+	const client = new S3Client({
+		region: config.region,
+		credentials: async function credentials() {
+			const keys = await resolveKeys(config.credentials)
+			return {
+				accessKeyId: keys.accessKeyId,
+				secretAccessKey: keys.secretAccessKey,
+				...(keys.sessionToken === undefined ? {} : { sessionToken: keys.sessionToken })
+			}
+		},
+		requestChecksumCalculation: "WHEN_REQUIRED",
+		responseChecksumValidation: "WHEN_REQUIRED",
+		...(config.endpoint === undefined ? {} : { endpoint: config.endpoint, forcePathStyle: true })
+	})
+
+	function objectKey(key: StoreKey): string {
+		return joinPrefix(prefix, key)
+	}
+
+	return {
+		async get(key) {
+			const ran = await errors.try(
+				client.send(
+					new GetObjectCommand({
+						Bucket: config.bucket,
+						Key: objectKey(key)
+					})
+				)
+			)
+			if (ran.error) {
+				if (httpStatus(ran.error) === 404) {
+					return null
+				}
+				throw wrapStore(asError(ran.error), `get ${key}`)
+			}
+			if (ran.data.Body === undefined) {
+				throw wrapStore(errors.new("vendor omitted body"), `get ${key}`)
+			}
+			return {
+				bytes: await ran.data.Body.transformToByteArray(),
+				etag: etagOf(ran.data.ETag, "get", key)
+			}
+		},
+
+		async getIfChanged(key, etag) {
+			const ran = await errors.try(
+				client.send(
+					new GetObjectCommand({
+						Bucket: config.bucket,
+						Key: objectKey(key),
+						IfNoneMatch: etag
+					})
+				)
+			)
+			if (ran.error) {
+				if (httpStatus(ran.error) === 304) {
+					return { tag: "unchanged" }
+				}
+				throw wrapStore(asError(ran.error), `getIfChanged ${key}`)
+			}
+			if (ran.data.Body === undefined) {
+				throw wrapStore(errors.new("vendor omitted body"), `getIfChanged ${key}`)
+			}
+			return {
+				tag: "changed",
+				fetched: {
+					bytes: await ran.data.Body.transformToByteArray(),
+					etag: etagOf(ran.data.ETag, "getIfChanged", key)
+				}
+			}
+		},
+
+		async putCreate(key, bytes) {
+			const ran = await errors.try(
+				client.send(
+					new PutObjectCommand({
+						Bucket: config.bucket,
+						Key: objectKey(key),
+						Body: bytes,
+						IfNoneMatch: "*"
+					})
+				)
+			)
+			if (ran.error) {
+				if (httpStatus(ran.error) === 412) {
+					return { tag: "exists" }
+				}
+				throw wrapStore(asError(ran.error), `putCreate ${key}`)
+			}
+			return { tag: "created", etag: etagOf(ran.data.ETag, "putCreate", key) }
+		},
+
+		async putSwap(key, bytes, etag) {
+			const ran = await errors.try(
+				client.send(
+					new PutObjectCommand({
+						Bucket: config.bucket,
+						Key: objectKey(key),
+						Body: bytes,
+						IfMatch: etag
+					})
+				)
+			)
+			if (ran.error) {
+				const status = httpStatus(ran.error)
+				if (status === 412 || status === 404) {
+					return { tag: "moved" }
+				}
+				throw wrapStore(asError(ran.error), `putSwap ${key}`)
+			}
+			return { tag: "swapped", etag: etagOf(ran.data.ETag, "putSwap", key) }
+		},
+
+		async delete(key) {
+			const ran = await errors.try(
+				client.send(
+					new DeleteObjectCommand({
+						Bucket: config.bucket,
+						Key: objectKey(key)
+					})
+				)
+			)
+			if (ran.error) {
+				if (httpStatus(ran.error) === 404) {
+					return
+				}
+				throw wrapStore(asError(ran.error), `delete ${key}`)
+			}
+		}
+	}
+}
+
+export type { S3Config, S3Credentials, StaticKeys }
+export { joinPrefix, s3Store }

package/src/store.ts

@@ -21,53 +21,45 @@ import { internalBlake3 } from "@bjornpagen/bumbledb"
 import * as errors from "@superbuilders/errors"
 import { toHex } from "#bytes.ts"
 import { wrapStore } from "#errors.ts"
+import type { StoreKey } from "#keys.ts"
+import { LOCK_SUFFIX } from "#keys.ts"
+
+declare const etagBrand: unique symbol
+type Etag = string & { readonly [etagBrand]: typeof etagBrand }
+
+function etag(raw: string): Etag {
+	return raw as Etag
+}
 
 interface Fetched {
 	readonly bytes: Uint8Array
-	readonly etag: string
+	readonly etag: Etag
 }
 
 type Poll = { readonly tag: "unchanged" } | { readonly tag: "changed"; readonly fetched: Fetched }
 
-type Create = { readonly tag: "created"; readonly etag: string } | { readonly tag: "exists" }
+type Create = { readonly tag: "created"; readonly etag: Etag } | { readonly tag: "exists" }
 
-type Swap = { readonly tag: "swapped"; readonly etag: string } | { readonly tag: "moved" }
+type Swap = { readonly tag: "swapped"; readonly etag: Etag } | { readonly tag: "moved" }
 
 interface ObjectStore {
 	/** GET; null on 404. */
-	get(key: string): Promise<Fetched | null>
+	get(key: StoreKey): Promise<Fetched | null>
 	/** GET with If-None-Match — the cheap manifest poll. */
-	getIfChanged(key: string, etag: string): Promise<Poll>
+	getIfChanged(key: StoreKey, etag: Etag): Promise<Poll>
 	/** PUT with If-None-Match: * — the log-slot arbitration primitive. */
-	putCreate(key: string, bytes: Uint8Array): Promise<Create>
+	putCreate(key: StoreKey, bytes: Uint8Array): Promise<Create>
 	/** PUT with If-Match — the manifest CAS primitive. */
-	putSwap(key: string, bytes: Uint8Array, etag: string): Promise<Swap>
+	putSwap(key: StoreKey, bytes: Uint8Array, etag: Etag): Promise<Swap>
 	/** DELETE, unconditional — the gc verb's tool. */
-	delete(key: string): Promise<void>
+	delete(key: StoreKey): Promise<void>
 }
 
-/** Suffix of the per-key pid-lockfile that serializes `putSwap`. */
-const LOCK_SUFFIX = ".lock"
-
 /** Ceiling of the jittered wait between probes of a live-held lock. */
 const LOCK_RETRY_MS = 10
 
-function contentEtag(bytes: Uint8Array): string {
-	return toHex(new Uint8Array(internalBlake3(bytes)))
-}
-
-function checkKey(key: string): void {
-	if (key.length === 0 || key.startsWith("/") || key.endsWith("/")) {
-		throw errors.new(`store key is not a slash path: ${key}`)
-	}
-	for (const segment of key.split("/")) {
-		if (segment.length === 0 || segment === "." || segment === "..") {
-			throw errors.new(`store key segment is illegal: ${key}`)
-		}
-		if (segment.endsWith(LOCK_SUFFIX)) {
-			throw errors.new(`store key collides with the lockfile suffix: ${key}`)
-		}
-	}
+function contentEtag(bytes: Uint8Array): Etag {
+	return etag(toHex(new Uint8Array(internalBlake3(bytes))))
 }
 
 function codeOf(error: Error): string | undefined {
@@ -173,8 +165,7 @@ async function releaseLock(lockPath: string): Promise<void> {
 function fsStore(root: string): ObjectStore {
 	const rootPath = path.resolve(root)
 
-	function objectPath(key: string): string {
-		checkKey(key)
+	function objectPath(key: StoreKey): string {
 		return path.join(rootPath, ...key.split("/"))
 	}
 
@@ -288,5 +279,59 @@ function fsStore(root: string): ObjectStore {
 	}
 }
 
-export type { Create, Fetched, ObjectStore, Poll, Swap }
-export { fsStore }
+/**
+ * The five verbs over one in-process Map. Single-process only: tests
+ * and ephemeral dev inside this process, no persistence, no
+ * cross-process claim, no configuration. Third `Etag` producer beside
+ * `fsStore` and `s3Store`: blake3 of the content, `fsStore`'s mint,
+ * carried as the same opaque brand.
+ */
+function memStore(): ObjectStore {
+	const objects = new Map<StoreKey, Fetched>()
+	return {
+		async get(key) {
+			return objects.get(key) ?? null
+		},
+
+		async getIfChanged(key, etag) {
+			const current = objects.get(key)
+			if (current === undefined) {
+				throw wrapStore(errors.new("poll target absent"), `getIfChanged ${key}`)
+			}
+			if (current.etag === etag) {
+				return { tag: "unchanged" }
+			}
+			return { tag: "changed", fetched: current }
+		},
+
+		async putCreate(key, bytes) {
+			if (objects.has(key)) {
+				return { tag: "exists" }
+			}
+			const copy = new Uint8Array(bytes)
+			const tag = contentEtag(copy)
+			objects.set(key, { bytes: copy, etag: tag })
+			return { tag: "created", etag: tag }
+		},
+
+		async putSwap(key, bytes, etag) {
+			const current = objects.get(key)
+			if (current === undefined || current.etag !== etag) {
+				return { tag: "moved" }
+			}
+			const copy = new Uint8Array(bytes)
+			const tag = contentEtag(copy)
+			objects.set(key, { bytes: copy, etag: tag })
+			return { tag: "swapped", etag: tag }
+		},
+
+		async delete(key) {
+			objects.delete(key)
+		}
+	}
+}
+
+export type { S3Config, S3Credentials } from "#store-s3.ts"
+export { s3Store } from "#store-s3.ts"
+export type { Create, Etag, Fetched, ObjectStore, Poll, Swap }
+export { etag, fsStore, memStore }

package/src/value.ts

@@ -1,10 +1,10 @@
 /**
  * The driver's raw-value vocabulary and its two canonical encodings:
- * the command codec's tagged little-endian form (20's tag table, the one
- * shared tagged-value encoding the footprint keys also hash), and the
- * engine's big-endian order-preserving literal form the fingerprint
- * mirror reproduces. Values here are always RAW — strings as UTF-8,
- * never intern ids — which is what makes footprint keys state-independent.
+ * the command codec's tagged little-endian form (the tag table the
+ * batch wire already declared), and the engine's big-endian
+ * order-preserving literal form the fingerprint mirror reproduces.
+ * Values here are always RAW — strings as UTF-8, never intern ids —
+ * so a key hashed from a raw value cannot depend on a catalog.
  */
 
 import type { ValueTypeSpec } from "@bjornpagen/bumbledb"
@@ -12,12 +12,12 @@ import * as errors from "@superbuilders/errors"
 import type { ByteReader, ByteWriter } from "#bytes.ts"
 import { bytesEqual, I64_MAX, I64_MIN, U64_MAX, utf8Encoder, utf8StrictDecoder } from "#bytes.ts"
 
-interface LogInterval {
+interface Interval {
 	readonly start: bigint
 	readonly end: bigint
 }
 
-type LogValue = boolean | bigint | string | Uint8Array | LogInterval
+type Value = boolean | bigint | string | Uint8Array | Interval
 
 /** 20's tag table: the codec's own numbering, normative to the byte. */
 const TAG = {
@@ -30,7 +30,7 @@ const TAG = {
 	fixedInterval: 6
 } as const
 
-function isInterval(value: LogValue): value is LogInterval {
+function isInterval(value: Value): value is Interval {
 	return typeof value === "object" && !(value instanceof Uint8Array)
 }
 
@@ -51,7 +51,7 @@ function wireTagOf(type: ValueTypeSpec): number {
 	}
 }
 
-function checkAgainst(context: string, type: ValueTypeSpec, value: LogValue): void {
+function checkAgainst(context: string, type: ValueTypeSpec, value: Value): void {
 	switch (type.kind) {
 		case "bool": {
 			if (typeof value !== "boolean") {
@@ -101,7 +101,7 @@ function checkAgainst(context: string, type: ValueTypeSpec, value: LogValue): vo
 }
 
 /** The codec's tagged form: `tag u8` + payload, at the field's layout. */
-function writeTagged(out: ByteWriter, type: ValueTypeSpec, value: LogValue): void {
+function writeTagged(out: ByteWriter, type: ValueTypeSpec, value: Value): void {
 	switch (type.kind) {
 		case "bool": {
 			out.u8(TAG.bool)
@@ -131,7 +131,7 @@ function writeTagged(out: ByteWriter, type: ValueTypeSpec, value: LogValue): voi
 			return
 		}
 		case "interval": {
-			const interval = value as LogInterval
+			const interval = value as Interval
 			if (type.width === undefined) {
 				out.u8(TAG.interval)
 				if (type.element === "u64") {
@@ -165,7 +165,7 @@ interface TaggedRefusal {
 }
 
 /** Full parse at the layout's type; every illegal byte is a typed refusal. */
-function readTagged(reader: ByteReader, type: ValueTypeSpec, refusal: TaggedRefusal): LogValue {
+function readTagged(reader: ByteReader, type: ValueTypeSpec, refusal: TaggedRefusal): Value {
 	const expected = wireTagOf(type)
 	const tag = reader.u8("value tag")
 	if (tag !== expected) {
@@ -215,7 +215,7 @@ function readTagged(reader: ByteReader, type: ValueTypeSpec, refusal: TaggedRefu
 	}
 }
 
-function valuesEqual(a: LogValue, b: LogValue): boolean {
+function valuesEqual(a: Value, b: Value): boolean {
 	if (typeof a === "boolean" || typeof a === "bigint" || typeof a === "string") {
 		return a === b
 	}
@@ -234,7 +234,7 @@ function valuesEqual(a: LogValue, b: LogValue): boolean {
  * the fingerprint's `put_literal` length-prefixes them separately, and
  * closed ground axioms with string columns are the mirror's recorded gap.
  */
-function writeCanonicalLiteral(out: ByteWriter, type: ValueTypeSpec, value: LogValue): void {
+function writeCanonicalLiteral(out: ByteWriter, type: ValueTypeSpec, value: Value): void {
 	switch (type.kind) {
 		case "bool": {
 			out.u8(value === true ? 1 : 0)
@@ -260,7 +260,7 @@ function writeCanonicalLiteral(out: ByteWriter, type: ValueTypeSpec, value: LogV
 			return
 		}
 		case "interval": {
-			const interval = value as LogInterval
+			const interval = value as Interval
 			if (type.width !== undefined) {
 				if (type.element === "u64") {
 					out.u64be(interval.start)
@@ -281,5 +281,5 @@ function writeCanonicalLiteral(out: ByteWriter, type: ValueTypeSpec, value: LogV
 	}
 }
 
-export type { LogInterval, LogValue, TaggedRefusal }
+export type { Interval, TaggedRefusal, Value }
 export { checkAgainst, isInterval, readTagged, TAG, valuesEqual, wireTagOf, writeCanonicalLiteral, writeTagged }

package/src/writer.ts

@@ -14,11 +14,12 @@ import * as crypto from "node:crypto"
 import type { Fact, FreshKeys, MemberRelation, SchemaRelations, Violation } from "@bjornpagen/bumbledb"
 import * as errors from "@superbuilders/errors"
 import { bytesEqual, utf8Encoder, utf8StrictDecoder } from "#bytes.ts"
-import type { BatchOp } from "#codec.ts"
+import type { Op } from "#codec.ts"
 import { decodeBatch, encodeBatch } from "#codec.ts"
-import type { RelationInfo } from "#descriptor.ts"
+import type { Braid, RelationInfo } from "#descriptor.ts"
 import { ErrSpanningCommit, throwContention } from "#errors.ts"
-import { idsKey, logKey } from "#keys.ts"
+import type { Generation } from "#keys.ts"
+import { generation, idsKey, logKey } from "#keys.ts"
 import type { Core, Replica } from "#replica.ts"
 import {
 	applyOps,
@@ -33,7 +34,7 @@ import {
 	readdressPending,
 	withGate
 } from "#replica.ts"
-import type { LogValue } from "#value.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. */
@@ -48,15 +49,20 @@ type Commit<Rels extends SchemaRelations, R> =
 	| {
 			readonly tag: "accepted"
 			readonly value: R
-			readonly braid: string
-			readonly generation: bigint
+			readonly braid: Braid
+			readonly generation: Generation
 			readonly durability: Durability
 	  }
 	| { readonly tag: "rejected"; readonly violations: readonly Violation<Rels>[] }
 
 type BraidOutcome<Rels extends SchemaRelations> =
-	| { readonly tag: "accepted"; readonly braid: string; readonly generation: bigint; readonly durability: Durability }
-	| { readonly tag: "rejected"; readonly braid: string; readonly violations: readonly Violation<Rels>[] }
+	| {
+			readonly tag: "accepted"
+			readonly braid: Braid
+			readonly generation: Generation
+			readonly durability: Durability
+	  }
+	| { readonly tag: "rejected"; readonly braid: Braid; readonly violations: readonly Violation<Rels>[] }
 
 interface CommitSplit<Rels extends SchemaRelations, R> {
 	readonly value: R
@@ -68,7 +74,7 @@ interface CommitSplit<Rels extends SchemaRelations, R> {
  * drawing on the id lease (10) — reservations never appear in the log;
  * the resulting inserts carry concrete values. Pure and synchronous.
  */
-interface LogBatch<Rels extends SchemaRelations> {
+interface Batch<Rels extends SchemaRelations> {
 	insert<Rel extends MemberRelation<Rels>>(relation: Rel, facts: Iterable<Fact<Rel>>): void
 	delete<Rel extends MemberRelation<Rels>>(relation: Rel, facts: Iterable<Fact<Rel>>): void
 	reserve<Rel extends MemberRelation<Rels>>(
@@ -79,8 +85,8 @@ interface LogBatch<Rels extends SchemaRelations> {
 }
 
 interface Writer<Rels extends SchemaRelations> {
-	commit<R>(body: (batch: LogBatch<Rels>) => R): Promise<Commit<Rels, R>>
-	commitSplit<R>(body: (batch: LogBatch<Rels>) => R): Promise<CommitSplit<Rels, R>>
+	commit<R>(body: (batch: Batch<Rels>) => R): Promise<Commit<Rels, R>>
+	commitSplit<R>(body: (batch: Batch<Rels>) => R): Promise<CommitSplit<Rels, R>>
 }
 
 interface LeaseRange {
@@ -162,20 +168,20 @@ function pushRange(state: WriterState, relation: number, field: number, next: bi
 }
 
 interface Recording {
-	readonly ops: BatchOp[]
+	readonly ops: Op[]
 }
 
 function lowerFact<Rels extends SchemaRelations>(
 	core: Core<Rels>,
 	info: RelationInfo,
 	fact: Record<string, unknown>
-): LogValue[] {
+): Value[] {
 	return info.fields.map(function lowerCell(field) {
 		const raw = fact[field.name]
 		if (raw === undefined) {
 			throw errors.new(`relation ${info.name}: fact is missing field ${field.name}`)
 		}
-		let value: LogValue
+		let value: Value
 		if (field.closedRef !== undefined) {
 			if (typeof raw !== "string") {
 				throw errors.new(`relation ${info.name} field ${field.name}: expected a ${field.closedRef} handle name`)
@@ -193,7 +199,7 @@ function lowerFact<Rels extends SchemaRelations>(
 			}
 			value = { start: interval.start, end: interval.end }
 		} else {
-			value = raw as LogValue
+			value = raw as Value
 		}
 		checkAgainst(`relation ${info.name} field ${field.name}`, field.type, value)
 		return value
@@ -203,7 +209,7 @@ function lowerFact<Rels extends SchemaRelations>(
 function recorderOf<Rels extends SchemaRelations>(
 	core: Core<Rels>,
 	state: WriterState
-): { batch: LogBatch<Rels>; recording: Recording } {
+): { batch: Batch<Rels>; recording: Recording } {
 	const recording: Recording = { ops: [] }
 	function infoOf(name: string): RelationInfo {
 		const info = core.descriptor.relationByName.get(name)
@@ -217,7 +223,7 @@ function recorderOf<Rels extends SchemaRelations>(
 	}
 	function record(op: "insert" | "delete", relationName: string, facts: Iterable<unknown>): void {
 		const info = infoOf(relationName)
-		const rows: LogValue[][] = []
+		const rows: Value[][] = []
 		for (const fact of facts) {
 			if (typeof fact !== "object" || fact === null) {
 				throw errors.new(`relation ${relationName}: a fact is not an object`)
@@ -226,7 +232,7 @@ function recorderOf<Rels extends SchemaRelations>(
 		}
 		recording.ops.push({ op, relation: relationName, rows })
 	}
-	const batch: LogBatch<Rels> = {
+	const batch: Batch<Rels> = {
 		insert(relation, facts) {
 			record("insert", relation.name, facts)
 		},
@@ -254,8 +260,8 @@ function recorderOf<Rels extends SchemaRelations>(
 async function recordWithLeases<Rels extends SchemaRelations, R>(
 	core: Core<Rels>,
 	state: WriterState,
-	body: (batch: LogBatch<Rels>) => R
-): Promise<{ value: R; ops: BatchOp[] }> {
+	body: (batch: Batch<Rels>) => 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() {
@@ -273,11 +279,8 @@ async function recordWithLeases<Rels extends SchemaRelations, R>(
 	throw errors.new("the id-lease pool could not satisfy the recording after 16 refills")
 }
 
-function braidsTouched<Rels extends SchemaRelations>(
-	core: Core<Rels>,
-	ops: readonly BatchOp[]
-): Map<string, BatchOp[]> {
-	const partitioned = new Map<string, BatchOp[]>()
+function braidsTouched<Rels extends SchemaRelations>(core: Core<Rels>, ops: readonly Op[]): Map<Braid, Op[]> {
+	const partitioned = new Map<Braid, Op[]>()
 	for (const op of ops) {
 		const info = core.descriptor.relationByName.get(op.relation)
 		const braid = info === undefined ? undefined : core.descriptor.braidOfRelation.get(info.id)
@@ -298,10 +301,10 @@ function braidsTouched<Rels extends SchemaRelations>(
  *  the hot statement and carries the offending facts' raw values; an
  *  accepted-but-outraced terminal loss carries the racing tip. */
 function screamContention<Rels extends SchemaRelations>(
-	braid: string,
+	braid: Braid,
 	rejudged:
 		| { readonly tag: "rejected"; readonly violations: readonly Violation<Rels>[] }
-		| { readonly tag: "outraced"; readonly tip: bigint }
+		| { readonly tag: "outraced"; readonly tip: Generation }
 ): never {
 	if (rejudged.tag === "rejected") {
 		const violation = rejudged.violations[0]
@@ -339,7 +342,7 @@ function screamContention<Rels extends SchemaRelations>(
 async function publishPending<Rels extends SchemaRelations>(
 	core: Core<Rels>,
 	state: WriterState,
-	ops: readonly BatchOp[]
+	ops: readonly Op[]
 ): Promise<Commit<Rels, undefined>> {
 	let losses = 0
 	for (;;) {
@@ -400,8 +403,8 @@ async function publishPending<Rels extends SchemaRelations>(
 async function disciplineCommit<Rels extends SchemaRelations>(
 	core: Core<Rels>,
 	state: WriterState,
-	braid: string,
-	ops: readonly BatchOp[]
+	braid: Braid,
+	ops: readonly Op[]
 ): Promise<Commit<Rels, undefined>> {
 	const entry = chainEntry(core, braid)
 	const timestamp = maxBigint(BigInt(Date.now()), entry.ts)
@@ -410,14 +413,14 @@ async function disciplineCommit<Rels extends SchemaRelations>(
 		{
 			fingerprint: core.descriptor.fingerprint,
 			braid,
-			braidGen: entry.g + 1n,
+			braidGen: generation(entry.g + 1n),
 			prev: entry.prev,
 			writer: state.writerId,
 			timestamp
 		},
 		ops
 	)
-	core.pending = { braid, gen: entry.g + 1n, bytes }
+	core.pending = { braid, gen: generation(entry.g + 1n), bytes }
 	core.pendingOps = ops
 	core.pendingApplied = false
 	await persistSidecar(core)
@@ -465,7 +468,7 @@ function openWriter<Rels extends SchemaRelations>(replica: Replica<Rels>): Write
 				if (partitioned.size > 1) {
 					throw errors.wrap(ErrSpanningCommit, `the recorded ops span braids ${[...partitioned.keys()].join(", ")}`)
 				}
-				const [braid, ops] = [...partitioned.entries()][0] as [string, BatchOp[]]
+				const [braid, ops] = [...partitioned.entries()][0] as [Braid, Op[]]
 				const outcome = await disciplineCommit(core, state, braid, ops)
 				if (outcome.tag === "rejected") {
 					return outcome
@@ -502,5 +505,5 @@ function openWriter<Rels extends SchemaRelations>(replica: Replica<Rels>): Write
 	}
 }
 
-export type { BraidOutcome, Commit, CommitSplit, Durability, LogBatch, Writer }
+export type { Batch, BraidOutcome, Commit, CommitSplit, Durability, Writer }
 export { openWriter }