ruact 0.0.2 → 0.0.3

data/lib/ruact/server_functions/endpoint_controller.rb

@@ -0,0 +1,237 @@
+# frozen_string_literal: true
+
+require "action_controller"
+
+require_relative "error_payload"
+require_relative "error_rendering"
+
+module Ruact
+  module ServerFunctions
+    # Story 8.1 — the single gem-mounted Rails controller backing
+    # `POST /__ruact/fn/:name`. It resolves the URL `:name` parameter to a
+    # registered {Ruact::ServerFunctions::RegistryEntry}, allocates a fresh
+    # instance of the entry's host controller class, and delegates dispatch
+    # to that instance via Rails' standard `dispatch(action_name, request,
+    # response)` plumbing.
+    #
+    # This indirection is what gives `ruact_action` blocks access to the host
+    # controller's `current_user`, `session`, `before_action` chain, Pundit /
+    # ActionPolicy authorization, and `rescue_from` handlers — the block runs
+    # inside an honest controller instance, not in some gem-internal context.
+    #
+    # The `dispatch_action` action below is the ONLY public action on this
+    # controller — there is no `:create`, `:update`, etc.; the host's actions
+    # are reached indirectly via the wrapper method
+    # `__ruact_action_<symbol>` that {Ruact::Controller#ruact_action} defines.
+    class EndpointController < ActionController::Base
+      # Story 9.1 — the Story 8.4 error chain + Story 8.5 upload guard bodies
+      # were extracted into the shared {ErrorRendering} module so the
+      # {Ruact::Server} concern (v2) hosts the IDENTICAL implementation during
+      # the strangler-fig transition. This controller keeps v1 semantics via
+      # the module's hook defaults (always render the structured payload,
+      # guard always applicable) plus the `__ruact_error_action_name` override
+      # below. Behavior is byte-for-byte unchanged.
+      include Ruact::ServerFunctions::ErrorRendering
+
+      # Story 8.1 AC8 — for controller-hosted actions the gem does NOT impose
+      # its own CSRF protection: the host's `ApplicationController` is what
+      # enforces `protect_from_forgery`; since those requests are dispatched
+      # THROUGH a fresh host-controller instance below, the host's CSRF rules
+      # apply. EndpointController itself only routes — never renders the
+      # host's content directly.
+      #
+      # Story 8.3 — STANDALONE actions have no host controller, so there is
+      # no host-side CSRF callback to delegate to. The endpoint enforces
+      # CSRF for the standalone branch itself, gated by
+      # `dispatching_standalone?` (resolved EARLY via prepend_before_action).
+      # The controller-action branch keeps `skip_forgery_protection`-equivalent
+      # behavior (the verify callback skips because the entry's host is a
+      # Class, not a Module).
+      skip_forgery_protection if respond_to?(:skip_forgery_protection)
+
+      prepend_before_action :resolve_ruact_entry!
+
+      # Story 8.5 — enforce `Ruact.config.max_upload_bytes` on multipart /
+      # urlencoded bodies BEFORE the registry lookup and BEFORE Rack's
+      # multipart parser runs. `prepend_before_action` is what makes this the
+      # very first callback: the size check is dispatch-independent and the
+      # cheapest possible reject is "look at Content-Length and bail" — so
+      # the upload guard wins the race against `resolve_ruact_entry!` and
+      # (for the standalone branch) the conditional CSRF callback. A
+      # consequence: an oversized request from a CSRF-attacker on a standalone
+      # action is 413'd before CSRF is even checked — correct (the attacker
+      # learns nothing about CSRF state from a 413).
+      prepend_before_action :__ruact_enforce_upload_limit!
+
+      # Story 8.3 — install a strategy + conditional callback so
+      # `verify_authenticity_token` only fires on the standalone-dispatch
+      # branch. `protect_from_forgery with: :exception, if: ...` is the
+      # idiomatic Rails way to wire BOTH the forgery_protection_strategy
+      # AND the before_action — using `before_action :verify_authenticity_token`
+      # directly would crash because the strategy class would be nil. The
+      # callback's `if:` proc resolves at request time after
+      # `resolve_ruact_entry!` populates `@__ruact_entry`. Rails' own
+      # `verified_request?` short-circuits when the host app sets
+      # `config.action_controller.allow_forgery_protection = false` (API
+      # mode), so the check is a no-op in that case — same observable
+      # behavior as the controller-hosted branch under the same setting.
+      protect_from_forgery with: :exception, if: :dispatching_standalone?
+
+      # Story 8.4 — OUTERMOST rescue chain so any StandardError that bubbled
+      # past the host's `rescue_from` chain (controller-hosted branch) or out
+      # of {StandaloneDispatcher} (standalone branch) is rendered as a
+      # structured JSON payload instead of Rails' default HTML error page.
+      # Most-specific entries come last because Rails resolves handlers in
+      # registration order (last registration wins for the same class), but
+      # because both handlers route to the same private method, the order is
+      # only relevant for the EXPLICIT InvalidAuthenticityToken entry — that
+      # one preempts Rails' auto-installed `handle_unverified_request`
+      # (Pitfall #1).
+      rescue_from StandardError, with: :__ruact_render_action_error
+      rescue_from ActionController::InvalidAuthenticityToken, with: :__ruact_render_action_error
+
+      # `POST /__ruact/fn/:name` (mounted by `Ruact::Railtie`).
+      def dispatch_action
+        entry = @__ruact_entry
+        return render_unknown(@__ruact_name_sym) unless entry
+
+        host = entry.controller
+        if Ruact::ServerFunctions::EndpointController.standalone_host?(host)
+          # Call StandaloneDispatcher WITHOUT passing the response so Rails'
+          # `ImplicitRender` does not see an uncommitted response (writing
+          # directly to `response.body =` would otherwise be silently
+          # overwritten by the implicit-render 204). Apply the dispatcher's
+          # Result directive via render/head, which Rails recognises as
+          # rendered output.
+          result = Ruact::ServerFunctions::StandaloneDispatcher.dispatch(entry, request)
+          return apply_standalone_result(result)
+        end
+
+        unless host.is_a?(Class)
+          return render(
+            json: { error: "ruact action :#{@__ruact_name_sym} has an invalid host shape — " \
+                           "expected a Controller class or a Module that extends Ruact::ServerAction" },
+            status: :internal_server_error
+          )
+        end
+
+        host_class = host
+
+        # Re-run-2 (2026-05-14) — rebuild `request.path_parameters` so that
+        # the host action sees `controller`/`action` keys describing ITSELF,
+        # not the gem-endpoint route. Without this, `params[:controller]`
+        # inside the host's action body returns
+        # `"ruact/server_functions/endpoint"` and `params[:action]` returns
+        # `"dispatch_action"` — which breaks `controller_name` /
+        # `controller_path` / Pundit policy resolution / any code that reads
+        # the routing identity. Restore after dispatch so the endpoint
+        # response can be rendered with its own identity intact.
+        # Re-run-4 (2026-05-15) — DROP `name: raw_name` from the swap.
+        # The host action does not need the routing function name (it's
+        # already inferable from `action_name`), and keeping it in
+        # `path_parameters` made `params[:name]` inside the host action /
+        # before_action chain return the route function name instead of
+        # a legitimate submitted body field named `:name`. Only
+        # `controller`/`action` are swapped — those are required for
+        # `controller_name` / `controller_path` / Pundit / instrumentation.
+        original_path_parameters = request.path_parameters.dup
+        host_path_parameters = {
+          controller: host_class.controller_path,
+          action: @__ruact_name_sym.to_s
+        }
+        request.path_parameters = host_path_parameters
+
+        # Thread-local sentinel allows the public action method to be
+        # invoked only here, not from a wildcard route the host may have
+        # set up — see the guard inside the defined method.
+        Thread.current[:__ruact_dispatching] = @__ruact_name_sym
+        host_class.dispatch(@__ruact_name_sym.to_s, request, response)
+      ensure
+        Thread.current[:__ruact_dispatching] = nil
+        request.path_parameters = original_path_parameters if original_path_parameters
+      end
+
+      # Story 8.3 — positive check for the standalone host shape. A host is
+      # standalone iff it's a Module (and not a Class) that extends
+      # `Ruact::ServerAction`. The class hierarchy `Class < Module` means
+      # `is_a?(Module)` also matches Classes; we exclude Classes explicitly.
+      def self.standalone_host?(host)
+        return false if host.nil?
+        return false if host.is_a?(Class)
+        return false unless host.is_a?(Module)
+
+        host.singleton_class.include?(Ruact::ServerAction)
+      end
+
+      private
+
+      # Translates a `StandaloneDispatcher::Result` into the appropriate
+      # render call. Calling `render` / `head` is what marks the response
+      # as performed (`performed? == true`); writing to `response.body =`
+      # directly would be overwritten by Rails' `ImplicitRender`.
+      def apply_standalone_result(result)
+        if result.body.nil? || result.body.empty?
+          head(result.status)
+        else
+          render(
+            body: result.body,
+            status: result.status,
+            content_type: result.content_type
+          )
+        end
+      end
+
+      # Resolves the registry entry BEFORE Rails' before_action chain runs
+      # the conditional `verify_authenticity_token` callback — the CSRF
+      # decision depends on knowing whether the host is standalone, which
+      # is only knowable after we have the entry in hand. Stashes the
+      # entry + name on instance ivars so `dispatch_action` and
+      # `dispatching_standalone?` can both read them.
+      def resolve_ruact_entry!
+        @__ruact_name_sym = request.path_parameters[:name].to_s.to_sym
+        @__ruact_entry = lookup_entry(@__ruact_name_sym)
+      end
+
+      # Story 8.5 — the upload-guard body lives in {ErrorRendering}
+      # (`__ruact_enforce_upload_limit!`); this controller uses it via the
+      # `prepend_before_action` above with the module's "always applicable"
+      # default (the endpoint route is POST-only — no GET carve-out needed).
+
+      def dispatching_standalone?
+        return false unless @__ruact_entry
+
+        Ruact::ServerFunctions::EndpointController.standalone_host?(@__ruact_entry.controller)
+      end
+
+      def lookup_entry(name_sym)
+        # Story 8.1 only routes through the action registry. Story 9.1 will
+        # extend this lookup to also check the query registry; until then,
+        # query-only symbols return 404 here.
+        Ruact.action_registry.entries[name_sym]
+      end
+
+      def render_unknown(name_sym)
+        render(
+          json: { error: "unknown ruact action: :#{name_sym}" },
+          status: :not_found
+        )
+      end
+
+      # Story 8.4 / 9.1 — the structured-error renderer body lives in
+      # {ErrorRendering} (`__ruact_render_action_error` + status mapping +
+      # payload-mode resolution + logging). This override supplies the v1
+      # `action_name` source.
+      #
+      # Story 8.5 — the upload-limit guard runs BEFORE `resolve_ruact_entry!`,
+      # so `@__ruact_name_sym` may still be nil when a 413 fires. Fall back
+      # to `request.path_parameters[:name]` (the URL `:name` segment Rails
+      # routed on) so the structured payload still carries a meaningful
+      # `action_name` instead of "(unknown)".
+      def __ruact_error_action_name
+        @__ruact_name_sym ||
+          request.path_parameters[:name]&.to_s&.to_sym ||
+          :"(unknown)"
+      end
+    end
+  end
+end

