ruact 0.0.5 → 0.0.7

data/spec/ruact/server_functions/codegen_spec.rb

@@ -5,302 +5,61 @@ require "tmpdir"
 
 module Ruact
   module ServerFunctions
-    RSpec.describe Codegen, :story_8_0a do
-      let(:base_snapshot) do
+    RSpec.describe Codegen, :story_9_3 do
+      # Story 9.9 — the v1 (registry / `_makeRef`) render path was demolished;
+      # only the route-driven (version-2) snapshot is supported.
+      let(:v2_base) do
         {
-          version: 1,
-          generated_at: "2026-05-13T12:34:56Z",
+          version: 2,
+          generated_at: "2026-06-09T00:00:00Z",
           functions: []
         }
       end
 
-      describe ".render — empty registry (Story 8.0a AC4)" do
-        it "emits a valid module with import line and the empty-registry comment" do
-          # Story 8.2 — the empty-registry branch also emits the
-          # `export { revalidate } from "..."` re-export so
-          # `import { revalidate } from "@/.ruact/server-functions"` works in
-          # projects that have not yet declared any server actions.
-          result = described_class.render(base_snapshot)
-
-          expect(result).to eq(<<~TS)
-            // AUTO-GENERATED by vite-plugin-ruact (Story 8.0a). DO NOT EDIT.
-            // Source: tmp/cache/ruact/server-functions.json (version 1)
-            // Generated at: 2026-05-13T12:34:56Z
-            import { _makeRef } from "ruact/server-functions-runtime";
-
-            // (no server functions registered yet — Stories 8.1 / 9.1 populate)
-            void _makeRef;
-
-            export { revalidate } from "ruact/server-functions-runtime";
-          TS
-        end
-
-        it "ends with exactly one trailing newline" do
-          result = described_class.render(base_snapshot)
-          expect(result).to end_with("\n")
-          expect(result).not_to end_with("\n\n")
-        end
-
-        it "references _makeRef even when empty so noUnusedLocals stays green " \
-           "(Re-run patch 2026-05-13)" do
-          # Strictly checks that the import is "touched" — the canonical
-          # `void _makeRef;` is the lightweight discard pattern.
-          expect(described_class.render(base_snapshot)).to include("void _makeRef;")
-        end
-      end
-
-      describe ".render — single action (Story 8.0a AC4 + Story 8.2 intersection)" do
-        it "emits an action export typed as a TS intersection of direct-call + <form action> shapes" do
-          # Story 8.2 (refined 2026-05-17 per review patch R1) — the
-          # intersection makes `<form action={createPost}>` typecheck
-          # directly against React 19's
-          # `(formData: FormData) => void | Promise<void>` while preserving
-          # `Promise<unknown>` for direct callers. See the 2026-05-17 entry
-          # in `gem/docs/internal/decisions/server-functions-api.md`.
-          snapshot = base_snapshot.merge(functions: [
-                                           {
-                                             "ruby_symbol" => "create_post",
-                                             "js_identifier" => "createPost",
-                                             "kind" => "action",
-                                             "controller" => "PostsController"
-                                           }
-                                         ])
-
-          expect(described_class.render(snapshot)).to eq(<<~TS)
-            // AUTO-GENERATED by vite-plugin-ruact (Story 8.0a). DO NOT EDIT.
-            // Source: tmp/cache/ruact/server-functions.json (version 1)
-            // Generated at: 2026-05-13T12:34:56Z
-            import { _makeRef } from "ruact/server-functions-runtime";
-
-            export const createPost: ((args?: FormData | Record<string, unknown>) => Promise<unknown>) & ((formData: FormData) => Promise<void>) =
-              _makeRef("create_post");
-
-            export { revalidate } from "ruact/server-functions-runtime";
-          TS
-        end
-
-        it "Story 8.2 — query signatures do NOT widen (regression guard)" do
-          snapshot = base_snapshot.merge(functions: [
-                                           {
-                                             "ruby_symbol" => "categories",
-                                             "js_identifier" => "categories",
-                                             "kind" => "query",
-                                             "controller" => "CategoriesController"
-                                           }
-                                         ])
-
-          out = described_class.render(snapshot)
-          # Action-style FormData widening must not bleed into the query export
-          expect(out).not_to match(/export const categories:[^=]*FormData/)
-          expect(out).to include("export const categories: () => Promise<unknown> =")
-        end
-      end
-
-      describe ".render — single query (Story 8.0a AC4)" do
-        it "emits a query export with the no-args signature" do
-          snapshot = base_snapshot.merge(functions: [
-                                           {
-                                             "ruby_symbol" => "categories",
-                                             "js_identifier" => "categories",
-                                             "kind" => "query",
-                                             "controller" => "CategoriesController"
-                                           }
-                                         ])
-
-          expect(described_class.render(snapshot)).to include(
-            "export const categories: () => Promise<unknown> =\n  _makeRef(\"categories\");\n"
-          )
-        end
-      end
-
-      describe ".render — mixed action and query (Story 8.0a)" do
-        it "emits both shapes in the order provided by the snapshot" do
-          snapshot = base_snapshot.merge(functions: [
-                                           { "ruby_symbol" => "create_post",
-                                             "js_identifier" => "createPost",
-                                             "kind" => "action",
-                                             "controller" => "PostsController" },
-                                           { "ruby_symbol" => "categories",
-                                             "js_identifier" => "categories",
-                                             "kind" => "query",
-                                             "controller" => "CategoriesController" }
-                                         ])
-
-          out = described_class.render(snapshot)
-          expect(out).to include("export const createPost:")
-          expect(out).to include("export const categories:")
-          expect(out.index("createPost")).to be < out.index("categories")
+      describe ".render — unsupported / malformed snapshots" do
+        it "rejects when snapshot is not a Hash" do
+          expect { described_class.render("oops") }
+            .to raise_error(Ruact::ConfigurationError, /snapshot must be a Hash/)
         end
