@bjornpagen/bumbledb 0.20.2 → 1.0.0

package/src/native.ts

@@ -1,44 +1,47 @@
 import { createRequire } from "node:module"
-import * as errors from "@superbuilders/errors"
+import { Result } from "effect"
+import { NativeLoadError, NativeOperationError, NativeReportedError } from "#errors.ts"
 import type { SchemaSpec, ValueSpec, ValueTypeSpec } from "#spec.ts"
 
-/** The opaque database handle (owns the LMDB environment + exclusive lock). */
+/**
+ * The opaque managed database capability. The native runtime registry —
+ * not this wrapper — owns the LMDB environment, the kernel directory
+ * lock and every session; a retained wrapper after a completed close is
+ * inert. Minted only by the managed handshake
+ * (`runtimeDirectoryDbOpen` → `runtimeDbTake` in #runtime-native.ts).
+ */
 type DbHandle = { readonly __brand: "bumbledb.db" }
 
-type InstanceHandle = { readonly __brand: "bumbledb.instance" }
-
-type WitnessHandle = { readonly __brand: "bumbledb.witness" }
-
-type BuilderHandle = { readonly __brand: "bumbledb.builder" }
-
-type OwnedHandle = { readonly __brand: "bumbledb.owned" }
-
-type TxHandle = { readonly __brand: "bumbledb.tx" }
-
-type PreparedHandle = { readonly __brand: "bumbledb.prepared" }
+/** Admitted owned instance attached through directory publish — not a JS builder. */
 
 /**
- * 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.
+ * The sealed per-theory log schema (`crates/bumbledb-log` successor
+ * lanes): the validated core schema plus its fingerprint, shared by the
+ * command/decision grammar. Immutable plain data; no lifecycle verbs.
  */
-type LogCodecHandle = { readonly __brand: "bumbledb.logCodec" }
-
-interface WireMutationReport {
-	readonly submitted: bigint
-	readonly changed: bigint
-}
-
-type WireFreshRange =
-	| { readonly empty: true }
-	| { readonly empty: false; readonly start: bigint; readonly endExclusive: bigint }
+type LogSchemaHandle = { readonly __brand: "bumbledb.logSchema" }
 
+/** A discrete half-open interval `[start, end)` over u64/i64. */
 interface IntervalValue {
 	readonly start: bigint
 	readonly end: bigint
 }
 
-type FactValue = boolean | bigint | string | Uint8Array | IntervalValue
+/**
+ * A dense-line half-open interval with canonical binary64 endpoints:
+ * NaN-free, strictly ordered; ±Infinity are unbounded endpoints.
+ */
+interface F64IntervalValue {
+	readonly start: number
+	readonly end: number
+}
+
+/**
+ * One marshalled cell. An application-owned Uuid crosses as its
+ * canonical hyphenated UUID string (chapter 32); there is no fresh
+ * range, reservation counter or issuance value anywhere on this wire.
+ */
+type FactValue = boolean | bigint | number | string | Uint8Array | IntervalValue | F64IntervalValue
 
 type TaggedValue = ValueSpec
 
@@ -70,9 +73,32 @@ interface RecIr {
 	readonly rec: readonly RuleIr[]
 }
 
-type HeadTermIr = { readonly kind: "var" } | { readonly kind: "aggregate"; readonly op: HeadOpIr }
+type HeadTermIr =
+	| { readonly kind: "var" }
+	| { readonly kind: "compute" }
+	| { readonly kind: "aggregate"; readonly op: HeadOpIr }
 
