@fuzdev/fuz_app 0.51.0 → 0.52.0

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/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":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EAAC,OAAO,EAAW,IAAI,EAAE,iBAAiB,EAAC,MAAM,MAAM,CAAC;AACpE,OAAO,KAAK,EAAC,CAAC,EAAC,MAAM,KAAK,CAAC;AAE3B,OAAO,KAAK,EAAC,MAAM,EAAC,MAAM,yBAAyB,CAAC;AAEpD,OAAO,KAAK,EAAC,EAAE,EAAC,MAAM,aAAa,CAAC;AACpC,OAAO,EACN,KAAK,iBAAiB,EACtB,KAAK,YAAY,EAKjB,MAAM,oBAAoB,CAAC;AAQ5B,OAAO,KAAK,EAAC,cAAc,EAAC,MAAM,sBAAsB,CAAC;AAEzD;;;;;GAKG;AACH,MAAM,MAAM,SAAS,GAClB;IAAC,IAAI,EAAE,MAAM,CAAA;CAAC,GACd;IAAC,IAAI,EAAE,eAAe,CAAA;CAAC,GACvB;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAC,GAC5B;IAAC,IAAI,EAAE,QAAQ,CAAA;CAAC,CAAC;AAEpB;;;;;;GAMG;AACH,MAAM,MAAM,iBAAiB,GAAG,CAAC,IAAI,EAAE,SAAS,KAAK,KAAK,CAAC,iBAAiB,CAAC,CAAC;AAE9E,6CAA6C;AAC7C,MAAM,MAAM,WAAW,GAAG,KAAK,GAAG,MAAM,GAAG,KAAK,GAAG,QAAQ,GAAG,OAAO,CAAC;AAEtE;;;;;;GAMG;AACH,MAAM,WAAW,YAAY;IAC5B,8DAA8D;IAC9D,EAAE,EAAE,EAAE,CAAC;IACP,oFAAoF;IACpF,aAAa,EAAE,EAAE,CAAC;IAClB,2EAA2E;IAC3E,eAAe,EAAE,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC;CACtC;AAED;;;;;;GAMG;AACH,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,EAAE,OAAO,EAAE,KAAK,EAAE,YAAY,KAAK,QAAQ,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAC;AAE7F;;;;;GAKG;AACH,MAAM,WAAW,SAAS;IACzB,MAAM,EAAE,WAAW,CAAC;IACpB,IAAI,EAAE,MAAM,CAAC;IACb;;;;;OAKG;IACH,IAAI,EAAE,SAAS,CAAC;IAChB,OAAO,EAAE,YAAY,CAAC;IACtB,WAAW,EAAE,MAAM,CAAC;IACpB;;;;;OAKG;IACH,MAAM,CAAC,EAAE,CAAC,CAAC,SAAS,CAAC;IACrB,6EAA6E;IAC7E,KAAK,CAAC,EAAE,CAAC,CAAC,SAAS,CAAC;IACpB,mEAAmE;IACnE,KAAK,EAAE,CAAC,CAAC,OAAO,CAAC;IACjB,oCAAoC;IACpC,MAAM,EAAE,CAAC,CAAC,OAAO,CAAC;IAClB;;;;;;OAMG;IACH,UAAU,CAAC,EAAE,YAAY,CAAC;IAC1B;;;;;;;;OAQG;IACH,MAAM,CAAC,EAAE,iBAAiB,CAAC;IAC3B;;;;;;;;;OASG;IACH,WAAW,CAAC,EAAE,OAAO,CAAC;CACtB;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,eAAe,GAAI,CAAC,EAAE,GAAG,OAAO,KAAG,CAE/C,CAAC;AAEF;;;;;;;;;;GAUG;AACH,eAAO,MAAM,gBAAgB,GAAI,CAAC,EAAE,GAAG,OAAO,KAAG,CAEhD,CAAC;AAEF;;;;;;;GAOG;AACH,eAAO,MAAM,eAAe,GAAI,CAAC,EAAE,GAAG,OAAO,KAAG,CAE/C,CAAC;AAwIF;;;;;;GAMG;AACH,eAAO,MAAM,sBAAsB,GAAI,KAAK,IAAI,EAAE,OAAO,KAAK,CAAC,cAAc,CAAC,KAAG,IAIhF,CAAC;AAgCF;;;;;;;;;;;;;;;;;;;GAmBG;AACH,eAAO,MAAM,iBAAiB,GAC7B,KAAK,IAAI,EACT,OAAO,KAAK,CAAC,SAAS,CAAC,EACvB,qBAAqB,iBAAiB,EACtC,KAAK,MAAM,EACX,IAAI,EAAE,KACJ,IAsCF,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,kBAAkB,GAAI,QAAQ,MAAM,EAAE,OAAO,KAAK,CAAC,SAAS,CAAC,KAAG,KAAK,CAAC,SAAS,CAK3F,CAAC"}
+{"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/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"}

