@fuzdev/fuz_app 0.38.1 → 0.40.0

package/dist/auth/self_service_role_actions.js

@@ -0,0 +1,198 @@
+/**
+ * Self-service role grant/revoke RPC actions.
+ *
+ * Two static `request_response` actions — `self_service_role_grant` and
+ * `self_service_role_revoke` — that take `{role}` as input and toggle a
+ * permit on the caller for an allowlisted role. Idempotent in both
+ * directions: re-granting an already-held role returns `granted: false`;
+ * revoking a role the caller doesn't hold returns `revoked: false`.
+ *
+ * The factory takes an `eligible_roles` allowlist (validated against the
+ * supplied `roles.role_options` at factory time so typos surface at startup
+ * instead of at first call). Roles outside the allowlist are rejected
+ * with `forbidden` + reason `role_not_self_service_eligible`.
+ *
+ * Audit metadata carries `self_service: true` so admin reviewers can
+ * distinguish self-toggled permits from admin grants/offers. The
+ * `permit_grant` / `permit_revoke` metadata schemas declare
+ * `self_service: z.boolean().optional()` explicitly, so the field is
+ * part of the documented schema surface and is round-trip-validated by
+ * `query_audit_log`.
+ *
+ * Static method names — `role` lives in the input, not the method name —
+ * so specs are codegen-compatible (`satisfies RequestResponseActionSpec`)
+ * and the surface stays constant as consumers add eligible roles. Mirrors
+ * the existing `permit_offer_create({role})` precedent rather than
+ * generating per-role methods.
+ *
+ * @module
+ */
+import { z } from 'zod';
+import { rpc_action } from '../actions/action_rpc.js';
+import { jsonrpc_errors } from '../http/jsonrpc_errors.js';
+import { Uuid } from '../uuid.js';
+import { RoleName } from './role_schema.js';
+import { query_grant_permit, query_permit_find_active_for_actor, query_permit_has_role, query_revoke_permit, } from './permit_queries.js';
+import { audit_log_fire_and_forget } from './audit_log_queries.js';
+/** Error reason — caller asked to self-toggle a role outside the configured allowlist. */
+export const ERROR_ROLE_NOT_SELF_SERVICE_ELIGIBLE = 'role_not_self_service_eligible';
+// -- Input/output schemas ---------------------------------------------------
+/** Input for `self_service_role_grant`. */
+export const SelfServiceRoleGrantInput = z.strictObject({
+    role: RoleName.meta({ description: 'Role to self-grant. Must be in the configured allowlist.' }),
+});
+/**
+ * Output for `self_service_role_grant`. `granted` is `false` on idempotent
+ * re-grant (caller already held the role globally); `permit_id` is set on
+ * new grants only.
+ */
+export const SelfServiceRoleGrantOutput = z.strictObject({
+    ok: z.literal(true),
+    granted: z.boolean(),
+    permit_id: Uuid.optional(),
+});
+/** Input for `self_service_role_revoke`. */
+export const SelfServiceRoleRevokeInput = z.strictObject({
+    role: RoleName.meta({ description: 'Role to self-revoke. Must be in the configured allowlist.' }),
+});
+/**
+ * Output for `self_service_role_revoke`. `revoked` is `false` when the
+ * caller held no active global permit for the role (idempotent).
+ */
+export const SelfServiceRoleRevokeOutput = z.strictObject({
+    ok: z.literal(true),
+    revoked: z.boolean(),
+});
+// -- Action specs -----------------------------------------------------------
+export const self_service_role_grant_action_spec = {
+    method: 'self_service_role_grant',
+    kind: 'request_response',
+    initiator: 'frontend',
+    auth: 'authenticated',
+    side_effects: true,
+    input: SelfServiceRoleGrantInput,
+    output: SelfServiceRoleGrantOutput,
+    async: true,
+    description: 'Self-grant an active permit for an allowlisted role. Idempotent — already-granted callers receive `granted: false`.',
+};
+export const self_service_role_revoke_action_spec = {
+    method: 'self_service_role_revoke',
+    kind: 'request_response',
+    initiator: 'frontend',
+    auth: 'authenticated',
+    side_effects: true,
+    input: SelfServiceRoleRevokeInput,
+    output: SelfServiceRoleRevokeOutput,
+    async: true,
+    description: 'Self-revoke an active global permit for an allowlisted role. Idempotent — callers without an active permit receive `revoked: false`.',
+};
+/**
+ * All self-service role action specs — a codegen-ready registry. Method
+ * names are static, so consumer typed-client codegen picks them up the
+ * same way it picks up `account_*_action_specs`.
+ */
+export const all_self_service_role_action_specs = [
+    self_service_role_grant_action_spec,
+    self_service_role_revoke_action_spec,
+];
+const require_request_auth = (auth) => {
+    if (!auth)
+        throw new Error('unreachable: action auth guard did not enforce authentication');
+    return auth;
+};
+/**
+ * Build the self-service role grant/revoke RPC actions.
+ *
+ * @param deps - `SelfServiceRoleActionDeps` slice of `AppDeps` (`log`, `on_audit_event`, optional `audit_log_config`)
+ * @param options - eligible-role allowlist plus optional role schema for typo-checking
+ * @returns the `RpcAction` array to spread into a `create_rpc_endpoint` call
+ */
+export const create_self_service_role_actions = (deps, options) => {
+    const eligible = new Set(options.eligible_roles);
+    if (options.roles) {
+        const role_options = options.roles.role_options;
+        for (const r of eligible) {
+            if (!role_options.has(r)) {
+                throw new Error(`create_self_service_role_actions: eligible_roles entry "${r}" is not registered in roles.role_options — typo or missing call to create_role_schema`);
+            }
+        }
+    }
+    const reject_if_ineligible = (role) => {
+        if (!eligible.has(role)) {
+            throw jsonrpc_errors.forbidden('role not eligible for self-service', {
+                reason: ERROR_ROLE_NOT_SELF_SERVICE_ELIGIBLE,
+            });
+        }
+    };
+    const grant_handler = async (input, ctx) => {
+        const auth = require_request_auth(ctx.auth);
+        reject_if_ineligible(input.role);
+        // Pre-check for idempotent re-grant. `query_grant_permit` is itself
+        // idempotent (returns the existing permit instead of inserting), but
+        // it doesn't signal "already existed" vs "newly inserted" — so we
+        // peek first. The TOCTOU window is benign for self-service: two
+        // concurrent grants both observe "no permit", both call
+        // `query_grant_permit`, and one collapses onto the other inside the
+        // query's `ON CONFLICT DO NOTHING`. Worst case both responses report
+        // `granted: true`; the DB still ends up with exactly one permit.
+        const already = await query_permit_has_role(ctx, auth.actor.id, input.role);
+        if (already) {
+            return { ok: true, granted: false };
+        }
+        const permit = await query_grant_permit(ctx, {
+            actor_id: auth.actor.id,
+            role: input.role,
+            scope_id: null,
+            expires_at: null,
+            granted_by: auth.actor.id,
+        });
+        void audit_log_fire_and_forget(ctx, {
+            event_type: 'permit_grant',
+            actor_id: auth.actor.id,
+            account_id: auth.account.id,
+            ip: ctx.client_ip,
+            metadata: {
+                role: permit.role,
+                permit_id: permit.id,
+                scope_id: permit.scope_id,
+                self_service: true,
+            },
+        }, deps);
+        return { ok: true, granted: true, permit_id: permit.id };
+    };
+    const revoke_handler = async (input, ctx) => {
+        const auth = require_request_auth(ctx.auth);
+        reject_if_ineligible(input.role);
+        // Find an active global permit for this (actor, role). No dedicated
+        // query exists, but `query_permit_find_active_for_actor` returns the
+        // short list of every active permit and we filter in JS — fewer
+        // round-trips than a new helper for a one-call-per-revoke path.
+        const active = await query_permit_find_active_for_actor(ctx, auth.actor.id);
+        const target = active.find((p) => p.role === input.role && p.scope_id === null);
+        if (!target) {
+            return { ok: true, revoked: false };
+        }
+        const result = await query_revoke_permit(ctx, target.id, auth.actor.id, auth.actor.id);
+        if (!result) {
+            // Raced with another revoker — treat as already revoked.
+            return { ok: true, revoked: false };
+        }
+        void audit_log_fire_and_forget(ctx, {
+            event_type: 'permit_revoke',
+            actor_id: auth.actor.id,
+            account_id: auth.account.id,
+            ip: ctx.client_ip,
+            metadata: {
+                role: result.role,
+                permit_id: result.id,
+                scope_id: result.scope_id,
+                self_service: true,
+            },
+        }, deps);
+        return { ok: true, revoked: true };
+    };
+    return [
+        rpc_action(self_service_role_grant_action_spec, grant_handler),
+        rpc_action(self_service_role_revoke_action_spec, revoke_handler),
+    ];
+};