data/lib/ruact/server_functions/error_payload.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+require_relative "backtrace_cleaner"
+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
+    # exception that bubbles past a host's `rescue_from` chain.
+    #
+    # The function is pure (no `Rails.env`, no `Ruact.config` reads) — the
+    # caller resolves `mode` (`:development` or `:production`) and passes it
+    # in. That keeps the module trivially testable without stubbing Rails env.
+    #
+    # In `:development` mode the payload carries the full surface:
+    # action name, error class, message, split backtrace (first 25 frames per
+    # bucket), contextual suggestion, and (for `ActiveRecord::RecordInvalid`)
+    # the model's `full_messages`.
+    #
+    # In `:production` mode the payload is reduced to four baseline keys:
+    # `_ruact_server_action_error`, `action_name`, `error_class`, `message`.
+    # React components can render their own UI from those four fields without
+    # any accidental backtrace leakage on the wire.
+    module ErrorPayload
+      # Maximum frames preserved per bucket. The full backtrace is still in
+      # the server log; the wire payload is for the overlay, which is
+      # unreadable past a couple of dozen frames anyway.
+      MAX_FRAMES_PER_BUCKET = 25
+
+      # @param action_name [Symbol, String]
+      # @param error [Exception]
+      # @param mode [Symbol] :development or :production
+      # @return [Hash{String=>Object}]
+      def self.build(action_name:, error:, mode:)
+        # Pitfall #5: defensive dup against frozen-string `Exception#message`
+        # implementations.
+        message = error.message.to_s.dup
+        payload = {
+          "_ruact_server_action_error" => true,
+          "action_name" => action_name.to_s,
+          "error_class" => error.class.name,
+          "message" => message
+        }
+        return payload if mode == :production
+
+        frames = BacktraceCleaner.split(error.backtrace)
+        payload["app_frames"] = frames[:app].first(MAX_FRAMES_PER_BUCKET)
+        payload["gem_frames"] = frames[:gem].first(MAX_FRAMES_PER_BUCKET)
+        payload["suggestion"] = ErrorSuggestion.for(error)
+        validation_errors = extract_validation_errors(error)
+        payload["validation_errors"] = validation_errors if validation_errors
+        upload_limit = extract_upload_limit(error)
+        payload["upload_limit"] = upload_limit if upload_limit
+        payload
+      end
+
+      # Story 8.5 — for `Ruact::UploadTooLargeError`, surface the
+      # `received_bytes` / `limit_bytes` pair as a dev-only block so the
+      # overlay can render both numbers without re-parsing the message.
+      # Returns nil for any other error class so the caller can omit the
+      # key entirely (preserves the "four baseline keys" prod contract).
+      def self.extract_upload_limit(error)
+        return nil unless error.class.name == "Ruact::UploadTooLargeError"
+
+        {
+          "received_bytes" => error.received_bytes,
+          "limit_bytes" => error.limit_bytes
+        }
+      end
+      private_class_method :extract_upload_limit
+
+      # Returns `full_messages` for `ActiveRecord::RecordInvalid` (or any
+      # error that exposes `.record.errors.full_messages`); `[]` when the
+      # record is nil; `nil` for unrelated exception classes (so the caller
+      # can omit the key entirely).
+      def self.extract_validation_errors(error)
+        return nil unless error.class.name == "ActiveRecord::RecordInvalid"
+        return [] unless error.respond_to?(:record)
+
+        record = error.record
+        return [] if record.nil?
+        return [] unless record.respond_to?(:errors)
+
+        errors = record.errors
+        return [] unless errors.respond_to?(:full_messages)
+
+        errors.full_messages.to_a
+      end
+      private_class_method :extract_validation_errors
+    end
+  end
+end

