@jarenjs/db 0.34.0

package/dist/types/driver.d.ts

@@ -0,0 +1,128 @@
+/**
+ * @file The driver seam: the contract every binding satisfies, the
+ * capability probe that runs once at open, and the sync-capable-async
+ * helpers the store composes with.
+ *
+ * A driver is `{ name, dialect, open(path, options) }`; `open` returns
+ * a `Connection` or a promise of one. Every connection method may
+ * return a value or a promise — the store never assumes either, and
+ * composes through {@link chain}, which does not allocate a promise
+ * when the driver answered with a value. That is what keeps the public
+ * asynchronous surface from paying twice while the synchronous fast
+ * path stays exact.
+ *
+ * The runtime builtin behind a binding is imported LAZILY inside
+ * `open()` via {@link lazyOpen} — never at module scope — because the
+ * packed-consumer gate imports every export subpath under Node *and*
+ * Bun, Bun ships no `node:sqlite`, and Node cannot resolve `bun:`
+ * specifiers. `open()` is where "this driver does not exist here"
+ * becomes the coded `JD0003` instead of a module-load crash.
+ *
+ * `capabilities` is read once at open — from the library's version
+ * report, its compile options and the binding's declaration — and is
+ * the single source of truth for feature gating; never a `typeof`
+ * sniff at a call site. Two slots are deliberately EMPTY on every
+ * SQLite driver: `statementTimeout` (no interrupt or progress handler
+ * exists to build one on) and `rowEstimates` (the query plan is prose,
+ * not numbers). They exist so a driver that has the facts can fill
+ * them without a contract change; pretending SQLite has them is the
+ * silent degradation this suite refuses.
+ */
+/** The minimum SQLite the store accepts, asserted at open. */
+export declare const SQLITE_FLOOR = "3.45.0";
+/**
+ * How long work may wait for an open transaction to settle before it is
+ * rejected with `JD0012`. Matches the store's default busy timeout: the
+ * question "has this waited unreasonably long?" has one answer per
+ * connection whether the contention is another process (SQLite's own
+ * busy timeout) or another transaction on this one.
+ */
+export declare const DEFAULT_QUEUE_TIMEOUT = 5000;
+/**
+ * @param {any} value
+ * @returns {boolean} true when the value is a thenable
+ */
+export declare function isThenable(value: any): boolean;
+/**
+ * Sync-capable-async composition: apply `next` to a driver result
+ * without allocating a promise when the result is already a value.
+ * @param {any} value - A driver return: a value or a promise
+ * @param {(value: any) => any} next
+ * @returns {any} `next`'s result, promise-wrapped only if the input was
+ */
+export declare function chain(value: any, next: (value: any) => any): any;
+/**
+ * Lift a driver result into a promise — the ONE allocation the public
+ * asynchronous surface pays per call.
+ * @param {any} value
+ * @returns {Promise<any>}
+ */
+export declare function toPromise(value: any): Promise<any>;
+/**
+ * Compare two dotted version strings numerically.
+ * @param {string} a
+ * @param {string} b
+ * @returns {number} negative when a < b, zero when equal
+ */
+export declare function compareVersions(a: string, b: string): number;
+/**
+ * Load a runtime builtin lazily and hand it to the binding's adapter.
+ * A failed import — the specifier does not exist on this runtime —
+ * becomes `JD0003` carrying the loader's error as `cause`.
+ * @param {string} specifier - The builtin module specifier
+ * @param {string} reason - The `JD0003` reason for this binding
+ * @param {(mod: any, ...args: any[]) => any} use - The binding's
+ *   module-to-connection adapter (a named export so the suite can
+ *   exercise it with a substitute module on any runtime)
+ * @param {any[]} args - Extra arguments forwarded to `use`
+ * @returns {Promise<any>}
+ */
+export declare function lazyOpen(specifier: string, reason: string, use: (mod: any, ...args: any[]) => any, args: any[]): Promise<any>;
+/**
+ * Normalize a raw statement to the contract shape. A binding without a
+ * native `iterate` gets one composed over `all` — eager, but the same
+ * rows in the same order.
+ * @param {{ run: Function, get: Function, all: Function,
+ *   iterate?: Function }} statement
+ * @returns {{ run: Function, get: Function, all: Function,
+ *   iterate: Function }}
+ */
+export declare function wrapStatement(statement: {
+    run: Function;
+    get: Function;
+    all: Function;
+    iterate?: Function;
+}): {
+    run: Function;
+    get: Function;
+    all: Function;
+    iterate: Function;
+};
+/**
+ * Finish a raw binding into the connection contract: probe the library
+ * once, assert the version floor, freeze the capability table, and
+ * attach the savepoint-nested `transaction`.
+ *
+ * The raw shape a binding supplies:
+ * `{ exec(sql), prepare(sql) -> { run, get, all, iterate? }, close(),
+ *   registerFunction?, registerAggregate?, session? }` — every method
+ * value-or-promise.
+ *
+ * @param {any} raw
+ * @param {{ dialect: any, synchronous?: boolean, queueTimeout?: number,
+ *   declared?: { sessions?: boolean, userFunctions?: boolean,
+ *     deterministicIndexableFunctions?: boolean,
+ *     aggregateFunctions?: boolean } }} options
+ * @returns {any} a Connection, or a promise of one
+ */
+export declare function openConnection(raw: any, options: {
+    dialect: any;
+    synchronous?: boolean;
+    queueTimeout?: number;
+    declared?: {
+        sessions?: boolean;
+        userFunctions?: boolean;
+        deterministicIndexableFunctions?: boolean;
+        aggregateFunctions?: boolean;
+    };
+}): any;

