@fuzdev/fuz_app 0.53.0 → 0.55.0

package/dist/auth/route_guards.js

@@ -1,7 +1,13 @@
 /**
  * Auth guard resolver for the route spec system.
  *
- * Maps `RouteAuth` discriminants to auth middleware handlers.
+ * Maps `RouteAuth` discriminants to two-phase auth middleware sets.
+ * `pre_validation` carries the 401 check (`require_auth`) so
+ * unauthenticated callers never see route-shape information from input
+ * parse failures. `post_authorization` carries the 403 role / keeper
+ * checks because they read the `RequestContext` populated by the
+ * dispatcher's authorization phase.
+ *
  * Injected into `apply_route_specs` to decouple the generic HTTP
  * framework (`http/route_spec.ts`) from auth-specific middleware.
  *
@@ -14,19 +20,19 @@ import { require_keeper } from './require_keeper.js';
  *
  * Maps `RouteAuth` to middleware:
  * - `none` → no guards
- * - `authenticated` → `require_auth`
- * - `role` → `require_role(role)`
- * - `keeper` → `require_keeper`
+ * - `authenticated` → pre-validation `require_auth`
+ * - `role` → pre-validation `require_auth` + post-authorization `require_role(role)`
+ * - `keeper` → pre-validation `require_auth` + post-authorization `require_keeper`
  */
 export const fuz_auth_guard_resolver = (auth) => {
     switch (auth.type) {
         case 'none':
-            return [];
+            return { pre_validation: [], post_authorization: [] };
         case 'authenticated':
-            return [require_auth];
+            return { pre_validation: [require_auth], post_authorization: [] };
         case 'role':
-            return [require_role(auth.role)];
+            return { pre_validation: [require_auth], post_authorization: [require_role(auth.role)] };
         case 'keeper':
-            return [require_keeper];
+            return { pre_validation: [require_auth], post_authorization: [require_keeper] };
     }
 };

package/dist/auth/self_service_role_action_specs.d.ts

@@ -15,6 +15,7 @@ export declare const ERROR_ROLE_NOT_SELF_SERVICE_ELIGIBLE: "role_not_self_servic
 export declare const SelfServiceRoleSetInput: z.ZodObject<{
     role: z.ZodString;
     enabled: z.ZodBoolean;
+    acting: z.ZodOptional<z.core.$ZodBranded<z.ZodUUID, "Uuid", "out">>;
 }, z.core.$strict>;
 export type SelfServiceRoleSetInput = z.infer<typeof SelfServiceRoleSetInput>;
 /**
@@ -37,6 +38,7 @@ export declare const self_service_role_set_action_spec: {
     input: z.ZodObject<{
         role: z.ZodString;
         enabled: z.ZodBoolean;
+        acting: z.ZodOptional<z.core.$ZodBranded<z.ZodUUID, "Uuid", "out">>;
     }, z.core.$strict>;
     output: z.ZodObject<{
         ok: z.ZodLiteral<true>;

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

@@ -1 +1 @@
-{"version":3,"file":"self_service_role_action_specs.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/auth/self_service_role_action_specs.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAC,CAAC,EAAC,MAAM,KAAK,CAAC;AAEtB,OAAO,KAAK,EAAC,yBAAyB,EAAC,MAAM,2BAA2B,CAAC;AAGzE,0FAA0F;AAC1F,eAAO,MAAM,oCAAoC,EAAG,gCAAyC,CAAC;AAE9F,yCAAyC;AACzC,eAAO,MAAM,uBAAuB;;;kBAMlC,CAAC;AACH,MAAM,MAAM,uBAAuB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,uBAAuB,CAAC,CAAC;AAE9E;;;;GAIG;AACH,eAAO,MAAM,wBAAwB;;;;kBAInC,CAAC;AACH,MAAM,MAAM,wBAAwB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,wBAAwB,CAAC,CAAC;AAEhF,eAAO,MAAM,iCAAiC;;;;;;;;;;;;;;;;;CAWT,CAAC;AAEtC;;;;GAIG;AACH,eAAO,MAAM,kCAAkC,EAAE,aAAa,CAAC,yBAAyB,CAEvF,CAAC"}
+{"version":3,"file":"self_service_role_action_specs.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/auth/self_service_role_action_specs.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAC,CAAC,EAAC,MAAM,KAAK,CAAC;AAEtB,OAAO,KAAK,EAAC,yBAAyB,EAAC,MAAM,2BAA2B,CAAC;AAIzE,0FAA0F;AAC1F,eAAO,MAAM,oCAAoC,EAAG,gCAAyC,CAAC;AAE9F,yCAAyC;AACzC,eAAO,MAAM,uBAAuB;;;;kBAOlC,CAAC;AACH,MAAM,MAAM,uBAAuB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,uBAAuB,CAAC,CAAC;AAE9E;;;;GAIG;AACH,eAAO,MAAM,wBAAwB;;;;kBAInC,CAAC;AACH,MAAM,MAAM,wBAAwB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,wBAAwB,CAAC,CAAC;AAEhF,eAAO,MAAM,iCAAiC;;;;;;;;;;;;;;;;;;CAWT,CAAC;AAEtC;;;;GAIG;AACH,eAAO,MAAM,kCAAkC,EAAE,aAAa,CAAC,yBAAyB,CAEvF,CAAC"}

package/dist/auth/self_service_role_action_specs.js

@@ -9,6 +9,7 @@
  */
 import { z } from 'zod';
 import { RoleName } from './role_schema.js';
+import { ActingActor } from './account_schema.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 for `self_service_role_set`. */
@@ -17,6 +18,7 @@ export const SelfServiceRoleSetInput = z.strictObject({
     enabled: z.boolean().meta({
         description: 'Desired post-call state. `true` grants if not held; `false` revokes if held. Idempotent in both directions.',
     }),
+    acting: ActingActor,
 });
 /**
  * Output for `self_service_role_set`. `enabled` echoes the post-call state

package/dist/auth/self_service_role_actions.d.ts

@@ -33,7 +33,7 @@
  */
 import { type RpcAction } from '../actions/action_rpc.js';
 import type { RoleSchemaResult } from './role_schema.js';
