ruact 0.0.3 → 0.0.4

data/lib/ruact/server_functions.rb

@@ -26,6 +26,7 @@ module Ruact
     autoload :SnapshotWriter,     "ruact/server_functions/snapshot_writer"
     autoload :Codegen,            "ruact/server_functions/codegen"
     autoload :RouteSource,        "ruact/server_functions/route_source"
+    autoload :QuerySource,        "ruact/server_functions/query_source"
     autoload :ErrorRendering,     "ruact/server_functions/error_rendering"
     autoload :EndpointController, "ruact/server_functions/endpoint_controller"
     autoload :StandaloneContext, "ruact/server_functions/standalone_context"
@@ -45,13 +46,23 @@ module Ruact
     # AC2 — transparency over silence: the exposed names are ALWAYS logged so a
     # routed non-GET action never becomes a callable server function silently.
     #
+    # Story 9.5 — the `entries` array now carries BOTH mutation actions (from
+    # {RouteSource}) and read queries (from {QuerySource}); they share ONE
+    # merged JS namespace. {.detect_merged_namespace_collisions!} catches a
+    # route×query clash (each source already catches its own intra-kind
+    # collisions); the rename-override macro `ruact_function_name` on the
+    # mutation side (or renaming the query method) resolves it.
+    #
     # @param route_set [#routes] the Rails route set.
     # @param root [Pathname] the app root (for `tmp/cache` + `app/javascript`).
     # @param logger [#info, nil] logger for the exposure line; defaults to
     #   `Rails.logger` when Rails is loaded, else nil.
-    # @return [Array<Hash>] the exposed v2 entries.
+    # @return [Array<Hash>] the exposed v2 entries (actions + queries).
     def self.write_v2_snapshot!(route_set:, root:, logger: default_logger)
-      entries = RouteSource.collect(route_set)
+      actions = RouteSource.collect(route_set)
+      queries = QuerySource.collect(route_set)
+      entries = (actions + queries).sort_by { |entry| entry["js_identifier"] }
+      detect_merged_namespace_collisions!(entries)
 
       json_path = root.join("tmp/cache/ruact/server-functions.next.json")
       ts_path   = root.join("app/javascript/.ruact/server-functions.next.ts")
@@ -71,5 +82,30 @@ module Ruact
     def self.default_logger
       defined?(Rails) && Rails.respond_to?(:logger) ? Rails.logger : nil
     end
+
+    # Story 9.5 (Task 2) — the merged JS namespace covers route (action)
+    # entries AND query entries. {RouteSource} already rejects action×action
+    # collisions and {QuerySource} rejects query×query; this final pass catches
+    # a route×query clash — two distinct origins (one a mutation route, one a
+    # query method) mapping to the same `js_identifier` would emit two
+    # `export const <id>` lines and crash the generated module at load. Fail
+    # loudly at boot naming BOTH origins. The escape hatch is the
+    # `ruact_function_name :<action>, as: "<id>"` rename macro on the mutation
+    # controller (Story 9.3) or renaming the colliding query method.
+    #
+    # @param entries [Array<Hash>] merged action + query entries.
+    # @raise [Ruact::ConfigurationError]
+    def self.detect_merged_namespace_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}\" — disambiguate with " \
+              "`ruact_function_name :<action>, as: \"<other-name>\"` on the mutation " \
+              "controller, or rename the query method."
+      end
+    end
   end
 end

data/lib/ruact/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Ruact
-  VERSION = "0.0.3"
+  VERSION = "0.0.4"
 end

data/spec/ruact/query_request_spec.rb

@@ -155,17 +155,47 @@ module QueryRequestSpecSupport # rubocop:disable Style/OneClassPerFile
 
   # Custom parent for the AC2 configurability unit assertion.
   class AltParentController < ActionController::Base; end
