@delali/sirannon-db 0.3.4-next.62 → 0.3.4

package/dist/core/index.mjs

@@ -1,29 +1,29 @@
-import { Transaction, LWWResolver, REMOTE_ORIGIN_NODE_ID, BatchReader, BatchApplier, recordLocalColumnVersions, HLC, loadPersistedHlc, isWellFormedHlc, HLC_CLOCK_META_KEY } from '../chunk-KXTYR2OQ.mjs';
-export { Transaction } from '../chunk-KXTYR2OQ.mjs';
-import { executeBatch, executeBatchSummary, execute, bindParams, executeGroup, query, queryForWire, queryOne } from '../chunk-MYNI2WFS.mjs';
-export { execute, executeBatch, query, queryOne } from '../chunk-MYNI2WFS.mjs';
-import { tokenizeSql, unsupported, findClauses, readSource, readSortTerms, readWindow, readSelectItems, parameterName } from '../chunk-SBL6GN43.mjs';
-import { reconcileMigrationChecksums, migrationContentChecksum, ensureCdcEpoch, SubscriptionBuilderImpl, ChangeTracker, SubscriptionManager, startPolling, runBulkLoad, TransactionGrouper, PrimedSubscription } from '../chunk-M2BEAH5I.mjs';
-export { ChangeTracker, isBulkLoadDurability, runBulkLoad } from '../chunk-M2BEAH5I.mjs';
-import { planBackupRestore, backupPiecesSafeToDelete } from '../chunk-YNTDOFTN.mjs';
-export { backupPiecesSafeToDelete, planBackupRestore } from '../chunk-YNTDOFTN.mjs';
-import { ensureMigrationsTable, prepareUpdateMigrationChecksum, prepareInsertMigration, selectAppliedMigrationsNewestFirst, prepareDeleteMigration, selectAppliedMigrations, tableInfoRows, selectTableSql, selectTableExists, selectMetaValue, upsertMetaValue, SEQ_STRING_RE, replaceMigrationHistory, highestMigrationVersion, selectCountOutboundChanges, ensureMetaTable, ensureChangesTable, ensureBatchApplyTables, PkResolver, selectMaxChangeSeq, selectMaxAppliedSourceSeq, insertMetaValueIfAbsent, selectMaxChangeHlc, updateUnstampedChangeStampsSql, UPSERT_META_VALUE_SQL, setForeignKeysEnabled, IDENTIFIER_RE, validateDdlSafety, ensureStagedChangesTable, upsertStagedChangeSql, selectFirstStagedTransactionEnd, deleteStagedChangesUpToSeq, selectMaxStagedSeq, deleteAllStagedChanges, deleteMetaValue, assertSafeIdentifier, selectStagedChangesInRange } from '../chunk-45MKELYA.mjs';
-import { ReplicationError } from '../chunk-2QLXDHAP.mjs';
-import { MIGRATIONS_TABLE, LIVE_PROBE_TABLE_PREFIX, META_TABLE, CHANGES_TABLE, assertSqlAllowed, INTERNAL_TABLE_PREFIX, eventTimestampToChangedAt, encodeTaggedValues, isReservedIdentifier, decodeTaggedValues, changedAtToEventTimestamp } from '../chunk-6CMCO7S4.mjs';
+import { Transaction, LWWResolver, REMOTE_ORIGIN_NODE_ID, BatchReader, BatchApplier, recordLocalColumnVersions, loadPersistedHlc, isWellFormedHlc, HLC_CLOCK_META_KEY } from '../chunk-A3PHCO6W.mjs';
+export { Transaction } from '../chunk-A3PHCO6W.mjs';
+import { runWriterTransaction, executeBatch, executeBatchSummary, execute, bindParams, executeGroup, query, queryForWire, queryOne } from '../chunk-52XW3Z76.mjs';
+export { execute, executeBatch, query, queryOne } from '../chunk-52XW3Z76.mjs';
+import { tokenizeSql, unsupported, findClauses, readSource, readSortTerms, readWindow, readSelectItems, parameterName } from '../chunk-ZYWI45EN.mjs';
+import { reconcileMigrationChecksums, migrationContentChecksum, resolveDeviceRetentionPolicy, ensureCdcEpoch, SubscriptionBuilderImpl, ChangeTracker, SubscriptionManager, startPolling, runBulkLoad, TransactionGrouper, PrimedSubscription } from '../chunk-ZN4HI5FK.mjs';
+export { ChangeTracker, isBulkLoadDurability, runBulkLoad } from '../chunk-ZN4HI5FK.mjs';
+import { planBackupRestore, backupPiecesSafeToDelete } from '../chunk-YW7IKQ7T.mjs';
+export { backupPiecesSafeToDelete, planBackupRestore } from '../chunk-YW7IKQ7T.mjs';
+import { ensureMigrationsTable, prepareUpdateMigrationChecksum, prepareInsertMigration, selectAppliedMigrationsNewestFirst, prepareDeleteMigration, selectAppliedMigrations, tableInfoRows, selectTableSql, selectTableExists, selectMetaValue, upsertMetaValue, SEQ_STRING_RE, replaceMigrationHistory, highestMigrationVersion, selectCountOutboundChanges, ensureMetaTable, ensureChangesTable, ensureBatchApplyTables, PkResolver, selectMaxChangeSeq, selectMaxAppliedSourceSeq, insertMetaValueIfAbsent, HLC, selectMaxChangeHlc, updateUnstampedChangeStampsSql, UPSERT_META_VALUE_SQL, setForeignKeysEnabled, IDENTIFIER_RE, validateDdlSafety, ensureStagedChangesTable, upsertStagedChangeSql, selectFirstStagedTransactionEnd, deleteStagedChangesUpToSeq, selectMaxStagedSeq, deleteAllStagedChanges, deleteMetaValue, assertSafeIdentifier, selectStagedChangesInRange } from '../chunk-ESTZZPT5.mjs';
+import { ReplicationError } from '../chunk-BLMRNSUG.mjs';
+import { MIGRATIONS_TABLE, LIVE_PROBE_TABLE_PREFIX, META_TABLE, CHANGES_TABLE, assertSqlAllowed, INTERNAL_TABLE_PREFIX, eventTimestampToChangedAt, encodeTaggedValues, isReservedIdentifier, decodeTaggedValues, changedAtToEventTimestamp } from '../chunk-2O3PP4CF.mjs';
 import '../chunk-GVCNMPOS.mjs';
-import { defaultStagingDir } from '../chunk-LXCGPZPA.mjs';
-export { defineDriver } from '../chunk-LXCGPZPA.mjs';
+import { defaultStagingDir } from '../chunk-IEKIYO4V.mjs';
+export { defineDriver } from '../chunk-IEKIYO4V.mjs';
 import { startCopyWithoutHoldingWriter } from '../chunk-W67A4H2E.mjs';
-import { DEFAULT_SYNCHRONOUS } from '../chunk-OUSWVNWT.mjs';
-export { DEFAULT_SYNCHRONOUS, isSynchronousLevel, synchronousPragmaValue } from '../chunk-OUSWVNWT.mjs';
-import { DEFAULT_CHAIN_NAME } from '../chunk-YVF2ZJTE.mjs';
-export { DEFAULT_CHAIN_NAME, readBackupChains } from '../chunk-YVF2ZJTE.mjs';
+import { DEFAULT_SYNCHRONOUS } from '../chunk-YCMB6GR4.mjs';
+export { DEFAULT_SYNCHRONOUS, isSynchronousLevel, synchronousPragmaValue } from '../chunk-YCMB6GR4.mjs';
+import { DEFAULT_CHAIN_NAME } from '../chunk-CZL4D3BM.mjs';
+export { DEFAULT_CHAIN_NAME, readBackupChains } from '../chunk-CZL4D3BM.mjs';
 import { invokeCallerCallback, randomHex } from '../chunk-QBBLSQHQ.mjs';
