ruact 0.0.2 → 0.0.4

data/lib/ruact/server_functions/query_context.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+module Ruact
+  module ServerFunctions
+    # Story 9.4 (D3) — per-request execution context injected into a
+    # {Ruact::Query} subclass by the internal query dispatch controller. A
+    # fresh instance is built per request (NFR8) wrapping the DISPATCHING
+    # controller instance; because that controller inherits
+    # `Ruact.config.query_parent_controller`, every delegated reader resolves
+    # to the host's own machinery — `current_user` IS the host's method
+    # (Devise / Pundit / hand-rolled), not a gem-side resolver lambda.
+    #
+    # Mirrors the SHAPE of the Story-8.3 `StandaloneContext` (plain accessors,
+    # per-request instance) while sourcing everything from the controller —
+    # the resolver-lambda pattern is superseded by the 2026-06-02 ADR
+    # addendum (Decision 2).
+    class QueryContext
+      # @param controller [ActionController::Base] the dispatching controller
+      #   instance (a generated subclass of `Ruact.config.query_parent_controller`).
+      def initialize(controller:)
+        @controller = controller
+      end
+
+      # The host's authenticated user. Resolved through the controller's own
+      # `current_user` — public OR private (hand-rolled apps commonly define
+      # it `private`). When the host chain defines no `current_user` at all,
+      # raises a NoMethodError that names the fix instead of a bare
+      # "undefined method" from deep inside a query body.
+      #
+      # @return [Object, nil]
+      # @raise [NoMethodError] when the parent controller chain defines no
+      #   `current_user`.
+      def current_user
+        unless @controller.respond_to?(:current_user, true)
+          raise NoMethodError,
+                "ruact: the query dispatch controller (inheriting " \
+                "#{@controller.class.superclass.name}, via Ruact.config.query_parent_controller) " \
+                "does not define `current_user`. Define it on the parent controller, or point " \
+                "`query_parent_controller` at a controller that does."
+        end
+
+        @controller.send(:current_user)
+      end
+
+      # @return [ActionController::Parameters] the request params (query-string
+      #   parameters on a GET query route).
+      def params
+        @controller.params
+      end
+
+      # @return [ActionDispatch::Request] the live request.
+      def request
+        @controller.request
+      end
+
+      # @return [ActionDispatch::Request::Session] the host middleware's session.
+      def session
+        @controller.session
+      end
+    end
+  end
+end

data/lib/ruact/server_functions/query_dispatch.rb