package/dist/types/drivers/bun.d.ts

@@ -0,0 +1,47 @@
+/**
+ * @file The Bun binding: `bun:sqlite` behind the driver contract. The
+ * builtin is imported lazily inside `open()` — never at module scope —
+ * so this module itself loads under any runtime; on a runtime that
+ * cannot resolve `bun:` specifiers the open fails with the coded
+ * `JD0003`.
+ *
+ * Probed reality this binding declares rather than papers over:
+ * `bun:sqlite`'s `Database` exposes no `function`, no `aggregate` and
+ * no `createSession` — on Bun the UDF hatch does not exist and there
+ * is no session-based change capture. The capability table says so.
+ *
+ * What it DOES expose is a native lazy row iterator, forwarded below.
+ * Without it the driver's generic fallback composes a cursor over
+ * `all()`, which materialises every row first — so a query that streams
+ * on Node would spike memory in a compiled Bun binary, on the same code
+ * and the same data. A cursor that is not lazy is not a cursor.
+ */
+/**
+ * Adapt an already-constructed `bun:sqlite` `Database` (or any object
+ * with its shape) into a probed connection. Exported so the adapter is
+ * exercisable without the builtin.
+ * @param {any} db - A Bun `Database`-shaped database
+ * @param {{ queueTimeout?: number }} [options]
+ * @returns {any} a Connection, or a promise of one
+ */
+export declare function adaptBunDatabase(db: any, options?: {
+    queueTimeout?: number;
+}): any;
+/**
+ * Construct and adapt the database from a loaded `bun:sqlite` module.
+ * Exported so the whole open path runs under any runtime with a
+ * substitute module.
+ * @param {any} mod - The `bun:sqlite` module (or a substitute)
+ * @param {string} path
+ * @param {{ readOnly?: boolean, queueTimeout?: number }} [options]
+ * @returns {any}
+ */
+export declare function fromBunModule(mod: any, path: string, options?: {
+    readOnly?: boolean;
+    queueTimeout?: number;
+}): any;
+/**
+ * The Bun driver: `{ name, dialect, open }` over `bun:sqlite`.
+ * @returns {any}
+ */
+export declare function bunDriver(): any;

package/dist/types/drivers/node.d.ts

