@bjornpagen/bumbledb-log 0.20.0 → 0.20.2

package/src/descriptor.ts

@@ -1,240 +0,0 @@
-/**
- * The parsed protocol descriptor: one thin parse of the engine's sealed
- * truth — relation ids, sealed field order, resolved closed rows,
- * materialized statements, and the real fingerprint — plus the braid
- * map and serial-at roster read off the log core's braids seat
- * (`internalLogBraidsOf`): one derivation of the braid partition,
- * projected here into the driver's branded shapes. Cached per theory
- * value.
- */
-
-import type {
-	AnySchema,
-	FactValue,
-	LogCodecHandle,
-	SchemaSpec,
-	SealedDescriptor,
-	SealedStatement,
-	ValueTypeSpec
-} from "@bjornpagen/bumbledb"
-import { internalDescriptor, internalLogBraidsOf, internalLogCodec, lower } from "@bjornpagen/bumbledb"
-import * as errors from "@superbuilders/errors"
-import { regex } from "arkregex"
-import { fromHex } from "#bytes.ts"
-
-interface FieldInfo {
-	readonly name: string
-	readonly type: ValueTypeSpec
-	readonly fresh: boolean
-	/** Set when the field's newtype names a closed relation's id class. */
-	readonly closedRef: string | undefined
-}
-
-interface RelationInfo {
-	readonly id: number
-	readonly name: string
-	readonly closed: boolean
-	readonly handles: readonly string[]
-	/** Sealed order: a closed relation's synthetic u64 `id` at ordinal 0. */
-	readonly fields: readonly FieldInfo[]
-	/** Closed ground axioms in sealed order (id first), resolved values. */
-	readonly rows: ReadonlyArray<readonly FactValue[]>
-}
-
-declare const braidBrand: unique symbol
-type Braid = string & { readonly [braidBrand]: typeof braidBrand }
-
-const BRAID_ID = regex("^c[0-9a-f]{8}$")
-
-function braid(raw: string): Braid {
-	if (!BRAID_ID.test(raw)) {
-		throw errors.new(`not a braid id: ${raw}`)
-	}
-	return raw as Braid
-}
-
-function refuseShape(why: string): never {
-	throw errors.new(`theory: ${why}`)
-}
-
-interface SerialStatement {
-	readonly statement: number
-	readonly braid: Braid
-}
-
-/** The braids seat names serial-at statements by id; the braid tag is a
- *  projection join through the statement's own relation. */
-function serialAtFrom(
-	ids: readonly number[],
-	statements: readonly SealedStatement[],
-	braidOfRelation: ReadonlyMap<number, Braid>
-): SerialStatement[] {
-	const statementById = new Map<number, SealedStatement>()
-	for (const statement of statements) {
-		statementById.set(statement.id, statement)
-	}
-	return ids.map(function joinBraid(id) {
-		const statement = statementById.get(id)
-		if (statement === undefined) {
-			refuseShape(`serial-at statement ${id} is not in the sealed statements`)
-		}
-		if (statement.kind === "containment") {
-			refuseShape(`serial-at statement ${id} is a containment`)
-		}
-		const relation = statement.kind === "functionality" ? statement.relation : statement.target.relation
-		const braid = braidOfRelation.get(relation)
-		if (braid === undefined) {
-			refuseShape(`serial-at statement ${id} relation ${relation} is in no braid`)
-		}
-		return { statement: id, braid }
-	})
-}
-
-interface Descriptor {
-	readonly relations: readonly RelationInfo[]
-	readonly relationByName: ReadonlyMap<string, RelationInfo>
-	readonly statements: readonly SealedStatement[]
-	/** Ordinary relation id → braid id (`c{smallest:08x}`). */
-	readonly braidOfRelation: ReadonlyMap<number, Braid>
-	/** Braid id → member relation ids, ascending. */
-	readonly braidMembers: ReadonlyMap<Braid, readonly number[]>
-	readonly serialAtStatements: readonly SerialStatement[]
-	/** The sealed per-theory codec handle — the grammar's one reader,
-	 *  minted once and cached with the parse. */
-	readonly codec: LogCodecHandle
-	readonly fingerprint: string
-	readonly fingerprintBytes: Uint8Array
-}
-
-/** The pure trio's input: the theory value, its lowered spec, or an already-parsed descriptor. */
-type Theory = AnySchema | SchemaSpec | Descriptor
-
-function isDescriptor(theory: Theory): theory is Descriptor {
-	return "braidMembers" in theory
-}
-
-function isSpec(theory: Theory): theory is SchemaSpec {
-	return Array.isArray((theory as SchemaSpec).relations)
-}
-
-const cache = new WeakMap<object, Descriptor>()
-
-function descriptorOf(theory: Theory): Descriptor {
-	if (isDescriptor(theory)) {
-		return theory
-	}
-	const hit = cache.get(theory)
-	if (hit !== undefined) {
-		return hit
-	}
-	const spec = isSpec(theory) ? theory : lower(theory)
-	const parsed = spec === theory ? fromSealed(spec) : (cache.get(spec) ?? fromSealed(spec))
-	cache.set(theory, parsed)
-	cache.set(spec, parsed)
-	return parsed
-}
-
-function braidHex(relationId: number): Braid {
-	return braid(`c${relationId.toString(16).padStart(8, "0")}`)
-}
-
-function fromSealed(spec: SchemaSpec): Descriptor {
-	const sealed: SealedDescriptor = internalDescriptor(spec)
-
-	/** Handle newtype (`{name}.id`, off each closed relation's sealed id slot) → roster name. */
-	const ownerOfIdClass = new Map<string, string>()
-	for (const relation of sealed.relations) {
-		if (relation.extension === undefined) {
-			continue
-		}
-		const idSlot = relation.fields.find(function idOf(field) {
-			return field.name === "id"
-		})
-		const handleClass = idSlot?.newtype
-		if (handleClass === undefined) {
-			refuseShape(`closed relation ${relation.name} has no handle class on its sealed id slot`)
-		}
-		ownerOfIdClass.set(handleClass, relation.name)
-	}
-
-	const relations: RelationInfo[] = sealed.relations.map(function relationOf(relation) {
-		const fields: FieldInfo[] = relation.fields.map(function fieldOf(field) {
-			return {
-				name: field.name,
-				type: field.valueType,
-				fresh: field.fresh,
-				closedRef: field.newtype === undefined ? undefined : ownerOfIdClass.get(field.newtype)
-			}
-		})
-		const extension = relation.extension ?? []
-		const named = new Map(
-			relation.fields.map(function indexOf(field) {
-				return [field.name, field]
-			})
-		)
-		const rows = extension.map(function rowOf(row) {
-			const cells = new Map(
-				row.values.map(function cellOf(cell) {
-					return [cell.name, cell.value]
-				})
-			)
-			return relation.fields.map(function cellValue(field) {
-				const hit = cells.get(field.name)
-				if (hit !== undefined) {
-					return hit
-				}
-				if (field.name === "id" && named.has("id")) {
-					return row.id
-				}
-				return refuseShape(`closed relation ${relation.name}: sealed row ${row.handle} missing field ${field.name}`)
-			})
-		})
-		return {
-			id: relation.id,
-			name: relation.name,
-			closed: relation.extension !== undefined,
-			handles: extension.map(function handleOf(row) {
-				return row.handle
-			}),
-			fields,
-			rows
-		}
-	})
-
-	const byName = new Map<string, RelationInfo>()
-	for (const relation of relations) {
-		if (byName.has(relation.name)) {
-			refuseShape(`duplicate relation ${relation.name}`)
-		}
-		byName.set(relation.name, relation)
-	}
-
-	const statements = sealed.statements
-	const braids = internalLogBraidsOf(sealed)
-	const braidOfRelation = new Map<number, Braid>()
-	const braidMembers = new Map<Braid, readonly number[]>()
-	for (const component of braids.components) {
-		const id = braidHex(component.braid)
-		braidMembers.set(id, component.relations)
-		for (const member of component.relations) {
-			braidOfRelation.set(member, id)
-		}
-	}
-	const serialAtStatements = serialAtFrom(braids.serialAt, statements, braidOfRelation)
-
-	const fingerprint = sealed.fingerprint
-	return {
-		relations,
-		relationByName: byName,
-		statements,
-		braidOfRelation,
-		braidMembers,
-		serialAtStatements,
-		codec: internalLogCodec(sealed),
-		fingerprint,
-		fingerprintBytes: fromHex(fingerprint)
-	}
-}
-
-export type { Braid, Descriptor, FieldInfo, RelationInfo, SerialStatement, Theory }
-export { braid, braidHex, descriptorOf, serialAtFrom }

