ruact 0.0.5 → 0.0.6

data/lib/ruact/server_functions/codegen.rb

@@ -5,11 +5,16 @@ require "ruact/server_functions/name_bridge"
 
 module Ruact
   module ServerFunctions
-    # Renders the snapshot Hash into the TypeScript module emitted to
-    # `app/javascript/.ruact/server-functions.ts`. Pure string-building plus a
-    # single write-if-changed call.
+    # Renders the route-driven (version-2) snapshot Hash into the TypeScript
+    # module emitted to `app/javascript/.ruact/server-functions.ts`. Pure
+    # string-building plus a single write-if-changed call.
     #
-    # The output of {.render} MUST be byte-identical to the JS-side codegen in
+    # Story 9.9 — the v1 (registry / `_makeRef`) render path was demolished;
+    # {.render} now dispatches only the version-2 (route-driven) shape. The
+    # actual rendering lives in the nested {V2} module (kept separate so the
+    # singleton class stays within its size budget).
+    #
+    # The output of {V2.render} MUST be byte-identical to the JS-side codegen in
     # `gem/vendor/javascript/vite-plugin-ruact/server-functions-codegen.mjs`.
     # The cross-implementation parity test under
     # `gem/vendor/javascript/vite-plugin-ruact/server-functions-codegen.test.mjs`
@@ -22,9 +27,7 @@ module Ruact
 
       # Story 9.3 — the route-driven snapshot schema. A version-2 snapshot
       # carries route-derived entries (`http_method` + `path` + `segments`,
-      # no `ruby_symbol`) and renders `_makeServerFunction(descriptor)` calls
-      # instead of `_makeRef("<sym>")`. {.render} dispatches on `version` so
-      # the v1 (registry-driven) path stays byte-for-byte untouched.
+      # no `ruby_symbol`) and renders `_makeServerFunction(descriptor)` calls.
       VERSION_V2 = 2
 
       RUNTIME_IMPORT = '"ruact/server-functions-runtime"'
@@ -45,13 +48,6 @@ module Ruact
       #      against the codegen-emitted module — no call-site cast, no
       #      wrapper closure.
       #
-      # Runtime behavior is unchanged — `_makeRef` always resolves with the
-      # JSON-decoded value (or `null` for empty bodies). The intersection is
-      # a TYPE-ONLY surface: when callers `await` the result, they see
-      # `Promise<unknown>`; when React invokes the function from a
-      # `<form action>` prop, the `Promise<void>` overload is selected and
-      # the return value is discarded by React.
-      #
       # See the 2026-05-17 entry in `gem/docs/internal/decisions/server-functions-api.md`
       # ("R1 — intersection-type refinement") for the option (a)→(a′)
       # evolution and the empirical typecheck-probe that motivated it.
@@ -66,10 +62,27 @@ module Ruact
       # 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.
+      #
+      # Story 13.4 — {QUERY_PARAMS_SIGNATURE}'s open `Record<string, unknown>`
+      # is now the FALLBACK only: emitted for a pre-13.4 snapshot entry that
+      # carries the `accepts_params` boolean but no structured `params`, and for
+      # a `**keyrest`-only query (open by design). A query whose entry carries
+      # the structured `params` metadata gets a typed object literal built from
+      # the declared keys instead (see {V2.render_query_export}).
       QUERY_PARAMS_SIGNATURE = "(params: Record<string, unknown>) => Promise<unknown>"
 
+      # Story 13.4 — the VALUE type of every typed query param. `Method#parameters`
+      # exposes only names + required/optional (never types or default values),
+      # so per-param scalar precision is not reflection-honest; this is the exact
+      # FR88 query-string wire contract instead (the kwargs sanitizer in
+      # `query_dispatch.rb` accepts only these). Keys and optionality ARE exact,
+      # which is what kills the `Record<string, unknown>`/`any` gap (named keys,
+      # missing-required and unknown-key become compile errors). Per-param scalar
+      # narrowing is deferred to a future explicit param-type DSL.
+      QUERY_PARAM_VALUE_TYPE = "string | number | boolean | null"
+
       # Story 8.2 — fixed re-export appended AFTER the per-function block.