@@ -0,0 +1,37 @@
+/**
+ * @file The Node binding: `node:sqlite` behind the driver contract.
+ * The builtin is imported lazily inside `open()` — never at module
+ * scope — so this module itself loads under any runtime; on a runtime
+ * without `node:sqlite` the open fails with the coded `JD0003`.
+ */
+/**
+ * Adapt an already-constructed `node:sqlite` `DatabaseSync` (or any
+ * object with its shape) into a probed connection. Exported so the
+ * adapter is exercisable without the builtin.
+ * @param {any} db - A `DatabaseSync`-shaped database
+ * @param {{ queueTimeout?: number }} [options]
+ * @returns {any} a Connection, or a promise of one
+ */
+export declare function adaptNodeDatabase(db: any, options?: {
+    queueTimeout?: number;
+}): any;
+/**
+ * Construct and adapt the database from a loaded `node:sqlite` module.
+ * The seam {@link nodeDriver} feeds through `lazyOpen`; exported so the
+ * whole open path runs under any runtime with a substitute module.
+ * @param {any} mod - The `node:sqlite` module (or a substitute)
+ * @param {string} path
+ * @param {{ timeout?: number, readOnly?: boolean,
+ *   queueTimeout?: number }} [options]
+ * @returns {any}
+ */
+export declare function fromNodeModule(mod: any, path: string, options?: {
+    timeout?: number;
+    readOnly?: boolean;
+    queueTimeout?: number;
+}): any;
+/**
+ * The Node driver: `{ name, dialect, open }` over `node:sqlite`.
+ * @returns {any}
+ */
+export declare function nodeDriver(): any;

package/dist/types/drivers/wasm.d.ts

@@ -0,0 +1,65 @@
+/**
+ * @file The wasm binding: an INJECTED handle behind the driver
+ * contract. This module imports no runtime builtin at all — the host
+ * (a browser, a worker) supplies the SQLite build, and this driver
+ * only adapts it. Every handle method may return a value or a promise;
+ * a main-thread OPFS-backed build is asynchronous and that is exactly
+ * why the public store surface is.
+ *
+ * The injected contract:
+ *
+ *   handle = {
+ *     open(path, options) -> raw | Promise<raw>,
+ *     synchronous?: boolean,           // default false
+ *     declares?: { userFunctions?, deterministicIndexableFunctions?,
+ *                  sessions? }         // default all false
+ *   }
+ *   raw = { exec(sql), prepare(sql) -> { run, get, all, iterate? },
+ *           close(), registerFunction?, registerAggregate?, session? }
+ *
+ * Capability truth still comes from the probe: whatever the handle
+ * declares is intersected with what the loaded library actually
+ * compiled in.
+ */
+/**
+ * Adapt an already-constructed `sqlite3.oo1` database (the official
+ * SQLite wasm build's object API) into the raw contract. The oo1 API
+ * is SYNCHRONOUS — wasm SQLite computes in place and the SAH-pool
+ * OPFS VFS does synchronous I/O inside a dedicated worker — which is
+ * exactly what keeps journal capture, live queries and the job queue
+ * working unchanged in a browser.
+ *
+ * Statements are REUSED by the store's prepared caches: every
+ * operation ends in `reset()`, never `finalize()`. oo1 user functions
+ * receive a context pointer first — stripped here — and register
+ * variadic (`arity: -1`), matching the engine's fragment shapes.
+ * @param {any} sqlite3 - the loaded sqlite3 module (for `capi`)
+ * @param {any} db - an `sqlite3.oo1.DB`-shaped database
+ * @returns {any} the raw binding for {@link openConnection}
+ */
+export declare function adaptOo1Database(sqlite3: any, db: any): any;
+/**
+ * Build the injected HANDLE from a loaded sqlite3 module — the D6
+ * recipe: the host loads the wasm build and picks the database class
+ * (`sqlite3.oo1.DB` for `:memory:`, the SAH-pool util's `OpfsSAHPoolDb`
+ * for OPFS persistence), and this package only adapts it.
+ *
+ * `sessions` is deliberately NOT declared even though the canonical
+ * wasm build compiles `ENABLE_SESSION`: this adapter does not yet map
+ * the session C API, so capture runs in the journal mode — stated in
+ * the capability matrix, adapting it is a roadmap item.
+ * @param {any} sqlite3 - the loaded sqlite3 module
+ * @param {{ DbClass?: any }} [handleOptions] - the database class to
+ *   construct (default `sqlite3.oo1.DB`)
+ * @returns {any} a handle for {@link wasmDriver}
+ */
+export declare function sqlite3Handle(sqlite3: any, handleOptions?: {
+    DbClass?: any;
+}): any;
+/**
+ * The wasm driver over an injected handle.
+ * @param {any} handle - The host-supplied SQLite handle (see the file
+ *   header for the contract)
+ * @returns {any}
+ */
+export declare function wasmDriver(handle: any): any;

