@fuzdev/fuz_app 0.51.0 → 0.53.0

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;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,SAAS,GAAU,cAAc,MAAM,KAAG,OAAO,CAAC,cAAc,CAgC5E,CAAC"}

package/dist/db/create_db.js

@@ -17,7 +17,6 @@ import { create_pglite_db } from './db_pglite.js';
 /**
  * Create a database connection based on a URL.
  *
- * Returns the `Db` instance, a typed `close` callback, driver type, and display name.
  * The `close` callback is bound to the actual driver — callers never need to
  * know which driver is in use.
  *
@@ -26,6 +25,9 @@ import { create_pglite_db } from './db_pglite.js';
  *
  * @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

@@ -6,7 +6,7 @@
  *
  * Transaction safety is provided by an injected `transaction` callback —
  * the driver adapters (`db/db_pg.ts`, `db/db_pglite.ts`) supply the driver-appropriate
- * implementation. Close is handled externally (returned alongside the Db
+ * 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,9 +47,10 @@ 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'];
 /**
@@ -76,10 +77,18 @@ 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`
      */
     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
      */
     query_one<T>(text: string, values?: Array<unknown>): Promise<T | undefined>;
     /**
@@ -91,6 +100,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;;;;;;OAMG;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;;;;;;OAMG;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

@@ -6,7 +6,7 @@
  *
  * Transaction safety is provided by an injected `transaction` callback —
  * the driver adapters (`db/db_pg.ts`, `db/db_pglite.ts`) supply the driver-appropriate
- * implementation. Close is handled externally (returned alongside the Db
+ * 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');
@@ -48,13 +49,21 @@ 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`
      */
     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
      */
     async query_one(text, values) {
         const rows = await this.query(text, values);
@@ -69,6 +78,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()`.
+ * Owns the transaction implementation, acquiring a dedicated pool client
+ * per transaction.
  *
  * @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()`.
+ * Owns the transaction implementation, acquiring a dedicated pool client
+ * per transaction.
  *
  * @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,12 @@
 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()`.
+ * Delegates transactions to PGlite's native `transaction()` method.
  *
- * @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.js

@@ -15,12 +15,12 @@ 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()`.
+ * Delegates transactions to PGlite's native `transaction()` method.
  *
- * @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,7 @@ 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
  * @throws MigrationError with `kind` of `binary-older-than-db`,
  *   `name-divergence-at-N`, `old-tracker-shape`, or `migration-failed`
  */
@@ -154,6 +155,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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;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,7 @@ 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
  * @throws MigrationError with `kind` of `binary-older-than-db`,
  *   `name-divergence-at-N`, `old-tracker-shape`, or `migration-failed`
  */
@@ -250,6 +251,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,

package/dist/dev/setup.d.ts

@@ -90,6 +90,7 @@ export declare const parse_db_name: (url: string) => string | null;
  *
  * @param deps - command execution capability
  * @returns a random 32-byte base64-encoded key
+ * @throws Error if `openssl rand` fails or is unavailable
  */
 export declare const generate_random_key: (deps: CommandDeps) => Promise<string>;
 /**
@@ -112,6 +113,7 @@ export declare const read_env_var: (deps: Pick<FsReadDeps, "stat" | "read_text_f
  * @param example_path - path to the example template
  * @param options - extra replacements, permissions, logger
  * @returns result indicating whether the file was created or updated
+ * @mutates filesystem - writes `env_path` (creating from `example_path` if missing) and optionally chmods to `0o600`
  */
 export declare const setup_env_file: (deps: FsReadDeps & FsWriteDeps & CommandDeps, env_path: string, example_path: string, options?: SetupEnvOptions) => Promise<SetupEnvResult>;
 /**
@@ -124,6 +126,7 @@ export declare const setup_env_file: (deps: FsReadDeps & FsWriteDeps & CommandDe
  * @param app_name - application name (used for default state directory)
  * @param options - state_dir override, permissions, logger
  * @returns result indicating whether a token was created
+ * @mutates filesystem - creates state directory and writes the token file (optionally chmods to `0o700` / `0o600`)
  */
 export declare const setup_bootstrap_token: (deps: FsReadDeps & FsWriteDeps & CommandDeps & EnvDeps, app_name: string, options?: SetupBootstrapTokenOptions) => Promise<SetupTokenResult>;
 /**
@@ -133,15 +136,20 @@ export declare const setup_bootstrap_token: (deps: FsReadDeps & FsWriteDeps & Co
  * @param app_name - application name
  * @param options - state_dir override, permissions, logger
  * @returns result from creating the new token
+ * @mutates filesystem - removes the existing token file (if any) then writes a fresh one
  */
 export declare const reset_bootstrap_token: (deps: FsReadDeps & FsWriteDeps & FsRemoveDeps & CommandDeps & EnvDeps, app_name: string, options?: SetupBootstrapTokenOptions) => Promise<SetupTokenResult>;
 /**
  * Create a PostgreSQL database if `createdb` is available.
  *
+ * Does not throw — returns the underlying command result so callers can
+ * decide how to react to a missing `createdb` or an "already exists" failure.
+ *
  * @param deps - command execution capability
  * @param db_name - database name to create
  * @param options - logger
  * @returns the command result
+ * @mutates external database - invokes `createdb` to create `db_name` when available
  */
 export declare const create_database: (deps: CommandDeps, db_name: string, options?: CreateDatabaseOptions) => Promise<CommandResult>;
 /**
@@ -152,9 +160,11 @@ export declare const create_database: (deps: CommandDeps, db_name: string, optio
  * For empty/missing URLs: skips.
  *
  * @param deps - command and file capabilities
- * @param database_url - the DATABASE_URL value
- * @param options - pglite_data_dir, logger
+ * @param database_url - the `DATABASE_URL` value
+ * @param options - `pglite_data_dir`, logger
  * @returns result describing what happened
+ * @mutates external database - drops and recreates the PostgreSQL database, or removes the PGlite data directory
+ * @mutates filesystem - removes `options.pglite_data_dir` recursively for PGlite URLs
  */
 export declare const reset_database: (deps: CommandDeps & FsReadDeps & FsRemoveDeps, database_url: string, options?: ResetDatabaseOptions) => Promise<ResetDbResult>;
 /** Input to `seed_dev_account`. */
@@ -186,6 +196,9 @@ export interface SeedDevAccountDeps extends QueryDeps {
  * updates an existing password (rerun would silently rotate it).
  *
  * Intended for `scripts/dev_setup.ts` — do not call in production.
+ *
+ * @mutates database - inserts an account/actor pair when missing and grants any requested role permits
+ * @throws Error if an existing account is found without an associated actor row
  */
 export declare const seed_dev_account: (deps: SeedDevAccountDeps, input: SeedDevAccountInput, options?: {
     log?: SetupLogger;

package/dist/dev/setup.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"setup.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/dev/setup.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"setup.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/dev/setup.ts"],"names":[],"mappings":"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"}

package/dist/dev/setup.js

@@ -37,6 +37,7 @@ export const parse_db_name = (url) => {
  *
  * @param deps - command execution capability
  * @returns a random 32-byte base64-encoded key
+ * @throws Error if `openssl rand` fails or is unavailable
  */
 export const generate_random_key = async (deps) => {
     const result = await deps.run_command('openssl', ['rand', '-base64', '32']);
@@ -78,6 +79,7 @@ export const read_env_var = async (deps, env_path, name) => {
  * @param example_path - path to the example template
  * @param options - extra replacements, permissions, logger
  * @returns result indicating whether the file was created or updated
+ * @mutates filesystem - writes `env_path` (creating from `example_path` if missing) and optionally chmods to `0o600`
  */
 export const setup_env_file = async (deps, env_path, example_path, options) => {
     const log = options?.log ?? default_setup_logger;
@@ -136,6 +138,7 @@ export const setup_env_file = async (deps, env_path, example_path, options) => {
  * @param app_name - application name (used for default state directory)
  * @param options - state_dir override, permissions, logger
  * @returns result indicating whether a token was created
+ * @mutates filesystem - creates state directory and writes the token file (optionally chmods to `0o700` / `0o600`)
  */
 export const setup_bootstrap_token = async (deps, app_name, options) => {
     const log = options?.log ?? default_setup_logger;
@@ -169,6 +172,7 @@ export const setup_bootstrap_token = async (deps, app_name, options) => {
  * @param app_name - application name
  * @param options - state_dir override, permissions, logger
  * @returns result from creating the new token
+ * @mutates filesystem - removes the existing token file (if any) then writes a fresh one
  */
 export const reset_bootstrap_token = async (deps, app_name, options) => {
     const log = options?.log ?? default_setup_logger;
@@ -191,10 +195,14 @@ export const reset_bootstrap_token = async (deps, app_name, options) => {
 /**
  * Create a PostgreSQL database if `createdb` is available.
  *
+ * Does not throw — returns the underlying command result so callers can
+ * decide how to react to a missing `createdb` or an "already exists" failure.
+ *
  * @param deps - command execution capability
  * @param db_name - database name to create
  * @param options - logger
  * @returns the command result
+ * @mutates external database - invokes `createdb` to create `db_name` when available
  */
 export const create_database = async (deps, db_name, options) => {
     const log = options?.log ?? default_setup_logger;
@@ -220,9 +228,11 @@ export const create_database = async (deps, db_name, options) => {
  * For empty/missing URLs: skips.
  *
  * @param deps - command and file capabilities
- * @param database_url - the DATABASE_URL value
- * @param options - pglite_data_dir, logger
+ * @param database_url - the `DATABASE_URL` value
+ * @param options - `pglite_data_dir`, logger
  * @returns result describing what happened
+ * @mutates external database - drops and recreates the PostgreSQL database, or removes the PGlite data directory
+ * @mutates filesystem - removes `options.pglite_data_dir` recursively for PGlite URLs
  */
 export const reset_database = async (deps, database_url, options) => {
     const log = options?.log ?? default_setup_logger;
@@ -273,6 +283,9 @@ export const reset_database = async (deps, database_url, options) => {
  * updates an existing password (rerun would silently rotate it).
  *
  * Intended for `scripts/dev_setup.ts` — do not call in production.
+ *
+ * @mutates database - inserts an account/actor pair when missing and grants any requested role permits
+ * @throws Error if an existing account is found without an associated actor row
  */
 export const seed_dev_account = async (deps, input, options) => {
     const log = options?.log ?? default_setup_logger;

package/dist/env/dotenv.d.ts

@@ -36,7 +36,8 @@ export declare const parse_dotenv: (content: string) => Record<string, string>;
  *
  * @param runtime - runtime with `read_text_file` capability
  * @param path - path to env file
- * @returns parsed env record, or null if file doesn't exist
+ * @returns parsed env record, or `null` if file doesn't exist
+ * @throws Error if reading fails for any reason other than `ENOENT` / `NotFound`
  */
 export declare const load_env_file: (runtime: Pick<FsReadDeps, "read_text_file">, path: string) => Promise<Record<string, string> | null>;
 //# sourceMappingURL=dotenv.d.ts.map

package/dist/env/dotenv.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"dotenv.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/env/dotenv.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAC,UAAU,EAAC,MAAM,oBAAoB,CAAC;AAEnD;;;;;;;;;;;;;;;;;;GAkBG;AAGH,eAAO,MAAM,YAAY,GAAI,SAAS,MAAM,KAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAkCnE,CAAC;AAiEF;;;;;;;;;;GAUG;AACH,eAAO,MAAM,aAAa,GACzB,SAAS,IAAI,CAAC,UAAU,EAAE,gBAAgB,CAAC,EAC3C,MAAM,MAAM,KACV,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,IAAI,CASvC,CAAC"}
+{"version":3,"file":"dotenv.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/env/dotenv.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAC,UAAU,EAAC,MAAM,oBAAoB,CAAC;AAEnD;;;;;;;;;;;;;;;;;;GAkBG;AAGH,eAAO,MAAM,YAAY,GAAI,SAAS,MAAM,KAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAkCnE,CAAC;AAiEF;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,aAAa,GACzB,SAAS,IAAI,CAAC,UAAU,EAAE,gBAAgB,CAAC,EAC3C,MAAM,MAAM,KACV,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,IAAI,CASvC,CAAC"}

package/dist/env/dotenv.js

@@ -135,7 +135,8 @@ const unescape_double_quoted = (s) => {
  *
  * @param runtime - runtime with `read_text_file` capability
  * @param path - path to env file
- * @returns parsed env record, or null if file doesn't exist
+ * @returns parsed env record, or `null` if file doesn't exist
+ * @throws Error if reading fails for any reason other than `ENOENT` / `NotFound`
  */
 export const load_env_file = async (runtime, path) => {
     try {

package/dist/env/load.d.ts

@@ -41,12 +41,10 @@ export declare const log_env_validation_error: (error: EnvValidationError, label
 /**
  * Load and validate env vars against a Zod schema.
  *
- * Reads each key from the schema using `get_env`, then validates.
- * Throws `EnvValidationError` on failure.
- *
  * @param schema - Zod object schema defining expected env vars
  * @param get_env - function to read an env var by key
  * @returns validated env object
+ * @throws EnvValidationError if Zod validation fails
  */
 export declare const load_env: <T extends z.ZodObject>(schema: T, get_env: (key: string) => string | undefined) => z.infer<T>;
 //# sourceMappingURL=load.d.ts.map

package/dist/env/load.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"load.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/env/load.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAC,CAAC,EAAC,MAAM,KAAK,CAAC;AAEtB;;;;GAIG;AACH,qBAAa,kBAAmB,SAAQ,KAAK;IAC5C,yCAAyC;IACzC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC;IACjD,gCAAgC;IAChC,QAAQ,CAAC,SAAS,EAAE,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC;IACrC,4DAA4D;IAC5D,QAAQ,CAAC,aAAa,EAAE,OAAO,CAAC;gBAEpB,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,EAAE,SAAS,EAAE,CAAC,CAAC,IAAI,CAAC,SAAS;IAOhF;;;;OAIG;IACH,aAAa,IAAI,KAAK,CAAC,MAAM,CAAC;CAG9B;AAED;;;;;;;;;GASG;AACH,eAAO,MAAM,wBAAwB,GAAI,OAAO,kBAAkB,EAAE,QAAQ,MAAM,KAAG,IAUpF,CAAC;AAEF;;;;;;;;;GASG;AACH,eAAO,MAAM,QAAQ,GAAI,CAAC,SAAS,CAAC,CAAC,SAAS,EAC7C,QAAQ,CAAC,EACT,SAAS,CAAC,GAAG,EAAE,MAAM,KAAK,MAAM,GAAG,SAAS,KAC1C,CAAC,CAAC,KAAK,CAAC,CAAC,CAaX,CAAC"}
+{"version":3,"file":"load.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/env/load.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAC,CAAC,EAAC,MAAM,KAAK,CAAC;AAEtB;;;;GAIG;AACH,qBAAa,kBAAmB,SAAQ,KAAK;IAC5C,yCAAyC;IACzC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC;IACjD,gCAAgC;IAChC,QAAQ,CAAC,SAAS,EAAE,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC;IACrC,4DAA4D;IAC5D,QAAQ,CAAC,aAAa,EAAE,OAAO,CAAC;gBAEpB,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,EAAE,SAAS,EAAE,CAAC,CAAC,IAAI,CAAC,SAAS;IAOhF;;;;OAIG;IACH,aAAa,IAAI,KAAK,CAAC,MAAM,CAAC;CAG9B;AAED;;;;;;;;;GASG;AACH,eAAO,MAAM,wBAAwB,GAAI,OAAO,kBAAkB,EAAE,QAAQ,MAAM,KAAG,IAUpF,CAAC;AAEF;;;;;;;GAOG;AACH,eAAO,MAAM,QAAQ,GAAI,CAAC,SAAS,CAAC,CAAC,SAAS,EAC7C,QAAQ,CAAC,EACT,SAAS,CAAC,GAAG,EAAE,MAAM,KAAK,MAAM,GAAG,SAAS,KAC1C,CAAC,CAAC,KAAK,CAAC,CAAC,CAaX,CAAC"}

package/dist/env/load.js

@@ -59,12 +59,10 @@ export const log_env_validation_error = (error, label) => {
 /**
  * Load and validate env vars against a Zod schema.
  *
- * Reads each key from the schema using `get_env`, then validates.
- * Throws `EnvValidationError` on failure.
- *
  * @param schema - Zod object schema defining expected env vars
  * @param get_env - function to read an env var by key
  * @returns validated env object
+ * @throws EnvValidationError if Zod validation fails
  */
 export const load_env = (schema, get_env) => {
     const raw = {};