-      # Emitted in BOTH branches (empty + populated registry) so
+      # Emitted in BOTH branches (empty + populated) 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
@@ -86,8 +99,7 @@ module Ruact
       # in JS-identifier terms (leading letter / underscore / `$`, then alnum
       # / underscore / `$`). The codegen validates every entry it consumes
       # because the JSON bridge is a trust boundary — a malformed snapshot
-      # (`functions[].js_identifier == ");\nevil();_makeRef("foo`) would
-      # otherwise inject TS at module top level.
+      # would otherwise inject TS at module top level.
       VALID_JS_IDENTIFIER = /\A[A-Za-z_$][A-Za-z0-9_$]*\z/
 
       ALLOWED_KINDS = %w[action query].freeze
@@ -95,24 +107,21 @@ module Ruact
       # JS comments (both `//` line comments and `/* … */` block comments via
       # the spec's LineTerminator production) end on LF, CR, U+2028, and U+2029.
       # A snapshot value that smuggles any of these would break out of the
-      # leading comment header in the emitted module. The reviewer's Pass-2
-      # finding noted that an earlier `/[\r\n]/` guard missed the two Unicode
-      # line separators; the regex is widened here and a parity test in
-      # `server-functions-codegen.test.mjs` keeps both renderers in sync.
-      LINE_TERMINATORS = /[\r\n

]/
+      # leading comment header in the emitted module. The regex covers both
+      # Unicode line separators (written as explicit escapes); a parity test
+      # keeps both renderers in sync.
+      LINE_TERMINATORS = /[\r\n\u2028\u2029]/
 
       class << self
-        # Renders +snapshot+ into the TS module text. Pure; no I/O.
+        # Renders +snapshot+ into the TS module text. Pure; no I/O. Story 9.9 —
+        # only the route-driven (version-2) shape is supported.
         #
-        # @param snapshot [Hash] result of {Ruact::ServerFunctions::Snapshot.dump};
-        #   must contain `:version`, `:generated_at`, `:functions` (with string-keyed
-        #   entries).
+        # @param snapshot [Hash] result of {Snapshot.dump_v2}; must contain
+        #   `:version`, `:generated_at`, `:functions` (string-keyed entries).
         # @return [String] TS module bytes, terminated by a single trailing newline.
-        # @raise [Ruact::ConfigurationError] when an entry fails any of the
-        #   snapshot-trust-boundary guards (line-break in version /
-        #   generated_at, invalid identifier shape, reserved JS word, kind
-        #   outside {ALLOWED_KINDS}, or duplicate `js_identifier` — mirror of
-        #   the JS-side `validateSnapshot` per the 2026-05-14 Re-run patch).
+        # @raise [Ruact::ConfigurationError] on a non-Hash snapshot, a missing
+        #   required key, a non-v2 `version`, or any trust-boundary violation in
+        #   {V2.render}.
         def render(snapshot)
           unless snapshot.is_a?(Hash)
             raise Ruact::ConfigurationError,
@@ -125,41 +134,15 @@ module Ruact
 
           validate_metadata!(version, generated_at)
 
-          return V2.render(version, generated_at, functions) if version.to_s == VERSION_V2.to_s
-
-          validate_functions!(functions)
-
-          io = +""
-          io << "// AUTO-GENERATED by vite-plugin-ruact (Story 8.0a). DO NOT EDIT.\n"
-          io << "// Source: tmp/cache/ruact/server-functions.json (version #{version})\n"
-          io << "// Generated at: #{generated_at}\n"
-          io << "import { _makeRef } from #{RUNTIME_IMPORT};\n"
-
-          if functions.empty?
-            io << "\n// (no server functions registered yet — Stories 8.1 / 9.1 populate)\n"
-            # `noUnusedLocals` would otherwise flag the `_makeRef` import. The
-            # `void` discard pattern keeps the import alive at zero runtime
-            # cost; once an action/query is registered the export below
-            # references `_makeRef` directly and this line is omitted.
-            io << "void _makeRef;\n"
-          else
-            io << "\n"
-            functions.each do |entry|
-              io << render_export(entry)
-            end
+          unless version.to_s == VERSION_V2.to_s
+            raise Ruact::ConfigurationError,
+                  "ruact server-function codegen: unsupported snapshot version " \
+                  "#{version.inspect} (only the route-driven version #{VERSION_V2} is " \
+                  "supported as of Story 9.9); the bridge JSON is corrupted — " \
+                  "regenerate via `bin/rails ruact:server_functions:generate`."
           end
 