package/dist/types/emit-model.d.ts

@@ -0,0 +1,44 @@
+/**
+ * @file Entity types from models (D17): build an EMIT MODEL DOCUMENT
+ * — the published contract from EMIT-FORMAT.md — that renders entity
+ * interfaces, input variants and the typed-store metadata from the
+ * same model document the runtime validates against.
+ *
+ * The seam (EMIT-FORMAT §4.1, recorded here as the order demanded):
+ * the schema compiler is INJECTED (`options.compile` is
+ * `compileEmitModel` from `@jarenjs/emit`), called with
+ * `extensions: ['x-entity']` so the vocabulary rides the member nodes
+ * verbatim; this module then post-processes the MODEL DOCUMENT —
+ * replacing relation member types with references, flipping
+ * optionality, adding declarations — and never renders a character of
+ * TypeScript itself. Emit stays database-free, db stays
+ * renderer-free, and the injection keeps `@jarenjs/emit` out of db's
+ * dependency graph (the generator script wires the two).
+ *
+ * What the artifact says, deliberately:
+ * - entity interfaces are CLOSED objects (excess-property checking is
+ *   the point of generated types; the runtime validator stays
+ *   authoritative for what a database accepts);
+ * - relation members are optional references — present only when a
+ *   graph load included them; `date-time`/`date` strings carry the
+ *   `DateTime` brand so the linq date operators light up;
+ * - the `<Name>Input` variant makes defaulted and generated members
+ *   optional, drops to-one/to-many relation members (`create`/`add`
+ *   refuse them), and types many-to-many members as key-or-document
+ *   arrays (what `add()` accepts);
+ * - `EntityMetaMap` carries doc/input/key/relations per entity — the
+ *   generic typed-store surface (`@jarenjs/db/typed`) binds to it.
+ */
+/**
+ * Build the emit-model document for a model's entities.
+ * @param {any} model - a jaren-model document with `entities`
+ * @param {{ compile: (schema: any, options?: any) => any,
+ *   source?: string, reserved?: string[] }} options - `compile` is
+ *   `compileEmitModel` (injected; see the header)
+ * @returns {any} an EMIT-FORMAT `0.1` model document
+ */
+export declare function entityEmitModel(model: any, options: {
+    compile: (schema: any, options?: any) => any;
+    source?: string;
+    reserved?: string[];
+}): any;

package/dist/types/emit.d.ts

