@fuzdev/fuz_app 0.50.0 → 0.52.0

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,8 @@ 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`
+ * @throws Error if `example_path` cannot be read when `env_path` is missing, or if a generator / write fails
  */
 export declare const setup_env_file: (deps: FsReadDeps & FsWriteDeps & CommandDeps, env_path: string, example_path: string, options?: SetupEnvOptions) => Promise<SetupEnvResult>;
 /**
@@ -124,6 +127,8 @@ 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`)
+ * @throws Error if `mkdir`, key generation, or `write_text_file` fails
  */
 export declare const setup_bootstrap_token: (deps: FsReadDeps & FsWriteDeps & CommandDeps & EnvDeps, app_name: string, options?: SetupBootstrapTokenOptions) => Promise<SetupTokenResult>;
 /**
@@ -133,15 +138,21 @@ 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
+ * @throws Error if `remove` or the underlying `setup_bootstrap_token` call fails
  */
 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 +163,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 +199,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,8 @@ 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`
+ * @throws Error if `example_path` cannot be read when `env_path` is missing, or if a generator / write fails
  */
 export const setup_env_file = async (deps, env_path, example_path, options) => {
     const log = options?.log ?? default_setup_logger;
@@ -136,6 +139,8 @@ 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`)
+ * @throws Error if `mkdir`, key generation, or `write_text_file` fails
  */
 export const setup_bootstrap_token = async (deps, app_name, options) => {
     const log = options?.log ?? default_setup_logger;
@@ -169,6 +174,8 @@ 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
+ * @throws Error if `remove` or the underlying `setup_bootstrap_token` call fails
  */
 export const reset_bootstrap_token = async (deps, app_name, options) => {
     const log = options?.log ?? default_setup_logger;
@@ -191,10 +198,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 +231,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 +286,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

@@ -42,11 +42,11 @@ 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.js

@@ -60,11 +60,11 @@ 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 = {};

package/dist/env/resolve.d.ts

@@ -56,7 +56,7 @@ export declare const resolve_env_vars_in_object: <T extends Record<string, unkno
  * @param value - string with `$$VAR$$` references
  * @param context - description for error message (e.g., `"target.host"`)
  * @returns resolved string
- * @throws error if any referenced env var is missing or empty
+ * @throws Error if any referenced env var is missing or empty
  */
 export declare const resolve_env_vars_required: (runtime: Pick<EnvDeps, "env_get">, value: string, context: string) => string;
 /**

package/dist/env/resolve.js

@@ -85,7 +85,7 @@ export const resolve_env_vars_in_object = (runtime, obj) => {
  * @param value - string with `$$VAR$$` references
  * @param context - description for error message (e.g., `"target.host"`)
  * @returns resolved string
- * @throws error if any referenced env var is missing or empty
+ * @throws Error if any referenced env var is missing or empty
  */
 export const resolve_env_vars_required = (runtime, value, context) => {
     const missing = [];

package/dist/env/update_env_variable.d.ts

@@ -31,6 +31,8 @@ export interface UpdateEnvVariableOptions {
  * @param key - the environment variable name (e.g., `'SOME_CONFIGURATION_KEY'`)
  * @param value - the new value for the environment variable
  * @param options - file path and optional read/write overrides
+ * @mutates filesystem - writes the updated content back to `options.env_file_path`
+ * @throws Error if the file read fails for any reason other than `ENOENT`, or if the write fails
  */
 export declare const update_env_variable: (key: string, value: string, options: UpdateEnvVariableOptions) => Promise<void>;
 //# sourceMappingURL=update_env_variable.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"update_env_variable.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/env/update_env_variable.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAKH;;GAEG;AACH,MAAM,WAAW,wBAAwB;IACxC,6BAA6B;IAC7B,aAAa,EAAE,MAAM,CAAC;IACtB,kFAAkF;IAClF,SAAS,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;IAChE,oFAAoF;IACpF,UAAU,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CAChF;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,mBAAmB,GAC/B,KAAK,MAAM,EACX,OAAO,MAAM,EACb,SAAS,wBAAwB,KAC/B,OAAO,CAAC,IAAI,CAmDd,CAAC"}
+{"version":3,"file":"update_env_variable.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/env/update_env_variable.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAKH;;GAEG;AACH,MAAM,WAAW,wBAAwB;IACxC,6BAA6B;IAC7B,aAAa,EAAE,MAAM,CAAC;IACtB,kFAAkF;IAClF,SAAS,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;IAChE,oFAAoF;IACpF,UAAU,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CAChF;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,eAAO,MAAM,mBAAmB,GAC/B,KAAK,MAAM,EACX,OAAO,MAAM,EACb,SAAS,wBAAwB,KAC/B,OAAO,CAAC,IAAI,CAmDd,CAAC"}

package/dist/env/update_env_variable.js

@@ -22,6 +22,8 @@ import { resolve } from 'node:path';
  * @param key - the environment variable name (e.g., `'SOME_CONFIGURATION_KEY'`)
  * @param value - the new value for the environment variable
  * @param options - file path and optional read/write overrides
+ * @mutates filesystem - writes the updated content back to `options.env_file_path`
+ * @throws Error if the file read fails for any reason other than `ENOENT`, or if the write fails
  */
 export const update_env_variable = async (key, value, options) => {
     const { env_file_path, read_file = readFile, write_file = writeFile } = options;

package/dist/hono_context.d.ts

@@ -7,7 +7,7 @@
  * Import this module once in your app to get type-safe access to
  * `auth_session_id`, `request_context`, and `credential_type` on the Hono context.
  *
- * In practice, this is auto-loaded by `app_server.ts` (side-effect import)
+ * In practice, this is auto-loaded by `server/app_server.ts` (side-effect import)
  * and transitively by auth middleware modules that import `CREDENTIAL_TYPE_KEY`.
  * Consumers don't need a manual import unless bypassing the standard server assembly.
  *

package/dist/hono_context.js

@@ -7,7 +7,7 @@
  * Import this module once in your app to get type-safe access to
  * `auth_session_id`, `request_context`, and `credential_type` on the Hono context.
  *
- * In practice, this is auto-loaded by `app_server.ts` (side-effect import)
+ * In practice, this is auto-loaded by `server/app_server.ts` (side-effect import)
  * and transitively by auth middleware modules that import `CREDENTIAL_TYPE_KEY`.
  * Consumers don't need a manual import unless bypassing the standard server assembly.
  *

package/dist/http/jsonrpc_errors.d.ts

@@ -7,10 +7,10 @@
  * codes stay in consumers — add by casting `as JsonrpcErrorCode`.
  *
  * `JsonrpcErrorCode` and `JsonrpcErrorObject` types are Zod-inferred
- * from `jsonrpc.ts` — this module re-uses those as the single source
+ * from `http/jsonrpc.ts` — this module re-uses those as the single source
  * of truth.
  *
- * Complementary to `error_schemas.ts`: that module is declarative
+ * Complementary to `http/error_schemas.ts`: that module is declarative
  * (Zod schemas for surface introspection), this one is runtime
  * (throw + catch + map).
  *

package/dist/http/jsonrpc_errors.js

@@ -7,10 +7,10 @@
  * codes stay in consumers — add by casting `as JsonrpcErrorCode`.
  *
  * `JsonrpcErrorCode` and `JsonrpcErrorObject` types are Zod-inferred
- * from `jsonrpc.ts` — this module re-uses those as the single source
+ * from `http/jsonrpc.ts` — this module re-uses those as the single source
  * of truth.
  *
- * Complementary to `error_schemas.ts`: that module is declarative
+ * Complementary to `http/error_schemas.ts`: that module is declarative
  * (Zod schemas for surface introspection), this one is runtime
  * (throw + catch + map).
  *

package/dist/http/jsonrpc_helpers.d.ts

@@ -2,8 +2,8 @@
  * JSON-RPC message builders, type guards, and converters.
  *
  * Used by the SAES runtime (ActionEvent, ActionPeer, transports) and
- * the RPC endpoint dispatcher. Complements `jsonrpc.ts` (schemas) and
- * `jsonrpc_errors.ts` (error infrastructure).
+ * the RPC endpoint dispatcher. Complements `http/jsonrpc.ts` (schemas) and
+ * `http/jsonrpc_errors.ts` (error infrastructure).
  *
  * @module
  */

package/dist/http/jsonrpc_helpers.js

@@ -2,8 +2,8 @@
  * JSON-RPC message builders, type guards, and converters.
  *
  * Used by the SAES runtime (ActionEvent, ActionPeer, transports) and
- * the RPC endpoint dispatcher. Complements `jsonrpc.ts` (schemas) and
- * `jsonrpc_errors.ts` (error infrastructure).
+ * the RPC endpoint dispatcher. Complements `http/jsonrpc.ts` (schemas) and
+ * `http/jsonrpc_errors.ts` (error infrastructure).
  *
  * @module
  */

package/dist/http/middleware_spec.d.ts

@@ -1,7 +1,7 @@
 /**
  * Middleware spec type — named middleware layer definition.
  *
- * Separated from `route_spec.ts` so middleware modules can import this
+ * Separated from `http/route_spec.ts` so middleware modules can import this
  * type without creating an upward dependency on routes.
  *
  * @module

package/dist/http/middleware_spec.js

@@ -1,7 +1,7 @@
 /**
  * Middleware spec type — named middleware layer definition.
  *
- * Separated from `route_spec.ts` so middleware modules can import this
+ * Separated from `http/route_spec.ts` so middleware modules can import this
  * type without creating an upward dependency on routes.
  *
  * @module

package/dist/http/origin.d.ts

@@ -3,7 +3,7 @@
  *
  * Verifies requests are coming from expected origins/referers.
  * CSRF protection is provided by `SameSite: strict` on session cookies
- * (see `session_middleware.ts`). This module provides origin allowlisting
+ * (see `auth/session_middleware.ts`). This module provides origin allowlisting
  * for locally-running services — preventing untrusted websites from
  * making requests as the user browses the web.
  *

package/dist/http/origin.js

@@ -3,7 +3,7 @@
  *
  * Verifies requests are coming from expected origins/referers.
  * CSRF protection is provided by `SameSite: strict` on session cookies
- * (see `session_middleware.ts`). This module provides origin allowlisting
+ * (see `auth/session_middleware.ts`). This module provides origin allowlisting
  * for locally-running services — preventing untrusted websites from
  * making requests as the user browses the web.
  *

package/dist/http/pending_effects.d.ts

@@ -24,6 +24,10 @@ export interface PendingEffectsContext {
  * Exceptions thrown by `fn` are caught and logged via `ctx.log.error`, so one
  * failed send cannot corrupt the already-committed response or starve other
  * queued effects in the same tick.
+ *
+ * @param ctx - context carrying `log` and the `pending_effects` queue
+ * @param fn - synchronous side effect to run after commit
+ * @mutates `ctx.pending_effects` - appends a never-rejecting promise wrapping `fn`
  */
 export declare const emit_after_commit: (ctx: PendingEffectsContext, fn: () => void) => void;
 //# sourceMappingURL=pending_effects.d.ts.map

package/dist/http/pending_effects.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"pending_effects.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/http/pending_effects.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EAAC,MAAM,EAAC,MAAM,yBAAyB,CAAC;AAEpD,kEAAkE;AAClE,MAAM,WAAW,qBAAqB;IACrC,GAAG,EAAE,MAAM,CAAC;IACZ,eAAe,EAAE,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC;CACtC;AAED;;;;;;GAMG;AACH,eAAO,MAAM,iBAAiB,GAAI,KAAK,qBAAqB,EAAE,IAAI,MAAM,IAAI,KAAG,IAU9E,CAAC"}
+{"version":3,"file":"pending_effects.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/http/pending_effects.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EAAC,MAAM,EAAC,MAAM,yBAAyB,CAAC;AAEpD,kEAAkE;AAClE,MAAM,WAAW,qBAAqB;IACrC,GAAG,EAAE,MAAM,CAAC;IACZ,eAAe,EAAE,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC;CACtC;AAED;;;;;;;;;;GAUG;AACH,eAAO,MAAM,iBAAiB,GAAI,KAAK,qBAAqB,EAAE,IAAI,MAAM,IAAI,KAAG,IAU9E,CAAC"}

package/dist/http/pending_effects.js

@@ -18,6 +18,10 @@
  * Exceptions thrown by `fn` are caught and logged via `ctx.log.error`, so one
  * failed send cannot corrupt the already-committed response or starve other
  * queued effects in the same tick.
+ *
+ * @param ctx - context carrying `log` and the `pending_effects` queue
+ * @param fn - synchronous side effect to run after commit
+ * @mutates `ctx.pending_effects` - appends a never-rejecting promise wrapping `fn`
  */
 export const emit_after_commit = (ctx, fn) => {
     ctx.pending_effects.push(Promise.resolve().then(() => {

package/dist/http/proxy.d.ts

@@ -92,6 +92,8 @@ export declare const resolve_client_ip: (forwarded_for: string, proxies: Array<P
  *    right-to-left, strip trusted entries, use first untrusted entry.
  *
  * @param options - trusted proxy configuration
+ * @mutates `c.var.client_ip` - set to the resolved (or `'unknown'`) client IP per request
+ * @throws Error if any entry in `options.trusted_proxies` is invalid (parsed eagerly via `parse_proxy_entry`)
  */
 export declare const create_proxy_middleware: (options: ProxyOptions) => MiddlewareHandler;
 /**
@@ -100,6 +102,7 @@ export declare const create_proxy_middleware: (options: ProxyOptions) => Middlew
  * Apply before auth middleware so `client_ip` is available for rate limiting.
  *
  * @param options - trusted proxy configuration
+ * @throws Error if any entry in `options.trusted_proxies` is invalid (delegates to `create_proxy_middleware`)
  */
 export declare const create_proxy_middleware_spec: (options: ProxyOptions) => MiddlewareSpec;
 /**

package/dist/http/proxy.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"proxy.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/http/proxy.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAC,OAAO,EAAE,iBAAiB,EAAC,MAAM,MAAM,CAAC;AAErD,OAAO,KAAK,EAAC,MAAM,EAAC,MAAM,yBAAyB,CAAC;AAEpD,OAAO,KAAK,EAAC,cAAc,EAAC,MAAM,sBAAsB,CAAC;AAEzD;;;;;;;;;;GAUG;AACH,eAAO,MAAM,YAAY,GAAI,IAAI,MAAM,KAAG,MAQzC,CAAC;AAEF;;GAEG;AACH,MAAM,WAAW,YAAY;IAC5B,sFAAsF;IACtF,eAAe,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;IAC/B,+DAA+D;IAC/D,iBAAiB,EAAE,CAAC,CAAC,EAAE,OAAO,KAAK,MAAM,GAAG,SAAS,CAAC;IACtD,wDAAwD;IACxD,GAAG,CAAC,EAAE,MAAM,CAAC;CACb;AAED;;GAEG;AACH,MAAM,MAAM,WAAW,GACpB;IAAC,IAAI,EAAE,IAAI,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAC,GAC7B;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,YAAY,EAAE,MAAM,GAAG,MAAM,CAAA;CAAC,CAAC;AAElF;;;;;;;;;GASG;AACH,eAAO,MAAM,iBAAiB,GAAI,OAAO,MAAM,KAAG,WA6CjD,CAAC;AAiBF;;;;;;;GAOG;AACH,eAAO,MAAM,aAAa,GAAI,IAAI,MAAM,EAAE,SAAS,KAAK,CAAC,WAAW,CAAC,KAAG,OAqBvE,CAAC;AAQF;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,iBAAiB,GAC7B,eAAe,MAAM,EACrB,SAAS,KAAK,CAAC,WAAW,CAAC,KACzB,MAAM,GAAG,SAiBX,CAAC;AAEF;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,uBAAuB,GAAI,SAAS,YAAY,KAAG,iBAyC/D,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,4BAA4B,GAAI,SAAS,YAAY,KAAG,cAInE,CAAC;AAEH;;;;;GAKG;AACH,eAAO,MAAM,aAAa,GAAI,GAAG,OAAO,KAAG,MAAyC,CAAC"}
+{"version":3,"file":"proxy.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/http/proxy.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAC,OAAO,EAAE,iBAAiB,EAAC,MAAM,MAAM,CAAC;AAErD,OAAO,KAAK,EAAC,MAAM,EAAC,MAAM,yBAAyB,CAAC;AAEpD,OAAO,KAAK,EAAC,cAAc,EAAC,MAAM,sBAAsB,CAAC;AAEzD;;;;;;;;;;GAUG;AACH,eAAO,MAAM,YAAY,GAAI,IAAI,MAAM,KAAG,MAQzC,CAAC;AAEF;;GAEG;AACH,MAAM,WAAW,YAAY;IAC5B,sFAAsF;IACtF,eAAe,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;IAC/B,+DAA+D;IAC/D,iBAAiB,EAAE,CAAC,CAAC,EAAE,OAAO,KAAK,MAAM,GAAG,SAAS,CAAC;IACtD,wDAAwD;IACxD,GAAG,CAAC,EAAE,MAAM,CAAC;CACb;AAED;;GAEG;AACH,MAAM,MAAM,WAAW,GACpB;IAAC,IAAI,EAAE,IAAI,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAC,GAC7B;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,YAAY,EAAE,MAAM,GAAG,MAAM,CAAA;CAAC,CAAC;AAElF;;;;;;;;;GASG;AACH,eAAO,MAAM,iBAAiB,GAAI,OAAO,MAAM,KAAG,WA6CjD,CAAC;AAiBF;;;;;;;GAOG;AACH,eAAO,MAAM,aAAa,GAAI,IAAI,MAAM,EAAE,SAAS,KAAK,CAAC,WAAW,CAAC,KAAG,OAqBvE,CAAC;AAQF;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,iBAAiB,GAC7B,eAAe,MAAM,EACrB,SAAS,KAAK,CAAC,WAAW,CAAC,KACzB,MAAM,GAAG,SAiBX,CAAC;AAEF;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,uBAAuB,GAAI,SAAS,YAAY,KAAG,iBAyC/D,CAAC;AAEF;;;;;;;GAOG;AACH,eAAO,MAAM,4BAA4B,GAAI,SAAS,YAAY,KAAG,cAInE,CAAC;AAEH;;;;;GAKG;AACH,eAAO,MAAM,aAAa,GAAI,GAAG,OAAO,KAAG,MAAyC,CAAC"}

package/dist/http/proxy.js

@@ -176,6 +176,8 @@ export const resolve_client_ip = (forwarded_for, proxies) => {
  *    right-to-left, strip trusted entries, use first untrusted entry.
  *
  * @param options - trusted proxy configuration
+ * @mutates `c.var.client_ip` - set to the resolved (or `'unknown'`) client IP per request
+ * @throws Error if any entry in `options.trusted_proxies` is invalid (parsed eagerly via `parse_proxy_entry`)
  */
 export const create_proxy_middleware = (options) => {
     const parsed_proxies = options.trusted_proxies.map(parse_proxy_entry);
@@ -225,6 +227,7 @@ export const create_proxy_middleware = (options) => {
  * Apply before auth middleware so `client_ip` is available for rate limiting.
  *
  * @param options - trusted proxy configuration
+ * @throws Error if any entry in `options.trusted_proxies` is invalid (delegates to `create_proxy_middleware`)
  */
 export const create_proxy_middleware_spec = (options) => ({
     name: 'trusted_proxy',

package/dist/http/route_spec.d.ts

@@ -185,6 +185,7 @@ export declare const apply_middleware_specs: (app: Hono, specs: Array<Middleware
  * @param log - the logger instance
  * @param db - database instance for transaction wrapping and `RouteContext`
  * @mutates `app`
+ * @throws Error if two specs share the same `method` + `path` (each combination must be unique)
  */
 export declare const apply_route_specs: (app: Hono, specs: Array<RouteSpec>, resolve_auth_guards: AuthGuardResolver, log: Logger, db: Db) => void;
 /**

package/dist/http/route_spec.d.ts.map

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

package/dist/http/route_spec.js

@@ -60,6 +60,8 @@ export const get_route_query = (c) => {
  * and for null-input routes (no body expected). For other routes with input
  * schemas, returns a middleware that parses and validates the JSON body,
  * storing the result on the context as `validated_input`.
+ *
+ * @mutates `c.var.validated_input` - set to the parsed and validated body on success
  */
 const create_input_validation = (input_schema, method) => {
     if (method === 'GET')
@@ -92,6 +94,8 @@ const create_input_validation = (input_schema, method) => {
  * Returns an empty array when no params schema is defined.
  * For routes with params schemas, returns a middleware that validates
  * `c.req.param()` against the schema, storing the result on the context as `validated_params`.
+ *
+ * @mutates `c.var.validated_params` - set to the parsed and validated path params on success
  */
 const create_params_validation = (params_schema) => {
     if (!params_schema)
@@ -113,6 +117,8 @@ const create_params_validation = (params_schema) => {
  * Returns an empty array when no query schema is defined.
  * For routes with query schemas, returns a middleware that validates
  * `c.req.query()` against the schema, storing the result on the context as `validated_query`.
+ *
+ * @mutates `c.var.validated_query` - set to the parsed and validated query params on success
  */
 const create_query_validation = (query_schema) => {
     if (!query_schema)
@@ -238,6 +244,7 @@ const wrap_error_catch = (handler, log) => {
  * @param log - the logger instance
  * @param db - database instance for transaction wrapping and `RouteContext`
  * @mutates `app`
+ * @throws Error if two specs share the same `method` + `path` (each combination must be unique)
  */
 export const apply_route_specs = (app, specs, resolve_auth_guards, log, db) => {
     const registered = new Set();

package/dist/http/schema_helpers.d.ts

@@ -1,7 +1,7 @@
 /**
  * Shared pure helpers for schema introspection and middleware matching.
  *
- * Used by both `route_spec.ts` (input validation) and `surface.ts`
+ * Used by both `http/route_spec.ts` (input validation) and `http/surface.ts`
  * (attack surface generation). Extracted to avoid circular dependencies
  * between routes and middleware.
  *

package/dist/http/schema_helpers.js

@@ -1,7 +1,7 @@
 /**
  * Shared pure helpers for schema introspection and middleware matching.
  *
- * Used by both `route_spec.ts` (input validation) and `surface.ts`
+ * Used by both `http/route_spec.ts` (input validation) and `http/surface.ts`
  * (attack surface generation). Extracted to avoid circular dependencies
  * between routes and middleware.
  *

package/dist/http/surface.d.ts

@@ -2,7 +2,7 @@
  * App surface generation — JSON-serializable attack surface from route and middleware specs.
  *
  * Pure schema helpers (`is_null_schema`, `schema_to_surface`, `middleware_applies`,
- * `merge_error_schemas`) live in `schema_helpers.ts`.
+ * `merge_error_schemas`) live in `http/schema_helpers.ts`.
  *
  * @module
  */

package/dist/http/surface.js

@@ -2,7 +2,7 @@
  * App surface generation — JSON-serializable attack surface from route and middleware specs.
  *
  * Pure schema helpers (`is_null_schema`, `schema_to_surface`, `middleware_applies`,
- * `merge_error_schemas`) live in `schema_helpers.ts`.
+ * `merge_error_schemas`) live in `http/schema_helpers.ts`.
  *
  * @module
  */

package/dist/rate_limiter.d.ts

@@ -83,8 +83,13 @@ export declare class RateLimiter {
     /**
      * Check whether `key` is allowed without recording an attempt.
      *
+     * Prunes timestamps that fell outside the window as a side effect (and
+     * removes the key entirely when none remain), so the backing map stays
+     * bounded even under read-only traffic.
+     *
      * @param key - rate limit key (e.g. IP address)
      * @param now - current timestamp in ms (defaults to `Date.now()`)
+     * @mutates internal map - prunes expired timestamps for `key`
      */
     check(key: string, now?: number): RateLimitResult;
     /**
@@ -92,19 +97,27 @@ export declare class RateLimiter {
      *
      * @param key - rate limit key (e.g. IP address)
      * @param now - current timestamp in ms (defaults to `Date.now()`)
+     * @mutates internal map - appends `now` to the timestamp list for `key` (after pruning expired entries)
      */
     record(key: string, now?: number): RateLimitResult;
     /**
      * Clear all attempts for `key` (e.g. after successful login).
+     *
+     * @mutates internal map - removes the entry for `key`
      */
     reset(key: string): void;
     /**
      * Remove entries whose timestamps are all outside the window.
      *
      * @param now - current timestamp in ms (defaults to `Date.now()`)
+     * @mutates internal map - prunes expired timestamps and deletes empty keys
      */
     cleanup(now?: number): void;
-    /** Stop the cleanup timer. Safe to call multiple times. */
+    /**
+     * Stop the cleanup timer. Safe to call multiple times.
+     *
+     * @mutates timer - clears the cleanup `setInterval` and nulls the handle
+     */
     dispose(): void;
 }
 /**

package/dist/rate_limiter.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"rate_limiter.d.ts","sourceRoot":"../src/lib/","sources":["../src/lib/rate_limiter.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAC,OAAO,EAAC,MAAM,MAAM,CAAC;AAKlC;;;;;;GAMG;AACH,eAAO,MAAM,6BAA6B,SAAU,CAAC;AAErD;;GAEG;AACH,MAAM,WAAW,kBAAkB;IAClC,kDAAkD;IAClD,YAAY,EAAE,MAAM,CAAC;IACrB,+CAA+C;IAC/C,SAAS,EAAE,MAAM,CAAC;IAClB,iEAAiE;IACjE,mBAAmB,EAAE,MAAM,CAAC;IAC5B;;;;;;;;;;;;;;OAcG;IACH,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CACzB;AAED,iFAAiF;AACjF,eAAO,MAAM,2BAA2B,EAAE,kBAKzC,CAAC;AAEF,uFAAuF;AACvF,eAAO,MAAM,gCAAgC,EAAE,kBAK9C,CAAC;AAEF;;GAEG;AACH,MAAM,WAAW,eAAe;IAC/B,sCAAsC;IACtC,OAAO,EAAE,OAAO,CAAC;IACjB,0CAA0C;IAC1C,SAAS,EAAE,MAAM,CAAC;IAClB,sEAAsE;IACtE,WAAW,EAAE,MAAM,CAAC;CACpB;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,qBAAa,WAAW;;IACvB,QAAQ,CAAC,OAAO,EAAE,kBAAkB,CAAC;gBAOzB,OAAO,EAAE,kBAAkB;IAcvC,8BAA8B;IAC9B,IAAI,IAAI,IAAI,MAAM,CAEjB;IAED;;;;;OAKG;IACH,KAAK,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,GAAE,MAAmB,GAAG,eAAe;IA2B7D;;;;;OAKG;IACH,MAAM,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,GAAE,MAAmB,GAAG,eAAe;IA0B9D;;OAEG;IACH,KAAK,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI;IAIxB;;;;OAIG;IACH,OAAO,CAAC,GAAG,GAAE,MAAmB,GAAG,IAAI;IAgBvC,2DAA2D;IAC3D,OAAO,IAAI,IAAI;CAMf;AAED;;;;GAIG;AACH,eAAO,MAAM,mBAAmB,GAAI,UAAU,OAAO,CAAC,kBAAkB,CAAC,KAAG,WAE3E,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,4BAA4B,GAAI,GAAG,OAAO,EAAE,aAAa,MAAM,KAAG,QAI7E,CAAC"}
+{"version":3,"file":"rate_limiter.d.ts","sourceRoot":"../src/lib/","sources":["../src/lib/rate_limiter.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAC,OAAO,EAAC,MAAM,MAAM,CAAC;AAKlC;;;;;;GAMG;AACH,eAAO,MAAM,6BAA6B,SAAU,CAAC;AAErD;;GAEG;AACH,MAAM,WAAW,kBAAkB;IAClC,kDAAkD;IAClD,YAAY,EAAE,MAAM,CAAC;IACrB,+CAA+C;IAC/C,SAAS,EAAE,MAAM,CAAC;IAClB,iEAAiE;IACjE,mBAAmB,EAAE,MAAM,CAAC;IAC5B;;;;;;;;;;;;;;OAcG;IACH,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CACzB;AAED,iFAAiF;AACjF,eAAO,MAAM,2BAA2B,EAAE,kBAKzC,CAAC;AAEF,uFAAuF;AACvF,eAAO,MAAM,gCAAgC,EAAE,kBAK9C,CAAC;AAEF;;GAEG;AACH,MAAM,WAAW,eAAe;IAC/B,sCAAsC;IACtC,OAAO,EAAE,OAAO,CAAC;IACjB,0CAA0C;IAC1C,SAAS,EAAE,MAAM,CAAC;IAClB,sEAAsE;IACtE,WAAW,EAAE,MAAM,CAAC;CACpB;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,qBAAa,WAAW;;IACvB,QAAQ,CAAC,OAAO,EAAE,kBAAkB,CAAC;gBAOzB,OAAO,EAAE,kBAAkB;IAcvC,8BAA8B;IAC9B,IAAI,IAAI,IAAI,MAAM,CAEjB;IAED;;;;;;;;;;OAUG;IACH,KAAK,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,GAAE,MAAmB,GAAG,eAAe;IA2B7D;;;;;;OAMG;IACH,MAAM,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,GAAE,MAAmB,GAAG,eAAe;IA0B9D;;;;OAIG;IACH,KAAK,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI;IAIxB;;;;;OAKG;IACH,OAAO,CAAC,GAAG,GAAE,MAAmB,GAAG,IAAI;IAgBvC;;;;OAIG;IACH,OAAO,IAAI,IAAI;CAMf;AAED;;;;GAIG;AACH,eAAO,MAAM,mBAAmB,GAAI,UAAU,OAAO,CAAC,kBAAkB,CAAC,KAAG,WAE3E,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,4BAA4B,GAAI,GAAG,OAAO,EAAE,aAAa,MAAM,KAAG,QAI7E,CAAC"}