@minnowdb/core 0.9.0 → 0.10.0

package/dist/engine/errors.d.ts

@@ -9,14 +9,35 @@ export declare class TransactionExpiredError extends Error {
     constructor();
 }
 /** The worker stopped responding within the configured request deadline. */
-export declare class DatabaseWorkerTimeoutError extends Error {
+export declare class DatabaseWorkerTimeoutError extends ConnectionLostError {
     readonly method: string;
     readonly timeoutMs: number;
     readonly name = "DatabaseWorkerTimeoutError";
     constructor(method: string, timeoutMs: number);
 }
+/**
+ * The worker's channel failed underneath every pending call: the worker raised a script error it
+ * did not handle, or sent a frame that could not be read. `reason` says which; `cause` carries
+ * the worker's own error when the browser handed it over.
+ */
+export declare class DatabaseWorkerFailedError extends ConnectionLostError {
+    readonly reason: "error" | "messageerror" | "reopened";
+    readonly name = "DatabaseWorkerFailedError";
+    constructor(reason: "error" | "messageerror" | "reopened", message: string, options?: ErrorOptions);
+}
+/**
+ * The store an `auto` descriptor remembered for this database cannot be opened here — OPFS in a
+ * context without synchronous access handles, typically — and the database is not reopened,
+ * empty, on the other store.
+ */
+export declare class DatabaseStoreUnavailableError extends Error {
+    readonly store: "opfs" | "indexeddb";
+    readonly databaseName: string;
+    readonly name = "DatabaseStoreUnavailableError";
+    constructor(store: "opfs" | "indexeddb", databaseName: string, message: string);
+}
 /** A transport failure cannot prove whether this operation published before its reply was lost. */
-export declare class DatabaseWorkerOutcomeUnknownError extends Error {
+export declare class DatabaseWorkerOutcomeUnknownError extends UnknownOutcomeError {
     readonly method: string;
     readonly requestId: string;
     readonly name = "DatabaseWorkerOutcomeUnknownError";
@@ -108,4 +129,42 @@ export declare class SqlCompileError extends TypeError {
     readonly name = "SqlCompileError";
     constructor(message: string, offset: number, length: number);
 }
+import { ConnectionLostError, UnknownOutcomeError } from "../storage/types.js";
+/**
+ * What an error means for the caller, in the three terms that decide what to do next. Every
+ * error Minnow throws maps to exactly one kind; an unrecognized error is `"other"` with the
+ * cautious answers.
+ */
+export type ErrorKind = 
+/** The operation may have happened. Reconcile a stable id or revision before retrying. */
+"unknown-outcome"
+/** This connection is finished; open a new one. Pending mutations were reported separately. */
+ | "connection-lost"
+/** Lost a race with another writer or a schema change; nothing happened. Retry as is. */
+ | "conflict"
+/** The request itself is wrong (a duplicate key, a bad table, a compile error). Fix it. */
+ | "rejected"
+/** A momentary condition: backpressure, coordination, an expired scope. Retry with backoff. */
+ | "transient"
+/** A limit was reached: quota, memory, a resource ceiling. Free something, then retry. */
+ | "resource"
+/** The stored data is unreadable by this build. Do not retry, and do not delete. */
+ | "corruption"
+/** The caller cancelled it; nothing happened. */
+ | "cancelled" | "other";
+export interface ErrorClassification {
+    kind: ErrorKind;
+    /** True when the operation may have published despite the error. Never replay when true. */
+    mayHavePublished: boolean;
+    /** Whether repeating the same call is sound: as is, only after reconciling, or not at all. */
+    retry: "safe" | "after-reconcile" | "never";
+    /** False when every later call on the same connection will fail the same way. */
+    connectionUsable: boolean;
+}
+/**
+ * Classifies any error into what it means for the caller: may the operation have published, is
+ * a retry sound, and is the connection still usable. Works on errors rehydrated from the worker
+ * or a follower hop, and on the platform's own `QuotaExceededError` and `AbortError`.
+ */
+export declare function classifyError(error: unknown): ErrorClassification;
 export {};

package/dist/engine/errors.js

@@ -4,7 +4,7 @@ class TransactionExpiredError extends Error {
     super("The SQL transaction expired and rolled back; issue ROLLBACK or BEGIN before continuing");
   }
 }
-class DatabaseWorkerTimeoutError extends Error {
+class DatabaseWorkerTimeoutError extends ConnectionLostError {
   method;
   timeoutMs;
   name = "DatabaseWorkerTimeoutError";
@@ -14,7 +14,25 @@ class DatabaseWorkerTimeoutError extends Error {
     this.timeoutMs = timeoutMs;
   }
 }
-class DatabaseWorkerOutcomeUnknownError extends Error {
+class DatabaseWorkerFailedError extends ConnectionLostError {
+  reason;
+  name = "DatabaseWorkerFailedError";
+  constructor(reason, message, options) {
+    super(message, options);
+    this.reason = reason;
+  }
+}
+class DatabaseStoreUnavailableError extends Error {
+  store;
+  databaseName;
+  name = "DatabaseStoreUnavailableError";
+  constructor(store, databaseName, message) {
+    super(message);
+    this.store = store;
+    this.databaseName = databaseName;
+  }
+}
+class DatabaseWorkerOutcomeUnknownError extends UnknownOutcomeError {
   method;
   requestId;
   name = "DatabaseWorkerOutcomeUnknownError";
@@ -138,11 +156,105 @@ class SqlCompileError extends TypeError {
   }
 }
 import { dateIsoString } from "../date-value.js";
+import { BlockReadBatchTooLargeError, CompactionBacklogError, CompactionJobConflictError, ConnectionLostError, GarbageCollectionJobConflictError, IndexedDbSchemaUpgradeBlockedError, LeaseConflictError, LeaseExpiredError, LeaseOwnerConflictError, OpfsCoordinationError, OpfsDatabaseInUseError, PostingBuildConflictError, SchemaConflictError, SnapshotImportConflictError, SnapshotManifestMissingError, StorageCorruptionError, StorageFormatVersionError, StorageResourceLimitError, TableInUseError, TableRecordConflictError, TempOwnerConflictError, TransactionRecordConflictError, UniqueIndexCoverageError, UniqueKeyBuildConflictError, UniqueKeyConflictError, UnknownOutcomeError, WriteConflictError } from "../storage/types.js";
+const CONFLICT_ERRORS = [
+  WriteConflictError,
+  SchemaConflictError,
+  TableRecordConflictError,
+  TransactionRecordConflictError,
+  LeaseConflictError,
+  LeaseOwnerConflictError,
+  CompactionJobConflictError,
+  GarbageCollectionJobConflictError,
+  TempOwnerConflictError,
+  UniqueKeyBuildConflictError,
+  PostingBuildConflictError,
+  SnapshotImportConflictError,
+  SnapshotManifestMissingError,
+  TableInUseError,
+  OpfsDatabaseInUseError
+];
+const TRANSIENT_ERRORS = [
+  OpfsCoordinationError,
+  DatabaseReadBacklogError,
+  MaintenanceBacklogError,
+  CompactionBacklogError,
+  LiveQueryLimitError,
+  LeaseExpiredError,
+  TransactionExpiredError,
+  IndexedDbSchemaUpgradeBlockedError,
+  VisibleSegmentCursorStaleError
+];
+const RESOURCE_ERRORS = [
+  StorageResourceLimitError,
+  BlockReadBatchTooLargeError,
+  CompactionMemoryBudgetError,
+  CompactionWriteAmplificationError
+];
+const REJECTED_ERRORS = [
+  UniqueConstraintError,
+  UniqueKeyConflictError,
+  UniqueIndexCoverageError,
+  MissingKeyError,
+  UnknownTableError,
+  SqlCompileError,
+  CompactionJobCancelledError
+];
+function isAnyOf(error, classes) {
+  return classes.some((constructor) => error instanceof constructor);
+}
+function hasErrorName(error, name) {
+  return typeof error === "object" && error !== null && error.name === name;
+}
+function classifyError(error) {
+  if (error instanceof UnknownOutcomeError) {
+    return {
+      kind: "unknown-outcome",
+      mayHavePublished: true,
+      retry: "after-reconcile",
+      connectionUsable: !(error.cause instanceof ConnectionLostError)
+    };
+  }
+  if (error instanceof ConnectionLostError) {
+    return {
+      kind: "connection-lost",
+      mayHavePublished: false,
+      retry: "never",
+      connectionUsable: false
+    };
+  }
+  if (error instanceof StorageCorruptionError || error instanceof StorageFormatVersionError) {
+    return { kind: "corruption", mayHavePublished: false, retry: "never", connectionUsable: true };
+  }
+  if (isAnyOf(error, CONFLICT_ERRORS)) {
+    return { kind: "conflict", mayHavePublished: false, retry: "safe", connectionUsable: true };
+  }
+  if (isAnyOf(error, TRANSIENT_ERRORS)) {
+    return { kind: "transient", mayHavePublished: false, retry: "safe", connectionUsable: true };
+  }
+  if (isAnyOf(error, RESOURCE_ERRORS) || hasErrorName(error, "QuotaExceededError")) {
+    return {
+      kind: "resource",
+      mayHavePublished: false,
+      retry: "after-reconcile",
+      connectionUsable: true
+    };
+  }
+  if (isAnyOf(error, REJECTED_ERRORS) || error instanceof TypeError || error instanceof RangeError || error instanceof SyntaxError) {
+    return { kind: "rejected", mayHavePublished: false, retry: "never", connectionUsable: true };
+  }
+  if (hasErrorName(error, "AbortError")) {
+    return { kind: "cancelled", mayHavePublished: false, retry: "safe", connectionUsable: true };
+  }
+  return { kind: "other", mayHavePublished: false, retry: "never", connectionUsable: true };
+}
 export {
   CompactionJobCancelledError,
   CompactionMemoryBudgetError,
   CompactionWriteAmplificationError,
   DatabaseReadBacklogError,
+  DatabaseStoreUnavailableError,
+  DatabaseWorkerFailedError,
   DatabaseWorkerOutcomeUnknownError,
   DatabaseWorkerTimeoutError,
   LiveQueryLimitError,
@@ -152,5 +264,6 @@ export {
   TransactionExpiredError,
   UniqueConstraintError,
   UnknownTableError,
-  VisibleSegmentCursorStaleError
+  VisibleSegmentCursorStaleError,
+  classifyError
 };

package/dist/engine/index.d.ts

@@ -5,6 +5,7 @@
 export * from "./catalog.js";
 export * from "./database.js";
 export * from "./errors.js";
+export { forgetStoreChoice } from "./auto-store.js";
 export { QueryMemoryBudgetError, type QueryMemoryUsage } from "./memory.js";
 export { MAX_SQL_NESTING_DEPTH, MAX_SQL_NUMERIC_DIGITS, MAX_SQL_PARAMETERS, MAX_SQL_PATTERN_CHARACTERS, MAX_SQL_PATTERN_MATCH_STEPS, MAX_SQL_SCALAR_RESULT_CHARACTERS, MAX_SQL_STRUCTURED_VALUE_DEPTH, MAX_SQL_STRUCTURED_VALUE_ITEMS, MAX_SQL_TEXT_CHARACTERS, MAX_SQL_TOKENS, } from "./cache-limits.js";
 /**

package/dist/engine/index.js

@@ -1,6 +1,7 @@
 export * from "./catalog.js";
 export * from "./database.js";
 export * from "./errors.js";
+import { forgetStoreChoice } from "./auto-store.js";
 import { QueryMemoryBudgetError } from "./memory.js";
 import { MAX_SQL_NESTING_DEPTH, MAX_SQL_NUMERIC_DIGITS, MAX_SQL_PARAMETERS, MAX_SQL_PATTERN_CHARACTERS, MAX_SQL_PATTERN_MATCH_STEPS, MAX_SQL_SCALAR_RESULT_CHARACTERS, MAX_SQL_STRUCTURED_VALUE_DEPTH, MAX_SQL_STRUCTURED_VALUE_ITEMS, MAX_SQL_TEXT_CHARACTERS, MAX_SQL_TOKENS } from "./cache-limits.js";
 import { column, foreignKeyName, isDestructiveStep, planMigration, schema, table, view } from "./schema.js";
@@ -22,6 +23,7 @@ export {
   QueryMemoryBudgetError,
   column,
   foreignKeyName,
+  forgetStoreChoice,
   isDestructiveStep,
   planMigration,
   schema,

package/dist/engine/live.d.ts

@@ -125,6 +125,25 @@ export interface LiveQueryStats {
     /** Work avoided because equal statements shared one query group or in-flight execution. */
     sharedExecutions: number;
     lastSweepMs: number;
+    /** One entry per distinct statement, with why it re-executes when it does. */
+    groups: readonly LiveQueryGroupStats[];
+}
+/** What one distinct live statement costs, and why. */
+export interface LiveQueryGroupStats {
+    /** The statement's SQL; undefined for a compiled-plan envelope. */
+    readonly sql: string | undefined;
+    readonly subscribers: number;
+    /** Whether the engine maintains this statement incrementally; false before its first run too. */
+    readonly maintainable: boolean;
+    /** Why it re-executes on every relevant commit; empty when it is maintained. */
+    readonly reasons: readonly string[];
+    /** Full executions after the first. */
+    readonly reruns: number;
+    /** Deliveries answered by patching the retained result. */
+    readonly maintained: number;
+    /** Full executions of a maintainable statement that a particular commit could not be patched for. */
+    readonly fallbacks: number;
+    readonly retainedRows: number;
 }
 /** A live query: plain SQL, parameterized SQL, or a compiled-plan envelope. */
 export type LiveQueryInput = string | {
@@ -157,6 +176,10 @@ export interface LiveMaintainedExecution {
     /** Modeled total bytes retained by the result and opaque maintenance state. */
     readonly retainedBytes?: number;
 }
+/** The host will not maintain this statement, and says why, in the terms a developer fixes. */
+export interface LiveMaintenanceDeclined {
+    readonly declined: readonly string[];
+}
 export interface LiveMaintainedChange extends LiveMaintainedExecution {
     readonly changed: boolean;
     /** For each row of `result`, its index in the previous result, or -1; see `LiveQueryDelivery`. */
@@ -175,7 +198,7 @@ export interface LiveQueryHost {
      * Executes a statement the host can later maintain incrementally, or returns undefined when
      * the statement's shape rules that out; the set then executes it in full from then on.
      */
-    executeMaintainable?(query: LiveQueryInput, context?: LiveQueryExecuteContext): Promise<LiveMaintainedExecution | undefined>;
+    executeMaintainable?(query: LiveQueryInput, context?: LiveQueryExecuteContext): Promise<LiveMaintainedExecution | LiveMaintenanceDeclined | undefined>;
     /**
      * Patches a retained result with the row changes the commits in (after, until] made to
      * `tableIds`, or returns undefined when only a full execution can answer.

package/dist/engine/live.js

@@ -111,7 +111,8 @@ class LiveQuerySet {
     retainedRows: 0,
     retainedBytes: 0,
     sharedExecutions: 0,
-    lastSweepMs: 0
+    lastSweepMs: 0,
+    groups: []
   };
   #lastProbe;
   #pendingProbe;
@@ -159,9 +160,22 @@ class LiveQuerySet {
   }
   get stats() {
     let retainedRows = 0;
-    for (const group of this.#groups.values())
-      retainedRows += group.result?.rows.length ?? 0;
-    return { ...this.#stats, retainedRows, retainedBytes: this.#retainedBytes };
+    const groups = [];
+    for (const group of this.#groups.values()) {
+      const rows = group.result?.rows.length ?? 0;
+      retainedRows += rows;
+      groups.push({
+        sql: typeof group.query === "string" ? group.query : group.query.kind === "sql-query" ? group.query.sql : void 0,
+        subscribers: group.subscribers.size,
+        maintainable: group.maintenance !== void 0,
+        reasons: group.reasons,
+        reruns: group.reruns,
+        maintained: group.maintained,
+        fallbacks: group.fallbacks,
+        retainedRows: rows
+      });
+    }
+    return { ...this.#stats, retainedRows, retainedBytes: this.#retainedBytes, groups };
   }
   #freshProbe() {
     let pending = this.#pendingProbe;
@@ -334,7 +348,11 @@ class LiveQuerySet {
       execution: void 0,
       deliveries: 0,
       maintenance: void 0,
-      unmaintainable: false
+      unmaintainable: false,
+      reasons: [],
+      reruns: 0,
+      maintained: 0,
+      fallbacks: 0
     };
     this.#groups.set(key, group);
     this.#indexGroup(group, dependencies);
@@ -399,9 +417,10 @@ class LiveQuerySet {
       try {
         if (this.#incremental && this.#host.executeMaintainable !== void 0 && !group.unmaintainable) {
           const maintained = await this.#host.executeMaintainable(group.query, context);
-          if (maintained === void 0)
+          if (maintained === void 0 || "declined" in maintained) {
             group.unmaintainable = true;
-          else {
+            group.reasons = maintained?.declined ?? ["the host declined to maintain it"];
+          } else {
             candidate = maintained;
             executed = maintained.result;
             maintenance = maintained.state;
@@ -665,6 +684,7 @@ class LiveQuerySet {
     if (catalogChanged) {
       group.maintenance = void 0;
       group.unmaintainable = false;
+      group.reasons = [];
       try {
         await this.#refreshDependencies(group);
       } catch (error) {
@@ -719,10 +739,14 @@ class LiveQuerySet {
           if (!this.#stillOpen() || this.#groups.get(group.key) !== group)
             return;
         }
-        if (execution !== void 0)
+        if (execution !== void 0) {
           this.#stats.maintained += 1;
-        else {
+          group.maintained += 1;
+        } else {
           this.#stats.reruns += 1;
+          group.reruns += 1;
+          if (group.maintenance !== void 0)
+            group.fallbacks += 1;
           execution = await this.#executeGroup(group, {
             probe: current,
             memoize: groupMemoizes(group)

package/dist/engine/scope-write-set.js

@@ -0,0 +1,36 @@
+const DEFAULT_SCOPE_WRITE_SET_BUDGET_BYTES = 64 * 1024 * 1024;
+const scopeWriteSetTestHooks = {
+  defaultBudgetBytes: DEFAULT_SCOPE_WRITE_SET_BUDGET_BYTES,
+  budgetBytes: DEFAULT_SCOPE_WRITE_SET_BUDGET_BYTES
+};
+function composeScopeEffect(base, next) {
+  switch (next.kind) {
+    case "delete":
+      return next;
+    case "insert":
+      return base?.kind === "delete" ? { kind: "upsert", values: next.values } : next;
+    case "upsert":
+      return base?.kind === "insert" ? { kind: "insert", values: next.values } : next;
+    case "update": {
+      if (base === void 0)
+        return next;
+      if (base.kind === "delete")
+        throw new Error("A deleted key cannot take an update");
+      const values = base.values.slice();
+      next.values.forEach((value, position) => {
+        if (value !== void 0)
+          values[position] = value;
+      });
+      return { kind: base.kind, values };
+    }
+  }
+}
+function netScopeEffect(entry) {
+  return entry.pending === void 0 ? entry.staged : composeScopeEffect(entry.staged, entry.pending);
+}
+export {
+  DEFAULT_SCOPE_WRITE_SET_BUDGET_BYTES,
+  composeScopeEffect,
+  netScopeEffect,
+  scopeWriteSetTestHooks
+};

package/dist/engine/worker-auto.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/engine/worker-auto.js

@@ -0,0 +1,3 @@
+import { attachWorkerHost } from "./worker-server.js";
+import { autoWorkerStore } from "./worker-store-auto.js";
+attachWorkerHost(self, autoWorkerStore);

package/dist/engine/worker-host.d.ts

@@ -1,5 +1,6 @@
 import { type RpcScope, type WorkerStoreFactory, type WorkerStoreOptions } from "./worker-server.js";
-export { exposeDatabase, singleStoreFactory, MAX_WORKER_HANDLES_PER_CONNECTION, type DatabaseInitPayload, type ExposeDatabaseOptions, type RpcScope, type StoreDescriptor, type WireDatabaseOptions, type WorkerStoreFactory, type WorkerStoreOptions, } from "./worker-server.js";
+export { forgetStoreChoice, openAutoStore, resolveAutoStoreKind, type AutoStoreKind, } from "./auto-store.js";
+export { exposeDatabase, singleStoreFactory, MAX_WORKER_HANDLES_PER_CONNECTION, type DatabaseInitPayload, type ExposeDatabaseOptions, type OpenedStore, type OpenedStoreKind, type RpcScope, type StoreDescriptor, type WireDatabaseOptions, type WorkerStoreFactory, type WorkerStoreOptions, } from "./worker-server.js";
 export interface AttachDatabaseWorkerOptions extends WorkerStoreOptions {
     /**
      * Replaces the stock store factory. `singleStoreFactory()` builds one that opens a single

package/dist/engine/worker-host.js

@@ -1,9 +1,21 @@
 import { attachWorkerHost } from "./worker-server.js";
+import { forgetStoreChoice, openAutoStore, resolveAutoStoreKind } from "./auto-store.js";
 import { exposeDatabase, singleStoreFactory, MAX_WORKER_HANDLES_PER_CONNECTION } from "./worker-server.js";
 function attachDatabaseWorker(scope, options = {}) {
   attachWorkerHost(scope, options.createStore ?? createStore, options);
 }
 async function createStore(descriptor, options) {
+  if (descriptor.kind === "auto") {
+    const { openAutoStore: openAutoStore2 } = await import("./auto-store.js");
+    return openAutoStore2(descriptor.name, async (kind) => {
+      const opened = await createStore(kind === "opfs" ? {
+        kind,
+        name: descriptor.name,
+        ...descriptor.opfs?.durability === void 0 ? {} : { durability: descriptor.opfs.durability }
+      } : { kind, name: descriptor.name, ...descriptor.indexeddb }, options);
+      return opened;
+    });
+  }
   if (descriptor.kind === "memory") {
     const { MemoryBlockStore } = await import("../storage/memory.js");
     return new MemoryBlockStore();
@@ -12,7 +24,8 @@ async function createStore(descriptor, options) {
     const { OpfsBlockStore } = await import("../storage/opfs/index.js");
     return OpfsBlockStore.open({
       name: descriptor.name,
-      ...descriptor.durability === void 0 ? {} : { durability: descriptor.durability }
+      ...descriptor.durability === void 0 ? {} : { durability: descriptor.durability },
+      ...options.onDiagnostic === void 0 ? {} : { onDiagnostic: options.onDiagnostic }
     });
   }
   const { IndexedDbBlockStore } = await import("../storage/indexeddb.js");
@@ -27,5 +40,8 @@ export {
   MAX_WORKER_HANDLES_PER_CONNECTION,
   attachDatabaseWorker,
   exposeDatabase,
+  forgetStoreChoice,
+  openAutoStore,
+  resolveAutoStoreKind,
   singleStoreFactory
 };

package/dist/engine/worker-server.d.ts

@@ -1,4 +1,5 @@
 import type { BlockStore } from "../storage/types.js";
+import { type WorkerErrorKind } from "../worker-protocol/index.js";
 import { MinnowDatabase, type MinnowDatabaseOptions } from "./database.js";
 /**
  * Worker-side host for the main-thread client. exposeDatabase() answers the client's RPC frames
@@ -24,12 +25,40 @@ export type StoreDescriptor = {
     kind: "opfs";
     name: string;
     durability?: "relaxed" | "strict";
+}
+/**
+ * OPFS where the worker can hold synchronous access handles, IndexedDB elsewhere. The choice
+ * is made once per name and remembered, so the database never reopens empty on the other
+ * store; `client.storeKind()` reports which one opened.
+ */
+ | {
+    kind: "auto";
+    name: string;
+    opfs?: {
+        durability?: "relaxed" | "strict";
+    };
+    indexeddb?: {
+        durability?: IDBTransactionDurability;
+        uniqueKeyCacheBytes?: number;
+    };
 };
+/** The store kinds a worker can actually open; `auto` resolves to one of the durable two. */
+export type OpenedStoreKind = "indexeddb" | "opfs" | "memory";
+/** What a store factory may return when the descriptor did not name the kind it opened. */
+export interface OpenedStore {
+    store: BlockStore;
+    kind: OpenedStoreKind;
+}
 /** The cloneable subset of MinnowDatabaseOptions; function-valued seams stay worker-side. */
 export type WireDatabaseOptions = Pick<MinnowDatabaseOptions, "compression" | "targetBlockBytes" | "rowsPerBlock" | "maxCommitRetries" | "coordinateWrites" | "spillOwnerLeaseMs" | "transactionOwnerLeaseMs" | "transactionIdleTimeoutMs" | "bufferPoolBytes" | "executionMemoryBudgetBytes" | "autoCollectDebtLimitCommits" | "autoCollect" | "autoCompact">;
 export interface DatabaseInitPayload {
     store: StoreDescriptor;
     options?: WireDatabaseOptions;
+    /**
+     * How often the worker reports on a call it is still working on; the client derives it
+     * from its own deadline so a short deadline still hears from a long call in time.
+     */
+    keepaliveIntervalMs?: number;
 }
 /** The slice of DedicatedWorkerGlobalScope (or MessagePort) the host needs. */
 export interface RpcScope {
@@ -42,6 +71,17 @@ export interface RpcScope {
         transfer: ArrayBuffer[];
     }): void;
 }
+/** Reports a worker failure that belongs to no request to the main thread. */
+export type WorkerErrorReporter = (kind: WorkerErrorKind, error: unknown, context: string) => void;
+/**
+ * The one place every failure that is nobody's call answer goes. It posts a diagnostic event
+ * frame the client turns into `onWorkerError` (or a `console.error` on the main thread), and on
+ * a real worker global it also catches what would otherwise be an uncaught exception, an
+ * unhandled rejection, or an unreadable inbound frame. Those three are marked handled so the
+ * browser does not log them a second time under the worker's own name; the main thread's copy
+ * carries the same message, stack, and cause.
+ */
+export declare function workerErrorReporter(scope: RpcScope): WorkerErrorReporter;
 export interface ExposeDatabaseOptions {
     /** Called when the client sends its dispose frame, after every handle has been closed. */
     onDispose?: () => void | Promise<void>;
@@ -56,18 +96,28 @@ export interface ExposeDatabaseOptions {
      * on the tab the user is looking at.
      */
     onVisibility?: (visible: boolean) => void;
+    /** The kind of store behind the database, reported to the client when it connects. */
+    storeKind?: OpenedStoreKind;
+    /** Milliseconds between keepalive reports on a call in progress; defaults to five seconds. */
+    keepaliveIntervalMs?: number;
 }
 /** What a worker store factory may need beyond the descriptor itself. */
 export interface WorkerStoreOptions {
     /** Test seam for environments without a global IndexedDB (e.g. fake-indexeddb). */
     indexedDB?: IDBFactory;
+    /**
+     * Hears a store's background failures — a failed checkpoint, a broken election — so they reach
+     * the main thread. The stock host wires it to the worker error reporter; a factory passes it
+     * to a store that accepts one (`OpfsBlockStoreOptions.onDiagnostic`).
+     */
+    onDiagnostic?: (error: unknown, context: string) => void;
 }
 /**
  * Builds the block store named by a client's init frame. The stock entry's factory loads the
  * adapter for any of the three kinds on demand; a per-store entry supplies one that imports a
  * single adapter statically and refuses the rest.
  */
-export type WorkerStoreFactory = (descriptor: StoreDescriptor, options: WorkerStoreOptions) => BlockStore | Promise<BlockStore>;
+export type WorkerStoreFactory = (descriptor: StoreDescriptor, options: WorkerStoreOptions) => BlockStore | OpenedStore | Promise<BlockStore | OpenedStore>;
 /** Hard per-connection ceiling for resident worker resources abandoned by a client. */
 export declare const MAX_WORKER_HANDLES_PER_CONNECTION = 256;
 /**
@@ -91,3 +141,5 @@ export declare function attachWorkerHost(scope: RpcScope, createStore: WorkerSto
 export declare function singleStoreFactory<Kind extends StoreDescriptor["kind"]>(kind: Kind, open: (descriptor: Extract<StoreDescriptor, {
     kind: Kind;
 }>, options: WorkerStoreOptions) => BlockStore | Promise<BlockStore>): WorkerStoreFactory;
+/** The refusal a worker entry gives an init frame for a store it does not bundle. */
+export declare function unsupportedStoreKindError(bundled: StoreDescriptor["kind"], requested: string): Error;