package/dist/auth/signup_routes.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"signup_routes.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/auth/signup_routes.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAC,CAAC,EAAC,MAAM,KAAK,CAAC;AAStB,OAAO,EAAkB,KAAK,SAAS,EAAC,MAAM,uBAAuB,CAAC;AAEtE,OAAO,EAA+B,KAAK,WAAW,EAAC,MAAM,oBAAoB,CAAC;AAClF,OAAO,KAAK,EAAC,gBAAgB,EAAC,MAAM,WAAW,CAAC;AAQhD,OAAO,KAAK,EAAC,WAAW,EAAC,MAAM,0BAA0B,CAAC;AAE1D,OAAO,KAAK,EAAC,uBAAuB,EAAC,MAAM,qBAAqB,CAAC;AAEjE;;GAEG;AACH,MAAM,WAAW,kBAAmB,SAAQ,uBAAuB;IAClE,6FAA6F;IAC7F,2BAA2B,EAAE,WAAW,GAAG,IAAI,CAAC;IAChD,yFAAyF;IACzF,YAAY,EAAE,WAAW,CAAC;CAC1B;AAID,0FAA0F;AAC1F,eAAO,MAAM,WAAW;;;;kBAItB,CAAC;AACH,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,WAAW,CAAC,CAAC;AAEtD,8EAA8E;AAC9E,eAAO,MAAM,YAAY;;kBAEvB,CAAC;AACH,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,YAAY,CAAC,CAAC;AAExD;;;;;;GAMG;AACH,eAAO,MAAM,yBAAyB,GACrC,MAAM,gBAAgB,EACtB,SAAS,kBAAkB,KACzB,KAAK,CAAC,SAAS,CA4HjB,CAAC"}
+{"version":3,"file":"signup_routes.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/auth/signup_routes.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAC,CAAC,EAAC,MAAM,KAAK,CAAC;AAStB,OAAO,EAAkB,KAAK,SAAS,EAAC,MAAM,uBAAuB,CAAC;AAEtE,OAAO,EAA+B,KAAK,WAAW,EAAC,MAAM,oBAAoB,CAAC;AAClF,OAAO,KAAK,EAAC,gBAAgB,EAAC,MAAM,WAAW,CAAC;AAQhD,OAAO,KAAK,EAAC,WAAW,EAAC,MAAM,0BAA0B,CAAC;AAE1D,OAAO,KAAK,EAAC,uBAAuB,EAAC,MAAM,qBAAqB,CAAC;AAEjE;;GAEG;AACH,MAAM,WAAW,kBAAmB,SAAQ,uBAAuB;IAClE,6FAA6F;IAC7F,2BAA2B,EAAE,WAAW,GAAG,IAAI,CAAC;IAChD,yFAAyF;IACzF,YAAY,EAAE,WAAW,CAAC;CAC1B;AAID,0FAA0F;AAC1F,eAAO,MAAM,WAAW;;;;kBAItB,CAAC;AACH,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,WAAW,CAAC,CAAC;AAEtD,8EAA8E;AAC9E,eAAO,MAAM,YAAY;;kBAEvB,CAAC;AACH,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,YAAY,CAAC,CAAC;AAExD;;;;;;GAMG;AACH,eAAO,MAAM,yBAAyB,GACrC,MAAM,gBAAgB,EACtB,SAAS,kBAAkB,KACzB,KAAK,CAAC,SAAS,CA2HjB,CAAC"}

