ruact 0.0.3 → 0.0.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ce264ae503bd6e5c3239399e6bc39491724eec59b8f166a7e69923e40e2e0a10
-  data.tar.gz: 6ae79fc064960c97e8345a9030778dc61489c1179ea70123aad28a0de0806bf3
+  metadata.gz: 2f8e264e2e404e5257d0fe7457cef545f4104288dc16db01e1c8e5762d361f99
+  data.tar.gz: 4a2ed748edb281b7d8bb0c20ce5e404db6ce7872f82c8db1545349ab709677d3
 SHA512:
-  metadata.gz: 660f2dbc8b3783eef80a3f935aa39a4afa34f02190578ada873fdd3074fe4182e77e9d5c486cd220edc68d89c8ff04581ab412eacd0bf3115c481841a4df9049
-  data.tar.gz: b4ddd9632c82d7a7d10e4113730bf4fedbd3b8b0007f917c4dc49fb880362e7b0b6a1bb7c2f953355d0926c39a893a7c377a693d0f8512330cfe226315e682cf
+  metadata.gz: 36eb5942d50d3761874bd912a9cfae5ad3538500b8e08a79b196310db8db66bc86fa8a6fc78262c8a2e73ba659feaa1dd821c344fe89ecbddf247c2e05924153
+  data.tar.gz: f8902075c57bb47e42f404d43a864829719bddc4f497371097f0c1576ef1565312b45e628f1d7a3e9a3811db497e1aa8325f8e935da4e7b4941ae2bdc468d72e

data/CHANGELOG.md