-      end
 
-      describe ".render — byte-stable across calls (Story 8.0a)" do
-        it "produces byte-identical output for identical snapshots" do
-          first  = described_class.render(base_snapshot)
-          second = described_class.render(base_snapshot.dup)
-          expect(first).to eq(second)
-        end
-      end
-
-      describe ".render — accepts symbol-keyed and string-keyed function entries" do
-        it "tolerates either key style" do
-          string_keys = base_snapshot.merge(functions: [
-                                              { "ruby_symbol" => "demo_ping",
-                                                "js_identifier" => "demoPing",
-                                                "kind" => "action" }
-                                            ])
-          symbol_keys = base_snapshot.merge(functions: [
-                                              { ruby_symbol: "demo_ping",
-                                                js_identifier: "demoPing",
-                                                kind: "action" }
-                                            ])
-          expect(described_class.render(string_keys)).to eq(described_class.render(symbol_keys))
+        it "wraps a missing root key as Ruact::ConfigurationError" do
+          evil = { generated_at: "2026-05-14T00:00:00Z", functions: [] } # no :version
+          expect { described_class.render(evil) }
+            .to raise_error(Ruact::ConfigurationError, /missing required key/)
         end
-      end
-
-      describe ".render — snapshot trust-boundary guards (Re-run patch 2026-05-13)" do
-        it "rejects a snapshot entry whose js_identifier is not a valid JS identifier " \
-           "(would otherwise inject TS at module top level)" do
-          snapshot = base_snapshot.merge(functions: [
-                                           { "ruby_symbol" => "create_post",
-                                             "js_identifier" => ");\nevil();_makeRef(\"x",
-                                             "kind" => "action" }
-                                         ])
-          expect { described_class.render(snapshot) }
-            .to raise_error(Ruact::ConfigurationError) do |error|
-              expect(error.message).to include("snapshot")
-              expect(error.message).to include("valid JS identifier")
-            end
-        end
-
-        it "rejects an entry with a non-String js_identifier" do
-          snapshot = base_snapshot.merge(functions: [
-                                           { "ruby_symbol" => "create_post",
-                                             "js_identifier" => nil,
-                                             "kind" => "action" }
-                                         ])
-          expect { described_class.render(snapshot) }
-            .to raise_error(Ruact::ConfigurationError, /valid JS identifier/)
-        end
-
-        it "JSON-escapes the ruby_symbol argument to _makeRef so backslashes / quotes " \
-           "in a (hand-edited or corrupted) snapshot cannot break out of the string literal" do
-          # The js_identifier still has to be a valid identifier — only the
-          # ruby_symbol can carry arbitrary string content. Escape it.
-          snapshot = base_snapshot.merge(functions: [
-                                           { "ruby_symbol" => "weird\"\\name",
-                                             "js_identifier" => "weirdName",
-                                             "kind" => "action" }
-                                         ])
-          out = described_class.render(snapshot)
-          expect(out).to include('_makeRef("weird\"\\\\name");')
-        end
-      end
-
-      describe ".render — snapshot trust-boundary guards (Re-run patch 2026-05-14)" do
-        # The Ruby renderer reads the same on-disk JSON bridge as the JS-side
-        # renderer (rake task path + Railtie path), so the same guards must
-        # apply on both sides. Mirrors the JS-side `validateSnapshot`.
 
         it "rejects a snapshot whose version contains a line break" do
