ruact 0.0.1 → 0.0.3

data/lib/ruact/server_functions/bucket_two_payload.rb

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+require "date"
+require_relative "../serializable"
+require_relative "../errors"
+
+module Ruact
+  module ServerFunctions
+    # Story 9.2 — pure serializer for the Bucket-2 (imperative `await fn()`)
+    # response body. Takes the host action's exposed instance variables (Rails
+    # `view_assigns`, resolved by the caller) and produces a JSON-ready Ruby
+    # Hash, keyed by ivar name, applying the SAME prop-exposure policy as the
+    # Flight serializer ({Ruact::Flight::Serializer#serialize_unknown}):
+    #
+    #   - {Ruact::Serializable} values expose ONLY their `ruact_props` (secrets
+    #     never leak), recursing into nested Serializables / collections.
+    #   - Under `strict_serialization`, a non-Serializable domain object raises
+    #     {Ruact::SerializationError} (no accidental full-record dump).
+    #   - Otherwise a vetted `as_json` fallback applies (guards against
+    #     `as_json` returning self / raising).
+    #
+    # Unlike the Flight serializer this produces PLAIN JSON-ready values (Hash /
+    # Array / scalar) — `render json:` does the final encoding, so JSON
+    # primitives (incl. Time/Date) pass through untouched rather than being
+    # Flight-encoded.
+    #
+    # Pure — no Rails / request / `Ruact.config` reads. The caller resolves the
+    # exposed-ivar set and the `strict` flag (mirroring the {ErrorPayload}
+    # caller/builder split, NFR26 / AC8).
+    module BucketTwoPayload
+      # JSON scalar + date/time primitives pass through untouched (Rails'
+      # `render json:` renders them — e.g. Time → ISO8601). They are NOT
+      # subject to the strict prop-exposure policy, matching the Flight
+      # serializer's primitive handling.
+      PRIMITIVES = [NilClass, TrueClass, FalseClass, Numeric, String, Symbol, Time, Date, DateTime].freeze
+      private_constant :PRIMITIVES
+
+      class << self
+        # @param assigns [Hash] exposed-ivar name (String, no `@`) => value
+        # @param strict [Boolean] the resolved `strict_serialization` mode
+        # @return [Hash{String=>Object}] JSON-ready hash keyed by ivar name
+        # @raise [Ruact::SerializationError] per the strict policy
+        def build(assigns, strict:)
+          assigns.to_h { |name, value| [name.to_s, serialize(value, strict)] }
+        end
+
+        # Story 9.4 (D6) — the per-value branch of the policy, extracted so the
+        # query dispatch controller serializes a method's single RETURN VALUE
+        # (Array / Hash / scalar / Serializable / nil) through the exact rules
+        # {.build} applies to each exposed ivar. One policy, two callers.
+        #
+        # @param value [Object] the query method's return value
+        # @param strict [Boolean] the resolved `strict_serialization` mode
+        # @return [Object] JSON-ready value (`nil` stays `nil` → JSON `null`)
+        # @raise [Ruact::SerializationError] per the strict policy
+        def serialize_value(value, strict:)
+          serialize(value, strict)
+        end
+
+        private
+
+        def serialize(value, strict)
+          case value
+          when *PRIMITIVES         then value
+          when Hash                then value.to_h { |k, v| [k.to_s, serialize(v, strict)] }
+          when Array               then value.map { |v| serialize(v, strict) }
+          when Ruact::Serializable then serialize(value.ruact_serialize, strict)
+          else serialize_object(value, strict)
+          end
+        end
+
+        # Non-Serializable, non-primitive object: mirror
+        # Flight::Serializer#serialize_unknown's strict/as_json policy.
+        def serialize_object(value, strict)
+          unless value.respond_to?(:as_json)
+            raise Ruact::SerializationError,
+                  "Cannot serialize #{value.class.name} — include Ruact::Serializable"
+          end
+
+          if strict
+            raise Ruact::SerializationError,
+                  "Cannot serialize #{value.class.name} — " \
+                  "include Ruact::Serializable or set strict_serialization: false"
+          end
+
+          serialize(as_json_value(value), strict)
+        end
+
+        def as_json_value(value)
+          data =
+            begin
+              value.as_json
+            rescue StandardError => e
+              raise Ruact::SerializationError,
+                    "#{value.class.name}#as_json raised #{e.class}: #{e.message}"
+            end
+
+          if data.equal?(value)
+            raise Ruact::SerializationError,
+                  "#{value.class.name}#as_json returned self — would cause infinite recursion. " \
+                  "Include Ruact::Serializable and declare ruact_props instead"
+          end
+
+          data
+        end
+      end
+    end
+  end
+end

