@delali/sirannon-db 0.3.4-next.61 → 0.3.4-next.64

package/README.md

@@ -6,9 +6,9 @@
 [![types](https://img.shields.io/badge/types-TypeScript-blue)](https://www.npmjs.com/package/@delali/sirannon-db)
 [![license](https://img.shields.io/npm/l/@delali/sirannon-db)](https://github.com/assetcorp/sirannon-db/blob/main/LICENSE)
 
-Build a networked SQLite service with connection pooling, change data capture, live queries, migrations, backups, device sync, and a client SDK. Applications reach Sirannon over HTTP or WebSocket, and Sirannon nodes replicate primary-owned changes over gRPC.
+Build a networked SQLite service with connection pooling, change data capture, live queries, migrations, backups, device sync, and a client SDK. Applications reach Sirannon over HTTP or WebSocket, while a primary replicates its changes to other Sirannon nodes over gRPC.
 
-**Read the full documentation at [sirannon.sondelali.com/docs](https://sirannon.sondelali.com/docs).** This page gets you running, and the [guides](#documentation) hold the reference depth. The suite that measures Sirannon against Postgres 17 is a Python project under [`benchmarks/server`](../../benchmarks/server), and the write-up generator rewrites [BENCHMARKS.md](../../BENCHMARKS.md) from the latest committed run.
+**Read the full documentation at [sirannon.sondelali.com/docs](https://sirannon.sondelali.com/docs).** Use this page to get started, and turn to the [guides](#documentation) for the detail. The benchmark harness that measures Sirannon against Postgres 17 is under [`benchmarks/server`](https://github.com/assetcorp/sirannon-db/tree/main/benchmarks/server), where a Node load generator drives both engines and a Python step joins their results. The write-up generator rewrites [BENCHMARKS.md](https://github.com/assetcorp/sirannon-db/blob/main/BENCHMARKS.md) from the latest committed run.
 
 The core engine, server, client, and primary-replica replication are stable. Coordinator-backed failover, device sync, and the Bun and Expo drivers are experimental.
 
@@ -25,13 +25,33 @@ Then add the SQLite driver for your runtime:
 | Driver | Import | Runtime | Install |
 | --- | --- | --- | --- |
 | better-sqlite3 | `@delali/sirannon-db/driver/better-sqlite3` | Node.js | `pnpm add -E better-sqlite3` |
-| Node built-in | `@delali/sirannon-db/driver/node` | Node.js >= 22 | None (flag-free from 22.13.0 and 23.4.0) |
+| Node built-in | `@delali/sirannon-db/driver/node` | Node.js >= 22 | None (no flag needed from 22.13.0 and 23.4.0) |
 | wa-sqlite | `@delali/sirannon-db/driver/wa-sqlite` | Browser (IndexedDB) | `pnpm add -E wa-sqlite` |
-| Bun | `@delali/sirannon-db/driver/bun` | Bun | None (uses `bun:sqlite`) |
+| Bun | `@delali/sirannon-db/driver/bun` | Bun | None (built on `bun:sqlite`) |
 | Expo | `@delali/sirannon-db/driver/expo` | React Native | `pnpm add -E expo-sqlite` |
 
 Write a custom driver by passing `capabilities` and an `open` function to `defineDriver`.
 
+To serve a registry over HTTP and WebSocket through `@delali/sirannon-db/server`, add uWebSockets.js as well. The npm registry has no package named `uWebSockets.js`, so install the tagged GitHub release v20.69.0, which is the version in Sirannon's own development dependencies:
+
+```bash
+pnpm add -E "uWebSockets.js@github:uNetworking/uWebSockets.js#v20.69.0"
+```
+
+When the process cannot load uWebSockets.js, `server.listen()` fails with code `SERVER_DEPENDENCY_MISSING` and a message that gives this install command.
+
+## Add Sirannon with a coding agent
+
+The [Sirannon skill](https://github.com/assetcorp/sirannon-db/tree/main/skills/sirannon) tells a coding agent which driver suits the app's runtime, which packages to install alongside it, and which server settings keep the data safe. Install the skill into the coding agents on your machine with the skills CLI:
+
+```bash
+npx skills add assetcorp/sirannon-db
+```
+
+The skill has the agent read the Sirannon version that your project installs, and it sends the agent to that version's types and documentation.
+
+On the [agents page](https://sirannon.sondelali.com/agents), you can copy a prompt for one of six database tasks and paste it into your coding agent.
+
 ## Quick start
 
 ```ts
@@ -47,36 +67,36 @@ await db.execute('INSERT INTO users (name, email) VALUES (?, ?)', ['Ada', 'ada@e
 const users = await db.query<{ id: number; name: string }>('SELECT * FROM users')
 ```
 
-In the browser, open the database directly and use one read connection, because the `Sirannon` registry is built for server-side use:
+In the browser, open the database through the same registry with the browser driver:
 
 ```ts
-import { Database } from '@delali/sirannon-db'
+import { Sirannon } from '@delali/sirannon-db'
 import { waSqlite } from '@delali/sirannon-db/driver/wa-sqlite'
 
-const driver = waSqlite({ vfs: 'IDBBatchAtomicVFS' })
-const db = await Database.create('app', '/app.db', driver, { readPoolSize: 1, walMode: false })
+const sirannon = new Sirannon({ driver: waSqlite({ vfs: 'IDBBatchAtomicVFS' }) })
+const db = await sirannon.open('app', '/app.db', { walMode: false })
 ```
 
-React Native uses the same shape through `expoSqlite()` with `readPoolSize: 1`.
+On React Native, open the database the same way with `expoSqlite()`.
 
 ## Package exports
 
 | Import | What you get |
 | --- | --- |
-| `@delali/sirannon-db` | Core library: queries, transactions, CDC, live queries, migrations, backups, hooks, metrics, lifecycle |
-| `@delali/sirannon-db/driver/*` | SQLite driver adapters (see the table above) |
-| `@delali/sirannon-db/file-migrations` | Load `.up.sql` and `.down.sql` files from a directory |
+| `@delali/sirannon-db` | Core library: queries, transactions, CDC, live queries, migrations, backups, hooks, metrics, and lifecycle |
+| `@delali/sirannon-db/driver/*` | SQLite driver adapters, listed in the table above |
+| `@delali/sirannon-db/file-migrations` | A loader for `.up.sql` and `.down.sql` files in a directory |
 | `@delali/sirannon-db/backup` | Backup destination types, chain records, and `restoreBackup` |
-| `@delali/sirannon-db/backup-scheduler` | Cron-scheduled backup runner with file rotation |
-| `@delali/sirannon-db/server` | HTTP and WebSocket server powered by uWebSockets.js |
-| `@delali/sirannon-db/client` | Client SDK with auto-reconnect, subscription restore, and device sync |
-| `@delali/sirannon-db/client/topology` | Topology-aware client that routes across a replication group |
-| `@delali/sirannon-db/react` | `useLiveQuery` and `useCommand` hooks |
+| `@delali/sirannon-db/backup-scheduler` | A cron-scheduled backup runner with file rotation |
+| `@delali/sirannon-db/server` | An HTTP and WebSocket server built on uWebSockets.js |
+| `@delali/sirannon-db/client` | A client SDK with automatic reconnection, subscription restore, and device sync |
+| `@delali/sirannon-db/client/topology` | A topology-aware client that routes across a replication group |
+| `@delali/sirannon-db/react` | The `useLiveQuery` and `useCommand` hooks |
 | `@delali/sirannon-db/codegen` | Typed operation references generated from your server's registry |
-| `@delali/sirannon-db/replication` | Replication engine, conflict resolvers, topologies, HLC |
-| `@delali/sirannon-db/replication/coordinator/etcd` | etcd-backed coordinator for primary authority and failover |
-| `@delali/sirannon-db/transport/grpc` | gRPC replication transport with TLS support |
-| `@delali/sirannon-db/transport/memory` | In-memory transport for testing |
+| `@delali/sirannon-db/replication` | The replication engine, conflict resolvers, topologies, and HLC |
+| `@delali/sirannon-db/replication/coordinator/etcd` | An etcd-backed coordinator for primary authority and failover |
+| `@delali/sirannon-db/transport/grpc` | A gRPC replication transport with TLS support |
+| `@delali/sirannon-db/transport/memory` | An in-memory transport for tests |
 
 ## Queries and transactions
 
@@ -94,11 +114,11 @@ const balance = await db.transaction(async tx => {
 })
 ```
 
-A large import runs faster through `bulkLoad`, which trades durability for speed inside one transaction and restores the configured level afterwards. The [core engine guide](../../docs/core.md) covers it, along with migrations, hooks, metrics, and the multi-tenant lifecycle. Backups have a [guide of their own](../../docs/backups.md).
+`bulkLoad` writes a large import in one transaction under relaxed durability, and then it restores the durability level that you configured. Read the [bulk load guide](https://sirannon.sondelali.com/docs/bulk-load) for the details, and the guides on [migrations](https://sirannon.sondelali.com/docs/migrations) and on [hooks, metrics, and the multi-tenant lifecycle](https://sirannon.sondelali.com/docs/hooks-metrics-and-lifecycle) for the rest of the core engine. Backups have a [guide of their own](https://sirannon.sondelali.com/docs/backups).
 
 ## Change data capture and live queries
 
-A subscription reports the rows that changed:
+Subscribe to a table to receive each row that changes:
 
 ```ts
 await db.watch('orders')
@@ -109,9 +129,9 @@ const subscription = db
   .subscribe(event => console.log(event.type, event.table, event.row, event.oldRow, event.seq))
 ```
 
-A filter reports membership of the set it describes. An order whose `status` changes from `pending` to `shipped` arrives as an insert, because the row enters the filter, and one that changes away from `shipped` arrives as a delete carrying the old row. Read `event.type` as the row's arrival or departure, since a real insert and a row entering the filter look the same.
+With a filter, you receive each change in a row's membership of the set that the filter matches. When an order's `status` changes from `pending` to `shipped`, the handler receives an insert, because the row joins the set. When an order's `status` changes away from `shipped`, the handler receives a delete with the previous row in `oldRow`. Read `event.type` as the row joining or leaving the set, because the handler receives the same event for a real insert and for a row that joins the set.
 
-A live query reports the current answer, updating the rows it holds from those same events:
+A live query holds the current result of a query and updates its rows from those same events:
 
 ```ts
 const pending = await db.live<{ id: number; total: number }>(
@@ -122,11 +142,11 @@ const pending = await db.live<{ id: number; total: number }>(
 pending.subscribe(() => render(pending.getState()))
 ```
 
-The [live queries guide](../../docs/live-queries.md) covers the update kinds, the statements a live query maintains, and the React hooks.
+Read the [live queries guide](https://sirannon.sondelali.com/docs/live-queries) for the kinds of update, the statements that a live query can maintain, and the React hooks.
 
 ## Serve it over the network
 
-A server accepts no SQL from the network by default. Register the reads and writes it runs, and callers invoke them by name:
+A server rejects SQL from the network by default. Callers call the reads and writes that you register on it by name:
 
 ```ts
 import { createServer } from '@delali/sirannon-db/server'
@@ -164,16 +184,16 @@ const client = new SirannonClient('http://localhost:9876', { transport: 'websock
 const db = client.database('app')
 
 const users = await db.query(activeUsers, {})
-const sub = await db.on('users').subscribe(event => console.log('User changed:', event))
+const liveUsers = await db.live(activeUsers, {})
 ```
 
-Run `sirannon-codegen` to generate those references from the registry instead of writing them by hand, and set `acceptSql: true` when you want the server to run statements a client sends. The [registered operations guide](../../docs/operations.md) covers both, the [server guide](../../docs/server.md) lists the routes and messages, and the [client guide](../../docs/client.md) covers the transports.
+The `sirannon-codegen` command generates those references from the registry, so you can skip writing them by hand. Set `acceptSql: true` when you want the server to execute the statements that a client sends. A client streams a table's changes through `db.on(table).subscribe` only from a server with `acceptSql: true` or an `onBeforeSubscribe` hook, which admits or refuses each table. Read the [registered operations guide](https://sirannon.sondelali.com/docs/registered-operations) and the [code generation guide](https://sirannon.sondelali.com/docs/code-generation) for operations and their references, the [server guide](https://sirannon.sondelali.com/docs/server) for `acceptSql`, the routes, and the messages, and the [client guide](https://sirannon.sondelali.com/docs/client-sdk) for the transports.
 
 ## Security
 
-Registered operations keep SQL on the server, so a caller reaches only the reads and writes you defined. Turning on `acceptSql` gives every client the run of the database, so put such a server behind an application layer, a private network boundary, or a `resolveExecutionTarget` that allows only known statements.
+With registered operations, your SQL stays on the server, so a caller of a registered read or write supplies only the arguments that you declared for it. With `acceptSql: true`, the server executes the statements that an admitted caller sends, so put that server behind an application layer or a private network boundary, or give it a `resolveExecutionTarget` that accepts only the statements that you know.
 
-Authenticate every request through the `authenticate` hook. Return the caller's identity, which registered operations read through `fromIdentity`, and throw to refuse:
+Authenticate every request through the `authenticate` hook. Return the caller's identity from the hook so that the server can fill each `fromIdentity` argument of a registered operation, and throw to reject the request:
 
 ```ts
 import { RequestDeniedError } from '@delali/sirannon-db'
@@ -192,7 +212,7 @@ const server = createServer<Identity>(sirannon, {
 })
 ```
 
-A Node client attaches `headers` to the WebSocket upgrade as well as to HTTP requests, so the hook reads `headers.authorization` on both transports:
+A Node client attaches `headers` to the WebSocket upgrade as well as to HTTP requests, so your hook can read `headers.authorization` on both transports:
 
 ```ts
 const client = new SirannonClient('https://api.example.com', {
@@ -200,7 +220,7 @@ const client = new SirannonClient('https://api.example.com', {
 })
 ```
 
-A browser attaches no header to `new WebSocket(...)`, so a browser client carries a short-lived ticket in `webSocketProtocols` instead. A browser client built with `headers` alone on the WebSocket transport fails at construction with `INVALID_ARGUMENT`, because that credential would never reach the server:
+A browser cannot attach a header to `new WebSocket(...)`, so give a browser client a short-lived ticket in `webSocketProtocols`:
 
 ```ts
 const client = new SirannonClient('https://api.example.com', {
@@ -208,45 +228,48 @@ const client = new SirannonClient('https://api.example.com', {
 })
 ```
 
-Pass both options when a browser client needs each of them, as the [entitlements example](examples/distributed-entitlements) does: the topology client sends `headers` on its coordinator discovery request to `GET /db/{id}/cluster` and the ticket on the socket handshake.
+When you construct a browser client on the WebSocket transport with `headers` alone, the constructor throws `INVALID_ARGUMENT`, because the browser would leave that credential out of the handshake. Pass both options when a browser client needs each of them, as the [entitlements example](https://github.com/assetcorp/sirannon-db/tree/main/packages/ts/examples/distributed-entitlements) does. Its topology client sends `headers` with the discovery request to `GET /db/{id}/cluster`, while it sends the ticket with the socket handshake.
 
-The client offers the plain `sirannon.v1` identifier ahead of your values and the server selects that identifier, so the ticket never comes back in the handshake response. Check the `Origin` header in the same hook. When the hook refuses an upgrade with status 401 or 403, the server closes the connection with code 4401 or 4403, and the client raises `UNAUTHORIZED` or `FORBIDDEN` and leaves that connection closed.
+Because the client offers the plain `sirannon.v1` identifier ahead of your values and the server selects it, the ticket stays out of the handshake response. Check the `Origin` header in the same hook. When the hook rejects an upgrade with status 401 or 403, the server closes the connection with code 4401 or 4403, and the client raises `UNAUTHORIZED` or `FORBIDDEN` and leaves that connection closed.
 
 - Bind to `127.0.0.1` or a private interface unless a proxy enforces TLS and access control.
-- Use HTTPS and WSS for non-local traffic, because the built-in server binds plain HTTP.
+- Use HTTPS and WSS for traffic beyond the local machine, because the built-in server listens on plain HTTP.
 - Authenticate every HTTP database route and every WebSocket upgrade, and check `Origin` against an allowlist.
-- Keep user input in parameters, which the driver binds rather than splicing into the SQL text.
-- Restrict CORS to known origins; `cors: true` allows every origin and belongs in local development.
+- Keep user input in parameters, which the driver binds separately from the SQL text.
+- Restrict CORS to known origins, since `cors: true` allows every origin and is for local development only.
 - Keep long-lived secrets out of browser-visible configuration, and redact credentials from access logs.
 - Add rate limits, audit logs, and abuse monitoring at the application or edge layer.
 
-The [security guide](https://sirannon.sondelali.com/docs) covers each of these in full.
+Read the [security guide](https://sirannon.sondelali.com/docs/security) for each of these in full.
 
 ## Documentation
 
-| Guide | What it covers |
+| Guide | Topics |
 | --- | --- |
-| [Core engine](../../docs/core.md) | Bulk load, live queries, migrations, hooks, metrics, and the multi-tenant lifecycle |
-| [Backups](../../docs/backups.md) | Copies to a file or to storage you supply, the chain of changes after one, and restoring from a moment you name |
-| [Server](../../docs/server.md) | HTTP routes, WebSocket messages, authentication, write shapes, the writer worker, and value encoding |
-| [Registered operations](../../docs/operations.md) | Naming the statements a server runs, identity-filled arguments, capabilities, and code generation |
-| [Live queries](../../docs/live-queries.md) | Maintained query results locally, over the network, and in React |
-| [Client SDK](../../docs/client.md) | Transports, subscriptions, topology-aware routing, and read concern |
-| [Device sync](../../docs/device-sync.md) | Offline-first two-way sync between a device's local database and a server |
-| [Distributed replication](../../docs/replication.md) | Replication, first sync, write and read concerns, coordinator failover, resolvers, and transports |
-| [Configuration reference](../../docs/configuration.md) | Every option table, from `SirannonOptions` to `GrpcReplicationOptions` |
-| [Errors](../../docs/errors.md) | Every code, when it happens, whether the call is safe to retry, and its HTTP status |
-
-The [specification](../spec/) defines the wire formats, value encodings, and replication invariants every implementation follows.
+| [Queries and transactions](https://sirannon.sondelali.com/docs/queries-and-transactions) | Parameterised SQL, batches, transactions, and the connection pool |
+| [Bulk load](https://sirannon.sondelali.com/docs/bulk-load) | One-transaction imports under relaxed durability, over the server, and through the client SDK |
+| [Migrations](https://sirannon.sondelali.com/docs/migrations) | File-based, programmatic, and bundled migrations, rollback, checksums, baselines, concurrency, and registry migrations |
+| [Hooks, metrics, and lifecycle](https://sirannon.sondelali.com/docs/hooks-metrics-and-lifecycle) | Before and after hooks, metrics callbacks, and the multi-tenant lifecycle |
+| [Backups](https://sirannon.sondelali.com/docs/backups) | Copies of an open database to a file and on a schedule, followed by the guides on [destinations](https://sirannon.sondelali.com/docs/backup-destinations), [continuous backups](https://sirannon.sondelali.com/docs/backup-chains), and [restores](https://sirannon.sondelali.com/docs/backup-restore) |
+| [Server](https://sirannon.sondelali.com/docs/server) | Registered operations on the server, caller identity, size limits, write shapes, `acceptSql`, the backup routes, HTTP routes, and the WebSocket protocol |
+| [Registered operations](https://sirannon.sondelali.com/docs/registered-operations) | Named reads and writes, identity-filled arguments, calls over HTTP and WebSocket, capabilities, and refusals |
+| [Live queries](https://sirannon.sondelali.com/docs/live-queries) | Maintained query results locally, over the network, and in React |
+| [Client SDK](https://sirannon.sondelali.com/docs/client-sdk) | Reads, writes, subscriptions, live queries, bulk imports, read concern, refused credentials, and client options |
+| [Device sync](https://sirannon.sondelali.com/docs/device-sync) | Offline-first two-way sync between a device's local database and a server |
+| [Distributed replication](https://sirannon.sondelali.com/docs/distributed-replication) | Certificates, first sync, write and read concerns, conflict resolution, coordinator failover, and schema changes |
+| [Configuration reference](https://sirannon.sondelali.com/docs/configuration) | Every option for the registry, a database, backups, the server, the client, device sync, and replication |
+| [Error codes](https://sirannon.sondelali.com/docs/error-codes) | Every error code, whether a retry is safe, its HTTP status, and the WebSocket close codes |
+
+The wire formats, the value encodings, and the replication invariants that every implementation follows are in the [specification](https://github.com/assetcorp/sirannon-db/tree/main/packages/spec).
 
 ## Example projects
 
 | Example | Runtime | What it demonstrates |
 | --- | --- | --- |
-| [`node`](examples/node/) | Node.js >= 22 | Schema, migrations, CRUD, transactions, CDC, live queries, pools, metrics, multi-tenant lifecycle, hooks, backup, shutdown |
-| [`web-wa-sqlite`](examples/web-wa-sqlite/) | Browser and Node.js | Offline-first device sync: a local database in the browser, snapshot load, offline writes, conflict resolution, and a local live query |
-| [`web-client`](examples/web-client/) | Browser and Node.js | Registered operations, code generation, remote live queries, and the React hooks |
-| [`distributed-entitlements`](examples/distributed-entitlements/) | Node.js and browser | Three-node coordinator-backed replication over gRPC with etcd authority, mTLS, and Toxiproxy failure controls |
+| [`node`](https://github.com/assetcorp/sirannon-db/tree/main/packages/ts/examples/node) | Node.js >= 22 | Schema, migrations, CRUD, transactions, CDC, live queries, pools, metrics, multi-tenant lifecycle, hooks, backup, and shutdown |
+| [`web-wa-sqlite`](https://github.com/assetcorp/sirannon-db/tree/main/packages/ts/examples/web-wa-sqlite) | Browser and Node.js | Offline-first device sync with a local database in the browser, snapshot load, offline writes, conflict resolution, and a local live query |
+| [`web-client`](https://github.com/assetcorp/sirannon-db/tree/main/packages/ts/examples/web-client) | Browser and Node.js | Registered operations, code generation, remote live queries, and the React hooks |
+| [`distributed-entitlements`](https://github.com/assetcorp/sirannon-db/tree/main/packages/ts/examples/distributed-entitlements) | Node.js and browser | Three-node coordinator-backed replication over gRPC with etcd authority, mTLS, and Toxiproxy failure controls |
 
 ```bash
 pnpm install && pnpm --filter @delali/sirannon-db build

package/dist/backup/index.d.ts

@@ -1,70 +1,69 @@
-import { B as BackupDestination, f as BackupRunReport } from '../types-DPSmjU54.js';
-export { g as BackupChain, h as BackupChainBase, i as BackupChainChange, j as BackupChainPosition, k as BackupChainRecord, l as BackupCycle, m as BackupCycleError, n as BackupCycleOptions, o as BackupCycleStatus, p as BackupFileReport, q as BackupGroupMembership, r as BackupGroupSource, s as BackupLogPosition, t as BackupNodePreference, u as BackupPiece, v as BackupProgress, w as BackupSkip, x as BackupSkipReason, y as BackupToDestinationOptions, z as BackupVerifyResult, C as DEFAULT_CHAIN_NAME, E as chainLogName, F as readBackupChains, G as verifyBackupRecord } from '../types-DPSmjU54.js';
-export { B as BackupCapabilities, a as BackupChainLocation, b as BackupRestorePlan, c as BackupSafeToDeleteOptions, d as backupPiecesSafeToDelete, p as planBackupRestore } from '../database-backup-B7oszQ2n.js';
-import { B as BackupRestoreOptions, a as BackupRestoreReport } from '../restore-options-CksYsH1l.js';
-export { b as BackupRestoreProgress } from '../restore-options-CksYsH1l.js';
-import '../query-types-p1liOP-b.js';
+import { B as BackupDestination, f as BackupRunReport } from '../types-Dc8oWlxj.js';
+export { g as BackupChain, h as BackupChainBase, i as BackupChainChange, j as BackupChainPosition, k as BackupChainRecord, l as BackupCycle, m as BackupCycleError, n as BackupCycleOptions, o as BackupCycleStatus, p as BackupFileReport, q as BackupGroupMembership, r as BackupGroupSource, s as BackupLogPosition, t as BackupNodePreference, u as BackupPiece, v as BackupProgress, w as BackupSkip, x as BackupSkipReason, y as BackupToDestinationOptions, z as BackupVerifyResult, C as DEFAULT_CHAIN_NAME, E as chainLogName, F as readBackupChains, G as verifyBackupRecord } from '../types-Dc8oWlxj.js';
+export { B as BackupCapabilities, a as BackupChainLocation, b as BackupRestorePlan, c as BackupSafeToDeleteOptions, d as backupPiecesSafeToDelete, p as planBackupRestore } from '../database-backup-DcLhxoa1.js';
+import { B as BackupRestoreOptions, a as BackupRestoreReport } from '../restore-options-CH8mE-Tb.js';
+export { b as BackupRestoreProgress } from '../restore-options-CH8mE-Tb.js';
+import '../query-types-5B02ixH0.js';
 
-/** What one assembled file took to build.
+/** The byte and piece counts for one file that Sirannon assembles from a destination.
  * @public
  */
 interface AssembleResult {
-    /** Bytes the assembly wrote. */
+    /** The number of bytes that Sirannon writes to the local file. */
     bytesWritten: number;
-    /** Pieces the assembly read. */
+    /** The number of pieces that Sirannon reads from the destination. */
     pieceCount: number;
-    /** SHA-256 of the assembled file, where the run recorded one to check it against. */
+    /** The SHA-256 of the assembled file, present only where the backup report holds a fingerprint to check it against. */
     fingerprint?: string;
 }
 /**
- * Builds a local file from the pieces a destination holds, checking the result
- * against what the run that wrote them reported.
+ * Rebuilds a local file from the pieces at a destination, and checks the result
+ * against the report of the backup that stored them.
  *
- * @param destination - Where the pieces are read from.
- * @param report - What the run that wrote those pieces recorded.
- * @param destPath - Path the assembled file is written to.
- * @returns The bytes and pieces the assembly wrote, and the fingerprint it computed.
+ * @param destination - The destination that holds the pieces.
+ * @param report - The report of the backup that stored those pieces.
+ * @param destPath - The path that Sirannon writes the assembled file to.
+ * @returns The bytes and pieces that Sirannon writes, and the fingerprint that it computes.
  *
  * @public
  */
 declare function assembleFromDestination(destination: BackupDestination, report: BackupRunReport, destPath: string): Promise<AssembleResult>;
 
 /**
- * Rebuilds a database from the moment you name and leaves it at a path of your
- * choosing.
+ * Rebuilds a database at the moment that you name, and writes it to a path
+ * that you choose.
  *
  * Sirannon reads the chain records at your destination and takes the newest
- * full copy finished at or before that moment. It then replays every change
- * piece captured from that copy up to the same moment, fetching one stored
- * piece and applying it before it asks for the next. One stored piece is
- * therefore all a restore holds, however large the database it rebuilds.
+ * full copy that finished at or before that moment. It then applies every
+ * change piece that it captured after that copy up to the same moment,
+ * fetching one stored piece and applying it before it requests the next, so a
+ * restore holds one stored piece in memory however large the database is.
  *
- * Two kinds of gap fail the call. A chain missing a change piece fails with
- * `BACKUP_CHAIN_BROKEN` naming the piece its sequence stops at, and a
- * destination missing one of the numbered pieces a file was stored in fails
- * with `BACKUP_DESTINATION_ERROR` naming that piece. Sirannon also checks each
- * file against the byte count and the fingerprint its backup recorded, both of
- * which cover the whole file.
+ * A gap fails the call in one of two ways. A missing change piece in the chain
+ * throws `BACKUP_CHAIN_BROKEN`, naming the sequence number where the chain
+ * stops, and a missing stored piece of a file throws
+ * `BACKUP_DESTINATION_ERROR`, naming that piece. Sirannon also checks each file
+ * against the byte count and the fingerprint in its record, both of which cover
+ * the whole file.
  *
- * Sirannon assembles the rebuilt database beside the path you named and renames
- * it onto that path once the last batch is folded in. A restore that fails, or
- * one the machine kills part-way, therefore leaves that path holding whatever
- * it held before. Where a database already sits at that path, Sirannon folds its
- * write-ahead log back into it before the rename, so a machine that stops the
- * restore between those two steps leaves that database whole. Where the fold
- * cannot empty that log, because another connection holds the database or
- * SQLite cannot open the file at all, Sirannon removes that database together
- * with its log, so a machine stopping there leaves the path plainly empty
- * rather than quietly short of its last commits. A database already there stops
- * the call unless you set `replaceExisting`, because the rename leaves the
- * rebuilt database at that path and nothing of the one it replaced.
+ * Sirannon builds the database next to the path that you name, and renames it
+ * onto that path after the checkpoint of the last batch. When the restore fails
+ * or the machine stops part-way, the path therefore keeps its previous
+ * contents. Where a database already exists at that path, Sirannon checkpoints
+ * its write-ahead log into it before the rename, so that a crash between those
+ * two steps leaves that database complete. Where the checkpoint cannot empty
+ * that log, because another connection holds the database or SQLite cannot open
+ * the file, Sirannon deletes that database and its log, so that a crash at that
+ * point leaves the path empty, with no database there that lacks its last
+ * commits. A database at that path stops the call unless you set
+ * `replaceExisting`, because the rename replaces that database entirely.
  *
- * The disk this needs is the finished database, plus one stored piece, plus the
- * log Sirannon writes for one batch of change pieces. `batchSize` sets that
- * last part.
+ * The restore needs disk space for the finished database, one stored piece,
+ * and the log that Sirannon writes for one batch of change pieces, whose size
+ * `batchSize` sets.
  *
- * @param options - Where to read from, what moment to reach, and where to put the result.
- * @returns The chain it read, the moment the result reflects, and what the restore fetched and replayed.
+ * @param options - The destination to read from, the moment to restore to, and the path for the result.
+ * @returns The chain that Sirannon reads, the moment that the rebuilt database reflects, and the counts of what the restore fetches and applies.
  *
  * @public
  */

package/dist/backup/index.mjs

@@ -1,8 +1,8 @@
-export { assembleFromDestination, restoreBackup } from '../chunk-E7Q7HE46.mjs';
-export { backupPiecesSafeToDelete, planBackupRestore } from '../chunk-YNTDOFTN.mjs';
-export { verifyBackupRecord } from '../chunk-7SC2TZAS.mjs';
-import '../chunk-U445A3C4.mjs';
-import '../chunk-GYCEJNU4.mjs';
-export { DEFAULT_CHAIN_NAME, chainLogName, readBackupChains } from '../chunk-YVF2ZJTE.mjs';
+export { assembleFromDestination, restoreBackup } from '../chunk-3BZLZ47R.mjs';
+export { backupPiecesSafeToDelete, planBackupRestore } from '../chunk-YW7IKQ7T.mjs';
+export { verifyBackupRecord } from '../chunk-DX4WGJL7.mjs';
+import '../chunk-QGVRRKB2.mjs';
+import '../chunk-R7GBXNTO.mjs';
+export { DEFAULT_CHAIN_NAME, chainLogName, readBackupChains } from '../chunk-CZL4D3BM.mjs';
 import '../chunk-QBBLSQHQ.mjs';
-import '../chunk-PBRXXISQ.mjs';
+import '../chunk-KINDFBQP.mjs';

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

@@ -1,14 +1,14 @@
-import { I as SQLiteConnection, J as BackupFileCopy, K as BackupRunRequest, f as BackupRunReport, L as BackupScheduleRequest } from '../types-DPSmjU54.js';
-export { p as BackupFileReport, O as BackupScheduleOptions, R as RunExclusive } from '../types-DPSmjU54.js';
-import '../query-types-p1liOP-b.js';
+import { I as SQLiteConnection, J as BackupFileCopy, K as BackupRunRequest, f as BackupRunReport, L as BackupScheduleRequest } from '../types-Dc8oWlxj.js';
+export { p as BackupFileReport, O as BackupScheduleOptions, R as RunExclusive } from '../types-Dc8oWlxj.js';
+import '../query-types-5B02ixH0.js';
 
-/** What one runtime needs before a copy can reach a destination without a local file.
+/** What a runtime supplies so that Sirannon can send a copy to a destination without writing a local file.
  * @internal
  */
 interface BackupStreamingSupport {
-    /** Absolute path of the compiled extension that carries the bytes. */
+    /** The absolute path of the compiled SQLite extension that queues the bytes of the copy for Sirannon to send. */
     extensionPath: string;
-    /** Opens the connection the extension's statements run on. */
+    /** Opens the connection that Sirannon runs the statements of the extension on. */
     openConnection(): Promise<SQLiteConnection>;
 }
 
@@ -16,35 +16,34 @@ declare class BackupManager {
     private readonly streaming?;
     constructor(streaming?: BackupStreamingSupport | undefined);
     /**
-     * Copies the database behind a connection to a file, while that database
-     * stays open for reads and writes.
+     * Copies the database that a connection has open to a file, while other
+     * callers go on reading from and writing to that database.
      *
-     * @param conn - Connection the copy runs on, which must be the connection that writes.
-     * @param destPath - Path to write the copy to. A file already there stops the copy.
-     * @param onFirstStep - Called once the copy's first step is done, so the caller can hand the writer back.
-     * @returns What the copy moved, how long it took, and how often it restarted.
+     * @param conn - The writer connection, which SQLite runs the copy on.
+     * @param destPath - The path to write the copy to. Sirannon refuses a path where a file already exists.
+     * @param onFirstStep - Called once after the first step of the copy, so that the caller can release the writer.
+     * @returns The pages that SQLite copies, the time that the copy takes, and the number of times that SQLite restarts it from page one.
      */
     backup(conn: SQLiteConnection, destPath: string, onFirstStep?: () => void): Promise<BackupFileCopy>;
     /**
-     * Reads the size of the file a copy wrote.
+     * Reads the size of the file that a copy writes.
      *
-     * @param resolved - Absolute path of that file.
-     * @param destPath - Path the caller named, which the error states.
-     * @returns Bytes it holds.
+     * @param resolved - The absolute path of that file.
+     * @param destPath - The path that the caller names, which Sirannon quotes in any error.
+     * @returns The size of the file, in bytes.
      */
     private fileBytes;
     /**
-     * Runs the copy, and removes the file it was writing where that copy fails, so
-     * that a database missing its later pages never stays on disk as though the
-     * copy had finished. Sirannon would otherwise count that half-written file
-     * among the copies it keeps, and it would evict a whole copy to make room for
-     * one nothing can restore.
+     * Runs the copy and deletes its file when the copy fails, so that a partly
+     * written database never stays on disk. Rotation would otherwise count that
+     * file among the copies it keeps, and it would delete a complete copy to make
+     * room for it.
      *
-     * Sirannon stops waiting on a copy once the stall deadline passes, and SQLite
-     * keeps writing that copy to the file. A removal that raced a live copy would
-     * leave a truncated file in place, and on Windows it would fail outright.
-     * Sirannon therefore removes the file only once the copy stops, while the
-     * caller receives the failure at once and waits for none of that.
+     * When the stall deadline passes, Sirannon stops waiting on the copy while
+     * SQLite goes on writing to the file. Deleting the file under a live copy
+     * would leave a truncated file in place, and on Windows the delete would fail.
+     * Sirannon therefore deletes the file once the copy stops, although the caller
+     * receives the failure straight away.
      */
     private copyOrClearUp;
     copyToDestination(conn: SQLiteConnection, request: BackupRunRequest): Promise<BackupRunReport>;
@@ -54,7 +53,7 @@ declare class BackupManager {
 }
 
 /**
- * Repeats a database backup on a cron schedule and keeps a bounded number of files.
+ * Copies a database to a file on a cron schedule, and deletes the oldest copies beyond a set number.
  *
  * @public
  */
@@ -64,29 +63,31 @@ declare class BackupScheduler {
     /**
      * Starts repeating backups and returns a function that stops them.
      *
-     * @param conn - Connection to the database being copied.
-     * @param request - Cron expression, destination directory, retention, and time zone, along with the callbacks and the database the copies come from.
+     * @param conn - The connection to the database that Sirannon copies.
+     * @param request - The cron expression, destination directory, retention, and time zone, with the callbacks and the details of the source database.
      * @returns A function that stops the schedule.
      */
     schedule(conn: SQLiteConnection, request: BackupScheduleRequest): () => void;
     /**
-     * Works out the database and the file every report names. A caller may supply
-     * either of them, and Sirannon reads the file SQLite has open where the caller
-     * named none. Sirannon puts that question to the connection that writes, so it
-     * asks with nothing else holding the writer.
+     * Returns the database identifier and the source file that every report
+     * names. The caller can supply either of them. Where the caller names no
+     * source file, Sirannon reads the path of the file that SQLite has open, and
+     * it runs that query on the writer connection while no other operation holds
+     * the writer.
      *
-     * @param conn - Connection the copies come from.
-     * @param run - The schedule, which holds whichever of the two the caller named.
-     * @param runExclusive - Runs the question with nothing else holding the writer.
-     * @returns The database identifier and the path of the file the copies come from.
-     * @throws A `BACKUP_ERROR` where the caller named no source file and SQLite has none open.
+     * @param conn - The connection that Sirannon copies from.
+     * @param run - The schedule, which holds whichever of the two the caller names.
+     * @param runExclusive - Runs the query while no other operation holds the writer.
+     * @returns The database identifier and the path of the source file.
+     * @throws A `BACKUP_ERROR` where the caller names no source file and SQLite reports no file open on the connection.
      */
     private namesFor;
     /**
-     * Passes one finished copy to the caller's completion callback, and stops
-     * waiting on that callback once its deadline passes.
+     * Passes the report of one finished copy to the completion callback of the
+     * caller, and fails with `BACKUP_ERROR` once the deadline of that callback
+     * passes. A deadline of zero waits for the callback without a limit.
      *
-     * @param report - What the copy produced.
+     * @param report - The report of the finished copy.
      * @param run - The schedule, which holds the callback and its deadline.
      */
     private handToCaller;

package/dist/backup-scheduler/index.mjs

@@ -1,6 +1,6 @@
-export { BackupScheduler } from '../chunk-JQWGHSEH.mjs';
+export { BackupScheduler } from '../chunk-NVSQ2T5Q.mjs';
 import '../chunk-W67A4H2E.mjs';
-import '../chunk-E6IMX7RS.mjs';
-import '../chunk-GYCEJNU4.mjs';
+import '../chunk-KJLNYOOL.mjs';
+import '../chunk-R7GBXNTO.mjs';
 import '../chunk-QBBLSQHQ.mjs';
-import '../chunk-PBRXXISQ.mjs';
+import '../chunk-KINDFBQP.mjs';

package/dist/baseline-Co3iIsN_.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Marks one migration file as a baseline, which a new database runs in place of every version up to and including `through`.
+ *
+ * A database that already has migration history skips the baseline and applies only the versions that it lacks.
+ *
+ * @public
+ */
+interface BaselineFileOption {
+    /**
+     * The version of the migration that acts as the baseline.
+     */
+    version: number;
+    /**
+     * The highest earlier version that a new database skips in favour of the baseline.
+     */
+    through: number;
+}
+
+export type { BaselineFileOption as B };