-          # Story 8.2 — `revalidate()` is always available, so the
-          # re-export lands in both branches (empty registry + populated).
-          # The codegen owns the canonical import path
-          # `@/.ruact/server-functions` and is the only stable surface devs
-          # are told to import from in the docs (per the Story 8.0 ADR);
-          # without this line, devs would need a second import statement
-          # from a less-stable runtime-package path.
-          io << "\n"
-          io << REVALIDATE_REEXPORT
-
-          io
+          V2.render(version, generated_at, functions)
         end
 
         # Writes the rendered TS module to +output_path+, only if it changed.
@@ -174,19 +157,8 @@ module Ruact
 
         private
 
-        def render_export(entry)
-          js_id    = entry["js_identifier"] || entry[:js_identifier]
-          kind     = (entry["kind"] || entry[:kind]).to_s
-          ruby_sym = entry["ruby_symbol"] || entry[:ruby_symbol]
-
-          signature = kind == "query" ? QUERY_SIGNATURE : ACTION_SIGNATURE
-
-          "export const #{js_id}: #{signature} =\n  _makeRef(#{json_escape(ruby_sym.to_s)});\n"
-        end
-
-        # Pass-2 patch 2026-05-14 — wrap raw `KeyError` from `Hash#fetch` so
-        # the rake / Railtie call sites get a consistent `Ruact::ConfigurationError`
-        # for every snapshot-shape failure, not a mixture of error classes.
+        # Wraps raw `KeyError` from `Hash#fetch` so call sites get a consistent
+        # `Ruact::ConfigurationError` for every snapshot-shape failure.
         def fetch_snapshot_key!(snapshot, sym_key, str_key)
           return snapshot[sym_key] if snapshot.key?(sym_key)
           return snapshot[str_key] if snapshot.key?(str_key)
@@ -197,10 +169,6 @@ module Ruact
                 "corrupted — regenerate via `bin/rails ruact:server_functions:generate`."
         end
 
-        # Mirror of the JS-side `validateSnapshot` (2026-05-14 Re-run parity
-        # fix). The Ruby renderer also reads from the on-disk JSON bridge in
-        # the rake-task and Railtie paths, so the same trust-boundary guards
-        # belong here.
         def validate_metadata!(version, generated_at)
           unless version.is_a?(Integer) || version.is_a?(String)
             raise Ruact::ConfigurationError,
@@ -226,113 +194,6 @@ module Ruact
                 "a line break (LF, CR, U+2028, or U+2029) — would break out of " \
                 "the header comment; snapshot JSON is corrupted."
         end
