@bjornpagen/bumbledb 0.14.0 → 0.17.0

package/dist/native.d.ts

@@ -1,63 +1,30 @@
 import type { SchemaSpec, ValueSpec, ValueTypeSpec } from "./spec.js";
-/**
- * The complete typed surface of the bumbledb-node napi bridge. ALL FFI
- * typing lives in this one file — no other module may know the `.node`
- * artifact exists. The bridge is a dumb bridge (PRD-04): descriptor in as
- * data, queries in as IR data, facts in/out as value rows, rejections out as
- * structured violation sets; anything smart lives in the SDK or the engine.
- *
- * Marshaling law: fact rows cross as NATURAL JS values, schema-directed by
- * the engine descriptor (`boolean ⇄ bool`, `bigint ⇄ u64/i64`,
- * `string ⇄ str`, `Uint8Array ⇄ bytes<N>`, `{ start, end }` ⇄ interval);
- * IR, spec, and query params cross as TAGGED plain objects mirroring the
- * engine's own data enums 1:1. Every u64/i64 crosses as `bigint`, never
- * `number`. Domain outcomes (schema errors, fingerprint mismatches,
- * rejections, generation moves, IR errors) are DATA; marshaling/shape
- * violations and use-after-close THROW.
- */
 /** The opaque database handle (owns the LMDB environment + exclusive lock). */
 type DbHandle = {
     readonly __brand: "bumbledb.db";
 };