package/dist/rate_limiter.js

@@ -71,8 +71,13 @@ export 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, now = Date.now()) {
         const { max_attempts, window_ms } = this.options;
@@ -102,6 +107,7 @@ export 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, now = Date.now()) {
         const { max_attempts, window_ms } = this.options;
@@ -128,6 +134,8 @@ export class RateLimiter {
     }
     /**
      * Clear all attempts for `key` (e.g. after successful login).
+     *
+     * @mutates internal map - removes the entry for `key`
      */
     reset(key) {
         this.#attempts.delete(key);
@@ -136,6 +144,7 @@ export class RateLimiter {
      * 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 = Date.now()) {
         const cutoff = now - this.options.window_ms;
@@ -153,7 +162,11 @@ export class RateLimiter {
             }
         }
     }
-    /** 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() {
         if (this.#cleanup_timer !== null) {
             clearInterval(this.#cleanup_timer);

package/dist/realtime/sse.d.ts

@@ -47,7 +47,8 @@ export interface SseNotification {
  * Hono's HTML callback resolution — keeps the same `data: JSON\n\n` format.
  *
  * @param c - Hono context
- * @returns object with response and stream controller
+ * @param log - logger for serialization and `on_close` listener errors
+ * @returns object with the streaming `Response` and an `SseStream` controller
  */
 export declare const create_sse_response: <T = unknown>(c: Context, log: Logger) => {
     response: Response;
@@ -57,9 +58,13 @@ export declare const create_sse_response: <T = unknown>(c: Context, log: Logger)
 export declare const SSE_CONNECTED_COMMENT = ": connected\n\n";
 /** Spec for a push event — declares params schema, description, and channel. */
 export interface EventSpec {
+    /** Event method name, used as the JSON-RPC notification `method`. */
     method: string;
+    /** Zod schema for the notification `params` payload. */
     params: z.ZodType;
+    /** Human-readable description for surface output and docs. */
     description: string;
+    /** Channel this event broadcasts on. Omit for cross-channel events. */
     channel?: string;
 }
 /**
@@ -70,6 +75,7 @@ export interface EventSpec {
  *
  * @param broadcaster - duck-typed broadcaster (e.g. `SubscriberRegistry`)
  * @param event_specs - event specs to validate against
+ * @param log - logger used to emit DEV warnings on unknown methods or param mismatches
  * @returns validated broadcaster wrapper (passthrough in production)
  */
 export declare const create_validated_broadcaster: <T extends SseNotification>(broadcaster: {

package/dist/realtime/sse.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"sse.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/realtime/sse.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAC,OAAO,EAAC,MAAM,MAAM,CAAC;AAElC,OAAO,EAAC,CAAC,EAAC,MAAM,KAAK,CAAC;AAEtB,OAAO,KAAK,EAAC,MAAM,EAAC,MAAM,yBAAyB,CAAC;AAEpD;;;;GAIG;AACH,MAAM,WAAW,SAAS,CAAC,CAAC,GAAG,OAAO;IACrC,mDAAmD;IACnD,IAAI,EAAE,CAAC,IAAI,EAAE,CAAC,KAAK,IAAI,CAAC;IACxB,6CAA6C;IAC7C,OAAO,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IAChC,wBAAwB;IACxB,KAAK,EAAE,MAAM,IAAI,CAAC;IAClB,+FAA+F;IAC/F,QAAQ,EAAE,CAAC,EAAE,EAAE,MAAM,IAAI,KAAK,IAAI,CAAC;CACnC;AAED;;;;GAIG;AACH,MAAM,WAAW,eAAe;IAC/B,qEAAqE;IACrE,MAAM,EAAE,MAAM,CAAC;IACf,+BAA+B;IAC/B,MAAM,EAAE,OAAO,CAAC;CAChB;AAED;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,mBAAmB,GAAI,CAAC,GAAG,OAAO,EAC9C,GAAG,OAAO,EACV,KAAK,MAAM,KACT;IAAC,QAAQ,EAAE,QAAQ,CAAC;IAAC,MAAM,EAAE,SAAS,CAAC,CAAC,CAAC,CAAA;CAiD3C,CAAC;AAEF,kGAAkG;AAClG,eAAO,MAAM,qBAAqB,oBAAoB,CAAC;AAEvD,gFAAgF;AAChF,MAAM,WAAW,SAAS;IACzB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,CAAC,CAAC,OAAO,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;;;;;;;;GASG;AACH,eAAO,MAAM,4BAA4B,GAAI,CAAC,SAAS,eAAe,EACrE,aAAa;IAAC,SAAS,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,KAAK,IAAI,CAAA;CAAC,EAC5D,aAAa,KAAK,CAAC,SAAS,CAAC,EAC7B,KAAK,MAAM,KACT;IAAC,SAAS,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,KAAK,IAAI,CAAA;CAmBhD,CAAC"}
+{"version":3,"file":"sse.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/realtime/sse.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAC,OAAO,EAAC,MAAM,MAAM,CAAC;AAElC,OAAO,EAAC,CAAC,EAAC,MAAM,KAAK,CAAC;AAEtB,OAAO,KAAK,EAAC,MAAM,EAAC,MAAM,yBAAyB,CAAC;AAEpD;;;;GAIG;AACH,MAAM,WAAW,SAAS,CAAC,CAAC,GAAG,OAAO;IACrC,mDAAmD;IACnD,IAAI,EAAE,CAAC,IAAI,EAAE,CAAC,KAAK,IAAI,CAAC;IACxB,6CAA6C;IAC7C,OAAO,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IAChC,wBAAwB;IACxB,KAAK,EAAE,MAAM,IAAI,CAAC;IAClB,+FAA+F;IAC/F,QAAQ,EAAE,CAAC,EAAE,EAAE,MAAM,IAAI,KAAK,IAAI,CAAC;CACnC;AAED;;;;GAIG;AACH,MAAM,WAAW,eAAe;IAC/B,qEAAqE;IACrE,MAAM,EAAE,MAAM,CAAC;IACf,+BAA+B;IAC/B,MAAM,EAAE,OAAO,CAAC;CAChB;AAED;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,mBAAmB,GAAI,CAAC,GAAG,OAAO,EAC9C,GAAG,OAAO,EACV,KAAK,MAAM,KACT;IAAC,QAAQ,EAAE,QAAQ,CAAC;IAAC,MAAM,EAAE,SAAS,CAAC,CAAC,CAAC,CAAA;CAiD3C,CAAC;AAEF,kGAAkG;AAClG,eAAO,MAAM,qBAAqB,oBAAoB,CAAC;AAEvD,gFAAgF;AAChF,MAAM,WAAW,SAAS;IACzB,qEAAqE;IACrE,MAAM,EAAE,MAAM,CAAC;IACf,wDAAwD;IACxD,MAAM,EAAE,CAAC,CAAC,OAAO,CAAC;IAClB,8DAA8D;IAC9D,WAAW,EAAE,MAAM,CAAC;IACpB,uEAAuE;IACvE,OAAO,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;;;;;;;;;GAUG;AACH,eAAO,MAAM,4BAA4B,GAAI,CAAC,SAAS,eAAe,EACrE,aAAa;IAAC,SAAS,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,KAAK,IAAI,CAAA;CAAC,EAC5D,aAAa,KAAK,CAAC,SAAS,CAAC,EAC7B,KAAK,MAAM,KACT;IAAC,SAAS,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,KAAK,IAAI,CAAA;CAmBhD,CAAC"}

package/dist/realtime/sse.js

@@ -21,7 +21,8 @@ import { DEV } from 'esm-env';
  * Hono's HTML callback resolution — keeps the same `data: JSON\n\n` format.
  *
  * @param c - Hono context
- * @returns object with response and stream controller
+ * @param log - logger for serialization and `on_close` listener errors
+ * @returns object with the streaming `Response` and an `SseStream` controller
  */
 export const create_sse_response = (c, log) => {
     const { promise, resolve } = Promise.withResolvers();
@@ -84,6 +85,7 @@ export const SSE_CONNECTED_COMMENT = `: connected\n\n`;
  *
  * @param broadcaster - duck-typed broadcaster (e.g. `SubscriberRegistry`)
  * @param event_specs - event specs to validate against
+ * @param log - logger used to emit DEV warnings on unknown methods or param mismatches
  * @returns validated broadcaster wrapper (passthrough in production)
  */
 export const create_validated_broadcaster = (broadcaster, event_specs, log) => {

package/dist/realtime/sse_auth_guard.d.ts

@@ -63,6 +63,24 @@ export interface AuditLogSse {
     /** The underlying registry — exposed for subscriber count monitoring. */
     registry: SubscriberRegistry<SseNotification>;
 }
+/**
+ * SSE event specs for audit log events.
+ *
+ * One spec per `AUDIT_EVENT_TYPES` entry, all sharing the `AuditLogEventJson` params schema.
+ * Pass to `create_app_server`'s `event_specs` for surface generation and DEV validation.
+ */
+export declare const AUDIT_LOG_EVENT_SPECS: Array<EventSpec>;
+/**
+ * Default max concurrent SSE subscribers per session scope for the audit log.
+ *
+ * The audit log SSE subscribes with `scope = session_hash` and
+ * `groups = [account_id]`. Only `scope` is capped — so this limits tabs
+ * per session. An account's total streams across all sessions is bounded
+ * transitively by `max_sessions × AUDIT_LOG_SSE_MAX_PER_SCOPE`. 10 tabs
+ * per session is a comfortable ceiling for normal use; consumers raising
+ * it above ~50 should consider server-side connection limits.
+ */
+export declare const AUDIT_LOG_SSE_MAX_PER_SCOPE = 10;
 /**
  * Create a complete audit log SSE setup with broadcasting and auth guard.
  *
@@ -70,6 +88,9 @@ export interface AuditLogSse {
  * call into a single object. The result satisfies `AuditLogRouteOptions['stream']`
  * and provides the `on_audit_event` callback for `CreateAppBackendOptions`.
  *
+ * @param options - factory options
+ * @returns audit log SSE setup (stream options + `on_audit_event` + registry)
+ *
  * @example
  * ```ts
  * const audit_sse = create_audit_log_sse({log});
@@ -83,28 +104,7 @@ export interface AuditLogSse {
  * // In create_app_server options:
  * event_specs: AUDIT_LOG_EVENT_SPECS,
  * ```
- *
- * @param options - factory options
- * @returns audit log SSE setup (stream options + on_audit_event + registry)
- */
-/**
- * SSE event specs for audit log events.
- *
- * One spec per `AUDIT_EVENT_TYPES` entry, all sharing the `AuditLogEventJson` params schema.
- * Pass to `create_app_server`'s `event_specs` for surface generation and DEV validation.
- */
-export declare const AUDIT_LOG_EVENT_SPECS: Array<EventSpec>;
-/**
- * Default max concurrent SSE subscribers per session scope for the audit log.
- *
- * The audit log SSE subscribes with `scope = session_hash` and
- * `groups = [account_id]`. Only `scope` is capped — so this limits tabs
- * per session. An account's total streams across all sessions is bounded
- * transitively by `max_sessions × AUDIT_LOG_SSE_MAX_PER_SCOPE`. 10 tabs
- * per session is a comfortable ceiling for normal use; consumers raising
- * it above ~50 should consider server-side connection limits.
  */
-export declare const AUDIT_LOG_SSE_MAX_PER_SCOPE = 10;
 export declare const create_audit_log_sse: (options: {
     /** Role required to access the SSE endpoint. Default `'admin'`. */
     role?: string;

package/dist/realtime/sse_auth_guard.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"sse_auth_guard.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/realtime/sse_auth_guard.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAC,MAAM,EAAC,MAAM,yBAAyB,CAAC;AAEpD,OAAO,EAGN,KAAK,aAAa,EAClB,MAAM,6BAA6B,CAAC;AACrC,OAAO,EAAC,kBAAkB,EAAE,KAAK,gBAAgB,EAAC,MAAM,0BAA0B,CAAC;AACnF,OAAO,KAAK,EAAC,SAAS,EAAE,eAAe,EAAE,SAAS,EAAC,MAAM,UAAU,CAAC;AAEpE,2DAA2D;AAC3D,eAAO,MAAM,iBAAiB,cAAc,CAAC;AAE7C;;;;;;;;;;GAUG;AACH,eAAO,MAAM,sBAAsB,EAAE,WAAW,CAAC,MAAM,CAKrD,CAAC;AAEH;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,qBAAqB,GAAI,CAAC,EACtC,UAAU,kBAAkB,CAAC,CAAC,CAAC,EAC/B,eAAe,MAAM,GAAG,IAAI,EAC5B,KAAK,MAAM,KACT,CAAC,CAAC,KAAK,EAAE,aAAa,KAAK,IAAI,CA6CjC,CAAC;AAEF;;;;;GAKG;AACH,MAAM,WAAW,WAAW;IAC3B,8FAA8F;IAC9F,SAAS,EAAE,CAAC,MAAM,EAAE,SAAS,CAAC,eAAe,CAAC,EAAE,OAAO,CAAC,EAAE,gBAAgB,KAAK,MAAM,IAAI,CAAC;IAC1F,kFAAkF;IAClF,GAAG,EAAE,MAAM,CAAC;IACZ,kGAAkG;IAClG,cAAc,EAAE,CAAC,KAAK,EAAE,aAAa,KAAK,IAAI,CAAC;IAC/C,yEAAyE;IACzE,QAAQ,EAAE,kBAAkB,CAAC,eAAe,CAAC,CAAC;CAC9C;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH;;;;;GAKG;AACH,eAAO,MAAM,qBAAqB,EAAE,KAAK,CAAC,SAAS,CAOlD,CAAC;AAEF;;;;;;;;;GASG;AACH,eAAO,MAAM,2BAA2B,KAAK,CAAC;AAE9C,eAAO,MAAM,oBAAoB,GAAI,SAAS;IAC7C,mEAAmE;IACnE,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,GAAG,EAAE,MAAM,CAAC;IACZ;;;;OAIG;IACH,aAAa,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAC9B,KAAG,WAgBH,CAAC"}
+{"version":3,"file":"sse_auth_guard.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/realtime/sse_auth_guard.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAC,MAAM,EAAC,MAAM,yBAAyB,CAAC;AAEpD,OAAO,EAGN,KAAK,aAAa,EAClB,MAAM,6BAA6B,CAAC;AACrC,OAAO,EAAC,kBAAkB,EAAE,KAAK,gBAAgB,EAAC,MAAM,0BAA0B,CAAC;AACnF,OAAO,KAAK,EAAC,SAAS,EAAE,eAAe,EAAE,SAAS,EAAC,MAAM,UAAU,CAAC;AAEpE,2DAA2D;AAC3D,eAAO,MAAM,iBAAiB,cAAc,CAAC;AAE7C;;;;;;;;;;GAUG;AACH,eAAO,MAAM,sBAAsB,EAAE,WAAW,CAAC,MAAM,CAKrD,CAAC;AAEH;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,qBAAqB,GAAI,CAAC,EACtC,UAAU,kBAAkB,CAAC,CAAC,CAAC,EAC/B,eAAe,MAAM,GAAG,IAAI,EAC5B,KAAK,MAAM,KACT,CAAC,CAAC,KAAK,EAAE,aAAa,KAAK,IAAI,CA6CjC,CAAC;AAEF;;;;;GAKG;AACH,MAAM,WAAW,WAAW;IAC3B,8FAA8F;IAC9F,SAAS,EAAE,CAAC,MAAM,EAAE,SAAS,CAAC,eAAe,CAAC,EAAE,OAAO,CAAC,EAAE,gBAAgB,KAAK,MAAM,IAAI,CAAC;IAC1F,kFAAkF;IAClF,GAAG,EAAE,MAAM,CAAC;IACZ,kGAAkG;IAClG,cAAc,EAAE,CAAC,KAAK,EAAE,aAAa,KAAK,IAAI,CAAC;IAC/C,yEAAyE;IACzE,QAAQ,EAAE,kBAAkB,CAAC,eAAe,CAAC,CAAC;CAC9C;AAED;;;;;GAKG;AACH,eAAO,MAAM,qBAAqB,EAAE,KAAK,CAAC,SAAS,CAOlD,CAAC;AAEF;;;;;;;;;GASG;AACH,eAAO,MAAM,2BAA2B,KAAK,CAAC;AAE9C;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,eAAO,MAAM,oBAAoB,GAAI,SAAS;IAC7C,mEAAmE;IACnE,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,GAAG,EAAE,MAAM,CAAC;IACZ;;;;OAIG;IACH,aAAa,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAC9B,KAAG,WAgBH,CAAC"}

package/dist/realtime/sse_auth_guard.js

@@ -92,30 +92,6 @@ export const create_sse_auth_guard = (registry, required_role, log) => {
         }
     };
 };
-/**
- * Create a complete audit log SSE setup with broadcasting and auth guard.
- *
- * Combines `SubscriberRegistry`, `create_sse_auth_guard`, and the broadcast
- * call into a single object. The result satisfies `AuditLogRouteOptions['stream']`
- * and provides the `on_audit_event` callback for `CreateAppBackendOptions`.
- *
- * @example
- * ```ts
- * const audit_sse = create_audit_log_sse({log});
- *
- * // In create_app_backend options:
- * on_audit_event: audit_sse.on_audit_event,
- *
- * // In create_route_specs:
- * create_audit_log_route_specs({stream: audit_sse});
- *
- * // In create_app_server options:
- * event_specs: AUDIT_LOG_EVENT_SPECS,
- * ```
- *
- * @param options - factory options
- * @returns audit log SSE setup (stream options + on_audit_event + registry)
- */
 /**
  * SSE event specs for audit log events.
  *
@@ -139,6 +115,30 @@ export const AUDIT_LOG_EVENT_SPECS = AUDIT_EVENT_TYPES.map((event_type) => ({
  * it above ~50 should consider server-side connection limits.
  */
 export const AUDIT_LOG_SSE_MAX_PER_SCOPE = 10;
+/**
+ * Create a complete audit log SSE setup with broadcasting and auth guard.
+ *
+ * Combines `SubscriberRegistry`, `create_sse_auth_guard`, and the broadcast
+ * call into a single object. The result satisfies `AuditLogRouteOptions['stream']`
+ * and provides the `on_audit_event` callback for `CreateAppBackendOptions`.
+ *
+ * @param options - factory options
+ * @returns audit log SSE setup (stream options + `on_audit_event` + registry)
+ *
+ * @example
+ * ```ts
+ * const audit_sse = create_audit_log_sse({log});
+ *
+ * // In create_app_backend options:
+ * on_audit_event: audit_sse.on_audit_event,
+ *
+ * // In create_route_specs:
+ * create_audit_log_route_specs({stream: audit_sse});
+ *
+ * // In create_app_server options:
+ * event_specs: AUDIT_LOG_EVENT_SPECS,
+ * ```
+ */
 export const create_audit_log_sse = (options) => {
     const role = options.role ?? 'admin';
     const max_per_scope = options.max_per_scope === undefined ? AUDIT_LOG_SSE_MAX_PER_SCOPE : options.max_per_scope;

package/dist/realtime/subscriber_registry.d.ts

@@ -101,8 +101,9 @@ export declare class SubscriberRegistry<T> {
      * Add a subscriber.
      *
      * @param stream - SSE stream to send data to
-     * @param options - channel filter and identity slots (scope + groups)
+     * @param options - channel filter and identity slots (`scope` + `groups`)
      * @returns unsubscribe function
+     * @mutates registry - adds the new subscriber; closes oldest matching subscribers when `max_per_scope` is exceeded
      */
     subscribe(stream: SseStream<T>, options?: SubscribeOptions): () => void;
     /**
@@ -122,8 +123,9 @@ export declare class SubscriberRegistry<T> {
      * Use for auth revocation — when a user's permissions change, close their
      * SSE connections so they must reconnect and re-authenticate.
      *
-     * @param identity - the identity key to match (checked against scope and groups)
+     * @param identity - the identity key to match (checked against `scope` and `groups`)
      * @returns the number of subscribers closed
+     * @mutates registry - removes matching subscribers and closes their streams
      */
     close_by_identity(identity: string): number;
 }