@fuzdev/fuz_app 0.61.0 → 0.62.0

package/dist/actions/CLAUDE.md

@@ -225,6 +225,24 @@ and `FrontendActionHandlers`.
 - `compose_gen_file({origin_path, imports, blocks})` — encapsulates the per-`*.gen.ts` boilerplate (banner + `imports.build()` + blocks join + template literal). Returns the full file body. Each consumer producer collapses to one `compose_gen_file` call wrapping the helper invocations.
 - `create_namespace_qualifier(sources, imports)` — multi-source consumer helper. Takes `ReadonlyArray<{ns, module, specs}>`, registers `import * as ns from module` for each on `imports`, builds the `method_to_ns` lookup with duplicate-method detection, returns `{qualify_spec, all_specs}` ready to thread through the high-level helpers. Closes the per-file boilerplate gap that kept zap + visiones on hand-rolled template strings even after the `qualify_spec?` callback landed (the per-call callback wasn't enough — the import dance + dup-check was the real boilerplate).
 
+## Registry compile (`compile_action_registry.ts`)
+
+Shared registration loop called by both `create_rpc_endpoint` and
+`register_action_ws`. Validates four invariants and returns the
+`Map<method, RpcAction>` the dispatchers use:
+
+1. Auth-shape biconditional (`assert_route_auth_acting_biconditional` —
+   `auth.actor !== 'none' ⟺ input declares acting?: ActingActor`).
+2. Rate-limit / account axis — `rate_limit: 'account' | 'both'` requires
+   `auth.account === 'required'`.
+3. JSON-RPC §4.2 wire validity — `request_response` specs with a handler
+   may not use `z.null()` for input (use `z.void()` for nullary).
+4. Unique `method` across the array.
+
+Only `request_response` specs with a handler reach the dispatch map;
+`remote_notification` / handler-less specs (e.g. WS `cancel`) stay
+registry-only.
+
 ## HTTP bridge (`action_bridge.ts`)
 
 Derives transport-specific specs from action specs. HTTP-specific concerns
@@ -256,7 +274,7 @@ surface is published in `library.json` codegen anyway.
 Shim responsibilities:
 
 1. **Parse envelope** — POST body as `JsonrpcRequest` (parse errors → JSON-RPC `parse_error` 400). GET reads `method`, `id`, `params` from query string; missing `method`/`id` → 400 `invalid_request`. Integer `id` normalization: `?id=42` matches `{id: 42}`.
-2. **Lookup method** — `Map<method, RpcAction>`. Unknown method → `method_not_found`. Duplicate methods throw at construction. Registration also runs `assert_route_auth_acting_biconditional(spec.auth, {input: spec.input}, ...)` to enforce invariant 2 — the helper takes a `{input, query?}` slot set so REST (input + query bi-located) and actions (input-only) share one entry point with surface-appropriate error messages.
+2. **Lookup method** — `Map<method, RpcAction>` built via `compile_action_registry` (which runs the registry-time invariants — see §Registry compile above). Unknown method → `method_not_found`.
 3. **GET read restriction** — GET is rejected for `side_effects: true` actions (`invalid_request` with "must use POST"). HTTP-only.
 4. **Build PerformActionInput** — read `account_id` / `credential_type` from `c.var`, resolve `client_ip` via `get_client_ip`, pass `c.req.raw.signal` as `signal`, build a DEV-warn-and-drop `notify`. Test-preset escape hatch reads `TEST_CONTEXT_PRESET_KEY` + `REQUEST_CONTEXT_KEY` and forwards as `preset.request_context`.
 5. **Call `perform_action`** — runs steps 1–6 of the shared pipeline (see §Shared dispatch core below).
@@ -358,19 +376,8 @@ narrowing — ideal when handlers are stateless free functions. fuz_app's
 handlers close over factory-captured deps (`log`, `audit`,
 `options.app_settings`, `options.max_tokens`), so per-pair typing via
 `rpc_action()` is the right shape here: the binding happens at
-construction time and the handler keeps its closure. Applied across
-all four registries — `admin_actions.ts`,
-`role_grant_offer_actions.ts`, `self_service_role_actions.ts` (every
-spec there is actor-implying), and `account_actions.ts` (account-grain).
-The conditional auto-selects the right tier per spec; consumers don't
-pick a binder.
-
-The earlier two-binder split (`rpc_action` + `rpc_actor_action`) was
-collapsed once the symmetric account-grain narrowing landed. Same
-runtime; the second symbol no longer added information the spec
-literal didn't already carry. Uniform binding keeps a future handler
-that gains `ctx.auth.actor` reads from accidentally landing on a
-looser narrow — the spec literal drives the type either way.
+construction time and the handler keeps its closure. The conditional
+auto-selects the right tier per spec; consumers don't pick a binder.
 
 ## Transports (`transports.ts`, `transports_http.ts`, `transports_ws.ts`, `transports_ws_backend.ts`)
 
@@ -529,11 +536,11 @@ dispatcher without the origin/auth front-stack.
 
 Actions are passed as `ReadonlyArray<Action>` — the composable
 `{spec, handler?}` tuple shared with `create_rpc_client`. The dispatcher
-fans the array into a `spec_by_method` map (drives envelope-shape
-validation) and an `action_map: Map<string, RpcAction>` (drives
-invocation, only request_response specs with a handler). Specs without
-a handler (client-only / dispatcher-handled like `cancel`) miss
-`action_map` and surface as `method_not_found` if the wire targets them.
+builds its `action_map: Map<string, RpcAction>` via `compile_action_registry`
+(see §Registry compile above) — only `request_response` specs with a
+handler land in the map. Specs without a handler (client-only /
+dispatcher-handled like `cancel`) surface as `method_not_found` if the
+wire targets them.
 
 Required deps: `db: Db` (pool-level, used by `perform_action` for both the
 per-message authorization phase and the transactional dispatch wrap when
@@ -988,9 +995,8 @@ transport; `ActionHandler` is the single handler signature.
 
 `RpcAction = Action<RequestResponseActionSpec> & {handler: ActionHandler}`
 is the narrowing the HTTP RPC dispatcher accepts (`create_rpc_endpoint`)
-and the `rpc_action` binder produces (the actor-axis narrowing now lives
-in `HandlerForSpec<TSpec>` — there's no longer a separate
-`rpc_actor_action`).
+and the `rpc_action` binder produces (the actor-axis narrowing lives
+in `HandlerForSpec<TSpec>`).
 
 ## Shared dispatch core (`perform_action.ts`)
 

package/dist/auth/CLAUDE.md

@@ -2,7 +2,7 @@
 
 > Auth domain: identity, crypto primitives, schema + DDL, queries, middleware, routes, RPC actions, cleanup.
 
-Forty source files, grouped below by theme. For design rationale and threat
+Grouped below by theme. For design rationale and threat
 model, see `../../../docs/identity.md` and `../../../docs/security.md`. For the
 subsystem's place in server assembly and middleware ordering, see
 `../../../docs/architecture.md` and the root `../../../CLAUDE.md`.
@@ -1530,9 +1530,9 @@ spread `all_self_service_role_action_specs` separately when needed.
 
 `all_fuz_auth_action_spec_registries` — walker/codegen entry for every
 fuz-auth action-spec bundle (`admin`, `role_grant_offer`, `account`,
-`self_service_role`, `actor_lookup`). Not a mounting surface; protocol
-specs are excluded. Iterated by `../../test/auth/action_spec_input_invariants.test.ts`
-and `../../test/auth/all_action_spec_registries.acting_biconditional.test.ts`.
+`self_service_role`, `actor_lookup`, `actor_search`). Not a mounting
+surface; protocol specs are excluded. Iterated by registry-wide
+invariant tests in `../../test/auth/`.
 
 ### `account_action_specs.ts` + `account_actions.ts` — seven self-service RPC actions
 

package/dist/server/app_server.d.ts

@@ -137,7 +137,10 @@ export interface AppServerOptions {
      * listener to `backend.deps.audit.on_event_chain` (composing with the
      * consumer's `on_audit_event` callback rather than rebuilding `AppDeps`), and
      * auto-includes `audit_log_event_specs` in the surface. The result is exposed
-     * on `AppServerContext` (for route factories) and `AppServer` (for the caller).
+     * on `AppServerContext` (for route factories) and `AppServer` (for the caller),
+     * always typed as `AuditLogSse | null` — when this option is set, the field
+     * is non-null. Use `require_audit_sse(ctx)` to assert the invariant in
+     * route factories that depend on it.
      *
      * Pass `true` for defaults (admin role), or `{role: 'custom'}` for a custom role.
      * Omit to wire audit SSE manually.
@@ -160,14 +163,27 @@ export interface AppServerOptions {
      * `create_standard_rpc_actions(ctx.deps, {app_settings: ctx.app_settings})`.
      */
     rpc_endpoints?: Array<RpcEndpointSpec> | ((context: AppServerContext) => Array<RpcEndpointSpec>);
-    /** Env schema for surface generation. Pass `z.object({})` when there are no env vars beyond `BaseServerEnv`. */
-    env_schema: z.ZodObject;
+    /**
+     * Env schema for surface generation. Defaults to `BaseServerEnv` —
+     * pass an extended schema (typically `BaseServerEnv.extend({...})`)
+     * when the consumer adds app-specific env vars.
+     */
+    env_schema?: z.ZodObject;
     /** Middleware applied after routes, before static serving. Included in surface. */
     post_route_middleware?: Array<MiddlewareSpec>;
     /** Static file serving. Omit if not serving static files. */
     static_serving?: {
         serve_static: ServeStaticFactory;
+        /** Root directory for static files. Default `'./build'`. */
+        root?: string;
+        /** Optional SPA fallback path served for client-side routes. */
         spa_fallback?: string;
+        /**
+         * Predicate deciding which paths receive the SPA fallback.
+         * Default: every path that is not under `/api/`. Only consulted
+         * when `spa_fallback` is set.
+         */
+        is_spa_route?: (path: string) => boolean;
     };
     /**
      * Await all pending fire-and-forget effects before returning the response.
@@ -202,7 +218,11 @@ export interface AppServerContext {
     action_account_rate_limiter: RateLimiter | null;
     /** Global app settings (mutable ref — mutated by settings admin route). */
     app_settings: AppSettings;
-    /** Factory-managed audit log SSE. `null` when `audit_log_sse` option is not set. */
+    /**
+     * Factory-managed audit log SSE. Non-null when the `audit_log_sse`
+     * option was passed to `create_app_server`, `null` when omitted.
+     * Use `require_audit_sse(ctx)` to assert the invariant.
+     */
     audit_sse: AuditLogSse | null;
 }
 /** Result of `create_app_server()`. */
@@ -215,11 +235,35 @@ export interface AppServer {
     app_settings: AppSettings;
     /** 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. */
+    /**
+     * Factory-managed audit log SSE. Non-null when the `audit_log_sse`
+     * option was passed to `create_app_server`, `null` when omitted.
+     * Use `require_audit_sse(server)` to assert the invariant.
+     */
     audit_sse: AuditLogSse | null;
     /** Close the database connection. Propagated from `AppBackend`. */
     close: () => Promise<void>;
 }
+/**
+ * Assert that `audit_sse` was wired by `create_app_server` and return it
+ * as a non-null `AuditLogSse`. Throws a labelled error when the
+ * `audit_log_sse` option was not passed to `create_app_server`.
+ *
+ * Use in route factories that depend on factory-managed audit SSE:
+ *
+ * ```ts
+ * create_route_specs: (ctx) => create_audit_log_route_specs({
+ *   stream: require_audit_sse(ctx),
+ * }),
+ * ```
+ *
+ * Preferred over `ctx.audit_sse!` — `!` lies to the type system and
+ * produces a downstream cannot-read-property crash if a consumer wires
+ * the route without enabling the option.
+ */
+export declare const require_audit_sse: (source: {
+    audit_sse: AuditLogSse | null;
+}) => AuditLogSse;
 /** Default maximum request body size: 1 MiB. */
 export declare const DEFAULT_MAX_BODY_SIZE: number;
 /**
@@ -231,7 +275,11 @@ export declare const DEFAULT_MAX_BODY_SIZE: number;
  * pass `migration_namespaces` to `create_app_backend`.
  *
  * When `audit_log_sse` is set, the SSE registry's listener is appended to
- * `backend.deps.audit.on_event_chain` — no shallow-copy of `AppDeps`.
+ * `backend.deps.audit.on_event_chain` — no shallow-copy of `AppDeps`. The
+ * `audit_sse` field on the returned `AppServer` (and the
+ * `AppServerContext` passed to `create_route_specs`) is non-null in that
+ * case; consumers can call `require_audit_sse(ctx)` / `require_audit_sse(server)`
+ * to assert the invariant.
  *
  * @returns assembled Hono app, backend, surface build, and bootstrap status
  */

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

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

package/dist/server/app_server.js

@@ -13,6 +13,7 @@ import { bodyLimit } from 'hono/body-limit';
 import { z } from 'zod';
 import { session_cookie_options, } from '../auth/session_cookie.js';
 import { create_audit_log_sse, audit_log_event_specs, } from '../realtime/sse_auth_guard.js';
+import { BaseServerEnv } from './env.js';
 import { query_app_settings_load } from '../auth/app_settings_queries.js';
 import { create_rate_limiter, default_login_account_rate_limit, default_action_account_rate_limit, default_action_ip_rate_limit, } from '../rate_limiter.js';
 // Side-effect import: augments Hono's ContextVariableMap so consumers
@@ -31,6 +32,29 @@ import { fuz_auth_guard_resolver } from '../auth/auth_guard_resolver.js';
 import { create_fuz_authorization_handler } from '../auth/request_context.js';
 import { ERROR_PAYLOAD_TOO_LARGE } from '../http/error_schemas.js';
 import { create_rpc_endpoint } from '../actions/action_rpc.js';
+/**
+ * Assert that `audit_sse` was wired by `create_app_server` and return it
+ * as a non-null `AuditLogSse`. Throws a labelled error when the
+ * `audit_log_sse` option was not passed to `create_app_server`.
+ *
+ * Use in route factories that depend on factory-managed audit SSE:
+ *
+ * ```ts
+ * create_route_specs: (ctx) => create_audit_log_route_specs({
+ *   stream: require_audit_sse(ctx),
+ * }),
+ * ```
+ *
+ * Preferred over `ctx.audit_sse!` — `!` lies to the type system and
+ * produces a downstream cannot-read-property crash if a consumer wires
+ * the route without enabling the option.
+ */
+export const require_audit_sse = (source) => {
+    if (!source.audit_sse) {
+        throw new Error('audit_sse is null — pass `audit_log_sse: true` (or `{role}`) in `AppServerOptions`');
+    }
+    return source.audit_sse;
+};
 /** Default maximum request body size: 1 MiB. */
 export const DEFAULT_MAX_BODY_SIZE = 1024 * 1024;
 /**
@@ -42,7 +66,11 @@ export const DEFAULT_MAX_BODY_SIZE = 1024 * 1024;
  * pass `migration_namespaces` to `create_app_backend`.
  *
  * When `audit_log_sse` is set, the SSE registry's listener is appended to
- * `backend.deps.audit.on_event_chain` — no shallow-copy of `AppDeps`.
+ * `backend.deps.audit.on_event_chain` — no shallow-copy of `AppDeps`. The
+ * `audit_sse` field on the returned `AppServer` (and the
+ * `AppServerContext` passed to `create_route_specs`) is non-null in that
+ * case; consumers can call `require_audit_sse(ctx)` / `require_audit_sse(server)`
+ * to assert the invariant.
  *
  * @returns assembled Hono app, backend, surface build, and bootstrap status
  */
@@ -161,7 +189,7 @@ export const create_app_server = async (options) => {
     const surface_spec = create_app_surface_spec({
         middleware_specs: surface_middleware,
         route_specs,
-        env_schema: options.env_schema,
+        env_schema: options.env_schema ?? BaseServerEnv,
         event_specs: all_event_specs,
         rpc_endpoints: resolved_rpc_endpoints,
     });
@@ -269,8 +297,8 @@ export const create_app_server = async (options) => {
     }
     // Static file serving
     if (options.static_serving) {
-        const { serve_static, spa_fallback } = options.static_serving;
-        for (const mw of create_static_middleware(serve_static, { spa_fallback })) {
+        const { serve_static, root, spa_fallback, is_spa_route } = options.static_serving;
+        for (const mw of create_static_middleware(serve_static, { root, spa_fallback, is_spa_route })) {
             app.use('/*', mw);
         }
     }

package/dist/testing/CLAUDE.md

@@ -700,14 +700,14 @@ deps — no DB needed.
 Options: `{build: () => AppSurfaceSpec, roles: Array<string>}`.
 
 **Opt-in bundles need their own per-bundle suite file.** Action bundles
-not folded into `create_standard_rpc_actions` (today `self_service_role_actions`
-and `actor_lookup_actions`) get zero adversarial / round-trip coverage
-from `describe_rpc_attack_surface_tests` + `describe_rpc_round_trip_tests`
-unless the consumer ships a `<module>.rpc_suites.db.test.ts` mounting the
-opt-in factory on the RPC endpoint and calling both suites. See
-`../../test/CLAUDE.md` §Composable Test Suites for the obligation note
-and `actor_lookup_actions.rpc_suites.db.test.ts` /
-`role_grant_offer_actions.rpc_suites.db.test.ts` as templates.
+not folded into `create_standard_rpc_actions` (today `self_service_role_actions`,
+`actor_lookup_actions`, and `actor_search_actions`) get zero adversarial
+/ round-trip coverage from `describe_rpc_attack_surface_tests` +
+`describe_rpc_round_trip_tests` unless the consumer ships a
+`<module>.rpc_suites.db.test.ts` mounting the opt-in factory on the RPC
+endpoint and calling both suites. See `../../test/CLAUDE.md` §Composable
+Test Suites for the obligation note; existing
+`../../test/auth/*.rpc_suites.db.test.ts` files are templates.
 
 ## Cross-cutting conventions
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fuzdev/fuz_app",
-  "version": "0.61.0",
+  "version": "0.62.0",
   "description": "fullstack app library",
   "glyph": "🗝",
   "logo": "logo.svg",