@jarenjs/db 0.46.5 → 0.56.0

package/types/index.d.ts

@@ -84,7 +84,9 @@ export interface ExecuteOptions {
   pushdown?: boolean;
 }
 
-export interface LoadInclude extends LoadSpec {
+/** An include's clauses: the root's without `after` — a keyset cursor
+ * paginates the root alone; an include windows with `skip`/`take`. */
+export interface LoadInclude extends Omit<LoadSpec, 'after'> {
   /** Project the related-row COUNT instead of the rows. */
   count?: boolean;
 }
@@ -128,6 +130,8 @@ export interface StoreStats {
     tracked: number;
     pendingInserts: number;
     pendingDeletes: number;
+    /** Pending `link`/`unlink` records: one per entity, own key and member (§11.7). */
+    pendingMemberships: number;
   } | null;
   liveQueries: number;
 }
@@ -143,6 +147,10 @@ export interface StoreCapabilities {
   readonly captureLog: boolean;
   readonly live: boolean;
   readonly jobs: boolean;
+  /** Whether a temporal spec naming a ZONE compiles here (D7's
+   * injected clock was supplied at open). Without it such a document
+   * is refused rather than answered in UTC. */
+  readonly zoneProvider: boolean;
   readonly [capability: string]: unknown;
 }
 
