@delali/sirannon-db 0.2.0 → 0.2.1

package/dist/backup-scheduler/index.d.ts

@@ -1,4 +1,5 @@
-import { e as SQLiteConnection, f as BackupScheduleOptions } from '../types-zhnRXrsb.js';
+import { e as SQLiteConnection, f as BackupScheduleOptions } from '../types-rVZKnKN-.js';
+import '../query-types-DL3LtPvY.js';
 
 declare class BackupManager {
     backup(conn: SQLiteConnection, destPath: string): Promise<void>;
@@ -8,9 +9,22 @@ declare class BackupManager {
 
 /** Runs a backup while the caller's writer lock is held, so it never shares the writer connection with another write. */
 type RunExclusive = (op: () => Promise<void>) => Promise<void>;
+/**
+ * @public
+ *
+ * Repeats a database backup on a cron schedule and keeps a bounded number of files.
+ */
 declare class BackupScheduler {
     private readonly manager;
     constructor(manager?: BackupManager);
+    /**
+     * Starts repeating backups and returns a function that stops them.
+     *
+     * @param conn - Connection to the database being copied.
+     * @param options - Cron expression, destination directory, retention, time zone, and failure callback.
+     * @param runExclusive - Runs each copy with the database's writer held so that no write commits mid-copy.
+     * @returns A function that stops the schedule.
+     */
     schedule(conn: SQLiteConnection, options: BackupScheduleOptions, runExclusive?: RunExclusive): () => void;
     private run;
 }

package/dist/backup-scheduler/index.mjs

@@ -1,2 +1,2 @@
-export { BackupScheduler } from '../chunk-PIKHN33N.mjs';
-import '../chunk-UC3SCMIN.mjs';
+export { BackupScheduler } from '../chunk-VOYGMAU7.mjs';
+import '../chunk-PBRXXISQ.mjs';

package/dist/baseline-D93hcIEE.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Marks the migration an existing database starts from, so earlier versions are recorded without running.
+ *
+ * @public
+ */
+interface BaselineFileOption {
+    /**
+     * Version of the migration carrying the baseline.
+     */
+    version: number;
+    /**
+     * Highest version this baseline covers.
+     */
+    through: number;
+}
+
+export type { BaselineFileOption as B };

package/dist/{change-tracker-DKRVUC3l.d.ts → change-tracker-DDmXB754.d.ts}

@@ -1,11 +1,33 @@
-import { e as SQLiteConnection, h as ChangeEvent } from './types-zhnRXrsb.js';
+import { e as SQLiteConnection } from './types-rVZKnKN-.js';
+import { C as ChangeEvent } from './query-types-DL3LtPvY.js';
 
+/**
+ * How long a change tracker keeps changes, and how much it reads at a time.
+ *
+ * @public
+ */
 interface ChangeTrackerOptions {
+    /**
+     * Milliseconds a change stays readable before it is pruned. Default: 3_600_000 (one hour).
+     */
     retention?: number;
+    /**
+     * Name of the table changes are recorded in.
+     */
     changesTable?: string;
+    /**
+     * Changes read in one poll. Default: 1000.
+     */
     pollBatchSize?: number;
 }
 
+/**
+ * Records every change to the tables you watch so that subscribers and replication can read them in order.
+ *
+ * Construct one, watch the tables you want captured, and pass it to a replication engine or leave it to the database that owns it.
+ *
+ * @public
+ */
 declare class ChangeTracker {
     private readonly watched;
     private lastSeq;
@@ -19,7 +41,19 @@ declare class ChangeTracker {
     private pruneBoundary;
     private lastPollAtTxBoundary;
     constructor(options?: ChangeTrackerOptions);
+    /**
+     * Starts recording changes to a table by installing its change-capture triggers.
+     *
+     * @param conn - Writer connection the triggers are created on.
+     * @param table - Name of the table to watch.
+     */
     watch(conn: SQLiteConnection, table: string): Promise<void>;
+    /**
+     * Stops recording changes to a table and drops its triggers.
+     *
+     * @param conn - Writer connection the triggers are dropped from.
+     * @param table - Name of the table to stop watching.
+     */
     unwatch(conn: SQLiteConnection, table: string): Promise<void>;
     /**
      * Rebuilds CDC triggers for every watched table directly on the supplied
@@ -45,6 +79,8 @@ declare class ChangeTracker {
      *   `conn`. The cached column list is updated on success.
      * - Any other error (driver failure, identifier validation failure) is
      *   rethrown so the caller's transaction can roll back deterministically.
+     *
+     * @internal
      */
     refreshAllTriggersUsingConnection(conn: SQLiteConnection): Promise<void>;
     /**
@@ -66,25 +102,37 @@ declare class ChangeTracker {
      * re-installed triggers compiled against the new schema. Those triggers
      * are dropped here so the recreated table starts with a clean slate and
      * the caller must explicitly `watch` it again.
+     *
+     * @internal
      */
     pruneDroppedTables(conn: SQLiteConnection, tables: readonly string[]): Promise<void>;
+    /** @internal */
     poll(conn: SQLiteConnection): Promise<ChangeEvent[]>;
+    /** @internal */
     get pollEndedAtTxBoundary(): boolean;
-    /** The highest seq already polled; live subscribers receive events beyond it. */
-    get cursor(): bigint;
     /**
-     * Reads retained changes for one table with seq in `(afterSeq, upToSeq]`,
-     * ordered ascending and capped at `limit`. Used to replay history to a
-     * resuming subscriber without disturbing the shared poll cursor.
+     * The highest seq already polled; live subscribers receive events beyond it.
+     *
+     * @internal
      */
-    readSince(conn: SQLiteConnection, table: string, afterSeq: bigint, upToSeq: bigint, limit: number): Promise<ChangeEvent[]>;
+    get cursor(): bigint;
+    /** @internal */
     readSinceTables(conn: SQLiteConnection, tables: readonly string[], afterSeq: bigint, upToSeq: bigint, limit: number): Promise<ChangeEvent[]>;
-    /** The lowest retained seq, or `null` when the change log is empty. */
+    /**
+     * The lowest retained seq, or `null` when the change log is empty.
+     *
+     * @internal
+     */
     getMinSeq(conn: SQLiteConnection): Promise<bigint | null>;
+    /** @internal */
     advanceToLatest(conn: SQLiteConnection): Promise<void>;
+    /** @internal */
     cleanup(conn: SQLiteConnection): Promise<number>;
+    /** @internal */
     setPruneBoundary(seq: bigint): void;
+    /** @internal */
     clearPruneBoundary(): void;
+    /** @internal */
     get watchedTables(): ReadonlySet<string>;
     private computeSeqBound;
     private assertIdentifier;

package/dist/{chunk-5NOIGN5Y.mjs → chunk-2QLXDHAP.mjs}

@@ -1,4 +1,4 @@
-import { SirannonError } from './chunk-UC3SCMIN.mjs';
+import { SirannonError } from './chunk-PBRXXISQ.mjs';
 
 // src/core/sync/errors.ts
 var ReplicationError = class extends SirannonError {

package/dist/{chunk-LNY2VVHE.mjs → chunk-7C36BCSN.mjs}

@@ -1,4 +1,4 @@
-import { MigrationError } from './chunk-UC3SCMIN.mjs';
+import { MigrationError } from './chunk-PBRXXISQ.mjs';
 
 // src/core/migrations/lazy-down.ts
 var LAZY_DOWN_SQL = /* @__PURE__ */ Symbol("sirannon.file-migration.lazy-down");

package/dist/{chunk-NVQS53NT.mjs → chunk-7FQRQH5Z.mjs}

@@ -1,56 +1,5 @@
-import { META_TABLE, CHANGES_TABLE, APPLIED_CHANGES_TABLE, MIGRATIONS_TABLE, COLUMN_VERSIONS_TABLE, DEVICE_CURSORS_TABLE, PEER_STATE_TABLE, SYNC_STATE_TABLE, STAGED_CHANGES_TABLE } from './chunk-D7LAYTKN.mjs';
-import { sha256Hex } from './chunk-GVCNMPOS.mjs';
-import { SirannonError } from './chunk-UC3SCMIN.mjs';
-
-// src/core/system-catalog/applied-changes-table.ts
-function toSeq(value) {
-  if (value === null || value === void 0) return 0n;
-  return typeof value === "bigint" ? value : BigInt(String(value));
-}
-async function ensureAppliedChangesTable(conn) {
-  await conn.exec(`
-CREATE TABLE IF NOT EXISTS "${APPLIED_CHANGES_TABLE}" (
-  source_node_id TEXT NOT NULL,
-  source_seq INTEGER NOT NULL,
-  applied_at REAL NOT NULL,
-  PRIMARY KEY (source_node_id, source_seq)
-)`);
-}
-function prepareInsertAppliedChange(conn) {
-  return conn.prepare(
-    `INSERT OR IGNORE INTO ${APPLIED_CHANGES_TABLE} (source_node_id, source_seq, applied_at) VALUES (?, ?, ?)`
-  );
-}
-async function selectMaxAppliedSourceSeq(conn, sourceNodeId) {
-  const stmt = await conn.prepare(
-    `SELECT MAX(source_seq) AS max_seq FROM ${APPLIED_CHANGES_TABLE} WHERE source_node_id = ?`
-  );
-  const row = await stmt.get(sourceNodeId);
-  return toSeq(row?.max_seq);
-}
-async function selectMaxAppliedSourceSeqByNode(conn) {
-  const stmt = await conn.prepare(
-    `SELECT source_node_id, MAX(source_seq) AS max_seq FROM ${APPLIED_CHANGES_TABLE} GROUP BY source_node_id`
-  );
-  const rows = await stmt.all();
-  const byNode = /* @__PURE__ */ new Map();
-  for (const row of rows) {
-    if (row.max_seq === null || row.max_seq === void 0) continue;
-    byNode.set(row.source_node_id, toSeq(row.max_seq));
-  }
-  return byNode;
-}
-async function selectAppliedSourceSeqsInRange(conn, sourceNodeId, fromSeq, toSeqBound) {
-  const stmt = await conn.prepare(
-    `SELECT source_seq FROM ${APPLIED_CHANGES_TABLE} WHERE source_node_id = ? AND source_seq >= ? AND source_seq <= ?`
-  );
-  const rows = await stmt.all(sourceNodeId, fromSeq.toString(), toSeqBound.toString());
-  const seqs = /* @__PURE__ */ new Set();
-  for (const row of rows) {
-    seqs.add(String(row.source_seq));
-  }
-  return seqs;
-}
+import { META_TABLE, CHANGES_TABLE, MIGRATIONS_TABLE, APPLIED_CHANGES_TABLE, COLUMN_VERSIONS_TABLE, DEVICE_CURSORS_TABLE, PEER_STATE_TABLE, SYNC_STATE_TABLE, STAGED_CHANGES_TABLE } from './chunk-7R4ER4FB.mjs';
+import { SirannonError } from './chunk-PBRXXISQ.mjs';
 
 // src/core/system-catalog/sqlite-catalog.ts
 async function selectTableExists(conn, table) {
@@ -167,11 +116,6 @@ var DDL_CHANGE_ROW_TABLE = "__ddl__";
 function selectChangesAfterSeqSql(tableName) {
   return `SELECT ${CHANGE_LOG_COLUMNS} FROM "${tableName}" WHERE seq > ? ORDER BY seq ASC LIMIT ?`;
 }
-function selectTableChangesInRangeSql(tableName) {
-  return `SELECT ${CHANGE_LOG_COLUMNS} FROM "${tableName}"
-          WHERE table_name = ? AND seq > ? AND seq <= ?
-          ORDER BY seq ASC LIMIT ?`;
-}
 function selectTablesChangesInRangeSql(tableName, tableCount) {
   const placeholders = Array.from({ length: tableCount }, () => "?").join(", ");
   return `SELECT ${CHANGE_LOG_COLUMNS} FROM "${tableName}"
@@ -312,6 +256,56 @@ function highestMigrationVersion(rows) {
   return highest;
 }
 
+// src/core/system-catalog/applied-changes-table.ts
+function toSeq(value) {
+  if (value === null || value === void 0) return 0n;
+  return typeof value === "bigint" ? value : BigInt(String(value));
+}
+async function ensureAppliedChangesTable(conn) {
+  await conn.exec(`
+CREATE TABLE IF NOT EXISTS "${APPLIED_CHANGES_TABLE}" (
+  source_node_id TEXT NOT NULL,
+  source_seq INTEGER NOT NULL,
+  applied_at REAL NOT NULL,
+  PRIMARY KEY (source_node_id, source_seq)
+)`);
+}
+function prepareInsertAppliedChange(conn) {
+  return conn.prepare(
+    `INSERT OR IGNORE INTO ${APPLIED_CHANGES_TABLE} (source_node_id, source_seq, applied_at) VALUES (?, ?, ?)`
+  );
+}
+async function selectMaxAppliedSourceSeq(conn, sourceNodeId) {
+  const stmt = await conn.prepare(
+    `SELECT MAX(source_seq) AS max_seq FROM ${APPLIED_CHANGES_TABLE} WHERE source_node_id = ?`
+  );
+  const row = await stmt.get(sourceNodeId);
+  return toSeq(row?.max_seq);
+}
+async function selectMaxAppliedSourceSeqByNode(conn) {
+  const stmt = await conn.prepare(
+    `SELECT source_node_id, MAX(source_seq) AS max_seq FROM ${APPLIED_CHANGES_TABLE} GROUP BY source_node_id`
+  );
+  const rows = await stmt.all();
+  const byNode = /* @__PURE__ */ new Map();
+  for (const row of rows) {
+    if (row.max_seq === null || row.max_seq === void 0) continue;
+    byNode.set(row.source_node_id, toSeq(row.max_seq));
+  }
+  return byNode;
+}
+async function selectAppliedSourceSeqsInRange(conn, sourceNodeId, fromSeq, toSeqBound) {
+  const stmt = await conn.prepare(
+    `SELECT source_seq FROM ${APPLIED_CHANGES_TABLE} WHERE source_node_id = ? AND source_seq >= ? AND source_seq <= ?`
+  );
+  const rows = await stmt.all(sourceNodeId, fromSeq.toString(), toSeqBound.toString());
+  const seqs = /* @__PURE__ */ new Set();
+  for (const row of rows) {
+    seqs.add(String(row.source_seq));
+  }
+  return seqs;
+}
+
 // src/core/system-catalog/column-versions-table.ts
 var UPSERT_COLUMN_VERSION = `INSERT INTO ${COLUMN_VERSIONS_TABLE} (table_name, row_id, column_name, hlc, node_id)
        VALUES (?, ?, ?, ?, ?)
@@ -634,11 +628,6 @@ var PkResolver = class {
   }
 };
 
-// src/core/sync/checksum.ts
-function computeChecksum(changes) {
-  return sha256Hex(canonicaliseForChecksum(changes));
-}
-
 // src/core/sync/validators.ts
 var IDENTIFIER_RE = /^[a-zA-Z_][a-zA-Z0-9_]*$/;
 var SEQ_STRING_RE = /^\d{1,19}$/;
@@ -662,4 +651,4 @@ function extractDroppedTable(sql) {
   return m?.[1] ?? null;
 }
 
-export { IDENTIFIER_RE, PkResolver, SEQ_STRING_RE, UPSERT_META_VALUE_SQL, assertSafeIdentifier, canonicaliseForChecksum, computeChecksum, deleteAllStagedChanges, deleteChangesBeforeSql, deleteChangesBeforeUpToSeqSql, deleteDeviceCursorsUpdatedBefore, deleteMetaValue, deleteStagedChangesUpToSeq, deleteSyncTableStates, ensureBatchApplyTables, ensureChangesTable, ensureDeviceCursorsTable, ensureMetaTable, ensureMigrationsTable, ensureReplicationStateTables, ensureStagedChangesTable, extractDroppedTable, highestMigrationVersion, insertDdlChange, insertMetaValueIfAbsent, prepareDeleteMigration, prepareDeleteRowColumnVersions, prepareDeleteRowColumnVersionsUpToHlc, prepareInsertAppliedChange, prepareInsertMigration, prepareUpdateMigrationChecksum, prepareUpsertColumnVersion, prepareUpsertNewerColumnVersion, referencedTables, replaceMigrationHistory, selectAppliedMigrations, selectAppliedMigrationsNewestFirst, selectAppliedSourceSeqsInRange, selectChangesAfterSeqSql, selectCompletedSyncTableNames, selectCountOutboundChanges, selectCountTableRows, selectDeviceCursors, selectFirstStagedTransactionEnd, selectMaxAppliedSourceSeq, selectMaxAppliedSourceSeqByNode, selectMaxChangeHlc, selectMaxChangeSeq, selectMaxColumnVersionHlc, selectMaxColumnVersionHlcForRow, selectMaxRowChangeHlc, selectMaxStagedSeq, selectMetaValue, selectMinChangeSeqSql, selectMinForeignChangeSeqSql, selectMinPeerAckedSeq, selectNodeChangesAfterSeqSql, selectOutboundChangesSql, selectPeerAckedSeq, selectStagedChangesInRange, selectSyncMetaRow, selectTableChangesInRangeSql, selectTableExists, selectTableSql, selectTablesChangesInRangeSql, selectUserSchemaObjects, selectUserTableNames, setForeignKeysEnabled, tableColumnNames, tableInfoRows, tablePkColumns, updateChangeStampsAfterSeqSql, updateUnstampedChangeStampsSql, upsertDeviceCursor, upsertMetaValue, upsertPeerAckedSeq, upsertStagedChangeSql, upsertSyncMeta, upsertSyncTableStatus, validateDdlSafety, validateIdentifier };
+export { IDENTIFIER_RE, PkResolver, SEQ_STRING_RE, UPSERT_META_VALUE_SQL, assertSafeIdentifier, canonicaliseForChecksum, deleteAllStagedChanges, deleteChangesBeforeSql, deleteChangesBeforeUpToSeqSql, deleteDeviceCursorsUpdatedBefore, deleteMetaValue, deleteStagedChangesUpToSeq, deleteSyncTableStates, ensureBatchApplyTables, ensureChangesTable, ensureDeviceCursorsTable, ensureMetaTable, ensureMigrationsTable, ensureReplicationStateTables, ensureStagedChangesTable, extractDroppedTable, highestMigrationVersion, insertDdlChange, insertMetaValueIfAbsent, prepareDeleteMigration, prepareDeleteRowColumnVersions, prepareDeleteRowColumnVersionsUpToHlc, prepareInsertAppliedChange, prepareInsertMigration, prepareUpdateMigrationChecksum, prepareUpsertColumnVersion, prepareUpsertNewerColumnVersion, referencedTables, replaceMigrationHistory, selectAppliedMigrations, selectAppliedMigrationsNewestFirst, selectAppliedSourceSeqsInRange, selectChangesAfterSeqSql, selectCompletedSyncTableNames, selectCountOutboundChanges, selectCountTableRows, selectDeviceCursors, selectFirstStagedTransactionEnd, selectMaxAppliedSourceSeq, selectMaxAppliedSourceSeqByNode, selectMaxChangeHlc, selectMaxChangeSeq, selectMaxColumnVersionHlc, selectMaxColumnVersionHlcForRow, selectMaxRowChangeHlc, selectMaxStagedSeq, selectMetaValue, selectMinChangeSeqSql, selectMinForeignChangeSeqSql, selectMinPeerAckedSeq, selectNodeChangesAfterSeqSql, selectOutboundChangesSql, selectPeerAckedSeq, selectStagedChangesInRange, selectSyncMetaRow, selectTableExists, selectTableSql, selectTablesChangesInRangeSql, selectUserSchemaObjects, selectUserTableNames, setForeignKeysEnabled, tableColumnNames, tableInfoRows, tablePkColumns, updateChangeStampsAfterSeqSql, updateUnstampedChangeStampsSql, upsertDeviceCursor, upsertMetaValue, upsertPeerAckedSeq, upsertStagedChangeSql, upsertSyncMeta, upsertSyncTableStatus, validateDdlSafety, validateIdentifier };

package/dist/{chunk-D7LAYTKN.mjs → chunk-7R4ER4FB.mjs}

@@ -1,4 +1,4 @@
-import { ForbiddenSqlError } from './chunk-UC3SCMIN.mjs';
+import { ForbiddenSqlError } from './chunk-PBRXXISQ.mjs';
 
 // src/core/internal-tables.ts
 var INTERNAL_TABLE_PREFIX = "_sirannon_";

package/dist/{chunk-FHWTZFI4.mjs → chunk-BQFQ65OL.mjs}

@@ -1,4 +1,4 @@
-import { SirannonError } from './chunk-UC3SCMIN.mjs';
+import { SirannonError } from './chunk-PBRXXISQ.mjs';
 
 // src/core/driver/define.ts
 function defineDriver(config) {

package/dist/{chunk-O7SLN3GI.mjs → chunk-BTTFW4Z4.mjs}

@@ -1,4 +1,4 @@
-import { ReplicationError } from './chunk-5NOIGN5Y.mjs';
+import { ReplicationError } from './chunk-2QLXDHAP.mjs';
 
 // src/replication/errors.ts
 var ConflictError = class extends ReplicationError {

package/dist/{chunk-H6PIVVDN.mjs → chunk-CCZK6LCB.mjs}

@@ -1,7 +1,7 @@
-import { tableColumnNames, tablePkColumns, selectMinChangeSeqSql, selectMaxChangeSeq, deleteChangesBeforeUpToSeqSql, deleteChangesBeforeSql, selectTableExists, ensureChangesTable, ensureMetaTable, insertMetaValueIfAbsent, selectMetaValue, selectChangesAfterSeqSql, selectTableChangesInRangeSql, selectTablesChangesInRangeSql } from './chunk-NVQS53NT.mjs';
-import { CHANGES_TABLE, isReservedIdentifier, CDC_TRIGGER_PREFIX, encodeTaggedValues, decodeTaggedValues, SAFE_INT_BOUND_TEXT } from './chunk-D7LAYTKN.mjs';
-import { synchronousPragmaValue } from './chunk-LFZ37BSX.mjs';
-import { SirannonError, ForbiddenSqlError, CDCError, MigrationError } from './chunk-UC3SCMIN.mjs';
+import { tableColumnNames, tablePkColumns, selectMinChangeSeqSql, selectMaxChangeSeq, deleteChangesBeforeUpToSeqSql, deleteChangesBeforeSql, selectTableExists, ensureChangesTable, ensureMetaTable, insertMetaValueIfAbsent, selectMetaValue, selectChangesAfterSeqSql, selectTablesChangesInRangeSql } from './chunk-7FQRQH5Z.mjs';
+import { CHANGES_TABLE, isReservedIdentifier, CDC_TRIGGER_PREFIX, encodeTaggedValues, decodeTaggedValues, SAFE_INT_BOUND_TEXT } from './chunk-7R4ER4FB.mjs';
+import { synchronousPragmaValue } from './chunk-OUSWVNWT.mjs';
+import { SirannonError, ForbiddenSqlError, CDCError, MigrationError } from './chunk-PBRXXISQ.mjs';
 
 // src/core/bulk-load.ts
 var DEFAULT_LOAD_DURABILITY = "off";
@@ -107,11 +107,6 @@ async function pollChanges(conn, cache, changesTable, afterSeq, batchSize) {
   }
   return { events, lastSeq, atTxBoundary: false };
 }
-async function readSinceOneTable(conn, cache, changesTable, table, afterSeq, upToSeq, limit) {
-  const stmt = await cache.get(conn, "read_since", selectTableChangesInRangeSql(changesTable));
-  const rows = await stmt.all(table, afterSeq.toString(), upToSeq.toString(), limit);
-  return rows.map(rowToEvent);
-}
 async function readSinceTables(conn, cache, changesTable, tables, afterSeq, upToSeq, limit) {
   if (tables.length === 0) return [];
   const stmt = await cache.get(
@@ -228,6 +223,12 @@ var ChangeTracker = class {
     this.pollBatchSize = options?.pollBatchSize ?? DEFAULT_POLL_BATCH_SIZE;
     this.assertIdentifier(this.changesTable, "changes table name");
   }
+  /**
+   * Starts recording changes to a table by installing its change-capture triggers.
+   *
+   * @param conn - Writer connection the triggers are created on.
+   * @param table - Name of the table to watch.
+   */
   async watch(conn, table) {
     this.assertIdentifier(table, "table name");
     if (isReservedIdentifier(table)) {
@@ -258,6 +259,12 @@ var ChangeTracker = class {
     this.watched.set(table, { table, columns, pkColumns });
     this.watchedTablesCache = null;
   }
+  /**
+   * Stops recording changes to a table and drops its triggers.
+   *
+   * @param conn - Writer connection the triggers are dropped from.
+   * @param table - Name of the table to stop watching.
+   */
   async unwatch(conn, table) {
     if (!this.watched.has(table)) {
       return;
@@ -290,6 +297,8 @@ var ChangeTracker = class {
    *   `conn`. The cached column list is updated on success.
    * - Any other error (driver failure, identifier validation failure) is
    *   rethrown so the caller's transaction can roll back deterministically.
+   *
+   * @internal
    */
   async refreshAllTriggersUsingConnection(conn) {
     const tables = Array.from(this.watched.keys());
@@ -337,6 +346,8 @@ var ChangeTracker = class {
    * re-installed triggers compiled against the new schema. Those triggers
    * are dropped here so the recreated table starts with a clean slate and
    * the caller must explicitly `watch` it again.
+   *
+   * @internal
    */
   async pruneDroppedTables(conn, tables) {
     let mutated = false;
@@ -352,6 +363,7 @@ var ChangeTracker = class {
       this.watchedTablesCache = null;
     }
   }
+  /** @internal */
   async poll(conn) {
     if (!this.changesTableReady) {
       await this.detectChangesTable(conn);
@@ -368,27 +380,19 @@ var ChangeTracker = class {
     this.lastSeq = result.lastSeq;
     return result.events;
   }
+  /** @internal */
   get pollEndedAtTxBoundary() {
     return this.lastPollAtTxBoundary;
   }
-  /** The highest seq already polled; live subscribers receive events beyond it. */
-  get cursor() {
-    return this.lastSeq;
-  }
   /**
-   * Reads retained changes for one table with seq in `(afterSeq, upToSeq]`,
-   * ordered ascending and capped at `limit`. Used to replay history to a
-   * resuming subscriber without disturbing the shared poll cursor.
+   * The highest seq already polled; live subscribers receive events beyond it.
+   *
+   * @internal
    */
-  async readSince(conn, table, afterSeq, upToSeq, limit) {
-    if (!this.changesTableReady) {
-      await this.detectChangesTable(conn);
-      if (!this.changesTableReady) {
-        return [];
-      }
-    }
-    return readSinceOneTable(conn, this.stmtCache, this.changesTable, table, afterSeq, upToSeq, limit);
+  get cursor() {
+    return this.lastSeq;
   }
+  /** @internal */
   async readSinceTables(conn, tables, afterSeq, upToSeq, limit) {
     if (tables.length === 0) return [];
     if (!this.changesTableReady) {
@@ -399,7 +403,11 @@ var ChangeTracker = class {
     }
     return readSinceTables(conn, this.stmtCache, this.changesTable, tables, afterSeq, upToSeq, limit);
   }
-  /** The lowest retained seq, or `null` when the change log is empty. */
+  /**
+   * The lowest retained seq, or `null` when the change log is empty.
+   *
+   * @internal
+   */
   async getMinSeq(conn) {
     if (!this.changesTableReady) {
       await this.detectChangesTable(conn);
@@ -415,6 +423,7 @@ var ChangeTracker = class {
     }
     return typeof seq === "bigint" ? seq : BigInt(String(seq));
   }
+  /** @internal */
   async advanceToLatest(conn) {
     if (!this.changesTableReady) {
       await this.detectChangesTable(conn);
@@ -427,6 +436,7 @@ var ChangeTracker = class {
       this.lastSeq = latestSeq;
     }
   }
+  /** @internal */
   async cleanup(conn) {
     if (!this.changesTableReady) {
       await this.detectChangesTable(conn);
@@ -449,12 +459,15 @@ var ChangeTracker = class {
     const result = await stmt.run(cutoff);
     return result.changes;
   }
+  /** @internal */
   setPruneBoundary(seq) {
     this.pruneBoundary = seq;
   }
+  /** @internal */
   clearPruneBoundary() {
     this.pruneBoundary = null;
   }
+  /** @internal */
   get watchedTables() {
     if (!this.watchedTablesCache) {
       this.watchedTablesCache = new Set(this.watched.keys());

package/dist/{chunk-JZGINXTN.mjs → chunk-HCCGEIZ2.mjs}

@@ -1,5 +1,5 @@
-import { assertSqlAllowed, encodeWireRowsInPlace } from './chunk-D7LAYTKN.mjs';
-import { SirannonError, QueryError } from './chunk-UC3SCMIN.mjs';
+import { assertSqlAllowed, encodeWireRowsInPlace } from './chunk-7R4ER4FB.mjs';
+import { SirannonError, QueryError } from './chunk-PBRXXISQ.mjs';
 
 // src/core/query-executor.ts
 var STATEMENT_CACHE_CAPACITY = 128;

package/dist/{chunk-67M7KAH6.mjs → chunk-IWGIYDMZ.mjs}

@@ -1,4 +1,4 @@
-import { MigrationError } from './chunk-UC3SCMIN.mjs';
+import { MigrationError } from './chunk-PBRXXISQ.mjs';
 
 // src/core/migrations/baseline.ts
 var SQLITE_USER_VERSION_MAX = 2147483647;

package/dist/{chunk-LFZ37BSX.mjs → chunk-OUSWVNWT.mjs}

@@ -1,4 +1,4 @@
-import { SirannonError } from './chunk-UC3SCMIN.mjs';
+import { SirannonError } from './chunk-PBRXXISQ.mjs';
 
 // src/core/driver/synchronous.ts
 var DEFAULT_SYNCHRONOUS = "normal";

package/dist/{chunk-HR5CWTLC.mjs → chunk-P2VJYRVY.mjs}

@@ -1,7 +1,8 @@
-import { query, execute, executeBatch } from './chunk-JZGINXTN.mjs';
-import { ensureMetaTable, selectMetaValue, computeChecksum, IDENTIFIER_RE, selectAppliedSourceSeqsInRange, prepareInsertAppliedChange, validateDdlSafety, extractDroppedTable, selectMaxChangeSeq, updateChangeStampsAfterSeqSql, selectOutboundChangesSql, selectNodeChangesAfterSeqSql, prepareDeleteRowColumnVersionsUpToHlc, canonicaliseForChecksum, prepareUpsertNewerColumnVersion, upsertMetaValue, selectMaxColumnVersionHlcForRow, selectMaxRowChangeHlc, validateIdentifier, prepareDeleteRowColumnVersions, prepareUpsertColumnVersion } from './chunk-NVQS53NT.mjs';
-import { ReplicationError, BatchValidationError } from './chunk-5NOIGN5Y.mjs';
-import { CHANGES_TABLE, decodeTaggedValues } from './chunk-D7LAYTKN.mjs';
+import { query, execute, executeBatch } from './chunk-HCCGEIZ2.mjs';
+import { ensureMetaTable, selectMetaValue, IDENTIFIER_RE, selectAppliedSourceSeqsInRange, prepareInsertAppliedChange, validateDdlSafety, extractDroppedTable, selectMaxChangeSeq, updateChangeStampsAfterSeqSql, selectOutboundChangesSql, selectNodeChangesAfterSeqSql, prepareDeleteRowColumnVersionsUpToHlc, canonicaliseForChecksum, prepareUpsertNewerColumnVersion, upsertMetaValue, selectMaxColumnVersionHlcForRow, selectMaxRowChangeHlc, validateIdentifier, prepareDeleteRowColumnVersions, prepareUpsertColumnVersion } from './chunk-7FQRQH5Z.mjs';
+import { ReplicationError, BatchValidationError } from './chunk-2QLXDHAP.mjs';
+import { CHANGES_TABLE, decodeTaggedValues } from './chunk-7R4ER4FB.mjs';
+import { sha256Hex } from './chunk-GVCNMPOS.mjs';
 
 // src/core/transaction.ts
 var Transaction = class _Transaction {
@@ -9,14 +10,35 @@ var Transaction = class _Transaction {
     this.conn = conn;
   }
   _lastInsertRowId = 0;
+  /**
+   * Runs a read inside this transaction.
+   *
+   * @param sql - The statement to run.
+   * @param params - Values bound to the statement, named or positional.
+   * @returns The rows the statement produced.
+   */
   async query(sql, params) {
     return query(this.conn, sql, params);
   }
+  /**
+   * Runs one write inside this transaction.
+   *
+   * @param sql - The statement to run.
+   * @param params - Values bound to the statement, named or positional.
+   * @returns How many rows changed, and the last inserted row id.
+   */
   async execute(sql, params) {
     const result = await execute(this.conn, sql, params);
     this._lastInsertRowId = result.lastInsertRowId;
     return result;
   }
+  /**
+   * Runs one statement over many parameter sets inside this transaction.
+   *
+   * @param sql - The statement to run for each parameter set.
+   * @param paramsBatch - One parameter set per run.
+   * @returns One result per parameter set, in order.
+   */
   async executeBatch(sql, paramsBatch) {
     const results = await executeBatch(this.conn, sql, paramsBatch);
     if (results.length > 0) {
@@ -24,9 +46,13 @@ var Transaction = class _Transaction {
     }
     return results;
   }
+  /**
+   * Row id SQLite assigned to the last row this transaction inserted.
+   */
   get lastInsertRowId() {
     return this._lastInsertRowId;
   }
+  /** @internal */
   static async run(conn, fn) {
     return conn.transaction(async (txConn) => {
       const tx = new _Transaction(txConn);
@@ -46,7 +72,11 @@ var HLC = class _HLC {
     this.wallMs = 0;
     this.logical = 0;
   }
-  /** Generate a new HLC timestamp, advancing the clock. */
+  /**
+   * Generate a new HLC timestamp, advancing the clock.
+   *
+   * @internal
+   */
   now() {
     const physicalMs = Date.now();
     if (physicalMs > this.wallMs) {
@@ -60,7 +90,11 @@ var HLC = class _HLC {
     }
     return _HLC.encode(this.wallMs, this.logical, this.nodeId);
   }
-  /** Merge a remote HLC timestamp into the local clock and return the updated value. */
+  /**
+   * Merge a remote HLC timestamp into the local clock and return the updated value.
+   *
+   * @internal
+   */
   receive(remote) {
     const r = _HLC.decode(remote);
     const physicalMs = Date.now();
@@ -98,6 +132,14 @@ var HLC = class _HLC {
       nodeId: parts.slice(2).join("-")
     };
   }
+  /**
+   * Builds the string form of a clock reading, which sorts in the same order as the reading itself.
+   *
+   * @param wallMs - Wall-clock milliseconds since the Unix epoch.
+   * @param logical - Counter that orders events sharing one millisecond.
+   * @param nodeId - Identifier of the node taking the reading.
+   * @returns The encoded stamp.
+   */
   static encode(wallMs, logical, nodeId) {
     const wallHex = wallMs.toString(16).padStart(12, "0");
     const logicalHex = logical.toString(16).padStart(4, "0");
@@ -107,6 +149,12 @@ var HLC = class _HLC {
 
 // src/core/sync/conflict/lww.ts
 var LWWResolver = class {
+  /**
+   * Takes the incoming row when its stamp is higher, and keeps the local row otherwise.
+   *
+   * @param ctx - The local and incoming versions of one row.
+   * @returns Which version to write.
+   */
   resolve(ctx) {
     if (ctx.remoteChange.operation === "delete") {
       return { action: "accept_remote" };
@@ -128,6 +176,11 @@ var LWWResolver = class {
   }
 };
 
+// src/core/sync/checksum.ts
+function computeChecksum(changes) {
+  return sha256Hex(canonicaliseForChecksum(changes));
+}
+
 // src/core/sync/hlc-store.ts
 var HLC_CLOCK_META_KEY = "hlc_clock";
 function isWellFormedHlc(candidate) {
@@ -403,7 +456,7 @@ var BatchApplier = class {
   }
   /**
    * Applies one pulled transaction whose changes are read from disk in
-   * batches, so a transaction of any size is applied with bounded memory.
+   * batches so that a transaction of any size is applied with bounded memory.
    * The whole group runs in one local transaction: the batches, the echo
    * stamping, and `withinTx` commit together or not at all.
    */

package/dist/{chunk-UC3SCMIN.mjs → chunk-PBRXXISQ.mjs}

@@ -54,6 +54,9 @@ var HookDeniedError = class extends SirannonError {
   }
 };
 var RequestDeniedError = class extends SirannonError {
+  /**
+   * HTTP status the server answers the refused request with.
+   */
   status;
   constructor(status, code, message) {
     super(message, code);