@bjornpagen/bumbledb 0.19.1 → 0.20.0

package/src/law.ts

@@ -58,6 +58,7 @@ import * as errors from "@superbuilders/errors"
 import type { AnyClosed } from "#closed.ts"
 import { isClosedMember, sealedFieldsOf } from "#closed.ts"
 import type { FaceData } from "#face.ts"
+import type { Same } from "#judgment.ts"
 import type { AnyRelation, RelationFields } from "#relation.ts"
 import type { SchemaRelation, SchemaRelations } from "#schema.ts"
 import { renderStatement, type Statement } from "#statements.ts"
@@ -196,7 +197,7 @@ type WallScan<Comps extends readonly string[], Gens extends string, Pairs extend
 		: WallScan<T, Gens, Pairs>
 	: unknown
 
-type SetEq<A extends string, B extends string> = [A] extends [B] ? ([B] extends [A] ? true : false) : false
+type SetEq<A extends string, B extends string> = Same<A, B>
 
 type KeyEntry = readonly [string, string]
 

package/src/marshal.ts

@@ -28,7 +28,7 @@
  */
 
 import * as errors from "@superbuilders/errors"
-import type { AnyField, ClosedRoster } from "#fields.ts"
+import type { AnyClosedRoster, AnyField } from "#fields.ts"
 import { isIntervalValue, literalShapeError, rosterOf } from "#fields.ts"
 import type { FactValue } from "#native.ts"
 import type { AnyRelation, Fact, FreshKeys, RelationData } from "#relation.ts"
@@ -61,7 +61,7 @@ function isStringIndexed(value: object): value is Readonly<Record<string, unknow
  * violation. `indexOf` is the whole machine (the roster is ≤ 256 rows,
  * engine law — no map is warranted).
  */