@@ -0,0 +1,313 @@
+# frozen_string_literal: true
+
+require "action_controller"
+
+require_relative "error_rendering"
+require_relative "bucket_two_payload"
+require_relative "query_context"
+
+module Ruact
+  module ServerFunctions
+    # Story 9.4 (D2) — generates the INTERNAL dispatch controller backing the
+    # routes the `ruact_queries` macro draws: one controller subclass PER
+    # {Ruact::Query} subclass, with one action per public query method. The
+    # per-class shape is what makes the AC4 callback opt-out scopable — a
+    # `ruact_skip_before_action` on one query class lands on that class's
+    # controller only, and `only:`/`except:` options scope it further to
+    # individual query methods (each method is one action).
+    #
+    # The controller inherits `Ruact.config.query_parent_controller`
+    # (default `ApplicationController`), resolved LAZILY here — at route-draw
+    # time, when the host's constants exist — never at gem-load or configure
+    # time. The host's REAL callback chain therefore runs before the query
+    # class is instantiated (FR89). The dev never sees this controller; it is
+    # named under this module (e.g.
+    # `Ruact::ServerFunctions::QueryDispatch::CatalogQueryController`) only so
+    # Rails' string-based route resolution (`to: "…/catalog_query#categories"`)
+    # and `rails routes` output stay legible.
+    #
+    # Regeneration is idempotent: every `ruact_queries` evaluation (boot AND
+    # every dev-mode routes reload) rebuilds the constant from the query
+    # class's CURRENT state, and the query class itself is re-constantized per
+    # request, so code reloading never serves a stale class.
+    module QueryDispatch
+      # Instance-level dispatch plumbing shared by every generated controller.
+      # Included into the generated subclass, so these definitions override
+      # anything the parent chain provides (notably the {Ruact::Server} gates,
+      # when the host's ApplicationController happens to include the mutation
+      # concern).
+      module Dispatching
+        # The Method#parameters types that mark keyword arguments (D7).
+        KEYWORD_PARAM_TYPES = %i[key keyreq].freeze
+
+        # Story 9.5 (FR88) — the wire is GET query-string values, so every
+        # primitive the client sends arrives as a String (`?limit=5` →
+        # `"5"`); `nil` is the only non-String primitive Rack can produce for
+        # a scalar param. Arrays (`?q[]=`) and Hashes (`?q[k]=`) are the
+        # rejected complex shapes. Membership here = "this is a primitive the
+        # allowlist accepts".
+        PRIMITIVE_PARAM_CLASSES = [String, NilClass].freeze
+
+        private
+
+        # The action body of every query action: fresh context + fresh query
+        # instance per request (NFR8), return value serialized through the
+        # SAME policy Bucket 2 applies to ivars (D6). Encoded explicitly so a
+        # scalar String/nil return still renders valid JSON (`"hi"` / `null`),
+        # which `render json:` alone would pass through raw.
+        def __ruact_dispatch_query(query_method)
+          query_class = self.class.__ruact_query_class
+          query = query_class.new(QueryContext.new(controller: self))
+          result = query.public_send(query_method, **__ruact_query_kwargs(query, query_method))
+          serialized = BucketTwoPayload.serialize_value(result, strict: Ruact.config.strict_serialization)
+          render json: ActiveSupport::JSON.encode(serialized)
+        end
+
+        # Story 9.5 (FR88) — the AUTHORITATIVE kwargs sanitization. The query
+        # method's declared keyword arguments are the contract; the client's
+        # `useQuery(ref, params)` call sends those as GET query-string values.
+        # Reads the RAW client params from `request.query_parameters` (not
+        # `params`, which is polluted with Rails' `controller`/`action`/
+        # `format` routing defaults — those must not count as "unknown
+        # parameters"). Enforces, in order:
+        #
+        #   1. **Allowlist** — every provided value must be a primitive
+        #      (`string | number | boolean | null`; on the wire: String or
+        #      nil). An Array (`?q[]=`) or Hash (`?q[k]=`) is rejected with a
+        #      descriptive `Ruact::BadRequestError` naming the offending key
+        #      and the allowlist → 400.
+        #   2. **Unknown param** — a provided key matching no declared kwarg
+        #      (and the method has no `**rest`) is rejected, not silently
+        #      dropped → 400.
+        #   3. **Missing required** — a declared `keyreq` the client did not
+        #      send → 400 naming the missing parameter.
+        #
+        # Returns the symbol-keyed kwargs hash to splat into the query method.
+        def __ruact_query_kwargs(query, query_method)
+          signature = query.method(query_method).parameters
+          required = signature.filter_map { |type, name| name.to_s if type == :keyreq }
+          optional = signature.filter_map { |type, name| name.to_s if type == :key }
+          accepts_rest = signature.any? { |type, _name| type == :keyrest }
+          declared = required + optional
+
+          provided = request.query_parameters
+
+          provided.each do |key, value|
+            __ruact_validate_query_param!(query_method, key, value, declared, accepts_rest)
+          end
+
+          missing = required.reject { |name| provided.key?(name) }
+          unless missing.empty?
+            raise Ruact::BadRequestError,
+                  "ruact query :#{query_method} is missing required parameter(s) " \
+                  "#{missing.map { |n| n.to_sym.inspect }.join(', ')}."
+          end
+
+          provided.each_with_object({}) do |(key, value), kwargs|
+            kwargs[key.to_sym] = value if declared.include?(key) || accepts_rest
+          end
+        end
+
+        # FR88 per-param gate — see {#__ruact_query_kwargs}. Order matters:
+        # the unknown-param check precedes the type check so an unknown
+        # complex param is reported as "unknown" (the more actionable error).
+        #
+        # `accepts_rest` (the method declares `**rest`) relaxes ONLY the
+        # named-parameter restriction — a `**rest` signature is the author's
+        # explicit opt-in to arbitrary kwargs, so no provided key is "unknown".
+        # The TYPE allowlist below STILL runs for every param including the
+        # rest-captured ones, so the FR88 security boundary (reject
+        # arrays/objects) holds regardless of `**rest`.
+        def __ruact_validate_query_param!(query_method, key, value, declared, accepts_rest)
+          unless declared.include?(key) || accepts_rest
+            raise Ruact::BadRequestError,
+                  "ruact query :#{query_method} received unknown parameter #{key.to_sym.inspect} " \
+                  "— it matches no keyword argument of the query method."
+          end
+
+          return if PRIMITIVE_PARAM_CLASSES.any? { |klass| value.is_a?(klass) }
+
+          raise Ruact::BadRequestError,
+                "ruact query :#{query_method} parameter #{key.to_sym.inspect} must be a " \
+                "string, number, boolean, or null — arrays and objects are rejected " \
+                "(got #{value.class})."
+        end
+
+        # D5 — the {Ruact::Server} mutation gate returns false for GET/HEAD so
+        # GET *pages* keep stock Rails errors; query dispatch requests are GET
+        # *function calls*, so the structured 8.4 payload must render here.
+        # `Ruact::ConfigurationError` still re-raises — a misconfiguration is
+        # a loud setup failure, never a disguised runtime 500 (the same rule
+        # the mutation concern enforces).
+        def __ruact_render_structured_error?(error)
+          !error.is_a?(Ruact::ConfigurationError)
+        end
+      end
+
+      class << self
+        # Builds (or rebuilds) the dispatch controller for +query_class+ and
+        # installs it under this module's namespace, where the route target
+        # string from {.route_target_for} resolves to it.
+        #
+        # @param query_class [Class] a {Ruact::Query} subclass
+        # @return [Class] the generated controller
+        # @raise [Ruact::ConfigurationError] when the parent controller cannot
+        #   be resolved or +query_class+ is anonymous
+        def controller_for(query_class)
+          *namespace_segments, base = constant_segments(query_class)
+          namespace = ensure_namespace(namespace_segments)
+          const_name = "#{base}Controller"
+          namespace.send(:remove_const, const_name) if namespace.const_defined?(const_name, false)
+          namespace.const_set(const_name, build_controller(query_class))
+        end
+
+        # The `to:` route target for +query_class+'s generated controller —
+        # the underscored constant path Rails camelizes back at dispatch time.
+        # The query class's namespace is PRESERVED (review round 4): a nested
+        # path, never flattened, so two classes whose names differ only in
+        # namespace boundary (`Admin::CatalogQuery` vs `AdminCatalogQuery`)
+        # map to DISTINCT controllers and can never cross-wire — collision is
+        # impossible by construction, across any number of RouteSets / engines.
+        #
+        # @param query_class [Class] a {Ruact::Query} subclass
+        # @return [String] e.g. `"ruact/server_functions/query_dispatch/admin/catalog_query"`
+        def route_target_for(query_class)
+          "ruact/server_functions/query_dispatch/#{path_segments(query_class).join('/')}"
+        end
+
+        private
+
+        # The underscored route-path segments for +query_class+
+        # (`Admin::CatalogQuery` → `["admin", "catalog_query"]`).
+        def path_segments(query_class)
+          base_segments(query_class).map(&:underscore)
+        end
+
+        # The generated controller's constant-name segments — derived from the
+        # SAME underscored path the route target uses, then `camelize`d
+        # (review round 5). Deriving both directions from one underscored form
+        # via the shared global inflector guarantees the route target Rails
+        # `camelize`s at dispatch time resolves to EXACTLY this constant,
+        # regardless of how the query class spelled an acronym or how the host
+        # configured `inflect.acronym` (`APIProbe::CatalogQuery` and the route
+        # `.../api_probe/catalog_query` both canonicalize identically). Using
+        # the raw class spelling instead would 404 acronym constants with the
+        # default inflector.
+        def constant_segments(query_class)
+          path_segments(query_class).map(&:camelize)
+        end
+
+        # The query class's fully-qualified name split into constant segments
+        # (`Admin::CatalogQuery` → `["Admin", "CatalogQuery"]`). The namespace
+        # is preserved so the generated controller lives at a nested,
+        # collision-free constant path under {QueryDispatch}.
+        def base_segments(query_class)
+          name = query_class.name
+          unless name
+            raise Ruact::ConfigurationError,
+                  "ruact_queries cannot mount an anonymous Ruact::Query subclass — " \
+                  "assign it to a constant (e.g. `class CatalogQuery < ApplicationQuery`)."
+          end
+
+          name.split("::")
+        end
+
+        # Walks (creating as needed) the nested module path under {QueryDispatch}
+        # that mirrors the query class's namespace, returning the innermost
+        # module the controller constant is set on. Idempotent — reuses existing
+        # modules so repeated draws (boot + dev reloads) never duplicate them.
+        def ensure_namespace(segments)
+          segments.reduce(self) do |mod, segment|
+            if mod.const_defined?(segment, false)
+              mod.const_get(segment, false)
+            else
+              mod.const_set(segment, Module.new)
+            end
+          end
+        end
+
+        # Lazy resolution of `Ruact.config.query_parent_controller` (AC2). Both
+        # failure shapes are configuration-time errors raised at route-draw —
+        # a typo'd name or a non-controller class must never reach a request.
+        def resolve_parent_controller
+          name = Ruact.config.query_parent_controller
+          parent = begin
+            name.constantize
+          rescue NameError
+            raise Ruact::ConfigurationError,
+                  "ruact_queries: Ruact.config.query_parent_controller = #{name.inspect} does not " \
+                  "resolve to a constant. Define that controller, or point query_parent_controller " \
+                  "at an existing one in config/initializers/ruact.rb."
+          end
+
+          unless parent.is_a?(Class) && parent <= ActionController::Metal
+            raise Ruact::ConfigurationError,
+                  "ruact_queries: Ruact.config.query_parent_controller = #{name.inspect} resolved to " \
+                  "#{parent.inspect}, which is not an ActionController class."
+          end
+
+          parent
+        end
+
+        def build_controller(query_class)
+          query_class_name = query_class.name
+
+          # Mixins applied on the built class (not inside a `Class.new do … end`
+          # block) so YARD's static MixinHandler does not emit "Undocumentable
+          # mixin … for class" for an anonymous class body — the
+          # `--fail-on-warning` docs gate treats that as an error. Runtime is
+          # identical.
+          controller = Class.new(resolve_parent_controller)
+          controller.include(Ruact::ServerFunctions::ErrorRendering)
+          controller.include(Dispatching)
+
+          controller.define_singleton_method(:__ruact_query_class) { query_class_name.constantize }
+
+          # AC5 — the salvaged 8.4 error chain, with the same front-loading
+          # trick as Ruact::Server: handlers the parent chain registered
+          # (inherited OR declared later) stay more recent and keep precedence;
+          # the structured renderer only catches what the host did not.
+          inherited_handlers = controller.rescue_handlers
+          controller.rescue_from(StandardError, with: :__ruact_render_action_error)
+          controller.rescue_handlers = (controller.rescue_handlers - inherited_handlers) + inherited_handlers
+
+          define_query_actions(controller, query_class)
+          apply_skips(controller, query_class)
+          controller
+        end
+
+        # Review round 1 (finding 1) — a query method whose name already exists
+        # anywhere on the generated controller chain (`params`, `render`,
+        # `session`, `process`, the gem's own `__ruact_*` plumbing, …) would
+        # OVERRIDE that method when installed as an action, corrupting request
+        # handling (e.g. `def params` shadows `ActionController#params` and
+        # recurses through the dispatch path). Reject at route-draw with a
+        # legible error instead of failing at the first request.
+        def define_query_actions(controller, query_class)
+          query_class.public_instance_methods(false).each do |query_method|
+            if controller.method_defined?(query_method) || controller.private_method_defined?(query_method)
+              raise Ruact::ConfigurationError,
+                    "ruact_queries: query method :#{query_method} on #{query_class.name} is already " \
+                    "defined on the dispatch controller chain (#{controller.superclass.name} / " \
+                    "ActionController / ruact plumbing) and would shadow it — rename the query method."
+            end
+
+            controller.define_method(query_method) do
+              __ruact_dispatch_query(query_method)
+            end
+          end
+        end
+
+        # AC4 / D1 — forwards every recorded `ruact_skip_before_action` to
+        # Rails' own `skip_before_action` on the generated controller. An
+        # unknown callback raises here (route-draw time) unless the query
+        # passed `raise: false`, mirroring stock Rails behavior.
+        def apply_skips(controller, query_class)
+          query_class.__ruact_skipped_callbacks.each do |callbacks, options|
+            controller.skip_before_action(*callbacks, **options)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ruact/server_functions/query_source.rb