-          evil = base_snapshot.merge(version: "1\n// injected")
+          evil = v2_base.merge(version: "2\n// injected")
           expect { described_class.render(evil) }
             .to raise_error(Ruact::ConfigurationError, /version.*line break/)
         end
 
         it "rejects a snapshot whose generated_at contains a line break" do
-          evil = base_snapshot.merge(generated_at: "2026-05-14\n// injected")
+          evil = v2_base.merge(generated_at: "2026-05-14\n// injected")
           expect { described_class.render(evil) }
             .to raise_error(Ruact::ConfigurationError, /generated_at.*line break/)
         end
 
-        it "rejects a snapshot whose functions field is not an Array" do
-          evil = base_snapshot.merge(functions: "oops2
// injected")
-          expect { described_class.render(evil) }
-            .to raise_error(Ruact::ConfigurationError, /functions must be an Array/)
-        end
-
-        it "rejects a snapshot entry whose kind is not in the allowlist" do
-          evil = base_snapshot.merge(functions: [
-                                       { "ruby_symbol" => "foo",
-                                         "js_identifier" => "foo",
-                                         "kind" => "mutation" }
-                                     ])
-          expect { described_class.render(evil) }
-            .to raise_error(Ruact::ConfigurationError, /invalid kind/)
-        end
-
-        it "rejects a snapshot whose entries duplicate a js_identifier" do
-          evil = base_snapshot.merge(functions: [
-                                       { "ruby_symbol" => "foo",
-                                         "js_identifier" => "foo",
-                                         "kind" => "action" },
-                                       { "ruby_symbol" => "bar",
-                                         "js_identifier" => "foo",
-                                         "kind" => "query" }
-                                     ])
-          expect { described_class.render(evil) }
-            .to raise_error(Ruact::ConfigurationError, /duplicate js_identifier "foo"/)
-        end
-
-        it "rejects a snapshot whose js_identifier is a JS reserved word" do
-          evil = base_snapshot.merge(functions: [
-                                       { "ruby_symbol" => "delete",
-                                         "js_identifier" => "delete",
-                                         "kind" => "action" }
-                                     ])
-          expect { described_class.render(evil) }
-            .to raise_error(Ruact::ConfigurationError, /reserved JS word/)
-        end
-
-        it "rejects a snapshot whose version contains a U+2028 line separator " \
-           "(Pass-2 patch 2026-05-14 — JS LineTerminator parity)" do
-          evil = base_snapshot.merge(version: "1
// injected")
+        it "rejects a snapshot whose version contains a U+2028 line separator (JS LineTerminator parity)" do
+          evil = v2_base.merge(version: "2
// injected")
           expect { described_class.render(evil) }
             .to raise_error(Ruact::ConfigurationError, /line break.*U\+2028/)
         end
 
-        it "rejects a snapshot whose generated_at contains a U+2029 paragraph separator " \
-           "(Pass-2 patch 2026-05-14
// — JS LineTerminator parity)" do
-          evil = base_snapshot.merge(generated_at: "2026-05-14
// injected")
+        it "rejects a snapshot whose generated_at contains a U+2029 paragraph separator (JS LineTerminator parity)" do
+          evil = v2_base.merge(generated_at: "2026-05-14
// injected")
           expect { described_class.render(evil) }
             .to raise_error(Ruact::ConfigurationError, /line break.*U\+2029/)
         end
 
-        it "wraps Hash#fetch KeyError as Ruact::ConfigurationError when a root key is " \
-           "missing (Pass-2 patch 2026-05-14)" do
-          evil = { generated_at: "2026-05-14T00:00:00Z", functions: [] } # no :version
-          expect { described_class.render(evil) }
-            .to raise_error(Ruact::ConfigurationError, /missing required key/)
-        end
-
-        it "rejects an entry with empty ruby_symbol so we never emit _makeRef(\"\") " \
-           "(Pass-2 patch 2026-05-14)" do
-          evil = base_snapshot.merge(functions: [
-                                       { "ruby_symbol" => "",
-                                         "js_identifier" => "foo",
-                                         "kind" => "action" }
-                                     ])
-          expect { described_class.render(evil) }
-            .to raise_error(Ruact::ConfigurationError, /missing or empty ruby_symbol/)
-        end
-
-        it "rejects an entry with nil ruby_symbol (Pass-2 patch 2026-05-14)" do
-          evil = base_snapshot.merge(functions: [
-                                       { "ruby_symbol" => nil,
-                                         "js_identifier" => "foo",
-                                         "kind" => "action" }
-                                     ])
+        it "rejects an unsupported (non-v2) snapshot version" do
+          evil = v2_base.merge(version: 1)
           expect { described_class.render(evil) }
-            .to raise_error(Ruact::ConfigurationError, /missing or empty ruby_symbol/)
-        end
-
-        it "rejects when snapshot is not a Hash" do
-          expect { described_class.render("oops") }
-            .to raise_error(Ruact::ConfigurationError, /snapshot must be a Hash/)
+            .to raise_error(Ruact::ConfigurationError, /unsupported snapshot version/)
         end
       end
 
-      describe ".generate_ts! (Story 8.0a — write-if-changed wrapper)" do
+      describe ".generate_ts! (write-if-changed wrapper)" do
         around do |example|
           Dir.mktmpdir do |dir|
             @tmpdir = dir
@@ -311,14 +70,14 @@ module Ruact
         let(:path) { File.join(@tmpdir, "server-functions.ts") }
 
         it "writes the file on first call and returns true" do
-          expect(described_class.generate_ts!(snapshot: base_snapshot, output_path: path))
+          expect(described_class.generate_ts!(snapshot: v2_base, output_path: path))
             .to be(true)
           expect(File.read(path)).to include("// AUTO-GENERATED by vite-plugin-ruact")
         end
 
-        it "does NOT rewrite when the content is byte-identical (Story 8.0a)" do
-          described_class.generate_ts!(snapshot: base_snapshot, output_path: path)
-          expect(described_class.generate_ts!(snapshot: base_snapshot, output_path: path))
+        it "does NOT rewrite when the content is byte-identical" do
+          described_class.generate_ts!(snapshot: v2_base, output_path: path)
+          expect(described_class.generate_ts!(snapshot: v2_base, output_path: path))
             .to be(false)
         end
       end
@@ -503,6 +262,136 @@ module Ruact
           expect(out).to end_with("export { revalidate } from \"ruact/server-functions-runtime\";\n")
         end
       end
+
+      describe ".render — typed query params (Story 13.4)", :story_13_4 do
+        def typed_query(js_id, path, params:, params_rest: false)
+          {
+            "js_identifier" => js_id, "kind" => "query", "http_method" => "GET",
+            "path" => path, "segments" => [],
+            "accepts_params" => !params.empty? || params_rest,
+            "params" => params, "params_rest" => params_rest,
+            "controller" => "CatalogQuery", "action" => js_id
+          }
+        end
+
+        let(:union) { "string | number | boolean | null" }
+
+        it "emits a typed params object (required + optional, declaration order)" do
+          out = described_class.render(version: 2, generated_at: "t", functions: [
+                                         typed_query("searchUsers", "/q/searchUsers", params: [
+                                                       { "name" => "term", "required" => true },
+                                                       { "name" => "limit", "required" => false }
+                                                     ])
+                                       ])
+          expect(out).to include(
+            "export const searchUsers: (params: { term: #{union}; limit?: #{union} }) => Promise<unknown> ="
+          )
+        end
+
+        it "emits the bare () signature for a query with empty params + no rest" do
+          out = described_class.render(version: 2, generated_at: "t", functions: [
+                                         typed_query("categories", "/q/categories", params: [])
+                                       ])
+          expect(out).to include("export const categories: () => Promise<unknown> =")
+        end
+
+        it "intersects named keys with Record<string, unknown> for a **keyrest query" do
+          out = described_class.render(version: 2, generated_at: "t", functions: [
+                                         typed_query("withRest", "/q/withRest",
+                                                     params: [{ "name" => "scope", "required" => true }],
+                                                     params_rest: true)
+                                       ])
+          expect(out).to include(
+            "export const withRest: (params: { scope: #{union} } & Record<string, unknown>) => Promise<unknown> ="
+          )
+        end
+
+        it "keeps the open Record<string, unknown> for a **keyrest-only query" do
+          out = described_class.render(version: 2, generated_at: "t", functions: [
+                                         typed_query("restOnly", "/q/restOnly", params: [], params_rest: true)
+                                       ])
+          expect(out).to include(
+            "export const restOnly: (params: Record<string, unknown>) => Promise<unknown> ="
+          )
+        end
+
+        it "quotes a param key that is not a valid bare JS identifier" do
+          out = described_class.render(version: 2, generated_at: "t", functions: [
+                                         typed_query("oddKey", "/q/oddKey",
+                                                     params: [{ "name" => "weird-key", "required" => false }])
+                                       ])
+          expect(out).to include("(params: { \"weird-key\"?: #{union} }) => Promise<unknown>")
+        end
+
+        it "falls back to the accepts_params boolean when no params metadata is present" do
+          out = described_class.render(version: 2, generated_at: "t", functions: [
+                                         { "js_identifier" => "legacyQuery", "kind" => "query",
+                                           "http_method" => "GET", "path" => "/q/legacyQuery",
+                                           "segments" => [], "accepts_params" => true }
+                                       ])
+          expect(out).to include(
+            "export const legacyQuery: (params: Record<string, unknown>) => Promise<unknown> ="
+          )
+        end
+
+        it "rejects params that are not an Array (trust boundary)" do
+          evil = typed_query("x", "/q/x", params: []).merge("params" => "oops")
+          expect { described_class.render(version: 2, generated_at: "t", functions: [evil]) }
+            .to raise_error(Ruact::ConfigurationError, /invalid.*params/)
+        end
+
+        it "rejects a params element that is not an object" do
+          evil = typed_query("x", "/q/x", params: ["nope"])
+          expect { described_class.render(version: 2, generated_at: "t", functions: [evil]) }
+            .to raise_error(Ruact::ConfigurationError, /params element that is not an object/)
+        end
+
+        it "rejects a params name containing a line break (TS injection guard)" do
+          evil = typed_query("x", "/q/x", params: [{ "name" => "a\n// injected", "required" => true }])
+          expect { described_class.render(version: 2, generated_at: "t", functions: [evil]) }
+            .to raise_error(Ruact::ConfigurationError, /non-empty single-line String/)
+        end
+
+        it "rejects a params name that is empty" do
+          evil = typed_query("x", "/q/x", params: [{ "name" => "", "required" => true }])
+          expect { described_class.render(version: 2, generated_at: "t", functions: [evil]) }
+            .to raise_error(Ruact::ConfigurationError, /non-empty single-line String/)
+        end
+
+        it "rejects a non-Boolean required" do
+          evil = typed_query("x", "/q/x", params: [{ "name" => "q", "required" => "yes" }])
+          expect { described_class.render(version: 2, generated_at: "t", functions: [evil]) }
+            .to raise_error(Ruact::ConfigurationError, /non-Boolean .*required/)
+        end
+
+        it "rejects a non-Boolean params_rest (would silently over-widen the type)" do
+          evil = typed_query("x", "/q/x", params: []).merge("params_rest" => "true")
+          expect { described_class.render(version: 2, generated_at: "t", functions: [evil]) }
+            .to raise_error(Ruact::ConfigurationError, /non-Boolean params_rest/)
+        end
+
+        it "accepts a legitimate required: false (not mis-read as absent)" do
+          expect do
+            described_class.render(version: 2, generated_at: "t", functions: [
+                                     typed_query("q1", "/q/q1", params: [{ "name" => "limit", "required" => false }])
+                                   ])
+          end.not_to raise_error
+        end
+
+        it "is byte-stable: regenerating a typed-query snapshot writes nothing the second pass" do
+          Dir.mktmpdir do |dir|
+            path = File.join(dir, "server-functions.ts")
+            snapshot = { version: 2, generated_at: "t", functions: [
+              typed_query("searchUsers", "/q/searchUsers", params: [
+                            { "name" => "term", "required" => true },
+                            { "name" => "limit", "required" => false }
+                          ])
+            ] }
+            expect(described_class.generate_ts!(snapshot: snapshot, output_path: path)).to be(true)
+            expect(described_class.generate_ts!(snapshot: snapshot, output_path: path)).to be(false)
+          end
+        end
+      end
     end
   end
 end

data/spec/ruact/server_functions/name_bridge_spec.rb

@@ -36,7 +36,7 @@ module Ruact
           expect { described_class.to_js_identifier(:CreatePost) }
             .to raise_error(Ruact::ConfigurationError) do |error|
               expect(error.message).to include(":CreatePost")
-              expect(error.message).to include("ruact_action / ruact_query")
+              expect(error.message).to include("ruact server-function name")
             end
         end
 
@@ -150,10 +150,10 @@ module Ruact
 
         describe "Ruact-reserved names (Story 8.2 review patch R2 — 2026-05-17)", :story_8_2 do
           # The codegen unconditionally re-exports certain runtime helpers
-          # from `@/.ruact/server-functions` (e.g. `revalidate`). A
-          # `ruact_action :revalidate` would emit `export const revalidate`
+          # from `@/.ruact/server-functions` (e.g. `revalidate`). A server
+          # function named `revalidate` would emit `export const revalidate`
           # next to the helper re-export and crash at module load with a
-          # duplicate-export error. Reject at controller load instead.
+          # duplicate-export error. Reject at route-draw instead.
           it "rejects :revalidate because it collides with the unconditional helper re-export" do
             expect { described_class.to_js_identifier(:revalidate) }
               .to raise_error(Ruact::ConfigurationError) do |error|
@@ -170,16 +170,16 @@ module Ruact
             expect(described_class.to_js_identifier(:_revalidate)).to eq("_revalidate")
           end
 
-          it "R12 — rejects :_make_ref because it collides with the codegen's runtime import" do
-            expect { described_class.to_js_identifier(:_make_ref) }
+          it "rejects :_make_server_function because it collides with the codegen's runtime import" do
+            expect { described_class.to_js_identifier(:_make_server_function) }
               .to raise_error(Ruact::ConfigurationError) do |error|
-                expect(error.message).to include(":_make_ref")
+                expect(error.message).to include(":_make_server_function")
                 expect(error.message).to include("duplicate export")
               end
           end
 
-          it "R12 — accepts :_make_ref_action (suffix escape hatch keeps working)" do
-            expect(described_class.to_js_identifier(:_make_ref_action)).to eq("_makeRefAction")
+          it "accepts :_make_ref now that the demolished v1 runtime export is no longer reserved (Story 9.9)" do
+            expect(described_class.to_js_identifier(:_make_ref)).to eq("_makeRef")
           end
 
           # Story 9.5 — `_makeQuery` (the v2 query import) and `useQuery` (the

data/spec/ruact/server_functions/query_source_spec.rb

@@ -19,6 +19,16 @@ module Ruact
       def search_users(term:); end
     end
 
+    # Story 13.4 — kwarg shapes exercising the per-param metadata derivation:
+    # a `**keyrest` (anonymous + named), and a positional that must be ignored.
+    class ParamShapesQ
+      def with_rest(scope:, **opts); end
+
+      def rest_only(**opts); end
+
+      def positional_ignored(id, query:); 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
@@ -82,6 +92,47 @@ module Ruact
           expect(by_id["searchUsers"]["accepts_params"]).to be(true)
         end
 
+        it "derives per-kwarg params metadata (name + required/optional, declaration order)", :story_13_4 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["params"]).to eq([
+                                          { "name" => "term", "required" => true },
+                                          { "name" => "limit", "required" => false }
+                                        ])
+          expect(entry["params_rest"]).to be(false)
+        end
+
+        it "emits empty params + accepts_params false for a no-kwargs query", :story_13_4 do
+          rs = route_set([query_route("#{prefix}catalog_q", "categories", "/q/categories")])
+          entry = described_class.collect(rs, query_class_for: resolver("#{prefix}catalog_q" => CatalogQ)).first
+          expect(entry["params"]).to eq([])
+          expect(entry["params_rest"]).to be(false)
+          expect(entry["accepts_params"]).to be(false)
+        end
+
+        it "flags params_rest for a `**keyrest` and still carries the named keys", :story_13_4 do
+          rs = route_set([query_route("#{prefix}params_q", "with_rest", "/q/withRest")])
+          entry = described_class.collect(rs, query_class_for: resolver("#{prefix}params_q" => ParamShapesQ)).first
+          expect(entry["params"]).to eq([{ "name" => "scope", "required" => true }])
+          expect(entry["params_rest"]).to be(true)
+          expect(entry["accepts_params"]).to be(true)
+        end
+
+        it "treats a `**keyrest`-only query as accepts_params (rest, no named keys)", :story_13_4 do
+          rs = route_set([query_route("#{prefix}params_q", "rest_only", "/q/restOnly")])
+          entry = described_class.collect(rs, query_class_for: resolver("#{prefix}params_q" => ParamShapesQ)).first
+          expect(entry["params"]).to eq([])
+          expect(entry["params_rest"]).to be(true)
+          expect(entry["accepts_params"]).to be(true)
+        end
+
+        it "ignores positional params (only kwargs are FR88 query params)", :story_13_4 do
+          rs = route_set([query_route("#{prefix}params_q", "positional_ignored", "/q/positionalIgnored")])
+          entry = described_class.collect(rs, query_class_for: resolver("#{prefix}params_q" => ParamShapesQ)).first
+          expect(entry["params"]).to eq([{ "name" => "query", "required" => true }])
+          expect(entry["params_rest"]).to be(false)
+        end
+
         it "ignores non-query routes (controller not under the dispatch namespace)" do
           rs = route_set([
                            query_route("posts", "create", "/posts"),