package/dist/auth/signup_routes.js

@@ -38,7 +38,7 @@ export const SignupOutput = z.strictObject({
  * @returns route specs (not yet applied to Hono)
  */
 export const create_signup_route_specs = (deps, options) => {
-    const { keyring, password, on_audit_event } = deps;
+    const { keyring, password } = deps;
     const { session_options, ip_rate_limiter, signup_account_rate_limiter, app_settings } = options;
     return [
         {
@@ -144,7 +144,7 @@ export const create_signup_route_specs = (deps, options) => {
                     account_id: result.id,
                     ip: get_client_ip(c),
                     metadata: invite ? { invite_id: invite.id, username } : { open_signup: true, username },
-                }, deps.log, on_audit_event);
+                }, deps);
                 return c.json({ ok: true });
             },
         },

package/dist/auth/standard_rpc_actions.d.ts

@@ -49,7 +49,7 @@ export type StandardRpcActionsDeps = PermitOfferActionDeps;
  * and `create_account_actions(deps, {max_tokens})`. The shared `roles`
  * option flows to admin + permit-offer.
  *
- * @param deps - stateless capabilities (log, on_audit_event, optional notification_sender)
+ * @param deps - `StandardRpcActionsDeps` (`log`, `on_audit_event`, optional `audit_log_config` from `AppDeps`; optional `notification_sender` for WS fan-out)
  * @param options - role schema, optional app-settings ref, permit-offer config, account config
  * @returns RPC actions to pass as `rpc_endpoints` or spread into `create_rpc_endpoint`
  */

package/dist/auth/standard_rpc_actions.js

@@ -28,7 +28,7 @@ import { create_account_actions } from './account_actions.js';
  * and `create_account_actions(deps, {max_tokens})`. The shared `roles`
  * option flows to admin + permit-offer.
  *
- * @param deps - stateless capabilities (log, on_audit_event, optional notification_sender)
+ * @param deps - `StandardRpcActionsDeps` (`log`, `on_audit_event`, optional `audit_log_config` from `AppDeps`; optional `notification_sender` for WS fan-out)
  * @param options - role schema, optional app-settings ref, permit-offer config, account config
  * @returns RPC actions to pass as `rpc_endpoints` or spread into `create_rpc_endpoint`
  */

package/dist/http/jsonrpc_errors.d.ts

@@ -27,71 +27,22 @@ export type JsonrpcErrorName = 'parse_error' | 'invalid_request' | 'method_not_f
  * Extensible — consumers add domain-specific codes to their own objects
  * by casting `as JsonrpcErrorCode`. Application codes use the -32000 to
  * -32099 range reserved by the JSON-RPC spec.
+ *
+ * Frozen with `Object.freeze` to convert accidental mutation (test
+ * cross-contamination, cast escapes) into loud TypeErrors. Spread into
+ * a fresh object to extend.
  */
-export declare const JSONRPC_ERROR_CODES: {
-    readonly parse_error: JsonrpcErrorCode;
-    readonly invalid_request: JsonrpcErrorCode;
-    readonly method_not_found: JsonrpcErrorCode;
-    readonly invalid_params: JsonrpcErrorCode;
-    readonly internal_error: JsonrpcErrorCode;
-    /**
-     * Same as HTTP 401 "unauthorized", but correctly named.
-     *
-     * @see https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Status#client_error_responses
-     */
-    readonly unauthenticated: JsonrpcErrorCode;
-    /**
-     * Named to match HTTP 403 — avoids confusion with 401 which
-     * is incorrectly named "unauthorized" in HTTP.
-     */
-    readonly forbidden: JsonrpcErrorCode;
-    readonly not_found: JsonrpcErrorCode;
-    readonly conflict: JsonrpcErrorCode;
-    /**
-     * Application-level validation failures (business logic).
-     * Use `invalid_params` (-32602) for schema/parsing failures.
-     */
-    readonly validation_error: JsonrpcErrorCode;
-    readonly rate_limited: JsonrpcErrorCode;
-    readonly service_unavailable: JsonrpcErrorCode;
-    readonly timeout: JsonrpcErrorCode;
-    /**
-     * Client-side backpressure — an outbound buffer (e.g. `FrontendWebsocketClient`'s
-     * disconnected request queue) refused a new request because it was full.
-     * Distinct from `rate_limited`, which signals a server-side policy.
-     */
-    readonly queue_overflow: JsonrpcErrorCode;
-    /**
-     * Caller-initiated cancellation (e.g. `AbortSignal` fired). Cooperative,
-     * not a failure — the request did not complete because the caller asked
-     * for it to stop.
-     */
-    readonly request_cancelled: JsonrpcErrorCode;
-};
+export declare const JSONRPC_ERROR_CODES: Readonly<Record<JsonrpcErrorName, JsonrpcErrorCode>>;
 /**
  * Named constructors for `JsonrpcErrorObject` values.
  *
  * Each function creates a JSON-RPC error object with the correct
  * code and a sensible default message. Used by the catch layer in
  * `apply_route_specs` to build response bodies.
+ *
+ * Frozen so tests must compose new objects rather than monkey-patch.
  */
