@fuzdev/fuz_app 0.62.0 → 0.64.0

package/dist/testing/surface_invariants.js

@@ -19,6 +19,7 @@ import './assert_dev_env.js';
 import { assert } from 'vitest';
 import { middleware_applies } from '../http/schema_helpers.js';
 import { filter_protected_routes, filter_role_routes, filter_keeper_routes, filter_routes_with_input, filter_routes_with_params, filter_routes_with_query, filter_public_routes, format_route_key, } from '../http/surface_query.js';
+import { PROTOCOL_ACTION_METHODS } from '../actions/action_codegen.js';
 // --- Structural invariants ---
 /**
  * Every protected route has 401 in `error_schemas`.
@@ -374,6 +375,83 @@ export const audit_error_schema_tightness = (surface) => {
     }
     return entries;
 };
+// --- RPC / WS structural invariants ---
+/**
+ * Every RPC method on every endpoint has a non-empty `description`.
+ *
+ * Parallel of `assert_descriptions_present` over `surface.rpc_endpoints`.
+ * Empty descriptions on RPC methods leak through `library.json` codegen and
+ * consumer-facing docs without the route-level check catching them.
+ */
+export const assert_rpc_method_descriptions_present = (surface) => {
+    for (const ep of surface.rpc_endpoints) {
+        for (const method of ep.methods) {
+            assert.ok(method.description.length > 0, `RPC method '${method.name}' on endpoint '${ep.path}' has empty description`);
+        }
+    }
+};
+/**
+ * Every WS method on every endpoint has a non-empty `description`.
+ *
+ * Parallel of `assert_descriptions_present` over `surface.ws_endpoints`.
+ * Same rationale as `assert_rpc_method_descriptions_present` — codegen +
+ * surface explorer consume the description, blank values surface as `''`.
+ */
+export const assert_ws_method_descriptions_present = (surface) => {
+    for (const ep of surface.ws_endpoints) {
+        for (const method of ep.methods) {
+            assert.ok(method.description.length > 0, `WS method '${method.name}' on endpoint '${ep.path}' has empty description`);
+        }
+    }
+};
+/**
+ * Every WS endpoint's `methods` includes every protocol action method
+ * (`heartbeat`, `cancel`).
+ *
+ * Consumers register WS endpoints by spreading `protocol_actions` from
+ * `actions/protocol.ts` before their own actions:
+ *
+ * ```ts
+ * ws_endpoints: [{path: '/api/ws', actions: [...protocol_actions, ...consumer_actions], ...}]
+ * ```
+ *
+ * Forgetting the spread compiles cleanly but breaks at runtime: client-side
+ * heartbeats and `cancel` notifications get `method_not_found` from the
+ * dispatcher, so disconnect detection silently regresses and per-request
+ * cancel never aborts the matching handler. Catch the mistake at the
+ * surface layer rather than at runtime.
+ */
+export const assert_ws_endpoints_include_protocol_actions = (surface) => {
+    for (const ep of surface.ws_endpoints) {
+        const method_names = new Set(ep.methods.map((m) => m.name));
+        for (const expected of PROTOCOL_ACTION_METHODS) {
+            assert.ok(method_names.has(expected), `WS endpoint '${ep.path}' is missing protocol action method '${expected}' — ` +
+                `spread \`protocol_actions\` from 'actions/protocol.js' into \`actions\``);
+        }
+    }
+};
+/**
+ * WS methods follow the kind ⇔ auth biconditional emitted by surface
+ * generation: `kind === 'remote_notification' ⟺ auth === null`.
+ *
+ * `generate_app_surface` produces this shape directly from the action
+ * spec union (notifications carry `auth: null` per `ActionSpecUnion`;
+ * `request_response` carries a `RouteAuth`). The assertion guards against
+ * drift if a future surface emitter, transform, or test fixture violates
+ * it — and gives consumers a clear failure message when a hand-built
+ * surface mocks the shape incorrectly.
+ */
+export const assert_ws_notifications_have_null_auth = (surface) => {
+    for (const ep of surface.ws_endpoints) {
+        for (const method of ep.methods) {
+            const is_notification = method.kind === 'remote_notification';
+            const has_null_auth = method.auth === null;
+            assert.ok(is_notification === has_null_auth, `WS method '${method.name}' on endpoint '${ep.path}' violates kind ⇔ auth: ` +
+                `kind='${method.kind}', auth=${has_null_auth ? 'null' : 'non-null'} ` +
+                `(notifications must have auth: null; request_response must have a RouteAuth)`);
+        }
+    }
+};
 /** Default patterns for sensitive REST routes that should be rate-limited. */
 const DEFAULT_SENSITIVE_PATTERNS = [
     /\/login$/,
@@ -424,7 +502,9 @@ export const assert_no_unexpected_public_mutations = (surface, allowlist = []) =
  *
  * Note: RPC endpoints (`create_rpc_endpoint`) use `input: z.null()` on their
  * route specs — the dispatcher handles body/query parsing internally. Real input
- * schemas live in `rpc_endpoints` surface, not on routes.
+ * schemas live in `rpc_endpoints` surface, not on routes; see
+ * `assert_rpc_ws_surface_invariants` for the parallel checks over RPC/WS
+ * method shapes.
  */
 export const assert_mutation_routes_use_post = (surface) => {
     const input_routes = filter_routes_with_input(surface);
@@ -546,6 +626,28 @@ export const assert_surface_invariants = (surface) => {
     assert_error_code_status_consistency(surface);
     assert_404_schemas_use_specific_errors(surface);
 };
+/**
+ * Run all RPC / WS structural invariants. Options-free — applies
+ * universally to the `surface.rpc_endpoints` and `surface.ws_endpoints`
+ * slots produced by `generate_app_surface`.
+ *
+ * Parallel of `assert_surface_invariants` for the non-REST surfaces.
+ * Within-endpoint duplicate method names and the auth-shape biconditional
+ * are already enforced at startup by `compile_action_registry` (see
+ * `actions/CLAUDE.md` §Registry compile) — these assertions cover only
+ * the contract-surface concerns that a runtime registration check
+ * cannot: empty descriptions, missing protocol-action spread on WS
+ * endpoints, and kind ⇔ auth drift on WS methods.
+ *
+ * @throws AssertionError on the first invariant violation; the message
+ *   names the offending endpoint, method, and field.
+ */
+export const assert_rpc_ws_surface_invariants = (surface) => {
+    assert_rpc_method_descriptions_present(surface);
+    assert_ws_method_descriptions_present(surface);
+    assert_ws_endpoints_include_protocol_actions(surface);
+    assert_ws_notifications_have_null_auth(surface);
+};
 /**
  * Run security policy invariants. Configurable with sensible defaults.
  *

package/dist/ui/CLAUDE.md

@@ -5,14 +5,16 @@ utilities. Cookie-based SPA auth; prerendered static HTML served by Hono
 (no SvelteKit SSR for sessions). State classes hold one or more `AsyncSlot`s
 via composition (one per distinct async operation — e.g. `list` + `create` +
 `revoke`); per-row write ops use `KeyedAsyncSlot<K, T = void, E = string>`
-(supersedes the old `AsyncSlot` + `SvelteSet<id>` pair) so concurrent rows
-don't abort each other and failures surface per-row via `slot.error(key)`.
-Payload lives as `$state.raw` fields on the class. Shared dependencies flow
-through Svelte context, never through props — RPC adapters in particular
-are provisioned once at the admin shell and read by every `Admin*.svelte`.
+so concurrent rows don't abort each other and failures surface per-row via
+`slot.error(key)`. Payload lives as `$state.raw` fields on the class.
+Shared dependencies flow through Svelte context, never through props —
+RPC adapters are provisioned once at the admin shell and read by every
+`Admin*.svelte`.
 
-See ../../docs/usage.md for end-to-end wiring examples (sections "Role grant
-offer UI" and "Admin UI"). This file is a reference, not a tutorial.
+For Svelte 5 patterns (runes, inline `$props`, contexts, snippets,
+attachments), see Skill(fuz-stack) svelte-patterns. See ../../docs/usage.md
+for end-to-end wiring examples ("Role grant offer UI", "Admin UI"). This
+file is a reference, not a tutorial.
 
 ## Key patterns
 
@@ -67,15 +69,8 @@ it. Six methods land on the reducer: `role_grant_offer_received` /
 `_retracted` / `_accepted` / `_declined` / `_supersede` all merge a
 `{offer}` payload; `role_grant_revoke` is ignored at this layer (role_grant
 lifecycle lives in auth/role_grants state). The six notification specs and
-their payload shapes are defined in `../auth/role_grant_offer_notifications.ts`
-(see `../auth/CLAUDE.md` §WS notifications).
-
-### Svelte 5 inline `$props` shape
-
-Always `const {...}: {...} = $props()` — never `interface Props`.
-Destructure defaults in the binding list; put the type literal inline.
-This matches the user-memory Svelte props rule and the existing file
-conventions.
+their payload shapes are defined in `auth/role_grant_offer_notifications.ts`
+(see `auth/CLAUDE.md` §WS notifications).
 
 ### Context over props for shared deps
 
@@ -184,8 +179,8 @@ destructive actions.
   reason codes with friendly copy: `ERROR_ROLE_GRANT_OFFER_SELF_TARGET`,
   `ERROR_ROLE_GRANT_OFFER_ROLE_NOT_GRANTABLE`, `ERROR_ROLE_GRANT_OFFER_NOT_AUTHORIZED`,
   `ERROR_ROLE_GRANT_OFFER_ACTOR_ACCOUNT_MISMATCH`, `ERROR_ROLE_GRANT_OFFER_ACTOR_MISMATCH`
-  — imported from `../auth/role_grant_offer_action_specs.js` (see
-  `../auth/CLAUDE.md` for `role_grant_offer_action_specs.ts` +
+  — imported from `auth/role_grant_offer_action_specs.js` (see
+  `auth/CLAUDE.md` for `role_grant_offer_action_specs.ts` +
   `role_grant_offer_actions.ts`).
 - `RoleGrantOfferHistory.svelte` — both-directions history (recipient +
   grantor, including terminal). Props: `current_actor_id: string | null`

package/dist/ui/SurfaceExplorer.svelte

@@ -17,6 +17,7 @@
 		is_plain_authenticated_auth,
 		is_public_auth,
 		is_role_auth,
+		type RouteAuth,
 	} from '../http/auth_shape.js';
 
 	const {surface}: {surface: AppSurface} = $props();
@@ -28,6 +29,13 @@
 
 	const summary = $derived(surface_auth_summary(surface));
 
+	const rpc_method_count = $derived(
+		surface.rpc_endpoints.reduce((sum, ep) => sum + ep.methods.length, 0),
+	);
+	const ws_method_count = $derived(
+		surface.ws_endpoints.reduce((sum, ep) => sum + ep.methods.length, 0),
+	);
+
 	const auth_matches_filter = (
 		auth: AppSurfaceRoute['auth'],
 		filter: (typeof auth_types)[number],
@@ -51,6 +59,8 @@
 	);
 
 	let expanded_event: string | null = $state.raw(null);
+	let expanded_rpc_method: string | null = $state.raw(null);
+	let expanded_ws_method: string | null = $state.raw(null);
 
 	const toggle_route = (key: string): void => {
 		expanded_route = expanded_route === key ? null : key;
@@ -60,7 +70,15 @@
 		expanded_event = expanded_event === method ? null : method;
 	};
 
-	const format_auth = (auth: AppSurfaceRoute['auth']): string => {
+	const toggle_rpc_method = (key: string): void => {
+		expanded_rpc_method = expanded_rpc_method === key ? null : key;
+	};
+
+	const toggle_ws_method = (key: string): void => {
+		expanded_ws_method = expanded_ws_method === key ? null : key;
+	};
+
+	const format_auth = (auth: RouteAuth): string => {
 		if (is_public_auth(auth)) return 'none';
 		if (is_keeper_auth(auth)) return 'keeper';
 		if (is_role_auth(auth)) return `role:${auth.roles!.join('|')}`;
@@ -68,7 +86,7 @@
 		return 'other';
 	};
 
-	const auth_chip_class = (auth: AppSurfaceRoute['auth']): string => {
+	const auth_chip_class = (auth: RouteAuth): string => {
 		if (is_public_auth(auth)) return 'chip color_b';
 		if (is_keeper_auth(auth)) return 'chip color_c';
 		if (is_role_auth(auth)) return 'chip color_d';
@@ -89,6 +107,8 @@
 		{#if role_count > 0}<span class="chip color_d">{role_count} role</span>{/if}
 		{#if summary.keeper > 0}<span class="chip color_c">{summary.keeper} keeper</span>{/if}
 		<span class="chip">{surface.middleware.length} middleware</span>
+		{#if rpc_method_count > 0}<span class="chip">{rpc_method_count} rpc methods</span>{/if}
+		{#if ws_method_count > 0}<span class="chip">{ws_method_count} ws methods</span>{/if}
 		{#if surface.env.length}<span class="chip">{surface.env.length} env</span>{/if}
 		{#if surface.events.length}<span class="chip">{surface.events.length} events</span>{/if}
 		{#if surface.diagnostics.length}{@const warnings = surface.diagnostics.filter(
@@ -283,6 +303,145 @@
 		</div>
 	{/if}
 
+	{#if surface.rpc_endpoints.length}
+		<h3>rpc endpoints</h3>
+		{#each surface.rpc_endpoints as endpoint (endpoint.path)}
+			<div class="row" style:gap="var(--space_sm)" style:align-items="center">
+				<code>{endpoint.path}</code>
+				<span class="chip">{endpoint.methods.length} methods</span>
+			</div>
+			{#if endpoint.methods.length === 0}
+				<p class="text_50">no methods</p>
+			{:else}
+				<div style:overflow-x="auto">
+					<table>
+						<thead>
+							<tr>
+								<th>method</th>
+								<th>auth</th>
+								<th>side effects</th>
+								<th>rate limit</th>
+								<th>description</th>
+							</tr>
+						</thead>
+						<tbody>
+							{#each endpoint.methods as method (method.name)}
+								{@const key = `${endpoint.path}|${method.name}`}
+								<tr onclick={() => toggle_rpc_method(key)} style:cursor="pointer">
+									<td><code>{method.name}</code></td>
+									<td>
+										<span class={auth_chip_class(method.auth)}>{format_auth(method.auth)}</span>
+									</td>
+									<td>{method.side_effects ? 'yes' : 'no'}</td>
+									<td class="text_50">{method.rate_limit_key ?? '-'}</td>
+									<td class="text_50">{method.description}</td>
+								</tr>
+								{#if expanded_rpc_method === key}
+									<tr transition:slide>
+										<td colspan="5">
+											<div class="column" style:gap="var(--space_sm)">
+												<div>
+													<strong>input</strong>
+													{#if method.input_schema}
+														<pre>{JSON.stringify(method.input_schema, null, 2)}</pre>
+													{:else}
+														<span class="text_50">none (z.void)</span>
+													{/if}
+												</div>
+												<div>
+													<strong>output</strong>
+													<pre>{JSON.stringify(method.output_schema, null, 2)}</pre>
+												</div>
+											</div>
+										</td>
+									</tr>
+								{/if}
+							{/each}
+						</tbody>
+					</table>
+				</div>
+			{/if}
+		{/each}
+	{/if}
+
+	{#if surface.ws_endpoints.length}
+		<h3>websocket endpoints</h3>
+		{#each surface.ws_endpoints as endpoint (endpoint.path)}
+			<div
+				class="row"
+				style:gap="var(--space_sm)"
+				style:align-items="center"
+				style:flex-wrap="wrap"
+			>
+				<code>{endpoint.path}</code>
+				<span class="chip">{endpoint.methods.length} methods</span>
+				{#each endpoint.required_roles as role (role)}
+					<span class="chip color_d">role:{role}</span>
+				{/each}
+				{#each endpoint.allowed_origins as origin (origin)}
+					<span class="chip color_b"><code>{origin}</code></span>
+				{/each}
+			</div>
+			{#if endpoint.methods.length === 0}
+				<p class="text_50">no methods</p>
+			{:else}
+				<div style:overflow-x="auto">
+					<table>
+						<thead>
+							<tr>
+								<th>method</th>
+								<th>kind</th>
+								<th>auth</th>
+								<th>side effects</th>
+								<th>rate limit</th>
+								<th>description</th>
+							</tr>
+						</thead>
+						<tbody>
+							{#each endpoint.methods as method (method.name)}
+								{@const key = `${endpoint.path}|${method.name}`}
+								<tr onclick={() => toggle_ws_method(key)} style:cursor="pointer">
+									<td><code>{method.name}</code></td>
+									<td><span class="chip">{method.kind}</span></td>
+									<td>
+										{#if method.auth}
+											<span class={auth_chip_class(method.auth)}>{format_auth(method.auth)}</span>
+										{:else}
+											<span class="text_50">—</span>
+										{/if}
+									</td>
+									<td>{method.side_effects ? 'yes' : 'no'}</td>
+									<td class="text_50">{method.rate_limit_key ?? '-'}</td>
+									<td class="text_50">{method.description}</td>
+								</tr>
+								{#if expanded_ws_method === key}
+									<tr transition:slide>
+										<td colspan="6">
+											<div class="column" style:gap="var(--space_sm)">
+												<div>
+													<strong>input</strong>
+													{#if method.input_schema}
+														<pre>{JSON.stringify(method.input_schema, null, 2)}</pre>
+													{:else}
+														<span class="text_50">none (z.void)</span>
+													{/if}
+												</div>
+												<div>
+													<strong>output</strong>
+													<pre>{JSON.stringify(method.output_schema, null, 2)}</pre>
+												</div>
+											</div>
+										</td>
+									</tr>
+								{/if}
+							{/each}
+						</tbody>
+					</table>
+				</div>
+			{/if}
+		{/each}
+	{/if}
+
 	{#if surface.diagnostics.length}
 		<h3>diagnostics</h3>
 		<div style:overflow-x="auto">

package/dist/ui/SurfaceExplorer.svelte.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"SurfaceExplorer.svelte.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/ui/SurfaceExplorer.svelte"],"names":[],"mappings":"AAaA,OAAO,KAAK,EAAC,UAAU,EAAwC,MAAM,oBAAoB,CAAC;AASzF,KAAK,gBAAgB,GAAI;IAAC,OAAO,EAAE,UAAU,CAAA;CAAC,CAAC;AAuShD,QAAA,MAAM,eAAe,sDAAwC,CAAC;AAC9D,KAAK,eAAe,GAAG,UAAU,CAAC,OAAO,eAAe,CAAC,CAAC;AAC1D,eAAe,eAAe,CAAC"}
+{"version":3,"file":"SurfaceExplorer.svelte.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/ui/SurfaceExplorer.svelte"],"names":[],"mappings":"AAaA,OAAO,KAAK,EAAC,UAAU,EAAwC,MAAM,oBAAoB,CAAC;AAUzF,KAAK,gBAAgB,GAAI;IAAC,OAAO,EAAE,UAAU,CAAA;CAAC,CAAC;AAgchD,QAAA,MAAM,eAAe,sDAAwC,CAAC;AAC9D,KAAK,eAAe,GAAG,UAAU,CAAC,OAAO,eAAe,CAAC,CAAC;AAC1D,eAAe,eAAe,CAAC"}

package/dist/ui/keyed_async_slot.svelte.d.ts

@@ -56,7 +56,7 @@ export type KeyedAsyncSlotOptions<T, E = string> = Omit<AsyncSlotOptions<T, E>,
  *
  * @typeParam K - The key type. Map identity is SameValueZero — branded
  *   strings (`Uuid`) work directly. For composite keys, stringify at
- *   the call site (e.g. `` `${account_id}:${role}` ``).
+ *   the call site (e.g. "`${account_id}:${role}`").
  * @typeParam T - The success payload type. Use `void` for write-only
  *   actions whose response isn't worth retaining.
  * @typeParam E - The shape of per-key `error(key)`. Defaults to

package/dist/ui/keyed_async_slot.svelte.js

@@ -48,7 +48,7 @@ import { AsyncSlot } from './async_slot.svelte.js';
  *
  * @typeParam K - The key type. Map identity is SameValueZero — branded
  *   strings (`Uuid`) work directly. For composite keys, stringify at
- *   the call site (e.g. `` `${account_id}:${role}` ``).
+ *   the call site (e.g. "`${account_id}:${role}`").
  * @typeParam T - The success payload type. Use `void` for write-only
  *   actions whose response isn't worth retaining.
  * @typeParam E - The shape of per-key `error(key)`. Defaults to

package/package.json

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