-type HeadOpIr = "sum" | "min" | "max" | "count" | "pack"
+type HeadOpIr = "sum" | "mean" | "min" | "max" | "count" | "pack"
+
+/**
+ * The computed-find scalar expression (C05 `FindTerm::Compute(ScalarExpr)`):
+ * exactly the frozen core roster, spelled as the migration plan JSON spells
+ * the same expressions (one grammar, no second evaluator). `var` binds a
+ * rule variable ordinal on this lane.
+ */
+type NumericCastIr = "toF64" | "toF64Exact" | "toI64Exact" | "toU64Exact"
+
+type ScalarExprIr =
+	| { readonly kind: "var"; readonly var: number }
+	| { readonly kind: "literal"; readonly value: TaggedValue }
+	| { readonly kind: "negate"; readonly expr: ScalarExprIr }
+	| { readonly kind: "add"; readonly left: ScalarExprIr; readonly right: ScalarExprIr }
+	| { readonly kind: "subtract"; readonly left: ScalarExprIr; readonly right: ScalarExprIr }
+	| { readonly kind: "multiply"; readonly left: ScalarExprIr; readonly right: ScalarExprIr }
+	| { readonly kind: "divide"; readonly left: ScalarExprIr; readonly right: ScalarExprIr }
+	| { readonly kind: "cast"; readonly cast: NumericCastIr; readonly expr: ScalarExprIr }
+	| { readonly kind: "isNaN"; readonly expr: ScalarExprIr }
+	| { readonly kind: "isFinite"; readonly expr: ScalarExprIr }
 
 interface RuleIr {
 	readonly finds: readonly FindTermIr[]
@@ -81,10 +107,15 @@ interface RuleIr {
 	readonly conditions: readonly ConditionTreeIr[]
 }
 
-type FoldOpIr = { readonly kind: "sum" } | { readonly kind: "min" } | { readonly kind: "max" }
+type FoldOpIr =
+	| { readonly kind: "sum" }
+	| { readonly kind: "mean" }
+	| { readonly kind: "min" }
+	| { readonly kind: "max" }
 
 type FindTermIr =
 	| { readonly kind: "var"; readonly var: number }
+	| { readonly kind: "compute"; readonly expr: ScalarExprIr }
 	| { readonly kind: "count" }
 	| { readonly kind: "aggregate"; readonly op: FoldOpIr; readonly over: number }
 	| { readonly kind: "pack"; readonly over: number }
@@ -95,6 +126,7 @@ type ParsedQuery = QueryIr & { readonly [parsedQueryBrand]: true }
 
 type AggOpIr =
 	| { readonly kind: "sum" }
+	| { readonly kind: "mean" }
 	| { readonly kind: "min" }
 	| { readonly kind: "max" }
 	| { readonly kind: "count" }
@@ -138,150 +170,180 @@ type ConditionTreeIr =
 
 type StatementKindTag = "functionality" | "containment" | "capacity"
 
+// ---------------------------------------------------------------------------
+// Successor log grammar wire (C06 through the C09 bridge). The 0.x
+// braids/codec/manifest/sidecar lanes and their mint tables are deleted.
+// ---------------------------------------------------------------------------
+
 /**
- * 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).
+ * A grammar lane's domain outcome: the payload, or a refusal row whose
+ * `kind` is an identity string spelled exactly as `bumbledb-log`'s
+ * identities emitter spells it (`logIdentities()` / log-identities.json).
  */
 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
+/** `FrameError` kinds (the `frame` identity family). */
+type LogFrameKind =
+	| "limitExceeded"
+	| "lengthOverflow"
+	| "allocation"
+	| "truncated"
+	| "family"
+	| "layout"
+	| "kind"
+	| "tag"
+	| "invalidEpoch"
+	| "stateIdentityMismatch"
+	| "emptyChangeSummary"
+	| "emptyEvidence"
+	| "invalidTerminalStamp"
+	| "invalidPreconditionEvidence"
+	| "invalidPolicy"
+	| "invalidSequence"
+	| "invalidCount"
+	| "trailingBytes"
+
+/** Receipt-row kinds: the frame family plus the foreign-scope refusal. */
+type LogReceiptKind = LogFrameKind | "foreignRow"
+
+/** Command-lane kinds: frame family plus the two command-only arms. */
+type LogCommandKind = LogFrameKind | "core" | "schemaMismatch"
+
+/** Chain-step refusals from the decode-and-verify lane. */
+type LogChainKind = "wrongParent" | "wrongSequence"
+
+/** The complete database scope of every command/receipt/decision. */
+interface LogIdentity {
+	/** Application-owned Uuid, canonical hyphenated UUID. */
+	readonly databaseId: string
+	readonly incarnationId: string
+	/** The core schema fingerprint, 64 lowercase hex characters. */
+	readonly schemaId: string
+}
+
+interface LogStateStamp {
+	readonly incarnation: string
+	readonly dataRevision: bigint
+}
+
+interface LogDecisionStamp {
+	readonly seq: bigint
+	readonly hash: Uint8Array
 }
 
-type LogOpKind = "insert" | "delete"
+type LogCondition = { readonly kind: "unconditional" } | { readonly kind: "exactState"; readonly state: LogStateStamp }
 
-/**
- * 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[]>
+interface LogCommandId {
+	readonly receiptEpoch: bigint
+	readonly requestId: string
 }
 
-/** One decoded op: rows cross exactly as the engine's `ValueOut` walk. */
-interface LogOpOut {
-	readonly kind: LogOpKind
-	readonly relation: number
-	readonly rows: FactValue[][]
+interface LogCommandMetadata {
+	readonly identity: LogIdentity
+	readonly id: LogCommandId
+	readonly condition: LogCondition
 }
 
-interface LogBatch {
-	readonly header: LogBatchHeader
-	readonly ops: readonly LogOpOut[]
+interface LogCommandRef {
+	readonly identity: LogIdentity
+	readonly receiptEpoch: bigint
+	readonly requestId: string
+	readonly digest: Uint8Array
 }
 
-interface LogBraidComponent {
-	readonly braid: number
-	readonly relations: readonly number[]
-}
+type LogOutcomeWire =
+	| { readonly kind: "committed"; readonly added: bigint; readonly removed: bigint; readonly result?: Uint8Array }
+	| { readonly kind: "noChange"; readonly result?: Uint8Array }
+	| { readonly kind: "preconditionFailed"; readonly expected: LogStateStamp; readonly observed: LogStateStamp }
+	| { readonly kind: "invariantRejected"; readonly evidence: Uint8Array }
 
-/** The braid decomposition + serial-at statement ids of one theory. */
-interface LogBraids {
-	readonly components: readonly LogBraidComponent[]
-	readonly serialAt: readonly number[]
+interface LogReceipt {
+	readonly command: LogCommandRef
+	readonly decisionAt: LogDecisionStamp
+	readonly stateAt: LogStateStamp
+	readonly outcome: LogOutcomeWire
 }
 
-/** The manifest document: an absent `checkpoint` is the store-birth null arm. */
-interface LogManifestDoc {
-	readonly fingerprint: Uint8Array
-	readonly checkpoint?: Uint8Array
+interface LogLimits {
+	readonly envelopeBytes: bigint
+	readonly changeBytes: bigint
+	readonly evidenceBytes: bigint
+	readonly resultBytes: bigint
 }
 
-interface LogCheckpointHead {
-	readonly braid: number
-	readonly g: bigint
-	readonly hash: Uint8Array
-	readonly ts: bigint
-}
+type LogAccess =
+	| { readonly kind: "active" }
+	| {
+			readonly kind: "frozen"
+			readonly operation: string
+			readonly intent:
+				| { readonly kind: "erasure" }
+				| { readonly kind: "migration"; readonly planSetDigest: Uint8Array; readonly target: string }
+	  }
 
-/** 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
-}
+type LogLifecycle =
+	| {
+			readonly kind: "live"
+			readonly access: LogAccess
+			readonly decision: LogDecisionStamp
+			readonly state: LogStateStamp
+			readonly receipts: { readonly openEpoch: bigint; readonly retiredThrough: bigint }
+	  }
+	| {
+			readonly kind: "deleted"
+			readonly operation: string
+			readonly reason:
+				| { readonly kind: "erasure" }
+				| {
+						readonly kind: "migrationAborted"
+						readonly sourceDatabase: string
+						readonly sourceIncarnation: string
+						readonly planSetDigest: Uint8Array
+				  }
+	  }
 
-interface LogChainEntry {
-	readonly braid: number
-	readonly g: bigint
-	readonly prev: Uint8Array
-	readonly ts: bigint
-}
+type LogActivation =
+	| { readonly kind: "notActivated" }
+	| {
+			readonly kind: "activated"
+			readonly operation: string
+			readonly targetGenesis: Uint8Array
+			readonly cause:
+				| { readonly kind: "create" }
+				| { readonly kind: "restore" }
+				| { readonly kind: "migration"; readonly planSetDigest: Uint8Array }
+	  }
 
-interface LogPendingBatch {
-	readonly braid: number
-	readonly slot: bigint
-	readonly bytes: Uint8Array
+interface LogAuthority {
+	readonly identity: LogIdentity
+	readonly revision: bigint
+	readonly lifecycle: LogLifecycle
+	readonly activation: LogActivation
 }
 
-/** The chain sidecar document: an absent `pending` is the `Settled` arm. */
-interface LogChain {
-	readonly entries: readonly LogChainEntry[]
-	readonly pending?: LogPendingBatch
+type LogGenesisProvenance =
+	| { readonly kind: "create" }
+	| { readonly kind: "restore"; readonly sourceEvidence: Uint8Array }
+	| {
+			readonly kind: "migration"
+			readonly sourceDatabase: string
+			readonly sourceIncarnation: string
+			readonly planSetDigest: Uint8Array
+	  }
+
+interface LogGenesis {
+	readonly identity: LogIdentity
+	readonly initialApplicationDigest: Uint8Array
+	readonly initialSystemDigest: Uint8Array
+	readonly provenance: LogGenesisProvenance
 }
 
 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
 }
@@ -299,17 +361,6 @@ interface ManifestRelation {
 	readonly extension?: readonly ManifestRow[]
 }
 
-interface ManifestStatement {
-	readonly id: number
-	readonly kind: StatementKindTag
-	readonly spelling: string
-}
-
-interface Manifest {
-	readonly relations: readonly ManifestRelation[]
-	readonly statements: readonly ManifestStatement[]
-}
-
 interface SealedSide {
 	readonly relation: number
 	readonly projection: readonly number[]
@@ -383,40 +434,12 @@ type Violation =
 			readonly facts: readonly ViolationFact[]
 	  }
 
-type CreateResult =
-	| { readonly tag: "accepted"; readonly db: DbHandle }
-	| { readonly tag: "rejected"; readonly violations: readonly Violation[] }
-	| { readonly tag: "schemaError"; readonly message: string }
-	| { readonly tag: "newtypeMismatch"; readonly message: string }
-
-/**
- * `dbOpen`'s domain outcome. `schemaError` spans both spec
- * resolution (unresolvable names, banned spellings — every issue in one
- * message) and schema validation at the declaration boundary;
- * `newtypeMismatch` is the coherence wall's own kind; `fingerprintMismatch`
- * is `dbOpen`'s stored-theory refusal.
- */
-type DbOpenResult =
-	| { readonly ok: true; readonly db: DbHandle }
-	| {
-			readonly ok: false
-			readonly kind: "schemaError" | "newtypeMismatch" | "fingerprintMismatch"
-			readonly message: string
-	  }
-
-type NativeWriteOutcome =
-	| { readonly tag: "accepted"; readonly generation: bigint }
-	| { readonly tag: "rejected"; readonly violations: readonly Violation[] }
-	| { readonly tag: "abandoned" }
-	| { readonly tag: "moved"; readonly witnessed: bigint; readonly current: bigint }
-
-type AdmitResult =
-	| { readonly tag: "accepted"; readonly value: OwnedHandle }
-	| { readonly tag: "rejected"; readonly violations: readonly Violation[] }
-
-type PrepareResult =
-	| { readonly ok: true; readonly prepared: PreparedHandle }
-	| { readonly ok: false; readonly kind: "irError"; readonly message: string }
+// The managed create/open outcome is `ManagedDbOutcome` in
+// #runtime-native.ts (accepted | rejected | refused); reads, writes and
+// queries are worker-affine session verbs there too. The historical
+// raw-pointer `dbRead`/`dbWrite`/`tx*`/`instance*`/`prepared*` synchronous
+// surface — a JS callback inside a native transaction — is deleted (P06),
+// as are the fresh/reserve issuance verbs (`WireFreshRange`).
 
 type ErrorFamilyKind =
 	| "formatMismatch"
@@ -431,7 +454,6 @@ type ErrorFamilyKind =
 	| "schema"
 	| "validation"
 	| "factShape"
-	| "freshExhausted"
 	| "closedRelationWrite"
 	| "commitSync"
 	| "transactionPoisoned"
@@ -441,201 +463,124 @@ type ErrorFamilyKind =
 	| "capacityRayMeasure"
 	| "derivedBudgetExceeded"
 	| "overflow"
+	| "scalar"
 	| "resultBytesOverflow"
 	| "corruption"
+	| "store"
 
 type AdmissionTag = "accepted" | "rejected"
 type WriteTag = "accepted" | "rejected" | "abandoned" | "moved"
-type OpenKind = "schemaError" | "newtypeMismatch" | "fingerprintMismatch"
+type OpenKind = "schemaError" | "newtypeMismatch" | "fingerprintMismatch" | "destinationExists"
 type PrepareKind = "irError"
 
 interface Native {
 	engineVersion(): string
 
+	/** Small identity-sized inputs only; bulk hashing rides `runtimeHash`. */
 	blake3Hash(data: Uint8Array): Uint8Array
 
 	descriptor(spec: SchemaSpec): SealedDescriptor
 
-	dbCreate(path: string, spec: SchemaSpec): Promise<CreateResult>
-
-	dbOpen(path: string, spec: SchemaSpec): Promise<DbOpenResult>
-
-	dbManifest(db: DbHandle): Manifest
-
-	dbFingerprint(db: DbHandle): string
-
-	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>
-
-	/**
-	 * Runs `callback` synchronously inside the engine read lease. The
-	 * instance handle is invalid after the callback returns; the witness
-	 * handle is a clone and may escape.
-	 */
-	dbRead<R>(db: DbHandle, callback: (instance: InstanceHandle, witness: WitnessHandle) => R): R
-	instanceGeneration(instance: InstanceHandle): bigint
-	instanceScan(instance: InstanceHandle, relationId: number): FactValue[][]
-
-	instanceCount(instance: InstanceHandle, relationId: number): bigint
-	instanceContains(instance: InstanceHandle, relationId: number, values: readonly FactValue[]): boolean
-	instanceGet(
-		instance: InstanceHandle,
-		relationId: number,
-		keyStatementId: number,
-		keyValues: readonly FactValue[]
-	): FactValue[] | null
-	instancePrepare(instance: InstanceHandle, query: ParsedQuery): PrepareResult
-	witnessClose(witness: WitnessHandle): void
+	// --- successor log grammar (small frames; command/decision lanes are
+	// executor verbs in #runtime-native.ts) ---
 
-	dbWrite(db: DbHandle, callback: (tx: TxHandle) => boolean): NativeWriteOutcome
+	logIdentities(): string
 
-	dbWriteFrom(db: DbHandle, witness: WitnessHandle, callback: (tx: TxHandle) => boolean): NativeWriteOutcome
-	/**
-	 * Records a collection of inserts into the delta; returns the engine
-	 * `{ submitted, changed }` report. `cells` is ONE flat row-major array
-	 * (length rows×arity) in sealed field order, and `rows` is the EXPLICIT
-	 * row count the caller states — the one collection crossing: the JS side
-	 * alone knows N when the roster is fieldless (N nullary facts project to 0 cells, so no
-	 * derivation can recover N), and the bridge verifies
-	 * `cells.length === rows × arity` exactly against its resident sealed
-	 * roster before building the engine's shape-proved collection in a
-	 * single pass. Empty (`rows === 0n`, no cells) is lawful and still a
-	 * mutation. Nothing is judged until commit; shape violations throw
-	 * typed, naming relation and field.
-	 */
-	txInsert(tx: TxHandle, relationId: number, rows: bigint, cells: readonly FactValue[]): WireMutationReport
+	logSchema(spec: SchemaSpec): LogSchemaHandle
 
-	txDelete(tx: TxHandle, relationId: number, rows: bigint, cells: readonly FactValue[]): WireMutationReport
+	logSchemaFingerprint(schema: LogSchemaHandle): string
 
-	txContains(tx: TxHandle, relationId: number, values: readonly FactValue[]): boolean
+	logReceiptKey(id: LogCommandId): Uint8Array
 
-	txGet(tx: TxHandle, relationId: number, keyStatementId: number, keyValues: readonly FactValue[]): FactValue[] | null
+	logReceiptEncode(receipt: LogReceipt, limits: LogLimits): LogResult<Uint8Array, LogReceiptKind>
 
-	txReserve(tx: TxHandle, relationId: number, fieldId: number, count: bigint): WireFreshRange
+	logReceiptDecode(
+		expected: { readonly identity: LogIdentity; readonly receiptEpoch: bigint; readonly requestId: string },
+		bytes: Uint8Array,
+		limits: LogLimits
+	): LogResult<LogReceipt, LogReceiptKind>
 
-	dbPrepare(db: DbHandle, query: ParsedQuery): PrepareResult
+	logReceiptDecodeAt(id: LogCommandId, bytes: Uint8Array, limits: LogLimits): LogResult<LogReceipt, LogReceiptKind>
 
-	preparedExecute(prepared: PreparedHandle, instance: InstanceHandle, params: readonly QueryParam[]): FactValue[][]
+	logControlEncode(authority: LogAuthority, cap: bigint): LogResult<Uint8Array, LogFrameKind>
 
-	preparedClose(prepared: PreparedHandle): void
+	logControlDecode(bytes: Uint8Array, cap: bigint): LogResult<LogAuthority, LogFrameKind>
 
-	instanceBuilderNew(spec: SchemaSpec): BuilderHandle
+	logGenesisEncode(record: LogGenesis, cap: bigint): LogResult<Uint8Array, LogFrameKind>
 
-	instanceBuilderLoad(
-		builder: BuilderHandle,
-		relationId: number,
-		rows: bigint,
-		cells: readonly FactValue[]
-	): WireMutationReport
-	instanceBuilderDelete(
-		builder: BuilderHandle,
-		relationId: number,
-		rows: bigint,
-		cells: readonly FactValue[]
-	): WireMutationReport
-	instanceBuilderReserve(builder: BuilderHandle, relationId: number, fieldId: number, count: bigint): WireFreshRange
-	instanceBuilderContains(builder: BuilderHandle, relationId: number, values: readonly FactValue[]): boolean
-	instanceBuilderGet(
-		builder: BuilderHandle,
-		relationId: number,
-		keyStatementId: number,
-		keyValues: readonly FactValue[]
-	): FactValue[] | null
-	instanceBuilderClose(builder: BuilderHandle): void
-	instanceBuilderAdmit(builder: BuilderHandle): Promise<AdmitResult>
-	ownedInstanceClose(instance: OwnedHandle): void
-	ownedScan(instance: OwnedHandle, relationId: number): FactValue[][]
+	logGenesisDecode(bytes: Uint8Array, cap: bigint): LogResult<LogGenesis, LogFrameKind>
 
-	ownedCount(instance: OwnedHandle, relationId: number): bigint
-	ownedContains(instance: OwnedHandle, relationId: number, values: readonly FactValue[]): boolean
-	ownedGet(
-		instance: OwnedHandle,
-		relationId: number,
-		keyStatementId: number,
-		keyValues: readonly FactValue[]
-	): 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
+	logGenesisStamp(record: LogGenesis, cap: bigint): LogResult<LogDecisionStamp, LogFrameKind>
 
-	logParseCkptScratch(bytes: Uint8Array): Uint8Array | null
-
-	logRenderCkptScratch(digest: Uint8Array): Uint8Array
+	logBlankDigests(): { readonly application: Uint8Array; readonly system: Uint8Array }
 }
 
 const SHIPPED_PLATFORMS = ["darwin-arm64", "linux-arm64", "linux-x64"] as const
 
 const requireNative = createRequire(import.meta.url)
 
-interface NativeBinding extends Native {
-	dbClose(db: DbHandle): void
+type NativeBinding = Native
+
+function ensureNativeBinding(): NativeBinding {
+	const loaded = bindingCache
+	if (loaded !== undefined) {
+		return loaded
+	}
+	const next = loadNativeBinding(process.platform, process.arch)
+	bindingCache = next
+	return next
+}
+
+/** Lazy singleton: the addon loads on first native access, not module evaluation. */
+const native: NativeBinding = new Proxy({} as NativeBinding, {
+	get(_target, property, receiver) {
+		return Reflect.get(ensureNativeBinding(), property, receiver)
+	},
+	set(_target, property, value) {
+		return Reflect.set(ensureNativeBinding(), property, value)
+	}
+})
+
+let bindingCache: NativeBinding | undefined
+
+function nativeBindingIsLoaded(): boolean {
+	return bindingCache !== undefined
 }
 
 function loadNativeBinding(platform: string, arch: string): NativeBinding {
 	const platformPackage = `@bjornpagen/bumbledb-${platform}-${arch}`
 
-	const present = errors.trySync(() => requireNative.resolve(`${platformPackage}/package.json`))
-	if (present.error) {
-		throw errors.wrap(
-			present.error,
-			`no native binary for ${platform}-${arch}: @bjornpagen/bumbledb ships ${SHIPPED_PLATFORMS.join(", ")} only`
-		)
+	const present = Result.try(() => requireNative.resolve(`${platformPackage}/package.json`))
+	if (Result.isFailure(present)) {
+		throw new NativeLoadError({
+			package: platformPackage,
+			operation: "resolve",
+			message: `no native binary for ${platform}-${arch}: @bjornpagen/bumbledb ships ${SHIPPED_PLATFORMS.join(", ")} only`,
+			cause: present.failure
+		})
 	}
 
-	const loaded = errors.trySync(() => requireNative(platformPackage))
-	if (loaded.error) {
-		throw errors.wrap(loaded.error, `load the ${platformPackage} native binary (package present but unloadable)`)
+	const loaded = Result.try(() => requireNative(platformPackage))
+	if (Result.isFailure(loaded)) {
+		throw new NativeLoadError({
+			package: platformPackage,
+			operation: "load",
+			message: `load the ${platformPackage} native binary (package present but unloadable)`,
+			cause: loaded.failure
+		})
 	}
-	return loaded.data
-}
-
-const binding: NativeBinding = loadNativeBinding(process.platform, process.arch)
-const native: Native = binding
-
-function dbClose(db: DbHandle): void {
-	binding.dbClose(db)
+	return loaded.success
 }
 
 /**
  * @internal blake3 of the given bytes via the resident native binding —
  * the engine's own hash, lent to the replication driver
  * (`@bjornpagen/bumbledb-log`). Not SDK API; the export is deliberately
- * undocumented in the package surface.
+ * undocumented in the package surface. Small identity-sized inputs only.
  */
 function internalBlake3(data: Uint8Array): Uint8Array {
 	return bridged("bumbledb blake3", function hashBytes() {
-		return binding.blake3Hash(data)
+		return ensureNativeBinding().blake3Hash(data)
 	})
 }
 
@@ -648,110 +593,28 @@ function internalBlake3(data: Uint8Array): Uint8Array {
  */
 function internalDescriptor(spec: SchemaSpec): SealedDescriptor {
 	return bridged("bumbledb descriptor", function sealSpec() {
-		return binding.descriptor(spec)
+		return ensureNativeBinding().descriptor(spec)
 	})
 }
 
 /**
- * @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.
+ * @internal the successor identity table emitted by the log core's one
+ * speller (`bumbledb_log::identities::emit`). Not SDK API.
  */
-function internalLogCodec(descriptor: SealedDescriptor): LogCodecHandle {
-	return bridged("bumbledb-log codec", function sealCodec() {
-		return binding.logCodec(descriptor)
+function internalLogIdentities(): string {
+	return bridged("bumbledb-log identities", function emitIdentities() {
+		return ensureNativeBinding().logIdentities()
 	})
 }
 
 /**
- * @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.
+ * @internal the sealed per-theory log schema off the same `SchemaSpec`
+ * every other lane speaks — one validated core schema, lent to the
+ * replication driver (`@bjornpagen/bumbledb-log`). 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 internalLogSchema(spec: SchemaSpec): LogSchemaHandle {
+	return bridged("bumbledb-log schema", function sealSchema() {
+		return ensureNativeBinding().logSchema(spec)
 	})
 }
 
@@ -768,79 +631,70 @@ function errorFromThrow(caught: unknown): Error {
 		return caught
 	}
 	if (isEngineThrow(caught)) {
-		const error = errors.new(`bumbledb ${caught.kind}: ${caught.message}`)
-		Object.defineProperty(error, "kind", { value: caught.kind, enumerable: true })
-		return error
+		return new NativeReportedError({
+			kind: caught.kind,
+			message: `bumbledb ${caught.kind}: ${caught.message}`,
+			cause: caught
+		})
 	}
-	return errors.new(String(caught))
+	return new NativeReportedError({ kind: "Unknown", message: String(caught), cause: caught })
 }
 
 function bridged<T>(context: string, run: () => T): T {
 	try {
 		return run()
 	} catch (caught) {
-		const inner = errorFromThrow(caught)
-		throw errors.wrap(inner, `${context}: ${inner.message}`)
-	}
-}
-
-async function bridgedAsync<T>(context: string, run: () => Promise<T>): Promise<T> {
-	try {
-		return await run()
-	} catch (caught) {
-		const inner = errorFromThrow(caught)
-		throw errors.wrap(inner, `${context}: ${inner.message}`)
+		if (caught instanceof Error) throw caught
+		throw new NativeOperationError({ operation: context, cause: caught })
 	}
 }
 
 export type {
 	AdmissionTag,
-	AdmitResult,
 	AggOpIr,
 	AtomIr,
 	AtomSourceIr,
-	BuilderHandle,
 	CmpOpIr,
 	ComparisonIr,
 	ConditionTreeIr,
 	DbHandle,
 	ErrorFamilyKind,
+	F64IntervalValue,
 	FactValue,
 	FindTermIr,
 	HeadOpIr,
 	HeadTermIr,
-	InstanceHandle,
 	IntervalValue,
-	LogBatch,
-	LogBatchDecodeKind,
-	LogBatchEncodeKind,
-	LogBatchHeader,
-	LogBraidComponent,
-	LogBraids,
-	LogChain,
-	LogChainEntry,
-	LogCheckpointDoc,
-	LogCheckpointHead,
-	LogCheckpointKind,
-	LogCodecHandle,
-	LogManifestDoc,
-	LogManifestKind,
-	LogOpIn,
-	LogOpKind,
-	LogOpOut,
-	LogPendingBatch,
+	LogAccess,
+	LogActivation,
+	LogAuthority,
+	LogChainKind,
+	LogCommandId,
+	LogCommandKind,
+	LogCommandMetadata,
+	LogCommandRef,
+	LogCondition,
+	LogDecisionStamp,
+	LogFrameKind,
+	LogGenesis,
+	LogGenesisProvenance,
+	LogIdentity,
+	LogLifecycle,
+	LogLimits,
+	LogOutcomeWire,
+	LogReceipt,
+	LogReceiptKind,
 	LogResult,
-	LogSidecarKind,
-	Manifest,
-	NativeWriteOutcome,
+	LogSchemaHandle,
+	LogStateStamp,
+	NumericCastIr,
 	OpenKind,
-	OwnedHandle,
 	ParsedQuery,
-	PreparedHandle,
 	PrepareKind,
 	QueryIr,
 	QueryParam,
 	RuleIr,
+	ScalarExprIr,
 	SealedDescriptor,
 	SealedHi,
 	SealedSide,
@@ -849,34 +703,19 @@ export type {
 	StatementKindTag,
 	TaggedValue,
 	TermIr,
-	TxHandle,
 	Violation,
 	ViolationFact,
-	WireFreshRange,
-	WireMutationReport,
-	WitnessHandle,
 	WriteTag
 }
 export {
 	bridged,
-	bridgedAsync,
-	dbClose,
 	errorFromThrow,
 	internalBlake3,
 	internalDescriptor,
-	internalLogBraidsOf,
-	internalLogCodec,
-	internalLogDecodeBatch,
-	internalLogEncodeBatch,
-	internalLogParseCheckpoint,
-	internalLogParseCkptScratch,
-	internalLogParseManifest,
-	internalLogParseSidecar,
-	internalLogRenderCheckpoint,
-	internalLogRenderCkptScratch,
-	internalLogRenderManifest,
-	internalLogRenderSidecar,
+	internalLogIdentities,
+	internalLogSchema,
 	loadNativeBinding,
 	native,
+	nativeBindingIsLoaded,
 	SHIPPED_PLATFORMS
 }