-
-        def validate_functions!(functions)
-          unless functions.is_a?(Array)
-            raise Ruact::ConfigurationError,
-                  "ruact server-function codegen: snapshot.functions must be an " \
-                  "Array, got #{functions.class}"
-          end
-
-          seen = {}
-          functions.each do |entry|
-            unless entry.is_a?(Hash)
-              raise Ruact::ConfigurationError,
-                    "ruact server-function codegen: snapshot.functions entry is " \
-                    "not a Hash: #{entry.inspect}"
-            end
-            js_id    = entry["js_identifier"] || entry[:js_identifier]
-            kind     = (entry["kind"] || entry[:kind]).to_s
-            ruby_sym = entry["ruby_symbol"] || entry[:ruby_symbol]
-
-            validate_ruby_symbol!(ruby_sym)
-            validate_js_identifier!(js_id, ruby_sym)
-            validate_kind!(kind, ruby_sym)
-            validate_not_reserved!(js_id, ruby_sym)
-            validate_no_duplicate!(seen, js_id)
-            seen[js_id] = true
-          end
-        end
-
-        # Pass-2 patch 2026-05-14 — without this guard, a missing or empty
-        # `ruby_symbol` on a snapshot entry would render `_makeRef("")` and
-        # silently emit an export that can never resolve at runtime (the
-        # placeholder rejects on call but the empty string is a meaningless
-        # registration name). Treat as a corrupt-snapshot signal.
-        def validate_ruby_symbol!(ruby_sym)
-          return if ruby_sym.is_a?(String) && !ruby_sym.empty?
-          return if ruby_sym.is_a?(Symbol) && !ruby_sym.empty?
-
-          raise Ruact::ConfigurationError,
-                "ruact server-function codegen: snapshot.functions entry has " \
-                "missing or empty ruby_symbol (got #{ruby_sym.inspect}); the " \
-                "bridge JSON is corrupted — regenerate via " \
-                "`bin/rails ruact:server_functions:generate`."
-        end
-
-        def validate_js_identifier!(js_id, ruby_sym)
-          return if js_id.is_a?(String) && js_id.match?(VALID_JS_IDENTIFIER)
-
-          raise Ruact::ConfigurationError,
-                "ruact server-function codegen rejected a snapshot entry: " \
-                "ruby_symbol=#{ruby_sym.inspect} js_identifier=#{js_id.inspect} " \
-                "is not a valid JS identifier (must match #{VALID_JS_IDENTIFIER.inspect}). " \
-                "The snapshot JSON is corrupted or was hand-edited — regenerate via " \
-                "`bin/rails ruact:server_functions:generate`."
-        end
-
-        def validate_kind!(kind, ruby_sym)
-          return if ALLOWED_KINDS.include?(kind)
-
-          raise Ruact::ConfigurationError,
-                "ruact server-function codegen: snapshot.functions entry has " \
-                "invalid kind #{kind.inspect} (must be \"action\" or \"query\") " \
-                "for ruby_symbol=#{ruby_sym.inspect}"
-        end
-
-        def validate_not_reserved!(js_id, ruby_sym)
-          if NameBridge::RESERVED_JS_IDENTIFIERS.include?(js_id)
-            raise Ruact::ConfigurationError,
-                  "ruact server-function codegen: js_identifier #{js_id.inspect} " \
-                  "is a reserved JS word — ruby_symbol=#{ruby_sym.inspect} would " \
-                  "emit an invalid TS module. NameBridge should have rejected this; " \
-                  "regenerate via `bin/rails ruact:server_functions:generate`."
-          end
-
-          # Story 8.2 R12 — even if NameBridge somehow lets a reserved
-          # ruact name through (e.g. a hand-edited bridge JSON), the
-          # codegen MUST refuse — otherwise the rendered module would
-          # bind `revalidate` / `_makeRef` twice (once via the
-          # re-export / import, once via the action `export const`)
-          # and crash at module load.
-          return unless NameBridge::RESERVED_BY_RUACT.include?(js_id)
-
-          raise Ruact::ConfigurationError,
-                "ruact server-function codegen: js_identifier #{js_id.inspect} " \
-                "is reserved by the ruact runtime/codegen surface (would clash " \
-                "with the module's `revalidate` re-export or `_makeRef` import) — " \
-                "ruby_symbol=#{ruby_sym.inspect} cannot be exported. NameBridge " \
-                "should have rejected this; regenerate via " \
-                "`bin/rails ruact:server_functions:generate`."
-        end
-
-        def validate_no_duplicate!(seen, js_id)
-          return unless seen.key?(js_id)
-
-          raise Ruact::ConfigurationError,
-                "ruact server-function codegen: duplicate js_identifier " \
-                "#{js_id.inspect} in snapshot — two entries would emit " \
-                "conflicting `export const` declarations. The snapshot JSON is " \
-                "corrupted or was hand-edited — regenerate via " \
-                "`bin/rails ruact:server_functions:generate`."
-        end
-
-        # Wraps `ruby_symbol` in a JSON-escaped string literal so backslashes,
-        # double quotes, and control characters cannot break out of the
-        # `_makeRef("<here>")` argument.
-        def json_escape(str)
-          JSON.dump(str)
-        end
       end
     end
   end

data/lib/ruact/server_functions/codegen_v2.rb

@@ -25,8 +25,8 @@ module Ruact
 
         # 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.
+        # 2026-06-02 ADR addendum restored HTTP GET semantics for queries, so a
+        # query entry is GET-only.
         QUERY_HTTP_METHODS = %w[GET].to_set.freeze
 
         class << self
@@ -87,13 +87,19 @@ module Ruact
 
           # 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).
+          # consumes it — 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
+            # Story 13.4 — the typed `params` signature (or the back-compat
+            # fallback) is built by {QueryParams}, kept separate so this
+            # singleton class stays within its size budget.
+            signature = QueryParams.signature(
+              params: fetch(entry, "params"),
+              params_rest: fetch(entry, "params_rest"),
+              accepts_params: fetch(entry, "accepts_params")
+            )
 
             descriptor = "{ path: #{JSON.dump(path)}, kind: \"query\" }"
             "export const #{js_id}: #{signature} =\n  _makeQuery(#{descriptor});\n"
