ruact 0.0.1 → 0.0.3

data/spec/ruact/server_functions/railtie_integration_spec.rb

@@ -0,0 +1,345 @@
+# frozen_string_literal: true
+
+require "spec_helper"
+require "tmpdir"
+require "fileutils"
+require "action_controller"
+
+# Spec_helper's rails_stub defines Rails; the railtie was not auto-required
+# because Rails was not yet defined when ruact.rb evaluated `require_relative
+# "ruact/railtie" if defined?(Rails)`. Load it explicitly (mirrors
+# spec/ruact/railtie_spec.rb).
+require "ruact/railtie"
+require "ruact/controller"
+require "ruact/server"
+
+# Story 8.0a — Railtie.write_server_functions_snapshot! is the entry point
+# wired into `config.to_prepare`. The full to_prepare boot lives in
+# controller_request_spec.rb; here we exercise the class method directly with
+# Rails.root pointed at a tmpdir, which is enough to validate the contract
+# (Story 8.0a Task 2.6 — Railtie path resolution + write-if-changed).
+module Ruact
+  module ServerFunctions
+    RSpec.describe "Ruact::Railtie.write_server_functions_snapshot!", :story_8_0a do
+      around do |example|
+        Dir.mktmpdir do |dir|
+          original_root = Rails.root
+          Rails.root    = Pathname.new(dir)
+          @tmpdir       = dir
+          example.run
+        ensure
+          Rails.root = original_root
+        end
+      end
+
+      let(:path) { File.join(@tmpdir, "tmp/cache/ruact/server-functions.json") }
+
+      it "writes the JSON to tmp/cache/ruact/server-functions.json (Story 8.0a)" do
+        result = Ruact::Railtie.write_server_functions_snapshot!
+        expect(result).to be(true)
+        expect(File).to exist(path)
+      end
+
+      it "writes an empty `functions: []` array when both registries are empty " \
+         "(Story 8.0a — empty-registry contract)" do
+        Ruact::Railtie.write_server_functions_snapshot!
+        parsed = JSON.parse(File.read(path))
+        expect(parsed.fetch("functions")).to eq([])
+      end
+
+      it "the file is short-circuited on a second call with an unchanged registry " \
+         "(Story 8.0a — pitfall #1)" do
+        Ruact::Railtie.write_server_functions_snapshot!
+        expect(Ruact::Railtie.write_server_functions_snapshot!).to be(false)
+      end
+
+      it "rewrites the file after a registration is added (Story 8.0a)" do
+        Ruact::Railtie.write_server_functions_snapshot!
+        Ruact.action_registry.register(:demo_ping, kind: :action)
+
+        expect(Ruact::Railtie.write_server_functions_snapshot!).to be(true)
+        parsed = JSON.parse(File.read(path))
+        expect(parsed["functions"].map { |fn| fn["ruby_symbol"] }).to eq(["demo_ping"])
+      end
+    end
+
+    RSpec.describe "Ruact::ServerFunctions.write_v2_snapshot! (Story 9.3)", :story_9_3 do
+      # A real Ruact::Server host so RouteSource's default constant-resolving
+      # host predicate recognizes it; stub_const (not a literal class) keeps the
+      # file single-definition and the constant scoped to the example.
+      before do
+        stub_const("V2DemoPostsController", Class.new(ActionController::Base) { include Ruact::Server })
+      end
+
+      around do |example|
+        Dir.mktmpdir { |dir| @tmpdir = dir and example.run }
+      end
+
+      def route_set
+        rs = ActionDispatch::Routing::RouteSet.new
+        rs.draw { resources :v2_demo_posts, only: %i[create update destroy] }
+        rs
+      end
+
+      def write!(logger: nil)
+        Ruact::ServerFunctions.write_v2_snapshot!(
+          route_set: route_set, root: Pathname.new(@tmpdir), logger: logger
+        )
+      end
+
+      let(:next_json) { File.join(@tmpdir, "tmp/cache/ruact/server-functions.next.json") }
+      let(:next_ts)   { File.join(@tmpdir, "app/javascript/.ruact/server-functions.next.ts") }
+      let(:real_json) { File.join(@tmpdir, "tmp/cache/ruact/server-functions.json") }
+
+      it "writes the v2 bridge + TS to the PARALLEL .next target (not the real file)" do
+        entries = write!
+
+        expect(entries.map { |e| e["js_identifier"] })
+          .to match_array(%w[createV2DemoPost updateV2DemoPost destroyV2DemoPost])
+        expect(File).to exist(next_json)
+        expect(File).to exist(next_ts)
+        # AC5/AC6 — the v1 real bridge is NOT written by the v2 path.
+        expect(File).not_to exist(real_json)
+        expect(JSON.parse(File.read(next_json)).fetch("version")).to eq(2)
+      end
+
+      it "renders _makeServerFunction calls targeting real routes into the .next TS" do
+        write!
+        ts = File.read(next_ts)
+        expect(ts).to include('import { _makeServerFunction } from "ruact/server-functions-runtime";')
+        expect(ts).to include('_makeServerFunction({ method: "POST", path: "/v2_demo_posts", segments: [] });')
+        expect(ts).to include('_makeServerFunction({ method: "PATCH", path: "/v2_demo_posts/:id", segments: ["id"] });')
+      end
+
+      it "is byte-stable across calls on an unchanged route table (no churn)" do
+        write!
+        first = File.read(next_ts)
+        write!
+        expect(File.read(next_ts)).to eq(first)
+      end
+
+      it "logs the exposed function names (AC2 — transparency over silence)" do
+        logger = instance_double(Logger, info: nil)
+        write!(logger: logger)
+        expect(logger).to have_received(:info).with(/\[ruact\] codegen: exposing .*createV2DemoPost/)
+      end
+    end
+
+    RSpec.describe "Ruact::Railtie registry-clear hook (Story 8.1)", :story_8_1 do
+      # The Railtie attaches a `before_class_unload` callback that clears both
+      # registries before Zeitwerk tears down constants — this prevents removed
+      # `ruact_action` declarations from lingering across reloads. The full
+      # Rails-app boot covering the controller class-body re-evaluation lives
+      # in `controller_request_spec.rb`; here we exercise the hook directly.
+      before do
+        Ruact.action_registry.clear!
+        Ruact.query_registry.clear!
+      end
+
+      it "clears both registries when invoked" do
+        Ruact.action_registry.register(:foo, kind: :action)
+        Ruact.query_registry.register(:bar, kind: :query)
+        expect(Ruact.action_registry.size).to eq(1)
+        expect(Ruact.query_registry.size).to eq(1)
+
+        # Direct invocation of the cleanup that the reloader hook would run.
+        Ruact.action_registry.clear!
+        Ruact.query_registry.clear!
+
+        expect(Ruact.action_registry.size).to eq(0)
+        expect(Ruact.query_registry.size).to eq(0)
+      end
+
+      it "the snapshot write-if-changed guard skips a rewrite when controllers " \
+         "re-register the same symbols after a clear (Story 8.1 — pitfall #1 mitigation)" do
+        Dir.mktmpdir do |dir|
+          original_root = Rails.root
+          Rails.root = Pathname.new(dir)
+
+          Ruact.action_registry.register(:create_post, kind: :action)
+          Ruact::Railtie.write_server_functions_snapshot!
+          original_bytes = File.read(File.join(dir, "tmp/cache/ruact/server-functions.json"))
+
+          # Simulate a reload cycle: clear, then re-register the same symbol
+          # with a fresh class object (the same as what would happen when
+          # controller class bodies re-evaluate after Zeitwerk teardown).
+          Ruact.action_registry.clear!
+          Ruact.action_registry.register(:create_post, kind: :action)
+
+          expect(Ruact::Railtie.write_server_functions_snapshot!).to be(false)
+          expect(File.read(File.join(dir, "tmp/cache/ruact/server-functions.json"))).to eq(original_bytes)
+        ensure
+          Rails.root = original_root
+        end
+      end
+    end
+
+    # Story 8.1 Re-run-6/8 — force_load_controllers! now walks Rails::Engine
+    # subclasses so engine-owned `ruact_action` declarations populate the
+    # registry at boot (not on first request to the engine controller).
+    # The regression target: a mounted engine that declares its own controller
+    # with `ruact_action :engine_action` must be visible to the snapshot
+    # writer + endpoint dispatcher BEFORE any HTTP traffic.
+    RSpec.describe "Ruact::Railtie.force_load_controllers! engine scanning (Story 8.1)", :story_8_1 do
+      before do
+        Ruact.action_registry.clear!
+        Ruact.query_registry.clear!
+
+        # In a real Rails boot, `require_dependency` is added to `Object` by
+        # `ActiveSupport::Dependencies.hook!` before `config.to_prepare`
+        # fires. The minimal spec-env setup (rails_stub + action_controller
+        # core) does not invoke the hook, so we stub the call directly to
+        # delegate to plain `load(file)` — which is sufficient to exercise
+        # the engine-scanning branch without dragging the full dependencies
+        # subsystem into the suite.
+        allow(Ruact::Railtie).to receive(:force_load_dir).and_wrap_original do |_original, dir|
+          files = Dir.glob("#{dir}/**/*_controller.rb")
+          files.each { |file| load(file) }
+          files.length
+        end
+      end
+
+      it "loads ruact_action declarations from a mounted Rails::Engine's app/controllers " \
+         "(re-run-6 #4 / re-run-8 #2 — engine-owned controllers must populate the registry at boot)" do
+        Dir.mktmpdir do |engine_dir|
+          # Build the engine's controller file on disk. The file's body
+          # declares a real `ruact_action` so populating the registry is
+          # observable (no mocks of the macro itself).
+          controllers_dir = File.join(engine_dir, "app/controllers")
+          FileUtils.mkdir_p(controllers_dir)
+          controller_path = File.join(controllers_dir, "engine_demo_controller.rb")
+          File.write(controller_path, <<~RUBY)
+            # frozen_string_literal: true
+
+            class EngineDemoController < ActionController::Base
+              include Ruact::Controller
+
+              ruact_action(:engine_only_action) { |_params| "from-engine" }
+            end
+          RUBY
+
+          # Build a real Rails::Engine subclass whose paths["app/controllers"]
+          # points at the on-disk controllers directory. `Engine#paths` is
+          # automatically populated by Rails.
+          fake_engine = Class.new(Rails::Engine) do
+            isolate_namespace Module.new
+            config.paths["app/controllers"] = controllers_dir
+          end
+
+          # Stub Rails::Engine.subclasses to return JUST our fake engine — the
+          # host app's own engine class is filtered out inside
+          # force_load_controllers! by an explicit `engine_class ==
+          # Rails.application.class` skip.
+          allow(Rails::Engine).to receive(:subclasses).and_return([fake_engine])
+
+          expect { Ruact::Railtie.force_load_controllers! }.not_to raise_error
+          expect(Ruact.action_registry.entries[:engine_only_action]).not_to be_nil
+          expect(Ruact.action_registry.entries[:engine_only_action].controller).to be(EngineDemoController)
+        end
+      ensure
+        # `EngineDemoController` is loaded via `require_dependency` against an
+        # absolute on-disk path; remove the constant so re-runs of the spec
+        # don't trip the macro's "method already defined" guard.
+        Object.send(:remove_const, :EngineDemoController) if defined?(EngineDemoController)
+      end
+
+      it "skips the host application's own Rails::Engine subclass " \
+         "(avoids double-loading app/controllers already covered by the Rails.application branch)" do
+        # Rails.application.class IS a Rails::Engine subclass; force_load_controllers!
+        # iterates the host app FIRST via the application branch, then skips it
+        # explicitly in the engine branch. Confirm that filtering happens.
+        host_class = Rails.application.class
+        allow(Rails::Engine).to receive(:subclasses).and_return([host_class])
+
+        # We expect ZERO additional load operations from the engine branch
+        # because the only subclass is the host app itself.
+        expect(Ruact::Railtie).not_to receive(:safe_engine_instance)
+
+        expect { Ruact::Railtie.force_load_controllers! }.not_to raise_error
+      end
+
+      it "swallows a misconfigured engine (engine_class.instance raising) " \
+         "via safe_engine_instance so a single broken engine cannot block boot" do
+        bad_engine = Class.new(Rails::Engine)
+        allow(bad_engine).to receive(:instance).and_raise(StandardError, "engine boot failed")
+        allow(Rails::Engine).to receive(:subclasses).and_return([bad_engine])
+
+        # Must not propagate; force_load_controllers! returns normally.
+        expect { Ruact::Railtie.force_load_controllers! }.not_to raise_error
+      end
+    end
+
+    # Story 8.3 — force_load_server_function_hosts! ALSO walks
+    # `app/server_actions/**/*.rb` so standalone modules register at boot
+    # alongside controller-hosted actions. Follows the Story 8.1 fake-engine
+    # pattern to bypass Rails.application's sticky root memoization.
+    RSpec.describe "Ruact::Railtie.force_load_server_function_hosts! " \
+                   "app/server_actions/ scanning (Story 8.3)", :story_8_3 do
+      before do
+        Ruact.action_registry.clear!
+        Ruact.query_registry.clear!
+
+        # Same stub as the Story 8.1 engine-scanning describe — substitutes
+        # `require_dependency` (unavailable in the minimal spec env) with
+        # plain `load`. Accepts both `dir` (positional) and `glob:` (kwarg).
+        allow(Ruact::Railtie).to receive(:force_load_dir).and_wrap_original do |_original, dir, glob: "**/*_controller.rb"|
+          files = Dir.glob("#{dir}/#{glob}")
+          files.each { |file| load(file) }
+          files.length
+        end
+      end
+
+      it "loads ruact_action declarations from app/server_actions/ at boot " \
+         "(Pitfall #7 — standalone modules must register before the snapshot writer runs)" do
+        Dir.mktmpdir do |engine_dir|
+          server_actions_dir = File.join(engine_dir, "app/server_actions")
+          FileUtils.mkdir_p(server_actions_dir)
+          module_path = File.join(server_actions_dir, "standalone_railtie_demo.rb")
+          File.write(module_path, <<~RUBY)
+            # frozen_string_literal: true
+
+            module StandaloneRailtieDemo
+              extend Ruact::ServerAction
+
+              ruact_action(:standalone_railtie_demo) { |_p| "from-standalone" }
+            end
+          RUBY
+
+          fake_engine = Class.new(Rails::Engine) do
+            isolate_namespace Module.new
+            # Register the path explicitly so `server_actions_paths_for`
+            # finds it via the Rails paths enumerator.
+            config.paths.add "app/server_actions", with: server_actions_dir
+          end
+
+          # Stub Rails::Engine.subclasses to expose ONLY the fake engine —
+          # the host app's own controllers/server_actions are filtered out
+          # by the engine_class == Rails.application.class skip inside
+          # force_load_server_function_hosts!.
+          allow(Rails::Engine).to receive(:subclasses).and_return([fake_engine])
+
+          expect { Ruact::Railtie.force_load_server_function_hosts! }.not_to raise_error
+
+          entry = Ruact.action_registry.entries[:standalone_railtie_demo]
+          expect(entry).not_to be_nil
+          expect(entry.controller).to be(StandaloneRailtieDemo)
+          expect(entry.controller).to be_a(Module)
+          expect(entry.controller).not_to be_a(Class)
+        end
+      ensure
+        Object.send(:remove_const, :StandaloneRailtieDemo) if defined?(StandaloneRailtieDemo)
+      end
+
+      it "silently no-ops when no engine has an app/server_actions/ directory " \
+         "(typical for apps that only use controller-hosted actions)" do
+        allow(Rails::Engine).to receive(:subclasses).and_return([])
+        expect { Ruact::Railtie.force_load_server_function_hosts! }.not_to raise_error
+      end
+
+      it "back-compat: the old `force_load_controllers!` name aliases to the new method" do
+        expect(Ruact::Railtie.method(:force_load_controllers!).original_name)
+          .to eq(:force_load_server_function_hosts!)
+      end
+    end
+  end
+end