+
+  # Story 9.5 (FR88) fixture — a required kwarg (`q`), an optional kwarg with
+  # a default (`limit`), and a separate required-only method. Mounted on the
+  # shared app alongside CatalogQuery so the FR88 sanitization is exercised
+  # end-to-end through the host chain.
+  class SearchQuery < ApplicationQuery
+    # `q` is the natural query parameter name and is asserted verbatim in the
+    # FR88 rejection messages below.
+    def search(q:, limit: "10") # rubocop:disable Naming/MethodParameterName
+      { "q" => q, "limit" => limit }
+    end
+
+    def tags(filter:)
+      { "filter" => filter }
+    end
+
+    # A `**rest` query: it opts into arbitrary kwargs, so extra params are NOT
+    # "unknown" — but the FR88 type allowlist still rejects arrays/objects.
+    def flexible(q:, **rest) # rubocop:disable Naming/MethodParameterName
+      { "q" => q, "rest" => rest.transform_keys(&:to_s) }
+    end
+
+    # For the null-wire contract: `useQuery` sends `null` as a bare key (`?opt`),
+    # which Rack parses as `nil` (distinct from `?opt=` → `""`).
+    def nullable(opt: "default")
+      { "opt" => opt }
+    end
+  end
 end
 
 if defined?(ControllerRequestSpecSupport) &&
    !ControllerRequestSpecSupport.instance_variable_get(:@__ruact_query_routes_appended)
   ControllerRequestSpecSupport.instance_variable_set(:@__ruact_query_routes_appended, true)
   ControllerRequestSpecSupport.app_class.routes.append do
-    ruact_queries QueryRequestSpecSupport::CatalogQuery, QueryRequestSpecSupport::PublicCatalogQuery
+    ruact_queries QueryRequestSpecSupport::CatalogQuery,
+                  QueryRequestSpecSupport::PublicCatalogQuery,
+                  QueryRequestSpecSupport::SearchQuery
   end
 end
 
-RSpec.describe "Story 9.4: Ruact::Query + ruact_queries dispatch", :story_9_4 do
+RSpec.describe "Story 9.4: Ruact::Query + ruact_queries dispatch", :story_9_4 do # rubocop:disable RSpec/MultipleDescribes
   include Rack::Test::Methods
 
   let(:app_class) { ControllerRequestSpecSupport.app_class }
@@ -444,3 +474,125 @@ RSpec.describe "Story 9.4: Ruact::Query + ruact_queries dispatch", :story_9_4 do
     end
   end
 end
