@fuzdev/fuz_app 0.55.0 → 0.57.0

package/dist/http/error_schemas.d.ts

@@ -12,7 +12,7 @@
  * @module
  */
 import { z } from 'zod';
-import type { RouteAuth } from './route_spec.js';
+import { type RouteAuth } from './auth_shape.js';
 /** Request body failed Zod validation. */
 export declare const ERROR_INVALID_REQUEST_BODY: "invalid_request_body";
 /** Request body is not valid JSON or not an object. */
@@ -25,6 +25,16 @@ export declare const ERROR_INVALID_QUERY_PARAMS: "invalid_query_params";
 export declare const ERROR_AUTHENTICATION_REQUIRED: "authentication_required";
 /** Authenticated but missing required role. */
 export declare const ERROR_INSUFFICIENT_PERMISSIONS: "insufficient_permissions";
+/**
+ * Route requires a credential type the request didn't arrive on.
+ * Symmetric with `ERROR_INSUFFICIENT_PERMISSIONS` + `required_roles`:
+ * the body carries `required_credential_types: ReadonlyArray<string>`
+ * — what the route demanded, not what arrived. Today the only
+ * credential gate is keeper (`['daemon_token']`); future gates
+ * (`agent_token`, `group_actor_token`) reuse the same literal and
+ * label themselves through the array.
+ */
+export declare const ERROR_CREDENTIAL_TYPE_REQUIRED: "credential_type_required";
 /** Rate limiter rejected the request. */
 export declare const ERROR_RATE_LIMIT_EXCEEDED: "rate_limit_exceeded";
 /** Username or password is wrong (intentionally vague for enumeration prevention). */
@@ -74,8 +84,6 @@ export declare const ERROR_NO_ACTORS_ON_ACCOUNT: "no_actors_on_account";
  * `ERROR_NO_ACTORS_ON_ACCOUNT` (the actor list enumerated empty).
  */
 export declare const ERROR_ACCOUNT_VANISHED: "account_vanished";
-/** Keeper routes require daemon_token credential type. */
-export declare const ERROR_KEEPER_REQUIRES_DAEMON_TOKEN: "keeper_requires_daemon_token";
 /** Daemon token header present but malformed or not matching current/previous token. */
 export declare const ERROR_INVALID_DAEMON_TOKEN: "invalid_daemon_token";
 /** Daemon token valid but keeper account not yet resolved (pre-bootstrap). */
@@ -104,8 +112,8 @@ export declare const ERROR_INVITE_ACCOUNT_EXISTS_USERNAME: "invite_account_exist
 export declare const ERROR_INVITE_ACCOUNT_EXISTS_EMAIL: "invite_account_exists_email";
 /** Admin tried to grant a role that is not web-grantable. */
 export declare const ERROR_ROLE_NOT_WEB_GRANTABLE: "role_not_web_grantable";
-/** Permit ID not found or not owned by the target actor. */
-export declare const ERROR_PERMIT_NOT_FOUND: "permit_not_found";
+/** Role grant ID not found or not owned by the target actor. */
+export declare const ERROR_ROLE_GRANT_NOT_FOUND: "role_grant_not_found";
 /** Query parameter `event_type` is not a valid audit event type. */
 export declare const ERROR_INVALID_EVENT_TYPE: "invalid_event_type";
 /** DELETE blocked by a foreign key constraint. */
@@ -124,31 +132,61 @@ export declare const ApiError: z.ZodObject<{
 }, z.core.$loose>;
 export type ApiError = z.infer<typeof ApiError>;
 /**
- * Input validation error — returned when the request body fails Zod parsing.
+ * Input validation error — returned when params / query / body fails Zod
+ * parsing, or when the request body is not valid JSON.
  *
- * `issues` contains the Zod validation issues for diagnostic display.
+ * `error` is one of the four validation codes the framework emits.
+ * `issues` carries Zod's validation issues for diagnostic display on the
+ * three schema-failure cases (`invalid_request_body`,
+ * `invalid_route_params`, `invalid_query_params`). The `invalid_json_body`
+ * case (request body parse failure or non-object root) emits no `issues`,
+ * so the field is optional.
  */
 export declare const ValidationError: z.ZodObject<{
-    error: z.ZodString;
-    issues: z.ZodArray<z.ZodObject<{
+    error: z.ZodEnum<{
+        invalid_request_body: "invalid_request_body";
+        invalid_json_body: "invalid_json_body";
+        invalid_route_params: "invalid_route_params";
+        invalid_query_params: "invalid_query_params";
+    }>;
+    issues: z.ZodOptional<z.ZodArray<z.ZodObject<{
         code: z.ZodString;
         message: z.ZodString;
         path: z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>;
-    }, z.core.$loose>>;
+    }, z.core.$loose>>>;
 }, z.core.$loose>;
 export type ValidationError = z.infer<typeof ValidationError>;