@@ -123,6 +129,11 @@ module Ruact
             path = fetch(entry, "path")
             validate_path!(js_id, path)
             validate_segments!(js_id, path, fetch(entry, "segments"))
+            # Story 13.4 — the structured query `params` metadata is a trust
+            # boundary (it becomes TS object keys); {QueryParams} rejects a
+            # malformed/corrupted snapshot rather than emit injected — or
+            # silently over-widened — TS.
+            QueryParams.validate!(js_id, fetch(entry, "params"), fetch(entry, "params_rest")) if kind == "query"
             seen[js_id] = true
           end
 
@@ -210,3 +221,9 @@ module Ruact
     end
   end
 end
+
+# Story 13.4 — the typed query `params` signature builder + its trust-boundary
+# validation, kept in their own module so {V2}'s singleton class stays within
+# its size budget (same split rationale as V2 itself vs {Codegen}). Required
+# after V2 + the signature constants are defined; consumed by V2 above.
+require_relative "codegen_v2_query_params"

data/lib/ruact/server_functions/codegen_v2_query_params.rb

@@ -0,0 +1,140 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Ruact
+  module ServerFunctions
+    module Codegen
+      module V2
+        # Story 13.4 (FR99) — builds the TYPED query accessor `params` signature
+        # from the per-kwarg metadata {QuerySource} derives, and validates that
+        # metadata as a trust boundary. Extracted from {V2} for the same reason
+        # {V2} was extracted from {Codegen}: keep each singleton class within its
+        # size budget. Constants ({QUERY_SIGNATURE}, {QUERY_PARAMS_SIGNATURE},
+        # {QUERY_PARAM_VALUE_TYPE}, {VALID_JS_IDENTIFIER}, {LINE_TERMINATORS}) are
+        # reached from {Codegen} via lexical scope.
+        #
+        # MUST stay byte-identical to the JS-side `querySignatureV2` /
+        # `validateQueryParams` in
+        # `gem/vendor/javascript/vite-plugin-ruact/server-functions-codegen.mjs`.
+        module QueryParams
+          class << self
+            # Picks the query accessor's `params` signature.
+            #
+            # When +params+ is an Array (the Story 13.4 structured metadata),
+            # build a typed object literal — one property per declared keyword,
+            # required/optional exact, value type the FR88 wire union (AC1).
+            # Empty params + no `**keyrest` → the bare {QUERY_SIGNATURE}
+            # (byte-identical to a no-kwargs query). A `**keyrest` keeps the open
+            # `Record<string, unknown>` (intersected with any named keys) so a
+            # legitimate dynamic key is never narrowed away (fail open).
+            #
+            # Falls back to the pre-13.4 +accepts_params+ boolean when no
+            # +params+ metadata is present (an older or hand-written snapshot)
+            # so no consumer breaks.
+            #
+            # @param params [Array<Hash>, nil] per-kwarg `{ "name", "required" }`.
+            # @param params_rest [Boolean, nil] whether a `**keyrest` is declared.
+            # @param accepts_params [Boolean, nil] the back-compat fallback flag.
+            # @return [String] the TS signature.
+            def signature(params:, params_rest:, accepts_params:)
+              return fallback(accepts_params) unless params.is_a?(Array)
+
+              rest = params_rest ? true : false
+              return QUERY_SIGNATURE if params.empty? && !rest
+
+              build(params, rest)
+            end
+
+            # Validates the structured `params` metadata. Reject a malformed or
+            # corrupted snapshot loudly rather than emit broken — or silently
+            # over-widened — TS. Absent `params`/`params_rest` is valid (the
+            # {signature} fallback handles it).
+            #
+            # @param js_id [String]
+            # @param params [Array<Hash>, nil]
+            # @param params_rest [Object, nil] expected Boolean or nil; a
+            #   non-Boolean truthy value would otherwise silently flip a query to
+            #   the open `& Record<string, unknown>` shape (Story 13.4 review R1).
+            # @raise [Ruact::ConfigurationError]
+            def validate!(js_id, params, params_rest = nil)
+              validate_rest!(js_id, params_rest)
+              return if params.nil?
+
+              unless params.is_a?(Array)
+                raise Ruact::ConfigurationError,
+                      "ruact server-function codegen: v2 query entry #{js_id.inspect} has invalid " \
+                      "params #{params.inspect} (must be an Array of { name, required } objects)."
+              end
+              params.each { |param| validate_entry!(js_id, param) }
+            end
+
+            private
+
+            def validate_rest!(js_id, params_rest)
+              return if params_rest.nil? || params_rest == true || params_rest == false
+
+              raise Ruact::ConfigurationError,
+                    "ruact server-function codegen: v2 query entry #{js_id.inspect} has a non-Boolean " \
+                    "params_rest #{params_rest.inspect}; snapshot JSON is corrupted."
+            end
+
+            def fallback(accepts_params)
+              accepts_params ? QUERY_PARAMS_SIGNATURE : QUERY_SIGNATURE
+            end
+
+            # Builds `(params: { q: <UNION>; limit?: <UNION> }) => Promise<unknown>`
+            # in declaration order. A `**keyrest`-only query (no named keys)
+            # reuses the open {QUERY_PARAMS_SIGNATURE}; with named keys present
+            # the rest is an intersection so the named keys still autocomplete.
+            def build(params, rest)
+              props = params.map do |param|
+                name = param["name"] || param[:name]
+                required = param.key?("required") ? param["required"] : param[:required]
+                optional = required ? "" : "?"
+                "#{format_key(name)}#{optional}: #{QUERY_PARAM_VALUE_TYPE}"
+              end
+
+              return QUERY_PARAMS_SIGNATURE if props.empty? # keyrest-only
+
+              object = "{ #{props.join('; ')} }"
+              object += " & Record<string, unknown>" if rest
+              "(params: #{object}) => Promise<unknown>"
+            end
+
+            # Kwarg names are Ruby symbols → almost always valid bare TS keys;
+            # quote (via JSON) any that are not so a corrupted snapshot cannot
+            # break out of the object literal. Mirrors the JS `formatParamKey`.
+            def format_key(name)
+              name.to_s.match?(VALID_JS_IDENTIFIER) ? name.to_s : JSON.dump(name.to_s)
+            end
+
+            def validate_entry!(js_id, param)
+              unless param.is_a?(Hash)
+                raise Ruact::ConfigurationError,
+                      "ruact server-function codegen: v2 query entry #{js_id.inspect} has a params " \
+                      "element that is not an object: #{param.inspect}; snapshot JSON is corrupted."
+              end
+
+              name = param["name"] || param[:name]
+              unless name.is_a?(String) && !name.empty? && !name.match?(LINE_TERMINATORS)
+                raise Ruact::ConfigurationError,
+                      "ruact server-function codegen: v2 query entry #{js_id.inspect} has a params " \
+                      "name #{name.inspect} that is not a non-empty single-line String; snapshot JSON is corrupted."
+              end
+
+              # Presence-aware (a plain `||` would mis-read a legitimate
+              # `required: false` as the absent key).
+              required = param.key?("required") ? param["required"] : param[:required]
+              return if [true, false].include?(required)
+
+              raise Ruact::ConfigurationError,
+                    "ruact server-function codegen: v2 query entry #{js_id.inspect} params name " \
+                    "#{name.inspect} has a non-Boolean `required` #{required.inspect}; snapshot JSON is corrupted."
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ruact/server_functions/error_payload.rb