-/** One live MVCC read snapshot. */
-type SnapshotHandle = {
-    readonly __brand: "bumbledb.snapshot";
+type InstanceHandle = {
+    readonly __brand: "bumbledb.instance";
 };
-/**
- * One exhumed store — the read-only, theory-less open (engine 70-api.md
- * § exhume). Lifetimes are disposables (ruled 2026-07-23, R12):
- * `exhumeClose` is the deterministic teardown the SDK's `Symbol.dispose`
- * rides — releasing the environment (and the store's exclusive lock)
- * scope-shaped, never a GC race; the engine-side drop remains the
- * reclamation-only backstop for a collected-but-undisposed handle.
- */
-type ExhumeHandle = {
-    readonly __brand: "bumbledb.exhume";
+type WitnessHandle = {
+    readonly __brand: "bumbledb.witness";
+};
+type BuilderHandle = {
+    readonly __brand: "bumbledb.builder";
+};
+type OwnedHandle = {
+    readonly __brand: "bumbledb.owned";
 };
-/**
- * One live write transaction — the submitted delta with the engine's
- * final-state point-read view. Spent by `txCommit`/`txAbort`.
- */
 type TxHandle = {
     readonly __brand: "bumbledb.tx";
 };
-/** One prepared query (plan pinned at prepare). */
 type PreparedHandle = {
     readonly __brand: "bumbledb.prepared";
 };
-/**
- * Engine mutation report as it crosses napi: both counts are engine
- * values, never reconstructed from JS length.
- */
 interface WireMutationReport {
     readonly submitted: bigint;
     readonly changed: bigint;
 }
-/**
- * Engine fresh-id range as it crosses napi. Empty cannot yield a start —
- * `start` is a minted id only on the nonempty arm. (C wires empty as
- * `{ start: 0, end_exclusive: 0 }` at that boundary only.)
- */
 type WireFreshRange = {
     readonly empty: true;
 } | {
@@ -65,37 +32,16 @@ type WireFreshRange = {
     readonly start: bigint;
     readonly endExclusive: bigint;
 };
-/** A half-open interval `[start, end)` as it crosses the boundary. */
 interface IntervalValue {
     readonly start: bigint;
     readonly end: bigint;
 }
-/**
- * One fact-row cell as a natural JS value. The expected engine type comes
- * from the schema descriptor (marshaling is schema-directed, never guessed):
- * `boolean` for bool, `bigint` for u64/i64, `string` for str, `Uint8Array`
- * for bytes<N> (width-checked), `{ start, end }` for intervals.
- */
 type FactValue = boolean | bigint | string | Uint8Array | IntervalValue;
-/**
- * One tagged engine value — the 1:1 mirror of `bumbledb::Value` for the
- * positions no schema field directs (IR literals, query params).
- */
 type TaggedValue = ValueSpec;
-/**
- * One positional execution argument: a tagged scalar, or a param SET
- * (`Term.paramSet` positions) as `{ kind: "set", values }`.
- */
 type QueryParam = TaggedValue | {
     readonly kind: "set";
     readonly values: readonly TaggedValue[];
 };
-/**
- * The IR mirror (`bumbledb::ir`, 1:1): relations, fields, interiors, and
- * params by NUMERIC id — the SDK resolves names through the manifest and
- * sends ids; the bridge never sees names in queries. Q1 is a tagged sum:
- * CQ carries no rec; Reach carries `rec` by value.
- */
 type QueryIr = {
     readonly kind: "cq";
     readonly interiors: readonly InteriorIr[];
@@ -108,34 +54,28 @@ type QueryIr = {
     readonly head: readonly HeadTermIr[];
     readonly rules: readonly RuleIr[];
 };
-/** One named interior: the head shape its rules align against, and the rules. */
 interface InteriorIr {
     readonly head: readonly HeadTermIr[];
     readonly rules: readonly RuleIr[];
 }
-/** The linear rec on a Reach query: shared head, base arms, rec arms. */
 interface RecIr {
     readonly head: readonly HeadTermIr[];
     readonly base: readonly RuleIr[];
     readonly rec: readonly RuleIr[];
 }
-/** One head position: a plain variable slot or an aggregate-op kind. */
 type HeadTermIr = {
     readonly kind: "var";
 } | {
     readonly kind: "aggregate";
     readonly op: HeadOpIr;
 };
-/** The var-free aggregate-op kind at a head position. */
 type HeadOpIr = "sum" | "min" | "max" | "count" | "pack";
-/** One rule: conjunctive body, anti-join atoms, condition trees. */
 interface RuleIr {
     readonly finds: readonly FindTermIr[];
     readonly atoms: readonly AtomIr[];
     readonly negated: readonly AtomIr[];
     readonly conditions: readonly ConditionTreeIr[];
 }
-/** One find term (mirrors `ir::FindTerm`). Count is nullary; pack and folds carry `over`. */
 type FoldOpIr = {
     readonly kind: "sum";
 } | {
@@ -155,21 +95,11 @@ type FindTermIr = {
 } | {
     readonly kind: "pack";
     readonly over: number;
-} | {
-    readonly kind: "measure";
-    readonly var: number;
-} | {
-    readonly kind: "aggregateMeasure";
-    readonly op: FoldOpIr;
-    readonly over: number;
 };
-/** Host brand: only {@link parseQueryIr} and `lowerQuery` inhabit this. Phantom — not a runtime key. */
 declare const parsedQueryBrand: unique symbol;
-/** A `QueryIr` that passed the host shape parse (rec/main nonempty, aggregate finds split). */
 type ParsedQuery = QueryIr & {
     readonly [parsedQueryBrand]: true;
 };
-/** One aggregate operator (mirrors `ir::AggOp`; Arg ops carry their key). */
 type AggOpIr = {
     readonly kind: "sum";
 } | {
@@ -181,7 +111,6 @@ type AggOpIr = {
 } | {
     readonly kind: "pack";
 };
-/** Where an atom draws its facts: a stored relation or a derived table. */
 type AtomSourceIr = {
     readonly kind: "edb";
     readonly relation: number;
@@ -189,15 +118,10 @@ type AtomSourceIr = {
     readonly kind: "interior";
     readonly interior: number;
 };
-/**
- * One atom: named-field bindings as `[fieldId, term]` pairs; absence of a
- * field is the wildcard.
- */
 interface AtomIr {
     readonly source: AtomSourceIr;
     readonly bindings: ReadonlyArray<readonly [number, TermIr]>;
 }
-/** One term of an atom binding or comparison (mirrors `ir::Term`). */
 type TermIr = {
     readonly kind: "var";
     readonly var: number;
@@ -210,11 +134,7 @@ type TermIr = {
 } | {
     readonly kind: "literal";
     readonly value: TaggedValue;
-} | {
-    readonly kind: "measure";
-    readonly var: number;
 };
-/** One comparison operator (mirrors `ir::CmpOp`). */
 type CmpOpIr = {
     readonly kind: "eq";
 } | {
@@ -233,16 +153,11 @@ type CmpOpIr = {
 } | {
     readonly kind: "pointIn";
 };
-/** One comparison condition. */
 interface ComparisonIr {
     readonly op: CmpOpIr;
     readonly lhs: TermIr;
     readonly rhs: TermIr;
 }
-/**
- * The input condition grammar: any boolean combination of comparisons
- * (validation distributes to DNF engine-side).
- */
 type ConditionTreeIr = {
     readonly kind: "leaf";
     readonly cmp: ComparisonIr;
@@ -253,18 +168,12 @@ type ConditionTreeIr = {
     readonly kind: "or";
     readonly children: readonly ConditionTreeIr[];
 };
-/** A statement's form tag. */
 type StatementKindTag = "functionality" | "containment" | "capacity";
-/** One field's name, dense id, and structural type. */
 interface ManifestField {
     readonly name: string;
     readonly id: number;
     readonly valueType: ValueTypeSpec;
 }
-/**
- * One closed-relation ground axiom as manifest data: handle →
- * declaration-order id → (column, value) pairs.
- */
 interface ManifestRow {
     readonly handle: string;
     readonly id: bigint;
@@ -273,31 +182,21 @@ interface ManifestRow {
         readonly value: FactValue;
     }>;
 }
-/**
- * One relation's names and ids; a closed relation's sealed field list opens
- * with the synthetic (`id`, u64) handle field and carries its extension.
- */
 interface ManifestRelation {
     readonly name: string;
     readonly id: number;
     readonly fields: readonly ManifestField[];
     readonly extension?: readonly ManifestRow[];
 }
-/** One statement's identity, form tag, and canonical spelling. */
 interface ManifestStatement {
     readonly id: number;
     readonly kind: StatementKindTag;
     readonly spelling: string;
 }
-/**
- * The theory's manifest: every name → id pairing as plain data (PRD-02's
- * tables, one JS object) — called once per open by the SDK.
- */
 interface Manifest {
     readonly relations: readonly ManifestRelation[];
     readonly statements: readonly ManifestStatement[];
 }
-/** One offending fact of a violation, decoded to named natural values. */
 interface ViolationFact {
     readonly relation: string;
     readonly fields: ReadonlyArray<{
@@ -305,15 +204,6 @@ interface ViolationFact {
         readonly value: FactValue;
     }>;
 }
-/**
- * One violated statement of a rejected commit, rendered to plain data: the
- * statement id (materialized order), form tag, CANONICAL spelling (the
- * engine's one renderer — a bijection on legal statements, paste-back-able),
- * the form's direction/measure payloads, and the decoded offending facts.
- * `measure` is the capacity form's witnessed group total — the engine
- * accumulates in u128 and the value crosses WHOLE as bigint (C3:
- * truncation is unrepresentable).
- */
 type Violation = {
     readonly statementId: number;
     readonly kind: "functionality";
@@ -332,15 +222,25 @@ type Violation = {
     readonly measure: bigint;
     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;
+};
 /**
- * `dbCreate`/`dbOpen`'s domain outcome. `schemaError` spans both spec
+ * `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 — a spec whose
- * statement pairs faces with disagreeing newtype labels (the engine twin
- * of the schema-level class wall; unreachable through the typed builder,
- * which computes every label from the laws, so only a raw spec can reach
- * it); `fingerprintMismatch` is `dbOpen`'s stored-theory refusal.
+ * `newtypeMismatch` is the coherence wall's own kind; `fingerprintMismatch`
+ * is `dbOpen`'s stored-theory refusal.
  */
 type DbOpenResult = {
     readonly ok: true;
@@ -350,50 +250,26 @@ type DbOpenResult = {
     readonly kind: "schemaError" | "newtypeMismatch" | "fingerprintMismatch";
     readonly message: string;
 };
-/**
- * `dbExhume`'s domain outcome: the live exhume handle, or one of the three
- * adoption-era refusals as data — `descriptorMissing` (the store predates
- * self-describing stores and has not been adopted; the remedy is one
- * fingerprint-matching `dbOpen` under the creating schema),
- * `formatMismatch`, and `corruption` (the persisted descriptor fails its
- * integrity gates). Genuine failures — a missing path, a held exclusive
- * lock — throw.
- */
-type ExhumeResult = {
-    readonly ok: true;
-    readonly exhume: ExhumeHandle;
+type NativeWriteOutcome = {
+    readonly tag: "accepted";
+    readonly generation: bigint;
 } | {
-    readonly ok: false;
-    readonly kind: "descriptorMissing" | "formatMismatch" | "corruption";
-    readonly message: string;
-};
-/**
- * `dbWriteFrom`'s domain outcome: the live witnessed transaction, or the
- * typed stale-premise verdict (a state-changing commit landed after the
- * witness snapshot; retry policy is host-side).
- */
-type WriteFromResult = {
-    readonly ok: true;
-    readonly tx: TxHandle;
+    readonly tag: "rejected";
+    readonly violations: readonly Violation[];
 } | {
-    readonly ok: false;
-    readonly kind: "generationMoved";
+    readonly tag: "abandoned";
+} | {
+    readonly tag: "moved";
     readonly witnessed: bigint;
     readonly current: bigint;
 };
-/**
- * `txCommit`'s domain outcome: the committed generation, or the COMPLETE
- * violation set (every violated statement cited once, per direction for a
- * containment, in materialized statement order).
- */
-type CommitResult = {
-    readonly ok: true;
-    readonly generation: bigint;
+type AdmitResult = {
+    readonly tag: "accepted";
+    readonly value: OwnedHandle;
 } | {
-    readonly ok: false;
+    readonly tag: "rejected";
     readonly violations: readonly Violation[];
 };
-/** `dbPrepare`'s domain outcome (IR roster errors are data). */
 type PrepareResult = {
     readonly ok: true;
     readonly prepared: PreparedHandle;
@@ -402,251 +278,82 @@ type PrepareResult = {
     readonly kind: "irError";
     readonly message: string;
 };
-/** One occurrence's plan drift (pinned vs live row counts). */
-interface OccurrenceDrift {
-    readonly relation: number;
-    readonly pinned: bigint;
-    readonly live: bigint;
-    readonly ratio: number;
-}
-/**
- * The pull-based plan-drift report: engine-policy-free — no threshold
- * exists engine-side; the host owns reprepare policy.
- */
-interface Staleness {
-    readonly perOccurrence: readonly OccurrenceDrift[];
-    readonly maxRatio: number;
-}
-/**
- * `dbSnapshot`'s reply: the live handle WITH its witnessed generation —
- * one crossing carries both (read inside the snapshot's own transaction,
- * the race-closing rule of 50-storage.md), so no second `dbGeneration`
- * call exists to pay or defend (finding 016's bridge shape).
- */
-type SnapshotOpened = {
-    readonly ok: true;
-    readonly snapshot: SnapshotHandle;
-    readonly generation: bigint;
-};
-/**
- * The plan-as-data report (ruled 2026-07-23, R13): the engine's
- * `ExecutionStats` rendered to plain objects — camelCase keys, u64
- * counters as `bigint`. A diagnostic surface, EXPLICITLY UNFROZEN: the
- * shape follows the plan representation wherever it goes and no
- * compatibility claim attaches, so this typing names the stable spine
- * (version, emits, the plan sections) and leaves each section's leaves
- * open for the host to introspect.
- */
-interface Explain {
-    readonly introspectionVersion: number;
-    readonly emits: bigint;
-    readonly disjointRules?: Readonly<Record<string, unknown>>;
-    readonly subsumed: ReadonlyArray<Readonly<Record<string, unknown>>>;
-    readonly dead: ReadonlyArray<Readonly<Record<string, unknown>>>;
-    readonly rules: ReadonlyArray<Readonly<Record<string, unknown>>>;
-    readonly interiors: ReadonlyArray<Readonly<Record<string, unknown>>>;
-    readonly reach?: Readonly<Record<string, unknown>>;
-}
+type ErrorFamilyKind = "formatMismatch" | "schemaMismatch" | "alreadyInitialized" | "destinationExists" | "publishedButUnsynced" | "environmentLocked" | "io" | "lmdb" | "readersFull" | "schema" | "validation" | "factShape" | "freshExhausted" | "closedRelationWrite" | "commitSync" | "transactionPoisoned" | "foreignPrepared" | "foreignWitness" | "param" | "capacityRayMeasure" | "derivedBudgetExceeded" | "overflow" | "resultBytesOverflow" | "corruption";
+type AdmissionTag = "accepted" | "rejected";
+type WriteTag = "accepted" | "rejected" | "abandoned" | "moved";
+type OpenKind = "schemaError" | "newtypeMismatch" | "fingerprintMismatch";
+type PrepareKind = "irError";
 interface Native {
-    /**
-     * Proof-of-life export (PRD-03): a non-empty string naming the bridge
-     * crate version and the engine's storage format version — evidence the
-     * cargo path dependency compiled, linked, and loaded through Node-API.
-     */
     engineVersion(): string;
-    /**
-     * Creates a fresh DURABLE store at `path` (frozen ruling 3: no ephemeral
-     * kind crosses this bridge). Refuses an already-initialized directory
-     * (throws); schema failures return as data.
-     */
-    dbCreate(path: string, spec: SchemaSpec): DbOpenResult;
-    /**
-     * Opens an existing durable store, verifying format version, store
-     * kind, and schema fingerprint (`fingerprintMismatch` as data).
-     */
-    dbOpen(path: string, spec: SchemaSpec): DbOpenResult;
-    /**
-     * Closes the handle. Dependent handles each hold the engine alive; the
-     * environment (and its exclusive lock) releases when the last closes.
-     */
-    dbClose(db: DbHandle): void;
-    /** The PRD-02 manifest — every name → id table, one plain object. */
+    dbCreate(path: string, spec: SchemaSpec): Promise<CreateResult>;
+    dbOpen(path: string, spec: SchemaSpec): Promise<DbOpenResult>;
     dbManifest(db: DbHandle): Manifest;
-    /**
-     * The open store's schema fingerprint, 64 lowercase hex chars — the
-     * cross-host identity readback (`dbCreate` stored this exact value,
-     * `dbOpen` verified it). The engine computes; the bridge hex-encodes.
-     * Test-facing (the cross-host fingerprint lock); the SDK surface stays
-     * bijective with the Rust surface, which exposes no fingerprint
-     * accessor on `Db` — so no `Db` method wraps this.
-     */
     dbFingerprint(db: DbHandle): string;
-    /**
-     * The current committed generation — diagnostics only. The write-side
-     * witness is always the SNAPSHOT handle (`dbWriteFrom`), never this
-     * integer: an integer witness would be a claim a caller could fabricate
-     * or stale-cache (the engine's recorded refusal).
-     */
     dbGeneration(db: DbHandle): bigint;
+    dbFromInstance(path: string, instance: OwnedHandle): Promise<DbHandle>;
     /**
-     * Opens a store FROM ITS OWN PERSISTED DESCRIPTOR (the read-only,
-     * theory-less open; engine 70-api.md § exhume) — no schema crosses in.
-     * The three adoption-era refusals return as data ({@link ExhumeResult});
-     * genuine failures throw. The handle's deterministic teardown is
-     * `exhumeClose` (R12); GC reclamation remains the backstop only.
-     */
-    dbExhume(path: string): ExhumeResult;
-    /**
-     * Closes the exhume handle, releasing its environment (and the store's
-     * exclusive lock) deterministically — the native teardown under the
-     * SDK's `Symbol.dispose` (ruled 2026-07-23, R12: lifetimes are
-     * disposables, never `close()` methods to remember).
-     */
-    exhumeClose(exhume: ExhumeHandle): void;
-    /**
-     * The exhumed store's persisted schema as manifest-shaped data — the
-     * engine's own manifest rendering of the STORED descriptor: relations
-     * in engine-id order, sealed field lists (a closed relation opens with
-     * the synthetic (`id`, u64) handle field) with structural value types,
-     * and closed-relation rosters.
+     * 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.
      */
-    exhumeDescriptor(exhume: ExhumeHandle): Manifest;
-    /**
-     * Full-relation export by NAME in row-id order, values marshaled per
-     * the STORED descriptor (str already resolved through `_dict` inside
-     * the engine; a closed relation scans its sealed roster). Each call is
-     * one self-contained snapshot read; an unknown relation name throws.
-     */
-    exhumeScan(exhume: ExhumeHandle, relationName: string): FactValue[][];
-    /**
-     * Opens one MVCC read snapshot as a live handle, returned WITH its
-     * witnessed generation — one crossing carries both (finding 016), so
-     * no separate `dbGeneration` call (with its own transient read
-     * transaction and fault-pairing close branch) exists on this path.
-     */
-    dbSnapshot(db: DbHandle): SnapshotOpened;
-    /** Closes the snapshot, releasing its LMDB reader slot. */
-    snapshotClose(snap: SnapshotHandle): void;
-    /** Full-relation export in row-id order (one row per fact). */
-    snapshotScan(snap: SnapshotHandle, relationId: number): FactValue[][];
-    /** Committed-state membership of one fact (sealed field order). */
-    snapshotContains(snap: SnapshotHandle, relationId: number, values: readonly FactValue[]): boolean;
-    /**
-     * Committed-state point lookup through a key statement (`keyValues` in
-     * the statement's projection order); `null` on a miss.
-     */
-    snapshotGet(snap: SnapshotHandle, relationId: number, keyStatementId: number, keyValues: readonly FactValue[]): FactValue[] | null;
-    /**
-     * Begins a write transaction: the submitted delta. One write
-     * transaction may be open per db handle at a time (single-writer
-     * engine; a second begin throws rather than deadlocking the process).
-     */
-    dbWriteBegin(db: DbHandle): TxHandle;
-    /**
-     * Begins a WITNESSED write transaction: commits only if no
-     * state-changing commit landed since `snap` was taken —
-     * `generationMoved` as data otherwise (the optimistic
-     * read-compute-write loop's entry; retry policy stays host-side).
-     */
-    dbWriteFrom(db: DbHandle, snap: SnapshotHandle): WriteFromResult;
+    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;
+    dbWrite(db: DbHandle, callback: (tx: TxHandle) => boolean): NativeWriteOutcome;
+    dbWriteFrom(db: DbHandle, witness: WitnessHandle, callback: (tx: TxHandle) => boolean): NativeWriteOutcome;
     /**
      * Records a collection of inserts into the delta; returns the engine
-     * `{ submitted, changed }` report. `rows` is an array of value-arrays
-     * in sealed field order. Empty is lawful and still a mutation (poison
-     * is observed). Nothing is judged until commit; shape violations throw typed.
-     */
-    txInsert(tx: TxHandle, relationId: number, rows: readonly (readonly FactValue[])[]): WireMutationReport;
-    /** Records a collection of deletes; returns the engine `{ submitted, changed }` report. */
-    txDelete(tx: TxHandle, relationId: number, rows: readonly (readonly FactValue[])[]): WireMutationReport;
-    /**
-     * Final-state membership (base + pending delta — the exact view the
-     * commit judgment judges; check-then-act is race-free by construction).
+     * `{ 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
+     * (proposals/one-representation/20): 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;
+    txDelete(tx: TxHandle, relationId: number, rows: bigint, cells: readonly FactValue[]): WireMutationReport;
     txContains(tx: TxHandle, relationId: number, values: readonly FactValue[]): boolean;
-    /** Final-state point lookup through a key statement; `null` on a miss. */
     txGet(tx: TxHandle, relationId: number, keyStatementId: number, keyValues: readonly FactValue[]): FactValue[] | null;
-    /**
-     * Mints `count` consecutive fresh values for `(relationId, fieldId)`.
-     * `count === 0n` is empty and does not yield a start.
-     */
     txReserve(tx: TxHandle, relationId: number, fieldId: number, count: bigint): WireFreshRange;
-    /**
-     * Commits the delta: every dependency statement judged against the
-     * final state; a rejection carries the complete violation rendering.
-     * The handle is spent either way.
-     */
-    txCommit(tx: TxHandle): CommitResult;
-    /** Aborts the delta (LMDB was never touched). The handle is spent. */
-    txAbort(tx: TxHandle): void;
-    /**
-     * Prepares a query (IR as data, ids only; plan pinned at prepare).
-     * Roster errors return as data.
-     */
     dbPrepare(db: DbHandle, query: ParsedQuery): PrepareResult;
-    /**
-     * Executes against a snapshot with positional params. One-copy owned
-     * rows out, column order = the query's head order; answers are a set
-     * — the host sorts.
-     */
-    preparedExecute(prepared: PreparedHandle, snap: SnapshotHandle, params: readonly QueryParam[]): FactValue[][];
-    /**
-     * Plan introspection as data (ruled 2026-07-23, R13): runs the prepared
-     * query against the snapshot with counting instrumentation (the
-     * engine's `Snapshot::profile`, ANALYZE semantics) and returns the
-     * structured stats — plan sections and counters as plain values.
-     * Scalar params only (the engine's profile entry has no param-set
-     * spelling).
-     */
-    preparedExplain(prepared: PreparedHandle, snap: SnapshotHandle, params: readonly QueryParam[]): Explain;
-    /** The pull-based plan-drift signal against a snapshot. */
-    preparedStaleness(prepared: PreparedHandle, snap: SnapshotHandle): Staleness;
-    /** Releases the prepared query. */
+    preparedExecute(prepared: PreparedHandle, instance: InstanceHandle, params: readonly QueryParam[]): FactValue[][];
     preparedClose(prepared: PreparedHandle): void;
+    instanceBuilderNew(spec: SchemaSpec): BuilderHandle;
+    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[][];
+    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[][];
 }
-/**
- * The sole platform this release ships (PRD-03 ruling 1: prebuilt-only,
- * darwin-arm64). The per-platform-package structure below makes adding
- * `darwin-x64`/`linux-*`/`win32-*` pure addition — one more `os`/`cpu`-gated
- * package plus a CI matrix — never a redesign. This constant names the
- * shipped set for the unsupported-platform message; the build's
- * `PUBLISH_PLATFORM` (`scripts/platform.ts` — src cannot import scripts,
- * the packaging boundary) and the `ts/.gitignore` carve-out spell the same
- * target, and the single-source pin in `test/build-platform.test.ts` holds
- * all three in lockstep.
- */
 declare const SHIPPED_PLATFORMS = "darwin-arm64";
-/**
- * Resolves and loads the native bridge from its per-platform binary package
- * (`@bjornpagen/bumbledb-<platform>-<arch>`) — the Biome/esbuild/napi-rs
- * pattern. npm/pnpm install ONLY the `optionalDependency` whose `os`/`cpu`
- * match the host, so a matching host resolves the addon and every other host
- * resolves nothing. The two failure modes are distinct and both typed:
- *
- *   - the platform package is ABSENT (the expected state on any
- *     non-darwin-arm64 host, and on a foreign `platform`/`arch` passed under
- *     test) — an actionable unsupported-platform error naming the running
- *     `platform-arch` and the shipped set;
- *   - the platform package is PRESENT but its `bumbledb.node` will not load
- *     (a genuine ABI/corruption fault) — the wrapped loader error.
- *
- * Parameterized on `platform`/`arch` so the resolution law is exercised for
- * foreign hosts as a unit, without spawning a foreign process.
- */
-declare function loadNativeBinding(platform: string, arch: string): Native;
-/**
- * The loaded bumbledb-node bridge for the running host. Import this object
- * for every native call; the resolve-and-load happens once at module
- * initialization and an absent or unloadable artifact fails fast here rather
- * than at first use.
- */
+interface NativeBinding extends Native {
+    dbClose(db: DbHandle): void;
+}
+declare function loadNativeBinding(platform: string, arch: string): NativeBinding;
 declare const native: Native;
-/**
- * The bridge guard — THE one wrapper every native call crosses (db.ts and
- * exhume.ts both import it): runs one native call and wraps anything it
- * throws, so marshal-shape refusals and handle-lifecycle refusals cross as
- * genuine typed failures, never bare foreign errors.
- */
+declare function dbClose(db: DbHandle): void;
+declare function errorFromThrow(caught: unknown): Error;
 declare function bridged<T>(context: string, run: () => T): T;
-export type { AggOpIr, AtomIr, AtomSourceIr, CmpOpIr, CommitResult, ComparisonIr, ConditionTreeIr, DbHandle, DbOpenResult, ExhumeHandle, ExhumeResult, Explain, FactValue, FindTermIr, FoldOpIr, HeadOpIr, HeadTermIr, InteriorIr, IntervalValue, Manifest, ManifestField, ManifestRelation, ManifestRow, ManifestStatement, Native, OccurrenceDrift, ParsedQuery, PreparedHandle, PrepareResult, QueryIr, QueryParam, RecIr, RuleIr, SnapshotHandle, SnapshotOpened, Staleness, StatementKindTag, TaggedValue, TermIr, TxHandle, Violation, ViolationFact, WireFreshRange, WireMutationReport, WriteFromResult };
-export { bridged, loadNativeBinding, native, SHIPPED_PLATFORMS };
+declare function bridgedAsync<T>(context: string, run: () => Promise<T>): Promise<T>;
+export type { AdmissionTag, AdmitResult, AggOpIr, AtomIr, AtomSourceIr, BuilderHandle, CmpOpIr, ComparisonIr, ConditionTreeIr, CreateResult, DbHandle, DbOpenResult, ErrorFamilyKind, FactValue, FindTermIr, FoldOpIr, HeadOpIr, HeadTermIr, InstanceHandle, InteriorIr, IntervalValue, Manifest, ManifestField, ManifestRelation, ManifestRow, ManifestStatement, Native, NativeWriteOutcome, OpenKind, OwnedHandle, ParsedQuery, PreparedHandle, PrepareKind, PrepareResult, QueryIr, QueryParam, RecIr, RuleIr, StatementKindTag, TaggedValue, TermIr, TxHandle, Violation, ViolationFact, WireFreshRange, WireMutationReport, WitnessHandle, WriteTag };
+export { bridged, bridgedAsync, dbClose, errorFromThrow, loadNativeBinding, native, SHIPPED_PLATFORMS };
 //# sourceMappingURL=native.d.ts.map