@@ -0,0 +1,72 @@
+/**
+ * @file Plan → SQL through a dialect. This is the query layer's shared
+ * emitter, the same division of labour as `createDialect`'s DDL/DML
+ * builders: structural SQL composition lives here, every
+ * dialect-varying spelling (identifiers, parameters, string literals,
+ * JSON access, `json_type`, `typeof`, string-operator forms, NULLS
+ * placement, EXPLAIN phrasing) comes from the dialect. Values are
+ * NEVER interpolated into the text: every literal and every external
+ * becomes an ordered parameter slot, which is what makes injection
+ * structurally impossible.
+ *
+ * Every emitted predicate is TOTAL (two-valued) by construction — the
+ * `json_type` guards from the truth table in ARCHITECTURE.md — so
+ * `NOT`/`AND`/`OR` compose classically and SQL's three-valued NULL
+ * logic never decides a row.
+ */
+export type ParamSlot = {
+    external: string;
+} | {
+    literal: unknown;
+};
+/**
+ * @typedef {{ external: string } | { literal: unknown }} ParamSlot
+ */
+/**
+ * Emit one plan as SQL plus its ordered parameter slots.
+ * @param {import('./algebra.js').Plan} plan
+ * @param {any} dialect
+ * @param {{ table: string, keyColumn: string, docColumn: string }} physical
+ * @returns {{ sql: string, slots: ParamSlot[] }}
+ */
+export declare function emitPlan(plan: import('./algebra.js').Plan, dialect: any, physical: {
+    table: string;
+    keyColumn: string;
+    docColumn: string;
+}): {
+    sql: string;
+    slots: ParamSlot[];
+};
+/**
+ * The entity predicate emitters, shared by the entity plan emitter
+ * and the graph-load builder: given an alias and its document column,
+ * emit one predicate with the flavor-correct forms.
+ * @param {any} dialect
+ * @param {(slot: ParamSlot) => string} param
+ * @returns {{ emitPred: (aliasSql: string, docSql: string, pred: any) => string }}
+ */
+export declare function createEntityPredicateEmitters(dialect: any, param: (slot: ParamSlot) => string): {
+    emitPred: (aliasSql: string, docSql: string, pred: any) => string;
+};
+/**
+ * Emit an entity plan (`entity-select` or `entity-join`) as SQL plus
+ * ordered parameter slots. Entity-COLUMN refs compare real typed
+ * columns with TOTAL forms and no `json_type` guard — a column-mapped
+ * property has no present-`null` (§9.3), so presence IS `IS NOT
+ * NULL`; entity-EPOCH refs compare the derived integer column against
+ * a plan-time epoch translation; entity-DOC refs ride the phase-A
+ * guarded truth table over the entity's JSONB column. Join emission
+ * appends BOTH bindings' row identities in binding order, which is
+ * exactly the engine's nested-loop order — determinism the oracle
+ * depends on.
+ * @param {any} plan - from `planEntityQuery`
+ * @param {any} dialect
+ * @param {(entity: string) => { table: string }} physicalOf
+ * @returns {{ sql: string, slots: ParamSlot[] }}
+ */
+export declare function emitEntityPlan(plan: any, dialect: any, physicalOf: (entity: string) => {
+    table: string;
+}): {
+    sql: string;
+    slots: ParamSlot[];
+};

package/dist/types/entity.d.ts

@@ -0,0 +1,23 @@
+/**
+ * @file Entity sets: create / read by key / update / delete over the
+ * hybrid mapping. The physical row is the mapped scalar columns, the
+ * foreign-key columns, and one JSONB `doc` column for everything
+ * else; a write SPLITS the completed document along the mapping and a
+ * read MERGES it back. Defaults apply in JavaScript before validation
+ * — the value the application sees and the value stored are the same
+ * — and identity follows the declared strategy (caller, uuid, auto).
+ *
+ * Epoch date columns are DERIVED: the document keeps the RFC 3339
+ * string, the column carries `getEpochOf…RFC3339(value)` so range
+ * predicates are index-friendly; reads take the string from the
+ * document and skip the derived column.
+ */
+/**
+ * The write/read machinery for one entity, prepared once.
+ * @param {any} connection
+ * @param {any} entity - the normalized entity (model.js)
+ * @param {any} entityMapping - `explainMapping(...).entities[name]`
+ * @param {((doc: any) => any) | null} validate
+ * @returns {any}
+ */
+export declare function entityCore(connection: any, entity: any, entityMapping: any, validate: ((doc: any) => any) | null): any;

package/dist/types/errors.d.ts