-import { LAZY_DOWN_SQL, parseMigrationFilename } from '../chunk-7C36BCSN.mjs';
-export { MIGRATION_FILENAME_PATTERN, parseMigrationFilename } from '../chunk-7C36BCSN.mjs';
-import { resolveEffectiveBaseline, planPendingMigrations, SQLITE_USER_VERSION_MAX, applyBaselineOption } from '../chunk-IWGIYDMZ.mjs';
-import { SirannonError, ConnectionPoolError, MigrationError, ReadOnlyError, MaxDatabasesError, DatabaseAlreadyExistsError, DatabaseNotFoundError, CDCError, WriteOverloadError, ExtensionError } from '../chunk-PBRXXISQ.mjs';
-export { BackupError, CDCError, ConnectionPoolError, DatabaseAlreadyExistsError, DatabaseNotFoundError, ExtensionError, ForbiddenSqlError, HookDeniedError, MaxDatabasesError, MigrationError, QueryError, ReadOnlyError, RequestDeniedError, SirannonError, TransactionError, WriteOverloadError } from '../chunk-PBRXXISQ.mjs';
+import { LAZY_DOWN_SQL, parseMigrationFilename } from '../chunk-VDN6FHU4.mjs';
+export { MIGRATION_FILENAME_PATTERN, parseMigrationFilename } from '../chunk-VDN6FHU4.mjs';
+import { resolveEffectiveBaseline, planPendingMigrations, SQLITE_USER_VERSION_MAX, applyBaselineOption } from '../chunk-BZWDPF4G.mjs';
+import { SirannonError, ConnectionPoolError, MigrationError, ReadOnlyError, MaxDatabasesError, DatabaseAlreadyExistsError, DatabaseNotFoundError, CDCError, WriteOverloadError, ExtensionError } from '../chunk-KINDFBQP.mjs';
+export { BackupError, CDCError, ConnectionPoolError, DatabaseAlreadyExistsError, DatabaseNotFoundError, ExtensionError, ForbiddenSqlError, HookDeniedError, MaxDatabasesError, MigrationError, QueryError, ReadOnlyError, RequestDeniedError, SirannonError, TransactionError, WriteOverloadError } from '../chunk-KINDFBQP.mjs';
 
 // src/core/connection-pool.ts
 async function closeAllSilently(connections) {
@@ -101,7 +101,7 @@ var ConnectionPool = class _ConnectionPool {
     }
     return this.writer;
   }