@@ -6,7 +6,7 @@ require_relative "error_suggestion"
 module Ruact
   module ServerFunctions
     # Story 8.4 — Builds the structured JSON body returned by
-    # {EndpointController#__ruact_render_action_error} for any server-action
+    # {ErrorRendering#__ruact_render_action_error} for any server-action
     # exception that bubbles past a host's `rescue_from` chain.
     #
     # The function is pure (no `Rails.env`, no `Ruact.config` reads) — the

data/lib/ruact/server_functions/error_rendering.rb

@@ -4,33 +4,23 @@ require_relative "error_payload"
 
 module Ruact
   module ServerFunctions
-    # Story 9.1 — the shared salvage core for the Story 8.4 structured-error
-    # rendering and the Story 8.5 upload guard. Extracted from
-    # {EndpointController} so the SAME implementation serves both homes during
-    # the strangler-fig transition:
+    # Story 9.1 — the shared core for the Story 8.4 structured-error rendering
+    # and the Story 8.5 upload guard, included by {Ruact::Server} (the
+    # route-driven concern hosts include). Story 9.9 demolished the v1 endpoint
+    # that previously shared this code, so {Ruact::Server} is now the sole home.
     #
-    #   - {EndpointController} (v1 — synthetic `POST /__ruact/fn/:name`
-    #     endpoint; removed by Story 9.9)
-    #   - {Ruact::Server} (v2 — the route-driven concern hosts include)
-    #
-    # Keeping one source guarantees the 8.4/8.5 wire contract is byte-for-byte
-    # identical across both homes by construction; behavioral differences are
-    # expressed exclusively through the three private hooks below, which each
-    # home may override:
+    # Behavioral specialization is expressed through three private hooks, which
+    # the including controller may override:
     #
     #   - {#__ruact_error_action_name} — where the payload's `action_name`