data/spec/ruact/server_functions/rake_spec.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+require "spec_helper"
+require "rake"
+require "tmpdir"
+require "fileutils"
+
+# Story 8.0a — exercises `rake ruact:server_functions:generate` end-to-end:
+# the task's body runs against a tmpdir as Rails.root, stubs the
+# :environment dependency, and asserts that:
+#   1. The JSON bridge is written to tmp/cache/ruact/.
+#   2. The TypeScript module is written to app/javascript/.ruact/.
+#   3. Re-running the task is idempotent (no rewrites on unchanged registry).
+#   4. ConfigurationError surfaces with a non-zero exit and a `[ruact] error:` line.
+module Ruact
+  module ServerFunctions
+    RSpec.describe "rake ruact:server_functions:generate", :story_8_0a do
+      around do |example|
+        Dir.mktmpdir do |dir|
+          original_root = Rails.root
+          Rails.root    = Pathname.new(dir)
+          @tmpdir       = dir
+
+          prev = Rake.application
+          Rake.application = Rake::Application.new
+          Rake.application.define_task(Rake::Task, :environment)
+          load File.expand_path("../../../lib/tasks/ruact.rake", __dir__)
+
+          example.run
+        ensure
+          Rake.application = prev
+          Rails.root       = original_root
+        end
+      end
+
+      let(:json_path) { File.join(@tmpdir, "tmp/cache/ruact/server-functions.json") }
+      let(:ts_path)   { File.join(@tmpdir, "app/javascript/.ruact/server-functions.ts") }
+
+      def invoke!
+        Rake::Task["ruact:server_functions:generate"].reenable
+        Rake::Task["ruact:server_functions:generate"].invoke
+      end
+
+      it "registers the task under the documented name (Story 8.0a)" do
+        expect(Rake.application.lookup("ruact:server_functions:generate")).not_to be_nil
+      end
+
+      it "writes both the JSON bridge and the TS module on first run (Story 8.0a)",
+         :aggregate_failures do
+        invoke!
+        expect(File).to exist(json_path)
+        expect(File).to exist(ts_path)
+        expect(File.read(ts_path)).to include("// AUTO-GENERATED by vite-plugin-ruact")
+      end
+
+      it "is idempotent: a second run does not change file contents (Story 8.0a)" do
+        invoke!
+        before = File.read(ts_path)
+        invoke!
+        expect(File.read(ts_path)).to eq(before)
+      end
+
+      it "produces the byte-identical TS module to Codegen.render (Story 8.0a AC7)" do
+        Ruact.action_registry.register(:demo_ping, kind: :action)
+        invoke!
+
+        snapshot = Snapshot.dump(Ruact.action_registry, Ruact.query_registry,
+                                 now: Time.parse(JSON.parse(File.read(json_path))["generated_at"]))
+        expect(File.read(ts_path)).to eq(Codegen.render(snapshot))
+      end
+
+      it "exits 1 with a `[ruact] error:` line when the registry has an invalid symbol " \
+         "(Story 8.0a — rake error reporting)" do
+        # Inject a bad entry by bypassing the registry's validation (the
+        # naming-bridge raises on .register; we want to verify what happens
+        # when an invalid entry slipped through and the task re-validates).
+        allow(Snapshot).to receive(:generate!)
+          .and_raise(Ruact::ConfigurationError,
+                     "ruact_action / ruact_query symbol :RECALCULATE must match /^[a-z_][a-z0-9_]*$/")
+        expect { invoke! }
+          .to raise_error(SystemExit)
+          .and output(/\[ruact\] error:.*RECALCULATE/).to_stderr
+      end
+    end
+  end
+end