@@ -9,6 +9,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 
+- **`useQuery` request de-duplication** ([Story 9.6](../_bmad-output/implementation-artifacts/9-6-automatic-request-deduplication-for-usequery.md)). Identical concurrent `useQuery` calls now share ONE network request: when three components mount `useQuery(categories)` with the same params while a request is in flight, exactly one `GET /q/categories` is issued — all of them receive the same resolved `data`, and an error propagates to every sharer. The dedup key derives from the **query reference identity + the serialized params**, with order-independent param serialization (`{ a: 1, b: 2 }` and `{ b: 2, a: 1 }` share a request; different params do not). Scope is **in-flight only** — there is no TTL cache and no stale-while-revalidate: once a request settles its shared entry is dropped, so a fresh mount refetches. Runtime-only change (`useQuery` hook); the `_makeQuery` GET accessor, codegen, and the Ruby query dispatch are unchanged. Runtime package version `0.3.0` → `0.4.0`; coverage in `usequery.test.mjs`.
+
+- **Queries in codegen + `useQuery` hook + FR88 kwargs sanitization** ([Story 9.5](../_bmad-output/implementation-artifacts/9-5-queries-in-codegen-usequery-re-pointed-kwargs-params.md)). The read-side of the route-driven redesign is complete: `import { categories, useQuery } from "@/.ruact/server-functions"` and `useQuery(categories)` / `useQuery(searchUsers, { q: input })` now work against `Ruact::Query` classes — same mental model as mutations, zero new concepts. **Codegen.** A new `Ruact::ServerFunctions::QuerySource` derives v2 query entries from the **drawn route table** (the GET routes the `ruact_queries` macro mounted under the generated query-dispatch namespace) — route-truth-consistent with dispatch, so only classes actually mounted in `routes.rb` are exposed (no over-exposure, and no `app/queries` force-load needed). Query entries join the **same merged JS namespace** as mutations; collisions fail loudly at boot naming both origins (route×query is caught at the codegen combine point; `query×query` by the source; the `ruact_function_name` rename macro on the mutation controller — or renaming the query method — is the escape hatch). The emitted module binds each query to `_makeQuery({ path, kind: "query" })` with a per-query TS signature (`() => Promise<unknown>` when the method declares no kwargs, `(params: Record<string, unknown>) => Promise<unknown>` when it does) and re-exports `useQuery` from the runtime (only when ≥1 query exists, so action-only/empty v2 modules stay byte-identical to Story 9.3). The Ruby↔JS byte-equality parity test covers query entries. **Runtime.** New `useQuery(reference, params?)` React hook → `{ data, loading, error }` (loading until first resolution; structured `RuactActionError` into `error`; superseded in-flight responses dropped; refetch on value-changed params); new `_makeQuery` GET helper issues `GET /q/<jsId>` with params in the query string — **no body, no CSRF** (reads are CSRF-free; the stale `POST /__ruact/fn/:id` query mechanism is voided). The runtime gains `react` as a **peerDependency** (its first React import; the mutation path stays React-free); package version `0.2.0` → `0.3.0`. **FR88 sanitization.** `query_dispatch.rb#__ruact_query_kwargs` now enforces the authoritative kwargs allowlist on `request.query_parameters`: only `string | number | boolean | null` are accepted — arrays (`?q[]=`) and objects (`?q[k]=`) are **rejected with a descriptive error naming the key and the allowlist**; a **missing required kwarg → 400** naming it; an **unknown param → 400** (rejected, not silently dropped). All raise the new `Ruact::BadRequestError` → HTTP 400 via the Story 8.4 structured payload. 9.5 writes ONLY the parallel `.next` codegen target (ownership flip is 9.8); `useQuery` request de-duplication is 9.6; the v1 substrate is untouched (demolition is 9.9). New files `lib/ruact/server_functions/query_source.rb`; new specs `query_source_spec.rb`, `:story_9_5` cases in `codegen_spec.rb` / `railtie_integration_spec.rb` / `query_request_spec.rb`; new runtime vitest `usequery.test.mjs` + query parity cases. ADR addendum (2026-06-10).
+
 - **`Ruact::Query` base class + `ruact_queries` route macro** ([Story 9.4](../_bmad-output/implementation-artifacts/9-4-ruact-query-base-class-and-ruact-queries-route-macro.md)). Server QUERIES are now plain classes under `app/queries/` (`class CatalogQuery < ApplicationQuery`, `ApplicationQuery < Ruact::Query`) — each public method defined directly on the subclass is one query — mounted with one line in `routes.rb`: `ruact_queries CatalogQuery` draws one **named GET route per public method** (`def search_users` → `GET /q/searchUsers`, named `ruact_query_searchUsers`), all visible in `rails routes` (no hidden endpoint; the route table stays the single source of truth). The prefix is configurable via the new `Ruact.config.query_route_prefix` (default `"/q"`). Dispatch goes through an internal gem controller — one generated subclass per query class — inheriting the new `Ruact.config.query_parent_controller` (default `"ApplicationController"`, constantized lazily at route-draw), so the host's REAL callback chain (`authenticate_user!`, tenant scoping, Pundit) runs **before** the query class is instantiated. The query instance is fresh per request and receives its context via the constructor: `current_user` / `params` / `request` / `session` delegate to the dispatching controller (so `current_user` IS the host's own method), and `CatalogQuery.new(fake_context).categories` is unit-testable with no Rails boot. Per-query callback opt-out via the new `ruact_skip_before_action` class macro (mirrors Rails' `skip_before_action` signature incl. `only:`/`except:`/`raise: false`; scoped to the declaring query class by construction). Queries are GET — no CSRF; the method's return value is serialized through the same `ruact_props` / `Ruact::Serializable` / `strict_serialization` policy as Bucket 2 (new `BucketTwoPayload.serialize_value` extraction; `nil` → JSON `null` with 200), and a query raise renders the salvaged structured-error payload with the same 422/403/413/500 mapping (the GET gate is overridden for query dispatch — `Ruact::ConfigurationError` still re-raises loudly). Keyword arguments are passed best-effort from GET query params by name (the strict FR88 sanitization wire contract ships with `useQuery` in Story 9.5; codegen of query entries is also 9.5). New files `lib/ruact/query.rb`, `lib/ruact/routing.rb`, `lib/ruact/server_functions/query_dispatch.rb`, `lib/ruact/server_functions/query_context.rb`. New specs `query_spec.rb`, `query_context_spec.rb`, `query_request_spec.rb` + extensions to `configuration_spec.rb` / `bucket_two_payload_spec.rb`, all tagged `:story_9_4`.
 
 - **Route-driven codegen for mutations + runtime re-target** ([Story 9.3](../_bmad-output/implementation-artifacts/9-3-route-driven-codegen-for-mutations-and-runtime-re-target.md)). The generated server-functions module is now derived from the **Rails route table** instead of the v1 registries: every non-GET routed action (POST/PUT/PATCH/DELETE) on a controller that `include Ruact::Server` becomes a callable server function — `resources :posts` is the only declaration, no `routes.rb` additions, no synthetic endpoint. New `Ruact::ServerFunctions::RouteSource` collects entries from the route set; the locked naming derivation table (recorded in the ADR) covers the RESTful writes (`posts#create` → `createPost`), custom member routes (`posts#publish` → `publishPost`), custom collection routes (`posts#publish_all` → `publishAllPosts`), singular resources (`resource :session` → `createSession`), and namespaced controllers with a **prefix** scheme (`admin/posts#create` → `createAdminPost`) so the merged JS namespace is collision-free by construction. Collisions fail loudly at boot naming both origins; the new `ruact_function_name :action, as: "jsId"` macro on `Ruact::Server` is the per-action rename escape hatch. The build always logs `[ruact] codegen: exposing …` (transparency over silence). The runtime gains `_makeServerFunction({ method, path, segments })` — it targets the real route + verb (e.g. `POST /posts`, `PUT /posts/:id`), interpolating `:id`-style path segments by name from the single FormData/object argument, and follows a Bucket-2 `{ "$redirect": "<path>" }` response client-side (via `globalThis.__ruact_navigate`, `window.location.assign` fallback) — the client half of the contract Story 9.2 emitted. The salvaged 8.1/8.2 behaviors (FormData branching, CSRF meta injection, text-first parsing, `RuactActionError`, `redirect: "error"`, the intersection action signature, `revalidate()`) are preserved via a shared `ruactInvoke` core; the v1 `_makeRef` accessor is byte-behavior-identical. The v2 codegen writes to a **parallel** target (`server-functions.next.{json,ts}`) for parity tests + inspection only — never imported by application code — so the v1 `server-functions.ts` is untouched (the per-app cutover to route-driven codegen is Story 9.8). The Ruby↔JS codegen byte-equality parity test is retained and extended for v2. New specs: `route_source_spec.rb`, `server_function_name_spec.rb`, v2 cases in `codegen_spec.rb` / `snapshot_spec.rb` / `railtie_integration_spec.rb` (tagged `:story_9_3`); +11 runtime vitest characterization tests; +5 codegen parity vitest cases.

data/docs/internal/decisions/server-functions-api.md

@@ -1678,3 +1678,102 @@ model never reads or populates it.
 **Deferred (noted, not ACs here):** install-generator scaffolding for
 `app/queries/application_query.rb`; codegen + `useQuery` + FR88 kwargs (9.5);
 dedup (9.6); docs rewrite (9.7); playground migration (9.8).
+
+---
+
+## 2026-06-10 — Story 9.5 — Queries in codegen, `useQuery` re-pointed, kwargs sanitized
+
+Closes the read-side of the route-driven redesign: queries now appear in the
+v2 codegen module, `useQuery` issues a real `GET /q/<jsId>`, and the FR88
+kwargs contract is enforced server-side. Append-only addendum to the
+2026-06-02 (route-driven) and 2026-06-09 (Story 9.4) entries.
+
+1. **Query codegen source = the drawn route table (route-truth), not the set
+   of `Ruact::Query` subclasses (AC1).** `Ruact::ServerFunctions::QuerySource`
+   enumerates drawn GET routes whose controller path is under
+   `ruact/server_functions/query_dispatch/` (the generated dispatch
+   controllers from Story 9.4) and emits one v2 query entry each. This is the
+   sibling of `RouteSource` (mutations) and was chosen over enumerating
+   `Ruact::Query.subclasses` deliberately: a host exposes a query ONLY by
+   mounting it with `ruact_queries` in `routes.rb`, so the route table is the
+   single source of truth. Reading subclasses would over-expose query classes
+   that are defined but never mounted (and `useQuery` would 404 on their
+   non-existent routes). **Consequence:** the "force-load `app/queries/` at
+   `config.to_prepare`" gap flagged in the story is *moot* — mounting a class
+   in `routes.rb` already autoloads it, so no force-load was added (avoiding
+   the over-exposure a blind force-load-then-enumerate would cause). `QuerySource`
+   is pure: the route set + a `query_class_for` resolver are injected (the
+   railtie passes the real `__ruact_query_class` lookup; specs inject a lambda).
+
+2. **Entry shape carries `accepts_params` for the TS signature (AC1).** A query
+   entry is `{ js_identifier, kind: "query", http_method: "GET", path,
+   segments: [], accepts_params, controller, action }`. `accepts_params` is
+   true iff the query method declares any keyword argument
+   (`:key`/`:keyreq`/`:keyrest`) and drives the emitted signature:
+   `(params: Record<string, unknown>) => Promise<unknown>` when true,
+   `() => Promise<unknown>` when false. `NameBridge.to_js_identifier` is reused
+   verbatim (single source of truth for snake→camel), so the codegen jsId is
+   byte-identical to the route the `ruact_queries` macro drew.
+
+3. **Merged JS namespace + collision detection (AC1, Task 2).** Action entries
+   (`RouteSource`) and query entries (`QuerySource`) share ONE namespace.
+   `RouteSource` rejects action×action and `QuerySource` rejects query×query
+   intra-kind; `ServerFunctions.detect_merged_namespace_collisions!` (run at
+   the `write_v2_snapshot!` combine point) rejects route×query. All three name
+   BOTH origins (`posts#categories and CatalogQuery#categories`). **Escape
+   hatch:** the `ruact_function_name :<action>, as: "<id>"` rename macro on the
+   *mutation controller* (Story 9.3) resolves a route×query clash; a
+   query×query clash is resolved by renaming a query method. The query side has
+   no rename macro because `routing.rb#draw_query_routes` derives the jsId
+   purely from the method name via `NameBridge` (kept read-only this story) —
+   renaming the method is the single, consistent lever, and keeps the route the
+   macro draws and the codegen jsId in lockstep by construction.
+
+4. **`useQuery` issues `GET /q/<jsId>` — the stale `POST /__ruact/fn/:id`
+   mechanism is VOIDED (AC2).** The 2026-05-13 ADR clarification #5 ("hook reads
+   `$$id`, POSTs `/__ruact/fn/:id`") is dead: Story 9.4 mounts queries as real
+   named GET routes and the 2026-06-02 addendum restored HTTP GET semantics for
+   reads (CSRF-free). The codegen emits `export const <id> = _makeQuery({ path,
+   kind: "query" })`; `useQuery(reference, params?) → { data, loading, error }`
+   invokes that reference inside a `useEffect`, tracking state and dropping a
+   superseded in-flight response (params changed / unmounted). The reference is
+   also directly callable for imperative use. `useQuery` and `_makeQuery` are
+   re-exported from `@/.ruact/server-functions` by the codegen — `useQuery` only
+   when the snapshot has ≥1 query entry, which keeps action-only and empty v2
+   modules **byte-identical to Story 9.3** (minimal-churn import list:
+   `_makeServerFunction` and/or `_makeQuery` are imported only when used).
+
+5. **`useQuery` wire format = primitives in the query string; server validation
+   is authoritative (AC3, FR88).** The client serializes `params` into the GET
+   query string: `string`/`number`/`boolean` → `key=value`, `null` → `key=`
+   (empty), and arrays/objects throw a client-side `TypeError` for immediate
+   feedback. The SERVER is the authority: `query_dispatch.rb#__ruact_query_kwargs`
+   reads `request.query_parameters` (the raw client params — NOT `params`, which
+   carries Rails' `controller`/`action`/`format` defaults that must not count as
+   "unknown") and enforces, in order: (a) **allowlist** — a value Rack parsed as
+   an Array (`?q[]=`) or Hash (`?q[k]=`) is rejected (a scalar arrives as a
+   String, the only non-`nil` primitive on the wire); (b) **unknown param** — a
+   key matching no declared kwarg (and no `**rest`) is rejected, not dropped;
+   (c) **missing required** — a `keyreq` the client omitted. All three raise the
+   new `Ruact::BadRequestError` (`< Ruact::Error`) → **HTTP 400** via a new case
+   in `__ruact_status_for`, rendered through the same Story 8.4 structured
+   payload (`_ruact_server_action_error: true`, `error_class`, `message` naming
+   the offending key + allowlist). Values are delivered to the query method as
+   Strings (GET semantics, unchanged from 9.4's best-effort) — FR88 governs the
+   *shape* on the wire, not type coercion, which stays the method's concern.
+
+6. **React becomes a `peerDependency` of the runtime package.** `useQuery` is
+   the runtime's first React import (`useState`/`useEffect`). React is declared
+   as a `peerDependency` (`">=18"`) — every host already has it; the runtime
+   never bundles its own copy. The mutation path (`_makeRef` /
+   `_makeServerFunction`) stays React-free. Package version `0.2.0` → `0.3.0`.
+   The hook is covered by jsdom + `@testing-library/react` vitest
+   (`usequery.test.mjs`); those dev-only deps live in the runtime package and
+   run via its own `npm test` (the vite-plugin parity run globs only the
+   node-environment `index.test.mjs`).
+
+7. **Scope guards (unchanged from the story plan).** 9.5 writes ONLY the
+   parallel `.next` codegen target (the ownership flip to the real
+   `server-functions.ts` is 9.8). Request de-duplication for `useQuery` is 9.6
+   (the hook fetches once per mount; a `useSyncExternalStore` refactor can layer
+   dedup later). The v1 substrate is untouched (demolition is 9.9).

data/lib/ruact/errors.rb

@@ -63,6 +63,17 @@ module Ruact
     end
   end
 
+  # Story 9.5 (FR88) — raised by the query dispatch controller when a
+  # `useQuery` request's parameters violate the kwargs allowlist: a complex
+  # value (array / object) where only `string | number | boolean | null` is
+  # accepted, a missing required keyword, or an unknown parameter that matches
+  # no declared kwarg. Inherits from `Ruact::Error` so the Story 8.4
+  # `rescue_from StandardError` chain on the dispatch controller catches it
+  # cleanly; `__ruact_status_for` maps it to HTTP 400 (Bad Request). The
+  # message names the offending key and the allowlist so the React dev can
+  # fix the call site without reading the server source.
+  class BadRequestError < Error; end
+
   # Story 8.5 — raised by `EndpointController#__ruact_enforce_upload_limit!`
   # when an inbound multipart / urlencoded request's `Content-Length` exceeds
   # `Ruact.config.max_upload_bytes`. The exception inherits from

data/lib/ruact/server_functions/codegen.rb

@@ -62,12 +62,26 @@ module Ruact
         "& ((formData: FormData) => Promise<void>)"
       QUERY_SIGNATURE  = "() => Promise<unknown>"
 
+      # Story 9.5 — a query method that declares keyword arguments (FR88
+      # params) gets the param-accepting signature; one with no kwargs keeps
+      # the bare {QUERY_SIGNATURE}. Queries are read-only (never reachable via
+      # `<form action>`), so neither widens to the action intersection.
+      QUERY_PARAMS_SIGNATURE = "(params: Record<string, unknown>) => Promise<unknown>"
+
       # Story 8.2 — fixed re-export appended AFTER the per-function block.
       # Emitted in BOTH branches (empty + populated registry) so
       # `import { revalidate } from "@/.ruact/server-functions"` works on
       # day one of any host app. Ruby + JS codegens emit byte-identically.
       REVALIDATE_REEXPORT = "export { revalidate } from #{RUNTIME_IMPORT};\n".freeze
 
+      # Story 9.5 — the `useQuery` hook re-export, appended (after
+      # {REVALIDATE_REEXPORT}) ONLY when the v2 snapshot carries query entries.
+      # Gating on query presence keeps the action-only and empty v2 modules
+      # byte-identical to their Story 9.3 output (minimal churn); a host that
+      # has no queries cannot call `useQuery` on anything anyway. Ruby + JS
+      # codegens emit this byte-identically.
+      USEQUERY_REEXPORT = "export { useQuery } from #{RUNTIME_IMPORT};\n".freeze
+
       # JS identifier shape — same as `NameBridge::VALID_SYMBOL` but expressed
       # in JS-identifier terms (leading letter / underscore / `$`, then alnum
       # / underscore / `$`). The codegen validates every entry it consumes

data/lib/ruact/server_functions/codegen_v2.rb

@@ -20,23 +20,39 @@ module Ruact
       # LINE_TERMINATORS, VALID_JS_IDENTIFIER) are reused from {Codegen} via
       # lexical scope.
       module V2
-        # Verbs a v2 entry may carry (mirrors {RouteSource::MUTATION_VERBS}).
+        # Verbs a v2 ACTION entry may carry (mirrors {RouteSource::MUTATION_VERBS}).
         HTTP_METHODS = %w[POST PUT PATCH DELETE].to_set.freeze
 
+        # Story 9.5 — the verb a v2 QUERY entry may carry. Queries are reads,
+        # mounted by {Ruact::Routing#ruact_queries} as named GET routes; the
+        # 2026-06-02 ADR addendum voided the old `POST /__ruact/fn/:id` query
+        # mechanism, so a query entry is GET-only.
+        QUERY_HTTP_METHODS = %w[GET].to_set.freeze
+
         class << self
           # @param version [Integer, String]
           # @param generated_at [String]
-          # @param functions [Array<Hash>] route-derived entries.
+          # @param functions [Array<Hash>] route-derived entries (actions AND,
+          #   Story 9.5, queries).
           # @return [String] TS module bytes (single trailing newline).
           # @raise [Ruact::ConfigurationError] on any trust-boundary violation.
           def render(version, generated_at, functions)
             validate_functions!(functions)
 
+            has_query  = functions.any? { |entry| fetch(entry, "kind").to_s == "query" }
+            has_action = functions.any? { |entry| fetch(entry, "kind").to_s == "action" }
+
+            # Import only what is used. Keep `_makeServerFunction` in the empty
+            # case so the no-functions module stays byte-identical to Story 9.3.
+            imports = []
+            imports << "_makeServerFunction" if has_action || functions.empty?
+            imports << "_makeQuery" if has_query
+
             io = +""
             io << "// AUTO-GENERATED by vite-plugin-ruact (Story 9.3). DO NOT EDIT.\n"
             io << "// Source: Rails route table (version #{version})\n"
             io << "// Generated at: #{generated_at}\n"
-            io << "import { _makeServerFunction } from #{RUNTIME_IMPORT};\n"
+            io << "import { #{imports.join(', ')} } from #{RUNTIME_IMPORT};\n"
 
             if functions.empty?
               io << "\n// (no server functions exposed yet — add a non-GET route on a Ruact::Server controller)\n"
@@ -48,12 +64,15 @@ module Ruact
 
             io << "\n"
             io << REVALIDATE_REEXPORT
+            io << USEQUERY_REEXPORT if has_query
             io
           end
 
           private
 
           def render_export(entry)
+            return render_query_export(entry) if fetch(entry, "kind").to_s == "query"
+
             js_id = fetch(entry, "js_identifier")
             method = fetch(entry, "http_method")
             path = fetch(entry, "path")
@@ -66,6 +85,20 @@ module Ruact
             "export const #{js_id}: #{ACTION_SIGNATURE} =\n  _makeServerFunction(#{descriptor});\n"
           end
 
+          # Story 9.5 — a query export binds a `_makeQuery` accessor carrying
+          # its GET descriptor `{ path, kind: "query" }`. `useQuery(<id>, …)`
+          # consumes it (the SUPERSEDED `POST /__ruact/fn/:id` mechanism is
+          # gone — reads go to `GET /q/<jsId>`). The signature accepts params
+          # only when the query method declares kwargs (FR88).
+          def render_query_export(entry)
+            js_id = fetch(entry, "js_identifier")
+            path = fetch(entry, "path")
+            signature = fetch(entry, "accepts_params") ? QUERY_PARAMS_SIGNATURE : QUERY_SIGNATURE
+
+            descriptor = "{ path: #{JSON.dump(path)}, kind: \"query\" }"
+            "export const #{js_id}: #{signature} =\n  _makeQuery(#{descriptor});\n"
+          end
+
           def validate_functions!(functions)
             unless functions.is_a?(Array)
               raise Ruact::ConfigurationError,
@@ -84,8 +117,9 @@ module Ruact
 
             js_id = fetch(entry, "js_identifier")
             validate_identifier!(js_id, seen)
-            validate_kind!(js_id, fetch(entry, "kind").to_s)
-            validate_method!(js_id, fetch(entry, "http_method"))
+            kind = fetch(entry, "kind").to_s
+            validate_kind!(js_id, kind)
+            validate_method!(js_id, kind, fetch(entry, "http_method"))
             path = fetch(entry, "path")
             validate_path!(js_id, path)
             validate_segments!(js_id, path, fetch(entry, "segments"))
@@ -112,19 +146,21 @@ module Ruact
           end
 
           def validate_kind!(js_id, kind)
-            return if kind == "action"
+            return if %w[action query].include?(kind)
 
             raise Ruact::ConfigurationError,
                   "ruact server-function codegen: v2 snapshot entry #{js_id.inspect} has invalid " \
-                  "kind #{kind.inspect} (v2 entries are always \"action\")."
+                  "kind #{kind.inspect} (v2 entries are \"action\" or \"query\")."
           end
 
-          def validate_method!(js_id, method)
-            return if HTTP_METHODS.include?(method)
+          # Story 9.5 — actions carry a mutation verb; queries are GET-only.
+          def validate_method!(js_id, kind, method)
+            allowed = kind == "query" ? QUERY_HTTP_METHODS : HTTP_METHODS
+            return if allowed.include?(method)
 
             raise Ruact::ConfigurationError,
                   "ruact server-function codegen: v2 snapshot entry #{js_id.inspect} has invalid " \
-                  "http_method #{method.inspect} (must be one of #{HTTP_METHODS.to_a.inspect})."
+                  "http_method #{method.inspect} (must be one of #{allowed.to_a.inspect})."
           end
 
           def validate_path!(js_id, path)

data/lib/ruact/server_functions/error_rendering.rb

@@ -119,6 +119,7 @@ module Ruact
       end
 
       # Story 8.4 — Status mapping per AC1:
+      # - `Ruact::BadRequestError` → 400 (Story 9.5 — FR88 kwargs rejection)
       # - `ActiveRecord::RecordInvalid` → 422
       # - `ActionController::InvalidAuthenticityToken` → 403
       # - `Ruact::UploadTooLargeError` → 413
@@ -127,6 +128,7 @@ module Ruact
       # at load time (parity with {ErrorSuggestion}).
       def __ruact_status_for(error)
         case error.class.name
+        when "Ruact::BadRequestError" then 400
         when "ActiveRecord::RecordInvalid" then 422
         when "ActionController::InvalidAuthenticityToken" then 403
         when "Ruact::UploadTooLargeError" then 413

data/lib/ruact/server_functions/name_bridge.rb

@@ -47,16 +47,21 @@ module Ruact
 
       # Story 8.2 (2026-05-17 review patches R2 + R12) — names already
       # bound at the top of `app/javascript/.ruact/server-functions.ts`,
-      # either by the helper re-export (`revalidate`) or the runtime
-      # import (`_makeRef`). A `ruact_action :revalidate` or
-      # `ruact_action :_make_ref` would emit a clashing `export const`
-      # next to the existing binding and crash at module-load time.
-      # The rule fires at controller-class load so the failure
-      # surfaces during boot, not at first request.
+      # either by a helper re-export (`revalidate`, `useQuery`) or a runtime
+      # import (`_makeRef`, `_makeServerFunction`, `_makeQuery`). A
+      # `ruact_action :revalidate` / a query method `use_query` would emit a
+      # clashing `export const` / duplicate export next to the existing
+      # binding and crash the generated module at load time. The rule fires
+      # at controller-class load / route-draw so the failure surfaces during
+      # boot, not at first request.
+      # Story 9.5 added `_makeQuery` (the v2 query import) and `useQuery` (the
+      # query hook re-export) to this list.
       RESERVED_BY_RUACT = %w[
+        _makeQuery
         _makeRef
         _makeServerFunction
         revalidate
+        useQuery
       ].to_set.freeze
 
       class << self

data/lib/ruact/server_functions/query_dispatch.rb

@@ -40,6 +40,14 @@ module Ruact
         # The Method#parameters types that mark keyword arguments (D7).
         KEYWORD_PARAM_TYPES = %i[key keyreq].freeze
 
+        # Story 9.5 (FR88) — the wire is GET query-string values, so every
+        # primitive the client sends arrives as a String (`?limit=5` →
+        # `"5"`); `nil` is the only non-String primitive Rack can produce for
+        # a scalar param. Arrays (`?q[]=`) and Hashes (`?q[k]=`) are the
+        # rejected complex shapes. Membership here = "this is a primitive the
+        # allowlist accepts".
+        PRIMITIVE_PARAM_CLASSES = [String, NilClass].freeze
+
         private
 
         # The action body of every query action: fresh context + fresh query
@@ -55,19 +63,76 @@ module Ruact
           render json: ActiveSupport::JSON.encode(serialized)
         end
 
-        # D7 — minimal, best-effort param passing: only the keyword arguments
-        # the query method declares, read by name from the GET query params
-        # (values arrive as Strings). The strict FR88 sanitization contract
-        # (primitive allowlist, reject objects, 400 on invalid) is Story 9.5,
-        # coupled to the `useQuery` wire format.
+        # Story 9.5 (FR88) — the AUTHORITATIVE kwargs sanitization. The query
+        # method's declared keyword arguments are the contract; the client's
+        # `useQuery(ref, params)` call sends those as GET query-string values.
+        # Reads the RAW client params from `request.query_parameters` (not
+        # `params`, which is polluted with Rails' `controller`/`action`/
+        # `format` routing defaults — those must not count as "unknown
+        # parameters"). Enforces, in order:
+        #
+        #   1. **Allowlist** — every provided value must be a primitive
+        #      (`string | number | boolean | null`; on the wire: String or
+        #      nil). An Array (`?q[]=`) or Hash (`?q[k]=`) is rejected with a
+        #      descriptive `Ruact::BadRequestError` naming the offending key
+        #      and the allowlist → 400.
+        #   2. **Unknown param** — a provided key matching no declared kwarg
+        #      (and the method has no `**rest`) is rejected, not silently
+        #      dropped → 400.
+        #   3. **Missing required** — a declared `keyreq` the client did not
+        #      send → 400 naming the missing parameter.
+        #
+        # Returns the symbol-keyed kwargs hash to splat into the query method.
         def __ruact_query_kwargs(query, query_method)
-          query.method(query_method).parameters.each_with_object({}) do |(type, name), kwargs|
-            next unless KEYWORD_PARAM_TYPES.include?(type)
+          signature = query.method(query_method).parameters
+          required = signature.filter_map { |type, name| name.to_s if type == :keyreq }
+          optional = signature.filter_map { |type, name| name.to_s if type == :key }
+          accepts_rest = signature.any? { |type, _name| type == :keyrest }
+          declared = required + optional
+
+          provided = request.query_parameters
+
+          provided.each do |key, value|
+            __ruact_validate_query_param!(query_method, key, value, declared, accepts_rest)
+          end
+
+          missing = required.reject { |name| provided.key?(name) }
+          unless missing.empty?
+            raise Ruact::BadRequestError,
+                  "ruact query :#{query_method} is missing required parameter(s) " \
+                  "#{missing.map { |n| n.to_sym.inspect }.join(', ')}."
+          end
 
-            kwargs[name] = params[name.to_s] if params.key?(name.to_s)
+          provided.each_with_object({}) do |(key, value), kwargs|
+            kwargs[key.to_sym] = value if declared.include?(key) || accepts_rest
           end
         end
 
+        # FR88 per-param gate — see {#__ruact_query_kwargs}. Order matters:
+        # the unknown-param check precedes the type check so an unknown
+        # complex param is reported as "unknown" (the more actionable error).
+        #
+        # `accepts_rest` (the method declares `**rest`) relaxes ONLY the
+        # named-parameter restriction — a `**rest` signature is the author's
+        # explicit opt-in to arbitrary kwargs, so no provided key is "unknown".
+        # The TYPE allowlist below STILL runs for every param including the
+        # rest-captured ones, so the FR88 security boundary (reject
+        # arrays/objects) holds regardless of `**rest`.
+        def __ruact_validate_query_param!(query_method, key, value, declared, accepts_rest)
+          unless declared.include?(key) || accepts_rest
+            raise Ruact::BadRequestError,
+                  "ruact query :#{query_method} received unknown parameter #{key.to_sym.inspect} " \
+                  "— it matches no keyword argument of the query method."
+          end
+
+          return if PRIMITIVE_PARAM_CLASSES.any? { |klass| value.is_a?(klass) }
+
+          raise Ruact::BadRequestError,
+                "ruact query :#{query_method} parameter #{key.to_sym.inspect} must be a " \
+                "string, number, boolean, or null — arrays and objects are rejected " \
+                "(got #{value.class})."
+        end
+
         # D5 — the {Ruact::Server} mutation gate returns false for GET/HEAD so
         # GET *pages* keep stock Rails errors; query dispatch requests are GET
         # *function calls*, so the structured 8.4 payload must render here.

data/lib/ruact/server_functions/query_source.rb

@@ -0,0 +1,150 @@
+# frozen_string_literal: true
+
+require "active_support/core_ext/string/inflections"
+require "ruact/server_functions/name_bridge"
+
+module Ruact
+  module ServerFunctions
+    # Story 9.5 — derives v2 QUERY entries for the route-driven codegen, the
+    # read-side sibling of {RouteSource} (which derives the non-GET mutation
+    # actions). Queries come from {Ruact::Query} subclasses mounted via the
+    # `ruact_queries` routing macro (Story 9.4).
+    #
+    # ## Why read the drawn route table, not all Ruact::Query subclasses
+    #
+    # The route table is the single source of truth (FR61): a host exposes a
+    # query ONLY by mounting its class with `ruact_queries` in `routes.rb`.
+    # Enumerating every `Ruact::Query` subclass would over-expose query classes
+    # that are defined but never mounted (and would 404 when `useQuery` fetched
+    # their non-existent routes). Reading the routes the `ruact_queries` macro
+    # actually drew keeps codegen route-truth-consistent with dispatch by
+    # construction — and means there is no `app/queries` force-load gap to
+    # paper over (mounting a class in `routes.rb` already autoloads it).
+    #
+    # Every generated query dispatch controller lives under the
+    # {QUERY_CONTROLLER_PREFIX} namespace (see
+    # {QueryDispatch.route_target_for}), so the GET routes this module consumes
+    # are unambiguous: any drawn route whose controller path starts with that
+    # prefix is a mounted query method.
+    #
+    # Pure by construction: {.collect} takes the route set and a resolver
+    # callable (controller-path → the backing {Ruact::Query} subclass). The
+    # railtie passes the real constant-resolving implementation; unit specs
+    # inject a lambda so the derivation is testable without booting controllers.
+    #
+    # @see RouteSource the mutation (action) sibling
+    # @see Ruact::Routing#ruact_queries the macro that draws the routes read here
+    module QuerySource
+      # The controller-path prefix every generated query dispatch controller
+      # lives under (mirrors {QueryDispatch.route_target_for}). A drawn GET
+      # route whose controller starts with this prefix is a mounted query.
+      QUERY_CONTROLLER_PREFIX = "ruact/server_functions/query_dispatch/"
+
+      # `Method#parameters` types that mark keyword arguments — the FR88 query
+      # parameters (mirrors {QueryDispatch::Dispatching::KEYWORD_PARAM_TYPES}).
+      KEYWORD_PARAM_TYPES = %i[key keyreq keyrest].freeze
+
+      class << self
+        # Collects v2 query entries from +route_set+.
+        #
+        # @param route_set [#routes] anything exposing `#routes` (an
+        #   `ActionDispatch::Routing::RouteSet`, or `Rails.application.routes`).
+        # @param query_class_for [#call, nil] `controller_path(String) ->
+        #   (Class | nil)` — resolves a query dispatch controller path to the
+        #   {Ruact::Query} subclass it backs. Defaults to real constant
+        #   resolution (reads the generated controller's `__ruact_query_class`).
+        # @return [Array<Hash>] query entries (string keys) sorted by
+        #   `js_identifier`; shape: `js_identifier`, `kind` (always `"query"`),
+        #   `http_method` (always `"GET"`), `path`, `segments` (always `[]`),
+        #   `accepts_params` (Boolean — does the method declare kwargs?),
+        #   `controller` (the query class name — for collision origins),
+        #   `action` (the Ruby method name).
+        # @raise [Ruact::ConfigurationError] on a query×query naming collision.
+        def collect(route_set, query_class_for: nil)
+          query_class_for ||= method(:default_query_class_for)
+
+          entries = []
+          route_set.routes.each do |route|
+            controller = route.defaults[:controller]
+            action = route.defaults[:action]
+            next if controller.nil? || action.nil?
+            next unless controller.to_s.start_with?(QUERY_CONTROLLER_PREFIX)
+
+            query_class = query_class_for.call(controller.to_s)
+            next if query_class.nil?
+
+            entries << build_entry(route, action.to_s, query_class)
+          end
+
+          entries = entries.sort_by { |entry| entry["js_identifier"] }
+          detect_collisions!(entries)
+          entries
+        end
+
+        private
+
+        def build_entry(route, action, query_class)
+          {
+            "js_identifier" => NameBridge.to_js_identifier(action),
+            "kind" => "query",
+            "http_method" => "GET",
+            "path" => clean_path(route),
+            "segments" => [],
+            "accepts_params" => accepts_params?(query_class, action),
+            "controller" => query_class.name,
+            "action" => action
+          }
+        end
+
+        # Does the query method declare any keyword arguments (FR88 params)?
+        # Drives the emitted TS signature: `(params) => Promise<unknown>` when
+        # true, `() => Promise<unknown>` when false (AC1).
+        def accepts_params?(query_class, action)
+          query_class.instance_method(action).parameters.any? do |(type, _name)|
+            KEYWORD_PARAM_TYPES.include?(type)
+          end
+        rescue NameError
+          false
+        end
+
+        # query×query collision — two mounted query classes whose methods map
+        # to the SAME JS identifier (e.g. `CatalogQuery#search_users` and
+        # `PeopleQuery#search_users`). Fail loudly at boot naming both origins.
+        # The route×query side of the merged namespace is detected at the
+        # codegen combine point (see {ServerFunctions.write_v2_snapshot!}).
+        def detect_collisions!(entries)
+          entries.group_by { |entry| entry["js_identifier"] }.each do |js_id, group|
+            next if group.size < 2
+
+            origins = group.map { |entry| "#{entry['controller']}##{entry['action']}" }
+            raise Ruact::ConfigurationError,
+                  "server-function naming collision: #{origins.join(' and ')} " \
+                  "both map to JS identifier \"#{js_id}\" — rename one of the query methods."
+          end
+        end
+
+        # `/q/categories(.:format)` → `/q/categories`. Mirrors
+        # {RouteSource#clean_path}: drops the trailing format optional and any
+        # remaining optional `( … )` group.
+        def clean_path(route)
+          spec = route.path.spec.to_s
+          spec = spec.delete_suffix("(.:format)")
+          spec.gsub(/\([^)]*\)/, "")
+        end
+
+        # Real resolver — used in the railtie/rake paths. The generated query
+        # dispatch controller exposes `__ruact_query_class` (a singleton method
+        # set by {QueryDispatch.controller_for}); resolve the controller
+        # constant from its path and read that back.
+        def default_query_class_for(controller)
+          klass = "#{controller}_controller".camelize.safe_constantize
+          return nil unless klass.respond_to?(:__ruact_query_class)
+
+          klass.__ruact_query_class
+        rescue StandardError
+          nil
+        end
+      end
+    end
+  end
+end