+
+RSpec.describe "Story 9.5: FR88 query kwargs sanitization", :story_9_5 do
+  include Rack::Test::Methods
+
+  let(:app_class) { ControllerRequestSpecSupport.app_class }
+  let(:app)       { app_class.instance }
+
+  let(:login_headers) { { "HTTP_X_TEST_LOGIN" => "1" } }
+
+  before do
+    Rails.logger = Logger.new(IO::NULL)
+    ControllerRequestSpecSupport.boot!
+  end
+
+  def structured_error(response)
+    expect(response.status).to eq(400)
+    body = JSON.parse(response.body)
+    expect(body.fetch("_ruact_server_action_error")).to be(true)
+    expect(body.fetch("error_class")).to eq("Ruact::BadRequestError")
+    body
+  end
+
+  describe "AC3 happy path — declared primitives pass" do
+    it "passes a required + optional kwarg by name (values arrive as strings)" do
+      get "/q/search?q=ruby&limit=5", {}, login_headers
+      expect(last_response.status).to eq(200)
+      expect(JSON.parse(last_response.body)).to eq("q" => "ruby", "limit" => "5")
+    end
+
+    it "omits an absent optional kwarg so the method default applies" do
+      get "/q/search?q=ruby", {}, login_headers
+      expect(last_response.status).to eq(200)
+      expect(JSON.parse(last_response.body)).to eq("q" => "ruby", "limit" => "10")
+    end
+
+    it "accepts boolean-ish / numeric-ish primitive strings on the wire" do
+      get "/q/search?q=true&limit=0", {}, login_headers
+      expect(last_response.status).to eq(200)
+      expect(JSON.parse(last_response.body)).to eq("q" => "true", "limit" => "0")
+    end
+  end
+
+  describe "AC3 — array param rejected (only string/number/boolean/null allowed)" do
+    it "400s with a descriptive error naming the key and the allowlist" do
+      get "/q/search?q[]=a&q[]=b", {}, login_headers
+      body = structured_error(last_response)
+      expect(body.fetch("message")).to match(/:q must be a string, number, boolean, or null/)
+      expect(body.fetch("message")).to match(/arrays and objects are rejected/)
+    end
+  end
+
+  describe "AC3 — object (hash) param rejected" do
+    it "400s with a descriptive error naming the offending key" do
+      get "/q/search?q[deep]=1", {}, login_headers
+      body = structured_error(last_response)
+      expect(body.fetch("message")).to match(/:q must be a string, number, boolean, or null/)
+    end
+  end
+
+  describe "AC3 — missing required kwarg → 400 naming the missing parameter" do
+    it "400s naming :q when it is absent" do
+      get "/q/search?limit=5", {}, login_headers
+      body = structured_error(last_response)
+      expect(body.fetch("message")).to match(/missing required parameter\(s\) :q/)
+      expect(body.fetch("action_name")).to eq("search")
+    end
+
+    it "400s naming :filter on a required-only method" do
+      get "/q/tags", {}, login_headers
+      body = structured_error(last_response)
+      expect(body.fetch("message")).to match(/missing required parameter\(s\) :filter/)
+    end
+  end
+
+  describe "AC3 — unknown param → 400 (rejected, not silently dropped)" do
+    it "400s naming the unknown parameter" do
+      get "/q/search?q=ruby&bogus=1", {}, login_headers
+      body = structured_error(last_response)
+      expect(body.fetch("message")).to match(/unknown parameter :bogus/)
+    end
+
+    it "rejects before running the query even when the declared param is also present" do
+      get "/q/search?q=ruby&bogus=1", {}, login_headers
+      expect(last_response.status).to eq(400)
+    end
+  end
+
+  describe "AC3 — a `**rest` query opts into extra kwargs, but the type allowlist still applies" do
+    it "accepts extra primitive params (not 'unknown' for a **rest signature)" do
+      get "/q/flexible?q=ruby&extra=1&flag=true", {}, login_headers
+      expect(last_response.status).to eq(200)
+      expect(JSON.parse(last_response.body)).to eq(
+        "q" => "ruby", "rest" => { "extra" => "1", "flag" => "true" }
+      )
+    end
+
+    it "STILL rejects an array param on a **rest query (FR88 type boundary holds)" do
+      get "/q/flexible?q=ruby&bad[]=1", {}, login_headers
+      body = structured_error(last_response)
+      expect(body.fetch("message")).to match(/:bad must be a string, number, boolean, or null/)
+    end
+
+    it "STILL rejects an object param on a **rest query" do
+      get "/q/flexible?q=ruby&bad[x]=1", {}, login_headers
+      body = structured_error(last_response)
+      expect(body.fetch("message")).to match(/:bad must be a string, number, boolean, or null/)
+    end
+  end
+
+  describe "null wire contract — a bare key (`?opt`) is delivered as nil, not empty string" do
+    it "delivers nil (the bare-key wire form useQuery sends for null)" do
+      get "/q/nullable?opt", {}, login_headers
+      expect(last_response.status).to eq(200)
+      expect(JSON.parse(last_response.body)).to eq("opt" => nil)
+    end
+
+    it "delivers an empty string for `?opt=` (distinct from null)" do
+      get "/q/nullable?opt=", {}, login_headers
+      expect(JSON.parse(last_response.body)).to eq("opt" => "")
+    end
+  end
+end

data/spec/ruact/server_functions/codegen_spec.rb

@@ -377,13 +377,13 @@ module Ruact
             .to raise_error(Ruact::ConfigurationError, /absent from path/)
         end
 