@@ -0,0 +1,165 @@
+/**
+ * @file Error types for @jarenjs/db, built on `@jarenjs/core`'s coded
+ * contract: every failure carries a stable `code` (JD0xxx compile-time,
+ * JD2xxx runtime), a bare `reason`, a composed `message`, and — where a
+ * position in the model document exists — a `docPath`. Runtime errors
+ * additionally carry the `collection` and, where one exists, the `key`
+ * as own properties. Database errors are wrapped, never leaked raw: the
+ * reason keeps the original text, `cause` keeps the original error. The
+ * normative table lives in docs/MODEL-FORMAT.md §7, proven in sync with
+ * `DB_CODES` below by a test.
+ */
+import { CodedError } from '@jarenjs/core/errors';
+/**
+ * The runtime code table (the `CSV_CODES` shape): one entry per code
+ * this package can raise, proven in sync with MODEL-FORMAT.md §7's
+ * normative table by a test.
+ */
+export declare const DB_CODES: Readonly<{
+    JD0001: "the SQLite library is below the supported floor";
+    JD0002: "the declared model disagrees with the existing database";
+    JD0003: "the driver binding is unavailable on this runtime";
+    JD0004: "an index path is not a singular member selection";
+    JD0005: "the model document is invalid";
+    JD0010: "strict mode refused a residual";
+    JD0011: "the profile refused the document";
+    JD0012: "work waited too long for the open transaction to settle";
+    JD0030: "an unknown x-entity member was declared";
+    JD0031: "relation declarations contradict each other";
+    JD0032: "the include specification is invalid";
+    JD0040: "the save spans a relation cycle";
+    JD0050: "live queries require change capture";
+    JD0051: "the demanded live mode is unavailable";
+    JD0052: "the live-query bound was reached";
+    JD0020: "the migration's from-shape does not match the database";
+    JD0021: "the migration is missing a required data transform";
+    JD0022: "an applied migration disagrees with the history record";
+    JD0023: "a migration step failed";
+    JD2001: "insert found the key already present";
+    JD2002: "a usable key could not be resolved for the write";
+    JD2003: "the write failed schema validation";
+    JD2004: "an undeclared collection was requested";
+    JD2005: "a database operation failed";
+    JD2006: "patch found no document at the key";
+    JD2007: "the result exceeded the profile row bound";
+    JD2040: "the row changed under an optimistic update";
+    JD2050: "a changeset could not be decoded";
+    JD2051: "the change log is not enabled";
+    JD2060: "the maintained live state exceeded its bound";
+    JD2061: "another context owns the database";
+    JD2062: "the store closed with job handlers still in flight";
+}>;
+/**
+ * A defect found while opening a store — in the model document, the
+ * declared indexes, the driver binding, or the database's agreement
+ * with the declaration. Codes:
+ *
+ *  - `JD0001` — the SQLite library reported a version below the
+ *    supported floor; the reason names the version found
+ *  - `JD0002` — a declared collection already exists in the database
+ *    with a different shape; nothing was altered — changing shape is
+ *    the migration story, a later capability
+ *  - `JD0003` — the runtime builtin behind a driver could not be
+ *    loaded here (Node cannot resolve `bun:`; Bun ships no
+ *    `node:sqlite`), or an injected handle is missing
+ *  - `JD0004` — an index path does not select exactly one member
+ *    (wildcards, slices, filters and descendants are not indexable);
+ *    the reason names the expression
+ *  - `JD0005` — the model document is invalid; `docPath` points at
+ *    the offending member
+ *  - `JD0010` — `strict: true` and part of the query would have run
+ *    outside the database; the reason names the forcing construct
+ *  - `JD0011` — the active profile refused the document before any
+ *    execution: an undeclared external, host function, collation or
+ *    collection, or a refused full-table scan; the reason names it
+ *  - `JD0030` — an unknown member inside an `x-entity` block; a
+ *    silently ignored mapping directive is a data-loss bug waiting
+ *  - `JD0031` — two relation declarations whose inverses contradict
+ *    (different `via`, impossible `many` pairings)
+ *  - `JD0032` — a graph-load include specification is invalid: an
+ *    unknown relation, a cycle, an untranslatable filter, or the
+ *    depth bound exceeded (the bound is printed, never silent)
+ *  - `JD0040` — `saveChanges()` cannot order its statements: the
+ *    entities being inserted or deleted form a foreign-key cycle
+ *    (self-references included); break the save in two
+ *  - `JD0050` — a live query was registered on a store opened without
+ *    `capture`; the patch stream is the invalidation source
+ *  - `JD0051` — `mode: 'incremental'` was demanded but the document
+ *    classifies as re-run; the reason names the forcing construct
+ *  - `JD0052` — registering would exceed the store's `live.maxQueries`
+ *    bound; the bound is printed, never silent
+ *  - `JD0020` — a migration's `from` hash does not match the
+ *    database's recorded shape; running it would corrupt
+ *  - `JD0021` — a draft transform was not filled in, or a document no
+ *    longer validates after the migration (a narrowing without an
+ *    adequate transform)
+ *  - `JD0022` — the migration list disagrees with the applied history
+ *    (an edited file, a missing file, a reordered sequence)
+ *  - `JD0023` — a step failed: an assertion returned rows, DDL was
+ *    rejected, or a transform produced an unstorable value
+ */
+export declare class DbCompileError extends CodedError {
+    /**
+     * @param {string} code
+     * @param {string} reason - The bare reason; `message` is composed per
+     *   the coded contract.
+     * @param {string} [docPath] - JSON Pointer into the model document,
+     *   where one exists.
+     * @param {Error} [cause]
+     */
+    constructor(code: string, reason: string, docPath?: string, cause?: Error);
+}
+/**
+ * A failure while reading or writing an open store. Codes:
+ *
+ *  - `JD2001` — `insert` hit a document already stored under the key
+ *  - `JD2002` — the declared key pointer resolved to nothing or to a
+ *    non-scalar, or an explicit key argument is not a string or number
+ *  - `JD2003` — the injected validation hook rejected the document
+ *    that a write would have stored; `errors` carries the hook's
+ *    findings when it produced any
+ *  - `JD2004` — `collection()` named a collection the model does not
+ *    declare
+ *  - `JD2005` — the database rejected an operation for a reason that
+ *    is not a duplicate key; the original error is the `cause`
+ *  - `JD2006` — `patch` addressed a key with no stored document
+ *  - `JD2007` — a fetch crossed the profile's `maxRows` bound; the
+ *    result is refused whole, never silently truncated
+ *  - `JD2040` — an optimistic update or delete matched no row: the
+ *    declared version changed under the save (or the row is gone);
+ *    the error names the entity and key, and the whole save rolled
+ *    back
+ *  - `JD2050` — a session changeset carried bytes this decoder does
+ *    not recognise (a future SQLite format change would land here)
+ *  - `JD2051` — `changesSince` was called on a store whose capture
+ *    has no persisted log
+ *  - `JD2060` — maintenance crossed the live query's `maxMaintained`
+ *    bound; the query delivered this error and closed rather than
+ *    degrade
+ *  - `JD2061` — a second context tried to open a database whose
+ *    storage grants one context exclusive access (the owner topology
+ *    of LIVE-FORMAT §11); connect to the owner instead
+ */
+export declare class DbRuntimeError extends CodedError {
+    collection: string | undefined;
+    key: string | number | undefined;
+    errors: unknown[] | undefined;
+    /**
+     * @param {string} code
+     * @param {string} reason - The bare reason; `message` is composed per
+     *   the coded contract.
+     * @param {{ docPath?: string, collection?: string,
+     *   key?: string | number, errors?: unknown[], cause?: unknown }} [details]
+     *   - `docPath` points into the model document (the collection the
+     *   failure belongs to); `collection`/`key` are installed as own
+     *   properties; `errors` carries validation findings; `cause` follows
+     *   the coded contract's `hasOwn` form.
+     */
+    constructor(code: string, reason: string, details?: {
+        docPath?: string;
+        collection?: string;
+        key?: string | number;
+        errors?: unknown[];
+        cause?: unknown;
+    });
+}