-function closedCellOf(context: string, closed: ClosedRoster, name: string): FactValue {
+function closedCellOf(context: string, closed: AnyClosedRoster, name: string): FactValue {
 	const id = closed.handles.indexOf(name)
 	if (id === -1) {
 		throw errors.new(
@@ -71,7 +71,7 @@ function closedCellOf(context: string, closed: ClosedRoster, name: string): Fact
 	return BigInt(id)
 }
 
-function handleOf(context: string, closed: ClosedRoster, cell: FactValue): string {
+function handleOf(context: string, closed: AnyClosedRoster, cell: FactValue): string {
 	if (typeof cell !== "bigint") {
 		throw literalShapeError(context, `a ${closed.name} handle id (bigint)`, cell)
 	}

package/src/native.ts

@@ -17,6 +17,13 @@ type TxHandle = { readonly __brand: "bumbledb.tx" }
 
 type PreparedHandle = { readonly __brand: "bumbledb.prepared" }
 
+/**
+ * The sealed per-theory log codec (`crates/bumbledb-log`): descriptor
+ * parsed once — vocabulary + braid map — beside the fingerprint the wire
+ * pins. Immutable plain data; no lifecycle verbs.
+ */
+type LogCodecHandle = { readonly __brand: "bumbledb.logCodec" }
+
 interface WireMutationReport {
 	readonly submitted: bigint
 	readonly changed: bigint
@@ -131,10 +138,152 @@ type ConditionTreeIr =
 
 type StatementKindTag = "functionality" | "containment" | "capacity"
 
+/**
+ * A log grammar lane's domain outcome: the payload, or a refusal row
+ * whose `kind` is an identity string spelled exactly as
+ * `crates/bumbledb-log` spells it (the `log-identities.json` mint table).
+ */
+type LogResult<T, K extends string> =
+	| { readonly ok: true; readonly value: T }
+	| { readonly ok: false; readonly kind: K; readonly message: string }
+
+/** `DecodeError::identity` — the batch decode refusal identities. */
+type LogBatchDecodeKind =
+	| "Truncated"
+	| "BadMagic"
+	| "Version"
+	| "Flags"
+	| "FingerprintMismatch"
+	| "UnknownBraid"
+	| "UnknownOpKind"
+	| "UnknownRelation"
+	| "ClosedRelation"
+	| "OpRelationOutsideBraid"
+	| "TagMismatch"
+	| "BoolByte"
+	| "InvalidUtf8"
+	| "EmptyInterval"
+	| "IntervalOverflow"
+	| "TrailingBytes"
+
+/** The batch encode refusal identities (`EncodeError`, bridge-spelled). */
+type LogBatchEncodeKind =
+	| "FingerprintMismatch"
+	| "UnknownBraid"
+	| "UnknownRelation"
+	| "ClosedRelation"
+	| "OpRelationOutsideBraid"
+	| "Arity"
+	| "Value"
+	| "TooManyOps"
+	| "TooManyRows"
+
+/** `ManifestError::identity`. */
+type LogManifestKind = "Malformed" | "Version"
+
+/** `CheckpointError::identity`. */
+type LogCheckpointKind = "Malformed" | "Version" | "Overflow" | "UnknownBraid" | "BraidSet"
+
+/** `SidecarError::identity`. */
+type LogSidecarKind = "Malformed" | "Version" | "UnknownBraid" | "Overflow"
+
+/**
+ * The batch header both directions. The codec handle is the fingerprint
+ * authority — the wire never carries one. `braid` is the raw braid id
+ * (the smallest relation id in its component).
+ */
+interface LogBatchHeader {
+	readonly braid: number
+	readonly braidGen: bigint
+	readonly prev: Uint8Array
+	readonly writer: bigint
+	readonly timestamp: bigint
+}
+
+type LogOpKind = "insert" | "delete"
+
+/**
+ * One op inbound to `logEncodeBatch`: rows carry TAGGED values (the
+ * query-literal lane's inbound spelling) so the bridge stays layout-blind
+ * and the codec core is the one judge of every cell.
+ */
+interface LogOpIn {
+	readonly kind: LogOpKind
+	readonly relation: number
+	readonly rows: ReadonlyArray<readonly TaggedValue[]>
+}
+
+/** One decoded op: rows cross exactly as the engine's `ValueOut` walk. */
+interface LogOpOut {
+	readonly kind: LogOpKind
+	readonly relation: number
+	readonly rows: FactValue[][]
+}
+
+interface LogBatch {
+	readonly header: LogBatchHeader
+	readonly ops: readonly LogOpOut[]
+}
+
+interface LogBraidComponent {
+	readonly braid: number
+	readonly relations: readonly number[]
+}
+
+/** The braid decomposition + serial-at statement ids of one theory. */
+interface LogBraids {
+	readonly components: readonly LogBraidComponent[]
+	readonly serialAt: readonly number[]
+}
+
+/** The manifest document: an absent `checkpoint` is the store-birth null arm. */
+interface LogManifestDoc {
+	readonly fingerprint: Uint8Array
+	readonly checkpoint?: Uint8Array
+}
+
+interface LogCheckpointHead {
+	readonly braid: number
+	readonly g: bigint
+	readonly hash: Uint8Array
+	readonly ts: bigint
+}
+
+/** The `ckpt/{digest}` document. Derived facts (digest, vector sum) stay derived. */
+interface LogCheckpointDoc {
+	readonly braids: readonly LogCheckpointHead[]
+	readonly catalog: Uint8Array
+	readonly writer: bigint
+	readonly prev?: Uint8Array
+}
+
+interface LogChainEntry {
+	readonly braid: number
+	readonly g: bigint
+	readonly prev: Uint8Array
+	readonly ts: bigint
+}
+
+interface LogPendingBatch {
+	readonly braid: number
+	readonly slot: bigint
+	readonly bytes: Uint8Array
+}
+
+/** The chain sidecar document: an absent `pending` is the `Settled` arm. */
+interface LogChain {
+	readonly entries: readonly LogChainEntry[]
+	readonly pending?: LogPendingBatch
+}
+
 interface ManifestField {
 	readonly name: string
 	readonly id: number
 	readonly valueType: ValueTypeSpec
+	/** The field's fresh attribute, straight off the declared spec; a closed relation's synthetic `id` slot is never fresh. */
+	readonly fresh: boolean
+	/** The field's host newtype name off the declared spec; a closed relation's synthetic `id` slot carries the handle newtype. Absent on a bare column. */
+	readonly newtype?: string
 }
 
 interface ManifestRow {
@@ -317,6 +466,13 @@ interface Native {
 
 	dbGeneration(db: DbHandle): bigint
 
+	/**
+	 * blake3 over the canonical catalog enumeration — the replication
+	 * equality oracle: equal digests imply identical judged content
+	 * regardless of page layout or allocation history.
+	 */
+	dbCatalogDigest(db: DbHandle): Uint8Array
+
 	dbFromInstance(path: string, instance: OwnedHandle): Promise<DbHandle>
 
 	/**
@@ -408,9 +564,37 @@ interface Native {
 	): FactValue[] | null
 	ownedPrepare(instance: OwnedHandle, query: ParsedQuery): PrepareResult
 	ownedExecute(prepared: PreparedHandle, instance: OwnedHandle, params: readonly QueryParam[]): FactValue[][]
+
+	logCodec(descriptor: SealedDescriptor): LogCodecHandle
+
+	logBraidsOf(descriptor: SealedDescriptor): LogBraids
+
+	logEncodeBatch(
+		handle: LogCodecHandle,
+		header: LogBatchHeader,
+		ops: readonly LogOpIn[]
+	): LogResult<Uint8Array, LogBatchEncodeKind>
+
+	logDecodeBatch(handle: LogCodecHandle, bytes: Uint8Array): LogResult<LogBatch, LogBatchDecodeKind>
+
+	logParseManifest(bytes: Uint8Array): LogResult<LogManifestDoc, LogManifestKind>
+
+	logRenderManifest(doc: LogManifestDoc): Uint8Array
+
+	logParseCheckpoint(handle: LogCodecHandle, bytes: Uint8Array): LogResult<LogCheckpointDoc, LogCheckpointKind>
+
+	logRenderCheckpoint(handle: LogCodecHandle, doc: LogCheckpointDoc): Uint8Array
+
+	logParseSidecar(handle: LogCodecHandle, bytes: Uint8Array): LogResult<LogChain, LogSidecarKind>
+
+	logRenderSidecar(handle: LogCodecHandle, chain: LogChain): Uint8Array
+
+	logParseCkptScratch(bytes: Uint8Array): Uint8Array | null
+
+	logRenderCkptScratch(digest: Uint8Array): Uint8Array
 }
 
-const SHIPPED_PLATFORMS = ["darwin-arm64", "linux-arm64"] as const
+const SHIPPED_PLATFORMS = ["darwin-arm64", "linux-arm64", "linux-x64"] as const
 
 const requireNative = createRequire(import.meta.url)
 
@@ -468,6 +652,109 @@ function internalDescriptor(spec: SchemaSpec): SealedDescriptor {
 	})
 }
 
+/**
+ * @internal the sealed per-theory log codec off the `DescriptorWire` —
+ * one implementation of the protocol grammar (`crates/bumbledb-log`),
+ * lent to the replication driver (`@bjornpagen/bumbledb-log`). Not SDK
+ * API; the export is deliberately undocumented in the package surface.
+ */
+function internalLogCodec(descriptor: SealedDescriptor): LogCodecHandle {
+	return bridged("bumbledb-log codec", function sealCodec() {
+		return binding.logCodec(descriptor)
+	})
+}
+
+/**
+ * @internal the braid decomposition + serial-at statement ids, riding
+ * the same `DescriptorWire`; the driver caches the result per theory
+ * beside the codec handle. Not SDK API.
+ */
+function internalLogBraidsOf(descriptor: SealedDescriptor): LogBraids {
+	return bridged("bumbledb-log braids", function deriveBraids() {
+		return binding.logBraidsOf(descriptor)
+	})
+}
+
+/** @internal batch encode through the sealed codec. Not SDK API. */
+function internalLogEncodeBatch(
+	handle: LogCodecHandle,
+	header: LogBatchHeader,
+	ops: readonly LogOpIn[]
+): LogResult<Uint8Array, LogBatchEncodeKind> {
+	return bridged("bumbledb-log encode", function encodeBatch() {
+		return binding.logEncodeBatch(handle, header, ops)
+	})
+}
+
+/** @internal batch decode through the sealed codec. Not SDK API. */
+function internalLogDecodeBatch(handle: LogCodecHandle, bytes: Uint8Array): LogResult<LogBatch, LogBatchDecodeKind> {
+	return bridged("bumbledb-log decode", function decodeBatch() {
+		return binding.logDecodeBatch(handle, bytes)
+	})
+}
+
+/** @internal manifest document parse — grammar only, no IO. Not SDK API. */
+function internalLogParseManifest(bytes: Uint8Array): LogResult<LogManifestDoc, LogManifestKind> {
+	return bridged("bumbledb-log manifest parse", function parseManifest() {
+		return binding.logParseManifest(bytes)
+	})
+}
+
+/** @internal the manifest's one encoding, byte-exact for CAS bodies. Not SDK API. */
+function internalLogRenderManifest(doc: LogManifestDoc): Uint8Array {
+	return bridged("bumbledb-log manifest render", function renderManifest() {
+		return binding.logRenderManifest(doc)
+	})
+}
+
+/** @internal checkpoint document parse against the theory's braids. Not SDK API. */
+function internalLogParseCheckpoint(
+	handle: LogCodecHandle,
+	bytes: Uint8Array
+): LogResult<LogCheckpointDoc, LogCheckpointKind> {
+	return bridged("bumbledb-log checkpoint parse", function parseCheckpoint() {
+		return binding.logParseCheckpoint(handle, bytes)
+	})
+}
+
+/** @internal checkpoint document render. Not SDK API. */
+function internalLogRenderCheckpoint(handle: LogCodecHandle, doc: LogCheckpointDoc): Uint8Array {
+	return bridged("bumbledb-log checkpoint render", function renderCheckpoint() {
+		return binding.logRenderCheckpoint(handle, doc)
+	})
+}
+
+/** @internal chain sidecar parse — the fs half stays in the driver. Not SDK API. */
+function internalLogParseSidecar(handle: LogCodecHandle, bytes: Uint8Array): LogResult<LogChain, LogSidecarKind> {
+	return bridged("bumbledb-log sidecar parse", function parseSidecar() {
+		return binding.logParseSidecar(handle, bytes)
+	})
+}
+
+/** @internal chain sidecar render. Not SDK API. */
+function internalLogRenderSidecar(handle: LogCodecHandle, chain: LogChain): Uint8Array {
+	return bridged("bumbledb-log sidecar render", function renderSidecar() {
+		return binding.logRenderSidecar(handle, chain)
+	})
+}
+
+/**
+ * @internal the digest a scratch-lease body names, or null — the refusal
+ * is undifferentiated by law. Not SDK API.
+ */
+function internalLogParseCkptScratch(bytes: Uint8Array): Uint8Array | null {
+	return bridged("bumbledb-log scratch parse", function parseScratch() {
+		return binding.logParseCkptScratch(bytes)
+	})
+}
+
+/** @internal the scratch-lease body: version byte + 32-byte digest. Not SDK API. */
+function internalLogRenderCkptScratch(digest: Uint8Array): Uint8Array {
+	return bridged("bumbledb-log scratch render", function renderScratch() {
+		return binding.logRenderCkptScratch(digest)
+	})
+}
+
 function isEngineThrow(value: unknown): value is { kind: ErrorFamilyKind; message: string } {
 	if (typeof value !== "object" || value === null) {
 		return false
@@ -516,34 +803,43 @@ export type {
 	CmpOpIr,
 	ComparisonIr,
 	ConditionTreeIr,
-	CreateResult,
 	DbHandle,
-	DbOpenResult,
 	ErrorFamilyKind,
 	FactValue,
 	FindTermIr,
-	FoldOpIr,
 	HeadOpIr,
 	HeadTermIr,
 	InstanceHandle,
-	InteriorIr,
 	IntervalValue,
+	LogBatch,
+	LogBatchDecodeKind,
+	LogBatchEncodeKind,
+	LogBatchHeader,
+	LogBraidComponent,
+	LogBraids,
+	LogChain,
+	LogChainEntry,
+	LogCheckpointDoc,
+	LogCheckpointHead,
+	LogCheckpointKind,
+	LogCodecHandle,
+	LogManifestDoc,
+	LogManifestKind,
+	LogOpIn,
+	LogOpKind,
+	LogOpOut,
+	LogPendingBatch,
+	LogResult,
+	LogSidecarKind,
 	Manifest,
-	ManifestField,
-	ManifestRelation,
-	ManifestRow,
-	ManifestStatement,
-	Native,
 	NativeWriteOutcome,
 	OpenKind,
 	OwnedHandle,
 	ParsedQuery,
 	PreparedHandle,
 	PrepareKind,
-	PrepareResult,
 	QueryIr,
 	QueryParam,
-	RecIr,
 	RuleIr,
 	SealedDescriptor,
 	SealedHi,
@@ -568,6 +864,18 @@ export {
 	errorFromThrow,
 	internalBlake3,
 	internalDescriptor,
+	internalLogBraidsOf,
+	internalLogCodec,
+	internalLogDecodeBatch,
+	internalLogEncodeBatch,
+	internalLogParseCheckpoint,
+	internalLogParseCkptScratch,
+	internalLogParseManifest,
+	internalLogParseSidecar,
+	internalLogRenderCheckpoint,
+	internalLogRenderCkptScratch,
+	internalLogRenderManifest,
+	internalLogRenderSidecar,
 	loadNativeBinding,
 	native,
 	SHIPPED_PLATFORMS

package/src/query/atom.ts

@@ -1,5 +1,5 @@
 import * as errors from "@superbuilders/errors"
-import type { AnyField, ClosedIdField, ClosedRoster, Infer, IntervalValue } from "#fields.ts"
+import type { AnyClosedRoster, AnyField, Infer, IntervalValue } from "#fields.ts"
 import type { ClassLookup, ClassRecordOf, SchemaClasses } from "#law.ts"
 import type {
 	AntiJoinOk,
@@ -77,7 +77,7 @@ type FindEntryData =
 interface FindColumn {
 	readonly name: string
 	readonly entry: FindEntryData
-	readonly closed: ClosedRoster | undefined
+	readonly closed: AnyClosedRoster | undefined
 	readonly slot: ClassedField | undefined
 }
 
@@ -140,7 +140,7 @@ type DerivedTable = InteriorData | RecHead
 
 type BindingInput<F extends AnyField> =
 	| Infer<F>
-	| (F extends ClosedIdField ? readonly Infer<F>[] : never)
+	| (F extends { readonly closed: { readonly handles: readonly string[] } } ? readonly Infer<F>[] : never)
 	| (F extends { readonly kind: "interval" } ? bigint : never)
 	| AnyVar
 	| Param<string>
@@ -364,7 +364,7 @@ function not(
  * closed-bound terms — the construction-time validations in
  * `#query/lower.ts` are that ban's runtime twin.
  */
-type NumericVarOk<V extends AnyVar> = V["field"] extends { readonly closed: ClosedRoster }
+type NumericVarOk<V extends AnyVar> = V["field"] extends { readonly closed: AnyClosedRoster }
 	? false
 	: V["field"]["kind"] extends "u64" | "i64"
 		? true
@@ -545,15 +545,10 @@ type CondParamsShape<C> = ShapeOf<CondParams<C>>
 
 export type {
 	AggData,
-	AnyCmp,
 	AnyCond,
-	AnyNotAtom,
-	AnyTreeChild,
 	AtomData,
 	BindingEntry,
 	BindingInput,
-	BindingTermData,
-	BindParams,
 	BindParamsShape,
 	CheckBindings,
 	CheckCond,
@@ -562,31 +557,23 @@ export type {
 	CmpKind,
 	CmpTermData,
 	CondData,
-	CondOkBool,
-	CondParams,
 	CondParamsShape,
 	DerivedTable,
 	FindColumn,
 	FindEntryData,
 	InteriorData,
-	IntervalSide,
 	IntervalVarOk,
 	MatchFields,
 	MatchOwner,
 	MatchShape,
 	NotAtom,
-	NotInteriorAtom,
 	NumericVarOk,
-	OrderSide,
 	ParamUse,
-	PointSide,
 	RecData,
 	RecHandle,
 	RecHead,
 	RuleData,
 	RuleItem,
-	SlotAt,
-	Tree,
-	TreeData
+	Tree
 }
-export { ALLEN, ALLEN_ALL_BITS, allen, and, comparison, eq, ge, gt, le, lt, ne, not, or, pointIn }
+export { ALLEN, allen, and, comparison, eq, ge, gt, le, lt, ne, not, or, pointIn }

package/src/query/find.ts

@@ -4,7 +4,6 @@ import type { IntervalVarOk, NumericVarOk } from "#query/atom.ts"
 import type { AnyVar, MintSlotOf } from "#query/scope.ts"
 
 type FoldOpName = "sum" | "min" | "max" | "pack"
-type AggOpName = "count" | FoldOpName
 
 interface CountAgg {
 	readonly agg: "count"
@@ -90,19 +89,5 @@ type HeadRecordOf<Classes extends SchemaClasses, F extends FindShape> = {
 	readonly [K in keyof F]: F[K] extends AnyVar ? MintSlotOf<Classes, F[K]> : never
 }
 
-export type {
-	Agg,
-	AggOpName,
-	AnyAgg,
-	CheckFind,
-	CheckRecFind,
-	CountAgg,
-	FindEntry,
-	FindEntryOk,
-	FindShape,
-	FindValue,
-	FoldOpName,
-	HeadRecordOf,
-	RowOfFind
-}
+export type { Agg, CheckFind, CheckRecFind, FindEntry, FindShape, HeadRecordOf, RowOfFind }
 export { count, max, min, pack, sum }