-    #     comes from. Default: the controller's own `action_name` (correct for
-    #     v2 host controllers). The v1 endpoint overrides it with its
-    #     registry-symbol / `path_parameters[:name]` fallback chain.
+    #     comes from. Default: the controller's own `action_name`.
     #   - {#__ruact_render_structured_error?} — whether the rescue handler
     #     renders the structured JSON payload for this request, or re-raises so
-    #     Rails' default error handling proceeds. Default: always render
-    #     (v1 endpoint semantics — every request there is a function call).
-    #     {Ruact::Server} gates this on the function-call predicate.
-    #   - {#__ruact_upload_guard_applicable?} — whether the upload guard
-    #     applies to this request at all. Default: always (the v1 endpoint is
-    #     POST-only). {Ruact::Server} skips GET/HEAD so page actions stay
-    #     byte-for-byte untouched.
+    #     Rails' default error handling proceeds. {Ruact::Server} gates this on
+    #     its function-call predicate.
+    #   - {#__ruact_upload_guard_applicable?} — whether the upload guard applies
+    #     to this request at all. {Ruact::Server} skips GET/HEAD so page actions
+    #     stay byte-for-byte untouched.
     #
     # All methods are private on the including controller; nothing here is
     # public API surface.
@@ -98,28 +88,31 @@ module Ruact
       end
 
       # Hook — where the structured payload's `action_name` field comes from.
-      # The controller's own `action_name` is correct for v2 host controllers
+      # The controller's own `action_name` is correct for host controllers
       # (it is populated by routing before any callback runs, including the
       # prepended upload guard — no early-rejection fallback dance needed).
       def __ruact_error_action_name
         action_name
       end
 
-      # Hook — render the structured payload for this request? The v1
-      # endpoint's answer is "always" (every request hitting
-      # `POST /__ruact/fn/:name` is a function call by construction).
+      # Hook — render the structured payload for this request? The default is
+      # "always"; {Ruact::Server} overrides it to gate on its function-call
+      # predicate (page/Flight requests re-raise so Rails' default error
+      # handling proceeds untouched).
       def __ruact_render_structured_error?(_error)
         true
       end
 
-      # Hook — does the upload guard apply to this request? The v1 endpoint's
-      # answer is "always" (the route is POST-only).
+      # Hook — does the upload guard apply to this request? The default is
+      # "always"; {Ruact::Server} overrides it to skip GET/HEAD.
       def __ruact_upload_guard_applicable?
         true
       end
 
       # Story 8.4 — Status mapping per AC1:
       # - `Ruact::BadRequestError` → 400 (Story 9.5 — FR88 kwargs rejection)
+      # - `Ruact::InvalidSignedGlobalIDError` → 400 (Story 13.2 — FR96 forged/
+      #   expired/wrong-purpose signed reference; an invalid client credential)
       # - `ActiveRecord::RecordInvalid` → 422
       # - `ActionController::InvalidAuthenticityToken` → 403
       # - `Ruact::UploadTooLargeError` → 413
@@ -128,7 +121,7 @@ module Ruact
       # at load time (parity with {ErrorSuggestion}).
       def __ruact_status_for(error)
         case error.class.name
-        when "Ruact::BadRequestError" then 400
+        when "Ruact::BadRequestError", "Ruact::InvalidSignedGlobalIDError" then 400
         when "ActiveRecord::RecordInvalid" then 422
         when "ActionController::InvalidAuthenticityToken" then 403
         when "Ruact::UploadTooLargeError" then 413