ruact 0.0.7 → 0.0.8

data/lib/ruact/erb_preprocessor.rb

@@ -28,6 +28,29 @@ module Ruact
     SUSPENSE_OPEN_RE  = /<Suspense\b([^>]*?)>/m
     SUSPENSE_CLOSE_RE = %r{</Suspense>}
 
+    # Story 15.2 (FR106) — matches ANY PascalCase component tag: opening
+    # (`<Card>`), self-closing (`<Card />`), or closing (`</Card>`). Capture 1 is
+    # the leading slash (present only on a closing tag); capture 2 is the name.
+    # The loud-children detection scans these left-to-right with a stack: an
+    # opening pushes, a self-closing (`/>`) is ignored, and a closing that pops a
+    # matching opening means that opening had children (paired usage) → loud
+    # error. A single linear pass (no backreference/lazy backtracking) keeps the
+    # component-dense fast path linear regardless of how many tags go unclosed.
+    COMPONENT_ANY_TAG_RE = %r{<(/)?([A-Z][A-Za-z0-9]*)(?:\s[^>]*)?>}
+
+    # Cheap allocation-free probe (`String#match?`) for "is there ANY PascalCase
+    # closing tag at all?". The loud-children scan only matters when one exists,
+    # so this gates the (copy-heavy) mask/scan work off the common all-self-
+    # closing fast path. `</Suspense>` matches too — harmless, it gets masked.
+    CLOSING_TAG_PROBE_RE = %r{</[A-Z][A-Za-z0-9]*>}
+
+    # Newline-preserving mask for ERB islands (`<% … %>`, `<%= … %>`, `<%# … %>`).
+    # The loud-children scan blanks these first so a `</Card>` that lives inside
+    # Ruby/ERB string or comment text can never be mistaken for a real component
+    # closing tag (a valid bare `<Dialog>` opening must not error because some
+    # unrelated `<% "</Dialog>" %>` appears later).
+    ERB_ISLAND_RE = /<%.*?%>/m
+
     # Matches a +{ruby_expr}+ attribute value — captures everything between the braces.
     # We use a simple bracket-depth counter approach during scanning instead of regex
     # because expressions can contain nested braces: {foo.bar({ a: 1 })}.
@@ -66,6 +89,16 @@ module Ruact
                end
         .gsub(SUSPENSE_CLOSE_RE, "</ruact-suspense>")
 
+      # Step 1.5 (Story 15.2 / FR106): before the general component pass, fail
+      # loudly if any PascalCase component tag is used with children (a matching
+      # closing tag). Silent degradation of `<Card>Hello</Card>` — the #1
+      # predictable JSX-habit mistake — becomes a self-contained, re-raised-as-is
+      # PreprocessorError naming the fix. It scans the ORIGINAL +source+ (so
+      # file:line is exact) and masks Suspense (the one legitimate paired
+      # PascalCase tag) newline-for-newline, so `<Suspense>...</Suspense>` can
+      # never trip and every reported line matches the template verbatim.
+      detect_children!(source, identifier)
+
       # Step 2: transform remaining PascalCase self-closing / opening component tags.
       result.gsub(COMPONENT_TAG_RE) do |match|
         component_name = ::Regexp.last_match(1)
@@ -99,6 +132,86 @@ module Ruact
 
     private
 