@@ -0,0 +1,150 @@
+# frozen_string_literal: true
+
+require "active_support/core_ext/string/inflections"
+require "ruact/server_functions/name_bridge"
+
+module Ruact
+  module ServerFunctions
+    # Story 9.5 — derives v2 QUERY entries for the route-driven codegen, the
+    # read-side sibling of {RouteSource} (which derives the non-GET mutation
+    # actions). Queries come from {Ruact::Query} subclasses mounted via the
+    # `ruact_queries` routing macro (Story 9.4).
+    #
+    # ## Why read the drawn route table, not all Ruact::Query subclasses
+    #
+    # The route table is the single source of truth (FR61): a host exposes a
+    # query ONLY by mounting its class with `ruact_queries` in `routes.rb`.
+    # Enumerating every `Ruact::Query` subclass would over-expose query classes
+    # that are defined but never mounted (and would 404 when `useQuery` fetched
+    # their non-existent routes). Reading the routes the `ruact_queries` macro
+    # actually drew keeps codegen route-truth-consistent with dispatch by
+    # construction — and means there is no `app/queries` force-load gap to
+    # paper over (mounting a class in `routes.rb` already autoloads it).
+    #
+    # Every generated query dispatch controller lives under the
+    # {QUERY_CONTROLLER_PREFIX} namespace (see
+    # {QueryDispatch.route_target_for}), so the GET routes this module consumes
+    # are unambiguous: any drawn route whose controller path starts with that
+    # prefix is a mounted query method.
+    #
+    # Pure by construction: {.collect} takes the route set and a resolver
+    # callable (controller-path → the backing {Ruact::Query} subclass). The
+    # railtie passes the real constant-resolving implementation; unit specs
+    # inject a lambda so the derivation is testable without booting controllers.
+    #
+    # @see RouteSource the mutation (action) sibling
+    # @see Ruact::Routing#ruact_queries the macro that draws the routes read here
+    module QuerySource
+      # The controller-path prefix every generated query dispatch controller
+      # lives under (mirrors {QueryDispatch.route_target_for}). A drawn GET
+      # route whose controller starts with this prefix is a mounted query.
+      QUERY_CONTROLLER_PREFIX = "ruact/server_functions/query_dispatch/"
+
+      # `Method#parameters` types that mark keyword arguments — the FR88 query
+      # parameters (mirrors {QueryDispatch::Dispatching::KEYWORD_PARAM_TYPES}).
+      KEYWORD_PARAM_TYPES = %i[key keyreq keyrest].freeze
+
+      class << self
+        # Collects v2 query entries from +route_set+.
+        #
+        # @param route_set [#routes] anything exposing `#routes` (an
+        #   `ActionDispatch::Routing::RouteSet`, or `Rails.application.routes`).
+        # @param query_class_for [#call, nil] `controller_path(String) ->
+        #   (Class | nil)` — resolves a query dispatch controller path to the
+        #   {Ruact::Query} subclass it backs. Defaults to real constant
+        #   resolution (reads the generated controller's `__ruact_query_class`).
+        # @return [Array<Hash>] query entries (string keys) sorted by
+        #   `js_identifier`; shape: `js_identifier`, `kind` (always `"query"`),
+        #   `http_method` (always `"GET"`), `path`, `segments` (always `[]`),
+        #   `accepts_params` (Boolean — does the method declare kwargs?),
+        #   `controller` (the query class name — for collision origins),
+        #   `action` (the Ruby method name).
+        # @raise [Ruact::ConfigurationError] on a query×query naming collision.
+        def collect(route_set, query_class_for: nil)
+          query_class_for ||= method(:default_query_class_for)
+
+          entries = []
+          route_set.routes.each do |route|
+            controller = route.defaults[:controller]
+            action = route.defaults[:action]
+            next if controller.nil? || action.nil?
+            next unless controller.to_s.start_with?(QUERY_CONTROLLER_PREFIX)
+
+            query_class = query_class_for.call(controller.to_s)
+            next if query_class.nil?
+
+            entries << build_entry(route, action.to_s, query_class)
+          end
+
+          entries = entries.sort_by { |entry| entry["js_identifier"] }
+          detect_collisions!(entries)
+          entries
+        end
+
+        private
+
+        def build_entry(route, action, query_class)
+          {
+            "js_identifier" => NameBridge.to_js_identifier(action),
+            "kind" => "query",
+            "http_method" => "GET",
+            "path" => clean_path(route),
+            "segments" => [],
+            "accepts_params" => accepts_params?(query_class, action),
+            "controller" => query_class.name,
+            "action" => action
+          }
+        end
+
+        # Does the query method declare any keyword arguments (FR88 params)?
+        # Drives the emitted TS signature: `(params) => Promise<unknown>` when
+        # true, `() => Promise<unknown>` when false (AC1).
+        def accepts_params?(query_class, action)
+          query_class.instance_method(action).parameters.any? do |(type, _name)|
+            KEYWORD_PARAM_TYPES.include?(type)
+          end
+        rescue NameError
+          false
+        end
+
+        # query×query collision — two mounted query classes whose methods map
+        # to the SAME JS identifier (e.g. `CatalogQuery#search_users` and
+        # `PeopleQuery#search_users`). Fail loudly at boot naming both origins.
+        # The route×query side of the merged namespace is detected at the
+        # codegen combine point (see {ServerFunctions.write_v2_snapshot!}).
+        def detect_collisions!(entries)
+          entries.group_by { |entry| entry["js_identifier"] }.each do |js_id, group|
+            next if group.size < 2
+
+            origins = group.map { |entry| "#{entry['controller']}##{entry['action']}" }
+            raise Ruact::ConfigurationError,
+                  "server-function naming collision: #{origins.join(' and ')} " \
+                  "both map to JS identifier \"#{js_id}\" — rename one of the query methods."
+          end
+        end
+
+        # `/q/categories(.:format)` → `/q/categories`. Mirrors
+        # {RouteSource#clean_path}: drops the trailing format optional and any
+        # remaining optional `( … )` group.
+        def clean_path(route)
+          spec = route.path.spec.to_s
+          spec = spec.delete_suffix("(.:format)")
+          spec.gsub(/\([^)]*\)/, "")
+        end
+
+        # Real resolver — used in the railtie/rake paths. The generated query
+        # dispatch controller exposes `__ruact_query_class` (a singleton method
+        # set by {QueryDispatch.controller_for}); resolve the controller
+        # constant from its path and read that back.
+        def default_query_class_for(controller)
+          klass = "#{controller}_controller".camelize.safe_constantize
+          return nil unless klass.respond_to?(:__ruact_query_class)
+
+          klass.__ruact_query_class
+        rescue StandardError
+          nil
+        end
+      end
+    end
+  end
+end