data/lib/ruact/server_functions/codegen.rb

@@ -0,0 +1,330 @@
+# frozen_string_literal: true
+
+require "json"
+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.
+    #
+    # The output of {.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`
+    # asserts this invariant; if it fails, fix the offending side rather than
+    # normalizing in the assertion (Story 8.0a Task 8.5).
+    module Codegen
+      # Bumped only when the rendered shape changes. Used by tests to assert
+      # cross-implementation parity without coupling to the literal byte string.
+      VERSION = 1
+
+      # 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.
+      VERSION_V2 = 2
+
+      RUNTIME_IMPORT = '"ruact/server-functions-runtime"'
+
+      # Story 8.2 (2026-05-16, refined 2026-05-17 per review patch R1) —
+      # ACTION_SIGNATURE is a TS intersection type with TWO call signatures:
+      #
+      #   1. `(args?: FormData | Record<string, unknown>) => Promise<unknown>`
+      #      — for direct callers (`await createPost({...})` /
+      #      `await createPost(formData)` / event handlers), preserving the
+      #      JSON-decoded response value.
+      #   2. `(formData: FormData) => Promise<void>` — assignable to
+      #      `@types/react@19.x`'s `<form action>` prop, which is typed as
+      #      `(formData: FormData) => void | Promise<void>`. TS rejects
+      #      `Promise<unknown>` → `Promise<void>` even via the void-discard
+      #      rule (Promise generics are invariant), so the intersection is
+      #      required to make `<form action={createPost}>` typecheck DIRECTLY
+      #      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.
+      # Query signatures stay narrow because queries are never reachable via
+      # `<form action>` (read-only via `useQuery`).
+      ACTION_SIGNATURE =
+        "((args?: FormData | Record<string, unknown>) => Promise<unknown>) " \
+        "& ((formData: FormData) => Promise<void>)"
+      QUERY_SIGNATURE  = "() => Promise<unknown>"
+
+      # Story 8.2 — fixed re-export appended AFTER the per-function block.
+      # Emitted in BOTH branches (empty + populated registry) so
+      # `import { revalidate } from "@/.ruact/server-functions"` works on
+      # day one of any host app. Ruby + JS codegens emit byte-identically.
+      REVALIDATE_REEXPORT = "export { revalidate } from #{RUNTIME_IMPORT};\n".freeze
+
+      # JS identifier shape — same as `NameBridge::VALID_SYMBOL` but expressed
+      # in JS-identifier terms (leading letter / underscore / `$`, then alnum
+      # / underscore / `$`). The codegen validates every entry it consumes
+      # 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.
+      VALID_JS_IDENTIFIER = /\A[A-Za-z_$][A-Za-z0-9_$]*\z/
+
+      ALLOWED_KINDS = %w[action query].freeze
+
+      # 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

]/
+
+      class << self
+        # Renders +snapshot+ into the TS module text. Pure; no I/O.
+        #
+        # @param snapshot [Hash] result of {Ruact::ServerFunctions::Snapshot.dump};
+        #   must contain `:version`, `:generated_at`, `:functions` (with 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).
+        def render(snapshot)
+          unless snapshot.is_a?(Hash)
+            raise Ruact::ConfigurationError,
+                  "ruact server-function codegen: snapshot must be a Hash, got #{snapshot.class}"
+          end
+
+          version      = fetch_snapshot_key!(snapshot, :version, "version")
+          generated_at = fetch_snapshot_key!(snapshot, :generated_at, "generated_at")
+          functions    = fetch_snapshot_key!(snapshot, :functions, "functions")
+
+          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
+          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
+        end
+
+        # Writes the rendered TS module to +output_path+, only if it changed.
+        # See {Ruact::ServerFunctions::SnapshotWriter.write_if_changed!}.
+        #
+        # @param snapshot [Hash]
+        # @param output_path [String, Pathname]
+        # @return [Boolean] true if the file was written; false if unchanged.
+        def generate_ts!(snapshot:, output_path:)
+          SnapshotWriter.write_if_changed!(path: output_path, content: render(snapshot))
+        end
+
+        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.
+        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)
+
+          raise Ruact::ConfigurationError,
+                "ruact server-function codegen: snapshot is missing required key " \
+                "#{sym_key.inspect} (or #{str_key.inspect}); the bridge JSON is " \
+                "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,
+                  "ruact server-function codegen: snapshot.version must be an " \
+                  "Integer or String, got #{version.class}"
+          end
+          if version.to_s.match?(LINE_TERMINATORS)
+            raise Ruact::ConfigurationError,
+                  "ruact server-function codegen: snapshot.version contains a " \
+                  "line break (LF, CR, U+2028, or U+2029) — would break out of " \
+                  "the header comment; snapshot JSON is corrupted."
+          end
+
+          unless generated_at.is_a?(String)
+            raise Ruact::ConfigurationError,
+                  "ruact server-function codegen: snapshot.generated_at must be " \
+                  "a String, got #{generated_at.class}"
+          end
+          return unless generated_at.match?(LINE_TERMINATORS)
+
+          raise Ruact::ConfigurationError,
+                "ruact server-function codegen: snapshot.generated_at contains " \
+                "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
+end
+
+# Story 9.3 — the route-driven (version-2) renderer lives in its own module so
+# the v1 singleton class stays within its size budget. Required after the
+# constants above are defined; `Codegen.render` delegates to it on version 2.
+require_relative "codegen_v2"