package/dist/types/graph.d.ts

@@ -0,0 +1,28 @@
+/**
+ * @file Row → entity-graph reconstruction. One place owns the merge
+ * discipline (§9.3): mapped scalar columns fold back into the JSONB
+ * document's parse (booleans un-integer, SQL NULL reads back ABSENT,
+ * derived epoch columns are skipped because the string never left the
+ * document), foreign-key columns fold in the same way, and — for the
+ * one-statement graph loads — projected relation JSON parses
+ * recursively into child arrays or single children.
+ */
+/**
+ * Merge one database row back into its entity document.
+ * @param {any} entityMapping - `explainMapping(...).entities[name]`
+ * @param {any} row - a row carrying the entity's columns plus the
+ *   rendered document text
+ * @param {string} [docField] - the column the document text rides in
+ * @returns {any}
+ */
+export declare function mergeEntityRow(entityMapping: any, row: any, docField?: string): any;
+/**
+ * Parse one graph-load row: the root entity's merge plus every
+ * included relation's projected JSON, recursively.
+ * @param {any} node - the include-plan node
+ *   `{ entityMapping, includes: { name, field, many, count, child }[] }`
+ * @param {any} row
+ * @param {string} docField
+ * @returns {any}
+ */
+export declare function parseGraphRow(node: any, row: any, docField?: string): any;