-export declare const jsonrpc_error_messages: {
-    readonly parse_error: (data?: unknown) => JsonrpcErrorObject;
-    readonly invalid_request: (data?: unknown) => JsonrpcErrorObject;
-    readonly method_not_found: (method?: string, data?: unknown) => JsonrpcErrorObject;
-    readonly invalid_params: (message?: string, data?: unknown) => JsonrpcErrorObject;
-    readonly internal_error: (message?: string, data?: unknown) => JsonrpcErrorObject;
-    readonly unauthenticated: (message?: string, data?: unknown) => JsonrpcErrorObject;
-    readonly forbidden: (message?: string, data?: unknown) => JsonrpcErrorObject;
-    readonly not_found: (resource?: string, data?: unknown) => JsonrpcErrorObject;
-    readonly conflict: (message?: string, data?: unknown) => JsonrpcErrorObject;
-    readonly validation_error: (message?: string, data?: unknown) => JsonrpcErrorObject;
-    readonly rate_limited: (message?: string, data?: unknown) => JsonrpcErrorObject;
-    readonly service_unavailable: (message?: string, data?: unknown) => JsonrpcErrorObject;
-    readonly timeout: (message?: string, data?: unknown) => JsonrpcErrorObject;
-    readonly queue_overflow: (message?: string, data?: unknown) => JsonrpcErrorObject;
-    readonly request_cancelled: (message?: string, data?: unknown) => JsonrpcErrorObject;
-};
+export declare const jsonrpc_error_messages: Readonly<Record<JsonrpcErrorName, (...args: Array<any>) => JsonrpcErrorObject>>;
 /**
  * Error class carrying a JSON-RPC error code — thrown by handlers,
  * caught by `apply_route_specs` and mapped to HTTP status + JSON-RPC error response.
@@ -109,29 +60,30 @@ export declare class ThrownJsonrpcError extends Error {
  * Usage: `throw jsonrpc_errors.not_found('user')` or `throw jsonrpc_errors.forbidden()`.
  */
 export declare const jsonrpc_errors: {
-    readonly parse_error: (data?: unknown) => ThrownJsonrpcError;
-    readonly invalid_request: (data?: unknown) => ThrownJsonrpcError;
-    readonly method_not_found: (method?: string | undefined, data?: unknown) => ThrownJsonrpcError;
-    readonly invalid_params: (message?: string | undefined, data?: unknown) => ThrownJsonrpcError;
-    readonly internal_error: (message?: string | undefined, data?: unknown) => ThrownJsonrpcError;
-    readonly unauthenticated: (message?: string | undefined, data?: unknown) => ThrownJsonrpcError;
-    readonly forbidden: (message?: string | undefined, data?: unknown) => ThrownJsonrpcError;
-    readonly not_found: (resource?: string | undefined, data?: unknown) => ThrownJsonrpcError;
-    readonly conflict: (message?: string | undefined, data?: unknown) => ThrownJsonrpcError;
-    readonly validation_error: (message?: string | undefined, data?: unknown) => ThrownJsonrpcError;
-    readonly rate_limited: (message?: string | undefined, data?: unknown) => ThrownJsonrpcError;
-    readonly service_unavailable: (message?: string | undefined, data?: unknown) => ThrownJsonrpcError;
-    readonly timeout: (message?: string | undefined, data?: unknown) => ThrownJsonrpcError;
-    readonly queue_overflow: (message?: string | undefined, data?: unknown) => ThrownJsonrpcError;
-    readonly request_cancelled: (message?: string | undefined, data?: unknown) => ThrownJsonrpcError;
+    readonly parse_error: (...args: any[]) => ThrownJsonrpcError;
+    readonly invalid_request: (...args: any[]) => ThrownJsonrpcError;
+    readonly method_not_found: (...args: any[]) => ThrownJsonrpcError;
+    readonly invalid_params: (...args: any[]) => ThrownJsonrpcError;
+    readonly internal_error: (...args: any[]) => ThrownJsonrpcError;
+    readonly unauthenticated: (...args: any[]) => ThrownJsonrpcError;
+    readonly forbidden: (...args: any[]) => ThrownJsonrpcError;
+    readonly not_found: (...args: any[]) => ThrownJsonrpcError;
+    readonly conflict: (...args: any[]) => ThrownJsonrpcError;
+    readonly validation_error: (...args: any[]) => ThrownJsonrpcError;
+    readonly rate_limited: (...args: any[]) => ThrownJsonrpcError;
+    readonly service_unavailable: (...args: any[]) => ThrownJsonrpcError;
+    readonly timeout: (...args: any[]) => ThrownJsonrpcError;
+    readonly queue_overflow: (...args: any[]) => ThrownJsonrpcError;
+    readonly request_cancelled: (...args: any[]) => ThrownJsonrpcError;
 };
 /**
  * Maps JSON-RPC error codes to HTTP status codes.
  *
  * Extensible — consumers with domain-specific error codes can spread
- * this into their own mapping object.
+ * this into their own mapping object. Frozen so the source can't be
+ * accidentally mutated; spread copies are mutable.
  */
-export declare const JSONRPC_ERROR_CODE_TO_HTTP_STATUS: Record<number, number>;
+export declare const JSONRPC_ERROR_CODE_TO_HTTP_STATUS: Readonly<Record<number, number>>;
 /**
  * Maps HTTP status codes to JSON-RPC error codes (reverse mapping).
  *
@@ -139,7 +91,7 @@ export declare const JSONRPC_ERROR_CODE_TO_HTTP_STATUS: Record<number, number>;
  * and invalid_request both map to 400), the last one wins. Use for
  * best-effort HTTP → JSON-RPC translation.
  */