data/lib/ruact/server_functions/error_rendering.rb

@@ -0,0 +1,188 @@
+# frozen_string_literal: true
+
+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:
+    #
+    #   - {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:
+    #
+    #   - {#__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.
+    #   - {#__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.
+    #
+    # All methods are private on the including controller; nothing here is
+    # public API surface.
+    module ErrorRendering
+      private
+
+      # Story 8.5 — `prepend_before_action` callback. Rejects requests whose
+      # wire `Content-Length` exceeds `Ruact.config.max_upload_bytes`. The
+      # check uses `Content-Length` (not body inspection) so it fires BEFORE
+      # Rack's multipart parser would touch the body — the cheapest possible
+      # reject. It only fires for `multipart/form-data` and
+      # `application/x-www-form-urlencoded`; JSON bodies have their own
+      # operational caps (host middleware / reverse proxy) and aren't a
+      # "max upload" concern. Chunked-transfer clients (`Content-Length`
+      # absent) bypass the guard because we cannot know the size up-front; the
+      # action body is responsible for any belt-and-suspenders check via
+      # `params[:file].size` / `params[:file].byte_size`. A nil
+      # `Ruact.config.max_upload_bytes` short-circuits the guard entirely —
+      # the gem-side knob has been opted out and the host's reverse proxy /
+      # middleware owns the cap.
+      #
+      # The reported `received_bytes` is the WIRE Content-Length, which
+      # includes multipart boundary overhead (a 9.5 MB file uploaded via
+      # multipart reports `received_bytes ≈ 9.5 MB + a few KB`). The 10 MB
+      # default has enough headroom that this is invisible for the common
+      # case; the docs page calls it out for the edge.
+      def __ruact_enforce_upload_limit!
+        return unless __ruact_upload_guard_applicable?
+
+        limit = Ruact.config.max_upload_bytes
+        return if limit.nil?
+
+        content_type = request.content_mime_type&.to_s
+        return unless ["multipart/form-data", "application/x-www-form-urlencoded"].include?(content_type)
+
+        received = request.content_length
+        return if received.nil?
+        return if received <= limit
+
+        raise Ruact::UploadTooLargeError.new(received_bytes: received, limit_bytes: limit)
+      end
+
+      # Story 8.4 — Structured server-action error renderer. Resolves the
+      # mode from {Ruact.config.dev_error_payload_enabled} (falling back to
+      # `Rails.env.development? || Rails.env.test?` when nil), builds the
+      # JSON body via {ErrorPayload.build}, logs the failure server-side
+      # (always — the prod constraint is "do not leak via the wire", not
+      # "do not log"), then renders `json: payload, status: <mapped>`.
+      #
+      # Story 9.1 — when {#__ruact_render_structured_error?} returns false
+      # (a non-function-call request on a {Ruact::Server} host), the error is
+      # re-raised instead: re-raising inside a `rescue_from` handler
+      # propagates out of `process_action` without re-entering the rescue
+      # chain (the handler IS the rescue clause), so Rails' default error
+      # handling — debug page in development, public 500 in production —
+      # proceeds exactly as if the concern were not installed.
+      def __ruact_render_action_error(error)
+        raise error unless __ruact_render_structured_error?(error)
+
+        action_name = __ruact_error_action_name
+        mode = __ruact_payload_mode
+        payload = ErrorPayload.build(action_name: action_name, error: error, mode: mode)
+        __ruact_log_action_error(action_name, error)
+        render(json: payload, status: __ruact_status_for(error))
+      end
+
+      # Hook — where the structured payload's `action_name` field comes from.
+      # The controller's own `action_name` is correct for v2 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).
+      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).
+      def __ruact_upload_guard_applicable?
+        true
+      end
+
+      # Story 8.4 — Status mapping per AC1:
+      # - `ActiveRecord::RecordInvalid` → 422
+      # - `ActionController::InvalidAuthenticityToken` → 403
+      # - `Ruact::UploadTooLargeError` → 413
+      # - any other StandardError → 500
+      # Uses class-name string match so the gem does NOT require ActiveRecord
+      # at load time (parity with {ErrorSuggestion}).
+      def __ruact_status_for(error)
+        case error.class.name
+        when "ActiveRecord::RecordInvalid" then 422
+        when "ActionController::InvalidAuthenticityToken" then 403
+        when "Ruact::UploadTooLargeError" then 413
+        else 500
+        end
+      end
+
+      # Story 8.4 — Resolve the payload mode from configuration with a Rails
+      # env fallback. The fallback keeps the Configuration trivially
+      # constructible in non-Rails specs while ensuring production hosts that
+      # never call `Ruact.configure` still see the reduced wire shape.
+      #
+      # Strict-boolean handling (review follow-up): only the literals `true`
+      # and `false` count as an explicit configuration. Any other value
+      # (strings like `"true"`, numerics, Symbols, etc.) falls back to the
+      # env-driven default rather than being coerced via Ruby truthiness —
+      # otherwise a misconfigured `c.dev_error_payload_enabled = "false"`
+      # would silently leak the verbose payload in production.
+      def __ruact_payload_mode
+        case Ruact.config.dev_error_payload_enabled
+        when true  then :development
+        when false then :production
+        else __ruact_default_dev_mode? ? :development : :production
+        end
+      end
+
+      def __ruact_default_dev_mode?
+        return false unless defined?(Rails) && Rails.respond_to?(:env)
+
+        Rails.env.development? || Rails.env.test?
+      end
+
+      # Story 8.4 AC6 — log a single error line + the full backtrace, both at
+      # `error` severity. When `Rails.logger` responds to `tagged` (the
+      # ActiveSupport::TaggedLogging extension; Rails 6+ default for the
+      # request logger), wrap the entry in a `ruact action:<name>` tag for
+      # log-aggregator indexing. The full backtrace is emitted regardless of
+      # the wire-payload mode — server-side logs always carry the full
+      # picture.
+      def __ruact_log_action_error(action_name, error)
+        return unless defined?(Rails) && Rails.respond_to?(:logger) && Rails.logger
+
+        line = "[ruact] server action :#{action_name} failed — #{error.class.name}: #{error.message}"
+        backtrace_text = Array(error.backtrace).join("\n")
+
+        logger = Rails.logger
+        if logger.respond_to?(:tagged)
+          logger.tagged("ruact action:#{action_name}") do
+            logger.error(line)
+            logger.error(backtrace_text) unless backtrace_text.empty?
+          end
+        else
+          logger.error(line)
+          logger.error(backtrace_text) unless backtrace_text.empty?
+        end
+      end
+    end
+  end
+end