-/** Permission error — returned by `require_role()` when the required role is missing. */
+/**
+ * Permission error — returned by `require_role()` and the dispatcher's
+ * post-authorization role gate when the actor's role_grants don't include any
+ * of the route's `auth.roles`.
+ *
+ * `required_roles` carries the full disjunction the route declared
+ * (`auth.roles` from the new flat-record shape). Single-role specs surface
+ * as a one-element array; multi-role disjunctions show every admittable
+ * role so clients can render targeted copy ("requires admin or steward").
+ */
 export declare const PermissionError: z.ZodObject<{
     error: z.ZodLiteral<"insufficient_permissions">;
-    required_role: z.ZodString;
+    required_roles: z.ZodReadonly<z.ZodArray<z.ZodString>>;
 }, z.core.$loose>;
 export type PermissionError = z.infer<typeof PermissionError>;
-/** Keeper credential error — returned by `require_keeper` when credential type is wrong. */
-export declare const KeeperError: z.ZodObject<{
-    error: z.ZodLiteral<"keeper_requires_daemon_token">;
-    credential_type: z.ZodString;
+/**
+ * Credential-type error — returned by the dispatcher's post-authorization
+ * credential gate (and the `require_credential_types` REST middleware) when
+ * the request's credential type isn't in the route's
+ * `auth.credential_types` allowlist.
+ *
+ * `required_credential_types` carries what the route declared
+ * (`['daemon_token']` for keeper; future gates carry their own labels).
+ * Symmetric with `PermissionError`'s `required_roles`: clients see what
+ * the route demanded, not what their credential is.
+ */
+export declare const CredentialTypeRequiredError: z.ZodObject<{
+    error: z.ZodLiteral<"credential_type_required">;
+    required_credential_types: z.ZodReadonly<z.ZodArray<z.ZodString>>;
 }, z.core.$loose>;
-export type KeeperError = z.infer<typeof KeeperError>;
+export type CredentialTypeRequiredError = z.infer<typeof CredentialTypeRequiredError>;
 /** Rate limit error — returned when a rate limiter rejects the request. */
 export declare const RateLimitError: z.ZodObject<{
     error: z.ZodLiteral<"rate_limit_exceeded">;
@@ -169,7 +207,7 @@ export type ForeignKeyError = z.infer<typeof ForeignKeyError>;
  * Authorization-phase failure shapes. Surfaced when the dispatcher's
  * `apply_authorization_phase` rejects a request before the handler runs —
  * the route is acting-aware (input declares `acting?: ActingActor` or
- * auth requires permits), but actor resolution failed.
+ * auth requires role_grants), but actor resolution failed.
  *
  * 400: `actor_required` (with `available[]`) for unspecified-actor on
  * a multi-actor account; `actor_not_on_account` for a supplied actor
@@ -180,7 +218,7 @@ export type ForeignKeyError = z.infer<typeof ForeignKeyError>;
  * race (account/actor row deleted between credential validation and
  * the dispatcher's follow-up read).
  *
- * Used by `derive_error_schemas` when `acting_aware` is true so the
+ * Used by `derive_error_schemas` when `auth.actor !== 'none'` so the
  * merged error surface matches what the dispatcher actually emits.
  */
 export declare const ActorRequiredError: z.ZodObject<{
@@ -232,24 +270,20 @@ export type RateLimitKey = z.infer<typeof RateLimitKey>;
  * Route handlers can declare additional error schemas via `RouteSpec.errors`;
  * explicit entries override auto-derived ones for the same status code.
  *
- * Derivation rules:
- * - **Has input schema** (non-null) or **has params schema** or **has query schema**: 400 (validation error with issues)
- * - **auth: authenticated**: 401
- * - **auth: role**: 401 + 403 (with `required_role`)
- * - **auth: keeper**: 401 + 403 (keeper-specific)
- * - **rate_limit**: 429 (rate limit exceeded with `retry_after`)
- * - **acting_aware**: extends 400 with `ActorRequiredError` / `ActorNotOnAccountError`
- *   and adds 500 union of `NoActorsOnAccountError` / `AccountVanishedError`. The
- *   dispatcher's authorization phase emits these on routes whose input declares
- *   `acting?: ActingActor` or whose auth requires permits (`role` / `keeper`); the
- *   route's surface must reflect them so DEV-mode error-schema validation in
- *   `wrap_output_validation` doesn't fail when the auth phase fires before the
- *   handler. See `http/CLAUDE.md` § Three-layer error-schema merge.
- *
- * `acting_aware` is computed at the merge call site (it requires inspecting
- * the input schema for `acting?: ActingActor`, which lives in `auth/`). This
- * keeps `http/` auth-agnostic — the per-route flag flows in via the optional
- * `is_acting_aware` callback on `apply_route_specs` / `generate_app_surface`.
+ * Derivation rules under the new flat-record auth shape:
+ * - **Has input / params / query schema**: 400 (`ValidationError`).
+ * - **`auth.account === 'required'`** or **`auth.actor === 'required'`**: 401
+ *   (`ApiError`) — pre-validation 401 fires when the credential isn't there.
+ *   `'optional'` does not derive 401.
+ * - **`auth.roles?.length`**: 403 (`PermissionError` carrying `required_roles`).
+ * - **`auth.credential_types?.length`**: 403 (`CredentialTypeRequiredError`
+ *   carrying `required_credential_types` — symmetric with `PermissionError`).
+ *   Today the only credential gate is keeper; future gates reuse the literal.
+ * - **`auth.actor !== 'none'`** (`'optional'` or `'required'`): extends 400
+ *   with `ActorRequiredError` / `ActorNotOnAccountError` and adds 500 union
+ *   of `NoActorsOnAccountError` / `AccountVanishedError`. The dispatcher's
+ *   authorization phase emits these whenever it tries to resolve an actor.
+ * - **rate_limit**: 429 (`RateLimitError` with `retry_after`).
  */
 export interface DeriveErrorSchemasOptions {
     auth: RouteAuth;
@@ -257,7 +291,6 @@ export interface DeriveErrorSchemasOptions {
     has_params?: boolean;
     has_query?: boolean;
     rate_limit?: RateLimitKey;
-    acting_aware?: boolean;
 }
-export declare const derive_error_schemas: ({ auth, has_input, has_params, has_query, rate_limit, acting_aware, }: DeriveErrorSchemasOptions) => RouteErrorSchemas;
+export declare const derive_error_schemas: ({ auth, has_input, has_params, has_query, rate_limit, }: DeriveErrorSchemasOptions) => RouteErrorSchemas;
 //# sourceMappingURL=error_schemas.d.ts.map

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

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

package/dist/http/error_schemas.js

@@ -12,6 +12,7 @@
  * @module
  */
 import { z } from 'zod';
+import { needs_actor } from './auth_shape.js';
 // --- Core: Validation (auto-derived by route spec middleware) ---
 /** Request body failed Zod validation. */
 export const ERROR_INVALID_REQUEST_BODY = 'invalid_request_body';
@@ -26,6 +27,16 @@ export const ERROR_INVALID_QUERY_PARAMS = 'invalid_query_params';
 export const ERROR_AUTHENTICATION_REQUIRED = 'authentication_required';
 /** Authenticated but missing required role. */
 export const ERROR_INSUFFICIENT_PERMISSIONS = 'insufficient_permissions';
+/**
+ * Route requires a credential type the request didn't arrive on.
+ * Symmetric with `ERROR_INSUFFICIENT_PERMISSIONS` + `required_roles`:
+ * the body carries `required_credential_types: ReadonlyArray<string>`
+ * — what the route demanded, not what arrived. Today the only
+ * credential gate is keeper (`['daemon_token']`); future gates
+ * (`agent_token`, `group_actor_token`) reuse the same literal and
+ * label themselves through the array.
+ */
+export const ERROR_CREDENTIAL_TYPE_REQUIRED = 'credential_type_required';
 /** Rate limiter rejected the request. */
 export const ERROR_RATE_LIMIT_EXCEEDED = 'rate_limit_exceeded';
 /** Username or password is wrong (intentionally vague for enumeration prevention). */
@@ -77,8 +88,6 @@ export const ERROR_NO_ACTORS_ON_ACCOUNT = 'no_actors_on_account';
  */
 export const ERROR_ACCOUNT_VANISHED = 'account_vanished';
 // --- Keeper / daemon token ---
-/** Keeper routes require daemon_token credential type. */
-export const ERROR_KEEPER_REQUIRES_DAEMON_TOKEN = 'keeper_requires_daemon_token';
 /** Daemon token header present but malformed or not matching current/previous token. */
 export const ERROR_INVALID_DAEMON_TOKEN = 'invalid_daemon_token';
 /** Daemon token valid but keeper account not yet resolved (pre-bootstrap). */
@@ -110,8 +119,8 @@ export const ERROR_INVITE_ACCOUNT_EXISTS_EMAIL = 'invite_account_exists_email';
 // --- Admin routes ---
 /** Admin tried to grant a role that is not web-grantable. */
 export const ERROR_ROLE_NOT_WEB_GRANTABLE = 'role_not_web_grantable';
-/** Permit ID not found or not owned by the target actor. */
-export const ERROR_PERMIT_NOT_FOUND = 'permit_not_found';
+/** Role grant ID not found or not owned by the target actor. */
+export const ERROR_ROLE_GRANT_NOT_FOUND = 'role_grant_not_found';
 /** Query parameter `event_type` is not a valid audit event type. */
 export const ERROR_INVALID_EVENT_TYPE = 'invalid_event_type';
 // --- DB table browser ---
@@ -130,27 +139,59 @@ export const ERROR_DATABASE_CONNECTION_FAILED = 'database_connection_failed';
 /** Base API error — all JSON error responses have at least `{error: string}`. */
 export const ApiError = z.looseObject({ error: z.string() });
 /**
- * Input validation error — returned when the request body fails Zod parsing.
+ * Input validation error — returned when params / query / body fails Zod
+ * parsing, or when the request body is not valid JSON.
  *
- * `issues` contains the Zod validation issues for diagnostic display.
+ * `error` is one of the four validation codes the framework emits.
+ * `issues` carries Zod's validation issues for diagnostic display on the
+ * three schema-failure cases (`invalid_request_body`,
+ * `invalid_route_params`, `invalid_query_params`). The `invalid_json_body`
+ * case (request body parse failure or non-object root) emits no `issues`,
+ * so the field is optional.
  */
 export const ValidationError = z.looseObject({
-    error: z.string(),
-    issues: z.array(z.looseObject({
+    error: z.enum([
+        ERROR_INVALID_REQUEST_BODY,
+        ERROR_INVALID_JSON_BODY,
+        ERROR_INVALID_ROUTE_PARAMS,
+        ERROR_INVALID_QUERY_PARAMS,
+    ]),
+    issues: z
+        .array(z.looseObject({
         code: z.string(),
         message: z.string(),
         path: z.array(z.union([z.string(), z.number()])),
-    })),
+    }))
+        .optional(),
 });
-/** Permission error — returned by `require_role()` when the required role is missing. */
+/**
+ * Permission error — returned by `require_role()` and the dispatcher's
+ * post-authorization role gate when the actor's role_grants don't include any
+ * of the route's `auth.roles`.
+ *
+ * `required_roles` carries the full disjunction the route declared
+ * (`auth.roles` from the new flat-record shape). Single-role specs surface
+ * as a one-element array; multi-role disjunctions show every admittable
+ * role so clients can render targeted copy ("requires admin or steward").
+ */
 export const PermissionError = z.looseObject({
     error: z.literal(ERROR_INSUFFICIENT_PERMISSIONS),
-    required_role: z.string(),
+    required_roles: z.array(z.string()).readonly(),
 });
-/** Keeper credential error — returned by `require_keeper` when credential type is wrong. */
-export const KeeperError = z.looseObject({
-    error: z.literal(ERROR_KEEPER_REQUIRES_DAEMON_TOKEN),
-    credential_type: z.string(),
+/**
+ * Credential-type error — returned by the dispatcher's post-authorization
+ * credential gate (and the `require_credential_types` REST middleware) when
+ * the request's credential type isn't in the route's
+ * `auth.credential_types` allowlist.
+ *
+ * `required_credential_types` carries what the route declared
+ * (`['daemon_token']` for keeper; future gates carry their own labels).
+ * Symmetric with `PermissionError`'s `required_roles`: clients see what
+ * the route demanded, not what their credential is.
+ */
+export const CredentialTypeRequiredError = z.looseObject({
+    error: z.literal(ERROR_CREDENTIAL_TYPE_REQUIRED),
+    required_credential_types: z.array(z.string()).readonly(),
 });
 /** Rate limit error — returned when a rate limiter rejects the request. */
 export const RateLimitError = z.looseObject({
@@ -169,7 +210,7 @@ export const ForeignKeyError = z.looseObject({
  * Authorization-phase failure shapes. Surfaced when the dispatcher's
  * `apply_authorization_phase` rejects a request before the handler runs —
  * the route is acting-aware (input declares `acting?: ActingActor` or
- * auth requires permits), but actor resolution failed.
+ * auth requires role_grants), but actor resolution failed.
  *
  * 400: `actor_required` (with `available[]`) for unspecified-actor on
  * a multi-actor account; `actor_not_on_account` for a supplied actor
@@ -180,7 +221,7 @@ export const ForeignKeyError = z.looseObject({
  * race (account/actor row deleted between credential validation and
  * the dispatcher's follow-up read).
  *
- * Used by `derive_error_schemas` when `acting_aware` is true so the
+ * Used by `derive_error_schemas` when `auth.actor !== 'none'` so the
  * merged error surface matches what the dispatcher actually emits.
  */
 export const ActorRequiredError = z.looseObject({
@@ -207,10 +248,10 @@ export const AccountVanishedError = z.looseObject({
  * - `'both'` — both keys.
  */
 export const RateLimitKey = z.enum(['ip', 'account', 'both']);
-export const derive_error_schemas = ({ auth, has_input = false, has_params = false, has_query = false, rate_limit, acting_aware = false, }) => {
+export const derive_error_schemas = ({ auth, has_input = false, has_params = false, has_query = false, rate_limit, }) => {
     const errors = {};
     const has_validation = has_input || has_params || has_query;
-    if (acting_aware) {
+    if (needs_actor(auth)) {
         errors[400] = has_validation
             ? z.union([ValidationError, ActorRequiredError, ActorNotOnAccountError])
             : z.union([ActorRequiredError, ActorNotOnAccountError]);
@@ -219,20 +260,27 @@ export const derive_error_schemas = ({ auth, has_input = false, has_params = fal
     else if (has_validation) {
         errors[400] = ValidationError;
     }
-    switch (auth.type) {
-        case 'none':
-            break;
-        case 'authenticated':
-            errors[401] = ApiError;
-            break;
-        case 'role':
-            errors[401] = ApiError;
-            errors[403] = PermissionError;
-            break;
-        case 'keeper':
-            errors[401] = ApiError;
-            errors[403] = KeeperError;
-            break;
+    // 401 fires when the dispatcher's pre-validation gate rejects an
+    // unauthenticated caller — `account === 'required'` (no credential) or
+    // `actor === 'required'` (no credential to resolve an actor against,
+    // per registry-time invariant 3 forbidding accountless actors in v1).
+    if (auth.account === 'required' || auth.actor === 'required') {
+        errors[401] = ApiError;
+    }
+    // 403 fires when `auth.roles` or `auth.credential_types` rejects a
+    // resolved request context. With both axes set, the 403 body could be
+    // either shape — emit the union so DEV-mode error-schema validation
+    // accepts whichever the dispatcher produced.
+    const has_role_gate = !!auth.roles?.length;
+    const has_credential_gate = !!auth.credential_types?.length;
+    if (has_role_gate && has_credential_gate) {
+        errors[403] = z.union([PermissionError, CredentialTypeRequiredError]);
+    }
+    else if (has_role_gate) {
+        errors[403] = PermissionError;
+    }
+    else if (has_credential_gate) {
+        errors[403] = CredentialTypeRequiredError;
     }
     if (rate_limit) {
         errors[429] = RateLimitError;

package/dist/http/pending_effects.d.ts

@@ -1,33 +1,86 @@
 /**
- * Shared post-commit side-effect helper.
+ * Two-queue side-effect machinery for request handlers.
  *
- * WS sends and `on_audit_event` SSE broadcasts must never fire mid-transaction —
- * a rollback would leak state that never existed. Anything pushed onto
- * `pending_effects` runs after the response is sent (see the request-context
- * middleware), so this helper is the canonical home for post-commit fan-out.
+ * Handlers register fire-and-forget work in one of two queues, distinguished
+ * by their timing contract:
  *
- * Satisfied by both `RouteContext` (HTTP routes) and `ActionContext` (RPC
- * actions) — they share `{log, pending_effects}` by convention, so this
- * module stays in `http/` (both depend on it).
+ * - `pending_effects: Array<Promise<void>>` — eager. Producers push pool
+ *   writes that are already in flight (audit emits, session-touch UPDATE,
+ *   api-token usage tracking). The pool write is rollback-resilient by
+ *   virtue of running outside the request transaction; pushing the
+ *   in-flight handle lets test mode (`await_pending_effects: true`) await
+ *   it.
+ * - `post_commit_effects: Array<() => void | Promise<void>>` — deferred.
+ *   Producers go through `emit_after_commit(ctx, fn)`; the flush
+ *   middleware is the only site that ever invokes the thunk, and it does
+ *   so after the request handler (and its wrapping `db.transaction`)
+ *   returns. Used for WS sends and any work that must observe a committed
+ *   transaction.
+ *
+ * The split exists because the two shapes encode different contracts:
+ * eager pushers are saying "wait for this work that's already started";
+ * thunk pushers are saying "run this after the handler returns." Burying
+ * both behind one `Array<PendingEffect>` made `c.var.pending_effects.push(x)`
+ * ambiguous at the call site. With separate queues, the field name is
+ * the contract.
+ *
+ * Both `RouteContext` (HTTP routes) and `ActionContext` (RPC + WS
+ * actions) carry both queues by convention, so this module stays in
+ * `http/` (every transport depends on it).
  *
  * @module
  */
 import type { Logger } from '@fuzdev/fuz_util/log.js';
-/** Minimal structural context required by `emit_after_commit`. */
-export interface PendingEffectsContext {
+/**
+ * Minimal structural context required by `emit_after_commit`. Both
+ * `RouteContext` and `ActionContext` satisfy this — they each carry
+ * `log` and `post_commit_effects`.
+ */
+export interface EmitAfterCommitContext {
     log: Logger;
-    pending_effects: Array<Promise<void>>;
+    post_commit_effects: Array<() => void | Promise<void>>;
 }
 /**
  * Defer a side effect until after the handler's transaction commits.
  *
- * Exceptions thrown by `fn` are caught and logged via `ctx.log.error`, so one
- * failed send cannot corrupt the already-committed response or starve other
- * queued effects in the same tick.
+ * Pushes a raw thunk onto `ctx.post_commit_effects` — the flush
+ * middleware (in `server/app_server.ts` and the per-message WS dispatcher)
+ * is the only site that ever invokes `fn`. This is load-bearing: a
+ * previous implementation queued `Promise.resolve().then(fn)`, which
+ * JavaScript's microtask scheduler drains before the wrapping
+ * `await db.query('COMMIT')` resumes — `fn` fired mid-transaction and a
+ * rollback would leak a notification for state that never landed.
+ *
+ * The thunk shape closes that gap by deferring the work to flush time.
+ * The flush owns the per-thunk `try/catch` + `log.error` so any
+ * directly-pushed thunk (tests included) cannot escape the safety net.
+ *
+ * @param ctx - context carrying `log` and the `post_commit_effects` queue
+ * @param fn - side effect to run after commit; may return `void` or `Promise<void>`
+ * @mutates `ctx.post_commit_effects` - appends `fn` verbatim
+ */
+export declare const emit_after_commit: (ctx: EmitAfterCommitContext, fn: () => void | Promise<void>) => void;
+/**
+ * Drain an eager `pending_effects` queue: `Promise.allSettled` the
+ * in-flight handles, route every rejection through `log.error`, and
+ * fan out to `on_rejection` when supplied (production wires this to
+ * `on_effect_error` for monitoring).
+ *
+ * Returned promise resolves once every effect has settled. Never
+ * rejects. No-op when `effects` is empty (common on read-only
+ * requests).
+ *
+ * Symmetric with `flush_post_commit_effects` for the deferred queue.
+ */
+export declare const flush_pending_effects: (effects: ReadonlyArray<Promise<void>>, log: Logger, on_rejection?: (reason: unknown) => void) => Promise<void>;
+/**
+ * Drain a `post_commit_effects` queue: invoke each thunk under
+ * `try/catch`, collect any returned promises, and `Promise.allSettled`
+ * them. Synchronous throws and async rejections are routed through
+ * `log.error` so one failing effect cannot starve siblings.
  *
- * @param ctx - context carrying `log` and the `pending_effects` queue
- * @param fn - synchronous side effect to run after commit
- * @mutates `ctx.pending_effects` - appends a never-rejecting promise wrapping `fn`
+ * Returned promise resolves once every thunk has finished. Never
+ * rejects.
  */
-export declare const emit_after_commit: (ctx: PendingEffectsContext, fn: () => void) => void;
+export declare const flush_post_commit_effects: (effects: ReadonlyArray<() => void | Promise<void>>, log: Logger) => Promise<void>;
 //# sourceMappingURL=pending_effects.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"pending_effects.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/http/pending_effects.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EAAC,MAAM,EAAC,MAAM,yBAAyB,CAAC;AAEpD,kEAAkE;AAClE,MAAM,WAAW,qBAAqB;IACrC,GAAG,EAAE,MAAM,CAAC;IACZ,eAAe,EAAE,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC;CACtC;AAED;;;;;;;;;;GAUG;AACH,eAAO,MAAM,iBAAiB,GAAI,KAAK,qBAAqB,EAAE,IAAI,MAAM,IAAI,KAAG,IAU9E,CAAC"}
+{"version":3,"file":"pending_effects.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/http/pending_effects.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAEH,OAAO,KAAK,EAAC,MAAM,EAAC,MAAM,yBAAyB,CAAC;AAEpD;;;;GAIG;AACH,MAAM,WAAW,sBAAsB;IACtC,GAAG,EAAE,MAAM,CAAC;IACZ,mBAAmB,EAAE,KAAK,CAAC,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC;CACvD;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,eAAO,MAAM,iBAAiB,GAC7B,KAAK,sBAAsB,EAC3B,IAAI,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,KAC5B,IAEF,CAAC;AAEF;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,qBAAqB,GACjC,SAAS,aAAa,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,EACrC,KAAK,MAAM,EACX,eAAe,CAAC,MAAM,EAAE,OAAO,KAAK,IAAI,KACtC,OAAO,CAAC,IAAI,CASd,CAAC;AAEF;;;;;;;;GAQG;AACH,eAAO,MAAM,yBAAyB,GACrC,SAAS,aAAa,CAAC,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC,EAClD,KAAK,MAAM,KACT,OAAO,CAAC,IAAI,CAiBd,CAAC"}

package/dist/http/pending_effects.js

@@ -1,35 +1,104 @@
 /**
- * Shared post-commit side-effect helper.
+ * Two-queue side-effect machinery for request handlers.
  *
- * WS sends and `on_audit_event` SSE broadcasts must never fire mid-transaction —
- * a rollback would leak state that never existed. Anything pushed onto
- * `pending_effects` runs after the response is sent (see the request-context
- * middleware), so this helper is the canonical home for post-commit fan-out.
+ * Handlers register fire-and-forget work in one of two queues, distinguished
+ * by their timing contract:
  *
- * Satisfied by both `RouteContext` (HTTP routes) and `ActionContext` (RPC
- * actions) — they share `{log, pending_effects}` by convention, so this
- * module stays in `http/` (both depend on it).
+ * - `pending_effects: Array<Promise<void>>` — eager. Producers push pool
+ *   writes that are already in flight (audit emits, session-touch UPDATE,
+ *   api-token usage tracking). The pool write is rollback-resilient by
+ *   virtue of running outside the request transaction; pushing the
+ *   in-flight handle lets test mode (`await_pending_effects: true`) await
+ *   it.
+ * - `post_commit_effects: Array<() => void | Promise<void>>` — deferred.
+ *   Producers go through `emit_after_commit(ctx, fn)`; the flush
+ *   middleware is the only site that ever invokes the thunk, and it does
+ *   so after the request handler (and its wrapping `db.transaction`)
+ *   returns. Used for WS sends and any work that must observe a committed
+ *   transaction.
+ *
+ * The split exists because the two shapes encode different contracts:
+ * eager pushers are saying "wait for this work that's already started";
+ * thunk pushers are saying "run this after the handler returns." Burying
+ * both behind one `Array<PendingEffect>` made `c.var.pending_effects.push(x)`
+ * ambiguous at the call site. With separate queues, the field name is
+ * the contract.
+ *
+ * Both `RouteContext` (HTTP routes) and `ActionContext` (RPC + WS
+ * actions) carry both queues by convention, so this module stays in
+ * `http/` (every transport depends on it).
  *
  * @module
  */
 /**
  * Defer a side effect until after the handler's transaction commits.
  *
- * Exceptions thrown by `fn` are caught and logged via `ctx.log.error`, so one
- * failed send cannot corrupt the already-committed response or starve other
- * queued effects in the same tick.
+ * Pushes a raw thunk onto `ctx.post_commit_effects` — the flush
+ * middleware (in `server/app_server.ts` and the per-message WS dispatcher)
+ * is the only site that ever invokes `fn`. This is load-bearing: a
+ * previous implementation queued `Promise.resolve().then(fn)`, which
+ * JavaScript's microtask scheduler drains before the wrapping
+ * `await db.query('COMMIT')` resumes — `fn` fired mid-transaction and a
+ * rollback would leak a notification for state that never landed.
  *
- * @param ctx - context carrying `log` and the `pending_effects` queue
- * @param fn - synchronous side effect to run after commit
- * @mutates `ctx.pending_effects` - appends a never-rejecting promise wrapping `fn`
+ * The thunk shape closes that gap by deferring the work to flush time.
+ * The flush owns the per-thunk `try/catch` + `log.error` so any
+ * directly-pushed thunk (tests included) cannot escape the safety net.
+ *
+ * @param ctx - context carrying `log` and the `post_commit_effects` queue
+ * @param fn - side effect to run after commit; may return `void` or `Promise<void>`
+ * @mutates `ctx.post_commit_effects` - appends `fn` verbatim
  */
 export const emit_after_commit = (ctx, fn) => {
-    ctx.pending_effects.push(Promise.resolve().then(() => {
+    ctx.post_commit_effects.push(fn);
+};
+/**
+ * Drain an eager `pending_effects` queue: `Promise.allSettled` the
+ * in-flight handles, route every rejection through `log.error`, and
+ * fan out to `on_rejection` when supplied (production wires this to
+ * `on_effect_error` for monitoring).
+ *
+ * Returned promise resolves once every effect has settled. Never
+ * rejects. No-op when `effects` is empty (common on read-only
+ * requests).
+ *
+ * Symmetric with `flush_post_commit_effects` for the deferred queue.
+ */
+export const flush_pending_effects = async (effects, log, on_rejection) => {
+    if (effects.length === 0)
+        return;
+    const results = await Promise.allSettled(effects);
+    for (const result of results) {
+        if (result.status === 'rejected') {
+            log.error('pending effect rejected:', result.reason);
+            on_rejection?.(result.reason);
+        }
+    }
+};
+/**
+ * Drain a `post_commit_effects` queue: invoke each thunk under
+ * `try/catch`, collect any returned promises, and `Promise.allSettled`
+ * them. Synchronous throws and async rejections are routed through
+ * `log.error` so one failing effect cannot starve siblings.
+ *
+ * Returned promise resolves once every thunk has finished. Never
+ * rejects.
+ */
+export const flush_post_commit_effects = async (effects, log) => {
+    const promises = [];
+    for (const fn of effects) {
         try {
-            fn();
+            const result = fn();
+            if (result instanceof Promise) {
+                promises.push(result.catch((err) => {
+                    log.error('post-commit side effect failed:', err);
+                }));
+            }
         }
         catch (err) {
-            ctx.log.error('post-commit side effect failed:', err);
+            log.error('post-commit side effect failed:', err);
         }
-    }));
+    }
+    if (promises.length)
+        await Promise.allSettled(promises);
 };