data/lib/ruact/server_functions/registry.rb

@@ -0,0 +1,148 @@
+# frozen_string_literal: true
+
+module Ruact
+  module ServerFunctions
+    # In-memory storage for server-function entries. One instance backs
+    # `Ruact.action_registry`; another backs `Ruact.query_registry` — kept
+    # separate so the JSON snapshot can emit a `kind` field per entry without
+    # the call sites having to thread an extra parameter through. Cross-registry
+    # JS-identifier collisions are detected by {Ruact::ServerFunctions::Snapshot}
+    # at snapshot time (a single registry only sees its own entries).
+    #
+    # Thread-safety: not thread-safe by design. Registration happens at
+    # controller-class load time (`config.to_prepare` in dev, eager-load in
+    # production), single-threaded. Reads from {#entries} return a frozen
+    # snapshot of the internal hash so concurrent readers cannot observe a
+    # partial registration.
+    class Registry
+      # The only kinds the codegen knows how to emit. Story 8.1 owns `:action`,
+      # Story 9.1 owns `:query`. Any other value is rejected at registration
+      # time — silent acceptance would otherwise let an unknown kind fall
+      # through and be emitted as an action signature.
+      ALLOWED_KINDS = %i[action query].freeze
+
+      def initialize
+        @entries = {}
+      end
+
+      # Adds +symbol+ to the registry.
+      #
+      # @param symbol [Symbol] the Ruby identifier (snake_case).
+      # @param kind [Symbol] `:action` or `:query`. Other values raise.
+      # @param controller [Class, nil] the controller class registering the
+      #   function. Used in collision-error messages.
+      # @yield the implementation body; stored verbatim for Story 8.1 / 9.1 to
+      #   invoke. May be nil for Story 8.0a's bootstrap (registries are empty
+      #   until 8.1 and 9.1 land).
+      # @return [Ruact::ServerFunctions::RegistryEntry] the entry just inserted.
+      # @raise [Ruact::ConfigurationError] when +symbol+ fails the naming-bridge
+      #   rule, when +kind+ is not in {ALLOWED_KINDS}, or when a different Ruby
+      #   symbol already maps to the same JS identifier in THIS registry. Cross-
+      #   registry collisions (one action + one query sharing a JS identifier)
+      #   are detected later by {Ruact::ServerFunctions::Snapshot.functions_payload}.
+      def register(symbol, kind:, controller: nil, &block)
+        validate_kind!(symbol, kind, controller)
+        js_identifier = translate_symbol(symbol, controller)
+        detect_collision!(symbol, js_identifier, controller)
+
+        entry = RegistryEntry.new(
+          ruby_symbol: symbol,
+          js_identifier: js_identifier,
+          kind: kind,
+          controller: controller,
+          block: block
+        )
+        @entries[symbol] = entry
+        entry
+      end
+
+      # @return [Hash{Symbol => Ruact::ServerFunctions::RegistryEntry}] frozen
+      #   snapshot of the current entries, ordered by insertion.
+      def entries
+        @entries.dup.freeze
+      end
+
+      # Wipes the registry. Used by `config.to_prepare` (between dev reloads) and
+      # by tests that need a clean slate.
+      #
+      # @return [self]
+      def clear!
+        @entries.clear
+        self
+      end
+
+      # @return [Integer] number of registered entries.
+      def size
+        @entries.size
+      end
+
+      # @return [Boolean] whether the registry has no entries.
+      def empty?
+        @entries.empty?
+      end
+
+      private
+
+      def validate_kind!(symbol, kind, controller)
+        return if ALLOWED_KINDS.include?(kind)
+
+        raise Ruact::ConfigurationError,
+              "invalid server-function symbol :#{symbol} in #{describe_controller(controller)}: " \
+              "kind #{kind.inspect} is not one of #{ALLOWED_KINDS.inspect}"
+      end
+
+      # Wraps the NameBridge call to attach controller context to the raised
+      # error (the AC7 "invalid server-function symbol :SYMBOL in CONTROLLER"
+      # shape). NameBridge itself is controller-agnostic; the wrap lives at the
+      # registry boundary because that is where controller context exists.
+      def translate_symbol(symbol, controller)
+        NameBridge.to_js_identifier(symbol)
+      rescue Ruact::ConfigurationError => e
+        raise Ruact::ConfigurationError,
+              "invalid server-function symbol :#{symbol} in #{describe_controller(controller)} — #{e.message}"
+      end
+
+      def detect_collision!(symbol, js_identifier, controller)
+        # Re-run-3 (2026-05-15) — TWO failure shapes:
+        #
+        # (a) Different Ruby symbols, same JS identifier (`:foo_bar` and
+        #     `:fooBar` both → "fooBar"). Filtered by `js_identifier ==`.
+        # (b) Same Ruby symbol declared on TWO different controllers
+        #     (e.g., `ruact_action :create_post` in both `PostsController`
+        #     AND `AdminPostsController`). Pre-batch this silently
+        #     overwrote `@entries[symbol]` with the last-loaded one, so
+        #     dispatch routed to whichever controller Zeitwerk happened
+        #     to load last — non-deterministic in dev, surprise breakage
+        #     when refactoring. Detect by checking the existing entry's
+        #     `controller` against the one trying to register.
+        existing = @entries[symbol]
+        if existing && existing.controller != controller
+          raise Ruact::ConfigurationError,
+                "server-function naming collision: " \
+                ":#{symbol} is declared in BOTH " \
+                "#{describe_controller(existing.controller)} and " \
+                "#{describe_controller(controller)}. Each `ruact_action` " \
+                "symbol must be unique across the whole registry — pick a " \
+                "more specific name (e.g. :admin_create_post) on one side."
+        end
+
+        collision = @entries.values.find do |e|
+          e.js_identifier == js_identifier && e.ruby_symbol != symbol
+        end
+        return unless collision
+
+        raise Ruact::ConfigurationError,
+              "server-function naming collision: " \
+              ":#{symbol} (in #{describe_controller(controller)}) and " \
+              ":#{collision.ruby_symbol} (in #{describe_controller(collision.controller)}) " \
+              "both map to JS identifier \"#{js_identifier}\""
+      end
+
+      def describe_controller(controller)
+        return "unknown controller" if controller.nil?
+
+        controller.respond_to?(:name) && controller.name ? controller.name : controller.inspect
+      end
+    end
+  end
+end