@fuzdev/fuz_app 0.50.0 → 0.52.0

package/dist/auth/signup_routes.js

@@ -3,7 +3,7 @@
  *
  * Public endpoint that creates an account. When `open_signup` is disabled
  * (default), a matching unclaimed invite is required. When enabled, anyone
- * can sign up without an invite. Follows the `bootstrap_routes.ts` pattern.
+ * can sign up without an invite. Follows the `auth/bootstrap_routes.ts` pattern.
  *
  * @module
  */

package/dist/cli/config.d.ts

@@ -43,6 +43,8 @@ export declare const load_config: <T>(runtime: Pick<FsReadDeps, "stat" | "read_t
  * @param path - path to the config JSON file
  * @param dir - directory containing the config file (created if missing)
  * @param config - configuration to save
+ * @mutates filesystem - creates `dir` (recursive) and writes JSON to `path`
+ * @throws Error if `mkdir` or `write_text_file` fails
  */
 export declare const save_config: <T>(runtime: Pick<FsWriteDeps, "mkdir" | "write_text_file">, path: string, dir: string, config: T) => Promise<void>;
 //# sourceMappingURL=config.d.ts.map

package/dist/cli/config.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"config.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/cli/config.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAC,CAAC,EAAC,MAAM,KAAK,CAAC;AAE3B,OAAO,KAAK,EAAC,OAAO,EAAE,UAAU,EAAE,WAAW,EAAE,OAAO,EAAC,MAAM,oBAAoB,CAAC;AAElF;;;;;;GAMG;AACH,eAAO,MAAM,WAAW,GAAI,SAAS,IAAI,CAAC,OAAO,EAAE,SAAS,CAAC,EAAE,MAAM,MAAM,KAAG,MAAM,GAAG,IAGtF,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,eAAe,GAAI,SAAS,IAAI,CAAC,OAAO,EAAE,SAAS,CAAC,EAAE,MAAM,MAAM,KAAG,MAAM,GAAG,IAG1F,CAAC;AAEF;;;;;;;GAOG;AACH,eAAO,MAAM,WAAW,GAAU,CAAC,EAClC,SAAS,IAAI,CAAC,UAAU,EAAE,MAAM,GAAG,gBAAgB,CAAC,GAAG,OAAO,EAC9D,MAAM,MAAM,EACZ,QAAQ,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,KAClB,OAAO,CAAC,CAAC,GAAG,IAAI,CAoBlB,CAAC;AAEF;;;;;;;;;GASG;AACH,eAAO,MAAM,WAAW,GAAU,CAAC,EAClC,SAAS,IAAI,CAAC,WAAW,EAAE,OAAO,GAAG,iBAAiB,CAAC,EACvD,MAAM,MAAM,EACZ,KAAK,MAAM,EACX,QAAQ,CAAC,KACP,OAAO,CAAC,IAAI,CAOd,CAAC"}
+{"version":3,"file":"config.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/cli/config.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAC,CAAC,EAAC,MAAM,KAAK,CAAC;AAE3B,OAAO,KAAK,EAAC,OAAO,EAAE,UAAU,EAAE,WAAW,EAAE,OAAO,EAAC,MAAM,oBAAoB,CAAC;AAElF;;;;;;GAMG;AACH,eAAO,MAAM,WAAW,GAAI,SAAS,IAAI,CAAC,OAAO,EAAE,SAAS,CAAC,EAAE,MAAM,MAAM,KAAG,MAAM,GAAG,IAGtF,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,eAAe,GAAI,SAAS,IAAI,CAAC,OAAO,EAAE,SAAS,CAAC,EAAE,MAAM,MAAM,KAAG,MAAM,GAAG,IAG1F,CAAC;AAEF;;;;;;;GAOG;AACH,eAAO,MAAM,WAAW,GAAU,CAAC,EAClC,SAAS,IAAI,CAAC,UAAU,EAAE,MAAM,GAAG,gBAAgB,CAAC,GAAG,OAAO,EAC9D,MAAM,MAAM,EACZ,QAAQ,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,KAClB,OAAO,CAAC,CAAC,GAAG,IAAI,CAoBlB,CAAC;AAEF;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,WAAW,GAAU,CAAC,EAClC,SAAS,IAAI,CAAC,WAAW,EAAE,OAAO,GAAG,iBAAiB,CAAC,EACvD,MAAM,MAAM,EACZ,KAAK,MAAM,EACX,QAAQ,CAAC,KACP,OAAO,CAAC,IAAI,CAOd,CAAC"}

package/dist/cli/config.js