-export declare const HTTP_STATUS_TO_JSONRPC_ERROR_CODE: Record<number, JsonrpcErrorCode>;
+export declare const HTTP_STATUS_TO_JSONRPC_ERROR_CODE: Readonly<Record<number, JsonrpcErrorCode>>;
 /**
  * Map a JSON-RPC error code to an HTTP status code.
  *

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

@@ -1 +1 @@
-{"version":3,"file":"jsonrpc_errors.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/http/jsonrpc_errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,EAMN,KAAK,gBAAgB,EACrB,KAAK,kBAAkB,EACvB,MAAM,cAAc,CAAC;AAEtB,0CAA0C;AAC1C,eAAO,MAAM,qBAAqB,kBAAkB,CAAC;AAErD,sEAAsE;AACtE,MAAM,MAAM,gBAAgB,GACzB,aAAa,GACb,iBAAiB,GACjB,kBAAkB,GAClB,gBAAgB,GAChB,gBAAgB,GAChB,iBAAiB,GACjB,WAAW,GACX,WAAW,GACX,UAAU,GACV,kBAAkB,GAClB,cAAc,GACd,qBAAqB,GACrB,SAAS,GACT,gBAAgB,GAChB,mBAAmB,CAAC;AAEvB;;;;;;GAMG;AACH,eAAO,MAAM,mBAAmB;0BAEK,gBAAgB;8BACR,gBAAgB;+BACd,gBAAgB;6BACpB,gBAAgB;6BAChB,gBAAgB;IAG1D;;;;OAIG;8BACwB,gBAAgB;IAC3C;;;OAGG;wBACkB,gBAAgB;wBAChB,gBAAgB;uBACjB,gBAAgB;IACpC;;;OAGG;+BACyB,gBAAgB;2BACpB,gBAAgB;kCACT,gBAAgB;sBAC5B,gBAAgB;IACnC;;;;OAIG;6BACuB,gBAAgB;IAC1C;;;;OAIG;gCAC0B,gBAAgB;CACiB,CAAC;AAEhE;;;;;;GAMG;AACH,eAAO,MAAM,sBAAsB;kCACb,OAAO,KAAG,kBAAkB;sCAMxB,OAAO,KAAG,kBAAkB;yCAMzB,MAAM,SAAS,OAAO,KAAG,kBAAkB;wCAM5C,MAAM,SAAS,OAAO,KAAG,kBAAkB;wCAO5D,MAAM,SACR,OAAO,KACZ,kBAAkB;yCAMM,MAAM,SAA6B,OAAO,KAAG,kBAAkB;mCAMrE,MAAM,SAAuB,OAAO,KAAG,kBAAkB;oCAMvD,MAAM,SAAS,OAAO,KAAG,kBAAkB;kCAM9C,MAAM,SAAsB,OAAO,KAAG,kBAAkB;0CAMhD,MAAM,SAA8B,OAAO,KAAG,kBAAkB;sCAMpE,MAAM,SAA0B,OAAO,KAAG,kBAAkB;6CAO1E,MAAM,SACR,OAAO,KACZ,kBAAkB;iCAMF,MAAM,SAAqB,OAAO,KAAG,kBAAkB;wCAMhD,MAAM,SAA4B,OAAO,KAAG,kBAAkB;2CAO9E,MAAM,SACR,OAAO,KACZ,kBAAkB;CAKoE,CAAC;AAE3F;;;;;GAKG;AACH,qBAAa,kBAAmB,SAAQ,KAAK;IAC5C,IAAI,EAAE,gBAAgB,CAAC;IACvB,IAAI,CAAC,EAAE,OAAO,CAAC;gBAEH,IAAI,EAAE,gBAAgB,EAAE,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,EAAE,OAAO,CAAC,EAAE,YAAY;CAK3F;AAWD;;;;GAIG;AACH,eAAO,MAAM,cAAc;8CAXQ,kBAAkB;kDAAlB,kBAAkB;gFAAlB,kBAAkB;+EAAlB,kBAAkB;+EAAlB,kBAAkB;gFAAlB,kBAAkB;0EAAlB,kBAAkB;2EAAlB,kBAAkB;yEAAlB,kBAAkB;iFAAlB,kBAAkB;6EAAlB,kBAAkB;oFAAlB,kBAAkB;wEAAlB,kBAAkB;+EAAlB,kBAAkB;kFAAlB,kBAAkB;CA2BqC,CAAC;AAI3F;;;;;GAKG;AACH,eAAO,MAAM,iCAAiC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAkBpE,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,iCAAiC,EAAE,MAAM,CAAC,MAAM,EAAE,gBAAgB,CAMzC,CAAC;AAEvC;;;;;;;;GAQG;AACH,eAAO,MAAM,iCAAiC,GAAI,MAAM,gBAAgB,KAAG,MAClB,CAAC;AAE1D;;;;;;;GAOG;AACH,eAAO,MAAM,iCAAiC,GAAI,QAAQ,MAAM,KAAG,gBACa,CAAC"}
+{"version":3,"file":"jsonrpc_errors.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/http/jsonrpc_errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,EAMN,KAAK,gBAAgB,EACrB,KAAK,kBAAkB,EACvB,MAAM,cAAc,CAAC;AAEtB,0CAA0C;AAC1C,eAAO,MAAM,qBAAqB,kBAAkB,CAAC;AAErD,sEAAsE;AACtE,MAAM,MAAM,gBAAgB,GACzB,aAAa,GACb,iBAAiB,GACjB,kBAAkB,GAClB,gBAAgB,GAChB,gBAAgB,GAChB,iBAAiB,GACjB,WAAW,GACX,WAAW,GACX,UAAU,GACV,kBAAkB,GAClB,cAAc,GACd,qBAAqB,GACrB,SAAS,GACT,gBAAgB,GAChB,mBAAmB,CAAC;AAEvB;;;;;;;;;;GAUG;AACH,eAAO,MAAM,mBAAmB,EA0C1B,QAAQ,CAAC,MAAM,CAAC,gBAAgB,EAAE,gBAAgB,CAAC,CAAC,CAAC;AAE3D;;;;;;;;GAQG;AACH,eAAO,MAAM,sBAAsB,EAmG7B,QAAQ,CAAC,MAAM,CAAC,gBAAgB,EAAE,CAAC,GAAG,IAAI,EAAE,KAAK,CAAC,GAAG,CAAC,KAAK,kBAAkB,CAAC,CAAC,CAAC;AAEtF;;;;;GAKG;AACH,qBAAa,kBAAmB,SAAQ,KAAK;IAC5C,IAAI,EAAE,gBAAgB,CAAC;IACvB,IAAI,CAAC,EAAE,OAAO,CAAC;gBAEH,IAAI,EAAE,gBAAgB,EAAE,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,EAAE,OAAO,CAAC,EAAE,YAAY;CAK3F;AAWD;;;;GAIG;AACH,eAAO,MAAM,cAAc;8CAXQ,kBAAkB;kDAAlB,kBAAkB;mDAAlB,kBAAkB;iDAAlB,kBAAkB;iDAAlB,kBAAkB;kDAAlB,kBAAkB;4CAAlB,kBAAkB;4CAAlB,kBAAkB;2CAAlB,kBAAkB;mDAAlB,kBAAkB;+CAAlB,kBAAkB;sDAAlB,kBAAkB;0CAAlB,kBAAkB;iDAAlB,kBAAkB;oDAAlB,kBAAkB;CA2BqC,CAAC;AAI3F;;;;;;GAMG;AACH,eAAO,MAAM,iCAAiC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAkB7E,CAAC;AAEH;;;;;;GAMG;AACH,eAAO,MAAM,iCAAiC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,gBAAgB,CAAC,CAQvF,CAAC;AAEH;;;;;;;;GAQG;AACH,eAAO,MAAM,iCAAiC,GAAI,MAAM,gBAAgB,KAAG,MAClB,CAAC;AAE1D;;;;;;;GAOG;AACH,eAAO,MAAM,iCAAiC,GAAI,QAAQ,MAAM,KAAG,gBACa,CAAC"}

package/dist/http/jsonrpc_errors.js

@@ -25,8 +25,12 @@ export const UNKNOWN_ERROR_MESSAGE = 'unknown error';
  * Extensible — consumers add domain-specific codes to their own objects
  * by casting `as JsonrpcErrorCode`. Application codes use the -32000 to
  * -32099 range reserved by the JSON-RPC spec.
+ *
+ * Frozen with `Object.freeze` to convert accidental mutation (test
+ * cross-contamination, cast escapes) into loud TypeErrors. Spread into
+ * a fresh object to extend.
  */