@@ -182,12 +190,44 @@ export interface SyncCollection<T = unknown> {
 
 // ————— entities (phase B) —————
 
+/** One row of an entity's relation table (MODEL-FORMAT §10.1): the
+ * declared relation as plain data a query producer can lower a hop
+ * from — never a document dialect. For a foreign-key relation `via`
+ * names the key property, `fkEntity` the entity holding it, `fkTargets`
+ * the entity it references and `targetKey` the key property it
+ * references there (the column a hop's equality compares `via` with);
+ * `kind` says which side holds the key (`oneToOne`: the declaring
+ * entity; `oneToMany`: the target). A many-to-many carries its
+ * `joinTable` and the target's `targetKey`. */
+export interface RelationEntry {
+  readonly to: string;
+  readonly kind: 'oneToOne' | 'oneToMany' | 'manyToMany';
+  readonly via?: string;
+  readonly fkEntity?: string;
+  readonly fkTargets?: string;
+  readonly joinTable?: string;
+  readonly targetKey: string;
+}
+
+/** An entity's relation table: one entry per declared relation member. */
+export type RelationTable = Readonly<Record<string, RelationEntry>>;
+
+/** The identity every entity set of one store shares — two sets with one
+ * `scope` may be joined in one document — carrying the relation tables
+ * of every root, keyed by entity name, so a hop can chain into another
+ * root of the same scope. */
+export interface EntityScope {
+  readonly relations: Readonly<Record<string, RelationTable>>;
+}
+
 export interface UntrackedReads<T = unknown> {
   get(key: EntityKeyArg): Promise<T | undefined>;
   load(spec?: LoadSpec): Promise<T[]>;
 }
 
 export interface EntitySet<T = unknown, I = unknown> {
+  /** The provider phantom: a chain over this set infers its item type. */
+  readonly __item?: T;
   create(doc: I): Promise<Readonly<T>>;
   get(key: EntityKeyArg): Promise<Readonly<T> | undefined>;
   update(key: EntityKeyArg, changes: Partial<T>): Promise<Readonly<T>>;
@@ -202,7 +242,27 @@ export interface EntitySet<T = unknown, I = unknown> {
   remove(key: EntityKeyArg | T): void;
   /** Drop tracking without scheduling anything — conflict recovery. */
   discard(key: EntityKeyArg | T): void;
+  /** Attach / detach one many-to-many membership through the unit of
+   * work (§11.7): local bookkeeping, written by `saveChanges()` as join
+   * rows against the join table as it stands then — idempotent. `own`
+   * and `target` are each a key or a document carrying the key. */
+  link(own: EntityKeyArg | T, member: string, target: EntityKeyArg | object): void;
+  unlink(own: EntityKeyArg | T, member: string, target: EntityKeyArg | object): void;
   asNoTracking(): UntrackedReads<T>;
+  /** The provider contract over this entity's root (MODEL-FORMAT §10.1):
+   * 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>>;
+  explain(document: unknown, options?: ExecuteOptions): Promise<unknown>;
+  /** The root expression this set's rows are bound through (`$.<Name>[*]`). */
+  readonly root: string;
+  /** The identity every entity set of one store shares: two sets with one
+   * `scope` may be joined in one document; it carries every root's
+   * relation table. */
+  readonly scope: EntityScope;
+  /** This entity's relation table (MODEL-FORMAT §10.1) — what a query
+   * producer lowers a relation hop from. */
+  readonly relations: RelationTable;
 }
 
 export interface SyncUntrackedReads<T = unknown> {
@@ -211,6 +271,8 @@ export interface SyncUntrackedReads<T = unknown> {
 }
 
 export interface SyncEntitySet<T = unknown, I = unknown> {
+  /** The provider phantom: a chain over this set infers its item type. */
+  readonly __item?: T;
   create(doc: I): Readonly<T>;
   get(key: EntityKeyArg): Readonly<T> | undefined;
   update(key: EntityKeyArg, changes: Partial<T>): Readonly<T>;
@@ -221,7 +283,15 @@ export interface SyncEntitySet<T = unknown, I = unknown> {
   put(next: T): Readonly<T>;
   remove(key: EntityKeyArg | T): void;
   discard(key: EntityKeyArg | T): void;
+  link(own: EntityKeyArg | T, member: string, target: EntityKeyArg | object): void;
+  unlink(own: EntityKeyArg | T, member: string, target: EntityKeyArg | object): void;
   asNoTracking(): SyncUntrackedReads<T>;
+  /** The provider contract over this entity's root, answering values. */
+  execute<R = unknown>(document: unknown, options?: ExecuteOptions): SequenceResult<R>;
+  explain(document: unknown, options?: ExecuteOptions): unknown;
+  readonly root: string;
+  readonly scope: EntityScope;
+  readonly relations: RelationTable;
 }
 
 // ————— the store —————
@@ -233,6 +303,14 @@ export interface SyncStore {
   entity(name: string): SyncEntitySet;
   transaction<R>(fn: (store: Store) => 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
+   * entities): it has no single root of its own, so a chain over it is
+   * refused by name — chain over `entity(name)` instead. */
+  readonly roots?: readonly string[];
+  /** The relation tables of every entity, keyed by entity name (present
+   * with entities; MODEL-FORMAT §10.1). */
+  readonly relations?: Readonly<Record<string, RelationTable>>;
   saveChanges?(): SaveReport;
 }
 
@@ -249,6 +327,13 @@ export interface Store {
    * in the engine's result shape. */
   execute?<R = unknown>(document: unknown, options?: ExecuteOptions): ValueOrPromise<SequenceResult<R>>;
   explain?(document: unknown, options?: ExecuteOptions): Promise<unknown>;
+  /** The entity roots this store-level provider serves (present with
+   * entities): it has no single root of its own, so a chain over it is
+   * refused by name — chain over `entity(name)` instead. */
+  readonly roots?: readonly string[];
+  /** The relation tables of every entity, keyed by entity name (present
+   * with entities; MODEL-FORMAT §10.1). */
+  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>>;
@@ -297,10 +382,30 @@ export interface LiveOptions {
   /** 'incremental' DEMANDS incrementality (JD0051 when the shape
    * re-runs); 'rerun' forces the re-run strategy. */
   mode?: 'auto' | 'incremental' | 'rerun';
+  /** Event time for a `$resample` / `$rolling` view (LIVE-FORMAT §13).
+   * Its members are closed: anything else is JD0053. */
+  eventTime?: LiveEventTime;
+}
+
+export interface LiveEventTime {
+  /** A singular row selector naming the instant member, e.g. '$.at'.
+   * It must be the member the spec aggregates by. */
+  path: string;
+  /** A finite epoch in milliseconds. Never a clock reading — the host
+   * supplies it, and `advance()` is the only way it moves. */
+  watermark: number;
+  /** How far behind the watermark a reading may still be applied
+   * (default 0). Older readings emit `lateData` and re-run. */
+  allowedLateness?: number;
+  /** The horizon this view claims, in milliseconds. It must cover the
+   * window (or bucket) width plus `allowedLateness`, or the view is
+   * classified as a re-run. */
+  retention: number;
 }
 
 export interface LiveMode {
-  readonly strategy: 'rows' | 'window' | 'accumulator' | 'group' | 'rerun';
+  readonly strategy: 'rows' | 'window' | 'accumulator' | 'group'
+    | 'bucket' | 'rolling' | 'rerun';
   readonly mode: 'incremental' | 'rerun';
   /** Present exactly when the strategy is 'rerun': the named reason. */
   readonly reason?: string;
@@ -312,6 +417,17 @@ export interface LiveEvent {
   seq?: number;
   /** A maintenance failure (JD2060 …): the query closed after this. */
   error?: unknown;
+  /** Present when a reading behind the lateness boundary forced this
+   * emission: the view re-read, and the row was never folded in as
+   * though it had arrived on time (LIVE-FORMAT §13). */
+  lateData?: {
+    reason: 'late-data';
+    at: number;
+    key: string;
+    watermark: number;
+    allowedLateness: number;
+    boundary: number;
+  };
 }
 
 export interface LiveStats {
@@ -320,8 +436,15 @@ export interface LiveStats {
   emissions: number;
   /** min/max extremum-removal recomputes (accumulator strategy). */
   fallbacks?: number;
-  /** whole-query re-executions (re-run strategy). */
+  /** whole-query re-executions (re-run strategy, and the re-read a
+   * late reading forces). */
   reruns?: number;
+  /** readings that arrived behind the lateness boundary (event time). */
+  lateData?: number;
+  /** buckets or window stretches folded again (event time). */
+  recomputes?: number;
+  /** the current watermark (event time). */
+  watermark?: number;
 }
 
 export interface LiveQuery {
@@ -333,6 +456,10 @@ export interface LiveQuery {
   readonly mode: LiveMode;
   stats(): LiveStats;
   subscribe(observer: (event: LiveEvent) => void): () => void;
+  /** Move the event-time watermark forward. Present only on a view
+   * registered with `eventTime`; a non-finite or backward value is a
+   * TypeError. */
+  advance?(watermark: number): void;
   close(): void;
 }
 
@@ -356,11 +483,26 @@ export interface OpenStoreOptions {
   /** The injected validation hook (D10); absent means unvalidated,
    * declared through `capabilities.validated`. */
   compileSchema?: (schema: unknown) => (doc: unknown) => unknown;
+  /** D7's injected clock — `{ toParts(epoch, zone), toEpoch(parts, zone,
+   * disambiguation) }`. A temporal spec naming a zone
+   * (`{ "every": "P1M", "zone": "Europe/Amsterdam" }`) compiles only
+   * 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;
+  /** How long work waits for an open transaction to settle before
+   * `JD0012` (MODEL-FORMAT §5.1); reaches every driver. */
+  queueTimeout?: number;
   journalMode?: string;
   statementCacheBound?: number;
   profile?: unknown;
   readOnly?: boolean;
+  /** A `createJsltRegistry()` registry (Ring 2/3): the operators a
+   * query may use, and the pushable subset. */
+  operators?: unknown;
+  /** Raw registry-free operators; never pushed. */
+  functions?: Record<string, unknown>;
+  extensions?: Record<string, unknown>;
 }
 
 export declare function openStore(model: unknown, options: OpenStoreOptions): Promise<Store>;
@@ -381,7 +523,9 @@ export interface Dialect {
 export interface Driver {
   readonly name: string;
   readonly dialect: Dialect;
-  open(options?: unknown): unknown;
+  /** Open a connection (value-or-promise) at `path` (`':memory:'` for
+   * none) with the driver's own options. */
+  open(path: string, options?: unknown): unknown;
 }
 
 export declare const sqliteDialect: Dialect;
@@ -392,6 +536,12 @@ export declare const SQLITE_FLOOR: string;
 
 export declare function normalizeEntities(model: unknown): Map<string, unknown>;
 export declare function explainMapping(model: unknown): unknown;
+/** The relation tables of normalized entities, keyed by entity name
+ * then by relation member (MODEL-FORMAT §10.1) — what every entity set
+ * exposes as `relations` and every scope carries for all its roots. */
+export declare function relationTables(
+  entities: Map<string, unknown>,
+): Readonly<Record<string, RelationTable>>;
 
 /**
  * Build the EMIT-FORMAT model document for a model's entities.
@@ -475,7 +625,9 @@ export declare const HISTORY_TABLE: string;
 // are deliberately WIDE (unknown), never wrong.
 
 export declare function planCollection(name: string, collection: unknown, dialect: Dialect): unknown;
-export declare function compileIndexPath(path: string, schema: unknown): unknown;
+export declare function compileIndexPath(expression: string, docPath: string): unknown;
+export declare function normalizeDeclaredSql(sql: string): string;
+export declare function comparableDeclaredSql(sql: string): string;
 export declare function schemaTypeAt(schema: unknown, segments: unknown): unknown;
 export declare const KEY_COLUMN: string;
 export declare const DOC_COLUMN: string;
@@ -523,7 +675,7 @@ export declare function openConnection(raw: unknown, options: unknown): unknown;
 export declare function wrapStatement(statement: unknown): unknown;
 export declare function lazyOpen(spec: unknown, reason: string, use: unknown, args?: unknown): unknown;
 export declare function classifyLiveQuery(
-  document: unknown, queryShape: unknown, keyed: boolean): unknown;
+  document: unknown, queryShape: unknown, keyed: boolean, eventTime?: unknown): unknown;
 export declare function createLiveRegistry(
   bounds: { maxQueries: number; maxMaintained: number }): unknown;
 export declare function diffRows(oldRows: readonly unknown[], newRows: readonly unknown[]):
@@ -534,6 +686,38 @@ export declare function createSortedWindow(
 export declare function compareCodepoint(a: string, b: string): number;
 export declare function collectEntityRoots(
   document: unknown, entities: ReadonlyMap<string, unknown>): Set<string>;
+/** The root expression an entity's rows are bound through (`$.<Name>[*]`) —
+ * what an entity set exposes as `root` and what `collectEntityRoots` reads. */
+export declare function entityRoot(name: string): string;
+
+// ————— the derived-index and k-nearest machinery —————
+// Constants carry their real shapes; the functions take and answer the
+// planner's own records, which have no published type — WIDE, never
+// wrong (the line at the top of this file).
+
+export declare const DERIVE_KINDS: ReadonlySet<string>;
+export declare const DERIVE_MAPPING: Readonly<Record<string, string | null>>;
+export declare const PHYSICAL_KINDS: ReadonlySet<string>;
+export declare const BBOX_COMPONENTS: readonly ['w', 's', 'e', 'n'];
+export declare const BBOX_INDEX_ORDER: readonly ['w', 'e', 's', 'n'];
+export declare const PRECISION_MIN: number;
+export declare const PRECISION_MAX: number;
+export declare const DIMS_MIN: number;
+export declare const DIMS_MAX: number;
+export declare function derivedMappingFor(kind: string, driverMapping: unknown): unknown;
+export declare function deriveGeohash(value: unknown, precision: number): unknown;
+export declare function deriveBboxEdge(value: unknown, component: 'w' | 's' | 'e' | 'n'): unknown;
+export declare function deriveVector(member: unknown, dims: number): unknown;
+export declare function storedMemberForm(member: unknown): unknown;
+export declare function derivedValue(column: unknown, member: unknown): unknown;
+export declare function memberAt(doc: unknown, segments: unknown): unknown;
+export declare function registerDeriveFunctions(connection: unknown): unknown;
+export declare function probeVector(value: unknown, dims: number): unknown;
+export declare function columnScore(bytes: unknown, dims: number, probe: unknown): unknown;
+export declare const KNN_MARGIN: number;
+export declare const IDENTITY_CHUNK: number;
+export declare function cutCandidates(rows: unknown[], m: number, margin: number): unknown;
+export declare function identityBatches(identities: unknown[]): unknown;
 
 // ————— the job queue (JOBS-FORMAT) —————
 
@@ -565,21 +749,25 @@ export interface JobCounts {
 
 export interface JobWorker {
   start(): JobWorker;
-  /** Resolves after in-flight handlers settle. */
-  stop(): Promise<void>;
+  /** 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 };
+    polls: number; wakes: number; claimErrors: number; inFlight: number };
 }
 
 export interface JobWorkerOptions {
-  handlers: Record<string,
-    (payload: unknown, context: { job: JobRecord, checkpointsFor: Function }) => unknown>;
+  handlers: Record<string, (payload: unknown, context: {
+    job: JobRecord; checkpointsFor: Function; signal: AbortSignal }) => unknown>;
+  /** A positive integer; the loops claiming concurrently. */
   concurrency?: number;
   pollInterval?: number;
   leaseMs?: number;
   owner?: string;
   backoffBase?: number;
   backoffCap?: number;
+  /** How long `stop()` waits for in-flight handlers by default. */
+  stopGraceMs?: number;
 }
 
 export interface JobsApi {
@@ -607,6 +795,7 @@ export interface JobsOptions {
   pollInterval?: number;
   backoffBase?: number;
   backoffCap?: number;
+  stopGraceMs?: number;
   /** Injectable clock and randomness — every test injects both. */
   now?: () => number;
   random?: () => number;
@@ -622,6 +811,7 @@ export declare function createDagJobRunner(store: Store, options: {
   owner?: string;
   backoffBase?: number;
   backoffCap?: number;
+  stopGraceMs?: number;
 }): JobWorker;
 
 export declare function createJobEngine(options: {
@@ -631,4 +821,8 @@ export declare const JOBS_TABLE: string;
 export declare const JOB_CHECKPOINTS_TABLE: string;
 export declare const JOB_DEFAULTS: Readonly<{
   maxAttempts: number; leaseMs: number; pollInterval: number;
-  backoffBase: number; backoffCap: number }>;
+  backoffBase: number; backoffCap: number; stopGraceMs: number }>;
+/** A total diagnostic string for any value, including ones that fight back. */
+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;

package/types/node.d.ts

@@ -2,9 +2,11 @@
 import type { Driver } from '@jarenjs/db';
 
 export interface NodeOpenOptions {
-  path?: string;
+  /** The busy timeout in milliseconds. */
   timeout?: number;
   readOnly?: boolean;
+  /** How long work waits for an open transaction (`JD0012` after). */
+  queueTimeout?: number;
 }
 
 /** The `node:sqlite` binding; the builtin loads lazily inside open(). */

package/types/typed.d.ts

@@ -15,6 +15,8 @@
 import type {
   EntityKeyArg, LoadExplanation, SaveReport, Store, StoreCapabilities,
   StoreStats, Collection, ExecuteOptions, SequenceResult, ValueOrPromise,
+  Dialect, ChangeRecord, LiveOptions, LiveQuery, JobsApi, SyncStore,
+  EntityScope, RelationEntry, RelationTable,
 } from '@jarenjs/db';
 
 /** The self-referential constraint an interface can satisfy: generated
@@ -36,9 +38,14 @@ export type TypedInclude<E extends MetaMap<E>, M extends EntityMeta> = {
   readonly [K in keyof M['relations']]?:
     true
     | { count: true }
-    | TypedLoadSpec<E, E[M['relations'][K]['entity'] & keyof E]>;
+    | TypedIncludeSpec<E, E[M['relations'][K]['entity'] & keyof E]>;
 };
 
+/** An include's clauses: the root's without `after` (a keyset cursor
+ * paginates the root alone; an include windows with `skip`/`take`). */
+export type TypedIncludeSpec<E extends MetaMap<E>, M extends EntityMeta> =
+  TypedLoadSpecBase & { include?: TypedInclude<E, M> };
+
 export interface TypedLoadSpecBase {
   /** A query expression over `$it` — its format is the runtime's. */
   where?: unknown;
@@ -68,15 +75,31 @@ export type Loaded<
         : Loaded<E, E[M['relations'][K]['entity'] & keyof E], I[K]> | null;
 } : NonNullable<unknown>);
 
+/** The relation members `link`/`unlink` take: the many-to-many ones —
+ * exactly the relation members the generated INPUT type also carries,
+ * since a membership array is writable where a projection is not. */
+export type MembershipMember<M extends EntityMeta> =
+  keyof M['relations'] & keyof M['input'] & string;
+
+/** What a membership names on the target side: the target's key, or a
+ * document carrying it. */
+export type MembershipTarget<E extends MetaMap<E>, M extends EntityMeta, K extends keyof M['relations']> =
+  E[M['relations'][K]['entity'] & keyof E]['key'] | M['relations'][K]['doc'];
+
 export interface TypedUntrackedReads<E extends MetaMap<E>, M extends EntityMeta> {
   get(key: EntityKeyArg): Promise<M['doc'] | undefined>;
   load<const S extends TypedLoadSpec<E, M>>(spec?: S): Promise<Array<Loaded<E, M, S>>>;
 }
 
 export interface TypedEntitySet<E extends MetaMap<E>, M extends EntityMeta> {
+  /** The provider phantom: `from(typed.entity('User'))` infers `User`
+   * without a cast. */
+  readonly __item?: M['doc'];
   create(doc: M['input']): Promise<Readonly<M['doc']>>;
   get(key: EntityKeyArg): Promise<Readonly<M['doc']> | undefined>;
-  update(key: EntityKeyArg, changes: Partial<M['doc']>): Promise<Readonly<M['doc']>>;
+  /** A relation member is a projection, never stored state: `update()`
+   * refuses it (`JD2003`), and the type does not offer it. */
+  update(key: EntityKeyArg, changes: Partial<Omit<M['doc'], keyof M['relations']>>): Promise<Readonly<M['doc']>>;
   delete(key: EntityKeyArg): Promise<boolean>;
   load<const S extends TypedLoadSpec<E, M>>(spec?: S):
     Promise<Array<Readonly<Loaded<E, M, S>>>>;
@@ -85,18 +108,51 @@ export interface TypedEntitySet<E extends MetaMap<E>, M extends EntityMeta> {
   put(next: M['doc']): Readonly<M['doc']>;
   remove(key: EntityKeyArg | M['doc']): void;
   discard(key: EntityKeyArg | M['doc']): void;
+  /** Attach / detach one many-to-many membership through the unit of
+   * work (MODEL-FORMAT §11.7): `member` is one of the relation members
+   * `create`/`add` also take as an array — never a projection — and
+   * `target` the target's key or a document carrying it. */
+  link<K extends MembershipMember<M>>(own: M['key'] | M['doc'], member: K, target: MembershipTarget<E, M, K>): void;
+  unlink<K extends MembershipMember<M>>(own: M['key'] | M['doc'], member: K, target: MembershipTarget<E, M, K>): void;
   asNoTracking(): TypedUntrackedReads<E, M>;
+  /** The provider contract over this entity's root (MODEL-FORMAT §10.1);
+   * the answer is the engine's result shape, value-or-promise (D2). */
+  execute<R = unknown>(document: unknown, options?: ExecuteOptions): ValueOrPromise<SequenceResult<R>>;
+  explain(document: unknown, options?: ExecuteOptions): Promise<unknown>;
+  /** The root expression this set's rows are bound through (`$.<Name>[*]`). */
+  readonly root: string;
+  /** The identity every entity set of one store shares; it carries every
+   * root's relation table. */
+  readonly scope: EntityScope;
+  /** This entity's relation table (MODEL-FORMAT §10.1): exactly the
+   * generated metadata's relation members, as the plain rows a query
+   * producer lowers a hop from. */
+  readonly relations: Readonly<Record<keyof M['relations'] & string, RelationEntry>>;
 }
 
+/** The typed store: every member of `Store` (a typed store is the same
+ * object, identity at runtime), with the entity sets typed. */
 export interface TypedStore<E extends MetaMap<E>> {
   readonly capabilities: StoreCapabilities;
+  readonly dialect: Dialect;
   stats(): StoreStats;
   collection<T = unknown>(name: string): Collection<T>;
   entity<K extends keyof E & string>(name: K): TypedEntitySet<E, E[K]>;
   execute?<R = unknown>(document: unknown, options?: ExecuteOptions): ValueOrPromise<SequenceResult<R>>;
+  explain?(document: unknown, options?: ExecuteOptions): Promise<unknown>;
+  /** The entity roots this store-level provider serves (present with entities). */
+  readonly roots?: readonly (keyof E & string)[];
+  /** The relation tables of every entity, keyed by entity name. */
+  readonly relations?: Readonly<Record<keyof E & string, RelationTable>>;
   saveChanges?(): Promise<SaveReport>;
   transaction<R>(fn: (store: Store) => R | Promise<R>): Promise<Awaited<R>>;
+  observe(fn: (record: ChangeRecord) => void): () => void;
+  changesSince?(after: number): Promise<ChangeRecord[]>;
+  dataVersion(): Promise<number>;
+  live?(document: unknown, options?: LiveOptions): Promise<LiveQuery>;
   close(options?: { graceMs?: number }): Promise<void>;
+  readonly jobs?: JobsApi;
+  readonly sync?: SyncStore;
 }
 
 /**

package/types/wasm.d.ts

@@ -3,3 +3,10 @@ import type { Driver } from '@jarenjs/db';
 
 /** A driver over an injected wasm SQLite handle (possibly async). */
 export declare function wasmDriver(handle: unknown): Driver;
+/** Adapt an `sqlite3.oo1.DB`-shaped database (a loaded sqlite3 module
+ * and one of its database objects) to the raw connection contract. */
+export declare function adaptOo1Database(sqlite3: unknown, db: unknown): unknown;
+/** Build the injected HANDLE for `wasmDriver` from a loaded sqlite3
+ * module: `DbClass` picks the database class (default `sqlite3.oo1.DB`;
+ * the SAH-pool util's `OpfsSAHPoolDb` for OPFS persistence). */
+export declare function sqlite3Handle(sqlite3: unknown, options?: { DbClass?: unknown }): unknown;