@@ -67,6 +67,8 @@ export const load_config = async (runtime, path, schema) => {
  * @param path - path to the config JSON file
  * @param dir - directory containing the config file (created if missing)
  * @param config - configuration to save
+ * @mutates filesystem - creates `dir` (recursive) and writes JSON to `path`
+ * @throws Error if `mkdir` or `write_text_file` fails
  */
 export const save_config = async (runtime, path, dir, config) => {
     // ensure directory exists

package/dist/cli/daemon.d.ts

@@ -39,6 +39,8 @@ export declare const get_daemon_info_path: (runtime: Pick<EnvDeps, "env_get">, n
  * @param runtime - runtime with file write and env capabilities
  * @param name - application name
  * @param info - daemon info to write
+ * @mutates filesystem - creates `~/.{name}/run/` and atomically writes `daemon.json`
+ * @throws Error if `$HOME` is not set, or if directory creation / atomic write fails
  */
 export declare const write_daemon_info: (runtime: Pick<EnvDeps, "env_get"> & Pick<FsWriteDeps, "mkdir" | "write_text_file" | "rename">, name: string, info: DaemonInfo) => Promise<void>;
 /**
@@ -85,11 +87,14 @@ export interface StopDaemonResult {
  * Stop a running daemon by sending SIGTERM and cleaning up the PID file.
  *
  * Returns a result object instead of logging directly, separating
- * lifecycle from presentation.
+ * lifecycle from presentation. Errors removing the PID file are swallowed
+ * (the daemon's own shutdown handler may have removed it concurrently).
  *
  * @param runtime - runtime with command, file, and env capabilities
  * @param name - application name
  * @returns result describing the outcome
+ * @mutates filesystem - removes `~/.{name}/run/daemon.json` on success or when corrupt
+ * @mutates external process - sends `SIGTERM` to the daemon process via `kill`
  */
 export declare const stop_daemon: (runtime: Pick<EnvDeps, "env_get"> & Pick<FsReadDeps, "stat" | "read_text_file"> & FsRemoveDeps & CommandDeps & LogDeps, name: string) => Promise<StopDaemonResult>;
 //# sourceMappingURL=daemon.d.ts.map

package/dist/cli/daemon.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"daemon.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/cli/daemon.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAC,CAAC,EAAC,MAAM,KAAK,CAAC;AAEtB,OAAO,EACN,KAAK,WAAW,EAChB,KAAK,OAAO,EACZ,KAAK,SAAS,EACd,KAAK,UAAU,EACf,KAAK,YAAY,EACjB,KAAK,WAAW,EAChB,KAAK,OAAO,EACZ,MAAM,oBAAoB,CAAC;AAI5B;;GAEG;AACH,eAAO,MAAM,UAAU;IACtB,sBAAsB;;IAEtB,yBAAyB;;IAEzB,uCAAuC;;IAEvC,yCAAyC;;IAEzC,0CAA0C;;kBAEzC,CAAC;AACH,MAAM,MAAM,UAAU,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,UAAU,CAAC,CAAC;AAEpD;;;;;;GAMG;AACH,eAAO,MAAM,oBAAoB,GAChC,SAAS,IAAI,CAAC,OAAO,EAAE,SAAS,CAAC,EACjC,MAAM,MAAM,KACV,MAAM,GAAG,IAGX,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,iBAAiB,GAC7B,SAAS,IAAI,CAAC,OAAO,EAAE,SAAS,CAAC,GAAG,IAAI,CAAC,WAAW,EAAE,OAAO,GAAG,iBAAiB,GAAG,QAAQ,CAAC,EAC7F,MAAM,MAAM,EACZ,MAAM,UAAU,KACd,OAAO,CAAC,IAAI,CAWd,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,gBAAgB,GAC5B,SAAS,IAAI,CAAC,OAAO,EAAE,SAAS,CAAC,GAAG,IAAI,CAAC,UAAU,EAAE,MAAM,GAAG,gBAAgB,CAAC,GAAG,OAAO,EACzF,MAAM,MAAM,KACV,OAAO,CAAC,UAAU,GAAG,IAAI,CAwB3B,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,iBAAiB,GAAU,SAAS,WAAW,EAAE,KAAK,MAAM,KAAG,OAAO,CAAC,OAAO,CAG1F,CAAC;AAEF;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,mBAAmB,GAC/B,MAAM,SAAS,EACf,MAAM,MAAM,EACZ,aAAkB,EAClB,mBAAiB,KACf,OAAO,CAAC,OAAO,CAYjB,CAAC;AAEF;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAChC,oCAAoC;IACpC,OAAO,EAAE,OAAO,CAAC;IACjB,yCAAyC;IACzC,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,qDAAqD;IACrD,OAAO,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;;;;GASG;AACH,eAAO,MAAM,WAAW,GACvB,SAAS,IAAI,CAAC,OAAO,EAAE,SAAS,CAAC,GAChC,IAAI,CAAC,UAAU,EAAE,MAAM,GAAG,gBAAgB,CAAC,GAC3C,YAAY,GACZ,WAAW,GACX,OAAO,EACR,MAAM,MAAM,KACV,OAAO,CAAC,gBAAgB,CA2C1B,CAAC"}
+{"version":3,"file":"daemon.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/cli/daemon.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAC,CAAC,EAAC,MAAM,KAAK,CAAC;AAEtB,OAAO,EACN,KAAK,WAAW,EAChB,KAAK,OAAO,EACZ,KAAK,SAAS,EACd,KAAK,UAAU,EACf,KAAK,YAAY,EACjB,KAAK,WAAW,EAChB,KAAK,OAAO,EACZ,MAAM,oBAAoB,CAAC;AAI5B;;GAEG;AACH,eAAO,MAAM,UAAU;IACtB,sBAAsB;;IAEtB,yBAAyB;;IAEzB,uCAAuC;;IAEvC,yCAAyC;;IAEzC,0CAA0C;;kBAEzC,CAAC;AACH,MAAM,MAAM,UAAU,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,UAAU,CAAC,CAAC;AAEpD;;;;;;GAMG;AACH,eAAO,MAAM,oBAAoB,GAChC,SAAS,IAAI,CAAC,OAAO,EAAE,SAAS,CAAC,EACjC,MAAM,MAAM,KACV,MAAM,GAAG,IAGX,CAAC;AAEF;;;;;;;;GAQG;AACH,eAAO,MAAM,iBAAiB,GAC7B,SAAS,IAAI,CAAC,OAAO,EAAE,SAAS,CAAC,GAAG,IAAI,CAAC,WAAW,EAAE,OAAO,GAAG,iBAAiB,GAAG,QAAQ,CAAC,EAC7F,MAAM,MAAM,EACZ,MAAM,UAAU,KACd,OAAO,CAAC,IAAI,CAWd,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,gBAAgB,GAC5B,SAAS,IAAI,CAAC,OAAO,EAAE,SAAS,CAAC,GAAG,IAAI,CAAC,UAAU,EAAE,MAAM,GAAG,gBAAgB,CAAC,GAAG,OAAO,EACzF,MAAM,MAAM,KACV,OAAO,CAAC,UAAU,GAAG,IAAI,CAwB3B,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,iBAAiB,GAAU,SAAS,WAAW,EAAE,KAAK,MAAM,KAAG,OAAO,CAAC,OAAO,CAG1F,CAAC;AAEF;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,mBAAmB,GAC/B,MAAM,SAAS,EACf,MAAM,MAAM,EACZ,aAAkB,EAClB,mBAAiB,KACf,OAAO,CAAC,OAAO,CAYjB,CAAC;AAEF;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAChC,oCAAoC;IACpC,OAAO,EAAE,OAAO,CAAC;IACjB,yCAAyC;IACzC,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,qDAAqD;IACrD,OAAO,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,WAAW,GACvB,SAAS,IAAI,CAAC,OAAO,EAAE,SAAS,CAAC,GAChC,IAAI,CAAC,UAAU,EAAE,MAAM,GAAG,gBAAgB,CAAC,GAC3C,YAAY,GACZ,WAAW,GACX,OAAO,EACR,MAAM,MAAM,KACV,OAAO,CAAC,gBAAgB,CA2C1B,CAAC"}

package/dist/cli/daemon.js

@@ -43,6 +43,8 @@ export const get_daemon_info_path = (runtime, name) => {
  * @param runtime - runtime with file write and env capabilities
  * @param name - application name
  * @param info - daemon info to write
+ * @mutates filesystem - creates `~/.{name}/run/` and atomically writes `daemon.json`
+ * @throws Error if `$HOME` is not set, or if directory creation / atomic write fails
  */
 export const write_daemon_info = async (runtime, name, info) => {
     const app_dir = get_app_dir(runtime, name);
@@ -126,11 +128,14 @@ export const check_daemon_health = async (deps, port, host = 'localhost', timeou
  * Stop a running daemon by sending SIGTERM and cleaning up the PID file.
  *
  * Returns a result object instead of logging directly, separating
- * lifecycle from presentation.
+ * lifecycle from presentation. Errors removing the PID file are swallowed
+ * (the daemon's own shutdown handler may have removed it concurrently).
  *
  * @param runtime - runtime with command, file, and env capabilities
  * @param name - application name
  * @returns result describing the outcome
+ * @mutates filesystem - removes `~/.{name}/run/daemon.json` on success or when corrupt
+ * @mutates external process - sends `SIGTERM` to the daemon process via `kill`
  */
 export const stop_daemon = async (runtime, name) => {
     const daemon_path = get_daemon_info_path(runtime, name);

package/dist/cli/util.d.ts

@@ -1,7 +1,7 @@
 /**
  * CLI utilities for colors, confirmation, and command delegation.
  *
- * For structured CLI logging, see `create_cli_logger` in `logger.ts`.
+ * For structured CLI logging, see `create_cli_logger` in `cli/logger.ts`.
  *
  * @module
  */

package/dist/cli/util.js

@@ -1,7 +1,7 @@
 /**
  * CLI utilities for colors, confirmation, and command delegation.
  *
- * For structured CLI logging, see `create_cli_logger` in `logger.ts`.
+ * For structured CLI logging, see `create_cli_logger` in `cli/logger.ts`.
  *
  * @module
  */

package/dist/db/assert_row.d.ts

@@ -12,7 +12,8 @@
  *
  * @param row - the row from `query_one` (`T | undefined`) or `rows[0]` (`T | undefined`)
  * @param context - optional context for the error message (e.g. table or operation name)
- * @returns the row, guaranteed non-undefined
+ * @returns the row, guaranteed non-`undefined`
+ * @throws Error if `row` is `undefined`
  */
 export declare const assert_row: <T>(row: T | undefined, context?: string) => T;
 //# sourceMappingURL=assert_row.d.ts.map

package/dist/db/assert_row.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"assert_row.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/db/assert_row.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH;;;;;;;;;;GAUG;AACH,eAAO,MAAM,UAAU,GAAI,CAAC,EAAE,KAAK,CAAC,GAAG,SAAS,EAAE,UAAU,MAAM,KAAG,CASpE,CAAC"}
+{"version":3,"file":"assert_row.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/db/assert_row.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,UAAU,GAAI,CAAC,EAAE,KAAK,CAAC,GAAG,SAAS,EAAE,UAAU,MAAM,KAAG,CASpE,CAAC"}

package/dist/db/assert_row.js

@@ -12,7 +12,8 @@
  *
  * @param row - the row from `query_one` (`T | undefined`) or `rows[0]` (`T | undefined`)
  * @param context - optional context for the error message (e.g. table or operation name)
- * @returns the row, guaranteed non-undefined
+ * @returns the row, guaranteed non-`undefined`
+ * @throws Error if `row` is `undefined`
  */
 export const assert_row = (row, context) => {
     if (row === undefined) {

package/dist/db/create_db.d.ts

@@ -8,7 +8,7 @@
  *
  * Both `pg` and `@electric-sql/pglite` are optional peer dependencies,
  * dynamically imported only when needed. For direct driver construction
- * without auto-detection, use `db_pg.ts` or `db_pglite.ts`.
+ * without auto-detection, use `db/db_pg.ts` or `db/db_pglite.ts`.
  *
  * @module
  */
@@ -29,10 +29,13 @@ export interface CreateDbResult {
  * know which driver is in use.
  *
  * For direct driver construction without URL routing, import
- * `create_pg_db` from `db_pg.ts` or `create_pglite_db` from `db_pglite.ts`.
+ * `create_pg_db` from `db/db_pg.ts` or `create_pglite_db` from `db/db_pglite.ts`.
  *
  * @param database_url - connection URL (`postgres://`, `postgresql://`, `file://`, or `memory://`)
  * @returns database instance, close callback, type, and display name
+ * @throws Error if `database_url` uses an unsupported scheme. Driver
+ *   construction (`pg.Pool` or `PGlite`) may also throw on bad connection
+ *   parameters or missing peer-dependency packages.
  */
 export declare const create_db: (database_url: string) => Promise<CreateDbResult>;
 //# sourceMappingURL=create_db.d.ts.map

package/dist/db/create_db.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"create_db.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/db/create_db.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EAAC,EAAE,EAAE,MAAM,EAAC,MAAM,SAAS,CAAC;AAIxC,yCAAyC;AACzC,MAAM,WAAW,cAAc;IAC9B,EAAE,EAAE,EAAE,CAAC;IACP,iFAAiF;IACjF,KAAK,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IAC3B,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,SAAS,GAAU,cAAc,MAAM,KAAG,OAAO,CAAC,cAAc,CAgC5E,CAAC"}
+{"version":3,"file":"create_db.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/db/create_db.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EAAC,EAAE,EAAE,MAAM,EAAC,MAAM,SAAS,CAAC;AAIxC,yCAAyC;AACzC,MAAM,WAAW,cAAc;IAC9B,EAAE,EAAE,EAAE,CAAC;IACP,iFAAiF;IACjF,KAAK,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IAC3B,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,SAAS,GAAU,cAAc,MAAM,KAAG,OAAO,CAAC,cAAc,CAgC5E,CAAC"}

package/dist/db/create_db.js

@@ -8,7 +8,7 @@
  *
  * Both `pg` and `@electric-sql/pglite` are optional peer dependencies,
  * dynamically imported only when needed. For direct driver construction
- * without auto-detection, use `db_pg.ts` or `db_pglite.ts`.
+ * without auto-detection, use `db/db_pg.ts` or `db/db_pglite.ts`.
  *
  * @module
  */
@@ -22,10 +22,13 @@ import { create_pglite_db } from './db_pglite.js';
  * know which driver is in use.
  *
  * For direct driver construction without URL routing, import
- * `create_pg_db` from `db_pg.ts` or `create_pglite_db` from `db_pglite.ts`.
+ * `create_pg_db` from `db/db_pg.ts` or `create_pglite_db` from `db/db_pglite.ts`.
  *
  * @param database_url - connection URL (`postgres://`, `postgresql://`, `file://`, or `memory://`)
  * @returns database instance, close callback, type, and display name
+ * @throws Error if `database_url` uses an unsupported scheme. Driver
+ *   construction (`pg.Pool` or `PGlite`) may also throw on bad connection
+ *   parameters or missing peer-dependency packages.
  */
 export const create_db = async (database_url) => {
     if (database_url.startsWith('postgres://') || database_url.startsWith('postgresql://')) {

package/dist/db/db.d.ts

@@ -5,8 +5,8 @@
  * Both `pg.Pool` and `@electric-sql/pglite` satisfy this interface.
  *
  * Transaction safety is provided by an injected `transaction` callback —
- * the driver adapters (`db_pg.ts`, `db_pglite.ts`) supply the driver-appropriate
- * implementation. Close is handled externally (returned alongside the Db
+ * the driver adapters (`db/db_pg.ts`, `db/db_pglite.ts`) supply the driver-appropriate
+ * implementation. Close is handled externally (returned alongside the `Db`
  * as `DbDriverResult`), not as a method on this class.
  *
  * @module
@@ -23,7 +23,7 @@ export interface DbClient {
  * Configuration for constructing a `Db` with transaction support.
  *
  * `transaction` is injected by `create_db` which knows the driver.
- * For pg: acquires a dedicated pool client per transaction.
+ * For `pg`: acquires a dedicated pool client per transaction.
  * For PGlite: delegates to `pglite.transaction()`.
  */
 export interface DbDeps {
@@ -47,16 +47,17 @@ export type DbType = 'postgres' | 'pglite-file' | 'pglite-memory';
 /**
  * Sentinel transaction function for transaction-scoped `Db` instances.
  *
- * Throws immediately — nested transactions are not supported.
  * Used by driver adapters when constructing the inner `Db` passed
  * to transaction callbacks.
+ *
+ * @throws Error always — nested transactions are not supported
  */
 export declare const no_nested_transaction: DbDeps['transaction'];
 /**
  * Database wrapper providing a consistent query and transaction interface.
  *
- * Construct via `create_pg_db()` from `db_pg.ts` or `create_pglite_db()` from
- * `db_pglite.ts` for proper transaction support, or via `create_db()` for
+ * Construct via `create_pg_db()` from `db/db_pg.ts` or `create_pglite_db()` from
+ * `db/db_pglite.ts` for proper transaction support, or via `create_db()` for
  * URL-based auto-detection.
  *
  * @example
@@ -76,10 +77,22 @@ export declare class Db {
     constructor(options: DbDeps);
     /**
      * Execute a query and return all rows.
+     *
+     * @param text - SQL text with `$1`, `$2`, ... parameter placeholders
+     * @param values - parameter values bound to the placeholders in `text`
+     * @returns the result rows, typed as `T`
+     * @throws Error propagated from the underlying driver on syntax errors,
+     *   constraint violations, or connection failures
      */
     query<T>(text: string, values?: Array<unknown>): Promise<Array<T>>;
     /**
-     * Execute a query and return the first row, or undefined if no rows.
+     * Execute a query and return the first row, or `undefined` if no rows.
+     *
+     * @param text - SQL text with `$1`, `$2`, ... parameter placeholders
+     * @param values - parameter values bound to the placeholders in `text`
+     * @returns the first row, or `undefined` when the result set is empty
+     * @throws Error propagated from the underlying driver on syntax errors,
+     *   constraint violations, or connection failures
      */
     query_one<T>(text: string, values?: Array<unknown>): Promise<T | undefined>;
     /**
@@ -91,6 +104,8 @@ export declare class Db {
      *
      * @param fn - async function receiving a transaction-scoped `Db`
      * @returns the value returned by `fn`
+     * @throws Error propagated from `fn` after `ROLLBACK`, or from the driver
+     *   if `BEGIN` / `COMMIT` / `ROLLBACK` itself fails
      */
     transaction<T>(fn: (tx_db: Db) => Promise<T>): Promise<T>;
 }

package/dist/db/db.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"db.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/db/db.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH;;GAEG;AACH,MAAM,WAAW,QAAQ;IACxB,KAAK,EAAE,CAAC,CAAC,GAAG,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,KAAK,CAAC,OAAO,CAAC,KAAK,OAAO,CAAC;QAAC,IAAI,EAAE,KAAK,CAAC,CAAC,CAAC,CAAA;KAAC,CAAC,CAAC;CACzF;AAED;;;;;;GAMG;AACH,MAAM,WAAW,MAAM;IACtB,MAAM,EAAE,QAAQ,CAAC;IACjB,WAAW,EAAE,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,KAAK,EAAE,EAAE,KAAK,OAAO,CAAC,CAAC,CAAC,KAAK,OAAO,CAAC,CAAC,CAAC,CAAC;CAC9D;AAED;;;;;;GAMG;AACH,MAAM,WAAW,cAAc;IAC9B,EAAE,EAAE,EAAE,CAAC;IACP,iFAAiF;IACjF,KAAK,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;CAC3B;AAED,4BAA4B;AAC5B,MAAM,MAAM,MAAM,GAAG,UAAU,GAAG,aAAa,GAAG,eAAe,CAAC;AAElE;;;;;;GAMG;AACH,eAAO,MAAM,qBAAqB,EAAE,MAAM,CAAC,aAAa,CAEvD,CAAC;AAEF;;;;;;;;;;;;;;;;;GAiBG;AACH,qBAAa,EAAE;;IACd,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC;gBAId,OAAO,EAAE,MAAM;IAK3B;;OAEG;IACG,KAAK,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,KAAK,CAAC,OAAO,CAAC,GAAG,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;IAKxE;;OAEG;IACG,SAAS,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,KAAK,CAAC,OAAO,CAAC,GAAG,OAAO,CAAC,CAAC,GAAG,SAAS,CAAC;IAKjF;;;;;;;;;OASG;IACG,WAAW,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,KAAK,EAAE,EAAE,KAAK,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC;CAG/D"}
+{"version":3,"file":"db.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/db/db.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH;;GAEG;AACH,MAAM,WAAW,QAAQ;IACxB,KAAK,EAAE,CAAC,CAAC,GAAG,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,KAAK,CAAC,OAAO,CAAC,KAAK,OAAO,CAAC;QAAC,IAAI,EAAE,KAAK,CAAC,CAAC,CAAC,CAAA;KAAC,CAAC,CAAC;CACzF;AAED;;;;;;GAMG;AACH,MAAM,WAAW,MAAM;IACtB,MAAM,EAAE,QAAQ,CAAC;IACjB,WAAW,EAAE,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,KAAK,EAAE,EAAE,KAAK,OAAO,CAAC,CAAC,CAAC,KAAK,OAAO,CAAC,CAAC,CAAC,CAAC;CAC9D;AAED;;;;;;GAMG;AACH,MAAM,WAAW,cAAc;IAC9B,EAAE,EAAE,EAAE,CAAC;IACP,iFAAiF;IACjF,KAAK,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;CAC3B;AAED,4BAA4B;AAC5B,MAAM,MAAM,MAAM,GAAG,UAAU,GAAG,aAAa,GAAG,eAAe,CAAC;AAElE;;;;;;;GAOG;AACH,eAAO,MAAM,qBAAqB,EAAE,MAAM,CAAC,aAAa,CAEvD,CAAC;AAEF;;;;;;;;;;;;;;;;;GAiBG;AACH,qBAAa,EAAE;;IACd,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC;gBAId,OAAO,EAAE,MAAM;IAK3B;;;;;;;;OAQG;IACG,KAAK,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,KAAK,CAAC,OAAO,CAAC,GAAG,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;IAKxE;;;;;;;;OAQG;IACG,SAAS,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,KAAK,CAAC,OAAO,CAAC,GAAG,OAAO,CAAC,CAAC,GAAG,SAAS,CAAC;IAKjF;;;;;;;;;;;OAWG;IACG,WAAW,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,KAAK,EAAE,EAAE,KAAK,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC;CAG/D"}

package/dist/db/db.js

@@ -5,8 +5,8 @@
  * Both `pg.Pool` and `@electric-sql/pglite` satisfy this interface.
  *
  * Transaction safety is provided by an injected `transaction` callback —
- * the driver adapters (`db_pg.ts`, `db_pglite.ts`) supply the driver-appropriate
- * implementation. Close is handled externally (returned alongside the Db
+ * the driver adapters (`db/db_pg.ts`, `db/db_pglite.ts`) supply the driver-appropriate
+ * implementation. Close is handled externally (returned alongside the `Db`
  * as `DbDriverResult`), not as a method on this class.
  *
  * @module
@@ -14,9 +14,10 @@
 /**
  * Sentinel transaction function for transaction-scoped `Db` instances.
  *
- * Throws immediately — nested transactions are not supported.
  * Used by driver adapters when constructing the inner `Db` passed
  * to transaction callbacks.
+ *
+ * @throws Error always — nested transactions are not supported
  */
 export const no_nested_transaction = () => {
     throw new Error('Nested transactions are not supported');
@@ -24,8 +25,8 @@ export const no_nested_transaction = () => {
 /**
  * Database wrapper providing a consistent query and transaction interface.
  *
- * Construct via `create_pg_db()` from `db_pg.ts` or `create_pglite_db()` from
- * `db_pglite.ts` for proper transaction support, or via `create_db()` for
+ * Construct via `create_pg_db()` from `db/db_pg.ts` or `create_pglite_db()` from
+ * `db/db_pglite.ts` for proper transaction support, or via `create_db()` for
  * URL-based auto-detection.
  *
  * @example
@@ -48,13 +49,25 @@ export class Db {
     }
     /**
      * Execute a query and return all rows.
+     *
+     * @param text - SQL text with `$1`, `$2`, ... parameter placeholders
+     * @param values - parameter values bound to the placeholders in `text`
+     * @returns the result rows, typed as `T`
+     * @throws Error propagated from the underlying driver on syntax errors,
+     *   constraint violations, or connection failures
      */
     async query(text, values) {
         const result = await this.client.query(text, values);
         return result.rows;
     }
     /**
-     * Execute a query and return the first row, or undefined if no rows.
+     * Execute a query and return the first row, or `undefined` if no rows.
+     *
+     * @param text - SQL text with `$1`, `$2`, ... parameter placeholders
+     * @param values - parameter values bound to the placeholders in `text`
+     * @returns the first row, or `undefined` when the result set is empty
+     * @throws Error propagated from the underlying driver on syntax errors,
+     *   constraint violations, or connection failures
      */
     async query_one(text, values) {
         const rows = await this.query(text, values);
@@ -69,6 +82,8 @@ export class Db {
      *
      * @param fn - async function receiving a transaction-scoped `Db`
      * @returns the value returned by `fn`
+     * @throws Error propagated from `fn` after `ROLLBACK`, or from the driver
+     *   if `BEGIN` / `COMMIT` / `ROLLBACK` itself fails
      */
     async transaction(fn) {
         return this.#transaction(fn);

package/dist/db/db_pg.d.ts

@@ -10,12 +10,13 @@
 import type { Pool } from 'pg';
 import { type DbDriverResult } from './db.js';
 /**
- * Create a `Db` backed by a pg `Pool`.
+ * Create a `Db` backed by a `pg.Pool`.
  *
  * Owns the transaction implementation (acquires a dedicated pool client
  * per transaction) and returns a `close` callback bound to `pool.end()`.
  *
  * @param pool - an already-constructed `pg.Pool`
+ * @returns the `Db` instance and a `close` callback bound to `pool.end()`
  */
 export declare const create_pg_db: (pool: Pool) => DbDriverResult;
 //# sourceMappingURL=db_pg.d.ts.map

package/dist/db/db_pg.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"db_pg.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/db/db_pg.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAC,IAAI,EAAC,MAAM,IAAI,CAAC;AAE7B,OAAO,EAA4B,KAAK,cAAc,EAAC,MAAM,SAAS,CAAC;AA0BvE;;;;;;;GAOG;AACH,eAAO,MAAM,YAAY,GAAI,MAAM,IAAI,KAAG,cAGxC,CAAC"}
+{"version":3,"file":"db_pg.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/db/db_pg.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAC,IAAI,EAAC,MAAM,IAAI,CAAC;AAE7B,OAAO,EAA4B,KAAK,cAAc,EAAC,MAAM,SAAS,CAAC;AA2BvE;;;;;;;;GAQG;AACH,eAAO,MAAM,YAAY,GAAI,MAAM,IAAI,KAAG,cAGxC,CAAC"}

package/dist/db/db_pg.js

@@ -9,10 +9,11 @@
  */
 import { Db, no_nested_transaction } from './db.js';
 /**
- * Create a transaction implementation for a pg Pool.
+ * Create a transaction implementation for a `pg.Pool`.
  *
  * Acquires a dedicated client from the pool for each transaction,
- * ensuring BEGIN/COMMIT/ROLLBACK all hit the same connection.
+ * ensuring `BEGIN` / `COMMIT` / `ROLLBACK` all hit the same connection.
+ * Releases the client in `finally` regardless of outcome.
  */
 const create_pg_transaction = (pool) => async (fn) => {
     const client = await pool.connect();
@@ -32,12 +33,13 @@ const create_pg_transaction = (pool) => async (fn) => {
     }
 };
 /**
- * Create a `Db` backed by a pg `Pool`.
+ * Create a `Db` backed by a `pg.Pool`.
  *
  * Owns the transaction implementation (acquires a dedicated pool client
  * per transaction) and returns a `close` callback bound to `pool.end()`.
  *
  * @param pool - an already-constructed `pg.Pool`
+ * @returns the `Db` instance and a `close` callback bound to `pool.end()`
  */
 export const create_pg_db = (pool) => ({
     db: new Db({ client: pool, transaction: create_pg_transaction(pool) }),

package/dist/db/db_pglite.d.ts

@@ -10,12 +10,13 @@
 import type { PGlite } from '@electric-sql/pglite';
 import { type DbDriverResult } from './db.js';
 /**
- * Create a `Db` backed by a PGlite instance.
+ * Create a `Db` backed by a `PGlite` instance.
  *
  * Delegates transactions to PGlite's native `transaction()` method
  * and returns a `close` callback bound to `pglite.close()`.
  *
- * @param pglite - an already-constructed PGlite instance
+ * @param pglite - an already-constructed `PGlite` instance
+ * @returns the `Db` instance and a `close` callback bound to `pglite.close()`
  */
 export declare const create_pglite_db: (pglite: PGlite) => DbDriverResult;
 //# sourceMappingURL=db_pglite.d.ts.map

package/dist/db/db_pglite.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"db_pglite.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/db/db_pglite.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAC,MAAM,EAAC,MAAM,sBAAsB,CAAC;AAEjD,OAAO,EAA4B,KAAK,cAAc,EAAC,MAAM,SAAS,CAAC;AAYvE;;;;;;;GAOG;AACH,eAAO,MAAM,gBAAgB,GAAI,QAAQ,MAAM,KAAG,cAGhD,CAAC"}
+{"version":3,"file":"db_pglite.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/db/db_pglite.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAC,MAAM,EAAC,MAAM,sBAAsB,CAAC;AAEjD,OAAO,EAA4B,KAAK,cAAc,EAAC,MAAM,SAAS,CAAC;AAYvE;;;;;;;;GAQG;AACH,eAAO,MAAM,gBAAgB,GAAI,QAAQ,MAAM,KAAG,cAGhD,CAAC"}

package/dist/db/db_pglite.js

@@ -15,12 +15,13 @@ import { Db, no_nested_transaction } from './db.js';
  */
 const create_pglite_transaction = (pglite) => async (fn) => pglite.transaction(async (tx) => fn(new Db({ client: tx, transaction: no_nested_transaction })));
 /**
- * Create a `Db` backed by a PGlite instance.
+ * Create a `Db` backed by a `PGlite` instance.
  *
  * Delegates transactions to PGlite's native `transaction()` method
  * and returns a `close` callback bound to `pglite.close()`.
  *
- * @param pglite - an already-constructed PGlite instance
+ * @param pglite - an already-constructed `PGlite` instance
+ * @returns the `Db` instance and a `close` callback bound to `pglite.close()`
  */
 export const create_pglite_db = (pglite) => ({
     db: new Db({ client: pglite, transaction: create_pglite_transaction(pglite) }),

package/dist/db/migrate.d.ts

@@ -66,13 +66,13 @@ export interface MigrationResult {
     applied_names: Array<string>;
 }
 /**
- * Tagged error vocabulary for {@link run_migrations} and {@link baseline}.
+ * Tagged error vocabulary for `run_migrations` and `baseline`.
  *
  * Callers branch on `.kind` rather than matching error messages — message
  * text is for operators, not control flow.
  */
 export type MigrationErrorKind = 'binary-older-than-db' | 'name-divergence-at-N' | 'old-tracker-shape' | 'migration-failed' | 'baseline-name-not-in-code' | 'baseline-name-out-of-order' | 'baseline-namespace-already-populated';
-/** Structured context passed alongside a {@link MigrationError}. */
+/** Structured context passed alongside a `MigrationError`. */
 export interface MigrationErrorContext {
     namespace?: string;
     at_index?: number;
@@ -80,7 +80,7 @@ export interface MigrationErrorContext {
     cause?: unknown;
 }
 /**
- * Tagged error thrown by {@link run_migrations} and {@link baseline}.
+ * Tagged error thrown by `run_migrations` and `baseline`.
  *
  * Branch on `.kind`; the message carries an operator-facing remediation hint.
  */
@@ -111,7 +111,7 @@ export declare class MigrationError extends Error {
  *
  * **Concurrency**: per-namespace advisory locks reduce contention in
  * multi-instance deployments but are best-effort on pool drivers (see
- * module docstring §Advisory locking). Correctness on concurrent boots
+ * the module docstring's "Advisory locking" notes). Correctness on concurrent boots
  * falls out of chain-tx atomicity + the `(namespace, name)` PK — the
  * loser's INSERT triggers PK violation and rollback; subsequent boots
  * see the committed state.
@@ -120,6 +120,8 @@ export declare class MigrationError extends Error {
  * @param namespaces - migration namespaces, processed in the order passed
  * @returns one result per namespace where work happened (already-up-to-date
  *   namespaces are omitted)
+ * @mutates schema_version - inserts one row per applied migration
+ * @mutates db - applies pending migrations' DDL/DML to the schema
  * @throws MigrationError with `kind` of `binary-older-than-db`,
  *   `name-divergence-at-N`, `old-tracker-shape`, or `migration-failed`
  */
@@ -154,6 +156,8 @@ export declare const run_migrations: (db: Db, namespaces: Array<MigrationNamespa
  * @param db - the database instance
  * @param ns - the namespace whose migrations are being baselined
  * @param names - prefix of `ns.migrations[].name` to record as already-applied
+ * @mutates schema_version - inserts tracker rows for `names` without running
+ *   the corresponding migration bodies
  * @throws MigrationError with `kind` of `old-tracker-shape`,
  *   `baseline-name-not-in-code`, `baseline-name-out-of-order`, or
  *   `baseline-namespace-already-populated`

package/dist/db/migrate.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"migrate.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/db/migrate.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AAEH,OAAO,KAAK,EAAC,EAAE,EAAC,MAAM,SAAS,CAAC;AAEhC;;;;GAIG;AACH,MAAM,WAAW,SAAS;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,EAAE,CAAC,EAAE,EAAE,EAAE,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CAC9B;AAED;;;;GAIG;AACH,MAAM,WAAW,kBAAkB;IAClC,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,KAAK,CAAC,SAAS,CAAC,CAAC;CAC7B;AAED,2DAA2D;AAC3D,MAAM,WAAW,eAAe;IAC/B,SAAS,EAAE,MAAM,CAAC;IAClB,+EAA+E;IAC/E,aAAa,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;CAC7B;AAED;;;;;GAKG;AACH,MAAM,MAAM,kBAAkB,GAC3B,sBAAsB,GACtB,sBAAsB,GACtB,mBAAmB,GACnB,kBAAkB,GAClB,2BAA2B,GAC3B,4BAA4B,GAC5B,sCAAsC,CAAC;AAE1C,oEAAoE;AACpE,MAAM,WAAW,qBAAqB;IACrC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,aAAa,CAAC,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;IACtC,KAAK,CAAC,EAAE,OAAO,CAAC;CAChB;AAED;;;;GAIG;AACH,qBAAa,cAAe,SAAQ,KAAK;IACxC,QAAQ,CAAC,IAAI,EAAE,kBAAkB,CAAC;IAClC,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,aAAa,CAAC,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;gBAEnC,IAAI,EAAE,kBAAkB,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,qBAAqB;CAQtF;AA6ED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,eAAO,MAAM,cAAc,GAC1B,IAAI,EAAE,EACN,YAAY,KAAK,CAAC,kBAAkB,CAAC,KACnC,OAAO,CAAC,KAAK,CAAC,eAAe,CAAC,CAuFhC,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,eAAO,MAAM,QAAQ,GACpB,IAAI,EAAE,EACN,IAAI,kBAAkB,EACtB,OAAO,aAAa,CAAC,MAAM,CAAC,KAC1B,OAAO,CAAC,IAAI,CA+Dd,CAAC"}
+{"version":3,"file":"migrate.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/db/migrate.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AAEH,OAAO,KAAK,EAAC,EAAE,EAAC,MAAM,SAAS,CAAC;AAEhC;;;;GAIG;AACH,MAAM,WAAW,SAAS;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,EAAE,CAAC,EAAE,EAAE,EAAE,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CAC9B;AAED;;;;GAIG;AACH,MAAM,WAAW,kBAAkB;IAClC,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,KAAK,CAAC,SAAS,CAAC,CAAC;CAC7B;AAED,2DAA2D;AAC3D,MAAM,WAAW,eAAe;IAC/B,SAAS,EAAE,MAAM,CAAC;IAClB,+EAA+E;IAC/E,aAAa,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;CAC7B;AAED;;;;;GAKG;AACH,MAAM,MAAM,kBAAkB,GAC3B,sBAAsB,GACtB,sBAAsB,GACtB,mBAAmB,GACnB,kBAAkB,GAClB,2BAA2B,GAC3B,4BAA4B,GAC5B,sCAAsC,CAAC;AAE1C,8DAA8D;AAC9D,MAAM,WAAW,qBAAqB;IACrC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,aAAa,CAAC,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;IACtC,KAAK,CAAC,EAAE,OAAO,CAAC;CAChB;AAED;;;;GAIG;AACH,qBAAa,cAAe,SAAQ,KAAK;IACxC,QAAQ,CAAC,IAAI,EAAE,kBAAkB,CAAC;IAClC,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,aAAa,CAAC,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;gBAEnC,IAAI,EAAE,kBAAkB,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,qBAAqB;CAQtF;AA6ED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,eAAO,MAAM,cAAc,GAC1B,IAAI,EAAE,EACN,YAAY,KAAK,CAAC,kBAAkB,CAAC,KACnC,OAAO,CAAC,KAAK,CAAC,eAAe,CAAC,CAuFhC,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,eAAO,MAAM,QAAQ,GACpB,IAAI,EAAE,EACN,IAAI,kBAAkB,EACtB,OAAO,aAAa,CAAC,MAAM,CAAC,KAC1B,OAAO,CAAC,IAAI,CA+Dd,CAAC"}

package/dist/db/migrate.js

@@ -41,7 +41,7 @@
  * @module
  */
 /**
- * Tagged error thrown by {@link run_migrations} and {@link baseline}.
+ * Tagged error thrown by `run_migrations` and `baseline`.
  *
  * Branch on `.kind`; the message carries an operator-facing remediation hint.
  */
@@ -145,7 +145,7 @@ const with_namespace_lock = async (db, namespace, fn) => {
  *
  * **Concurrency**: per-namespace advisory locks reduce contention in
  * multi-instance deployments but are best-effort on pool drivers (see
- * module docstring §Advisory locking). Correctness on concurrent boots
+ * the module docstring's "Advisory locking" notes). Correctness on concurrent boots
  * falls out of chain-tx atomicity + the `(namespace, name)` PK — the
  * loser's INSERT triggers PK violation and rollback; subsequent boots
  * see the committed state.
@@ -154,6 +154,8 @@ const with_namespace_lock = async (db, namespace, fn) => {
  * @param namespaces - migration namespaces, processed in the order passed
  * @returns one result per namespace where work happened (already-up-to-date
  *   namespaces are omitted)
+ * @mutates schema_version - inserts one row per applied migration
+ * @mutates db - applies pending migrations' DDL/DML to the schema
  * @throws MigrationError with `kind` of `binary-older-than-db`,
  *   `name-divergence-at-N`, `old-tracker-shape`, or `migration-failed`
  */
@@ -250,6 +252,8 @@ export const run_migrations = async (db, namespaces) => {
  * @param db - the database instance
  * @param ns - the namespace whose migrations are being baselined
  * @param names - prefix of `ns.migrations[].name` to record as already-applied
+ * @mutates schema_version - inserts tracker rows for `names` without running
+ *   the corresponding migration bodies
  * @throws MigrationError with `kind` of `old-tracker-shape`,
  *   `baseline-name-not-in-code`, `baseline-name-out-of-order`, or
  *   `baseline-namespace-already-populated`

package/dist/db/sql_identifier.d.ts

@@ -21,7 +21,8 @@ export declare const VALID_SQL_IDENTIFIER: RegExp;
  *
  * @param name - the identifier to validate
  * @returns the validated identifier
- * @throws if the identifier contains invalid characters
+ * @throws Error if the identifier contains characters outside `[a-zA-Z0-9_]`
+ *   or starts with a digit
  */
 export declare const assert_valid_sql_identifier: (name: string) => string;
 //# sourceMappingURL=sql_identifier.d.ts.map

package/dist/db/sql_identifier.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"sql_identifier.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/db/sql_identifier.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH;;;GAGG;AACH,eAAO,MAAM,oBAAoB,QAA6B,CAAC;AAE/D;;;;;;;;;GASG;AACH,eAAO,MAAM,2BAA2B,GAAI,MAAM,MAAM,KAAG,MAK1D,CAAC"}
+{"version":3,"file":"sql_identifier.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/db/sql_identifier.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH;;;GAGG;AACH,eAAO,MAAM,oBAAoB,QAA6B,CAAC;AAE/D;;;;;;;;;;GAUG;AACH,eAAO,MAAM,2BAA2B,GAAI,MAAM,MAAM,KAAG,MAK1D,CAAC"}

package/dist/db/sql_identifier.js

@@ -21,7 +21,8 @@ export const VALID_SQL_IDENTIFIER = /^[a-zA-Z_][a-zA-Z0-9_]*$/;
  *
  * @param name - the identifier to validate
  * @returns the validated identifier
- * @throws if the identifier contains invalid characters
+ * @throws Error if the identifier contains characters outside `[a-zA-Z0-9_]`
+ *   or starts with a digit
  */
 export const assert_valid_sql_identifier = (name) => {
     if (!VALID_SQL_IDENTIFIER.test(name)) {

package/dist/db/status.d.ts

@@ -55,7 +55,10 @@ export interface DbStatus {
  *
  * @param db - the database instance
  * @param namespaces - migration namespaces to check status for
- * @returns a snapshot of database status
+ * @returns a snapshot of database status; `connected: false` with `error`
+ *   set when the initial connectivity probe fails
+ * @throws Error propagated from the driver if a query fails after the
+ *   connectivity probe (e.g. a table is dropped mid-scan)
  */
 export declare const query_db_status: (db: Db, namespaces?: Array<MigrationNamespace>) => Promise<DbStatus>;
 /**

package/dist/db/status.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"status.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/db/status.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAC,EAAE,EAAC,MAAM,SAAS,CAAC;AAChC,OAAO,KAAK,EAAC,kBAAkB,EAAC,MAAM,cAAc,CAAC;AAErD;;GAEG;AACH,MAAM,WAAW,eAAe;IAC/B,SAAS,EAAE,MAAM,CAAC;IAClB,uEAAuE;IACvE,aAAa,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;IAC7B,2EAA2E;IAC3E,aAAa,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;IAC7B,wEAAwE;IACxE,UAAU,EAAE,OAAO,CAAC;CACpB;AAED;;GAEG;AACH,MAAM,WAAW,WAAW;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;CAClB;AAED;;GAEG;AACH,MAAM,WAAW,QAAQ;IACxB,yCAAyC;IACzC,SAAS,EAAE,OAAO,CAAC;IACnB,0CAA0C;IAC1C,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,+BAA+B;IAC/B,WAAW,EAAE,MAAM,CAAC;IACpB,4BAA4B;IAC5B,MAAM,EAAE,KAAK,CAAC,WAAW,CAAC,CAAC;IAC3B,sCAAsC;IACtC,UAAU,EAAE,KAAK,CAAC,eAAe,CAAC,CAAC;IACnC;;;;OAIG;IACH,iBAAiB,CAAC,EAAE,OAAO,CAAC;CAC5B;AA8BD;;;;;;;;GAQG;AACH,eAAO,MAAM,eAAe,GAC3B,IAAI,EAAE,EACN,aAAa,KAAK,CAAC,kBAAkB,CAAC,KACpC,OAAO,CAAC,QAAQ,CAoFlB,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,gBAAgB,GAAI,QAAQ,QAAQ,KAAG,MA4CnD,CAAC"}
+{"version":3,"file":"status.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/db/status.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAC,EAAE,EAAC,MAAM,SAAS,CAAC;AAChC,OAAO,KAAK,EAAC,kBAAkB,EAAC,MAAM,cAAc,CAAC;AAErD;;GAEG;AACH,MAAM,WAAW,eAAe;IAC/B,SAAS,EAAE,MAAM,CAAC;IAClB,uEAAuE;IACvE,aAAa,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;IAC7B,2EAA2E;IAC3E,aAAa,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;IAC7B,wEAAwE;IACxE,UAAU,EAAE,OAAO,CAAC;CACpB;AAED;;GAEG;AACH,MAAM,WAAW,WAAW;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;CAClB;AAED;;GAEG;AACH,MAAM,WAAW,QAAQ;IACxB,yCAAyC;IACzC,SAAS,EAAE,OAAO,CAAC;IACnB,0CAA0C;IAC1C,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,+BAA+B;IAC/B,WAAW,EAAE,MAAM,CAAC;IACpB,4BAA4B;IAC5B,MAAM,EAAE,KAAK,CAAC,WAAW,CAAC,CAAC;IAC3B,sCAAsC;IACtC,UAAU,EAAE,KAAK,CAAC,eAAe,CAAC,CAAC;IACnC;;;;OAIG;IACH,iBAAiB,CAAC,EAAE,OAAO,CAAC;CAC5B;AA8BD;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,eAAe,GAC3B,IAAI,EAAE,EACN,aAAa,KAAK,CAAC,kBAAkB,CAAC,KACpC,OAAO,CAAC,QAAQ,CAmFlB,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,gBAAgB,GAAI,QAAQ,QAAQ,KAAG,MA4CnD,CAAC"}

package/dist/db/status.js

@@ -29,7 +29,10 @@ const has_table = async (db, table_name) => {
  *
  * @param db - the database instance
  * @param namespaces - migration namespaces to check status for
- * @returns a snapshot of database status
+ * @returns a snapshot of database status; `connected: false` with `error`
+ *   set when the initial connectivity probe fails
+ * @throws Error propagated from the driver if a query fails after the
+ *   connectivity probe (e.g. a table is dropped mid-scan)
  */
 export const query_db_status = async (db, namespaces) => {
     // check connectivity
@@ -51,7 +54,7 @@ export const query_db_status = async (db, namespaces) => {
 		 ORDER BY table_name`);
     const tables = [];
     for (const { table_name } of table_rows) {
-        // table_name from information_schema is trusted
+        // table_name from information_schema is trusted (no parameterized DDL)
         const result = await db.query_one(`SELECT COUNT(*) as count FROM "${table_name}"`);
         tables.push({
             name: table_name,