-        it "rejects a v2 entry with a non-action kind" do
+        it "rejects a v2 entry with an unknown kind (Story 9.5 — action/query only)" do
           evil = v2_snapshot.merge(functions: [
-                                     { "js_identifier" => "createPost", "kind" => "query",
+                                     { "js_identifier" => "createPost", "kind" => "mutation",
                                        "http_method" => "POST", "path" => "/posts", "segments" => [] }
                                    ])
           expect { described_class.render(evil) }
-            .to raise_error(Ruact::ConfigurationError, /v2 entries are always/)
+            .to raise_error(Ruact::ConfigurationError, /v2 entries are "action" or "query"/)
         end
 
         it "rejects a v2 entry whose js_identifier is reserved" do
@@ -424,6 +424,85 @@ module Ruact
             .to raise_error(Ruact::ConfigurationError, /absent from path/)
         end
       end
+
+      describe ".render — v2 query entries (Story 9.5)", :story_9_5 do
+        def query_entry(js_id, path, accepts_params:)
+          {
+            "js_identifier" => js_id, "kind" => "query", "http_method" => "GET",
+            "path" => path, "segments" => [], "accepts_params" => accepts_params,
+            "controller" => "CatalogQuery", "action" => js_id
+          }
+        end
+
+        it "emits a no-param query as _makeQuery with the () signature + useQuery re-export" do
+          out = described_class.render(version: 2, generated_at: "t", functions: [
+                                         query_entry("categories", "/q/categories", accepts_params: false)
+                                       ])
+          expect(out).to include('import { _makeQuery } from "ruact/server-functions-runtime";')
+          expect(out).to include("export const categories: () => Promise<unknown> =")
+          expect(out).to include('_makeQuery({ path: "/q/categories", kind: "query" });')
+          expect(out).to include('export { useQuery } from "ruact/server-functions-runtime";')
+          expect(out).to include('export { revalidate } from "ruact/server-functions-runtime";')
+        end
+
+        it "emits a param-declaring query with the (params) signature" do
+          out = described_class.render(version: 2, generated_at: "t", functions: [
+                                         query_entry("searchUsers", "/q/searchUsers", accepts_params: true)
+                                       ])
+          expect(out).to include("export const searchUsers: (params: Record<string, unknown>) => Promise<unknown> =")
+          expect(out).to include('_makeQuery({ path: "/q/searchUsers", kind: "query" });')
+        end
+
+        it "imports both accessors and re-exports useQuery for a mixed action+query snapshot" do
+          out = described_class.render(version: 2, generated_at: "t", functions: [
+                                         { "js_identifier" => "createPost", "kind" => "action",
+                                           "http_method" => "POST", "path" => "/posts", "segments" => [] },
+                                         query_entry("categories", "/q/categories", accepts_params: false)
+                                       ])
+          expect(out).to include('import { _makeServerFunction, _makeQuery } from "ruact/server-functions-runtime";')
+          expect(out).to include("_makeServerFunction({ method: \"POST\"")
+          expect(out).to include("_makeQuery({ path: \"/q/categories\", kind: \"query\" })")
+          expect(out).to include('export { useQuery } from "ruact/server-functions-runtime";')
+        end
+
+        it "accepts GET for a query entry (queries are GET-only)" do
+          expect do
+            described_class.render(version: 2, generated_at: "t", functions: [
+                                     query_entry("categories", "/q/categories", accepts_params: false)
+                                   ])
+          end.not_to raise_error
+        end
+
+        it "rejects a non-GET verb on a query entry" do
+          evil = { "js_identifier" => "categories", "kind" => "query", "http_method" => "POST",
+                   "path" => "/q/categories", "segments" => [] }
+          expect { described_class.render(version: 2, generated_at: "t", functions: [evil]) }
+            .to raise_error(Ruact::ConfigurationError, /invalid http_method/)
+        end
+
+        it "rejects a query entry whose js_identifier is the useQuery re-export name" do
+          evil = { "js_identifier" => "useQuery", "kind" => "query", "http_method" => "GET",
+                   "path" => "/q/useQuery", "segments" => [], "accepts_params" => false }
+          expect { described_class.render(version: 2, generated_at: "t", functions: [evil]) }
+            .to raise_error(Ruact::ConfigurationError, /reserved/)
+        end
+
+        it "rejects a query entry whose js_identifier is the _makeQuery import name" do
+          evil = { "js_identifier" => "_makeQuery", "kind" => "query", "http_method" => "GET",
+                   "path" => "/q/_makeQuery", "segments" => [], "accepts_params" => false }
+          expect { described_class.render(version: 2, generated_at: "t", functions: [evil]) }
+            .to raise_error(Ruact::ConfigurationError, /reserved/)
+        end
+
+        it "does NOT re-export useQuery for an action-only snapshot (byte-stable with 9.3)" do
+          out = described_class.render(version: 2, generated_at: "t", functions: [
+                                         { "js_identifier" => "createPost", "kind" => "action",
+                                           "http_method" => "POST", "path" => "/posts", "segments" => [] }
+                                       ])
+          expect(out).not_to include("useQuery")
+          expect(out).to end_with("export { revalidate } from \"ruact/server-functions-runtime\";\n")
+        end
+      end
     end
   end
 end

data/spec/ruact/server_functions/name_bridge_spec.rb

@@ -181,6 +181,30 @@ module Ruact
           it "R12 — accepts :_make_ref_action (suffix escape hatch keeps working)" do
             expect(described_class.to_js_identifier(:_make_ref_action)).to eq("_makeRefAction")
           end
+
+          # Story 9.5 — `_makeQuery` (the v2 query import) and `useQuery` (the
+          # query hook re-export) are new top-level bindings in the generated
+          # module; a query/action method mapping to either would redeclare the
+          # import / duplicate the export and crash at module load.
+          it "Story 9.5 — rejects :use_query because it collides with the useQuery re-export" do
+            expect { described_class.to_js_identifier(:use_query) }
+              .to raise_error(Ruact::ConfigurationError) do |error|
+                expect(error.message).to include(":use_query")
+                expect(error.message).to include("duplicate export")
+              end
+          end
+
+          it "Story 9.5 — rejects :_make_query because it collides with the codegen's runtime import" do
+            expect { described_class.to_js_identifier(:_make_query) }
+              .to raise_error(Ruact::ConfigurationError) do |error|
+                expect(error.message).to include(":_make_query")
+                expect(error.message).to include("duplicate export")
+              end
+          end
+
+          it "Story 9.5 — accepts :use_query_results (suffix escape hatch keeps working)" do
+            expect(described_class.to_js_identifier(:use_query_results)).to eq("useQueryResults")
+          end
         end
       end
     end

data/spec/ruact/server_functions/query_source_spec.rb

@@ -0,0 +1,142 @@
+# frozen_string_literal: true
+
+require "spec_helper"
+require "ruact/server_functions"
+require "ruact/server_functions/query_source"
+
+module Ruact
+  module ServerFunctions
+    # Plain query classes — only `instance_method(...).parameters` (kwargs
+    # presence) and `.name` (collision origin) are read. Defined at module
+    # level so they are not example-group-leaky constants.
+    class CatalogQ
+      def categories; end
+
+      def search_users(term:, limit: 10); end
+    end
+
+    class PeopleQ
+      def search_users(term:); end
+    end
+
+    # Story 9.5 — query introspection: the drawn route table (filtered to the
+    # generated query dispatch controllers) → v2 query entries. Pure: route set
+    # and the query-class resolver are injected, so the derivation is testable
+    # with no Rails boot and no controllers (a fake route set + plain query
+    # classes).
+    RSpec.describe QuerySource, :story_9_5 do
+      # Minimal route double exposing the surface QuerySource reads:
+      # `defaults[:controller]`, `defaults[:action]`, `path.spec.to_s`.
+      def query_route(controller, action, path)
+        spec = Object.new
+        spec.define_singleton_method(:to_s) { "#{path}(.:format)" }
+        path_obj = Object.new
+        path_obj.define_singleton_method(:spec) { spec }
+        route = Object.new
+        route.define_singleton_method(:defaults) { { controller: controller, action: action } }
+        route.define_singleton_method(:path) { path_obj }
+        route
+      end
+
+      def route_set(routes)
+        rs = Object.new
+        rs.define_singleton_method(:routes) { routes }
+        rs
+      end
+
+      let(:prefix) { QuerySource::QUERY_CONTROLLER_PREFIX }
+
+      def resolver(map)
+        ->(controller) { map[controller] }
+      end
+
+      describe ".collect" do
+        it "emits one query entry per mounted query route (route-truth)" do
+          rs = route_set([
+                           query_route("#{prefix}catalog_q", "categories", "/q/categories"),
+                           query_route("#{prefix}catalog_q", "search_users", "/q/searchUsers")
+                         ])
+          entries = described_class.collect(rs, query_class_for: resolver("#{prefix}catalog_q" => CatalogQ))
+
+          expect(entries.map { |e| e["js_identifier"] }).to eq(%w[categories searchUsers])
+          expect(entries).to all(include("kind" => "query", "http_method" => "GET", "segments" => []))
+        end
+
+        it "derives jsId via NameBridge and carries the clean path" do
+          rs = route_set([query_route("#{prefix}catalog_q", "search_users", "/q/searchUsers")])
+          entry = described_class.collect(rs, query_class_for: resolver("#{prefix}catalog_q" => CatalogQ)).first
+          expect(entry["js_identifier"]).to eq("searchUsers")
+          expect(entry["path"]).to eq("/q/searchUsers")
+          expect(entry["controller"]).to eq("Ruact::ServerFunctions::CatalogQ")
+          expect(entry["action"]).to eq("search_users")
+        end
+
+        it "flags accepts_params true when the method declares kwargs, false otherwise" do
+          rs = route_set([
+                           query_route("#{prefix}catalog_q", "categories", "/q/categories"),
+                           query_route("#{prefix}catalog_q", "search_users", "/q/searchUsers")
+                         ])
+          entries = described_class.collect(rs, query_class_for: resolver("#{prefix}catalog_q" => CatalogQ))
+          by_id = entries.to_h { |e| [e["js_identifier"], e] }
+          expect(by_id["categories"]["accepts_params"]).to be(false)
+          expect(by_id["searchUsers"]["accepts_params"]).to be(true)
+        end
+
+        it "ignores non-query routes (controller not under the dispatch namespace)" do
+          rs = route_set([
+                           query_route("posts", "create", "/posts"),
+                           query_route("#{prefix}catalog_q", "categories", "/q/categories")
+                         ])
+          entries = described_class.collect(rs, query_class_for: resolver("#{prefix}catalog_q" => CatalogQ))
+          expect(entries.map { |e| e["js_identifier"] }).to eq(%w[categories])
+        end
+
+        it "skips a query route whose class cannot be resolved (nil resolver result)" do
+          rs = route_set([query_route("#{prefix}gone_q", "categories", "/q/categories")])
+          expect(described_class.collect(rs, query_class_for: resolver({}))).to eq([])
+        end
+
+        it "raises a query×query collision naming both origins" do
+          rs = route_set([
+                           query_route("#{prefix}catalog_q", "search_users", "/q/searchUsers"),
+                           query_route("#{prefix}people_q", "search_users", "/q/searchUsers")
+                         ])
+          map = { "#{prefix}catalog_q" => CatalogQ, "#{prefix}people_q" => PeopleQ }
+          expect { described_class.collect(rs, query_class_for: resolver(map)) }
+            .to raise_error(Ruact::ConfigurationError, /CatalogQ#search_users and .*PeopleQ#search_users/m)
+        end
+      end
+    end
+
+    # Story 9.5 (Task 2) — the merged JS namespace (route entries + query
+    # entries share it). The route×query side is detected at the codegen
+    # combine point.
+    RSpec.describe ".detect_merged_namespace_collisions!", :story_9_5 do
+      def action_entry(js_id, controller, action)
+        { "js_identifier" => js_id, "kind" => "action", "controller" => controller, "action" => action }
+      end
+
+      def query_entry(js_id, controller, action)
+        { "js_identifier" => js_id, "kind" => "query", "controller" => controller, "action" => action }
+      end
+
+      it "raises on a route×query collision naming both origins + the rename escape hatch" do
+        entries = [
+          action_entry("categories", "posts", "categories"),
+          query_entry("categories", "CatalogQuery", "categories")
+        ]
+        expect { ServerFunctions.detect_merged_namespace_collisions!(entries) }
+          .to raise_error(Ruact::ConfigurationError,
+                          /posts#categories and CatalogQuery#categories.*ruact_function_name/m)
+      end
+
+      it "does not raise when the rename makes the identifiers distinct" do
+        entries = [
+          action_entry("listCategories", "posts", "categories"), # renamed via ruact_function_name
+          query_entry("categories", "CatalogQuery", "categories")
+        ]
+        expect { ServerFunctions.detect_merged_namespace_collisions!(entries) }.not_to raise_error
+      end
+    end
+  end
+end

data/spec/ruact/server_functions/railtie_integration_spec.rb

@@ -125,6 +125,73 @@ module Ruact
       end
     end
 
+    RSpec.describe "Ruact::ServerFunctions.write_v2_snapshot! — queries (Story 9.5)", :story_9_5 do
+      # `ruact_queries` + query dispatch live behind these requires (loaded
+      # explicitly here as the railtie would at boot).
+      require "ruact/routing"
+      require "ruact/query"
+
+      around do |example|
+        Dir.mktmpdir { |dir| @tmpdir = dir and example.run }
+      end
+
+      before do
+        stub_const("V2QueryParentController", Class.new(ActionController::Base))
+        Ruact.configure { |c| c.query_parent_controller = "V2QueryParentController" }
+        stub_const("V2CatalogQuery", Class.new(Ruact::Query) do
+          def categories; end
+          def search(term:); end
+        end)
+      end
+
+      def route_set
+        route_set = ActionDispatch::Routing::RouteSet.new
+        route_set.draw { ruact_queries V2CatalogQuery }
+        route_set
+      end
+
+      def write!(routes = route_set)
+        Ruact::ServerFunctions.write_v2_snapshot!(route_set: routes, root: Pathname.new(@tmpdir))
+      end
+
+      let(:next_ts) { File.join(@tmpdir, "app/javascript/.ruact/server-functions.next.ts") }
+
+      it "emits query entries (route-truth) merged into the v2 snapshot" do
+        entries = write!
+        expect(entries.map { |e| e["js_identifier"] }).to match_array(%w[categories search])
+        expect(entries).to all(include("kind" => "query", "http_method" => "GET"))
+      end
+
+      it "renders _makeQuery refs + the useQuery re-export into the .next TS" do
+        write!
+        ts = File.read(next_ts)
+        expect(ts).to include('import { _makeQuery } from "ruact/server-functions-runtime";')
+        expect(ts).to include('_makeQuery({ path: "/q/categories", kind: "query" });')
+        expect(ts).to include("export const categories: () => Promise<unknown> =")
+        expect(ts).to include("export const search: (params: Record<string, unknown>) => Promise<unknown> =")
+        expect(ts).to include('export { useQuery } from "ruact/server-functions-runtime";')
+      end
+
+      it "raises a route×query collision when an action and a query share a js_identifier" do
+        stub_const("CategoriesController", Class.new(ActionController::Base) { include Ruact::Server })
+        stub_const("CollideQuery", Class.new(Ruact::Query) { def categories; end })
+        rs = ActionDispatch::Routing::RouteSet.new
+        rs.draw do
+          # POST /categories#create would derive js_identifier "createCategory" — to
+          # force a clash, use a custom collection route named to collide head-on.
+          post "categories", to: "categories#categories"
+          ruact_queries CollideQuery
+        end
+        # Rename the action's js_identifier to exactly "categories" so it collides
+        # with the query method.
+        CategoriesController.define_singleton_method(:__ruact_function_name_overrides) do
+          { "categories" => "categories" }
+        end
+        expect { Ruact::ServerFunctions.write_v2_snapshot!(route_set: rs, root: Pathname.new(@tmpdir)) }
+          .to raise_error(Ruact::ConfigurationError, /both map to JS identifier "categories".*ruact_function_name/m)
+      end
+    end
+
     RSpec.describe "Ruact::Railtie registry-clear hook (Story 8.1)", :story_8_1 do
       # The Railtie attaches a `before_class_unload` callback that clears both
       # registries before Zeitwerk tears down constants — this prevents removed

data/vendor/javascript/ruact-server-functions-runtime/index.d.ts

@@ -87,6 +87,40 @@ export function _makeServerFunction(descriptor: {
 ) => Promise<unknown>) &
   ((formData: RuactFormData) => Promise<void>);
 
+/**
+ * Story 9.5 — the read-side (query) accessor. The codegen emits
+ * `_makeQuery({ path, kind: "query" })` for every method on a mounted
+ * `Ruact::Query` subclass. The returned callable issues a GET to the named
+ * query route (`GET /q/<jsId>`), serializing `params` into the query string
+ * (FR88: string / number / boolean / null only). Reads are CSRF-free: no
+ * body, no `X-CSRF-Token`.
+ *
+ * Usually consumed through {@link useQuery}, but callable directly in
+ * imperative code. The emitted module narrows the param surface per query
+ * (`() => Promise<unknown>` when the Ruby method declares no kwargs;
+ * `(params: Record<string, unknown>) => Promise<unknown>` when it does).
+ */
+export function _makeQuery(descriptor: {
+  path: string;
+  kind?: string;
+}): (params?: Record<string, unknown>) => Promise<unknown>;
+
+/**
+ * Story 9.5 — React hook for reading a server query. Pass a query reference
+ * (the codegen-emitted `_makeQuery` accessor) and optional params; issues
+ * `GET /q/<jsId>` on mount (and whenever the serialized params change) and
+ * returns `{ data, loading, error }`. `loading` is true until the first
+ * resolution; `error` carries the structured {@link RuactActionError} on
+ * failure. A superseded in-flight response is dropped.
+ *
+ * Request de-duplication across components is Story 9.6; this hook fetches
+ * once per mount.
+ */
+export function useQuery<T = unknown>(
+  reference: (params?: Record<string, unknown>) => Promise<unknown>,
+  params?: Record<string, unknown>,
+): { data: T | undefined; loading: boolean; error: unknown };
+
 /**
  * Story 8.2 — issues a Flight refetch of the supplied path (or the
  * current URL when omitted) and swaps the React tree in place. Mirrors