-import type { RouteFactoryDeps } from './deps.js';
+import type { AuditEmitDeps } from './deps.js';
 /** Options for `create_self_service_role_actions`. */
 export interface SelfServiceRoleActionsOptions {
     /**
@@ -50,12 +50,13 @@ export interface SelfServiceRoleActionsOptions {
     roles?: RoleSchemaResult;
 }
 /**
- * Dependencies for `create_self_service_role_actions`. Same shape as the
- * peer factories so consumers thread one deps object through all three.
- * `audit_log_config` flows from `AppDeps` and is consumed by
+ * Dependencies for `create_self_service_role_actions`.
+ *
+ * Aliases the shared `AuditEmitDeps` so consumers thread one deps object
+ * through every action factory. `audit_log_config` is consumed by
  * `audit_log_fire_and_forget`.
  */
-export type SelfServiceRoleActionDeps = Pick<RouteFactoryDeps, 'log' | 'on_audit_event' | 'audit_log_config'>;
+export type SelfServiceRoleActionDeps = AuditEmitDeps;
 /**
  * Build the unified self-service role toggle RPC action.
  *

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

@@ -1 +1 @@
-{"version":3,"file":"self_service_role_actions.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/auth/self_service_role_actions.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AAEH,OAAO,EAAiC,KAAK,SAAS,EAAC,MAAM,0BAA0B,CAAC;AAExF,OAAO,KAAK,EAAC,gBAAgB,EAAC,MAAM,kBAAkB,CAAC;AACvD,OAAO,KAAK,EAAC,gBAAgB,EAAC,MAAM,WAAW,CAAC;AAgBhD,sDAAsD;AACtD,MAAM,WAAW,6BAA6B;IAC7C;;;;OAIG;IACH,cAAc,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;IACtC;;;;OAIG;IACH,KAAK,CAAC,EAAE,gBAAgB,CAAC;CACzB;AAED;;;;;GAKG;AACH,MAAM,MAAM,yBAAyB,GAAG,IAAI,CAC3C,gBAAgB,EAChB,KAAK,GAAG,gBAAgB,GAAG,kBAAkB,CAC7C,CAAC;AAOF;;;;;;;GAOG;AACH,eAAO,MAAM,gCAAgC,GAC5C,MAAM,yBAAyB,EAC/B,SAAS,6BAA6B,KACpC,KAAK,CAAC,SAAS,CA4GjB,CAAC"}
+{"version":3,"file":"self_service_role_actions.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/auth/self_service_role_actions.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AAEH,OAAO,EAA4C,KAAK,SAAS,EAAC,MAAM,0BAA0B,CAAC;AAEnG,OAAO,KAAK,EAAC,gBAAgB,EAAC,MAAM,kBAAkB,CAAC;AACvD,OAAO,KAAK,EAAC,aAAa,EAAC,MAAM,WAAW,CAAC;AAY7C,sDAAsD;AACtD,MAAM,WAAW,6BAA6B;IAC7C;;;;OAIG;IACH,cAAc,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;IACtC;;;;OAIG;IACH,KAAK,CAAC,EAAE,gBAAgB,CAAC;CACzB;AAED;;;;;;GAMG;AACH,MAAM,MAAM,yBAAyB,GAAG,aAAa,CAAC;AAEtD;;;;;;;GAOG;AACH,eAAO,MAAM,gCAAgC,GAC5C,MAAM,yBAAyB,EAC/B,SAAS,6BAA6B,KACpC,KAAK,CAAC,SAAS,CA8HjB,CAAC"}

package/dist/auth/self_service_role_actions.js

@@ -31,16 +31,13 @@
  *
  * @module
  */
-import { rpc_action } from '../actions/action_rpc.js';
+import { rpc_actor_action } from '../actions/action_rpc.js';
 import { jsonrpc_errors } from '../http/jsonrpc_errors.js';
-import { query_grant_permit, query_permit_find_active_for_actor, query_permit_has_role, query_revoke_permit, } from './permit_queries.js';
+import { query_grant_permit, query_revoke_permit } from './permit_queries.js';
 import { audit_log_fire_and_forget } from './audit_log_queries.js';
+import { is_permit_active } from './account_schema.js';
+import { has_scoped_role } from './request_context.js';
 import { ERROR_ROLE_NOT_SELF_SERVICE_ELIGIBLE, self_service_role_set_action_spec, } from './self_service_role_action_specs.js';
-const require_request_auth = (auth) => {
-    if (!auth)
-        throw new Error('unreachable: action auth guard did not enforce authentication');
-    return auth;
-};
 /**
  * Build the unified self-service role toggle RPC action.
  *
@@ -67,19 +64,19 @@ export const create_self_service_role_actions = (deps, options) => {
         }
     };
     const handler = async (input, ctx) => {
-        const auth = require_request_auth(ctx.auth);
+        const auth = ctx.auth;
         reject_if_ineligible(input.role);
         if (input.enabled) {
             // 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
+            // peek first. Reads from the in-memory `auth.permits` snapshot
+            // (no DB roundtrip). 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
             // `changed: 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) {
+            if (has_scoped_role(auth, input.role, null)) {
                 return { ok: true, enabled: true, changed: false };
             }
             const permit = await query_grant_permit(ctx, {
@@ -89,10 +86,19 @@ export const create_self_service_role_actions = (deps, options) => {
                 expires_at: null,
                 granted_by: auth.actor.id,
             });
+            // `permit_grant` is the canonical actor-bound-subject event —
+            // populate both target columns even on self-service so the
+            // "always populated for permit_grant" rule holds uniformly
+            // regardless of who initiated the grant. On self-service the
+            // grantor and grantee are the same identity; admin direct-grant
+            // (separate code path) populates the same columns with the
+            // grantee actor.
             void audit_log_fire_and_forget(ctx, {
                 event_type: 'permit_grant',
                 actor_id: auth.actor.id,
                 account_id: auth.account.id,
+                target_account_id: auth.account.id,
+                target_actor_id: auth.actor.id,
                 ip: ctx.client_ip,
                 metadata: {
                     role: permit.role,
@@ -103,12 +109,13 @@ export const create_self_service_role_actions = (deps, options) => {
             }, deps);
             return { ok: true, enabled: true, changed: true };
         }
-        // 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);
+        // Find an active global permit for this (actor, role) in the in-memory
+        // `auth.permits` snapshot. No DB roundtrip — same correctness-equivalent
+        // pattern as `has_scoped_role` above (race window is between predicate
+        // and `query_revoke_permit`'s actual UPDATE, not between predicate and
+        // middleware load).
+        const now = new Date();
+        const target = auth.permits.find((p) => p.role === input.role && p.scope_id === null && is_permit_active(p, now));
         if (!target) {
             return { ok: true, enabled: false, changed: false };
         }
@@ -117,10 +124,16 @@ export const create_self_service_role_actions = (deps, options) => {
             // Raced with another revoker — treat as already revoked.
             return { ok: true, enabled: false, changed: false };
         }
+        // Same actor-bound rule as the grant branch — `permit_revoke`
+        // always populates both target columns even on self-service so
+        // forensic queries that filter on `target_actor_id IS NOT NULL`
+        // don't silently miss self-toggled permits.
         void audit_log_fire_and_forget(ctx, {
             event_type: 'permit_revoke',
             actor_id: auth.actor.id,
             account_id: auth.account.id,
+            target_account_id: auth.account.id,
+            target_actor_id: auth.actor.id,
             ip: ctx.client_ip,
             metadata: {
                 role: result.role,
@@ -131,5 +144,5 @@ export const create_self_service_role_actions = (deps, options) => {
         }, deps);
         return { ok: true, enabled: false, changed: true };
     };
-    return [rpc_action(self_service_role_set_action_spec, handler)];
+    return [rpc_actor_action(self_service_role_set_action_spec, handler)];
 };

package/dist/db/migrate.d.ts

@@ -6,12 +6,15 @@
  * `(namespace, name, sequence, applied_at)` — and the runner verifies the
  * applied list is a name-prefix of the code's migration array at boot.
  *
- * **Append-only after first publish**: once a fuz_app version containing a
- * given migration is published (`npm publish` / `jsr publish`), that
- * migration's name and position are frozen. Never edit, rename, or reorder
- * after publish — append only. Pre-publish, anything goes; the cliff is the
- * publish event. Edits to a published migration's body slip past the runner
- * (no content hashing) and are caught by schema-snapshot tests in consumers.
+ * **Schema is not stabilized yet — append-only is NOT the rule.** While
+ * fuz_app is pre-stable, migration bodies, names, and positions can change
+ * freely between versions; consumers upgrading across a schema change are
+ * expected to drop and re-bootstrap their dev/test databases (production
+ * deployments are not yet a supported use case). Once the schema is
+ * declared stable a hard append-only-after-publish rule will apply and the
+ * cliff will be called out in that release's notes; until then, body edits
+ * to a published migration slip past the runner (no content hashing) by
+ * design — they're the recommended way to evolve the schema.
  *
  * **Chain-level transactions**: All pending migrations in a namespace run in
  * a single transaction. Any failure rolls back every migration in that run —
@@ -53,7 +56,8 @@ export interface Migration {
 /**
  * A named group of ordered migrations.
  *
- * Array index = position in the chain. Append-only after publish.
+ * Array index = position in the chain. Pre-stable: bodies, names, and
+ * positions can change between versions (consumers re-bootstrap on upgrade).
  */
 export interface MigrationNamespace {
     namespace: string;

package/dist/db/migrate.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"migrate.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/db/migrate.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AAEH,OAAO,KAAK,EAAC,EAAE,EAAC,MAAM,SAAS,CAAC;AAEhC;;;;GAIG;AACH,MAAM,WAAW,SAAS;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,EAAE,CAAC,EAAE,EAAE,EAAE,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CAC9B;AAED;;;;GAIG;AACH,MAAM,WAAW,kBAAkB;IAClC,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,KAAK,CAAC,SAAS,CAAC,CAAC;CAC7B;AAED,2DAA2D;AAC3D,MAAM,WAAW,eAAe;IAC/B,SAAS,EAAE,MAAM,CAAC;IAClB,+EAA+E;IAC/E,aAAa,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;CAC7B;AAED;;;;;GAKG;AACH,MAAM,MAAM,kBAAkB,GAC3B,sBAAsB,GACtB,sBAAsB,GACtB,mBAAmB,GACnB,kBAAkB,GAClB,2BAA2B,GAC3B,4BAA4B,GAC5B,sCAAsC,CAAC;AAE1C,8DAA8D;AAC9D,MAAM,WAAW,qBAAqB;IACrC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,aAAa,CAAC,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;IACtC,KAAK,CAAC,EAAE,OAAO,CAAC;CAChB;AAED;;;;GAIG;AACH,qBAAa,cAAe,SAAQ,KAAK;IACxC,QAAQ,CAAC,IAAI,EAAE,kBAAkB,CAAC;IAClC,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,aAAa,CAAC,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;gBAEnC,IAAI,EAAE,kBAAkB,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,qBAAqB;CAQtF;AA6ED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,eAAO,MAAM,cAAc,GAC1B,IAAI,EAAE,EACN,YAAY,KAAK,CAAC,kBAAkB,CAAC,KACnC,OAAO,CAAC,KAAK,CAAC,eAAe,CAAC,CAuFhC,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,eAAO,MAAM,QAAQ,GACpB,IAAI,EAAE,EACN,IAAI,kBAAkB,EACtB,OAAO,aAAa,CAAC,MAAM,CAAC,KAC1B,OAAO,CAAC,IAAI,CA+Dd,CAAC"}
+{"version":3,"file":"migrate.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/db/migrate.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4CG;AAEH,OAAO,KAAK,EAAC,EAAE,EAAC,MAAM,SAAS,CAAC;AAEhC;;;;GAIG;AACH,MAAM,WAAW,SAAS;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,EAAE,CAAC,EAAE,EAAE,EAAE,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CAC9B;AAED;;;;;GAKG;AACH,MAAM,WAAW,kBAAkB;IAClC,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,KAAK,CAAC,SAAS,CAAC,CAAC;CAC7B;AAED,2DAA2D;AAC3D,MAAM,WAAW,eAAe;IAC/B,SAAS,EAAE,MAAM,CAAC;IAClB,+EAA+E;IAC/E,aAAa,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;CAC7B;AAED;;;;;GAKG;AACH,MAAM,MAAM,kBAAkB,GAC3B,sBAAsB,GACtB,sBAAsB,GACtB,mBAAmB,GACnB,kBAAkB,GAClB,2BAA2B,GAC3B,4BAA4B,GAC5B,sCAAsC,CAAC;AAE1C,8DAA8D;AAC9D,MAAM,WAAW,qBAAqB;IACrC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,aAAa,CAAC,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;IACtC,KAAK,CAAC,EAAE,OAAO,CAAC;CAChB;AAED;;;;GAIG;AACH,qBAAa,cAAe,SAAQ,KAAK;IACxC,QAAQ,CAAC,IAAI,EAAE,kBAAkB,CAAC;IAClC,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,aAAa,CAAC,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;gBAEnC,IAAI,EAAE,kBAAkB,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,qBAAqB;CAQtF;AA6ED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,eAAO,MAAM,cAAc,GAC1B,IAAI,EAAE,EACN,YAAY,KAAK,CAAC,kBAAkB,CAAC,KACnC,OAAO,CAAC,KAAK,CAAC,eAAe,CAAC,CAuFhC,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,eAAO,MAAM,QAAQ,GACpB,IAAI,EAAE,EACN,IAAI,kBAAkB,EACtB,OAAO,aAAa,CAAC,MAAM,CAAC,KAC1B,OAAO,CAAC,IAAI,CA+Dd,CAAC"}

package/dist/db/migrate.js

@@ -6,12 +6,15 @@
  * `(namespace, name, sequence, applied_at)` — and the runner verifies the
  * applied list is a name-prefix of the code's migration array at boot.
  *
- * **Append-only after first publish**: once a fuz_app version containing a
- * given migration is published (`npm publish` / `jsr publish`), that
- * migration's name and position are frozen. Never edit, rename, or reorder
- * after publish — append only. Pre-publish, anything goes; the cliff is the
- * publish event. Edits to a published migration's body slip past the runner
- * (no content hashing) and are caught by schema-snapshot tests in consumers.
+ * **Schema is not stabilized yet — append-only is NOT the rule.** While
+ * fuz_app is pre-stable, migration bodies, names, and positions can change
+ * freely between versions; consumers upgrading across a schema change are
+ * expected to drop and re-bootstrap their dev/test databases (production
+ * deployments are not yet a supported use case). Once the schema is
+ * declared stable a hard append-only-after-publish rule will apply and the
+ * cliff will be called out in that release's notes; until then, body edits
+ * to a published migration slip past the runner (no content hashing) by
+ * design — they're the recommended way to evolve the schema.
  *
  * **Chain-level transactions**: All pending migrations in a namespace run in
  * a single transaction. Any failure rolls back every migration in that run —

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

@@ -1 +1 @@
-{"version":3,"file":"setup.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/dev/setup.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"setup.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/dev/setup.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EACX,WAAW,EACX,aAAa,EACb,OAAO,EACP,UAAU,EACV,YAAY,EACZ,WAAW,EACX,MAAM,oBAAoB,CAAC;AAC5B,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,qBAAqB,CAAC;AAQnD;;;;;GAKG;AACH,MAAM,WAAW,WAAW;IAC3B,EAAE,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC;IAC1B,IAAI,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC;IAC5B,KAAK,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC;CAC7B;AAED,2CAA2C;AAC3C,eAAO,MAAM,oBAAoB,EAAE,WAIlC,CAAC;AAEF,kCAAkC;AAClC,MAAM,WAAW,cAAc;IAC9B,6DAA6D;IAC7D,OAAO,EAAE,OAAO,CAAC;IACjB,kDAAkD;IAClD,OAAO,EAAE,OAAO,CAAC;IACjB,yBAAyB;IACzB,IAAI,EAAE,MAAM,CAAC;CACb;AAED,yCAAyC;AACzC,MAAM,WAAW,gBAAgB;IAChC,kEAAkE;IAClE,OAAO,EAAE,OAAO,CAAC;IACjB,2BAA2B;IAC3B,UAAU,EAAE,MAAM,CAAC;CACnB;AAED,kCAAkC;AAClC,MAAM,WAAW,aAAa;IAC7B,+CAA+C;IAC/C,KAAK,EAAE,OAAO,CAAC;IACf,wEAAwE;IACxE,OAAO,EAAE,OAAO,CAAC;IACjB,0CAA0C;IAC1C,OAAO,EAAE,UAAU,GAAG,QAAQ,GAAG,MAAM,CAAC;CACxC;AAED,oCAAoC;AACpC,MAAM,WAAW,eAAe;IAC/B;;;;;OAKG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC;IACrD,qEAAqE;IACrE,eAAe,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAChE,GAAG,CAAC,EAAE,WAAW,CAAC;CAClB;AAED,2CAA2C;AAC3C,MAAM,WAAW,0BAA0B;IAC1C,6DAA6D;IAC7D,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,2DAA2D;IAC3D,eAAe,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAChE,GAAG,CAAC,EAAE,WAAW,CAAC;CAClB;AAED,qCAAqC;AACrC,MAAM,WAAW,qBAAqB;IACrC,GAAG,CAAC,EAAE,WAAW,CAAC;CAClB;AAED,oCAAoC;AACpC,MAAM,WAAW,oBAAoB;IACpC,iDAAiD;IACjD,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,GAAG,CAAC,EAAE,WAAW,CAAC;CAClB;AAID;;;;GAIG;AACH,eAAO,MAAM,aAAa,GAAI,KAAK,MAAM,KAAG,MAAM,GAAG,IAQpD,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,mBAAmB,GAAU,MAAM,WAAW,KAAG,OAAO,CAAC,MAAM,CAI3E,CAAC;AAIF;;;;;;;GAOG;AACH,eAAO,MAAM,YAAY,GACxB,MAAM,IAAI,CAAC,UAAU,EAAE,MAAM,GAAG,gBAAgB,CAAC,EACjD,UAAU,MAAM,EAChB,MAAM,MAAM,KACV,OAAO,CAAC,MAAM,GAAG,SAAS,CAU5B,CAAC;AAIF;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,cAAc,GAC1B,MAAM,UAAU,GAAG,WAAW,GAAG,WAAW,EAC5C,UAAU,MAAM,EAChB,cAAc,MAAM,EACpB,UAAU,eAAe,KACvB,OAAO,CAAC,cAAc,CAiDxB,CAAC;AAEF;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,qBAAqB,GACjC,MAAM,UAAU,GAAG,WAAW,GAAG,WAAW,GAAG,OAAO,EACtD,UAAU,MAAM,EAChB,UAAU,0BAA0B,KAClC,OAAO,CAAC,gBAAgB,CA0B1B,CAAC;AAEF;;;;;;;;GAQG;AACH,eAAO,MAAM,qBAAqB,GACjC,MAAM,UAAU,GAAG,WAAW,GAAG,YAAY,GAAG,WAAW,GAAG,OAAO,EACrE,UAAU,MAAM,EAChB,UAAU,0BAA0B,KAClC,OAAO,CAAC,gBAAgB,CAoB1B,CAAC;AAIF;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,eAAe,GAC3B,MAAM,WAAW,EACjB,SAAS,MAAM,EACf,UAAU,qBAAqB,KAC7B,OAAO,CAAC,aAAa,CAgBvB,CAAC;AAEF;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,cAAc,GAC1B,MAAM,WAAW,GAAG,UAAU,GAAG,YAAY,EAC7C,cAAc,MAAM,EACpB,UAAU,oBAAoB,KAC5B,OAAO,CAAC,aAAa,CA8CvB,CAAC;AAIF,mCAAmC;AACnC,MAAM,WAAW,mBAAmB;IACnC,+EAA+E;IAC/E,QAAQ,EAAE,MAAM,CAAC;IACjB,+EAA+E;IAC/E,QAAQ,EAAE,MAAM,CAAC;IACjB,8CAA8C;IAC9C,KAAK,CAAC,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;CAC9B;AAED,oCAAoC;AACpC,MAAM,WAAW,oBAAoB;IACpC,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;IACjB,uEAAuE;IACvE,OAAO,EAAE,OAAO,CAAC;CACjB;AAED,2CAA2C;AAC3C,MAAM,WAAW,kBAAmB,SAAQ,SAAS;IACpD,oEAAoE;IACpE,aAAa,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;CACrD;AAED;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,gBAAgB,GAC5B,MAAM,kBAAkB,EACxB,OAAO,mBAAmB,EAC1B,UAAU;IAAC,GAAG,CAAC,EAAE,WAAW,CAAA;CAAC,KAC3B,OAAO,CAAC,oBAAoB,CAwC9B,CAAC"}

package/dist/dev/setup.js

@@ -8,7 +8,7 @@
  *
  * @module
  */
-import { query_account_by_username, query_actor_by_account, query_create_account_with_actor, } from '../auth/account_queries.js';
+import { query_account_by_username, query_actors_by_account, query_create_account_with_actor, } from '../auth/account_queries.js';
 import { query_grant_permit } from '../auth/permit_queries.js';
 /** Default logger using bracket format. */
 export const default_setup_logger = {
@@ -292,11 +292,13 @@ export const seed_dev_account = async (deps, input, options) => {
     const query_deps = { db: deps.db };
     const existing = await query_account_by_username(query_deps, input.username);
     if (existing) {
-        const actor = await query_actor_by_account(query_deps, existing.id);
-        if (!actor) {
+        const actors = await query_actors_by_account(query_deps, existing.id);
+        if (actors.length === 0) {
             log.error(`dev account '${input.username}' exists but has no actor`);
             throw new Error(`dev account '${input.username}' has no actor`);
         }
+        // Dev seed is single-actor by construction; pick the first.
+        const actor = actors[0];
         for (const role of input.roles ?? []) {
             await query_grant_permit(query_deps, {
                 actor_id: actor.id,

package/dist/hono_context.d.ts

@@ -25,6 +25,63 @@ export type CredentialType = z.infer<typeof CredentialType>;
 export declare const CREDENTIAL_TYPE_KEY = "credential_type";
 /** Hono context variable name for the authenticated API token id. */
 export declare const AUTH_API_TOKEN_ID_KEY = "auth_api_token_id";
+/**
+ * Hono context variable name for the authenticated account id.
+ *
+ * Set by the auth middleware (session, bearer, or daemon token) on a valid
+ * credential. `null` for unauthenticated requests. The route-spec wrapper /
+ * RPC dispatcher's authorization phase reads this when resolving the acting
+ * actor; account-grain auth guards (`require_auth`) and account-grain handlers
+ * read it directly.
+ */
+export declare const ACCOUNT_ID_KEY = "auth_account_id";
+/**
+ * Hono context variable name for the test-harness pre-baked context flag.
+ *
+ * Test harnesses (`create_test_app_from_specs`, `create_fake_hono_context`,
+ * the WS round-trip `connect()` helper, plus per-test middleware that
+ * pre-populates `REQUEST_CONTEXT_KEY`) set this to `true` so
+ * `apply_authorization_phase` skips its DB-backed actor resolution and
+ * trusts the supplied `RequestContext`. Production middleware never sets
+ * this key — only test code does. The flag is the explicit escape hatch
+ * that replaced the implicit "is `REQUEST_CONTEXT_KEY` already set?" probe,
+ * so that future production code consulting `REQUEST_CONTEXT_KEY` cannot
+ * silently bypass the live build.
+ */
+export declare const TEST_CONTEXT_PRESET_KEY = "test_context_preset";
+/**
+ * Cached parsed JSON request body, keyed by `'cached_request_body'`.
+ *
+ * Written by `read_raw_acting` (in the dispatcher's authorization
+ * phase) when it pre-parses the body to extract the `acting` field;
+ * read by `create_input_validation` so the input-validation step does
+ * not pay for a second `JSON.parse` on the same Hono-cached body text.
+ *
+ * Decouples our pipeline from Hono's internal `bodyCache` shape: Hono
+ * caches the body *text* (so a second `c.req.json()` call doesn't
+ * re-read the request stream), but each call still re-runs
+ * `JSON.parse(text)`. Storing the parsed value here saves the second
+ * parse and keeps fuz_app from depending on undocumented Hono
+ * implementation details.
+ *
+ * Three states:
+ *
+ * - Key absent — body has not been pre-parsed yet (the route had no
+ *   `acting` to extract, or the request is GET).
+ * - `{ok: true, body: unknown}` — pre-parse succeeded; the parsed
+ *   value (object, primitive, or array) is in `body`.
+ * - `{ok: false}` — pre-parse threw (malformed JSON). The downstream
+ *   input-validation step short-circuits with `ERROR_INVALID_JSON_BODY`
+ *   instead of re-parsing.
+ */
+export declare const CACHED_REQUEST_BODY_KEY = "cached_request_body";
+/** The shape stored under `CACHED_REQUEST_BODY_KEY`. */
+export type CachedRequestBody = {
+    ok: true;
+    body: unknown;
+} | {
+    ok: false;
+};
 declare module 'hono' {
     interface ContextVariableMap {
         /** Resolved client IP, set by the trusted proxy middleware. */
@@ -36,6 +93,13 @@ declare module 'hono' {
         validated_query: unknown;
         /** How the request was authenticated (`'session'`, `'api_token'`, or `'daemon_token'`). */
         credential_type: CredentialType | null;
+        /**
+         * Authenticated account id. Set by the session / bearer / daemon-token
+         * middleware on a valid credential; `null` for unauthenticated requests.
+         * The dispatcher's authorization phase resolves the acting actor against
+         * this id; `require_auth` 401s when it is `null`.
+         */
+        auth_account_id: string | null;
         /**
          * blake3 hash of the authenticated session token, or `null` for non-session
          * credentials. Set by `create_request_context_middleware`. Used to scope
@@ -57,6 +121,19 @@ declare module 'hono' {
          * all effects are awaited before the response returns.
          */
         pending_effects: Array<Promise<void>>;
+        /**
+         * Set to `true` by test harnesses that pre-populate `request_context`
+         * to bypass the dispatcher's DB-backed actor resolution. Read by
+         * `apply_authorization_phase`. Production middleware never sets this.
+         */
+        test_context_preset: boolean;
+        /**
+         * Pre-parsed JSON request body cache. Written by `read_raw_acting`
+         * (the dispatcher's `acting` extractor) and read by
+         * `create_input_validation` so the same body is not parsed twice.
+         * See `CACHED_REQUEST_BODY_KEY` for state semantics.
+         */
+        cached_request_body: CachedRequestBody;
     }
 }
 //# sourceMappingURL=hono_context.d.ts.map

package/dist/hono_context.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"hono_context.d.ts","sourceRoot":"../src/lib/","sources":["../src/lib/hono_context.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAC,CAAC,EAAC,MAAM,KAAK,CAAC;AAEtB,OAAO,KAAK,EAAC,cAAc,EAAC,MAAM,2BAA2B,CAAC;AAE9D,4DAA4D;AAC5D,eAAO,MAAM,gBAAgB,mDAAoD,CAAC;AAElF,yDAAyD;AACzD,eAAO,MAAM,cAAc;;;;EAA2B,CAAC;AACvD,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,cAAc,CAAC,CAAC;AAE5D,0DAA0D;AAC1D,eAAO,MAAM,mBAAmB,oBAAoB,CAAC;AAErD,qEAAqE;AACrE,eAAO,MAAM,qBAAqB,sBAAsB,CAAC;AAEzD,OAAO,QAAQ,MAAM,CAAC;IACrB,UAAU,kBAAkB;QAC3B,+DAA+D;QAC/D,SAAS,EAAE,MAAM,CAAC;QAClB,eAAe,EAAE,MAAM,GAAG,IAAI,CAAC;QAC/B,eAAe,EAAE,cAAc,GAAG,IAAI,CAAC;QACvC,eAAe,EAAE,OAAO,CAAC;QACzB,gBAAgB,EAAE,OAAO,CAAC;QAC1B,eAAe,EAAE,OAAO,CAAC;QACzB,2FAA2F;QAC3F,eAAe,EAAE,cAAc,GAAG,IAAI,CAAC;QACvC;;;;;WAKG;QACH,uBAAuB,EAAE,MAAM,GAAG,IAAI,CAAC;QACvC;;;;;;WAMG;QACH,iBAAiB,EAAE,MAAM,GAAG,IAAI,CAAC;QACjC;;;;WAIG;QACH,eAAe,EAAE,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC;KACtC;CACD"}
+{"version":3,"file":"hono_context.d.ts","sourceRoot":"../src/lib/","sources":["../src/lib/hono_context.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAC,CAAC,EAAC,MAAM,KAAK,CAAC;AAEtB,OAAO,KAAK,EAAC,cAAc,EAAC,MAAM,2BAA2B,CAAC;AAE9D,4DAA4D;AAC5D,eAAO,MAAM,gBAAgB,mDAAoD,CAAC;AAElF,yDAAyD;AACzD,eAAO,MAAM,cAAc;;;;EAA2B,CAAC;AACvD,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,cAAc,CAAC,CAAC;AAE5D,0DAA0D;AAC1D,eAAO,MAAM,mBAAmB,oBAAoB,CAAC;AAErD,qEAAqE;AACrE,eAAO,MAAM,qBAAqB,sBAAsB,CAAC;AAEzD;;;;;;;;GAQG;AACH,eAAO,MAAM,cAAc,oBAAoB,CAAC;AAEhD;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,uBAAuB,wBAAwB,CAAC;AAE7D;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,eAAO,MAAM,uBAAuB,wBAAwB,CAAC;AAE7D,wDAAwD;AACxD,MAAM,MAAM,iBAAiB,GAAG;IAAC,EAAE,EAAE,IAAI,CAAC;IAAC,IAAI,EAAE,OAAO,CAAA;CAAC,GAAG;IAAC,EAAE,EAAE,KAAK,CAAA;CAAC,CAAC;AAExE,OAAO,QAAQ,MAAM,CAAC;IACrB,UAAU,kBAAkB;QAC3B,+DAA+D;QAC/D,SAAS,EAAE,MAAM,CAAC;QAClB,eAAe,EAAE,MAAM,GAAG,IAAI,CAAC;QAC/B,eAAe,EAAE,cAAc,GAAG,IAAI,CAAC;QACvC,eAAe,EAAE,OAAO,CAAC;QACzB,gBAAgB,EAAE,OAAO,CAAC;QAC1B,eAAe,EAAE,OAAO,CAAC;QACzB,2FAA2F;QAC3F,eAAe,EAAE,cAAc,GAAG,IAAI,CAAC;QACvC;;;;;WAKG;QACH,eAAe,EAAE,MAAM,GAAG,IAAI,CAAC;QAC/B;;;;;WAKG;QACH,uBAAuB,EAAE,MAAM,GAAG,IAAI,CAAC;QACvC;;;;;;WAMG;QACH,iBAAiB,EAAE,MAAM,GAAG,IAAI,CAAC;QACjC;;;;WAIG;QACH,eAAe,EAAE,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC;QACtC;;;;WAIG;QACH,mBAAmB,EAAE,OAAO,CAAC;QAC7B;;;;;WAKG;QACH,mBAAmB,EAAE,iBAAiB,CAAC;KACvC;CACD"}

package/dist/hono_context.js

@@ -19,3 +19,53 @@ export const CredentialType = z.enum(CREDENTIAL_TYPES);
 export const CREDENTIAL_TYPE_KEY = 'credential_type';
 /** Hono context variable name for the authenticated API token id. */
 export const AUTH_API_TOKEN_ID_KEY = 'auth_api_token_id';
+/**
+ * Hono context variable name for the authenticated account id.
+ *
+ * Set by the auth middleware (session, bearer, or daemon token) on a valid
+ * credential. `null` for unauthenticated requests. The route-spec wrapper /
+ * RPC dispatcher's authorization phase reads this when resolving the acting
+ * actor; account-grain auth guards (`require_auth`) and account-grain handlers
+ * read it directly.
+ */
+export const ACCOUNT_ID_KEY = 'auth_account_id';
+/**
+ * Hono context variable name for the test-harness pre-baked context flag.
+ *
+ * Test harnesses (`create_test_app_from_specs`, `create_fake_hono_context`,
+ * the WS round-trip `connect()` helper, plus per-test middleware that
+ * pre-populates `REQUEST_CONTEXT_KEY`) set this to `true` so
+ * `apply_authorization_phase` skips its DB-backed actor resolution and
+ * trusts the supplied `RequestContext`. Production middleware never sets
+ * this key — only test code does. The flag is the explicit escape hatch
+ * that replaced the implicit "is `REQUEST_CONTEXT_KEY` already set?" probe,
+ * so that future production code consulting `REQUEST_CONTEXT_KEY` cannot
+ * silently bypass the live build.
+ */
+export const TEST_CONTEXT_PRESET_KEY = 'test_context_preset';
+/**
+ * Cached parsed JSON request body, keyed by `'cached_request_body'`.
+ *
+ * Written by `read_raw_acting` (in the dispatcher's authorization
+ * phase) when it pre-parses the body to extract the `acting` field;
+ * read by `create_input_validation` so the input-validation step does
+ * not pay for a second `JSON.parse` on the same Hono-cached body text.
+ *
+ * Decouples our pipeline from Hono's internal `bodyCache` shape: Hono
+ * caches the body *text* (so a second `c.req.json()` call doesn't
+ * re-read the request stream), but each call still re-runs
+ * `JSON.parse(text)`. Storing the parsed value here saves the second
+ * parse and keeps fuz_app from depending on undocumented Hono
+ * implementation details.
+ *
+ * Three states:
+ *
+ * - Key absent — body has not been pre-parsed yet (the route had no
+ *   `acting` to extract, or the request is GET).
+ * - `{ok: true, body: unknown}` — pre-parse succeeded; the parsed
+ *   value (object, primitive, or array) is in `body`.
+ * - `{ok: false}` — pre-parse threw (malformed JSON). The downstream
+ *   input-validation step short-circuits with `ERROR_INVALID_JSON_BODY`
+ *   instead of re-parsing.
+ */
+export const CACHED_REQUEST_BODY_KEY = 'cached_request_body';

package/dist/http/CLAUDE.md

@@ -91,21 +91,66 @@ wrapper). See `../auth/signup_routes.ts`.
 
 `apply_route_specs` assembles the following middleware chain per spec:
 
-1. **Auth guards** — `resolve_auth_guards(spec.auth)`, injected via
-   `AuthGuardResolver` (use `fuz_auth_guard_resolver` from `../auth/route_guards.ts`)
-2. **Params validation** — `spec.params` → `validated_params` context var;
-   mismatch returns 400 `ERROR_INVALID_ROUTE_PARAMS` with Zod `issues`
-3. **Query validation** — `spec.query` → `validated_query`; mismatch returns
-   400 `ERROR_INVALID_QUERY_PARAMS`
-4. **Input validation** — JSON body parsed + validated; mismatch returns 400
-   `ERROR_INVALID_JSON_BODY` (not JSON) or `ERROR_INVALID_REQUEST_BODY`
-   (schema failure with `issues`). Skipped on GET and `z.null()` inputs
-5. **Handler** — wrapped in transaction when `use_transaction` (see above),
-   receives `RouteContext`
-6. **DEV-only output + error validation** — wraps the handler (see below)
-7. **Error catch** — catches `ThrownJsonrpcError` → maps to HTTP status +
-   JSON-RPC error body; catches generic `Error` → 500 `internal_error`
-   (message only included in DEV)
+1. **Params validation** — `spec.params` → `validated_params` context
+   var; mismatch returns 400 `ERROR_INVALID_ROUTE_PARAMS` with Zod
+   `issues`
+2. **Query validation** — `spec.query` → `validated_query`; mismatch
+   returns 400 `ERROR_INVALID_QUERY_PARAMS`
+3. **Pre-validation auth guards** — `require_auth` (401
+   `ERROR_AUTHENTICATION_REQUIRED`) for any non-public route. Fires
+   before any body parsing so unauthenticated callers never see
+   route-shape information from input parse failures. The
+   `AuthGuardResolver` (e.g. `fuz_auth_guard_resolver` from
+   `../auth/route_guards.ts`) returns this set as
+   `pre_validation: Array<MiddlewareHandler>`.
+4. **Authorization phase** — when the route's input schema declares
+   `acting?: ActingActor` or `spec.auth.type` is `'role'` / `'keeper'`,
+   resolves the acting actor against `c.var.account_id` (set by the
+   auth middleware) plus the raw `acting` value extracted from query
+   (GET) or pre-parsed JSON body (mutating methods), builds
+   `RequestContext` via `build_request_context`, and sets
+   `REQUEST_CONTEXT_KEY`. Resolution failures return 400
+   `ERROR_ACTOR_REQUIRED` (with `available[]`) or
+   `ERROR_ACTOR_NOT_ON_ACCOUNT` (or 500 `ERROR_NO_ACTORS_ON_ACCOUNT`
+   when the actor enumeration came back empty, 500 `ERROR_ACCOUNT_VANISHED`
+   on torn account/actor reads after a successful resolve) before the
+   handler runs. Account-grain
+   routes skip this phase; their handlers see no `RequestContext` (or
+   one with `actor: null`, depending on the helper). The pre-parsed body
+   lands on `c.var.cached_request_body` (see step 6) so the subsequent
+   input-validation step reads from there instead of re-parsing.
+5. **Post-authorization auth guards** — `require_role(role)` /
+   `require_keeper` (403 `ERROR_INSUFFICIENT_PERMISSIONS` /
+   `ERROR_KEEPER_REQUIRES_DAEMON_TOKEN`). Reads `REQUEST_CONTEXT_KEY`
+   populated by step 4. The resolver returns this set as
+   `post_authorization: Array<MiddlewareHandler>`.
+6. **Input validation** — JSON body parsed + validated; mismatch returns
+   400 `ERROR_INVALID_JSON_BODY` (not JSON) or `ERROR_INVALID_REQUEST_BODY`
+   (schema failure with `issues`). Skipped on GET and `z.null()` inputs.
+   On mutating methods, the parse result is shared with the authorization
+   phase's pre-parse via `c.var.cached_request_body`
+   (`CACHED_REQUEST_BODY_KEY` from `hono_context.ts`) — the cache is
+   fuz_app-owned, not Hono's internal `bodyCache`, so a future Hono
+   internals refactor can't break our second-parse-avoidance contract.
+7. **Handler** — wrapped in transaction when `use_transaction` (see
+   above), receives `RouteContext`
+8. **DEV-only output + error validation** — wraps the handler (see below)
+9. **Error catch** — catches `ThrownJsonrpcError` → maps to HTTP status +
+   the flat REST `ApiError` body (`{error: <reason>, message?, ...rest_data}`);
+   catches generic `Error` → 500 `{error: 'internal_error', message?}`
+   (message only included in DEV). The reason string comes from
+   `err.data.reason` when set (consumer-supplied canonical reason
+   override) or from `jsonrpc_error_code_to_name(err.code)` (e.g.
+   `-32003 → 'not_found'`). The flat shape matches what middleware
+   and direct handlers emit (`c.json({error: ERROR_FOO}, status)`,
+   `c.json(failure.body, status)` from the dispatcher's authorization
+   phase) — REST callers see one envelope across every emit site, while
+   the JSON-RPC dispatcher keeps its own `{jsonrpc, id, error: {code,
+message, data}}` envelope on the RPC mount
+
+The auth-before-validation order matches the RPC dispatcher
+(`actions/action_rpc.ts`) so HTTP RPC and REST surface failures with
+the same priority: 401 → 403 → 400 → handler.
 
 Duplicate `method path` pairs throw at registration.
 
@@ -162,21 +207,39 @@ Pair every schema with the `z.infer` type export (`export type ApiError = z.infe
 
 ### Three-layer error-schema merge
 
-`merge_error_schemas(spec, middleware_errors?)` (in `schema_helpers.ts`)
+`merge_error_schemas(spec, middleware_errors?, acting_aware?)` (in `schema_helpers.ts`)
 merges three layers, later overrides earlier at the same status code:
 
-1. **Derived** — from `derive_error_schemas(auth, has_input, has_params, has_query, rate_limit)`:
+1. **Derived** — from `derive_error_schemas({auth, has_input?, has_params?, has_query?, rate_limit?, acting_aware?})`:
    - `has_input || has_params || has_query` → 400 `ValidationError`
    - `auth.type === 'authenticated'` → 401 `ApiError`
    - `auth.type === 'role'` → 401 `ApiError` + 403 `PermissionError`
    - `auth.type === 'keeper'` → 401 `ApiError` + 403 `KeeperError`
    - `rate_limit` → 429 `RateLimitError`
+   - `acting_aware` → widens 400 to a union with `ActorRequiredError` /
+     `ActorNotOnAccountError` and adds 500 union of `NoActorsOnAccountError`
+     / `AccountVanishedError`. Mirrors what the dispatcher's authorization
+     phase actually emits on routes whose input declares `acting?: ActingActor`
+     or whose auth requires permits — so DEV-mode error-schema validation in
+     `wrap_output_validation` doesn't reject the auth phase's body.
 2. **Middleware** — from `MiddlewareSpec.errors` that apply to the route's
    path (via `middleware_applies`)
 3. **Explicit** — `RouteSpec.errors` — always wins
 
 Routes typically only need `errors` for handler-specific codes (404, 409, 422).
 
+`acting_aware` is computed at the call site (`apply_route_specs` /
+`generate_app_surface`) via the optional `is_acting_aware?: (spec) => boolean`
+callback. Computation lives in the consumer because the canonical
+"input declares `acting?: ActingActor`" check uses reference equality with
+the canonical `ActingActor` Zod schema in `auth/account_schema.ts`, and
+`http/` stays auth-agnostic. fuz_app's `create_app_server` wires
+`(spec) => is_actor_implying_auth(spec.auth) || input_schema_declares_acting(spec.input)`
+— consumers building on raw `apply_route_specs` opt in by passing the
+same predicate (or a narrower one). When the callback is omitted the
+flag defaults to false so frameworks not using fuz_app's auth phase don't
+get fuz_app-specific shapes on their derived surface.
+
 ### `ERROR_*` constants by category
 
 - **Validation**: `ERROR_INVALID_REQUEST_BODY`, `ERROR_INVALID_JSON_BODY`,