@jarenjs/db 0.56.0 → 0.67.0

package/types/index.d.ts

@@ -16,6 +16,8 @@
  * `@jarenjs/db/typed`.
  */
 
+import type { Runtime } from '@jarenjs/core/runtime';
+
 // ————— errors —————
 
 export declare const DB_CODES: Readonly<Record<string, string>>;
@@ -25,8 +27,37 @@ export declare class DbCompileError extends Error {
   readonly code: string;
   readonly reason: string;
   readonly docPath?: string;
+  /** Present on a `JD0002` raised by a driver failure at open: the
+   * classifier's class and verdict (MODEL-FORMAT §7). */
+  readonly class?: DriverErrorClass;
+  readonly retryable?: boolean;
 }
 
+/** The stable classes `classifyDriverError` assigns (MODEL-FORMAT §7). */
+export type DriverErrorClass = 'busy' | 'full' | 'readonly' | 'io' | 'corrupt' | 'cantopen'
+  | 'constraint' | 'duplicate' | 'overflow' | 'error';
+
+/** Classify a SQLite driver failure: the class, the runtime code it is
+ * raised under (`null` for `overflow`, which the query path answers by
+ * re-running in the engine), whether a retry can succeed, and the
+ * sentence the wrapped error leads with. */
+export declare function classifyDriverError(error: unknown,
+  unique?: { table: string; column: string }):
+  { class: DriverErrorClass; code: string | null; retryable: boolean; reason: string };
+/** Wrap a driver failure as the coded runtime error its class calls
+ * for, `class`/`retryable`/`cause` attached; anything that is not a
+ * driver's own error is returned as it is. */
+export declare function wrapDriverError(error: unknown, details?: {
+  docPath?: string; collection?: string; key?: string | number;
+  unique?: { table: string; column: string }; duplicateReason?: string;
+  code?: string; reason?: string;
+  /** Wrap even a failure that is not a driver's under `code`, with
+   * `class: 'error'` — for a lifecycle that promises a coded failure. */
+  always?: boolean }): Error;
+/** Whether an error is a SQLite driver's own (a numeric result code, or
+ * node:sqlite's error shape). */
+export declare function isDriverError(error: unknown): boolean;
+
 export declare class DbRuntimeError extends Error {
   constructor(code: string, reason: string, options?: {
     docPath?: string;
@@ -41,6 +72,10 @@ export declare class DbRuntimeError extends Error {
   readonly collection?: string;
   readonly key?: unknown;
   readonly errors?: unknown[];
+  /** Present on an error the driver-failure classifier wrapped
+   * (MODEL-FORMAT §7): the stable class and whether a retry can succeed. */
+  readonly class?: DriverErrorClass;
+  readonly retryable?: boolean;
 }
 
 // ————— shared shapes —————
@@ -73,8 +108,67 @@ export type ValueOrPromise<T> = T | Promise<T>;
  */
 export interface QueryCursor<T = unknown> {
   next(): Promise<IteratorResult<T, undefined>>;
+  /** Release the statement, exactly once, at the row boundary the
+   * cursor is on; idempotent, and what `for await`'s break, throw and
+   * exhaustion all reach. */
   return(): Promise<IteratorResult<T, undefined>>;
   [Symbol.asyncIterator](): QueryCursor<T>;
+  /** What this cursor will do for the externals it was given: pull one
+   * database row per `next()`, or fill a buffer on the first pull. */
+  readonly streaming: 'row' | 'buffered';
+  /** What forces the buffer, `null` when the cursor streams. */
+  readonly barrier: CursorBarrier | null;
+}
+
+/** Why a cursor buffers: `construct` is the stable identifier (a
+ * planner construct such as `$orderby` or `$let`, or `external`,
+ * `window`, `pushdown`), `reason` the sentence for a person. */
+export interface CursorBarrier {
+  readonly construct: string;
+  readonly reason: string;
+}
+
+/**
+ * The safe execution profile (MODEL-FORMAT §8): five independent bounds
+ * — engine limits, a row bound, reference containment, mandatory
+ * predicates, a member allow-list — plus the graph bounds. Every member
+ * is optional over the `'safe'` defaults. A budget the engine can count is ENFORCED; one it
+ * cannot count on SQLite (visited rows, elapsed statement time) is
+ * refused at preflight on plan shape (`refuseFullScan`) or reported as
+ * unavailable (`explain().budget`), never approximated.
+ */
+export interface ProfileSpec {
+  limits?: { sequenceItems?: number; resultItems?: number; steps?: number; depth?: number };
+  /** Rows a fetch may return, materialise or feed a residual, per call
+   * (`JD2007` when crossed). */
+  maxRows?: number;
+  externals?: readonly string[];
+  functions?: readonly string[];
+  collations?: readonly string[];
+  /** The names a document may read — collections AND entity roots;
+   * `null` allows all of the store's. */
+  collections?: readonly string[] | null;
+  /** A predicate conjoined into every plan over the named collection or
+   * entity, at its root, after translation. */
+  predicates?: Readonly<Record<string, unknown>>;
+  /** Refuse a plan whose shape is a full-table scan — including the
+   * whole-root fetch an entity residual needs (`JD0011`). */
+  refuseFullScan?: boolean;
+  /** A cap on any include's per-root rows, on the include depth, and on
+   * one item's serialised bytes (`JD2076`); `null` for none. */
+  maxIncludedRows?: number | null;
+  maxDepth?: number | null;
+  maxBytes?: number | null;
+  /** Per ROOT (a collection or an entity), the members a document may
+   * READ, as the model's own singular index-path spelling (`'$.name'`,
+   * `'$.address.city'`). Allowing a member allows everything under it
+   * and none of its siblings. A root the list does not name is
+   * unrestricted; a root the MODEL does not declare is `JD0011` before
+   * any statement. Reading a root item whole — the bare binding, an
+   * alias of it, a wildcard with no singular prefix — is refused rather
+   * than narrowed, and so is a graph `load()` of a policed entity, which
+   * answers whole documents by definition. */
+  members?: Readonly<Record<string, readonly string[]>>;
 }
 
 export interface ExecuteOptions {
@@ -82,6 +176,40 @@ export interface ExecuteOptions {
   strict?: boolean;
   /** `false` forces the set residual — the oracle's harness switch. */
   pushdown?: boolean;
+  /** The safety profile for THIS call, replacing the store's (normalized
+   * over the `'safe'` defaults, MODEL-FORMAT §8); applies to collection,
+   * entity, graph, include and store-root execution alike. */
+  profile?: 'safe' | ProfileSpec;
+  /** Cancellation: a call already aborted runs no statement (`JD2072`);
+   * a cursor or page is released at its next row boundary. */
+  signal?: AbortSignal;
+  /** An epoch-millisecond deadline, checked before a statement runs and
+   * at every row boundary of a cursor or page (`JD2075`). NOT a
+   * statement timeout: the shipped SQLite drivers expose no interrupt
+   * (`capabilities.statementTimeout` is `false`), so a single statement
+   * runs to its end — `explain().budget.time` says so. */
+  deadline?: number;
+  /** On a cursor: a plan that would buffer — a set residual, a
+   * k-nearest cut, a native group, a chain's window, an external the
+   * database cannot bind — is the refusal `JD0037` naming the barrier,
+   * raised before any statement runs; the plan is declined, never run
+   * with its memory behaviour quietly changed. On `execute()` it is a
+   * `TypeError`: a whole answer has no stream to hold to. */
+  strictStreaming?: boolean;
+}
+
+/** What a cursor takes: `execute`'s options, `signal` honoured at every
+ * row boundary — an aborted cursor releases its statement and every
+ * later pull is `JD2072`. */
+export interface CursorOptions extends ExecuteOptions {}
+
+/** An entity cursor's options. `tracking: true` registers every yielded
+ * entity document with the unit of work — a snapshot per row, so the
+ * tracker grows with the result and is bounded by nothing but it; off
+ * by default for exactly that reason. The document must then return a
+ * bare entity binding (`JD0034` for a projection, a count or a window). */
+export interface EntityCursorOptions extends CursorOptions {
+  tracking?: boolean;
 }
 
 /** An include's clauses: the root's without `after` — a keyset cursor
@@ -89,6 +217,14 @@ export interface ExecuteOptions {
 export interface LoadInclude extends Omit<LoadSpec, 'after'> {
   /** Project the related-row COUNT instead of the rows. */
   count?: boolean;
+  /** The per-root bounds (MODEL-FORMAT §10.4): rows of this relation
+   * per parent (default `INCLUDE_ROWS_DEFAULT`, or the include's own
+   * `take`), and serialised bytes per parent (default
+   * `INCLUDE_BYTES_DEFAULT`). Crossing one is the refusal `JD2073`,
+   * never a truncated graph. `Infinity` (`null` in JSON) is the
+   * unbounded case, spelled. */
+  maxRows?: number | null;
+  maxBytes?: number | null;
 }
 
 export interface LoadSpec {
@@ -97,16 +233,103 @@ export interface LoadSpec {
   orderBy?: unknown;
   take?: number;
   skip?: number;
-  /** The keyset cursor: needs a single unique-column ordering. */
-  after?: string | number;
+  /** The keyset cursor (MODEL-FORMAT §10.5): the structural continuation
+   * a page emitted, over the declared ordering with the primary key
+   * appended; or, the single-column form, one value of a unique
+   * ordering column. */
+  after?: string | number | LoadContinuation;
   maxDepth?: number;
   include?: Readonly<Record<string, boolean | LoadInclude>>;
 }
 
+/** One term of a keyset ordering's identity: the mapped column, its
+ * direction, and where its nulls sort. */
+export interface OrderIdentity {
+  readonly column: string;
+  readonly desc: boolean;
+  readonly nullsFirst: boolean;
+}
+
+/** One term of the order a statement actually executes under. `source`
+ * is closed: a mapped `column`, a `document` path the dialect extracts,
+ * the `group` key of a bucketed plan, or the row `identity` an emitter
+ * appends so a sequence answers in insertion order. Only a `column`
+ * term carries a column name, only a `document` term a path; the
+ * identity term carries neither, and its `nullsFirst` is `null` because
+ * a row identity is never absent. `tieBreaker` marks a term the plan
+ * appended rather than one the caller declared. */
+export interface EffectiveOrderTerm {
+  readonly source: 'column' | 'document' | 'group' | 'identity';
+  readonly binding: string | null;
+  readonly column: string | null;
+  readonly path: readonly (string | number)[] | null;
+  readonly desc: boolean;
+  readonly nullsFirst: boolean | null;
+  readonly tieBreaker: boolean;
+}
+
+/**
+ * The continuation a page emits (MODEL-FORMAT §10.5): unsigned,
+ * structural, opaque — the ordering's identity, so it cannot be
+ * replayed against another ordering (`JD0035`); the last row's declared
+ * order-key values as the document carries them; and the row's primary
+ * key, the tie-breaker the plan appends. Signing, tenant scoping, expiry
+ * and wire encoding are the HOST's: the store has no principal and no
+ * key, and a continuation handed to an untrusted client unsigned is the
+ * host's mistake, not a store guarantee.
+ */
+export interface LoadContinuation {
+  readonly order: readonly OrderIdentity[];
+  readonly keys: readonly unknown[];
+  readonly key: EntityKeyArg;
+}
+
+/** A page's options: `limit` roots at most (default `PAGE_LIMIT_DEFAULT`),
+ * `maxBytes` serialised bytes at most (`Infinity`/absent for no byte
+ * bound), the continuation to resume from, and `consistency` —
+ * `'snapshot'` is refused (`JD0036`) over an ordering whose keys a
+ * write may change; `'live'` (the default) reports the truth in
+ * `snapshot`. */
+export interface PageOptions<C = LoadContinuation> extends EntityCursorOptions {
+  limit?: number;
+  after?: C;
+  maxBytes?: number | null;
+  consistency?: 'live' | 'snapshot';
+}
+
+/** One page: never more than `limit` items or `maxBytes` bytes; the
+ * continuation of the last delivered item (or the one resumed from, when
+ * nothing fit); `hasMore` by one peek past the page; `snapshot` true
+ * only over an immutable ordering — otherwise LIVE pagination, where a
+ * row whose order key changes can move across the cursor. */
+export interface Page<T, C = LoadContinuation> {
+  readonly items: T[];
+  readonly continuation: C | null;
+  readonly hasMore: boolean;
+  readonly snapshot: boolean;
+}
+
 export interface LoadExplanation {
   sql: string;
   pagination: 'keyset' | 'offset' | 'none';
   includes: ReadonlyArray<{ path: string; kind: string; count: boolean }>;
+  /** The per-root bounds every row-projecting include runs under;
+   * `null` is the unbounded case a caller spelled. */
+  bounds: ReadonlyArray<{ path: string; maxRows: number | null; maxBytes: number | null }>;
+  /** The effective deterministic order the statement executes under, in
+   * every load mode: the declared terms, then the tie-breaker the clause
+   * appends — the primary key in keyset mode, the row identity
+   * otherwise. */
+  order: readonly EffectiveOrderTerm[];
+  /** The keyset ordering's IDENTITY: the value a continuation carries and
+   * is checked against (`JD0035`); `null` for a load outside keyset
+   * mode, which has no continuation to emit. Whether a page over it is a
+   * snapshot is `snapshot`. */
+  identity: readonly OrderIdentity[] | null;
+  snapshot: boolean | null;
+  /** A graph load pulls one root row per statement row, always. */
+  streaming: 'row';
+  barrier: null;
 }
 
 /** What `saveChanges()` returns: data, not a boolean (§11.6). */
@@ -136,13 +359,159 @@ export interface StoreStats {
   liveQueries: number;
 }
 
+/**
+ * The connection pragmas in effect, read back from the connection after
+ * the open sequence applied them — never the requested values. `null`
+ * where the driver's binding declares the pragma absent or the engine
+ * answers nothing (a `:memory:` database's `mmapSize`).
+ */
+export interface StorePragmas {
+  readonly busyTimeout: number | null;
+  readonly journalMode: 'delete' | 'truncate' | 'persist' | 'memory' | 'wal' | 'off' | null;
+  readonly synchronous: 'off' | 'normal' | 'full' | 'extra' | null;
+  readonly walAutocheckpoint: number | null;
+  readonly journalSizeLimit: number | null;
+  readonly cacheSize: number | null;
+  readonly mmapSize: number | null;
+  readonly tempStore: 'default' | 'file' | 'memory' | null;
+}
+
+export interface MaintenanceCapabilities {
+  readonly checkpoint: boolean;
+  readonly integrityCheck: boolean;
+  readonly foreignKeyCheck: boolean;
+  readonly optimize: boolean;
+  /** The online backup (`backupTo`): the Node binding's; `false`
+   * elsewhere, where the call is refused `JD2077`. */
+  readonly backup: boolean;
+}
+
+/** The platform's progress report, verbatim: the last event may still
+ * carry a remainder — completion is the resolved call. */
+export interface BackupProgress {
+  readonly totalPages: number;
+  readonly remainingPages: number;
+}
+
+export interface BackupOptions {
+  /** Pages copied per step (the platform's `rate`); progress and the
+   * cancellation check happen between steps. */
+  rate?: number;
+  onProgress?: (progress: BackupProgress) => void;
+  /** Cancels between pages: `JD2079`, the temporary file removed, the
+   * target untouched. */
+  signal?: AbortSignal;
+  /** An epoch-millisecond deadline on the store's clock, honoured before
+   * the copy and between its pages (`JD2075`, same cleanup). */
+  deadline?: number;
+  /** The checkpoint that fixes the snapshot boundary (default
+   * `'passive'`; `false` skips it; a read-only store skips it by
+   * default and refuses an explicit one `JD2077`). */
+  checkpoint?: 'passive' | 'full' | 'restart' | 'truncate' | false;
+}
+
+export interface BackupResult {
+  readonly path: string;
+  /** The page total the platform answered. */
+  readonly pages: number;
+  readonly checkpoint: CheckpointResult | null;
+}
+
+/** Cancellation of a maintenance operation: checked once, before the
+ * one statement it issues (`JD2081` / `JD2075`, on the store's clock). */
+export interface MaintenanceCallOptions {
+  signal?: AbortSignal;
+  /** An epoch-millisecond deadline on the runtime record's clock. */
+  deadline?: number;
+}
+
+export interface CheckpointOptions extends MaintenanceCallOptions {
+  /** `PRAGMA wal_checkpoint` mode (default `'passive'`). */
+  mode?: 'passive' | 'full' | 'restart' | 'truncate';
+}
+
+/** The engine's own checkpoint row: `-1` frames on a database that is
+ * not in WAL mode. A second passive checkpoint reports the same counts
+ * as the first; a second `truncate` reports zeros. */
+export interface CheckpointResult {
+  readonly busy: boolean;
+  readonly logFrames: number;
+  readonly checkpointedFrames: number;
+}
+
+export interface IntegrityCheckOptions extends MaintenanceCallOptions {
+  /** At most this many problem rows (`PRAGMA integrity_check(N)`). */
+  limit?: number;
+}
+
+/** `ok` for the engine's single `ok` row; otherwise its problem rows
+ * verbatim. Corruption is the result, never a throw. */
+export interface IntegrityCheckResult {
+  readonly ok: boolean;
+  readonly problems: readonly string[];
+}
+
+export interface ForeignKeyViolation {
+  readonly table: string;
+  readonly rowId: number | null;
+  readonly parent: string;
+  readonly fkid: number;
+}
+
+export interface ForeignKeyCheckResult {
+  readonly ok: boolean;
+  readonly violations: readonly ForeignKeyViolation[];
+}
+
+/** `PRAGMA optimize` reports nothing; the honest result is that it ran. */
+export interface OptimizeResult {
+  readonly ran: true;
+}
+
+/** The granularity at which each lifecycle honours `signal`/`deadline`:
+ * the boundaries the driver actually has. `midStatement` is a filled
+ * slot — `false` on every shipped SQLite binding, which exposes no
+ * interrupt. */
+export interface CancellationCapabilities {
+  readonly query: 'row';
+  readonly queue: true;
+  readonly migration: 'step';
+  readonly maintenance: 'statement';
+  readonly backup: 'page';
+  readonly midStatement: boolean;
+}
+
 export interface StoreCapabilities {
   readonly version: string;
   readonly readOnly: boolean;
   readonly validated: boolean;
   readonly profiled: boolean;
+  /** The read-back connection configuration (MODEL-FORMAT §4). */
+  readonly pragmas: StorePragmas;
+  /** `pragmas.busyTimeout` under its long-published name. */
   readonly busyTimeoutMs: number | null;
+  /** `pragmas.journalMode` under its long-published name. */
   readonly journalMode: string | null;
+  /** The configuration pragmas the driver's binding declares it can
+   * apply, by option name; a request outside them is `JD0007`. */
+  readonly configurablePragmas: readonly string[];
+  /** Per-operation availability of the maintenance surface: `false`
+   * where the driver's binding does not declare an operation and, for
+   * the two that write, on a read-only store; a call is refused
+   * `JD2077` exactly where this says `false`. */
+  readonly maintenance: MaintenanceCapabilities;
+  /** Where a cancellation takes effect, per lifecycle (MODEL-FORMAT §4). */
+  readonly cancellation: CancellationCapabilities;
+  /** Whether the binding's statements carry a lazy row iterator; when
+   * `false` every cursor reports `streaming: 'buffered'` with a
+   * `{ construct: 'driver' }` barrier. Probed at open. */
+  readonly lazyIteration: boolean;
+  readonly sessions: boolean;
+  readonly sessionReason: string | null;
+  readonly worker: boolean;
+  readonly pooling: boolean;
+  readonly poolReaders: number;
+  readonly poolWriters: number;
   readonly capture: 'session' | 'journal' | 'none';
   readonly captureLog: boolean;
   readonly live: boolean;
@@ -171,7 +540,7 @@ export interface Collection<T = unknown> {
    * a synchronous driver stays synchronous. */
   execute<R = unknown>(document: unknown, options?: ExecuteOptions): ValueOrPromise<SequenceResult<R>>;
   /** The same document as an item cursor — one item per pull. */
-  query<R = unknown>(document: unknown, options?: ExecuteOptions): QueryCursor<R>;
+  query<R = unknown>(document: unknown, options?: CursorOptions): QueryCursor<R>;
   explain(document: unknown, options?: ExecuteOptions): Promise<unknown>;
   /** Register a live query (LIVE-FORMAT §7); requires capture. */
   live(document: unknown, options?: LiveOptions): Promise<LiveQuery>;
@@ -233,6 +602,13 @@ export interface EntitySet<T = unknown, I = unknown> {
   update(key: EntityKeyArg, changes: Partial<T>): Promise<Readonly<T>>;
   delete(key: EntityKeyArg): Promise<boolean>;
   load(spec?: LoadSpec): Promise<ReadonlyArray<Readonly<T>>>;
+  /** The graph cursor: one root graph per pull, its includes attached
+   * and bounded (§10.4), from the same one statement `load` runs;
+   * `return()` releases it. Untracked unless `tracking: true`. */
+  loadCursor(spec?: LoadSpec, options?: EntityCursorOptions): QueryCursor<Readonly<T>>;
+  /** One bounded page over the composite keyset (§10.5). A `take` or
+   * `skip` in the spec is refused: the page windows by its limit. */
+  page(spec?: LoadSpec, options?: PageOptions): Promise<Page<Readonly<T>>>;
   explainLoad(spec?: LoadSpec): LoadExplanation;
   /** Track a pending insert (local, synchronous — no round trip). */
   add(doc: I): Readonly<T>;
@@ -253,6 +629,12 @@ export interface EntitySet<T = unknown, I = unknown> {
    * the document is over the multi-entity root and arrives whole; the
    * answer is the engine's result shape, value-or-promise (D2). */
   execute<R = unknown>(document: unknown, options?: ExecuteOptions): ValueOrPromise<SequenceResult<R>>;
+  /** The same document as an item cursor: one row per pull from an open
+   * statement, released on `return()`; a set residual materialises the
+   * fetched root first and says so (`streaming: 'buffered'`). A chain's
+   * `for await` over this set is this cursor. Untracked unless
+   * `tracking: true`. */
+  cursor<R = T>(document: unknown, options?: EntityCursorOptions): QueryCursor<R>;
   explain(document: unknown, options?: ExecuteOptions): Promise<unknown>;
   /** The root expression this set's rows are bound through (`$.<Name>[*]`). */
   readonly root: string;
@@ -278,6 +660,9 @@ export interface SyncEntitySet<T = unknown, I = unknown> {
   update(key: EntityKeyArg, changes: Partial<T>): Readonly<T>;
   delete(key: EntityKeyArg): boolean;
   load(spec?: LoadSpec): ReadonlyArray<Readonly<T>>;
+  loadCursor(spec?: LoadSpec, options?: EntityCursorOptions): SyncQueryCursor<Readonly<T>>;
+  page(spec?: LoadSpec, options?: PageOptions): Page<Readonly<T>>;
+  cursor<R = T>(document: unknown, options?: EntityCursorOptions): SyncQueryCursor<R>;
   explainLoad(spec?: LoadSpec): LoadExplanation;
   add(doc: I): Readonly<T>;
   put(next: T): Readonly<T>;
@@ -294,6 +679,15 @@ export interface SyncEntitySet<T = unknown, I = unknown> {
   readonly relations: RelationTable;
 }
 
+/** A lazy synchronous cursor; return, disposal, errors and close release its source. */
+export interface SyncQueryCursor<T = unknown> extends IterableIterator<T> {
+  readonly streaming: 'row' | 'buffered';
+  readonly barrier: CursorBarrier | null;
+  return(): IteratorResult<T, undefined>;
+  [Symbol.iterator](): SyncQueryCursor<T>;
+  [Symbol.dispose](): void;
+}
+
 // ————— the store —————
 
 export interface SyncStore {
@@ -301,7 +695,7 @@ export interface SyncStore {
    * the consumer's words; the handle's writes take it and reads answer it. */
   collection<T = unknown>(name: string): SyncCollection<T>;
   entity(name: string): SyncEntitySet;
-  transaction<R>(fn: (store: Store) => R): R;
+  transaction<R>(fn: (store: TransactionStore) => R): R;
   execute?<R = unknown>(document: unknown, options?: ExecuteOptions): SequenceResult<R>;
   explain?(document: unknown, options?: ExecuteOptions): unknown;
   /** The entity roots this store-level provider serves (present with
@@ -315,6 +709,7 @@ export interface SyncStore {
 }
 
 export interface Store {
+  readonly replication?: Replication;
   readonly capabilities: StoreCapabilities;
   readonly dialect: Dialect;
   stats(): StoreStats;
@@ -336,13 +731,56 @@ export interface Store {
   readonly relations?: Readonly<Record<string, RelationTable>>;
   /** The unit of work (§11); present only with entities. */
   saveChanges?(): Promise<SaveReport>;
-  transaction<R>(fn: (store: Store) => R | Promise<R>): Promise<Awaited<R>>;
+  /**
+   * A top-level transaction. The callback receives a
+   * {@link TransactionStore} whose handles are INSIDE it; this store's
+   * own handles are an unrelated caller and wait for the commit.
+   *
+   * `signal` abandons the call while it is still QUEUED — the callback
+   * then never runs and no statement is issued (`JD2064`). A transaction
+   * that has already taken the connection runs to its own end.
+   *
+   * `unitOfWork: 'own'` gives the callback a tracker of its own, so two
+   * concurrent handlers hold two records for one entity key and neither
+   * sees the other's pending state; `'shared'` (the default) writes
+   * through the store's, which is what lets a caller `add()` a document
+   * outside the transaction and save it inside. Both behave identically
+   * with and without capture.
+   */
+  transaction<R>(fn: (store: TransactionStore) => R | Promise<R>,
+    options?: TransactionScopeOptions): Promise<Awaited<R>>;
   /** Register a change observer; requires capture. Returns unsubscribe. */
   observe(fn: (record: ChangeRecord) => void): () => void;
-  /** Read the persisted log forward (JD2051 without capture.log). */
+  /** Read the persisted log forward from `after` (`JD2051` without
+   * `capture.log`) — EVERY surviving record in one array, UNBOUNDED, with
+   * no watermark: a reconnecting consumer whose cursor fell below the
+   * retention floor receives the surviving suffix and cannot tell it
+   * from the whole. Unsafe for a reconnecting consumer; `changes.page()`
+   * is the supported path (LIVE-FORMAT §5). */
   changesSince?(after: number): Promise<ChangeRecord[]>;
+  /** The bounded change reader: the log's watermarks and pages that
+   * never exceed their bounds and report a retention gap explicitly;
+   * present exactly when the log is enabled. */
+  readonly changes?: ChangesReader;
   /** PRAGMA data_version — the coarse cross-connection signal. */
   dataVersion(): Promise<number>;
+  /** `PRAGMA wal_checkpoint(<mode>)` under the store gate (MODEL-FORMAT
+   * §4). Refused `JD2077` on a read-only store or a binding that does
+   * not declare it; a driver failure is `JD2078`. */
+  checkpoint(options?: CheckpointOptions): Promise<CheckpointResult>;
+  /** `PRAGMA integrity_check` under the store gate; corruption is the
+   * RESULT (`ok: false`), never a throw. */
+  integrityCheck(options?: IntegrityCheckOptions): Promise<IntegrityCheckResult>;
+  /** `PRAGMA foreign_key_check` under the store gate. */
+  foreignKeyCheck(options?: MaintenanceCallOptions): Promise<ForeignKeyCheckResult>;
+  /** `PRAGMA optimize` under the store gate; refused `JD2077` on a
+   * read-only store. */
+  optimize(options?: MaintenanceCallOptions): Promise<OptimizeResult>;
+  /** An online backup published whole or not at all (MODEL-FORMAT §4):
+   * copied to a temporary sibling, renamed onto `targetPath` only at
+   * verified completion; a cancelled (`JD2079`) or failed (`JD2078`)
+   * copy leaves neither file. Writers proceed during the copy. */
+  backupTo(targetPath: string, options?: BackupOptions): Promise<BackupResult>;
   /** Register a live query over an entity-root document (re-run
    * strategy in this version); present only with entities. */
   live?(document: unknown, options?: LiveOptions): Promise<LiveQuery>;
@@ -350,12 +788,148 @@ export interface Store {
    * `graceMs` to wind up; the connection closes whether or not they
    * did, and a handler still in flight is reported as JD2062. */
   close(options?: { graceMs?: number }): Promise<void>;
-  /** The queue surface; present when opened with `jobs` (JOBS-FORMAT). */
-  readonly jobs?: JobsApi;
+  /** The queue surface; present when opened with `jobs` (JOBS-FORMAT).
+   * Root calls here take the store gate — an unrelated enqueue, claim,
+   * checkpoint or settlement never joins an open application
+   * transaction's fate. The transactional-outbox spelling is the
+   * `tx.jobs` a transaction callback receives, which runs as the exact
+   * scope and co-commits with the domain transaction. */
+  readonly jobs?: JobsApi & JobsAdminApi;
   /** Present exactly when the driver is synchronous — never stubs. */
   readonly sync?: SyncStore;
 }
 
+/** The options a top-level transaction takes. An unknown `unitOfWork`
+ * value is a compile error here and runtime API misuse there. */
+export interface TransactionScopeOptions {
+  /** Abandons the call while it is still QUEUED (`JD2064`); a
+   * transaction that has taken the connection runs to its own end. */
+  signal?: AbortSignal;
+  /** `'own'` gives the callback an independent tracker; `'shared'`
+   * (the default) writes through the store's. */
+  unitOfWork?: 'own' | 'shared';
+  /** `'immediate'` takes the write lock up front (`BEGIN IMMEDIATE`), so
+   * a body that reads before it writes never meets the read→write
+   * upgrade `SQLITE_BUSY` the busy handler cannot retry — what a claim
+   * needs under concurrent writers; `'deferred'` (the default) is the
+   * savepoint as always. A nested `tx.transaction()` is a savepoint
+   * whichever mode the root chose; the synchronous twin has no mode. */
+  mode?: 'deferred' | 'immediate';
+}
+
+/**
+ * The named-savepoint group a live transaction view carries
+ * (MODEL-FORMAT §5.2): checkpoint-and-continue without a sentinel
+ * exception. The label is a map key and diagnostic for that exact
+ * transaction — never SQL; the driver generates the identifier. A
+ * blank, duplicate or unknown label is `JD2071`; a stale or
+ * cross-scope view is `JD2070` first. `rollbackTo` keeps the target
+ * active (repeated rollback is defined) and invalidates every later
+ * checkpoint; `release` removes the target and every later checkpoint,
+ * keeping their rows — the engine's own semantics, exactly.
+ */
+export interface SavepointController {
+  create(label: string): Promise<void>;
+  rollbackTo(label: string): Promise<void>;
+  release(label: string): Promise<void>;
+}
+
+/** The synchronous twin of {@link SavepointController}, answering
+ * values (present under `tx.sync` on a synchronous driver). */
+export interface SyncSavepointController {
+  create(label: string): void;
+  rollbackTo(label: string): void;
+  release(label: string): void;
+}
+
+/** The synchronous surface a transaction view carries: the store's,
+ * plus the transaction-only savepoint group. */
+export interface TransactionSyncStore extends SyncStore {
+  readonly savepoints: SyncSavepointController;
+}
+
+/**
+ * The store a transaction callback receives: the same surface, with
+ * every handle bound to THIS transaction's exact scope.
+ *
+ * `tx.collection(...)`, `tx.entity(...)`, `tx.sync`, `tx.jobs` and
+ * `tx.saveChanges()` run as the transaction's owner, and
+ * `tx.transaction(...)` nests through its savepoint. The outer store's
+ * handles are, by construction, an unrelated caller: they wait for the
+ * commit, and one awaited from inside the callback is a self-wait that
+ * `JD0012` names rather than a hang.
+ *
+ * The view lives exactly as long as its own scope: any stateful member
+ * used after the transaction settled, or while an async inner savepoint
+ * is current, refuses `JD2070` before touching tracker state or the
+ * database. There is deliberately no `close` — a transaction view does
+ * not own the store lifetime; the root store remains the only owner of
+ * the connection.
+ */
+export interface TransactionStore extends Omit<Store,
+  'close' | 'transaction' | 'sync' | 'checkpoint' | 'integrityCheck' | 'foreignKeyCheck' | 'optimize' | 'backupTo'
+  | 'jobs' | 'replication'> {
+  /** The transactional outbox (JOBS-FORMAT §3): no administration here —
+   * an admin operation is a root call. */
+  readonly jobs?: JobsApi;
+  transaction<R>(fn: (store: TransactionStore) => R | Promise<R>): Promise<Awaited<R>>;
+  /** Named partial rollback over the transaction's one savepoint stack
+   * (MODEL-FORMAT §5.2). Root stores, clients, workers and checkpoint
+   * stores expose none of it. */
+  readonly savepoints: SavepointController;
+  /** Present exactly when the driver is synchronous, as on the store. */
+  readonly sync?: TransactionSyncStore;
+}
+
+/** The log's two watermarks (LIVE-FORMAT §5): the earliest surviving
+ * sequence (`null` when nothing survives) and the highest sequence the
+ * FILE ever allocated — durable across an emptied log, a reopen and a
+ * second store over the same file, never a process counter. */
+export interface ChangeBounds {
+  readonly earliestAvailable: number | null;
+  readonly highWatermark: number;
+}
+
+/** A change page's options: `after` is the last sequence seen and is
+ * required — there is no legitimate "give me everything" for a change
+ * log; `limit` records at most (default `PAGE_LIMIT_DEFAULT`),
+ * `maxBytes` serialised patch bytes at most (none unless given),
+ * `signal` honoured at a record boundary (`JD2072`). */
+export interface ChangePageOptions {
+  after: number;
+  limit?: number;
+  maxBytes?: number | null;
+  signal?: AbortSignal;
+  /** An epoch-millisecond deadline, read against the store's clock at every record boundary (`JD2075`). */
+  deadline?: number;
+}
+
+/**
+ * One page of the log. `resetRequired: true` means the record after
+ * `after` no longer survives: `items` is EMPTY and `next` absent — a
+ * total refusal, never a partial suffix — and the consumer re-seeds
+ * from a snapshot and resumes at `highWatermark`. Otherwise `next` is
+ * the sequence to continue from (`after` itself when nothing was
+ * delivered), `hasMore` says whether records remain above it, and the
+ * watermarks are the log's as read after the page.
+ */
+export interface ChangePage {
+  readonly items: ChangeRecord[];
+  readonly next?: number;
+  readonly earliestAvailable: number | null;
+  readonly highWatermark: number;
+  readonly hasMore: boolean;
+  readonly resetRequired: boolean;
+}
+
+/** The bounded change reader (LIVE-FORMAT §5). A record larger than
+ * `maxBytes` is `JD2074` without advancing `next` — the same rule, the
+ * same implementation, as an entity page. */
+export interface ChangesReader {
+  bounds(): Promise<ChangeBounds>;
+  page(options: ChangePageOptions): Promise<ChangePage>;
+}
+
 /** One committed transaction's change record (LIVE-FORMAT §§1–5). */
 export interface ChangeRecord {
   /** Monotonic; continues across reopens when the log is enabled. */
@@ -405,7 +979,7 @@ export interface LiveEventTime {
 
 export interface LiveMode {
   readonly strategy: 'rows' | 'window' | 'accumulator' | 'group'
-    | 'bucket' | 'rolling' | 'rerun';
+    | 'bucket' | 'rolling' | 'join' | 'graph' | 'nested-group' | 'rerun';
   readonly mode: 'incremental' | 'rerun';
   /** Present exactly when the strategy is 'rerun': the named reason. */
   readonly reason?: string;
@@ -431,6 +1005,9 @@ export interface LiveEvent {
 }
 
 export interface LiveStats {
+  dependencyReads?: number;
+  refreshedRoots?: number;
+  refreshedGroups?: number;
   records: number;
   matched: number;
   emissions: number;
@@ -464,6 +1041,8 @@ export interface LiveQuery {
 }
 
 export interface LiveBounds {
+  /** Serialized input/output cache credit for join, graph and nested-group strategies. */
+  maxBytes?: number;
   /** Registrations beyond it are JD0052 (default 64). */
   maxQueries?: number;
   /** Per-query ceiling on maintained entries — rows, window entries
@@ -472,8 +1051,17 @@ export interface LiveBounds {
 }
 
 export interface OpenStoreOptions {
+  replication?: ReplicationOptions;
   driver: Driver;
   path?: string;
+  /**
+   * What a store-level call does while another caller's transaction owns
+   * the connection. `'wait'` (the default) queues behind it under
+   * `queueTimeout` and then refuses `JD0012`; `'strict'` refuses at once,
+   * for a host that would rather see the contention than pay for it.
+   * Either way the call never joins the transaction.
+   */
+  transactions?: 'wait' | 'strict';
   /** Change capture (LIVE-FORMAT): off unless requested. */
   capture?: boolean | CaptureOptions;
   /** Live-query bounds (LIVE-FORMAT §12). */
@@ -489,13 +1077,43 @@ export interface OpenStoreOptions {
    * where one was injected; without it the document is refused rather
    * than answered in UTC. No time-zone database is bundled. */
   zoneProvider?: unknown;
-  busyTimeout?: number;
+  /** The host's runtime record (`@jarenjs/core/runtime`): the clock the
+   * capture log and the job queue stamp, the identifier a `uuid`
+   * identity and a `default: 'uuid'` allocate, the job queue's backoff
+   * jitter and the zone provider — each read only where the explicit
+   * option (`zoneProvider`, `jobs.now`, `jobs.random`) is absent, and
+   * handed on to the job engine. */
+  runtime?: Partial<Runtime>;
   /** How long work waits for an open transaction to settle before
    * `JD0012` (MODEL-FORMAT §5.1); reaches every driver. */
   queueTimeout?: number;
-  journalMode?: string;
+  /**
+   * The connection pragmas — a closed, validated set (MODEL-FORMAT §4).
+   * An option naming any other pragma is `JD0006`; a pragma the driver
+   * or the store kind cannot apply is `JD0007`; every value is read back
+   * after the open sequence and reported on `capabilities.pragmas`, and
+   * one the engine did not take is `JD0008`.
+   */
+  /** `PRAGMA busy_timeout`, in milliseconds (default 5000). */
+  busyTimeout?: number;
+  /** `PRAGMA journal_mode` (default `'wal'` on a writable file; a
+   * read-only store keeps the file's mode and refuses an explicit one). */
+  journalMode?: 'delete' | 'truncate' | 'persist' | 'memory' | 'wal' | 'off';
+  /** `PRAGMA synchronous`. */
+  synchronous?: 'off' | 'normal' | 'full' | 'extra';
+  /** `PRAGMA wal_autocheckpoint`, in pages; `0` disables. */
+  walAutocheckpoint?: number;
+  /** `PRAGMA journal_size_limit`, in bytes; `-1` for none. */
+  journalSizeLimit?: number;
+  /** `PRAGMA cache_size`: pages, or negative KiB. */
+  cacheSize?: number;
+  /** `PRAGMA mmap_size`, in bytes. */
+  mmapSize?: number;
+  /** `PRAGMA temp_store`. */
+  tempStore?: 'default' | 'file' | 'memory';
   statementCacheBound?: number;
-  profile?: unknown;
+  /** The store-level safety profile (MODEL-FORMAT §8). */
+  profile?: 'safe' | ProfileSpec;
   readOnly?: boolean;
   /** A `createJsltRegistry()` registry (Ring 2/3): the operators a
    * query may use, and the pushable subset. */
@@ -530,7 +1148,37 @@ export interface Driver {
 
 export declare const sqliteDialect: Dialect;
 export declare function createDialect(spec: unknown): Dialect;
+/** The closed set of dialect capabilities, each with the answer a
+ * spelling spec that says nothing gets. `createDialect` refuses a name
+ * outside it, so a misspelling cannot read as a quiet `false`. */
+export declare const DIALECT_CAPABILITIES: Readonly<Record<string, boolean>>;
+/** The R*Tree mapping's DDL group for one spelling spec — the virtual
+ * table and the three row triggers that keep it in sync. Composed into
+ * a dialect whose `capabilities.virtualTables` is true. */
+export declare function rtreeDdl(spec: unknown): Record<string, Function>;
 export declare const SQLITE_FLOOR: string;
+/** Assemble the connection contract around a raw binding whose
+ * capabilities a probe has already answered. */
+export declare function finishConnection(
+  raw: unknown, dialect: Dialect, synchronous: boolean,
+  capabilities: Readonly<Record<string, unknown>>, queueTimeout: number,
+): unknown;
+/** The default probe: SQLite's version report, its compile options and
+ * what the binding declares. */
+export declare function sqliteProbe(
+  raw: unknown, dialect: Dialect, declared: unknown,
+): unknown;
+/** The capability answers every connection carries, each defaulted to
+ * the conservative one — what a probe for another engine fills in. */
+export declare function baseCapabilities(): Record<string, unknown>;
+/** The option names of the closed configurable-pragma set, in the
+ * order the open sequence applies them (MODEL-FORMAT §4). */
+export declare const PRAGMA_NAMES: readonly string[];
+/** The `PRAGMA wal_checkpoint` modes, closed. */
+export declare const CHECKPOINT_MODES: readonly string[];
+/** The maintenance operations, in the order `capabilities.maintenance`
+ * lists them. */
+export declare const MAINTENANCE_OPERATIONS: readonly string[];
 
 // ————— entities: models, mapping, generated types —————
 
@@ -564,6 +1212,8 @@ export declare function translateOperations(
 export declare function keyToken(parts: readonly unknown[]): string;
 export declare function createCaptureEngine(options: unknown): unknown;
 export declare const CHANGES_TABLE: string;
+/** The change log's durable state table: the highest sequence the file ever allocated (LIVE-FORMAT §5). */
+export declare const CHANGES_STATE_TABLE: string;
 export declare const DEFAULT_RETENTION: number;
 /** Deep-freeze a JSON value in place and return it (idempotent). */
 export declare function deepFreeze<T>(value: T): T;
@@ -572,6 +1222,58 @@ export declare const BATCH_ROW_BOUND: number;
 
 // ————— migrations —————
 
+/** Where a migration runs: the driver, the file (`':memory:'` when
+ * absent) and the busy timeout the run opens with. */
+export interface MigrationTarget {
+  driver: Driver;
+  path?: string;
+  /** `PRAGMA busy_timeout` for the run's connection, ms (default 5000). */
+  busyTimeout?: number;
+}
+
+/** One progress event: the migration and collection a data step is
+ * walking, and the running count of the rows it has transformed,
+ * derived or asserted so far (one of the three counters per event). */
+export interface MigrationProgress {
+  readonly migration: string;
+  readonly collection: string;
+  readonly transformed?: number;
+  readonly derived?: number;
+  readonly asserted?: number;
+}
+
+/** One row of an introspection's loss report: what the physical shape
+ * does not carry, by a stable code, once, sorted. */
+export interface IntrospectReportRow {
+  readonly code: string;
+  /** The physical object it is about (`users`, `users.gx_age`). */
+  readonly object: string;
+  readonly detail: string;
+}
+
+/** Every code the loss report uses, with what it means. */
+export declare const INTROSPECT_CODES: Readonly<Record<string, string>>;
+
+/**
+ * Database → model, read-only. Answers the `jaren-model` document this
+ * database's shape says it is, beside a report of everything the shape
+ * cannot carry. `strict` refuses instead of returning a partial model.
+ */
+export declare function introspectModel(connection: unknown, options?: {
+  strict?: boolean;
+  /** Narrow the read to a named set of tables. */
+  tables?: readonly string[];
+  /** The document pointer a text key column cannot record, per table. */
+  keys?: Record<string, string>;
+}): unknown;
+
+/** The neutral IR one read produces: tables with their columns,
+ * generated expressions, indexes and foreign keys, plus the views a
+ * model cannot declare. */
+export declare function readSchema(connection: unknown, options?: {
+  tables?: readonly string[];
+}): unknown;
+
 export interface MigrateOptions {
   baseline: unknown;
   model?: unknown;
@@ -579,14 +1281,64 @@ export interface MigrateOptions {
   dryRun?: boolean;
   batchSize?: number;
   shadow?: boolean;
+  /** Where the shadow replay runs (default `':memory:'`). */
+  shadowPath?: string;
+  /** The host's declared index-expression functions, by name — the same
+   * declarations `openStore` is given, resolved into the planned DDL. */
+  expressions?: Record<string, ExpressionFunction>;
+  /** The driver the shadow replay opens through (default the target's).
+   * A file engine's shadow is another file; a SERVER engine's is another
+   * schema, and only the host can name one — the baseline shape the
+   * replay creates would otherwise collide with the real store's. */
+  shadowDriver?: unknown;
+  /** Called once per batch a data step walks (transform, derive, or a
+   * per-document assertion). */
+  onProgress?: (progress: MigrationProgress) => void;
   /** Re-register declared deterministic functions on every connection
    * the migration opens (real, shadow, reference) — §10. */
   registerFunctions?: (connection: unknown) => unknown;
+  /** The host's runtime record: the clock every applied migration is
+   * stamped with and the deadline is read against; the platform's own
+   * when absent. */
+  runtime?: Partial<Runtime>;
+  /** Cancels between migrations, steps and batches (`JD2080`); the
+   * migration in flight rolls back whole. */
+  signal?: AbortSignal;
+  /** An epoch-millisecond deadline on `runtime`'s clock (`JD2075`). */
+  deadline?: number;
+  /** What a MATERIALIZING assertion may hold. A per-document predicate
+   * and a single associative aggregate over the root are answered in
+   * batches and are never bounded by this; anything else must hold the
+   * collection at once and crosses these bounds before the excess is
+   * held (`JD2007` rows, `JD2076` bytes). Defaults to
+   * {@link ASSERTION_BOUNDS_DEFAULT}; `null` on either member removes
+   * that bound, deliberately. */
+  assertionBounds?: { maxRows?: number | null; maxBytes?: number | null };
 }
 
+/** The finite defaults a materializing assertion runs under when the
+ * caller declares none: 100,000 rows and 64 MiB. */
+export declare const ASSERTION_BOUNDS_DEFAULT: {
+  readonly maxRows: number;
+  readonly maxBytes: number;
+};
+
+/** How a host must run an assertion, and why. `perDocument` walks in
+ * batches; `fold` is one associative aggregate whose batch answers
+ * combine; `materialize` needs every document at once and is bounded. */
+export declare function classifyAssertion(query: unknown): {
+  strategy: 'perDocument' | 'fold' | 'materialize';
+  shape: string | null;
+  reason: string;
+};
+
 export declare function migrate(
-  target: unknown, migrations: readonly unknown[], options: MigrateOptions,
+  target: MigrationTarget, migrations: readonly unknown[], options: MigrateOptions,
 ): Promise<unknown>;
+/** Whether an assertion step is a per-document predicate (a FLWOR over
+ * `$[*]` whose body reads only its binding), which the runner evaluates
+ * per batch; anything else reads the collection whole. */
+export declare function isPerDocumentAssertion(query: unknown): boolean;
 export declare function planMigration(from: unknown, to: unknown, options?: unknown): unknown;
 /** The whole-model diff — collections AND entities (MIGRATION-FORMAT §9). */
 export declare function planModelMigration(from: unknown, to: unknown, options?: unknown): unknown;
@@ -597,11 +1349,15 @@ export interface MigrationStatusReport {
   drift: string | null;
   upToDate: boolean;
 }
+/** Report a database's migration state without touching it: the
+ * history table is probed, never created. `model` enables the drift
+ * comparison once the chain is fully applied. */
 export declare function migrationStatus(
-  target: { driver: Driver; path?: string },
+  target: MigrationTarget,
   migrations: readonly unknown[],
-  options: { baseline: unknown; model?: unknown;
-    registerFunctions?: (connection: unknown) => unknown },
+  options?: { model?: unknown;
+    registerFunctions?: (connection: unknown) => unknown;
+    signal?: AbortSignal; deadline?: number; runtime?: Partial<Runtime> },
 ): Promise<MigrationStatusReport>;
 /** Create a model's whole physical shape on a connection. */
 export declare function createModelShape(connection: unknown, model: unknown): unknown;
@@ -619,6 +1375,97 @@ export declare function migrationChecksum(migration: unknown): string;
 export declare const MIGRATION_VERSION: string;
 export declare const HISTORY_TABLE: string;
 
+/** The counters a storeless run reports for one collection. */
+export interface DocumentMigrationCounts {
+  readonly read: number;
+  readonly transformed: number;
+  readonly asserted: number;
+}
+
+/** What a storeless run did, per collection: `materialized` held the
+ * documents and ran the steps as a Store does; `streamed` carried each
+ * batch through every step in one pass. */
+export type DocumentMigrationStrategy = 'materialized' | 'streamed';
+
+export interface DocumentMigrationReport {
+  /** The migration ids this run applied, in order. */
+  readonly applied: string[];
+  /** Always empty: a storeless run has no history to skip against. */
+  readonly skipped: string[];
+  /** The last migration's target shape hash, or null for no migrations. */
+  readonly shape: string | null;
+  readonly counts: Record<string, DocumentMigrationCounts>;
+  readonly strategy: Record<string, DocumentMigrationStrategy>;
+}
+
+export interface DocumentMigrationOptions {
+  /** What a MATERIALIZING assertion may hold; the same bounds, and the
+   * same refusals, a Store applies. Defaults to
+   * {@link ASSERTION_BOUNDS_DEFAULT}. */
+  assertionBounds?: { maxRows?: number | null; maxBytes?: number | null };
+  /** Documents per assertion batch and per progress event (default 500). */
+  batchSize?: number;
+  onProgress?: (progress: MigrationProgress) => void;
+  /** The key members of a collection's documents, which a transform may
+   * keep but never move; a Store reads these from its model. */
+  keys?: Record<string, readonly string[]>;
+  /** The JSLT compiler a `jslt` step is compiled with (the suite's own
+   * when absent). */
+  compileJslt?: (stylesheet: unknown) => (document: unknown) => unknown;
+  /** The query compiler a `query` step is compiled with. */
+  compileQuery?: (query: unknown) => unknown;
+  runtime?: Partial<Runtime>;
+  /** Cancels between steps and batches (`JD2080`). */
+  signal?: AbortSignal;
+  /** An epoch-millisecond deadline on `runtime`'s clock (`JD2075`). */
+  deadline?: number;
+}
+
+/** Apply a migration's document steps to documents held in memory. The
+ * source is rewindable, so the steps run exactly as a Store runs them —
+ * every step over the whole collection, in step order — which is what
+ * makes the answer, and the refusal, identical to the Store's. A step
+ * that needs tables (`ddl`, `sql`, `rebuild`, `derive`) is refused
+ * (`JD0023`) before the first document is read. */
+export declare function migrateDocuments(
+  collections: Record<string, readonly unknown[]>,
+  migrations: readonly unknown[],
+  options?: DocumentMigrationOptions,
+): Promise<{ documents: Record<string, unknown[]>; report: DocumentMigrationReport }>;
+
+/** Apply a migration's document steps to a source that can be walked
+ * only once, writing each document out as it finishes: the input is
+ * consumed exactly once and nothing beyond one batch is held. A
+ * cross-document assertion, which needs every document at once, is
+ * refused by name rather than silently buffering the collection. */
+export declare function streamDocuments(
+  sources: Record<string, Iterable<unknown> | AsyncIterable<unknown>>,
+  migrations: readonly unknown[],
+  options: DocumentMigrationOptions & {
+    write: (collection: string, document: unknown) => unknown;
+  },
+): Promise<DocumentMigrationReport>;
+
+/** The step kinds that act on documents, and so run on any host. */
+export declare const DOCUMENT_STEP_KINDS: ReadonlySet<string>;
+/** The step kinds that need a physical database and are refused without one. */
+export declare const PHYSICAL_STEP_KINDS: ReadonlySet<string>;
+/** Compile one document step into the operation every host runs. */
+export declare function compileDocumentStep(
+  step: unknown, index: number, context: {
+    migrationId: string;
+    compileJslt: (stylesheet: unknown) => (document: unknown) => unknown;
+    compileQuery: (query: unknown) => unknown;
+    keys?: readonly string[];
+  },
+): unknown;
+/** Structural validation of one migration document (`JD0023`/`JD0021`). */
+export declare function checkMigrationDocument(migration: unknown): void;
+/** The refusal a failing step raises, spelled the one way every host spells it. */
+export declare function stepFailure(
+  migrationId: string, index: number, kind: string, reason: string, cause?: Error,
+): DbCompileError;
+
 // ————— the machinery exports —————
 // The planner/emitter/residual/profile internals are public for tools
 // and tests; their documents have their own formats, so their types
@@ -628,11 +1475,25 @@ export declare function planCollection(name: string, collection: unknown, dialec
 export declare function compileIndexPath(expression: string, docPath: string): unknown;
 export declare function normalizeDeclaredSql(sql: string): string;
 export declare function comparableDeclaredSql(sql: string): string;
+/** The comparison kind a declared schema type implies — what a column
+ * over that member holds, and how its expression must read it. */
+export declare function columnKindFor(
+  schemaType: string | undefined,
+): 'text' | 'number' | 'boolean' | undefined;
 export declare function schemaTypeAt(schema: unknown, segments: unknown): unknown;
 export declare const KEY_COLUMN: string;
 export declare const DOC_COLUMN: string;
 export declare function planQuery(document: unknown, shape: unknown, options?: unknown): unknown;
 export declare function assertDecidedKind(node: unknown): void;
+/** The planner's reason vocabulary: every cause a plan can name for work
+ * it left in the engine, under a stable identifier. Most entries are the
+ * whole sentence; the four that quote the caller's own values carry the
+ * stable opening they begin with. */
+export declare const PLANNER_REASONS: Readonly<Record<string,
+  { readonly text: string } | { readonly prefix: string }>>;
+/** The vocabulary identifier of one reason sentence, or `null` when no
+ * entry claims it. */
+export declare function reasonId(reason: string): string | null;
 export declare function entityShape(entity: unknown, entityMapping: unknown): unknown;
 export declare function entityPathRef(node: unknown, slot: number, shape: unknown): unknown;
 export declare function planEntityPredicate(node: unknown, slot: number, shape: unknown): unknown;
@@ -645,12 +1506,80 @@ export declare function parseGraphRow(node: unknown, row: unknown, docField?: st
 export declare function selectPlan(collection: string): unknown;
 export declare function conjoin(plan: unknown, predicate: unknown): unknown;
 export declare function assertNoSqlText(plan: unknown): void;
+/** Whether an order term reads its value from a mapped column rather
+ * than the document. */
+export declare function ordersByColumn(ref: unknown): boolean;
+/** The effective order a set of declared terms executes under: the terms,
+ * then the tie-breaker the emitter appends — the primary key when
+ * `keyColumns` is given (keyset mode), one row identity per binding
+ * otherwise. */
+export declare function effectiveOrder(
+  terms: unknown, options?: { bindings?: (string | null)[]; keyColumns?: readonly string[] },
+): EffectiveOrderTerm[];
+/** The effective order of one plan, in the same normalized form its
+ * emitter renders; `null` for a statement that orders nothing. */
+export declare function planOrder(plan: unknown): EffectiveOrderTerm[] | null;
 export declare const PLAN_VERSION: number;
 export declare function typeOfPath(shape: unknown, segments: unknown): unknown;
 export declare function isNumericType(type: unknown): boolean;
 export declare function compileSetResidual(document: unknown, limits?: unknown): unknown;
 export declare function compileRowResidual(rowReturn: unknown, limits?: unknown): unknown;
+export declare function compilePackedResidual(document: unknown, limits?: unknown): unknown;
+/** The one cursor mechanism every engine builds on: a row source pulled
+ * one row per `next()` and released exactly once, or a materialised
+ * source that says so. */
+export declare function createCursor<T = unknown>(spec: {
+  streaming: 'row' | 'buffered';
+  barrier?: CursorBarrier | null;
+  signal?: AbortSignal;
+  materialize?: () => unknown;
+  open?: () => unknown;
+  items?: (row: unknown) => T[];
+}): QueryCursor<T>;
 export declare function sequenceResult(items: unknown[]): unknown;
+// ————— model-declared index expressions —————
+
+/** The three node kinds, closed: `member`, `value`, `call`. */
+export declare const EXPRESSION_KINDS: readonly string[];
+/** How deep a declared expression may nest. */
+export declare const EXPRESSION_DEPTH: number;
+/** One host declaration for a function a model's index expression may
+ * name. An engine that registers functions needs `apply`; one that
+ * cannot needs the `sql` name of an IMMUTABLE function it already has. */
+export interface ExpressionFunction {
+  arity: number;
+  /** Required, and never inferred: an index over a function that may
+   * answer differently for one row is an index that lies. */
+  deterministic: true;
+  apply?: (...args: any[]) => unknown;
+  sql?: string;
+}
+/** Resolve one expression against the host's declarations, refusing an
+ * unknown, wrong-arity or non-deterministic function with `JD0004`. */
+export declare function normalizeExpression(
+  node: unknown, docPath: string, declarations: Record<string, ExpressionFunction>,
+  depth?: number,
+): unknown;
+/** The identity two declarations of one expression share. */
+export declare function canonicalExpression(node: unknown): string;
+/** Every member path an expression reads, in order. */
+export declare function expressionMembers(node: unknown, out?: string[]): string[];
+/** Every function an expression calls, sorted. */
+export declare function expressionFunctions(node: unknown, out?: Set<string>): string[];
+/** The SQL an expression compiles to on one dialect. */
+export declare function expressionSql(
+  node: unknown, dialect: Dialect, context: unknown,
+): string;
+/** A short, stable column stem for one expression. */
+export declare function expressionStem(node: unknown): string;
+/** The SQL name a declared function is registered under. */
+export declare function registeredName(name: string): string;
+/** Register every function a set of expressions calls, on one connection. */
+export declare function registerExpressionFunctions(
+  connection: unknown, names: readonly string[],
+  declarations: Record<string, ExpressionFunction>,
+): unknown;
+
 export declare function deterministicFragment(fragment: unknown): unknown;
 export declare function registerFragment(connection: unknown, registered: Set<string>, fragment: unknown): void;
 export declare function createQueryEngine(context: unknown): unknown;
@@ -658,6 +1587,9 @@ export declare function createQueryState(bound?: number): unknown;
 export declare function createEntityQueryEngine(context: unknown): unknown;
 export declare function createLoadEngine(context: unknown, entityName: string): unknown;
 export declare const INCLUDE_DEPTH_DEFAULT: number;
+export declare const INCLUDE_ROWS_DEFAULT: number;
+export declare const INCLUDE_BYTES_DEFAULT: number;
+export declare const PAGE_LIMIT_DEFAULT: number;
 export declare function normalizeProfile(profile: unknown): unknown;
 export declare const SAFE_PROFILE: unknown;
 export declare function translateProfilePredicate(predicate: unknown, shape: unknown): unknown;
@@ -680,7 +1612,7 @@ export declare function createLiveRegistry(
   bounds: { maxQueries: number; maxMaintained: number }): unknown;
 export declare function diffRows(oldRows: readonly unknown[], newRows: readonly unknown[]):
   Array<{ op: string; path: string; value?: unknown }>;
-export declare const LIVE_DEFAULTS: { maxQueries: number; maxMaintained: number };
+export declare const LIVE_DEFAULTS: { maxQueries: number; maxMaintained: number; maxBytes: number };
 export declare function createSortedWindow(
   terms: unknown[], limit: number | null): unknown;
 export declare function compareCodepoint(a: string, b: string): number;
@@ -721,49 +1653,133 @@ export declare function identityBatches(identities: unknown[]): unknown;
 
 // ————— the job queue (JOBS-FORMAT) —————
 
+/** A job's state: `cancelled` is terminal like `done` and `dead` and
+ * is set only by `cancel()` (JOBS-FORMAT §10). */
+export type JobState = 'pending' | 'leased' | 'done' | 'failed' | 'dead' | 'cancelled';
+
 export interface JobRecord {
   readonly id: string;
   readonly kind: string;
   readonly payload: unknown;
-  readonly state: 'pending' | 'leased' | 'done' | 'failed' | 'dead';
+  readonly state: JobState;
   readonly runAt: number;
   readonly attempts: number;
   readonly maxAttempts: number;
   readonly leaseUntil: number | null;
   readonly leaseOwner: string | null;
+  /** How many times this job has been claimed. It identifies the
+   * ATTEMPT, which the owner cannot: one worker reuses one owner. */
+  readonly leaseGeneration: number;
   readonly lastError: string | null;
   readonly result: unknown;
   readonly createdAt: number;
   readonly updatedAt: number;
 }
 
+/**
+ * The capability one claim mints: the right to settle THIS attempt of
+ * this job, for as long as the lease is valid.
+ *
+ * It is a token rather than an owner, because an owner is reused by
+ * every attempt one worker makes and so cannot say which attempt is
+ * speaking. It is immutable: `renew` answers a NEW lease and retires
+ * this one, so a reference kept across a renewal can never quietly
+ * become valid again.
+ *
+ * Only `claim` and `renew` hand one out. `get` does not — a record
+ * anyone can read must not carry the capability to settle it.
+ */
+export interface JobLease {
+  readonly jobId: string;
+  readonly token: string;
+  readonly generation: number;
+  readonly attempt: number;
+  /** Diagnostics only: never a guard. */
+  readonly owner: string | null;
+  readonly expiresAt: number;
+}
+
+/** What `claim` answers: the record, and the lease to settle it with. */
+export interface ClaimedJob extends JobRecord {
+  readonly lease: JobLease;
+}
+
 export interface JobCounts {
   pending: number;
   leased: number;
   done: number;
   failed: number;
   dead: number;
+  cancelled: number;
   /** Pending/failed totals per kind — how a handler-less kind REPORTS. */
   pendingKinds: Record<string, number>;
 }
 
+/** What became of one attempt. A LOST settlement is its own outcome:
+ * counting it as a completion is what let a corpse report success over
+ * work another attempt was still doing, and counting it as a failure
+ * would burn a retry the job never spent. */
+export interface JobOutcome {
+  /** `cancelled`: the attempt was taken from this worker by `cancel()`
+   * with its lease — neither a completion, a failure nor a loss. */
+  readonly outcome: 'completed' | 'failed' | 'lost' | 'cancelled';
+  /** Where the loss was noticed: settling the result, or settling the
+   * failure that came before it. Absent on the other two outcomes. */
+  readonly phase?: 'completion' | 'failure';
+  readonly jobId: string;
+  readonly kind: string;
+  readonly attempt: number;
+  readonly generation: number;
+  /** The refusal code a lost settlement carries (`JD2065`/`JD2066`/
+   * `JD2067`); `null` when the lease was lost some other way. */
+  readonly code?: string | null;
+  readonly reason?: string;
+}
+
 export interface JobWorker {
   start(): JobWorker;
   /** Stop claiming, signal in-flight handlers, and wait up to `graceMs`
    * (JOBS-FORMAT §6): the record says whether every loop drained. */
   stop(options?: { graceMs?: number }): Promise<{ drained: boolean; inFlight: number }>;
   stats(): { claims: number; completions: number; failures: number;
-    polls: number; wakes: number; claimErrors: number; inFlight: number };
+    polls: number; wakes: number; claimErrors: number; inFlight: number;
+    /** Leases replaced while a handler was still running. */
+    renewals: number;
+    /** Attempts whose lease was lost mid-flight — never a completion,
+     * never a failure. */
+    lostSettlements: number;
+    /** Attempts cancelled through `cancel()` while their handler ran. */
+    cancellations: number };
+  /** The leases this worker holds right now: one per in-flight attempt,
+   * each the newest that attempt has been given. */
+  leases(): readonly JobLease[];
 }
 
 export interface JobWorkerOptions {
+  /**
+   * `checkpoints` is bound to THIS attempt and follows its current
+   * lease, so a renewal does not strand it. `signal` aborts for either
+   * reason a handler must wind up for: the worker is stopping, or the
+   * job is no longer this attempt's to finish — in which case the
+   * signal's `reason` is the coded refusal that says which.
+   */
   handlers: Record<string, (payload: unknown, context: {
-    job: JobRecord; checkpointsFor: Function; signal: AbortSignal }) => unknown>;
+    job: ClaimedJob;
+    checkpoints: { load(runId: string): unknown;
+      save(runId: string, nodeId: string, value: unknown): unknown;
+      complete(runId: string, result: unknown): unknown };
+    signal: AbortSignal }) => unknown>;
   /** A positive integer; the loops claiming concurrently. */
   concurrency?: number;
   pollInterval?: number;
   leaseMs?: number;
   owner?: string;
+  /** Renew each attempt's lease while its handler runs (the default).
+   * `false` for a handler that must not outlive its lease. */
+  renew?: boolean;
+  /** Called once per settled attempt, including the lost ones. An
+   * observer that throws never affects the loop. */
+  onOutcome?: (event: JobOutcome) => void;
   backoffBase?: number;
   backoffCap?: number;
   /** How long `stop()` waits for in-flight handlers by default. */
@@ -775,13 +1791,30 @@ export interface JobsApi {
     options?: { id?: string; runAt?: number; maxAttempts?: number }): Promise<string>;
   get(id: string): Promise<JobRecord | undefined>;
   counts(): Promise<JobCounts>;
-  /** The low-level guarded claim the worker itself uses (§3). */
+  /** The low-level guarded claim the worker itself uses (§3). It mints
+   * the fence: a fresh token and the next generation. */
   claim(options: { kinds: string[]; owner: string; leaseMs?: number }):
-    Promise<JobRecord | undefined>;
-  complete(id: string, owner: string, result?: unknown): Promise<boolean>;
-  fail(id: string, owner: string, error: unknown): Promise<boolean>;
-  /** The per-job flow checkpoint store binding (§7). */
-  checkpointsFor(job: JobRecord): {
+    Promise<ClaimedJob | undefined>;
+  /**
+   * Replace a lease with a later one (§3). A handler that runs longer
+   * than its lease renews rather than hoping; the lease it is given
+   * back supersedes the one it passed in, which then settles nothing.
+   *
+   * Refuses `JD2065` (the job is not leased — unknown, or already
+   * settled), `JD2066` (the lease was superseded) or `JD2067` (it
+   * expired), never a silent `false`.
+   */
+  renew(lease: JobLease, options?: { leaseMs?: number }): Promise<JobLease>;
+  /** Settle the attempt this lease holds. `true`, or one of the three
+   * coded refusals above — a caller that cannot tell "already done"
+   * from "you are stale" guesses, and guesses wrong. */
+  complete(lease: JobLease, result?: unknown): Promise<boolean>;
+  fail(lease: JobLease, error: unknown): Promise<boolean>;
+  /** The per-attempt flow checkpoint store binding (§7). Rows are
+   * stamped with the attempt's generation: `load` reads what was
+   * written up to it, and a settlement prunes no further, so a stale
+   * attempt cannot erase a live one's work. */
+  checkpointsFor(job: ClaimedJob): {
     load(runId: string): unknown;
     save(runId: string, nodeId: string, value: unknown): unknown;
     complete(runId: string, result: unknown): unknown;
@@ -789,6 +1822,45 @@ export interface JobsApi {
   createWorker(options: JobWorkerOptions): JobWorker;
 }
 
+export interface JobPageOptions {
+  /** A closed state; every job when absent. */
+  state?: JobState;
+  kind?: string;
+  /** The id to continue past (keyset by id). */
+  after?: string;
+  /** At most this many items (default 100). */
+  limit?: number;
+  /** Row-boundary cancellation, as every cursor (`JD2072` / `JD2075`). */
+  signal?: AbortSignal;
+  deadline?: number;
+}
+
+/**
+ * Job administration (JOBS-FORMAT §10) — root-only mechanism, never a
+ * schedule: WHEN to sweep or cancel is the host's call.
+ */
+export interface JobsAdminApi {
+  /** A keyset cursor over the queue by id, admitted per pull under the
+   * store gate; each item is the record `get` answers. */
+  page(options?: JobPageOptions): QueryCursor<JobRecord>;
+  /** Cancel a queued job by its identity, or a claimed one through its
+   * CURRENT lease (the fence's rule): the row settles as `cancelled`,
+   * a local attempt's handler signal aborts, and the call resolves once
+   * that attempt wound up. `true` when this call cancelled it, `false`
+   * when it already was; `JD2065`/`JD2066`/`JD2067`/`JD2068` as a
+   * settling call refuses. */
+  cancel(id: string, options?: { lease?: JobLease; signal?: AbortSignal; deadline?: number }): Promise<boolean>;
+  /** Return a failed, dead, cancelled or lease-expired job to the queue
+   * with its attempt history intact; `false` when it already was
+   * pending; a live lease refuses `JD2068`, unknown or done `JD2065`. */
+  requeue(id: string, options?: { signal?: AbortSignal; deadline?: number }): Promise<boolean>;
+  /** Delete settled jobs (done, dead, cancelled) last changed before
+   * `settledBefore`, oldest first, at most `limit`, with their
+   * checkpoints; a second identical sweep answers `{ removed: 0 }`. */
+  sweep(options: { settledBefore: number; limit?: number; signal?: AbortSignal; deadline?: number }):
+    Promise<{ removed: number }>;
+}
+
 export interface JobsOptions {
   maxAttempts?: number;
   leaseMs?: number;
@@ -809,14 +1881,21 @@ export declare function createDagJobRunner(store: Store, options: {
   pollInterval?: number;
   leaseMs?: number;
   owner?: string;
+  renew?: boolean;
+  onOutcome?: (event: JobOutcome) => void;
   backoffBase?: number;
   backoffCap?: number;
   stopGraceMs?: number;
 }): JobWorker;
 
+/** The checkpoint row a run's identity lives in — the workflow revision
+ * and a hash of the input a resume must agree with (`JD2069` when it
+ * does not). Pruned with the run it belongs to. */
+export declare const RUN_IDENTITY_NODE: string;
+
 export declare function createJobEngine(options: {
   connection: unknown; now?: () => number; random?: () => number;
-  defaults?: JobsOptions }): unknown;
+  defaults?: JobsOptions; runtime?: Partial<Runtime> }): unknown;
 export declare const JOBS_TABLE: string;
 export declare const JOB_CHECKPOINTS_TABLE: string;
 export declare const JOB_DEFAULTS: Readonly<{
@@ -826,3 +1905,55 @@ export declare const JOB_DEFAULTS: Readonly<{
 export declare function describeValue(value: unknown): string;
 /** A job result as the queue stores it: JSON text, or the reason it could not be. */
 export declare function serializeResult(value: unknown): unknown;
+
+/** Transport-neutral, net logical operations in a single transaction. */
+export interface ReplicationOperation {
+  table: string;
+  key: string;
+  before: Record<string, unknown> | null;
+  after: Record<string, unknown> | null;
+}
+export type ReplicationFrontier = Record<string, number>;
+export interface ReplicationEnvelope {
+  $replication: '0.1'; replica: string; seq: number; model: string;
+  frontier: ReplicationFrontier; operations: ReplicationOperation[];
+}
+export interface ReplicationConflict {
+  envelope: string; table: string; key: string;
+  base: Record<string, unknown> | null;
+  local: { value: Record<string, unknown> | null; frontier: ReplicationFrontier };
+  remote: { value: Record<string, unknown> | null; replica: string; seq: number; frontier: ReplicationFrontier };
+  resolver: string | null;
+  resolution: { action: 'local' | 'remote' | 'merged'; value: Record<string, unknown> | null } | null;
+}
+export interface ReplicationOptions {
+  replica: string; retention?: number; maxOperations?: number; maxBytes?: number;
+  resolver?: { id: string; resolve(conflict: Readonly<ReplicationConflict>):
+    { action: 'local' | 'remote' } | { action: 'merged'; value: Record<string, unknown> | null } };
+}
+export interface ReplicationRequest { signal?: AbortSignal; deadline?: number }
+export interface Replication {
+  snapshot(request?: ReplicationRequest): Promise<ReplicationSnapshot>;
+  reset(snapshot: ReplicationSnapshot, request?: ReplicationRequest): Promise<{ status: 'reset'; frontier: ReplicationFrontier }>;
+  frontier(): Promise<ReplicationFrontier>;
+  apply(envelope: ReplicationEnvelope, request?: ReplicationRequest): Promise<{
+    status: 'applied' | 'duplicate' | 'conflict'; frontier: ReplicationFrontier; conflicts: ReplicationConflict[];
+  }>;
+  page(request?: ReplicationRequest & { after?: number; limit?: number; maxBytes?: number }): Promise<{
+    items: ReplicationEnvelope[]; earliestAvailable: number | null; highWatermark: number;
+    next?: number; bytes?: number; hasMore: boolean; resetRequired: boolean;
+  }>;
+  conflicts(request?: ReplicationRequest & { limit?: number; maxBytes?: number }): Promise<ReplicationConflict[]>;
+}
+export declare const REPLICATION_VERSION: '0.1';
+export declare const REPLICATION_DEFAULTS: Readonly<{ retention: number; maxOperations: number; maxBytes: number }>;
+export declare function normalizeFrontier(value: unknown): ReplicationFrontier;
+export declare function replicationIdentity(replica: string, seq: number): string;
+export declare function normalizeReplication(document: unknown): ReplicationEnvelope;
+export declare function encodeReplication(document: unknown): string;
+export interface ReplicationSnapshot {
+  $replicationSnapshot: '0.1'; model: string; frontier: ReplicationFrontier;
+  rows: { table: string; key: string; value: Record<string, unknown> | null; frontier: ReplicationFrontier }[];
+  receipts: ReplicationEnvelope[];
+}
+export declare function normalizeReplicationSnapshot(document: unknown): ReplicationSnapshot;