package/src/errors.ts

@@ -1,309 +0,0 @@
-/**
- * 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. 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"
-import type { Braid } from "#descriptor.ts"
-import type { Generation, StoreKey } from "#keys.ts"
-
-/**
- * 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"
-)
-
-/** 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")
-
-/** 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 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")
-
-/** A put_create at a slot below the published checkpoint vector. */
-const ErrSlotRetired = errors.new("bumbledb-log slotRetired: the slot is retired")
-
-/** The vendor channel: I/O and store infrastructure failures. */
-const ErrStore = errors.new("bumbledb-log store failure")
-
-/**
- * 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 =
-	// 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 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: "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 }
-
-type ChainCause = "prev" | "slot" | "timestamp"
-
-interface ChainMismatchData {
-	readonly cause: ChainCause
-	readonly braid: Braid
-	readonly slot: Generation
-	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: Generation }
-
-interface ContentionData {
-	readonly braid: Braid
-	readonly cause: ContentionCause
-}
-
-interface OverWidthData {
-	readonly requested: bigint
-}
-
-interface RefillNeededData {
-	readonly relation: number
-	readonly field: number
-	readonly requested: bigint
-}
-
-interface ExhaustedData {
-	readonly relation: number
-	readonly field: number
-}
-
-interface SlotRetiredData {
-	readonly braid: Braid
-	readonly slot: Generation
-}
-
-/** 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: "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 overWidthData = new WeakMap<Error, OverWidthData>()
-const refillNeededData = new WeakMap<Error, RefillNeededData>()
-const exhaustedData = new WeakMap<Error, ExhaustedData>()
-const slotRetiredData = new WeakMap<Error, SlotRetiredData>()
-
-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 refuseManifestMissing(detail: string): never {
-	throw errors.wrap(ErrManifestMissing, detail)
-}
-
-function isManifestMissing(error: unknown): boolean {
-	return error instanceof Error && errors.is(error, ErrManifestMissing)
-}
-
-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)
-	throw error
-}
-
-function refuseSlotRetired(data: SlotRetiredData, detail: string): never {
-	const error = errors.wrap(ErrSlotRetired, detail)
-	slotRetiredData.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)
-}
-
-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)
-}
-
-function slotRetiredOf(error: Error): SlotRetiredData | undefined {
-	return slotRetiredData.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,
-	ExhaustedData,
-	LeaseRefusal,
-	OverWidthData,
-	RefillNeededData,
-	RefusalCause,
-	SlotRetiredData
-}
-export {
-	chainMismatchOf,
-	contentionOf,
-	ErrChainMismatch,
-	ErrContention,
-	ErrExhausted,
-	ErrOverWidth,
-	ErrRefillNeeded,
-	ErrRefused,
-	ErrReplayDiverged,
-	ErrSlotRetired,
-	ErrSpanningCommit,
-	ErrStore,
-	exhaustedOf,
-	isManifestMissing,
-	overWidthOf,
-	refillNeededOf,
-	refusalOf,
-	refuse,
-	refuseChain,
-	refuseExhausted,
-	refuseManifestMissing,
-	refuseOverWidth,
-	refuseSlotRetired,
-	slotRetiredOf,
-	throwContention,
-	throwRefillNeeded,
-	wrapStore
-}

package/src/index.ts

@@ -1,57 +0,0 @@
-/**
- * @bjornpagen/bumbledb-log — braided object-store replication for
- * 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"
-export { braid, braidsOf, serialAtStatementsOf } from "#braids.ts"
-export type { BatchHeader, ChainEntry, DecodedBatch, EncodeHeader, Op } from "#codec.ts"
-export { decodeBatch, encodeBatch, verifyChain } from "#codec.ts"
-export type { Descriptor, SerialStatement, Theory } from "#descriptor.ts"
-export { descriptorOf } from "#descriptor.ts"
-export type { ChainCause, ChainMismatchData, ContentionCause, ContentionData, RefusalCause } from "#errors.ts"
-export {
-	chainMismatchOf,
-	contentionOf,
-	ErrChainMismatch,
-	ErrContention,
-	ErrManifestMissing,
-	ErrRefused,
-	ErrReplayDiverged,
-	ErrSpanningCommit,
-	ErrStore,
-	isManifestMissing,
-	refusalOf
-} from "#errors.ts"
-export type { Generation, StoreKey } from "#keys.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 { CheckpointOrder } from "#vector.ts"
-export { Overflow, Vector } from "#vector.ts"
-export type {
-	Batch,
-	BraidOutcome,
-	Commit,
-	CommitReceipt,
-	CommitSplit,
-	Deposition,
-	Durability,
-	EmptyCommit,
-	Landing,
-	Writer
-} from "#writer.ts"
-export { openWriter } from "#writer.ts"