-export const JSONRPC_ERROR_CODES = {
+export const JSONRPC_ERROR_CODES = Object.freeze({
     // Standard JSON-RPC errors — values from jsonrpc.ts
     parse_error: JSONRPC_PARSE_ERROR,
     invalid_request: JSONRPC_INVALID_REQUEST,
@@ -67,15 +71,17 @@ export const JSONRPC_ERROR_CODES = {
      * for it to stop.
      */
     request_cancelled: -32010,
-};
+});
 /**
  * Named constructors for `JsonrpcErrorObject` values.
  *
  * Each function creates a JSON-RPC error object with the correct
  * code and a sensible default message. Used by the catch layer in
  * `apply_route_specs` to build response bodies.
+ *
+ * Frozen so tests must compose new objects rather than monkey-patch.
  */
-export const jsonrpc_error_messages = {
+export const jsonrpc_error_messages = Object.freeze({
     parse_error: (data) => ({
         code: JSONRPC_ERROR_CODES.parse_error,
         message: 'parse error',
@@ -151,7 +157,7 @@ export const jsonrpc_error_messages = {
         message,
         data,
     }),
-};
+});
 /**
  * Error class carrying a JSON-RPC error code — thrown by handlers,
  * caught by `apply_route_specs` and mapped to HTTP status + JSON-RPC error response.
@@ -198,9 +204,10 @@ export const jsonrpc_errors = {
  * Maps JSON-RPC error codes to HTTP status codes.
  *
  * Extensible — consumers with domain-specific error codes can spread
- * this into their own mapping object.
+ * this into their own mapping object. Frozen so the source can't be
+ * accidentally mutated; spread copies are mutable.
  */
-export const JSONRPC_ERROR_CODE_TO_HTTP_STATUS = {
+export const JSONRPC_ERROR_CODE_TO_HTTP_STATUS = Object.freeze({
     [-32700]: 400, // parse_error
     [-32600]: 400, // invalid_request
     [-32601]: 404, // method_not_found
@@ -218,7 +225,7 @@ export const JSONRPC_ERROR_CODE_TO_HTTP_STATUS = {
     [-32007]: 503, // service_unavailable
     [-32008]: 504, // timeout
     [-32010]: 499, // request_cancelled (nginx "client closed request")
-};
+});
 /**
  * Maps HTTP status codes to JSON-RPC error codes (reverse mapping).
  *
@@ -226,10 +233,10 @@ export const JSONRPC_ERROR_CODE_TO_HTTP_STATUS = {
  * and invalid_request both map to 400), the last one wins. Use for
  * best-effort HTTP → JSON-RPC translation.
  */
-export const HTTP_STATUS_TO_JSONRPC_ERROR_CODE = Object.fromEntries(Object.entries(JSONRPC_ERROR_CODE_TO_HTTP_STATUS).map(([code, status]) => [
+export const HTTP_STATUS_TO_JSONRPC_ERROR_CODE = Object.freeze(Object.fromEntries(Object.entries(JSONRPC_ERROR_CODE_TO_HTTP_STATUS).map(([code, status]) => [
     status,
     Number(code),
-]));
+])));
 /**
  * Map a JSON-RPC error code to an HTTP status code.
  *

package/dist/server/app_backend.d.ts

@@ -12,12 +12,12 @@
  */
 import { Logger } from '@fuzdev/fuz_util/log.js';
 import type { AppDeps } from '../auth/deps.js';
-import type { AuditLogEvent } from '../auth/audit_log_schema.js';
+import type { AuditLogConfig, AuditLogEvent } from '../auth/audit_log_schema.js';
 import type { DbType } from '../db/db.js';
 import type { Keyring } from '../auth/keyring.js';
 import type { PasswordHashDeps } from '../auth/password.js';
 import type { StatResult } from '../runtime/deps.js';
-import { type MigrationResult } from '../db/migrate.js';
+import { type MigrationNamespace, type MigrationResult } from '../db/migrate.js';
 /**
  * Result of `create_app_backend()` — database metadata + deps bundle.
  *
@@ -28,7 +28,7 @@ export interface AppBackend {
     deps: AppDeps;
     db_type: DbType;
     db_name: string;
-    /** Migration results from `create_app_backend` (auth migrations only). */
+    /** Migration results from `create_app_backend` — auth migrations plus any consumer namespaces passed via `migration_namespaces`. */
     readonly migration_results: ReadonlyArray<MigrationResult>;
     /** Close the database connection. Bound to the actual driver. */
     close: () => Promise<void>;
@@ -60,15 +60,34 @@ export interface CreateAppBackendOptions {
      * to all route factories automatically. Defaults to a noop.
      */
     on_audit_event?: (event: AuditLogEvent) => void;
+    /**
+     * Audit-log config for consumer event-type extensions. Built once at
+     * startup via `create_audit_log_config({extra_events})` and threaded
+     * through `AppDeps.audit_log_config` to every fuz_app emit site so
+     * consumer handlers cannot silently fall back to the builtin config.
+     * Omit to use `BUILTIN_AUDIT_LOG_CONFIG` (no extra events).
+     */
+    audit_log_config?: AuditLogConfig;
+    /**
+     * Additional migration namespaces to run after the builtin auth namespace.
+     * Each namespace's own `schema_version` row tracks progress; order is
+     * append-only so forward-only guarantees hold per-namespace.
+     *
+     * The reserved `'fuz_auth'` namespace is rejected at startup. Omit for no
+     * extra namespaces. This is the only place to splice consumer migrations
+     * — DB init belongs to the backend lifecycle, not server assembly.
+     */
+    migration_namespaces?: ReadonlyArray<MigrationNamespace>;
 }
 /**
  * Initialize the backend: database + auth migrations + deps.
  *
- * Calls `create_db` → `run_migrations` (auth namespace) and bundles
- * the result with the provided keyring and password deps.
+ * Calls `create_db` → `run_migrations` (auth namespace, then any
+ * `migration_namespaces` from options in order) and bundles the result
+ * with the provided keyring and password deps.
  *
- * @param options - keyring, password deps, and optional database URL
- * @returns app backend with deps, database metadata, and migration results
+ * @param options - keyring, password deps, optional database URL, and optional `migration_namespaces`
+ * @returns app backend with deps, database metadata, and combined migration results
  */
 export declare const create_app_backend: (options: CreateAppBackendOptions) => Promise<AppBackend>;
 //# sourceMappingURL=app_backend.d.ts.map

package/dist/server/app_backend.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"app_backend.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/server/app_backend.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAC,MAAM,EAAC,MAAM,yBAAyB,CAAC;AAE/C,OAAO,KAAK,EAAC,OAAO,EAAC,MAAM,iBAAiB,CAAC;AAC7C,OAAO,KAAK,EAAC,aAAa,EAAC,MAAM,6BAA6B,CAAC;AAC/D,OAAO,KAAK,EAAC,MAAM,EAAC,MAAM,aAAa,CAAC;AACxC,OAAO,KAAK,EAAC,OAAO,EAAC,MAAM,oBAAoB,CAAC;AAChD,OAAO,KAAK,EAAC,gBAAgB,EAAC,MAAM,qBAAqB,CAAC;AAC1D,OAAO,KAAK,EAAC,UAAU,EAAC,MAAM,oBAAoB,CAAC;AACnD,OAAO,EAAiB,KAAK,eAAe,EAAC,MAAM,kBAAkB,CAAC;AAItE;;;;;GAKG;AACH,MAAM,WAAW,UAAU;IAC1B,IAAI,EAAE,OAAO,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,0EAA0E;IAC1E,QAAQ,CAAC,iBAAiB,EAAE,aAAa,CAAC,eAAe,CAAC,CAAC;IAC3D,iEAAiE;IACjE,KAAK,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;CAC3B;AAED;;;;;GAKG;AACH,MAAM,WAAW,uBAAuB;IACvC,+DAA+D;IAC/D,IAAI,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC,CAAC;IACnD,2BAA2B;IAC3B,cAAc,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;IAClD,qBAAqB;IACrB,WAAW,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAC7C,0EAA0E;IAC1E,YAAY,EAAE,MAAM,CAAC;IACrB,wCAAwC;IACxC,OAAO,EAAE,OAAO,CAAC;IACjB,iFAAiF;IACjF,QAAQ,EAAE,gBAAgB,CAAC;IAC3B,6EAA6E;IAC7E,GAAG,CAAC,EAAE,MAAM,CAAC;IACb;;;;OAIG;IACH,cAAc,CAAC,EAAE,CAAC,KAAK,EAAE,aAAa,KAAK,IAAI,CAAC;CAChD;AAED;;;;;;;;GAQG;AACH,eAAO,MAAM,kBAAkB,GAAU,SAAS,uBAAuB,KAAG,OAAO,CAAC,UAAU,CAa7F,CAAC"}
+{"version":3,"file":"app_backend.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/server/app_backend.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAC,MAAM,EAAC,MAAM,yBAAyB,CAAC;AAE/C,OAAO,KAAK,EAAC,OAAO,EAAC,MAAM,iBAAiB,CAAC;AAC7C,OAAO,KAAK,EAAC,cAAc,EAAE,aAAa,EAAC,MAAM,6BAA6B,CAAC;AAC/E,OAAO,KAAK,EAAC,MAAM,EAAC,MAAM,aAAa,CAAC;AACxC,OAAO,KAAK,EAAC,OAAO,EAAC,MAAM,oBAAoB,CAAC;AAChD,OAAO,KAAK,EAAC,gBAAgB,EAAC,MAAM,qBAAqB,CAAC;AAC1D,OAAO,KAAK,EAAC,UAAU,EAAC,MAAM,oBAAoB,CAAC;AACnD,OAAO,EAAiB,KAAK,kBAAkB,EAAE,KAAK,eAAe,EAAC,MAAM,kBAAkB,CAAC;AAI/F;;;;;GAKG;AACH,MAAM,WAAW,UAAU;IAC1B,IAAI,EAAE,OAAO,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,oIAAoI;IACpI,QAAQ,CAAC,iBAAiB,EAAE,aAAa,CAAC,eAAe,CAAC,CAAC;IAC3D,iEAAiE;IACjE,KAAK,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;CAC3B;AAED;;;;;GAKG;AACH,MAAM,WAAW,uBAAuB;IACvC,+DAA+D;IAC/D,IAAI,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC,CAAC;IACnD,2BAA2B;IAC3B,cAAc,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;IAClD,qBAAqB;IACrB,WAAW,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAC7C,0EAA0E;IAC1E,YAAY,EAAE,MAAM,CAAC;IACrB,wCAAwC;IACxC,OAAO,EAAE,OAAO,CAAC;IACjB,iFAAiF;IACjF,QAAQ,EAAE,gBAAgB,CAAC;IAC3B,6EAA6E;IAC7E,GAAG,CAAC,EAAE,MAAM,CAAC;IACb;;;;OAIG;IACH,cAAc,CAAC,EAAE,CAAC,KAAK,EAAE,aAAa,KAAK,IAAI,CAAC;IAChD;;;;;;OAMG;IACH,gBAAgB,CAAC,EAAE,cAAc,CAAC;IAClC;;;;;;;;OAQG;IACH,oBAAoB,CAAC,EAAE,aAAa,CAAC,kBAAkB,CAAC,CAAC;CACzD;AAED;;;;;;;;;GASG;AACH,eAAO,MAAM,kBAAkB,GAAU,SAAS,uBAAuB,KAAG,OAAO,CAAC,UAAU,CAoC7F,CAAC"}

package/dist/server/app_backend.js

@@ -12,28 +12,50 @@
  */
 import { Logger } from '@fuzdev/fuz_util/log.js';
 import { run_migrations } from '../db/migrate.js';
-import { AUTH_MIGRATION_NS } from '../auth/migrations.js';
+import { AUTH_MIGRATION_NS, AUTH_MIGRATION_NAMESPACE } from '../auth/migrations.js';
 import { create_db } from '../db/create_db.js';
 /**
  * Initialize the backend: database + auth migrations + deps.
  *
- * Calls `create_db` → `run_migrations` (auth namespace) and bundles
- * the result with the provided keyring and password deps.
+ * Calls `create_db` → `run_migrations` (auth namespace, then any
+ * `migration_namespaces` from options in order) and bundles the result
+ * with the provided keyring and password deps.
  *
- * @param options - keyring, password deps, and optional database URL
- * @returns app backend with deps, database metadata, and migration results
+ * @param options - keyring, password deps, optional database URL, and optional `migration_namespaces`
+ * @returns app backend with deps, database metadata, and combined migration results
  */
 export const create_app_backend = async (options) => {
     const { database_url, keyring, password, stat, read_text_file, delete_file } = options;
     const log = options.log ?? new Logger('server');
     const on_audit_event = options.on_audit_event ?? (() => { }); // eslint-disable-line @typescript-eslint/no-empty-function
+    const { audit_log_config } = options;
     const { db, close, db_type, db_name } = await create_db(database_url);
-    const migration_results = await run_migrations(db, [AUTH_MIGRATION_NS]);
+    if (options.migration_namespaces?.length) {
+        for (const ns of options.migration_namespaces) {
+            if (ns.namespace === AUTH_MIGRATION_NAMESPACE) {
+                throw new Error(`Migration namespace "${AUTH_MIGRATION_NAMESPACE}" is reserved by fuz_app — choose a different namespace`);
+            }
+        }
+    }
+    const migration_results = await run_migrations(db, [
+        AUTH_MIGRATION_NS,
+        ...(options.migration_namespaces ?? []),
+    ]);
     return {
         db_type,
         db_name,
         migration_results,
         close,
-        deps: { keyring, password, db, stat, read_text_file, delete_file, log, on_audit_event },
+        deps: {
+            keyring,
+            password,
+            db,
+            stat,
+            read_text_file,
+            delete_file,
+            log,
+            on_audit_event,
+            audit_log_config,
+        },
     };
 };

package/dist/server/app_server.d.ts

@@ -17,7 +17,7 @@ import { type AuditLogSse } from '../realtime/sse_auth_guard.js';
 import type { AppSettings } from '../auth/app_settings_schema.js';
 import { type RateLimiter } from '../rate_limiter.js';
 import type { DaemonTokenState } from '../auth/daemon_token.js';
-import { type MigrationNamespace, type MigrationResult } from '../db/migrate.js';
+import type { MigrationResult } from '../db/migrate.js';
 import type { AppDeps } from '../auth/deps.js';
 import type { AppBackend } from './app_backend.js';
 import '../hono_context.js';
@@ -104,8 +104,6 @@ export interface AppServerOptions {
      * Default: auto-created (authenticated).
      */
     surface_route?: false;
-    /** Consumer migration namespaces — run after auth migrations during init. */
-    migration_namespaces?: Array<MigrationNamespace>;
     /**
      * Build route specs from the initialized backend.
      * Called after all middleware is ready.
@@ -191,7 +189,7 @@ export interface AppServer {
     bootstrap_status: BootstrapStatus;
     /** Global app settings (mutable ref — mutated by settings admin route). */
     app_settings: AppSettings;
-    /** Combined migration results — auth migrations from `create_app_backend` plus consumer migrations. */
+    /** Migration results from `create_app_backend` (auth + any `migration_namespaces` passed there). */
     migration_results: ReadonlyArray<MigrationResult>;
     /** Factory-managed audit log SSE. `null` when `audit_log_sse` option is not set. */
     audit_sse: AuditLogSse | null;
@@ -203,9 +201,10 @@ export declare const DEFAULT_MAX_BODY_SIZE: number;
 /**
  * Create a fully assembled Hono app with auth, middleware, and routes.
  *
- * Handles the full lifecycle: consumer migrations → proxy middleware →
- * auth middleware → bootstrap status → route specs → surface generation →
- * Hono app assembly → static serving.
+ * Handles the assembly lifecycle: proxy middleware → auth middleware →
+ * bootstrap status → route specs → surface generation → Hono app assembly →
+ * static serving. Database migrations belong to the backend lifecycle —
+ * pass `migration_namespaces` to `create_app_backend`.
  *
  * @param options - server configuration
  * @returns assembled Hono app, backend, surface build, and bootstrap status