-  /** Returns the writer and every reader, for an operation that must apply to the whole pool. */
+  /** Returns the writer and every reader, so that the caller can apply an operation to every connection in the pool. */
   connections() {
     if (this.closed) {
       throw new ConnectionPoolError("Connection pool is closed");
@@ -263,9 +263,10 @@ var DatabaseBackupController = class {
     );
   }
   /**
-   * Builds the cycle and starts it in the background. Its first turn copies the
-   * whole database, and an open cannot wait on that. A failure reaches the
-   * caller through the cycle's own error callback.
+   * Builds the backup cycle and starts it without awaiting the first turn, which
+   * copies the whole database, so that the open can return first. When the start
+   * fails, this method passes the error to the `onError` callback in the cycle
+   * options.
    */
   startCycle(options) {
     const engine = this.require();
@@ -318,7 +319,7 @@ var DatabaseBackupController = class {
   async piecesSafeToDelete(options) {
     return backupPiecesSafeToDelete(await this.chains(), options);
   }
-  /** Stops the cycle, capturing the log one final time so nothing written since the previous turn is lost. */
+  /** Stops the backup cycle after one last capture, which sends the writes made since the previous turn to the destination. */
   async stopCycle() {
     if (!this.cycle) return;
     const cycle = this.cycle;
@@ -445,12 +446,14 @@ var SyncStamper = class _SyncStamper {
 
 // src/core/database-cdc.ts
 var DatabaseCdcController = class {
-  constructor(runExclusive, acquireWriter, pollInterval, retention, openSnapshotConnection) {
+  constructor(runExclusive, acquireWriter, pollInterval, retention, openSnapshotConnection, deviceRetention, onDispatched) {
     this.runExclusive = runExclusive;
     this.acquireWriter = acquireWriter;
     this.pollInterval = pollInterval;
     this.retention = retention;
     this.openSnapshotConnection = openSnapshotConnection;
+    this.deviceRetention = deviceRetention;
+    this.onDispatched = onDispatched;
   }
   tracker = null;
   subscriptionManager = null;
@@ -545,7 +548,7 @@ var DatabaseCdcController = class {
       return Transaction.run(writer, fn);
     }
     const state = { sawDdl: false, droppedTables: [] };
-    const result = await writer.transaction(async (txConn) => {
+    const result = await runWriterTransaction(writer, async (txConn) => {
       const value = await fn(new CdcAwareTransaction(txConn, tracker, state));
       await this.applyStamps(txConn);
       return value;
@@ -563,7 +566,7 @@ var DatabaseCdcController = class {
   }
   ensure() {
     const tracker = this.tracker ?? new ChangeTracker({ retention: this.retention });
-    const subscriptions = this.subscriptionManager ?? new SubscriptionManager();
+    const subscriptions = this.subscriptionManager ?? new SubscriptionManager(this.onDispatched);
     this.tracker = tracker;
     this.subscriptionManager = subscriptions;
     return { tracker, subscriptions };
@@ -577,7 +580,8 @@ var DatabaseCdcController = class {
       this.subscriptionManager,
       this.pollInterval,
       void 0,
-      this.runExclusive
+      this.runExclusive,
+      this.deviceRetention
     );
   }
 };
@@ -872,6 +876,7 @@ var DatabaseMigrationController = class {
 };
 
 // src/core/hooks/query-hooks.ts
+var STATEMENT_SUCCEEDED = { failed: false };
 function fireBeforeQueryHooks(parentHooks, localHooks, databaseId, sql, params, options) {
   const hasParent = parentHooks?.has("beforeQuery");
   const hasLocal = localHooks.has("beforeQuery");
@@ -886,19 +891,13 @@ function fireBeforeQueryHooks(parentHooks, localHooks, databaseId, sql, params,
   parentHooks?.invokeSync("beforeQuery", ctx);
   localHooks.invokeSync("beforeQuery", ctx);
 }
-function fireAfterQueryHooks(parentHooks, localHooks, databaseId, sql, params, durationMs) {
+function fireAfterQueryHooks(parentHooks, localHooks, databaseId, sql, params, durationMs, outcome) {
   const hasParent = parentHooks?.has("afterQuery");
   const hasLocal = localHooks.has("afterQuery");
   if (!hasParent && !hasLocal) return;
-  const ctx = { databaseId, sql, params, durationMs };
-  try {
-    parentHooks?.invokeSync("afterQuery", ctx);
-  } catch {
-  }
-  try {
-    localHooks.invokeSync("afterQuery", ctx);
-  } catch {
-  }
+  const ctx = outcome.failed ? { databaseId, sql, params, durationMs, error: outcome.error } : { databaseId, sql, params, durationMs };
+  parentHooks?.invokeSyncIgnoringFailures("afterQuery", ctx);
+  localHooks.invokeSyncIgnoringFailures("afterQuery", ctx);
 }
 
 // src/core/database-observability.ts
@@ -916,41 +915,50 @@ var DatabaseObserver = class {
     this.fireBefore(sql, params, options);
     const start = performance.now();
     try {
-      return await op();
-    } finally {
-      this.fireAfter(sql, params, performance.now() - start);
+      const result = await op();
+      this.fireAfter(sql, params, performance.now() - start, STATEMENT_SUCCEEDED);
+      return result;
+    } catch (error) {
+      this.fireAfter(sql, params, performance.now() - start, { failed: true, error });
+      throw error;
     }
   }
-  track(sql, op) {
+  track(sql, op, measure) {
     if (!this.metrics) return op();
-    return this.metrics.trackQuery(op, { databaseId: this.databaseId, sql });
+    return this.metrics.trackQuery(op, { databaseId: this.databaseId, sql }, measure);
   }
   async withTransactionHooks(statements, op) {
     for (const statement of statements) this.fireBefore(statement.sql, statement.params);
     const start = performance.now();
     try {
-      return await this.trackEach(statements, op);
-    } finally {
-      const durationMs = performance.now() - start;
-      for (const statement of statements) this.fireAfter(statement.sql, statement.params, durationMs);
+      const results = await this.trackEach(statements, op);
+      this.fireAfterEach(statements, performance.now() - start, STATEMENT_SUCCEEDED);
+      return results;
+    } catch (error) {
+      this.fireAfterEach(statements, performance.now() - start, { failed: true, error });
+      throw error;
     }
   }
+  fireAfterEach(statements, durationMs, outcome) {
+    for (const statement of statements) this.fireAfter(statement.sql, statement.params, durationMs, outcome);
+  }
   trackEach(statements, op) {
     const metrics = this.metrics;
     if (!metrics) return op();
     let run = op;
-    for (const statement of statements) {
+    statements.forEach((statement, index) => {
       const inner = run;
-      const sql = statement.sql;
-      run = () => metrics.trackQuery(inner, { databaseId: this.databaseId, sql });
-    }
+      run = () => metrics.trackQuery(inner, { databaseId: this.databaseId, sql: statement.sql }, (results) => ({
+        changes: results[index]?.changes
+      }));
+    });
     return run();
   }
   fireBefore(sql, params, options) {
     fireBeforeQueryHooks(this.parentHooks, this.localHooks, this.databaseId, sql, params, options);
   }
-  fireAfter(sql, params, durationMs) {
-    fireAfterQueryHooks(this.parentHooks, this.localHooks, this.databaseId, sql, params, durationMs);
+  fireAfter(sql, params, durationMs, outcome) {
+    fireAfterQueryHooks(this.parentHooks, this.localHooks, this.databaseId, sql, params, durationMs, outcome);
   }
 };
 
@@ -1301,7 +1309,7 @@ var DatabaseSyncController = class {
   }
   applyLocalPruneBoundary() {
     if (this.localPruneBoundary !== null) {
-      this.cdc.changeTracker?.setPruneBoundary(this.localPruneBoundary);
+      this.cdc.changeTracker?.setPruneBoundary("device-sync", this.localPruneBoundary);
     }
   }
   readOutboxBatch(afterSeq, limit) {
@@ -1579,6 +1587,14 @@ function toError(error) {
 }
 
 // src/core/database-writes.ts
+function changesOf(result) {
+  return { changes: result.changes };
+}
+function totalChanges(results) {
+  let changes = 0;
+  for (const result of results) changes += result.changes;
+  return { changes };
+}
 var DatabaseWriteController = class {
   constructor(deps) {
     this.deps = deps;
@@ -1592,7 +1608,8 @@ var DatabaseWriteController = class {
       () => writeGate.run(
         () => observer.track(
           sql,
-          () => writerLock.isHeld() ? groupCommitter.runUngrouped(sql, params) : groupCommitter.submit(sql, params)
+          () => writerLock.isHeld() ? groupCommitter.runUngrouped(sql, params) : groupCommitter.submit(sql, params),
+          changesOf
         )
       )
     );
@@ -1605,7 +1622,12 @@ var DatabaseWriteController = class {
       options,
       () => writeGate.run(
         () => writerLock.run(
-          () => this.runInTransaction(pool.acquireWriter(), sql, (txConn) => executeBatch(txConn, sql, paramsBatch))
+          () => this.runInTransaction(
+            pool.acquireWriter(),
+            sql,
+            (txConn) => executeBatch(txConn, sql, paramsBatch),
+            totalChanges
+          )
         )
       )
     );
@@ -1626,7 +1648,7 @@ var DatabaseWriteController = class {
             durability: options?.durability,
             checkpoint: options?.checkpoint ?? true,
             capturesChangeLog,
-            loadRows: () => this.runInTransaction(writer, sql, (txConn) => executeBatchSummary(txConn, sql, paramsBatch))
+            loadRows: () => this.runInTransaction(writer, sql, (txConn) => executeBatchSummary(txConn, sql, paramsBatch), changesOf)
           });
         })
       )
@@ -1655,15 +1677,16 @@ var DatabaseWriteController = class {
       return results;
     });
   }
-  async runInTransaction(writer, sql, run) {
+  async runInTransaction(writer, sql, run, measure) {
     const { observer, cdc } = this.deps;
     const result = await observer.track(
       sql,
-      () => writer.transaction(async (txConn) => {
+      () => runWriterTransaction(writer, async (txConn) => {
         const value = await run(txConn);
         await cdc.applyStamps(txConn);
         return value;
-      })
+      }),
+      measure
     );
     await applyDdlSideEffectsIfRelevant(cdc.changeTracker, writer, sql);
     return result;
@@ -1678,8 +1701,16 @@ var HOOK_CONFIG_MAP = {
   onDatabaseOpen: "databaseOpen",
   onDatabaseClose: "databaseClose",
   onBeforeSubscribe: "beforeSubscribe",
-  onBeforeSnapshot: "beforeSnapshot"
+  onBeforeSnapshot: "beforeSnapshot",
+  onBeforePush: "beforePush"
 };
+function callSynchronously(event, hook, ctx) {
+  const result = hook(ctx);
+  if (result == null || typeof result.then !== "function") return;
+  result.then(void 0, () => {
+  });
+  throw new Error(`Hook for '${event}' returned a Promise. Use invoke() for async hooks.`);
+}
 var HookRegistry = class {
   hooks = /* @__PURE__ */ new Map();
   constructor(config) {
@@ -1713,9 +1744,17 @@ var HookRegistry = class {
     if (!list || list.length === 0) return;
     const snapshot = list.slice();
     for (const hook of snapshot) {
-      const result = hook(ctx);
-      if (result != null && typeof result.then === "function") {
-        throw new Error(`Hook for '${event}' returned a Promise. Use invoke() for async hooks.`);
+      callSynchronously(event, hook, ctx);
+    }
+  }
+  invokeSyncIgnoringFailures(event, ctx) {
+    const list = this.hooks.get(event);
+    if (!list || list.length === 0) return;
+    const snapshot = list.slice();
+    for (const hook of snapshot) {
+      try {
+        callSynchronously(event, hook, ctx);
+      } catch {
       }
     }
   }
@@ -1844,7 +1883,7 @@ var LoadedExtensions = class {
       await connection.loadExtension(resolvedPath);
     }
   }
-  /** Loads an extension onto the pool's connections and every connection opened beyond it, then records it. */
+  /** Loads an extension into the pool's connections and every tracked connection, then records its resolved path. */
   load(poolConnections, extensionPath) {
     return this.runInTurn(async () => {
       const resolved = await loadExtension(this.driver, [...poolConnections, ...this.openedConnections], extensionPath);
@@ -1852,12 +1891,12 @@ var LoadedExtensions = class {
     });
   }
   /**
-   * Opens a connection, loads every recorded extension onto it, and returns a
-   * connection that forwards to it. Closing the returned connection stops the
-   * tracking and closes the one underneath.
+   * Opens a connection, loads every recorded extension into it, and returns a
+   * wrapper that forwards each call to it. Closing the wrapper stops the
+   * tracking and closes the connection underneath.
    *
-   * @param openConnection - Opens the connection this database needs.
-   * @returns The connection to read and write through.
+   * @param openConnection - The function that opens the connection that this database needs.
+   * @returns The wrapper to read and write through.
    */
   open(openConnection) {
     return this.runInTurn(async () => {
@@ -1994,7 +2033,9 @@ async function createDatabaseRuntime(id, path, driver, options, internals) {
     () => pool.acquireWriter(),
     options?.cdcPollInterval ?? 50,
     options?.cdcRetention ?? 36e5,
-    canOpenSnapshotConnection ? openSnapshotConnection : null
+    canOpenSnapshotConnection ? openSnapshotConnection : null,
+    resolveDeviceRetentionPolicy(options),
+    internals?.metrics?.observeDispatch(id)
   );
   const sync = new DatabaseSyncController(
     (op) => writeGate.run(() => writerLock.run(op)),
@@ -2068,20 +2109,26 @@ async function closeDatabaseRuntime(runtime, closeListeners) {
 
 // src/core/database-lifecycle.ts
 var DatabaseLifecycle = class {
-  /** Identifier this database was opened under. */
+  /** The identifier that this database was opened under. */
   id;
-  /** File path of the SQLite database. */
+  /** The file path of the SQLite database. */
   path;
-  /** Whether this database refuses writes. */
+  /** Whether this database rejects writes. */
   readOnly;
   /**
-   * Pool, locks, and controllers this database runs its work through.
+   * The retention settings that this database was opened with, which form an empty object when the caller set none.
+   *
+   * @internal
+   */
+  changeRetention;
+  /**
+   * The pool, locks, and controllers that this database sends its work through.
    *
    * @internal
    */
   runtime;
   /**
-   * Functions that run while this database closes.
+   * The functions that Sirannon calls while this database closes.
    *
    * @internal
    */
@@ -2092,11 +2139,16 @@ var DatabaseLifecycle = class {
     this.path = path;
     this.runtime = runtime;
     this.readOnly = options?.readOnly ?? false;
+    this.changeRetention = {
+      ...options?.cdcRetention === void 0 ? {} : { cdcRetention: options.cdcRetention },
+      ...options?.deviceCursorRetention === void 0 ? {} : { deviceCursorRetention: options.deviceCursorRetention },
+      ...options?.maxChangesHeldForDevice === void 0 ? {} : { maxChangesHeldForDevice: options.maxChangesHeldForDevice }
+    };
   }
   /**
-   * Registers a function that runs while this database closes.
+   * Registers a function that Sirannon calls while this database closes.
    *
-   * @param fn - Called during {@link DatabaseLifecycle.close}.
+   * @param fn - The function to call during {@link DatabaseLifecycle.close}.
    *
    * @internal
    */
@@ -2105,7 +2157,7 @@ var DatabaseLifecycle = class {
     this.closeListeners.push(fn);
   }
   /**
-   * Closes every connection this database holds and ends its subscriptions.
+   * Closes every connection that this database opened, and stops delivering changes to its subscriptions.
    */
   async close() {
     if (this.closing) return;
@@ -2113,19 +2165,19 @@ var DatabaseLifecycle = class {
     await closeDatabaseRuntime(this.runtime, this.closeListeners);
   }
   /**
-   * Whether this database has been closed.
+   * True once {@link DatabaseLifecycle.close} has started on this database.
    */
   get closed() {
     return this.closing;
   }
   /**
-   * Number of read connections the pool holds.
+   * The number of read connections in the pool.
    */
   get readerCount() {
     return this.runtime.pool.readerCount;
   }
   /**
-   * Refuses the call when this database is closed, is loading a snapshot, or refuses writes.
+   * Throws when this database is closed, is loading a snapshot, or rejects writes.
    *
    * @internal
    */
@@ -2134,7 +2186,7 @@ var DatabaseLifecycle = class {
     if (this.readOnly) throw new ReadOnlyError(this.id);
   }
   /**
-   * Refuses the call when this database is closed or is loading a snapshot.
+   * Throws when this database is closed or is loading a snapshot.
    *
    * @internal
    */
@@ -2148,7 +2200,7 @@ var DatabaseLifecycle = class {
     }
   }
   /**
-   * Refuses the call when this database is closed.
+   * Throws when this database is closed.
    *
    * @internal
    */
@@ -2164,71 +2216,74 @@ var DatabaseBackups = class extends DatabaseLifecycle {
   /**
    * Copies this database to a file while it stays open for reads and writes.
    *
-   * SQLite moves the pages in steps on the connection that writes, so a write
-   * runs in the gap between two steps rather than waiting for the whole copy.
+   * Sirannon holds the writer only until SQLite copies the first step of pages,
+   * so later writes commit between the steps of the copy and wait for none of it.
    *
-   * @param destPath - Path the copy is written to.
-   * @returns The run identifier, the timings, the pages it moved, and the bytes the file holds.
+   * @param destPath - The path of the file that Sirannon writes the copy to.
+   * @returns The run identifier, the timings, the number of pages copied, and the size of the file in bytes.
    */
   async backup(destPath) {
     this.ensureOpen();
     return this.runtime.backups.backup(destPath);
   }
   /**
-   * Copies this database to a destination you supply, in fixed-size pieces,
-   * while it stays open for reads and writes.
+   * Copies this database to a destination that you supply, in fixed-size
+   * pieces, while it stays open for reads and writes.
    *
-   * Sirannon carries no storage client, so the destination is where you
-   * connect object storage or anything else that moves bytes.
+   * Sirannon includes no storage client, so you connect object storage, or any
+   * other store, through the destination.
    *
-   * The pieces reach the destination as SQLite writes them where this runtime
-   * carries the compiled streaming extension, so the run needs no local disk.
-   * Every other runtime writes one local file first and needs local disk equal
-   * to the backup. {@link DatabaseBackups.backupCapabilities} states which of
-   * the two this one does.
+   * Where this runtime has the compiled streaming extension, Sirannon sends each
+   * piece to the destination as SQLite writes it, so the copy needs no local
+   * disk. On every other runtime, Sirannon writes one local file first, which
+   * needs local disk equal to the size of the backup.
+   * {@link DatabaseBackups.backupCapabilities} reports which of the two routes
+   * applies to this runtime.
    *
-   * @param options - Destination, naming, piece size, and progress reporting.
-   * @returns The run identifier, the timings, what the run wrote, and how often the copy restarted.
+   * @param options - The destination, the naming, the piece size, and the progress callback.
+   * @returns The run identifier, the timings, what the copy wrote, and how many times the copy restarted.
    */
   async backupTo(options) {
     this.ensureOpen();
     return this.runtime.backups.backupTo(options);
   }
   /**
-   * Reports which backup operations this database's runtime supports, so you
-   * learn before a run rather than when one fails.
+   * Reports which backup operations this database's runtime supports, so that
+   * you can check them before you start a backup.
    *
-   * @returns What this runtime copies, whether it needs local disk, and whether it schedules.
+   * @returns Whether this runtime can copy the database, whether a copy needs local disk, and whether it can schedule copies.
    */
   backupCapabilities() {
     return this.runtime.backups.capabilities();
   }
   /**
-   * Starts repeating backups on a cron schedule, keeping a bounded number of files.
+   * Starts copying this database to a directory on a cron schedule, and deletes
+   * the oldest copies beyond {@link BackupScheduleOptions.maxFiles}.
    *
-   * @param options - Cron expression, destination directory, retention, and time zone, along with the callbacks Sirannon calls after each finished copy and after each failure.
+   * @param options - The cron expression, destination directory, retention, and time zone, with the callbacks that Sirannon calls after each finished copy and after each failure.
    */
   scheduleBackup(options) {
     this.ensureOpen();
     this.runtime.backups.schedule(options);
   }
   /**
-   * Runs one turn of the checkpoint cycle now instead of waiting for its
-   * interval. A turn sends any capture still waiting, reads the log frames
+   * Takes one turn of the backup cycle now, without waiting for the interval. A
+   * turn sends any capture that is still waiting, captures the log frames
    * written since the previous turn, and then checkpoints the log.
    *
-   * A database needs the `backups` option to have a cycle at all. On a node its
-   * replication group backs up from somewhere else, the turn writes nothing and
-   * reports a skip through `onSkip`.
+   * Only a database opened with the `backups` option has a cycle, and on any
+   * other database this throws `BACKUP_UNSUPPORTED`. On a node whose replication
+   * group takes its backups from another node, Sirannon writes nothing on the
+   * turn and reports a skip through `onSkip`.
    *
-   * @returns What the turn wrote, or undefined where it wrote nothing.
+   * @returns What Sirannon wrote on the turn, or undefined when it wrote nothing.
    */
   async captureBackupChanges() {
     this.ensureOpen();
     return this.runtime.backups.captureChanges();
   }
   /**
-   * Lists what the backup destination holds.
+   * Lists the backup chains at the destination.
    *
    * @returns One entry per chain, newest first, each with its full copy and its change pieces in order.
    */
@@ -2237,12 +2292,13 @@ var DatabaseBackups = class extends DatabaseLifecycle {
     return this.runtime.backups.chains();
   }
   /**
-   * Reads what this database's backup cycle is doing at this moment, and what
-   * its recent turns produced.
+   * Returns what this database's backup cycle is doing now, and the outcome of
+   * its recent turns.
    *
-   * A caller that triggers a turn with {@link DatabaseBackups.captureBackupChanges}
-   * without waiting on it would read this until that turn finishes. A full copy
-   * of a large database reports its pages as SQLite moves them.
+   * You can poll this while a turn that you started with
+   * {@link DatabaseBackups.captureBackupChanges} is still under way, and during
+   * a full copy of a large database, the status includes the pages that SQLite
+   * has copied so far.
    *
    * @returns Whether a turn is under way, how far it has got, and the last run, skip, and failure.
    */
@@ -2251,64 +2307,64 @@ var DatabaseBackups = class extends DatabaseLifecycle {
     return this.runtime.backups.status();
   }
   /**
-   * Reads one of this database's backups back out of the destination and
-   * compares it against the record the backup that wrote it left behind.
+   * Fetches one of this database's backups from the destination and checks it
+   * against the record that Sirannon wrote with that backup.
    *
-   * A restore would fail on a damaged piece only once that restore had already
-   * begun, so name the backup here beforehand. Sirannon then fetches every
-   * piece in order and folds a SHA-256 over the bytes as they arrive, and it
-   * compares that digest and the byte count against the record. Only one piece
-   * is in memory at any moment, so a check over a large full copy needs no
-   * local storage of its own.
+   * A restore fails on a damaged piece only after the restore has started, so
+   * call this beforehand to check the backup. Sirannon fetches every piece in
+   * order, computes a SHA-256 over the bytes as they arrive, and compares that
+   * digest and the byte count with the record. Sirannon keeps one piece in
+   * memory at a time, so checking a large full copy needs no local disk.
    *
-   * A missing piece, a byte count that differs from the recorded one, and a
-   * digest that differs from the recorded one will each fail with
-   * `BACKUP_DESTINATION_ERROR`.
+   * This method throws `BACKUP_DESTINATION_ERROR` when a piece is missing, or
+   * when the byte count or the digest differs from the record.
    *
-   * @param name - Name the backup is stored under, which every entry {@link DatabaseBackups.backupChain} returns states.
-   * @returns The pieces read, the bytes they add up to, and the digest where the backup recorded one.
+   * @param name - The name that the backup is stored under, as each entry from {@link DatabaseBackups.backupChain} gives it.
+   * @returns The number of pieces read, their total size in bytes, and the digest when the backup recorded one.
    */
   async verifyBackup(name) {
     this.ensureNotClosed();
     return this.runtime.backups.verify(name);
   }
   /**
-   * Reads where this database's backups are stored.
+   * Returns where this database's backups are stored.
    *
-   * `restoreBackup` accepts what you get back, and it then rebuilds this
-   * database from its own backups at whatever path you name.
+   * Pass the destination, chain name, and deadline from the result to
+   * `restoreBackup` to rebuild this database from its backups at a path that
+   * you name.
    *
-   * @returns The destination, the name its chains are listed under, and the directory Sirannon stages captures in.
+   * @returns The destination, the name that the chains are listed under, and the directory where Sirannon stages captures.
    */
   backupLocation() {
     this.ensureNotClosed();
     return this.runtime.backups.location();
   }
   /**
-   * Works out what a restore to a given moment has to read.
+   * Returns the full copy and the change pieces that a restore to a given
+   * moment would apply.
    *
-   * The result also tells you the moment it would actually reach, which is when
-   * the last piece was captured. One piece covers every write in the interval
-   * it was taken over, so a restore arrives at a piece boundary, not at the
-   * exact millisecond you named.
+   * The plan also includes the moment that the restored database would reflect,
+   * which is the capture time of its last piece. Each piece contains every write
+   * from one capture interval, so a restore stops at a piece boundary, which
+   * can fall before the millisecond that you name.
    *
-   * @param moment - Epoch milliseconds you want back.
-   * @returns The full copy, the change pieces to apply in order, and the moment the result reflects.
+   * @param moment - The moment to restore to, in epoch milliseconds.
+   * @returns The full copy, the change pieces to apply in order, and the moment that the result reflects.
    */
   async backupRestorePlan(moment) {
     this.ensureNotClosed();
     return this.runtime.backups.restorePlan(moment);
   }
   /**
-   * Tells you which backups no restore still needs, so you can delete them
-   * knowing exactly what you give up. Name the earliest moment you still want
-   * to reach and the answer also covers the older chains a newer full copy
-   * already spans.
+   * Returns the backup records that no restore needs any longer, so that you
+   * can delete them from the destination yourself.
    *
-   * Sirannon lists them and deletes nothing. The destination is yours.
+   * When you pass the earliest moment that a restore must still reach, the list
+   * also includes every chain whose full copy finished before the full copy
+   * that a restore to that moment would start from.
    *
-   * @param options - How far back you still want to be able to restore.
-   * @returns The records you may delete, oldest first.
+   * @param options - The earliest moment that a restore must still reach.
+   * @returns The records that you can delete, oldest chain first.
    */
   async backupPiecesSafeToDelete(options) {
     this.ensureNotClosed();
@@ -2317,12 +2373,18 @@ var DatabaseBackups = class extends DatabaseLifecycle {
 };
 
 // src/core/database-reads.ts
+function countRows(rows) {
+  return { rowsReturned: rows.length };
+}
+function countRow(row) {
+  return { rowsReturned: row === void 0 ? 0 : 1 };
+}
 function readRows(deps, sql, params, options) {
   return deps.observer.withQueryHooks(
     sql,
     params,
     options,
-    () => onReadConnection(deps, sql, (conn) => query(conn, sql, params))
+    () => onReadConnection(deps, sql, (conn) => query(conn, sql, params), countRows)
   );
 }
 function readWireRows(deps, sql, params, options) {
@@ -2330,7 +2392,7 @@ function readWireRows(deps, sql, params, options) {
     sql,
     params,
     options,
-    () => onReadConnection(deps, sql, (conn) => queryForWire(conn, sql, params))
+    () => onReadConnection(deps, sql, (conn) => queryForWire(conn, sql, params), countRows)
   );
 }
 function readOneRow(deps, sql, params, options) {
@@ -2338,14 +2400,14 @@ function readOneRow(deps, sql, params, options) {
     sql,
     params,
     options,
-    () => onReadConnection(deps, sql, (conn) => queryOne(conn, sql, params))
+    () => onReadConnection(deps, sql, (conn) => queryOne(conn, sql, params), countRow)
   );
 }
-function onReadConnection(deps, sql, op) {
+function onReadConnection(deps, sql, op, measure) {
   if (deps.pool.readerCount === 0) {
-    return deps.writerLock.run(() => deps.observer.track(sql, () => op(deps.pool.acquireWriter())));
+    return deps.writerLock.run(() => deps.observer.track(sql, () => op(deps.pool.acquireWriter()), measure));
   }
-  return deps.observer.track(sql, () => op(deps.pool.acquireReader()));
+  return deps.observer.track(sql, () => op(deps.pool.acquireReader()), measure);
 }
 
 // src/core/live/column-collations.ts
@@ -3430,22 +3492,23 @@ var Database = class _Database extends DatabaseBackups {
     return this.runtime.sync.applyChanges(batch, resolver);
   }
   /**
-   * Returns the device-sync port for this database, which reads and advances
-   * the cursors a `SyncController` keeps against a server.
+   * Returns the device-sync port for this database, which a `SyncController`
+   * calls to apply pulled changes, read unpushed local changes, and store its
+   * push and pull cursors.
    *
-   * @returns The port, which `downloadDatabaseSnapshot` also accepts.
+   * @returns The port, which you can also pass to `downloadDatabaseSnapshot`.
    */
   deviceSync() {
     this.ensureNotClosed();
     return this.runtime.sync.devicePort();
   }
   /**
-   * Runs a read and returns every row.
+   * Executes a read and returns every row.
    *
-   * @param sql - The statement to run.
-   * @param params - Values bound to the statement, named or positional.
-   * @param options - Read concern for this statement.
-   * @returns The rows the statement produced.
+   * @param sql - The statement to execute.
+   * @param params - The values to bind to the statement, named or positional.
+   * @param options - The read concern for this statement.
+   * @returns The rows that the statement returns.
    */
   async query(sql, params, options) {
     this.ensureOpen();
@@ -3457,35 +3520,35 @@ var Database = class _Database extends DatabaseBackups {
     return readWireRows(this.runtime.reads, sql, params, options);
   }
   /**
-   * Runs a read and returns its first row.
+   * Executes a read and returns its first row.
    *
-   * @param sql - The statement to run.
-   * @param params - Values bound to the statement, named or positional.
-   * @param options - Read concern for this statement.
-   * @returns The first row, or undefined when the statement produced none.
+   * @param sql - The statement to execute.
+   * @param params - The values to bind to the statement, named or positional.
+   * @param options - The read concern for this statement.
+   * @returns The first row, or undefined when the statement returns none.
    */
   async queryOne(sql, params, options) {
     this.ensureOpen();
     return readOneRow(this.runtime.reads, sql, params, options);
   }
   /**
-   * Runs one write.
+   * Executes one write statement.
    *
-   * @param sql - The statement to run.
-   * @param params - Values bound to the statement, named or positional.
-   * @param options - Write concern for this statement.
-   * @returns How many rows changed, and the last inserted row id.
+   * @param sql - The statement to execute.
+   * @param params - The values to bind to the statement, named or positional.
+   * @param options - The write concern for this statement.
+   * @returns The number of rows that the statement changed, and the row id of the last inserted row.
    */
   async execute(sql, params, options) {
     this.ensureWritable();
     return this.runtime.writes.execute(sql, params, options);
   }
   /**
-   * Runs one statement over many parameter sets inside a single transaction.
+   * Executes one statement once for each parameter set, inside a single transaction.
    *
-   * @param sql - The statement to run for each parameter set.
-   * @param paramsBatch - One parameter set per run.
-   * @param options - Write concern for the transaction.
+   * @param sql - The statement to execute for each parameter set.
+   * @param paramsBatch - One parameter set for each execution.
+   * @param options - The write concern for the transaction.
    * @returns One result per parameter set, in order.
    */
   async executeBatch(sql, paramsBatch, options) {
@@ -3493,34 +3556,38 @@ var Database = class _Database extends DatabaseBackups {
     return this.runtime.writes.executeBatch(sql, paramsBatch, options);
   }
   /**
-   * Imports many rows with relaxed writer durability, then restores the configured level.
+   * Imports many rows at a relaxed synchronous level, then restores the level that you configured.
+   *
+   * Use this for a load that you can re-run from scratch, and use
+   * {@link Database.executeBatch} where the rows need full durability. Sirannon
+   * holds the writer lock for the whole load and commits every row in one
+   * transaction. Whether the load succeeds or fails, Sirannon restores the
+   * configured level before this method resolves. The result contains totals
+   * for the whole load, so that a large load keeps no per-row results in memory.
    *
-   * Use this for a load you can re-run from scratch, because
-   * {@link Database.executeBatch} keeps full durability. The load holds the
-   * writer lock throughout and restores the configured level before this
-   * resolves, whether it succeeds or fails. One transaction covers the whole
-   * batch, and the rows are summed rather than returned one by one to bound
-   * memory on a large load. Like {@link Database.execute}, this writes only to
-   * the local database; under replication the server routes loads through the
-   * engine instead.
+   * Like {@link Database.execute}, this writes to the local database only. A
+   * server whose execution target has no `bulkLoad` method, such as the
+   * replication engine, rejects bulk loads with `BULK_LOAD_UNSUPPORTED`.
    *
-   * @param sql - The statement to run for each parameter set.
+   * @param sql - The statement to execute for each parameter set.
    * @param paramsBatch - One parameter set per row.
-   * @param options - Durability during the load, and whether it ends with a checkpoint.
-   * @returns How many rows the load applied and how many rows changed.
+   * @param options - The synchronous level during the load, and whether the load ends with a checkpoint.
+   * @returns The number of parameter sets that the load applied, and the number of rows that changed.
    */
   async bulkLoad(sql, paramsBatch, options) {
     this.ensureWritable();
     return this.runtime.writes.bulkLoad(sql, paramsBatch, options);
   }
   /**
-   * Runs a fixed list of statements in one transaction so that several callers can share one commit.
+   * Executes a fixed list of statements in one transaction, which Sirannon can commit together with other callers' writes.
    *
-   * This takes the statements up front rather than a callback, because a group
-   * cannot wait on an arbitrary caller-supplied callback without delaying every
-   * transaction beside it.
+   * When every statement is an INSERT, UPDATE, DELETE, or REPLACE, Sirannon
+   * groups the transaction with other writes into one commit, and otherwise it
+   * executes the transaction on its own. This method takes the statements up
+   * front, because a group commit that waited on a caller's callback would delay
+   * every other transaction in the group.
    *
-   * @param statements - The statements to run, in order, each with its own parameters.
+   * @param statements - The statements to execute, in order, each with its own parameters.
    * @returns One result per statement, in order.
    */
   async executeTransaction(statements) {
@@ -3529,19 +3596,19 @@ var Database = class _Database extends DatabaseBackups {
     return this.runtime.writes.executeTransaction(statements);
   }
   /**
-   * Runs a function inside one transaction, committing when it returns and rolling back when it throws.
+   * Calls a function inside one transaction, and commits when the function returns or rolls back when it throws.
    *
-   * @param fn - Receives the transaction and runs statements on it.
-   * @returns Whatever the function returned.
+   * @param fn - The function to call with the transaction, which executes its statements through it.
+   * @returns The value that the function returns.
    */
   async transaction(fn) {
     this.ensureWritable();
     return this.runtime.writes.transaction(fn);
   }
   /**
-   * Starts recording changes to a table so that subscribers and replication see them.
+   * Starts recording changes to a table, so that subscribers and replication receive them.
    *
-   * @param table - Name of the table to watch.
+   * @param table - The name of the table to watch.
    */
   async watch(table) {
     this.ensureWritable();
@@ -3550,17 +3617,17 @@ var Database = class _Database extends DatabaseBackups {
   /**
    * Stops recording changes to a table.
    *
-   * @param table - Name of the table to stop watching.
+   * @param table - The name of the table to stop watching.
    */
   async unwatch(table) {
     this.ensureOpen();
     await this.runtime.cdc.unwatch(table);
   }
   /**
-   * Runs a CDC maintenance write (change-log pruning) on the shared writer
-   * under the writer lock. Serialising it with application writes keeps it
-   * from becoming a second writer that contends for SQLite's single write
-   * lock and stalls the event loop on `busy_timeout`.
+   * Executes a change-log maintenance write, such as pruning, on the shared
+   * writer connection under the writer lock, so that it queues behind
+   * application writes and never contends with them for SQLite's write lock,
+   * which would block the event loop for the `busy_timeout`.
    *
    * @internal
    */
@@ -3574,22 +3641,22 @@ var Database = class _Database extends DatabaseBackups {
     await this.runtime.cdc.ensureStamping();
   }
   /**
-   * Begins a change subscription on a watched table.
+   * Starts building a change subscription on a watched table.
    *
-   * @param table - Name of the watched table.
-   * @returns A builder you narrow with a filter and then subscribe to.
+   * @param table - The name of the watched table.
+   * @returns A builder that you narrow with a filter and then subscribe to.
    */
   on(table) {
     this.ensureOpen();
     return this.runtime.cdc.on(table);
   }
   /**
-   * Opens a live query that keeps a registered read's rows current as the tables behind it change.
+   * Opens a live query that keeps the rows of a single-table SELECT current as that table changes, and watches the table first.
    *
-   * @param operation - Name of the registered read, or a reference built by {@link operationRef}.
-   * @param args - Arguments the operation takes.
-   * @param options - Re-read jitter and the transaction size above which the query re-reads.
-   * @returns The live query, already subscribed.
+   * @param sql - The SELECT statement to keep current.
+   * @param params - The values to bind to the statement, named or positional.
+   * @param options - The re-read jitter, the transaction size above which the query re-reads, and the reporter for listener failures.
+   * @returns The live query, holding its first rows and subscribed to changes.
    */
   async live(sql, params, options) {
     this.ensureWritable();
@@ -3597,17 +3664,17 @@ var Database = class _Database extends DatabaseBackups {
     return openLiveQuery({ cdc, watch: (table) => this.watch(table) }, sql, params, options);
   }
   /**
-   * Applies every migration this database has not yet applied, in ascending version order.
+   * Applies every migration that this database has yet to apply, in ascending version order.
    *
    * @param migrations - The full set of migrations for this database.
-   * @returns Which migrations this call applied, and how many it skipped.
+   * @returns The migrations that this call applied, and the number that the database had already applied.
    */
   async migrate(migrations) {
     this.ensureOpen();
     return this.runtime.migrations.migrate(migrations);
   }
   /**
-   * Lists the migrations this database has applied.
+   * Lists the migrations that this database has applied.
    *
    * @returns One entry per applied migration, with its version, name, and checksum.
    */
@@ -3616,38 +3683,38 @@ var Database = class _Database extends DatabaseBackups {
     return this.runtime.migrations.applied();
   }
   /**
-   * Undoes applied migrations, newest first.
+   * Reverts applied migrations, newest first.
    *
-   * @param migrations - The full set of migrations so that the runner finds each down statement.
-   * @param version - Lowest version to keep. Without it, only the newest migration is undone.
-   * @returns Which migrations this call undid.
+   * @param migrations - The full set of migrations, from which the runner takes each down statement.
+   * @param version - The version to roll back to, which stays applied with every version below it; when you omit it, the runner reverts only the newest migration.
+   * @returns The migrations that this call reverted.
    */
   async rollback(migrations, version) {
     this.ensureOpen();
     return this.runtime.migrations.rollback(migrations, version);
   }
   /**
-   * Loads a SQLite extension into this database.
+   * Loads a compiled SQLite extension into every connection of this database.
    *
-   * @param extensionPath - Path to the extension, which the driver resolves to an absolute path.
+   * @param extensionPath - The path to the extension, which the driver resolves to an absolute path.
    */
   async loadExtension(extensionPath) {
     this.ensureOpen();
     await this.runtime.loadExtension(extensionPath);
   }
   /**
-   * Registers a hook that runs before each statement on this database. Throw from it to refuse the statement.
+   * Registers a hook that Sirannon calls before each statement on this database; throw from the hook to reject the statement.
    *
-   * @param hook - Receives the statement, its parameters, and the concerns it carries.
+   * @param hook - The hook, which Sirannon calls with the statement, its parameters, and its read or write concern.
    * @returns A function that removes the hook.
    */
   onBeforeQuery(hook) {
     return this.runtime.hookRegistry.register("beforeQuery", hook);
   }
   /**
-   * Registers a hook that runs after each statement on this database.
+   * Registers a hook that Sirannon calls after each statement on this database.
    *
-   * @param hook - Receives the statement and how long it took.
+   * @param hook - The hook, which Sirannon calls with the statement and its duration.
    * @returns A function that removes the hook.
    */
   onAfterQuery(hook) {
@@ -3788,9 +3855,10 @@ var LifecycleManager = class {
 };
 
 // src/core/lifecycle/tenant.ts
-var SAFE_ID_PATTERN = /^[a-zA-Z0-9][a-zA-Z0-9_-]*$/;
+var SAFE_ID_PATTERN = /^[a-z0-9][a-z0-9_-]*$/;
 var MAX_ID_LENGTH = 255;
 var MAX_FILENAME_LENGTH = 255;
+var SAFE_ID_RULE = `1 to ${MAX_ID_LENGTH} lowercase letters, digits, underscores, or hyphens, starting with a letter or a digit`;
 function sanitizeTenantId(id) {
   if (!id || id.length > MAX_ID_LENGTH) return void 0;
   if (!SAFE_ID_PATTERN.test(id)) return void 0;
@@ -3799,7 +3867,7 @@ function sanitizeTenantId(id) {
 function tenantPath(basePath, tenantId, extension = ".db") {
   const sanitized = sanitizeTenantId(tenantId);
   if (!sanitized) {
-    throw new Error(`Invalid tenant ID: '${tenantId}'`);
+    throw new Error(`Invalid tenant ID: '${tenantId}'. A tenant ID must be ${SAFE_ID_RULE}.`);
   }
   const filename = `${sanitized}${extension}`;
   if (filename.length > MAX_FILENAME_LENGTH) {
@@ -3828,14 +3896,17 @@ var MetricsCollector = class {
   constructor(config) {
     this.config = config ?? {};
   }
-  async trackQuery(fn, context) {
+  async trackQuery(fn, context, measure) {
     if (!this.config.onQueryComplete) {
       return fn();
     }
     const start = performance.now();
     let failed = false;
+    let outcome = {};
     try {
-      return await fn();
+      const result = await fn();
+      if (measure) outcome = measure(result);
+      return result;
     } catch (err) {
       failed = true;
       throw err;
@@ -3844,6 +3915,7 @@ var MetricsCollector = class {
       try {
         this.config.onQueryComplete({
           ...context,
+          ...outcome,
           durationMs,
           error: failed
         });
@@ -3867,6 +3939,12 @@ var MetricsCollector = class {
     } catch {
     }
   }
+  observeDispatch(databaseId) {
+    if (!this.config.onCDCEvent) return void 0;
+    return (event, subscriberCount) => {
+      this.trackCDCEvent({ databaseId, table: event.table, operation: event.type, subscriberCount });
+    };
+  }
   get active() {
     return !!(this.config.onQueryComplete || this.config.onConnectionOpen || this.config.onConnectionClose || this.config.onCDCEvent);
   }
@@ -3997,10 +4075,10 @@ var RegistryMigrationSet = class {
   }
   loading = null;
   /**
-   * Reads the set, loading it where a function supplies it.
+   * Returns the migrations, and calls the source function on the first request when the migrations come from a function.
    *
-   * @returns The migrations, which is an empty list where the registry has none.
-   * @throws When the function returns anything but a list.
+   * @returns The migrations, or an empty list when the registry has none.
+   * @throws A `MigrationError` with code `MIGRATION_SOURCE_INVALID` when the function returns something other than an array.
    */
   load() {
     const source = this.source;
@@ -4026,7 +4104,7 @@ var RegistryMigrationSet = class {
     return loading;
   }
   /**
-   * Applies the set to one database. A database that refuses writes takes none.
+   * Applies the migrations to one database, and skips a read-only database.
    *
    * @param db - The database to migrate.
    */
@@ -4038,6 +4116,25 @@ var RegistryMigrationSet = class {
   }
 };
 
+// src/core/registry-defaults.ts
+function withRegistryDefaults(registry, options) {
+  const defaults = {};
+  if (registry.writerWorker !== void 0 && options?.writerWorker === void 0) {
+    defaults.writerWorker = registry.writerWorker;
+  }
+  if (registry.cdcRetention !== void 0 && options?.cdcRetention === void 0) {
+    defaults.cdcRetention = registry.cdcRetention;
+  }
+  if (registry.deviceCursorRetention !== void 0 && options?.deviceCursorRetention === void 0) {
+    defaults.deviceCursorRetention = registry.deviceCursorRetention;
+  }
+  if (registry.maxChangesHeldForDevice !== void 0 && options?.maxChangesHeldForDevice === void 0) {
+    defaults.maxChangesHeldForDevice = registry.maxChangesHeldForDevice;
+  }
+  if (Object.keys(defaults).length === 0) return options;
+  return { ...options, ...defaults };
+}
+
 // src/core/sirannon-offline.ts
 async function takeDatabaseOffline(offline) {
   await offline.database.close();
@@ -4085,12 +4182,12 @@ var Sirannon = class {
   metricsCollector;
   lifecycleManager;
   migrations;
-  /** The driver, hooks, metrics, lifecycle, migrations, and writer-worker default this registry was built with. */
+  /** The driver, hooks, metrics, lifecycle, migrations, and writer-worker and retention defaults that this registry was constructed with. */
   options;
   /**
-   * Builds a registry.
+   * Creates a registry.
    *
-   * @param options - Driver, hooks, metrics, lifecycle, migrations, and the writer-worker default.
+   * @param options - The driver, hooks, metrics, lifecycle, migrations, and the defaults for every database that the registry opens.
    */
   constructor(options) {
     this.options = options;
@@ -4113,14 +4210,18 @@ var Sirannon = class {
   get hookRegistry() {
     return this._hookRegistry;
   }
+  /** @internal */
+  get metrics() {
+    return this.metricsCollector;
+  }
   /**
    * Opens a database and registers it under an identifier.
    *
-   * @param id - Identifier callers reach this database by.
-   * @param path - File path of the SQLite database.
-   * @param options - Pool size, journal mode, durability, and change-capture settings.
+   * @param id - The identifier that callers use to reach this database.
+   * @param path - The file path of the SQLite database.
+   * @param options - The pool size, journal mode, synchronous level, and change-capture settings.
    * @returns The open database.
-   * @throws When the identifier is already registered.
+   * @throws A `DatabaseAlreadyExistsError` when the identifier is already in use, or `DATABASE_OPEN_FAILED` when the open or a registry migration fails.
    */
   async open(id, path, options) {
     this.ensureOpenAllowed(id);
@@ -4128,7 +4229,7 @@ var Sirannon = class {
       throw new DatabaseAlreadyExistsError(id);
     }
     this.opening.add(id);
-    const resolvedOptions = this.withRegistryDefaults(options);
+    const resolvedOptions = withRegistryDefaults(this.options, options);
     let db;
     try {
       if (this._hookRegistry.has("beforeConnect")) {
@@ -4169,10 +4270,7 @@ var Sirannon = class {
       this.openedWith.delete(id);
       this.lifecycleManager?.untrack(id);
       if (this._hookRegistry.has("databaseClose")) {
-        try {
-          this._hookRegistry.invokeSync("databaseClose", { databaseId: id, path });
-        } catch {
-        }
+        this._hookRegistry.invokeSyncIgnoringFailures("databaseClose", { databaseId: id, path });
       }
       this.metricsCollector?.trackConnection({
         databaseId: id,
@@ -4185,10 +4283,7 @@ var Sirannon = class {
     this.openedWith.set(id, resolvedOptions === void 0 ? { path } : { path, options: resolvedOptions });
     this.lifecycleManager?.markActive(id);
     if (this._hookRegistry.has("databaseOpen")) {
-      try {
-        this._hookRegistry.invokeSync("databaseOpen", { databaseId: id, path });
-      } catch {
-      }
+      this._hookRegistry.invokeSyncIgnoringFailures("databaseOpen", { databaseId: id, path });
     }
     this.metricsCollector?.trackConnection({
       databaseId: id,
@@ -4198,15 +4293,10 @@ var Sirannon = class {
     });
     return db;
   }
-  withRegistryDefaults(options) {
-    const fallback = this.options.writerWorker;
-    if (fallback === void 0 || options?.writerWorker !== void 0) return options;
-    return { ...options, writerWorker: fallback };
-  }
   /**
    * Closes one database and removes it from the registry.
    *
-   * @param id - Identifier of the database to close.
+   * @param id - The identifier of the database to close.
    */
   async close(id) {
     this.ensureRunning();
@@ -4217,19 +4307,18 @@ var Sirannon = class {
     await db.close();
   }
   /**
-   * Closes one database, calls an action against the file behind it, and then
-   * opens that database again under the same identifier with the settings it
-   * had before.
+   * Closes one database, calls an action on its file, and then opens that
+   * database again under the same identifier with its earlier settings.
    *
-   * A restore rebuilds a database at the path it already occupies, so no
-   * connection may be open on that file while Sirannon replaces its bytes. The
-   * identifier answers nothing until that database is open again, though an
-   * action that failed still leaves a database open at the end.
+   * A restore rebuilds a database at its current path, so no connection may be
+   * open on that file while Sirannon replaces its bytes. {@link Sirannon.get}
+   * returns undefined for the identifier until the database is open again, and
+   * Sirannon reopens the database even after a failed action.
    *
-   * @param id - Identifier of the database to take offline.
-   * @param action - Runs with the database closed, and receives its file path.
-   * @returns Whether the action returned, what it produced or threw, and what a failed reopen threw.
-   * @throws When no database is open under the identifier, when it refuses writes, or when the close fails.
+   * @param id - The identifier of the database to take offline.
+   * @param action - The function that Sirannon calls with the database file path once the database is closed.
+   * @returns Whether the action returned, the value that it returned or the error that it threw, and any error that the reopen threw.
+   * @throws A `DatabaseNotFoundError` when no database is open under the identifier, a `ReadOnlyError` when the database is read-only, or the close error when the close fails.
    *
    * @internal
    */
@@ -4265,7 +4354,7 @@ var Sirannon = class {
   /**
    * Returns an already-open database.
    *
-   * @param id - Identifier of the database.
+   * @param id - The identifier of the database.
    * @returns The database, or undefined when none is open under that identifier.
    */
   get(id) {
@@ -4278,15 +4367,15 @@ var Sirannon = class {
     return void 0;
   }
   /**
-   * Returns an open database, opening it through the lifecycle resolver where it is not open yet.
+   * Returns an open database, and opens it through the lifecycle resolver when it is not open yet.
    *
-   * This is the call an in-process application makes for a database the registry opens on first
-   * use through the `lifecycle.autoOpen` resolver, such as one file per tenant. Concurrent calls
-   * for the same unopened identifier share one open, so each receives the same database or the
+   * An in-process application calls this for a database that the registry opens on first use
+   * through the `lifecycle.autoOpen` resolver, such as one file per tenant. Concurrent calls for
+   * the same unopened identifier share one open, so each call receives the same database or the
    * same error.
    *
-   * @param id - Identifier of the database.
-   * @returns The database, or undefined when none is open and the resolver names no path for it.
+   * @param id - The identifier of the database.
+   * @returns The database, or undefined when none is open and the resolver returns no path for it.
    */
   async resolve(id) {
     const db = this.get(id);
@@ -4303,29 +4392,30 @@ var Sirannon = class {
     return inFlight;
   }
   /**
-   * Returns the registry migration set every database applies as it opens.
+   * Returns the registry's migration set, which Sirannon applies to each writable database as it opens.
    *
-   * Where the set came from a function, the registry calls that function once and
-   * caches what it returned, so this reports the same list on every call.
+   * When the set comes from a function, the registry calls that function once and caches the
+   * result, so this returns the same list on every call; after a failed load, the next call
+   * tries again.
    *
-   * @returns The migrations declared in `SirannonOptions.migrations`, or an empty list where none are.
+   * @returns The migrations declared in `SirannonOptions.migrations`, or an empty list when there are none.
    */
   registryMigrations() {
     return this.migrations.load();
   }
   /**
-   * Reports whether a database is open under an identifier.
+   * Returns whether a database is open under an identifier.
    *
-   * @param id - Identifier to check.
-   * @returns True when the registry holds an open database under it.
+   * @param id - The identifier to check.
+   * @returns True when the registry has an open database under that identifier.
    */
   has(id) {
     return this.dbs.has(id);
   }
   /**
-   * Returns every database this registry currently holds open.
+   * Returns every database that this registry has open.
    *
-   * @returns The open databases, keyed by identifier.
+   * @returns A copy of the open databases, keyed by identifier.
    */
   databases() {
     return new Map(this.dbs);
@@ -4333,9 +4423,9 @@ var Sirannon = class {
   /**
    * Closes every open database and stops the lifecycle timers.
    *
-   * A database whose file Sirannon is replacing delays the shutdown until that
-   * work finishes, since a process that exits part-way through would leave the
-   * path with no database on it at all.
+   * When Sirannon is replacing a database's file, the shutdown waits for that
+   * work to finish, because a process that exits part-way through the
+   * replacement can leave no database at the path.
    */
   async shutdown() {
     if (this._shutdown) return;
@@ -4347,45 +4437,45 @@ var Sirannon = class {
     await closeEveryDatabase(this.dbs);
   }
   /**
-   * Registers a hook that runs before each statement on every database in this registry. Throw from it to refuse the statement.
+   * Registers a hook that Sirannon calls before each statement on every database in this registry; throw from the hook to reject the statement.
    *
-   * @param hook - Receives the statement, its parameters, and the concerns it carries.
+   * @param hook - The hook, which Sirannon calls with the statement, its parameters, and its read or write concern.
    * @returns A function that removes the hook.
    */
   onBeforeQuery(hook) {
     return this._hookRegistry.register("beforeQuery", hook);
   }
   /**
-   * Registers a hook that runs after each statement on every database in this registry.
+   * Registers a hook that Sirannon calls after each statement on every database in this registry.
    *
-   * @param hook - Receives the statement and how long it took.
+   * @param hook - The hook, which Sirannon calls with the statement and its duration.
    * @returns A function that removes the hook.
    */
   onAfterQuery(hook) {
     return this._hookRegistry.register("afterQuery", hook);
   }
   /**
-   * Registers a hook that runs before a database connection opens.
+   * Registers a hook that Sirannon calls before it opens a database.
    *
-   * @param hook - Receives the database identifier and its file path.
+   * @param hook - The hook, which Sirannon calls with the database identifier and file path.
    * @returns A function that removes the hook.
    */
   onBeforeConnect(hook) {
     return this._hookRegistry.register("beforeConnect", hook);
   }
   /**
-   * Registers a hook that runs once a database is open.
+   * Registers a hook that Sirannon calls once a database is open.
    *
-   * @param hook - Receives the database identifier and its file path.
+   * @param hook - The hook, which Sirannon calls with the database identifier and file path.
    * @returns A function that removes the hook.
    */
   onDatabaseOpen(hook) {
     return this._hookRegistry.register("databaseOpen", hook);
   }
   /**
-   * Registers a hook that runs once a database is closed.
+   * Registers a hook that Sirannon calls once a database is closed.
    *
-   * @param hook - Receives the database identifier and its file path.
+   * @param hook - The hook, which Sirannon calls with the database identifier and file path.
    * @returns A function that removes the hook.
    */
   onDatabaseClose(hook) {