+    # Story 15.2 (FR106) — raise a loud, self-contained {ChildrenNotSupportedError}
+    # on the FIRST PascalCase component tag used with children (a matching closing
+    # tag). +source+ is the ORIGINAL template text; +identifier+ is the template
+    # path (from {ErbPreprocessorHook}). Suspense — the one legitimate paired
+    # PascalCase tag — is masked newline-for-newline first, so it never trips AND
+    # every byte position (hence every reported line) still lines up with the raw
+    # template. The line uses the same idiom as Step 2 (`count("\n") + 1`) on the
+    # OPENING tag's offset. Message mirrors {ComponentContract.raise_error} shape
+    # so both loud preprocess errors read identically. A no-op when no pair is
+    # present — the fast path stays byte-identical.
+    def detect_children!(source, identifier)
+      # Fast path: a children pair REQUIRES a literal PascalCase closing tag, so
+      # a source without one (the common all-self-closing case) can never trip —
+      # bail before allocating anything. `match?` builds no MatchData, and this
+      # skips the mask/scan copies entirely, keeping the hot render/preprocess
+      # path's allocation profile flat (the benchmark renders only self-closing
+      # components, so it must stay at baseline).
+      return unless source.match?(CLOSING_TAG_PROBE_RE)
+
+      # ERB islands first, then Suspense — both blank their text newline-for-
+      # newline so byte offsets (hence reported lines) still match the raw
+      # template, while neither ERB string text nor the legitimate Suspense pair
+      # can be seen by the tag scan.
+      scan = mask_suspense(mask_erb(source))
+      # PER-NAME open stacks (name → [offsets]) so a closing tag checks for a
+      # matching open in O(1) via `open_ats[name].last`, keeping the whole scan
+      # linear even under thousands of stray/unmatched PascalCase closing tags
+      # (a global stack + `rindex` was quadratic — Codex Round 3).
+      open_ats = Hash.new { |h, k| h[k] = [] }
+
+      scan.scan(COMPONENT_ANY_TAG_RE) do
+        m    = ::Regexp.last_match
+        name = m[2]
+
+        if m[1] # a closing tag `</Name>`
+          at = open_ats[name].last
+          next unless at # stray close with no open → literal text, ignore
+
+          raise_children_error(name, identifier, scan, at)
+        elsif m[0].end_with?("/>") # self-closing → carries no children
+          next
+        else # an opening tag `<Name ...>` — record the NEAREST open of this name
+          open_ats[name] << m.begin(0)
+        end
+      end
+
+      nil
+    end
+
+    # Raise the self-contained {ChildrenNotSupportedError}. +at+ is the OPENING
+    # tag's byte offset in +scan+ (position-faithful to the raw source), so the
+    # line uses the same idiom as Step 2. Message mirrors
+    # {ComponentContract.raise_error} so both loud preprocess errors read alike.
+    def raise_children_error(component, identifier, scan, at)
+      line     = scan[0...at].count("\n") + 1
+      location = [identifier, line].compact.join(":")
+      location = "(unknown location)" if location.empty?
+      raise ChildrenNotSupportedError,
+            "ruact: <#{component}> at #{location} children are not supported " \
+            "— pass content as a prop, e.g. `<#{component} content={...} />`."
+    end
+
+    # Blank out Suspense open/close tags (the one legitimate paired PascalCase
+    # tag) while preserving EVERY newline and byte offset, so the loud-children
+    # scan neither trips on `<Suspense>...</Suspense>` nor mis-reports a line when
+    # a multi-line Suspense opening precedes the offending tag. Non-newline chars
+    # → spaces (same length); newlines kept verbatim.
+    def mask_suspense(source)
+      source
+        .gsub(SUSPENSE_OPEN_RE)  { |m| m.gsub(/[^\n]/, " ") }
+        .gsub(SUSPENSE_CLOSE_RE) { |m| m.gsub(/[^\n]/, " ") }
+    end
+
+    # Blank ERB islands (position-faithful, see {mask_suspense}) so component
+    # tags that appear only inside Ruby/ERB string or comment text are invisible
+    # to the loud-children tag scan.
+    def mask_erb(source)
+      source.gsub(ERB_ISLAND_RE) { |m| m.gsub(/[^\n]/, " ") }
+    end
+
     # Extract a string attribute value (double or single quoted) from an attrs string.
     def extract_string_attr(attrs, name)
       m = attrs.match(/\b#{Regexp.escape(name)}\s*=\s*"([^"]*)"/) ||

data/lib/ruact/errors.rb

@@ -22,6 +22,22 @@ module Ruact
   # re-wrapping it with the generic "at line N: snippet" tail.
   class ComponentContractError < PreprocessorError; end
 
+  # Story 15.2 (FR106) — raised by {Ruact::ErbPreprocessor} at preprocess time
+  # when a PascalCase component tag is used with children (a matching closing
+  # tag, e.g. `<Card>Hello</Card>`). ruact component tags are self-closing only:
+  # a component receives a props Hash, never a children element tree. This is the
+  # #1 predictable JSX-habit mistake, and it used to degrade silently (the
+  # children leaked into the surrounding HTML while the component rendered with
+  # none). Subclasses {PreprocessorError} so it flows through the same dev error
+  # overlay (NFR30 lineage) and the hook treats it uniformly — but the distinct
+  # class (mirroring {ComponentContractError}) lets the preprocessor re-raise it
+  # AS-IS (its message already carries the component name + file:line + the exact
+  # fix) and lets the 15.7 capstone assert this trap fails loudly by class. The
+  # sole legitimate paired PascalCase tag, `<Suspense>...</Suspense>`, is
+  # normalized to `<ruact-suspense>` in Step 1 before this detection runs, so it
+  # never trips.
+  class ChildrenNotSupportedError < PreprocessorError; end
+
   # Raised when application code attempts to mutate Ruact::Configuration outside
   # of a Ruact.configure block. The configuration is frozen after initialization
   # to prevent runtime drift; see Story 7.3 for the rationale and the decision

data/lib/ruact/manifest_resolver.rb

@@ -79,8 +79,8 @@ module Ruact
       return nil if soft
 
       raise ManifestError, <<~MSG.strip
-        [ruact] Vite dev server inacessível em #{base_url} e nenhum \
-        react-client-manifest.json encontrado em #{file_path} — rode `bin/dev`.
+        [ruact] Vite dev server unreachable at #{base_url} and no \
+        react-client-manifest.json found at #{file_path} — run `bin/dev`.
       MSG
     end
 

data/lib/ruact/serializable.rb

@@ -5,32 +5,71 @@ module Ruact
   # client component. Declare which attributes are safe to serialize with
   # +ruact_props+; only those attributes will be included in the wire payload.
   #
-  # @example
+  # Works on POROs and on ActiveRecord models alike. For a PORO the loud check
+  # fires at class-load; for an ActiveRecord model (whose attribute readers are
+  # defined lazily) the same loud check is deferred to the first
+  # +ruact_serialize+ — see {ClassMethods#ruact_props}.
+  #
+  # @example PORO
   #   class Post
   #     include Ruact::Serializable
   #     attr_reader :id, :title, :secret
   #     ruact_props :id, :title   # :secret is never sent to the client
   #   end
+  #
+  # @example ActiveRecord model
+  #   class Post < ApplicationRecord
+  #     include Ruact::Serializable
+  #     ruact_props :id, :title   # other columns never cross to the client
+  #   end
   module Serializable
     def self.included(base)
       base.extend(ClassMethods)
       base.instance_variable_set(:@ruact_props, [])
+      base.instance_variable_set(:@ruact_deferred_props, [])
     end
 
     module ClassMethods
       # Declare which instance methods should be included in the serialized
-      # payload. Raises +ArgumentError+ at class-load time if any name has no
-      # corresponding method defined on the class.
+      # payload.
+      #
+      # The loud-omission guarantee is preserved: a name with no corresponding
+      # method still raises a clean +ArgumentError+. Only the *timing* of that
+      # check depends on the class:
+      #
+      # * **PORO** — checked eagerly at class-load (macro-invocation) time, as
+      #   before. A typo'd/absent prop raises immediately.
+      # * **ActiveRecord model** — ActiveRecord defines its attribute reader
+      #   methods lazily (on first instance access), so at macro-invocation time
+      #   +method_defined?(:title)+ is +false+ even for a real column. Checking
+      #   eagerly would either reject a valid model at boot or require a live DB
+      #   connection at class-load (a Rails anti-pattern). So for a lazy-attribute
+      #   class the not-yet-defined names are recorded and their loud check is
+      #   deferred to the first +ruact_serialize+ (via +respond_to?+ on the
+      #   instance), where the DB is up. A genuine typo still raises the same
+      #   clean +ArgumentError+ — just at first render of that model, not at boot.
       #
       # @param attrs [Array<Symbol>]
+      # @raise [ArgumentError] immediately for an undefined prop on a PORO; at
+      #   first +ruact_serialize+ for an undefined prop on an ActiveRecord model.
       def ruact_props(*attrs)
+        deferred = []
         attrs.each do |attr|
-          unless method_defined?(attr)
-            raise ArgumentError,
-                  "ruact_props: method `#{attr}` is not defined on #{self}"
+          next if method_defined?(attr)
+
+          # Lazy-attribute (ActiveRecord) class: the reader may still appear on
+          # first instance access. Record it and check loudly on first serialize
+          # instead of failing a valid model at boot.
+          if ruact_lazy_attribute_class?
+            deferred << attr
+            next
           end
+
+          raise ArgumentError,
+                "ruact_props: method `#{attr}` is not defined on #{self}"
         end
         @ruact_props = attrs
+        @ruact_deferred_props = deferred
       end
 
       # Returns the list of declared prop names as symbols.
@@ -46,12 +85,65 @@ module Ruact
         end
         []
       end
+
+      # Names whose eager loud check was deferred to first serialize (lazy
+      # ActiveRecord attributes). Read from the same class that declared the
+      # props, so subclasses share the parent declaration.
+      #
+      # @return [Array<Symbol>]
+      def ruact_deferred_props_list
+        klass = self
+        while klass
+          if klass.instance_variable_defined?(:@ruact_props)
+            return klass.instance_variable_get(:@ruact_deferred_props) || []
+          end
+
+          klass = klass.superclass
+        end
+        []
+      end
+
+      # Run the deferred loud check once, on first +ruact_serialize+. A recorded
+      # name that the instance does not +respond_to?+ (a typo, or a genuinely
+      # absent column) raises the same clean +ArgumentError+ the eager path would.
+      #
+      # Memoization keys on the *validated deferred list itself* (not a bare
+      # boolean), so any change to the effective declaration — a re-declaration
+      # on this class OR on an ancestor whose props a subclass inherits — is
+      # detected and re-validated loudly on the next serialize. Once a given
+      # list has been validated it costs one array comparison per serialize.
+      #
+      # @param instance [Object]
+      # @raise [ArgumentError]
+      def ruact_validate_deferred_props!(instance)
+        deferred = ruact_deferred_props_list
+        return if @ruact_deferred_props_validated == deferred
+
+        deferred.each do |attr|
+          next if instance.respond_to?(attr)
+
+          raise ArgumentError,
+                "ruact_props: method `#{attr}` is not defined on #{self}"
+        end
+        @ruact_deferred_props_validated = deferred
+      end
+
+      # True when this class defines its attribute reader methods lazily, i.e.
+      # an ActiveRecord model. Detected WITHOUT a hard ActiveRecord dependency
+      # (the gem stays single-dep +nokogiri+): the constant is only referenced
+      # when it is already defined in the host.
+      #
+      # @return [Boolean]
+      def ruact_lazy_attribute_class?
+        !!(defined?(ActiveRecord::Base) && self < ActiveRecord::Base)
+      end
     end
 
     # Serialize only the attributes declared with +ruact_props+.
     #
     # @return [Hash{String => Object}]
     def ruact_serialize
+      self.class.ruact_validate_deferred_props!(self)
       self.class.ruact_props_list.to_h { |attr| [attr.to_s, public_send(attr)] }
     end
   end

data/lib/ruact/server.rb

@@ -104,6 +104,28 @@ module Ruact
       before_action :__ruact_set_vary_on_accept!
       after_action  :__ruact_set_vary_on_accept!
 
+      # Story 15.0 (F6) — dev-only legibility warning: an action that registers
+      # validation errors (`ruact_errors(record)`) and then performs an EXPLICIT
+      # render on a function-call request bypasses `default_render`, so the
+      # registered errors silently vanish from the JSON body. The warning names
+      # the opt-out; it never fires on the documented-correct patterns (Bucket-1
+      # page render, redirect on either bucket, the fall-through itself, or an
+      # action that never touches the collector). Log-only — bodies and statuses
+      # are byte-identical in every environment.
+      after_action :__ruact_warn_errors_injection_opt_out!
+
+      # Story 15.5 (FR109) — dev-only response-shape legibility log: one
+      # `[ruact]` line per ruact-NEGOTIATED request naming the chosen bucket +
+      # the deciding signal (e.g. `Accept: application/json + POST →
+      # function-call JSON`), so the dual-bucket negotiation is observable at
+      # runtime without a debugger. Adjacent to the F6 warning above so the two
+      # dev-only legibility hooks read as a pair. Same dev gate
+      # (`__ruact_development?`), same log-only invariant — bodies, statuses,
+      # and headers are byte-identical in every environment. SILENT outside
+      # development and on a plain Rails action on the same controller (a
+      # response ruact did not negotiate).
+      after_action :__ruact_log_response_shape!
+
       # Story 8.4 salvage — same registration order as v1 (Pitfall #1): the
       # generic StandardError entry first, the explicit
       # InvalidAuthenticityToken entry second so it wins Rails'
@@ -201,6 +223,12 @@ module Ruact
       # one (see {Ruact::ValidationErrorsCollector::RESERVED_ASSIGN_KEYS}).
       assigns = view_assigns.except(*ValidationErrorsCollector::RESERVED_ASSIGN_KEYS)
 
+      # Story 15.0 (F6) — reaching this branch means ruact itself is producing
+      # the function-call response (fall-through: injection, plain JSON, or
+      # 204), so the opt-out warning must stay silent. Set AFTER `view_assigns`
+      # is captured above so the flag ivar never leaks into the serialized body.
+      @__ruact_function_response_owned = true
+
       # Story 13.3 (FR98, AC3) — when the host opted into the validation-error
       # round-trip (`ruact_errors(@record)` was called this request), inject the
       # collected errors under the reserved JSON key `"errors"` alongside the
@@ -249,6 +277,11 @@ module Ruact
       _ensure_url_is_http_header_safe(location)
       location = _enforce_open_redirect_protection(location, allow_other_host: allow_other_host)
 
+      # Story 15.0 (F6) — a Bucket-2 `redirect_to` is a ruact-owned response
+      # (`$redirect`; registered errors ride flash), not an injection opt-out.
+      @__ruact_function_response_owned = true
+      # Story 15.5 (FR109) — mark the `$redirect` sub-shape for the dev log.
+      @__ruact_function_redirect = true
       render json: { "$redirect" => __ruact_redirect_path(location) }
     end
 
@@ -290,6 +323,136 @@ module Ruact
       url
     end
 
+    # Story 15.0 (F6) — the dev-only opt-out warning. Fires when ALL hold:
+    # development environment, the request is a function call
+    # ({#__ruact_function_call?}), the collector was touched
+    # (`ruact_errors(record)` ran this request), and the response was produced
+    # by an EXPLICIT host render — i.e. neither {#default_render}'s
+    # function-call branch nor the Bucket-2 {#redirect_to} set
+    # `@__ruact_function_response_owned`. In that shape the registered errors
+    # were silently dropped from the JSON body (the F6 finding).
+    #
+    # The four MUST-NOT-warn guardrails fall out of the predicate:
+    #   (a) Bucket-1 `render :new` — not a function call;
+    #   (b) `redirect_to` on either bucket — Bucket-2 sets the owned flag,
+    #       Bucket-1 is not a function call;
+    #   (c) the fall-through — `default_render` sets the owned flag;
+    #   (d) an untouched collector — `__ruact_errors_touched?` is false.
+    # The exception path never reaches here either: a raise aborts the
+    # after_action chain before this hook runs (`rescue_from` renders outside
+    # it), so a structured error payload is not misread as an opt-out.
+    def __ruact_warn_errors_injection_opt_out!
+      return unless __ruact_development?
+      return unless __ruact_function_call?
+      return unless __ruact_errors_touched?
+      return if @__ruact_function_response_owned
+
+      Rails.logger&.warn(
+        "[ruact] #{self.class.name}##{action_name} called `ruact_errors` and then rendered " \
+        "explicitly on a function-call request — the registered validation errors were NOT " \
+        "injected into the JSON response. Remove the explicit render and let the action fall " \
+        "through (ruact injects `errors` into the body), or surface them on a page render with " \
+        "`errors={ruact_errors}` / carry them through a `redirect_to` (flash)."
+      )
+    end
+
+    # Story 15.5 (FR109) — the dev-only response-shape log. Emits exactly one
+    # `[ruact]` line per ruact-negotiated request naming the chosen bucket and
+    # the deciding signal (Accept + verb), mirroring the vocabulary of the
+    # canonical caller→shape table in `server-actions.md`. Log-only: the
+    # response body, status, and headers are byte-identical to before in every
+    # environment.
+    #
+    # Coverage (D1, `Ruact::Server`-only for 15.5): the function-call-JSON
+    # bucket (incl. the `204` and `$redirect` sub-shapes) plus, for a page
+    # render on a controller that also includes {Ruact::Controller}, the
+    # Flight-page and HTML-shell shapes. A GET query (separate dispatch
+    # controller) and a page-only controller (includes `Ruact::Controller` but
+    # not `Ruact::Server`) are NOT covered — the table documents those shapes;
+    # extending the log to them is deferred (see deferred-work.md).
+    #
+    # SILENT (returns nil message) outside development and on a plain Rails
+    # action on the same controller — a response ruact did not negotiate
+    # (no function-call Accept and no ruact page render). A raise / before_action
+    # halt that skips the after_action chain is an accepted, documented log gap
+    # (identical to the F6 warning).
+    def __ruact_log_response_shape!
+      return unless __ruact_development?
+
+      message = __ruact_response_shape_log_message
+      return unless message
+
+      Rails.logger&.info(message)
+    end
+
+    # Classify the negotiated response shape from the request signals
+    # (`__ruact_function_call?`, Accept, verb) and the ruact-owned outcome flags
+    # (`@__ruact_function_redirect` set by the Bucket-2 {#redirect_to};
+    # `@__ruact_negotiated_page` set by {Ruact::Controller#emit_ruact_response} /
+    # its Flight `redirect_to`). Returns nil when ruact did not negotiate the
+    # response, so the log stays silent on plain Rails actions.
+    #
+    # @return [String, nil] the `[ruact] Ctrl#action — <signal> → <bucket>`
+    #   line, or nil for a non-negotiated response.
+    def __ruact_response_shape_log_message
+      shape, signal = __ruact_negotiated_shape_and_signal
+      return unless shape
+
+      "[ruact] #{self.class.name}##{action_name} — #{signal} → #{shape}"
+    end
+
+    # @return [Array(String, String), nil] `[bucket, deciding_signal]` for a
+    #   ruact-negotiated response, or nil for one ruact did not own.
+    def __ruact_negotiated_shape_and_signal
+      if __ruact_function_call?
+        [__ruact_function_call_shape, "Accept: application/json + #{request.request_method}"]
+      else
+        __ruact_page_shape_and_signal
+      end
+    end
+
+    # The function-call (Bucket-2) sub-shape, distinguished by the ruact-owned
+    # outcome: a `$redirect` directive, a `204 No Content` (no exposed ivars),
+    # or the ordinary serialized-ivars JSON.
+    def __ruact_function_call_shape
+      return "function-call $redirect" if @__ruact_function_redirect
+      return "function-call JSON (204, no ivars)" if response.status == 204
+
+      "function-call JSON"
+    end
+
+    # The page-render (Bucket-1 / HTML-shell) shape, keyed on the flag
+    # {Ruact::Controller#emit_ruact_response} set when ruact rendered the page.
+    # nil for a plain Rails render (the flag was never set) → the log stays
+    # silent on a non-negotiated response.
+    def __ruact_page_shape_and_signal
+      case @__ruact_negotiated_page
+      when :flight
+        ["Flight page", __ruact_flight_signal]
+      when :flight_redirect
+        ["Flight redirect", __ruact_flight_signal]
+      when :html_shell
+        ["HTML shell", "HTML-acceptable Accept, no Flight header"]
+      end
+    end
+
+    # The Flight deciding signal, faithful to how the request announced itself:
+    # the `Accept: text/x-component` header, or the `Ruact-Request: 1` header.
+    def __ruact_flight_signal
+      if request.headers["Accept"].to_s.include?("text/x-component")
+        "Accept: text/x-component"
+      else
+        "Ruact-Request: 1"
+      end
+    end
+
+    # @return [Boolean] true only in a real Rails development environment
+    #   (mirrors {Ruact::ManifestResolver.development?}).
+    def __ruact_development?
+      defined?(Rails) && Rails.respond_to?(:env) && Rails.env.respond_to?(:development?) &&
+        Rails.env.development?
+    end
+
     # Raw discriminator — does the request's `Accept` header equal
     # `application/json`? This is exactly what the 8.1 runtime sends on every
     # `_makeRef` fetch (Bucket 2 — imperative `await createPost(...)`).

data/lib/ruact/server_functions/introspection.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+module Ruact
+  module ServerFunctions
+    # Story 15.3 (FR107) — the machine-readable `ruact:routes --json` document:
+    # a read-only, side-effect-free view of the accessor/route table for headless
+    # agents and CI gates. Reuses the SAME collectors codegen consumes (via
+    # {Ruact::ServerFunctions.introspect}), so the introspection can never fork a
+    # parallel derivation and never writes the codegen bridge / TS module.
+    #
+    # ## Shape
+    #
+    #     { "schema_version" => Integer,
+    #       "accessors" => [
+    #         { "accessor" => String,   # the JS identifier (js_identifier)
+    #           "kind"     => String,   # "action" | "query"
+    #           "verb"     => String,   # HTTP method
+    #           "path"     => String,   # cleaned route path
+    #           "segments" => Array<String>,
+    #           "params"   => [{ "name" => String, "required" => Boolean }] } ] }
+    #
+    # Queries carry their declared kwargs as `params` (Story 13.4); actions carry
+    # their required path segments, uniformly shaped as `{ name, required: true }`.
+    # Per Story 15.3 decision D3 there is NO per-accessor component-contract link
+    # (accessors are server functions, not components) — the table reports
+    # accessors faithfully and omits the "target component contract" clause.
+    module Introspection
+      # Version of the `ruact:routes --json` document. **EXPERIMENTAL / UNSTABLE**:
+      # `0` signals the shape may change without a major version bump while the
+      # agent-facing surface is iterated — gate any parser on it. Distinct from
+      # {Ruact::Doctor::SCHEMA_VERSION} (a separate, independently-versioned
+      # document) and from {Snapshot::VERSION_V2} (the internal codegen bridge).
+      SCHEMA_VERSION = 0
+
+      class << self
+        # Builds the `ruact:routes --json` document from +route_set+. The resolver
+        # callables default to real constant resolution; specs inject lambdas.
+        #
+        # @param route_set [#routes] the Rails route set.
+        # @param host_predicate [#call, nil] forwarded to {ServerFunctions.introspect}.
+        # @param overrides_for [#call, nil] forwarded to {ServerFunctions.introspect}.
+        # @param query_class_for [#call, nil] forwarded to {ServerFunctions.introspect}.
+        # @return [Hash] the schema-versioned introspection document.
+        # @raise [Ruact::ConfigurationError] on any naming collision.
+        def as_json(route_set:, host_predicate: nil, overrides_for: nil, query_class_for: nil)
+          entries = ServerFunctions.introspect(
+            route_set: route_set,
+            host_predicate: host_predicate,
+            overrides_for: overrides_for,
+            query_class_for: query_class_for
+          )
+          {
+            "schema_version" => SCHEMA_VERSION,
+            "accessors" => entries.map { |entry| shape(entry) }
+          }
+        end
+
+        private
+
+        def shape(entry)
+          {
+            "accessor" => entry["js_identifier"],
+            "kind" => entry["kind"],
+            "verb" => entry["http_method"],
+            "path" => entry["path"],
+            "segments" => entry["segments"],
+            "params" => params_for(entry)
+          }
+        end
+
+        # Queries declare their params as kwargs (Story 13.4 → `params`); actions
+        # derive them from required path segments. Uniform `{ name, required }`.
+        def params_for(entry)
+          return entry["params"] if entry["kind"] == "query"
+
+          entry["segments"].map { |segment| { "name" => segment, "required" => true } }
+        end
+      end
+    end
+  end
+end

data/lib/ruact/server_functions.rb

@@ -29,6 +29,7 @@ module Ruact
     autoload :ValidationErrors,   "ruact/server_functions/validation_errors"
     autoload :QueryContext, "ruact/server_functions/query_context"
     autoload :QueryDispatch, "ruact/server_functions/query_dispatch"
+    autoload :Introspection, "ruact/server_functions/introspection"
 
     # Story 9.3 / 9.9 — orchestrates the route-driven (v2) codegen. Reads the
     # route table via {RouteSource} + {QuerySource}, writes the version-2 bridge
@@ -55,10 +56,7 @@ module Ruact
     #   `Rails.logger` when Rails is loaded, else nil.
     # @return [Array<Hash>] the exposed v2 entries (actions + queries).
     def self.write_v2_snapshot!(route_set:, root:, logger: default_logger)
-      actions = RouteSource.collect(route_set)
-      queries = QuerySource.collect(route_set)
-      entries = (actions + queries).sort_by { |entry| entry["js_identifier"] }
-      detect_merged_namespace_collisions!(entries)
+      entries = introspect(route_set: route_set)
 
       json_path = root.join("tmp/cache/ruact/server-functions.json")
       ts_path   = root.join("app/javascript/.ruact/server-functions.ts")
@@ -75,6 +73,30 @@ module Ruact
       entries
     end
 
+    # Story 15.3 (FR107) — the read-only, side-effect-free combine point:
+    # collect mutation actions ({RouteSource}) + read queries ({QuerySource}),
+    # sort by `js_identifier`, and run the merged-namespace collision check —
+    # WITHOUT writing the bridge/TS. Both {.write_v2_snapshot!} (codegen) and
+    # {Ruact::ServerFunctions::Introspection} (`ruact:routes --json`) call THIS,
+    # so what an agent verifies against can never drift from what codegen emits
+    # (single source of truth), and a CI gate can introspect without mutating the
+    # tree. The resolver callables default to real constant resolution; specs
+    # inject lambdas to exercise the derivation without booting controllers.
+    #
+    # @param route_set [#routes] the Rails route set.
+    # @param host_predicate [#call, nil] forwarded to {RouteSource.collect}.
+    # @param overrides_for [#call, nil] forwarded to {RouteSource.collect}.
+    # @param query_class_for [#call, nil] forwarded to {QuerySource.collect}.
+    # @return [Array<Hash>] merged action + query entries (string keys), sorted.
+    # @raise [Ruact::ConfigurationError] on any naming collision.
+    def self.introspect(route_set:, host_predicate: nil, overrides_for: nil, query_class_for: nil)
+      actions = RouteSource.collect(route_set, host_predicate: host_predicate, overrides_for: overrides_for)
+      queries = QuerySource.collect(route_set, query_class_for: query_class_for)
+      entries = (actions + queries).sort_by { |entry| entry["js_identifier"] }
+      detect_merged_namespace_collisions!(entries)
+      entries
+    end
+
     def self.default_logger
       defined?(Rails) && Rails.respond_to?(:logger) ? Rails.logger : nil
     end