data/lib/ruact/server_functions/codegen_v2.rb

@@ -0,0 +1,176 @@
+# frozen_string_literal: true
+
+require "json"
+require "ruact/server_functions/name_bridge"
+
+module Ruact
+  module ServerFunctions
+    module Codegen
+      # Story 9.3 — renders a version-2 (route-driven) snapshot into the TS
+      # module. Each entry is an action targeting a real path + verb, emitted as
+      # `_makeServerFunction({ method, path, segments })` instead of v1's
+      # `_makeRef("<sym>")`. Lives in its own module (nested in {Codegen}) so the
+      # v1 singleton class stays within its size budget; {Codegen.render}
+      # delegates here when `snapshot.version == 2`.
+      #
+      # The output MUST stay byte-identical to the JS-side `renderV2` in
+      # `gem/vendor/javascript/vite-plugin-ruact/server-functions-codegen.mjs`;
+      # the parity test ("Story 9.3 — route-driven (v2) render + parity") asserts
+      # this. Constants (ACTION_SIGNATURE, RUNTIME_IMPORT, REVALIDATE_REEXPORT,
+      # LINE_TERMINATORS, VALID_JS_IDENTIFIER) are reused from {Codegen} via
+      # lexical scope.
+      module V2
+        # Verbs a v2 entry may carry (mirrors {RouteSource::MUTATION_VERBS}).
+        HTTP_METHODS = %w[POST PUT PATCH DELETE].to_set.freeze
+
+        class << self
+          # @param version [Integer, String]
+          # @param generated_at [String]
+          # @param functions [Array<Hash>] route-derived entries.
+          # @return [String] TS module bytes (single trailing newline).
+          # @raise [Ruact::ConfigurationError] on any trust-boundary violation.
+          def render(version, generated_at, functions)
+            validate_functions!(functions)
+
+            io = +""
+            io << "// AUTO-GENERATED by vite-plugin-ruact (Story 9.3). DO NOT EDIT.\n"
+            io << "// Source: Rails route table (version #{version})\n"
+            io << "// Generated at: #{generated_at}\n"
+            io << "import { _makeServerFunction } from #{RUNTIME_IMPORT};\n"
+
+            if functions.empty?
+              io << "\n// (no server functions exposed yet — add a non-GET route on a Ruact::Server controller)\n"
+              io << "void _makeServerFunction;\n"
+            else
+              io << "\n"
+              functions.each { |entry| io << render_export(entry) }
+            end
+
+            io << "\n"
+            io << REVALIDATE_REEXPORT
+            io
+          end
+
+          private
+
+          def render_export(entry)
+            js_id = fetch(entry, "js_identifier")
+            method = fetch(entry, "http_method")
+            path = fetch(entry, "path")
+            segments = fetch(entry, "segments") || []
+
+            descriptor =
+              "{ method: #{JSON.dump(method)}, path: #{JSON.dump(path)}, " \
+              "segments: [#{segments.map { |s| JSON.dump(s) }.join(', ')}] }"
+
+            "export const #{js_id}: #{ACTION_SIGNATURE} =\n  _makeServerFunction(#{descriptor});\n"
+          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 { |entry| validate_entry!(entry, seen) }
+          end
+
+          def validate_entry!(entry, seen)
+            unless entry.is_a?(Hash)
+              raise Ruact::ConfigurationError,
+                    "ruact server-function codegen: snapshot.functions entry is not a Hash: #{entry.inspect}"
+            end
+
+            js_id = fetch(entry, "js_identifier")
+            validate_identifier!(js_id, seen)
+            validate_kind!(js_id, fetch(entry, "kind").to_s)
+            validate_method!(js_id, fetch(entry, "http_method"))
+            path = fetch(entry, "path")
+            validate_path!(js_id, path)
+            validate_segments!(js_id, path, fetch(entry, "segments"))
+            seen[js_id] = true
+          end
+
+          def validate_identifier!(js_id, seen)
+            unless js_id.is_a?(String) && js_id.match?(VALID_JS_IDENTIFIER)
+              raise Ruact::ConfigurationError,
+                    "ruact server-function codegen rejected a v2 snapshot entry: " \
+                    "js_identifier=#{js_id.inspect} is not a valid JS identifier " \
+                    "(must match #{VALID_JS_IDENTIFIER.inspect}); snapshot JSON is corrupted."
+            end
+            if NameBridge::RESERVED_JS_IDENTIFIERS.include?(js_id) ||
+               NameBridge::RESERVED_BY_RUACT.include?(js_id)
+              raise Ruact::ConfigurationError,
+                    "ruact server-function codegen: js_identifier #{js_id.inspect} is reserved — " \
+                    "cannot be exported; snapshot JSON is corrupted."
+            end
+            return unless seen.key?(js_id)
+
+            raise Ruact::ConfigurationError,
+                  "ruact server-function codegen: duplicate js_identifier #{js_id.inspect} in snapshot."
+          end
+
+          def validate_kind!(js_id, kind)
+            return if kind == "action"
+
+            raise Ruact::ConfigurationError,
+                  "ruact server-function codegen: v2 snapshot entry #{js_id.inspect} has invalid " \
+                  "kind #{kind.inspect} (v2 entries are always \"action\")."
+          end
+
+          def validate_method!(js_id, method)
+            return if HTTP_METHODS.include?(method)
+
+            raise Ruact::ConfigurationError,
+                  "ruact server-function codegen: v2 snapshot entry #{js_id.inspect} has invalid " \
+                  "http_method #{method.inspect} (must be one of #{HTTP_METHODS.to_a.inspect})."
+          end
+
+          def validate_path!(js_id, path)
+            unless path.is_a?(String) && path.start_with?("/")
+              raise Ruact::ConfigurationError,
+                    "ruact server-function codegen: v2 snapshot entry #{js_id.inspect} has invalid " \
+                    "path #{path.inspect} (must be a String beginning with \"/\")."
+            end
+            return unless path.match?(LINE_TERMINATORS)
+
+            raise Ruact::ConfigurationError,
+                  "ruact server-function codegen: v2 snapshot entry #{js_id.inspect} path contains a " \
+                  "line break — would break out of the generated call; snapshot JSON is corrupted."
+          end
+
+          def validate_segments!(js_id, path, segments)
+            unless segments.is_a?(Array) && segments.all? { |s| s.is_a?(String) && !s.empty? }
+              raise Ruact::ConfigurationError,
+                    "ruact server-function codegen: v2 snapshot entry #{js_id.inspect} has invalid " \
+                    "segments #{segments.inspect} (must be an Array of non-empty Strings)."
+            end
+            # Whole-token match: `:id` must NOT satisfy a declared segment when
+            # the path only has `:id_extra` (a substring `include?` would).
+            missing = segments.reject { |s| path.match?(/:#{Regexp.escape(s)}(?![A-Za-z0-9_])/) }
+            unless missing.empty?
+              raise Ruact::ConfigurationError,
+                    "ruact server-function codegen: v2 snapshot entry #{js_id.inspect} declares " \
+                    "segment(s) #{missing.inspect} absent from path #{path.inspect}; snapshot JSON is corrupted."
+            end
+
+            # Bidirectional: every dynamic `:param` in the path MUST be declared
+            # in segments, else the runtime would fetch a literal `:param` URL.
+            undeclared = path.scan(/:([A-Za-z_][A-Za-z0-9_]*)/).flatten - segments
+            return if undeclared.empty?
+
+            raise Ruact::ConfigurationError,
+                  "ruact server-function codegen: v2 snapshot entry #{js_id.inspect} path #{path.inspect} " \
+                  "has dynamic segment(s) #{undeclared.inspect} not declared in segments; snapshot JSON is corrupted."
+          end
+
+          # v2 snapshots use string keys on disk; specs may pass symbol keys.
+          def fetch(entry, key)
+            entry[key] || entry[key.to_sym]
+          end
+        end
+      end
+    end
+  end
+end