data/lib/ruact/server_functions/error_suggestion.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module Ruact
+  module ServerFunctions
+    # Story 8.4 — Maps an exception class (by its String name) to a short
+    # corrective suggestion shown in the dev overlay's structured view.
+    #
+    # The class-name match runs against `error.class.name` (a String) so the
+    # module does NOT need `require "active_record"` or
+    # `require "action_controller"` to operate; it works in AR-less specs and
+    # bare-Rack hosts (see Pitfall #4 in the story).
+    #
+    # The {SUGGESTIONS} table is a gem-published surface — new entries land
+    # via an ADR amendment + a constant update, NOT via runtime registration.
+    module ErrorSuggestion
+      SUGGESTIONS = {
+        "ActiveRecord::RecordInvalid" =>
+          "Validation failed — check the model's `validates` rules",
+        "ActionController::InvalidAuthenticityToken" =>
+          "CSRF token mismatch — ensure the page was rendered after the most recent server restart and the session cookie is intact",
+        # Story 8.5 — multipart-upload reject. Routes devs to either the
+        # config knob (for "raise the limit by a few MB") or the streaming
+        # upload pipelines (for "this should never have been a server-action
+        # request in the first place").
+        "Ruact::UploadTooLargeError" =>
+          "Upload exceeded the configured size limit. Increase Ruact.config.max_upload_bytes or use Active Storage Direct Upload / a presigned S3 URL for large files."
+      }.freeze
+
+      # Suggestion string for the given error, or nil for unknown classes.
+      #
+      # @param error [Exception]
+      # @return [String, nil]
+      def self.for(error)
+        SUGGESTIONS[error.class.name]
+      end
+    end
+  end
+end