package/dist/types/index.d.ts

@@ -0,0 +1,35 @@
+/**
+ * @file @jarenjs/db — document storage over SQLite through two seams:
+ * a driver (how a connection is made: `@jarenjs/db/node`, `/bun`, or
+ * `/wasm` with an injected handle) and a dialect (how SQL is spelled).
+ * This root subpath never touches a runtime builtin — a browser
+ * bundler resolves it clean; the bindings live behind their own
+ * subpaths and load their builtin lazily inside `open()`.
+ */
+export { openStore, normalizeModel, MODEL_VERSION } from './store.js';
+export { createDialect } from './dialect.js';
+export { sqliteDialect } from './dialects/sqlite.js';
+export { SQLITE_FLOOR, chain, toPromise, isThenable, compareVersions, openConnection, wrapStatement, lazyOpen, } from './driver.js';
+export { planCollection, compileIndexPath, schemaTypeAt, KEY_COLUMN, DOC_COLUMN, normalizeDeclaredSql, comparableDeclaredSql, } from './ddl.js';
+export { planQuery, assertDecidedKind, entityShape, entityPathRef, planEntityPredicate, planEntityQuery, } from './plan.js';
+export { emitPlan, createEntityPredicateEmitters, emitEntityPlan } from './emit.js';
+export { mergeEntityRow, parseGraphRow } from './graph.js';
+export { selectPlan, conjoin, assertNoSqlText, PLAN_VERSION } from './algebra.js';
+export { typeOfPath, isNumericType } from './types.js';
+export { compileSetResidual, compileRowResidual, sequenceResult } from './residual.js';
+export { deterministicFragment, registerFragment } from './udf.js';
+export { createQueryEngine, createQueryState, createEntityQueryEngine, createLoadEngine, INCLUDE_DEPTH_DEFAULT, } from './query.js';
+export { normalizeProfile, SAFE_PROFILE, translateProfilePredicate, applyMandatoryPredicate, applyRowBound, } from './profile.js';
+export { translatePatch } from './patch-sql.js';
+export { normalizeEntities, explainMapping } from './model.js';
+export { planEntity, planJoinTable } from './ddl.js';
+export { entityCore } from './entity.js';
+export { entityEmitModel } from './emit-model.js';
+export { parseChangeset, translateOperations, keyToken, createCaptureEngine, CHANGES_TABLE, DEFAULT_RETENTION, } from './capture.js';
+export { createTracker, deepFreeze, BATCH_PARAM_BUDGET, BATCH_ROW_BOUND, } from './tracker.js';
+export { planMigration, planModelMigration, migrate, migrationStatus, shapeHash, migrationChecksum, createModelShape, schemaShapeOf, compareShapeToModel, MIGRATION_VERSION, HISTORY_TABLE, } from './migrate.js';
+export { DbCompileError, DbRuntimeError, DB_CODES } from './errors.js';
+export { classifyLiveQuery, createLiveRegistry, diffRows, LIVE_DEFAULTS } from './live.js';
+export { createSortedWindow, compareCodepoint } from './window.js';
+export { createJobEngine, JOBS_TABLE, JOB_CHECKPOINTS_TABLE, JOB_DEFAULTS, describeValue, serializeResult, } from './jobs.js';
+export { createDagJobRunner } from './dag-job.js';