data/spec/ruact/server_functions/registry_spec.rb

@@ -0,0 +1,199 @@
+# frozen_string_literal: true
+
+require "spec_helper"
+
+module Ruact
+  module ServerFunctions
+    RSpec.describe Registry, :story_8_0a do
+      subject(:registry) { described_class.new }
+
+      let(:posts_controller) do
+        Class.new { def self.name = "PostsController" }
+      end
+
+      let(:bar_controller) do
+        Class.new { def self.name = "BarController" }
+      end
+
+      describe "#register (Story 8.0a)" do
+        it "stores a single entry keyed by its Ruby symbol", :aggregate_failures do
+          entry = registry.register(:create_post, kind: :action, controller: posts_controller)
+
+          expect(entry).to be_a(RegistryEntry)
+          expect(entry.ruby_symbol).to eq(:create_post)
+          expect(entry.js_identifier).to eq("createPost")
+          expect(entry.kind).to eq(:action)
+          expect(entry.controller).to eq(posts_controller)
+          expect(registry.entries.keys).to eq([:create_post])
+        end
+
+        it "captures the implementation block verbatim for downstream invocation" do
+          block = -> { :pong }
+          entry = registry.register(:demo_ping, kind: :action, controller: posts_controller, &block)
+          expect(entry.block).to be(block)
+        end
+
+        it "allows registering an action and a query with the same symbol in separate registries" do
+          actions = described_class.new
+          queries = described_class.new
+          actions.register(:create_post, kind: :action, controller: posts_controller)
+          queries.register(:create_post, kind: :query, controller: posts_controller)
+          expect(actions.entries.keys).to eq([:create_post])
+          expect(queries.entries.keys).to eq([:create_post])
+        end
+
+        it "raises Ruact::ConfigurationError for SCREAMING_SNAKE symbols (Story 8.0a)" do
+          expect { registry.register(:RECALCULATE, kind: :action, controller: posts_controller) }
+            .to raise_error(Ruact::ConfigurationError) do |error|
+              expect(error.message).to include(":RECALCULATE")
+            end
+        end
+
+        it "raises Ruact::ConfigurationError on JS-identifier collision and names both " \
+           "Ruby symbols and both controllers (Story 8.0a)", :aggregate_failures do
+          registry.register(:foo_bar, kind: :action, controller: posts_controller)
+          expect { registry.register(:foo__bar, kind: :action, controller: bar_controller) }
+            .to raise_error(Ruact::ConfigurationError) do |error|
+              expect(error.message).to include(":foo_bar")
+              expect(error.message).to include(":foo__bar")
+              expect(error.message).to include("PostsController")
+              expect(error.message).to include("BarController")
+              expect(error.message).to include('"fooBar"')
+            end
+        end
+
+        it "allows re-registering the same Ruby symbol (replace semantics, dev reload)" do
+          registry.register(:create_post, kind: :action, controller: posts_controller)
+          expect do
+            registry.register(:create_post, kind: :action, controller: posts_controller)
+          end.not_to raise_error
+          expect(registry.size).to eq(1)
+        end
+
+        it "tolerates a nil controller (Rails-console registration path)" do
+          expect { registry.register(:create_post, kind: :action) }.not_to raise_error
+        end
+
+        it "rejects kinds other than :action / :query (Chunk1 Major 2026-05-13)" do
+          expect { registry.register(:create_post, kind: :wat, controller: posts_controller) }
+            .to raise_error(Ruact::ConfigurationError) do |error|
+              expect(error.message).to include(":create_post")
+              expect(error.message).to include("PostsController")
+              expect(error.message).to include(":wat")
+              expect(error.message).to include("[:action, :query]")
+            end
+        end
+
+        it "wraps NameBridge symbol-shape failures with AC7 'invalid server-function " \
+           "symbol :SYMBOL in CONTROLLER' framing (Re-run patch m5)" do
+          expect { registry.register(:RECALCULATE, kind: :action, controller: posts_controller) }
+            .to raise_error(Ruact::ConfigurationError) do |error|
+              expect(error.message).to start_with("invalid server-function symbol :RECALCULATE in PostsController")
+            end
+        end
+      end
+
+      describe "#entries (Story 8.0a)" do
+        it "returns a frozen snapshot independent of subsequent mutations" do
+          registry.register(:create_post, kind: :action, controller: posts_controller)
+          snapshot = registry.entries
+          expect(snapshot).to be_frozen
+          registry.register(:list_posts, kind: :query, controller: posts_controller)
+          expect(snapshot.keys).to eq([:create_post])
+        end
+      end
+
+      describe "#clear! (Story 8.0a)" do
+        it "wipes all entries and returns self" do
+          registry.register(:create_post, kind: :action, controller: posts_controller)
+          expect(registry.clear!).to be(registry)
+          expect(registry).to be_empty
+        end
+      end
+
+      describe "Story 8.3 — mixed controller+standalone collision", :story_8_3 do
+        let(:posts_controller_class) do
+          Class.new { def self.name = "PostsController" }
+        end
+
+        let(:standalone_create_post_module) do
+          Module.new do
+            extend Ruact::ServerAction
+
+            def self.name
+              "CreatePost"
+            end
+          end
+        end
+
+        it "raises Ruact::ConfigurationError when the same Ruby symbol is declared in a controller " \
+           "AND in a standalone module — message names BOTH hosts" do
+          registry.register(:create_post, kind: :action, controller: posts_controller_class)
+
+          expect do
+            registry.register(:create_post, kind: :action, controller: standalone_create_post_module)
+          end.to raise_error(Ruact::ConfigurationError) do |error|
+            expect(error.message).to include(":create_post")
+            expect(error.message).to include("PostsController")
+            expect(error.message).to include("CreatePost")
+            expect(error.message).to include("declared in BOTH")
+          end
+        end
+
+        it "raises Ruact::ConfigurationError when the same symbol is declared in standalone " \
+           "first, then in a controller (order-independent)" do
+          registry.register(:create_post, kind: :action, controller: standalone_create_post_module)
+
+          expect do
+            registry.register(:create_post, kind: :action, controller: posts_controller_class)
+          end.to raise_error(Ruact::ConfigurationError) do |error|
+            expect(error.message).to include("PostsController")
+            expect(error.message).to include("CreatePost")
+          end
+        end
+
+        it "describe_controller names a Module host correctly (no inspection fallback) " \
+           "when one side of the collision is a Module" do
+          registry.register(:create_post, kind: :action, controller: standalone_create_post_module)
+          another_module = Module.new do
+            extend Ruact::ServerAction
+
+            def self.name
+              "AdminCreatePost"
+            end
+          end
+
+          # Cross-bridge JS-identifier collision: two DIFFERENT Ruby symbols
+          # producing the SAME JS identifier — bridges into `js_identifier ==`
+          # branch of detect_collision!. The bridge collapses underscores,
+          # so `:create_post` and `:create__post` both → "createPost".
+          expect do
+            registry.register(:create__post, kind: :action, controller: another_module)
+          end.to raise_error(Ruact::ConfigurationError) do |error|
+            expect(error.message).to include("CreatePost")
+            expect(error.message).to include("AdminCreatePost")
+            expect(error.message).to include('"createPost"')
+          end
+        end
+      end
+
+      describe "Ruact module-level accessors (Story 8.0a)" do
+        it "returns two independent Registry singletons" do
+          expect(Ruact.action_registry).to be_a(described_class)
+          expect(Ruact.query_registry).to be_a(described_class)
+          expect(Ruact.action_registry).not_to equal(Ruact.query_registry)
+        end
+
+        it "memoizes the same instance across calls" do
+          expect(Ruact.action_registry).to equal(Ruact.action_registry)
+          expect(Ruact.query_registry).to equal(Ruact.query_registry)
+        end
+
+        it "both registries are empty at boot (Story 8.1 / 9.1 populate them)" do
+          expect(Ruact.action_registry).to be_empty
+          expect(Ruact.query_registry).to be_empty
+        end
+      end
+    end
+  end
+end