data/lib/ruact/server_functions/name_bridge.rb

@@ -0,0 +1,113 @@
+# frozen_string_literal: true
+
+module Ruact
+  module ServerFunctions
+    # Translates a Ruby symbol into the JS identifier exported from
+    # `app/javascript/.ruact/server-functions.ts`. The bridge is Ruby-side only;
+    # the Vite plugin reads the already-translated identifier from the JSON
+    # snapshot and emits it verbatim (Story 8.0a design decision: one source of
+    # truth for naming).
+    #
+    # Rules (locked by Story 8.0 ADR + 2026-05-13 review-patch tightening):
+    # - Symbol must match `/\A[a-z_][a-z0-9_]*\z/`; otherwise raises
+    #   {Ruact::ConfigurationError} at controller-class load time.
+    # - A single leading underscore is preserved (e.g. `:_internal_dump` →
+    #   `"_internalDump"`).
+    # - Runs of underscores collapse and uppercase the following alphanumeric
+    #   (e.g. `:foo__bar` → `"fooBar"`).
+    # - The source symbol cannot be made of underscores alone (`:_`, `:__`, …) —
+    #   would otherwise emit `"_"`, which carries no semantic content and
+    #   collides with the common "ignored value" lint convention.
+    # - The translated JS identifier cannot match a JavaScript reserved word
+    #   or future-reserved word (ES2020+ list plus the module-top-level
+    #   `await` / `async`). `:class` → `"class"` would compile under Babel
+    #   loose-mode but break under `tsc --noEmit` and most ESLint configs.
+    #
+    # @see docs/internal/decisions/server-functions-api.md "Naming bridge"
+    module NameBridge
+      VALID_SYMBOL = /\A[a-z_][a-z0-9_]*\z/
+
+      UNDERSCORE_ONLY = /\A_+\z/
+
+      # ES2020+ reserved + strict-mode reserved + contextually-reserved at
+      # module top level + strict-mode invalid binding names. The codegen emits
+      # in a module context (the generated `app/javascript/.ruact/server-functions.ts`
+      # is `"type": "module"`, so all code runs in strict mode), so `await`,
+      # `eval`, and `arguments` are all reserved as identifier names.
+      # Keep this list sorted; matches the MDN reference plus the contextual
+      # additions and the strict-mode `eval`/`arguments` ban from the
+      # 2026-05-13 Re-run review patch.
+      RESERVED_JS_IDENTIFIERS = %w[
+        arguments async await break case catch class const continue
+        debugger default delete do else enum eval export extends false
+        finally for function if implements import in instanceof interface
+        let new null package private protected public return static super
+        switch this throw true try typeof var void while with yield
+      ].to_set.freeze
+
+      # Story 8.2 (2026-05-17 review patches R2 + R12) — names already
+      # bound at the top of `app/javascript/.ruact/server-functions.ts`,
+      # either by the helper re-export (`revalidate`) or the runtime
+      # import (`_makeRef`). A `ruact_action :revalidate` or
+      # `ruact_action :_make_ref` would emit a clashing `export const`
+      # next to the existing binding and crash at module-load time.
+      # The rule fires at controller-class load so the failure
+      # surfaces during boot, not at first request.
+      RESERVED_BY_RUACT = %w[
+        _makeRef
+        _makeServerFunction
+        revalidate
+      ].to_set.freeze
+
+      class << self
+        # @param symbol [Symbol, String] the Ruby identifier registered via
+        #   `ruact_action` / `ruact_query` (Phase 2 stories 8.1 and 9.1).
+        # @return [String] the corresponding JS identifier.
+        # @raise [Ruact::ConfigurationError] when +symbol+ does not match the
+        #   allowed shape, is all-underscores, or maps to a JS reserved word —
+        #   caught at controller load time so misnamed routes never reach
+        #   production.
+        # @example
+        #   Ruact::ServerFunctions::NameBridge.to_js_identifier(:create_post)
+        #   # => "createPost"
+        # @example leading underscore preserved
+        #   Ruact::ServerFunctions::NameBridge.to_js_identifier(:_internal_dump)
+        #   # => "_internalDump"
+        def to_js_identifier(symbol)
+          str = symbol.to_s
+
+          unless str.match?(VALID_SYMBOL)
+            raise Ruact::ConfigurationError,
+                  "ruact_action / ruact_query symbol :#{symbol} must match /^[a-z_][a-z0-9_]*$/"
+          end
+
+          if str.match?(UNDERSCORE_ONLY)
+            raise Ruact::ConfigurationError,
+                  "ruact_action / ruact_query symbol :#{symbol} cannot be composed " \
+                  "entirely of underscores (no semantic content)"
+          end
+
+          leading = str.start_with?("_") ? "_" : ""
+          body    = str.sub(/\A_+/, "")
+          js_id   = leading + body.gsub(/_+([a-z0-9])/) { Regexp.last_match(1).upcase }
+
+          if RESERVED_JS_IDENTIFIERS.include?(js_id)
+            raise Ruact::ConfigurationError,
+                  "ruact_action / ruact_query symbol :#{symbol} maps to JS reserved " \
+                  "word \"#{js_id}\" — pick a different Ruby symbol (e.g. :#{symbol}_action)"
+          end
+
+          if RESERVED_BY_RUACT.include?(js_id)
+            raise Ruact::ConfigurationError,
+                  "ruact_action / ruact_query symbol :#{symbol} maps to \"#{js_id}\", " \
+                  "which is already exported by the ruact runtime from " \
+                  "`@/.ruact/server-functions` and would emit a duplicate export. " \
+                  "Pick a different Ruby symbol (e.g. :#{symbol}_action)."
+          end
+
+          js_id
+        end
+      end
+    end
+  end
+end