rails_tool_views 0.1.0

data/lib/generators/rails_tool_views/install/templates/create_rails_tool_views.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+class CreateRailsToolViews < ActiveRecord::Migration[7.2]
+  # Identifier columns are bounded to 150 bytes in RailsToolViews::Data, and the
+  # value is stored in a byte-limited column. This keeps every index key within
+  # utf8mb4's 3072-byte limit on MySQL/InnoDB: the widest index is the five
+  # presentation columns below (5 * 150 * 4 = 3000 bytes).
+  def change
+    create_table :rails_tool_views_surfaces, id: :string do |t|
+      t.string :actor_ref, null: false, limit: 150
+      t.string :tenant_ref, null: false, limit: 150
+      t.string :context_ref, limit: 150
+      t.string :component_key, null: false
+      t.string :component_digest, null: false
+      t.integer :contract_version, default: 1, null: false
+      t.json :props, null: false
+      t.json :state, null: false
+      t.integer :revision, default: 1, null: false
+      t.integer :lock_version, default: 0, null: false
+      t.timestamps
+    end
+    add_index :rails_tool_views_surfaces, [:tenant_ref, :actor_ref]
+    create_table :rails_tool_views_presentations do |t|
+      t.references :surface, type: :string, foreign_key: { to_table: :rails_tool_views_surfaces }, null: false
+      t.string :actor_ref, null: false, limit: 150
+      t.string :tenant_ref, null: false, limit: 150
+      t.string :adapter, null: false, limit: 150
+      t.string :call_id, null: false, limit: 150
+      t.string :context_ref, null: false, limit: 150
+      t.string :request_digest, null: false
+      t.json :result, null: false
+      t.timestamps
+    end
+    add_index :rails_tool_views_presentations, [:tenant_ref, :actor_ref, :adapter, :call_id, :context_ref], unique: true, name: "index_rails_tool_views_call_scope"
+    create_table :rails_tool_views_action_executions do |t|
+      t.references :surface, type: :string, foreign_key: { to_table: :rails_tool_views_surfaces }, null: false
+      t.string :actor_ref, null: false, limit: 150
+      t.string :action_key, null: false
+      t.string :idempotency_key, null: false, limit: 150
+      t.string :request_digest, null: false
+      t.integer :base_revision, null: false
+      t.json :result, null: false
+      t.timestamps
+    end
+    add_index :rails_tool_views_action_executions, [:surface_id, :idempotency_key], unique: true, name: "index_rails_tool_views_action_replay"
+    create_table :rails_tool_views_agent_interactions do |t|
+      t.references :surface, type: :string, foreign_key: { to_table: :rails_tool_views_surfaces }, null: false
+      t.references :action_execution, foreign_key: { to_table: :rails_tool_views_action_executions }, null: false, index: { unique: true, name: "index_rails_tool_views_interaction_execution" }
+      t.json :payload, null: false
+      t.string :status, null: false, default: "pending"
+      t.string :error_code
+      t.datetime :claimed_at
+      t.integer :attempts, null: false, default: 0
+      t.timestamps
+    end
+  end
+end

data/lib/generators/rails_tool_views/install/templates/rails_tool_views.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+RailsToolViews.configure do |config|
+  # Fail closed until host authentication resolves stable actor AND tenant refs.
+  # config.scope_resolver = ->(controller) {
+  #   RailsToolViews::Scope.new(actor: controller.current_user.id.to_s,
+  #     tenant: controller.current_account.id.to_s)
+  # }
+  # Mounted controllers inherit this host controller's filters and helpers.
+  # config.parent_controller = "::ApplicationController"
+end
+# Register trusted components and explicit policies in Rails.application.config.to_prepare.
+# Read the gem README for a complete ChoiceCard definition and optional adapter.

data/lib/rails_tool_views/adapters/ruby_llm.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+# Only this explicitly required file loads RubyLLM.
+require "rails_tool_views"
+require "ruby_llm"
+
+module RailsToolViews
+  module Adapters
+    module RubyLLM
+      # Optional RubyLLM tool exposing a scoped, approved component catalog.
+      class PresentUI < ::RubyLLM::Tool
+        description "Present one trusted interactive Rails component to the user."
+        # Returns the stable provider-facing tool name.
+        def self.tool_name
+          "present_ui"
+        end
+        attr_reader :references
+        # Captures an authorized catalog and server-owned correlation context.
+        def initialize(keys:, scope:, context:, adapter_key: "ruby_llm")
+          @scope = scope
+          @context = Data.identifier(context, code: "INVALID_CONTEXT")
+          @adapter_key = Data.identifier(adapter_key, code: "INVALID_CORRELATION")
+          @components = RailsToolViews.registry.catalog(keys: keys, scope: scope)
+          raise Error.new("EMPTY_CATALOG") if @components.empty?
+          @references = []
+        end
+        # Returns the bounded schema presented to the provider.
+        def parameters_schema
+          { "type" => "object", "additionalProperties" => false, "required" => %w[component props],
+            "properties" => { "component" => { "type" => "string", "enum" => @components.map(&:key) },
+              "props" => { "anyOf" => @components.map { |component| component.schema.json }.uniq } } }
+        end
+        # Presents a component using a real RubyLLM ToolCall; returns an acknowledgment or rejection.
+        def execute(component:, props:, tool_call: nil)
+          definition = @components.find { |item| item.key == component.to_s }
+          raise Error.new("NOT_ALLOWED", status: 403) unless definition
+          raise Error.new("INCOMPATIBLE_COMPONENT", status: 422) unless RailsToolViews.registry.fetch(definition.key).digest == definition.digest
+          # A server-owned ToolCall is required for provider replay safety.
+          raise Error.new("MISSING_TOOL_CALL") unless tool_call.is_a?(::RubyLLM::ToolCall)
+          raise Error.new("INVALID_TOOL_CALL") unless tool_call.name == name
+          surface = RailsToolViews.present(definition.key, props: props, scope: @scope, context: @context,
+            correlation: { adapter: @adapter_key, call_id: tool_call.id, context: @context })
+          reference = { surface_id: surface.id, context_ref: @context }
+          @references << reference.freeze unless @references.include?(reference)
+          RailsToolViews.notify("adapter.tool_called", surface_id: surface.id, revision: surface.revision)
+          # The persisted presentation receipt preserves the original tool result.
+          # Match the receipt byte for byte; a non-binary collation must not return
+          # another call's acknowledgment.
+          presentation = RailsToolViews::Presentation.find_by(surface_id: surface.id, adapter: @adapter_key, call_id: tool_call.id, context_ref: @context)
+          unless presentation && presentation.adapter == @adapter_key && presentation.call_id == tool_call.id && presentation.context_ref == @context
+            raise Error.new("INVALID_CORRELATION")
+          end
+          presentation.result.symbolize_keys
+        rescue Error => error
+          error.to_h
+        end
+      end
+
+      # Host owns durable chat lookup and delivery deduplication. This adapter
+      # only starts a supported user turn; RubyLLM prevents pending-tool mixing.
+      class Continuation
+        # Accepts authorized chat resolution and durable host delivery deduplication.
+        def initialize(chat_resolver:, delivery:)
+          @chat_resolver, @delivery = chat_resolver, delivery
+        end
+        # Starts a user turn within the host delivery deduplication block.
+        def call(payload, delivery_key:)
+          @delivery.call(delivery_key) do
+            chat = @chat_resolver.call(payload.fetch("context_ref"))
+            chat.ask(JSON.generate(payload))
+          end
+        end
+      end
+    end
+  end
+end

data/lib/rails_tool_views/core.rb

@@ -0,0 +1,288 @@
+# frozen_string_literal: true
+require "json"
+require "digest"
+require "securerandom"
+require "json_schemer"
+require_relative "version"
+
+# Registers trusted Rails views and orchestrates persistent, authorized interactions.
+module RailsToolViews
+  # A recoverable rejection with a stable code and HTTP status.
+  class Error < StandardError
+    attr_reader :code, :status
+    MESSAGES = {
+      "NOT_FOUND" => "This view is unavailable.", "NOT_ALLOWED" => "You do not have permission to use this view.",
+      "CONFLICT" => "This view changed. Refresh to continue.", "INVALID_ARGUMENTS" => "Check the submitted values and try again.",
+      "VALIDATION_FAILED" => "Check the highlighted fields and try again.",
+      "INCOMPATIBLE_COMPONENT" => "This view's contract changed. Ask the application owner to migrate or recreate it.",
+      "RENDER_FAILED" => "This view cannot be rendered. Your saved state is preserved.",
+      "AGENT_UNAVAILABLE" => "Your changes were saved, but the AI follow-up could not complete.",
+      "IDEMPOTENCY_CONFLICT" => "This request identifier was already used for a different request."
+    }.freeze
+    # Hosts own the wording of their codes: pass message:, or translate
+    # rails_tool_views.errors.<downcased code>. Built-in codes translate the same way.
+    def self.message_for(code)
+      fallback = MESSAGES.fetch(code) { "The request was rejected (#{code})." }
+      defined?(::I18n) ? ::I18n.t(code.downcase, scope: %i[rails_tool_views errors], default: fallback) : fallback
+    end
+    # Creates a rejection; message overrides the default or translated wording.
+    def initialize(code, status: 400, message: nil)
+      @code, @status = code, status
+      super(message || self.class.message_for(code))
+    end
+    # Returns a bounded rejection payload for the caller.
+    def to_h
+      { status: "rejected", code: code, message: message }
+    end
+  end
+
+  module Data # :nodoc:
+    module_function
+    def normalize(value, depth = 0)
+      raise Error.new("PAYLOAD_TOO_DEEP") if depth > RailsToolViews.configuration.max_depth
+      case value
+      when Hash
+        result = {}
+        value.each do |key, item|
+          raise Error.new("INVALID_JSON") unless key.is_a?(String) || key.is_a?(Symbol)
+          raise Error.new("INVALID_JSON") if result.key?(key.to_s)
+          result[key.to_s] = normalize(item, depth + 1)
+        end
+        result
+      when Array then value.map { |item| normalize(item, depth + 1) }
+      when String then value.dup
+      when Integer, TrueClass, FalseClass, NilClass then value
+      when Float
+        raise Error.new("INVALID_JSON") unless value.finite?
+        value
+      else raise Error.new("INVALID_JSON")
+      end
+    end
+    def bounded(value)
+      normalized = normalize(value)
+      raise Error.new("PAYLOAD_TOO_LARGE", status: 413) if JSON.generate(normalized).bytesize > RailsToolViews.configuration.max_payload_bytes
+      normalized
+    rescue JSON::GeneratorError, EncodingError
+      raise Error.new("INVALID_JSON")
+    end
+    def freeze_deep(value)
+      case value
+      when Hash then value.each { |key, item| key.freeze; freeze_deep(item) }
+      when Array then value.each { |item| freeze_deep(item) }
+      end
+      value.freeze
+    end
+    def canonical(value)
+      case value
+      when Hash then value.keys.sort.to_h { |key| [key, canonical(value[key])] }
+      when Array then value.map { |item| canonical(item) }
+      else value
+      end
+    end
+    def digest(value)
+      "sha256:#{Digest::SHA256.hexdigest(JSON.generate(canonical(bounded(value))))}"
+    end
+    # Actor, tenant, context, adapter, call and replay references are persisted
+    # in string columns that carry multi-column indexes. Cap them in bytes so a
+    # value can never overflow a byte-limited column and every unique key fits
+    # utf8mb4's 3072-byte index limit on MySQL/InnoDB. A byte cap also bounds the
+    # character count, which is what a varchar length actually limits.
+    IDENTIFIER_BYTES = 150
+    def reference(value, code: "INVALID_SCOPE", limit: 255)
+      raise Error.new(code) unless value.is_a?(String) && !value.strip.empty? && value.bytesize <= limit
+      value.dup.freeze
+    end
+    # A bounded reference for a stored, indexed identifier.
+    def identifier(value, code: "INVALID_SCOPE")
+      reference(value, code: code, limit: IDENTIFIER_BYTES)
+    end
+  end
+
+  # Host-owned validation feedback. Only return approved, schema-validated form
+  # values; rejected requests do not change Surface or domain persistence.
+  # A rejected form with field messages and explicitly safe retained values.
+  class ValidationError < Error
+    attr_reader :fields, :values
+    # Creates field feedback with only the values the host approves for redisplay.
+    def initialize(fields:, values: {}, message: nil)
+      @fields, @values = Data.bounded(fields), Data.bounded(values)
+      unless @fields.is_a?(Hash) && @values.is_a?(Hash) && @fields.all? { |key, text| key.match?(/\A[a-z][a-z0-9_]*\z/) && text.is_a?(String) && text.length <= 500 }
+        raise Error.new("INVALID_VALIDATION_FEEDBACK")
+      end
+      Data.freeze_deep(@fields)
+      Data.freeze_deep(@values)
+      super("VALIDATION_FAILED", status: 422, message: message)
+    end
+    # Returns a bounded rejection payload for the caller.
+    def to_h
+      super.merge(fields: fields, values: values)
+    end
+  end
+
+  # Validates a bounded, closed JSON contract.
+  class Schema
+    KEYWORDS = %w[type properties required additionalProperties items enum const minimum maximum minLength maxLength pattern minItems maxItems uniqueItems description title anyOf oneOf allOf].freeze
+    TYPES = %w[object array string number integer boolean null].freeze
+    COMBINATORS = %w[anyOf oneOf allOf].freeze
+    attr_reader :json
+    # Builds a closed schema; rejects unsupported or unbounded nested contracts.
+    def initialize(schema)
+      @json = Data.bounded(schema)
+      inspect_schema!(@json)
+      raise Error.new("INVALID_SCHEMA") unless @json["type"] == "object" && @json["additionalProperties"] == false
+      @validator = JSONSchemer.schema(@json, ref_resolver: ->(_uri) { raise Error.new("INVALID_SCHEMA") })
+      raise Error.new("INVALID_SCHEMA") unless @validator.valid_schema?
+      Data.freeze_deep(@json)
+    rescue JSONSchemer::UnknownRef, ArgumentError
+      raise Error.new("INVALID_SCHEMA")
+    end
+    # Returns normalized validated data, or raises Error with the supplied code.
+    def validate!(value, code: "INVALID_PROPS")
+      data = Data.bounded(value)
+      raise Error.new(code) unless @validator.valid?(data)
+      data
+    end
+    private
+    # Every subschema is walked, and every value position must say what it
+    # accepts: an untyped or empty schema admits any JSON, which would reopen a
+    # closed object from the inside. `bounded` is true only for a combinator
+    # branch whose enclosing schema already constrains the same value.
+    def inspect_schema!(schema, bounded: false) # :nodoc:
+      raise Error.new("INVALID_SCHEMA") unless schema.is_a?(Hash) && (schema.keys - KEYWORDS).empty?
+      types = Array(schema["type"])
+      combinators = COMBINATORS.select { |key| schema.key?(key) }
+      constrained = types.any? || schema.key?("enum") || schema.key?("const")
+      valid = (types - TYPES).empty? && (constrained || bounded || combinators.any?) &&
+        (!schema.key?("enum") || schema["enum"].is_a?(Array)) &&
+        (!schema.key?("additionalProperties") || schema["additionalProperties"] == false) &&
+        schema.fetch("properties", {}).is_a?(Hash) && schema.fetch("items", {}).is_a?(Hash) &&
+        (!types.include?("object") || schema["additionalProperties"] == false) &&
+        (!types.include?("array") || schema.key?("items")) &&
+        combinators.all? { |key| schema[key].is_a?(Array) && schema[key].any? }
+      raise Error.new("INVALID_SCHEMA") unless valid
+      schema.fetch("properties", {}).each_value { |child| inspect_schema!(child) }
+      inspect_schema!(schema["items"]) if schema.key?("items")
+      combinators.each { |key| schema[key].each { |child| inspect_schema!(child, bounded: bounded || constrained) } }
+    end
+  end
+
+  # Immutable actor and tenant references resolved by the host.
+  class Scope
+    attr_reader :actor, :tenant
+    # Creates frozen, nonempty string references for an authenticated identity.
+    def initialize(actor:, tenant:)
+      @actor, @tenant = Data.identifier(actor), Data.identifier(tenant)
+      freeze
+    end
+  end
+
+  # Policy and handler context populated by the runtime.
+  Access = Struct.new(:actor, :tenant, :operation, :props, :surface, :action, :arguments, :context_ref, keyword_init: true)
+  # Handler result containing the next UI state and an optional agent flag.
+  Transition = Struct.new(:state, :agent, keyword_init: true)
+  Action = Struct.new(:key, :schema, :policy, :handler, keyword_init: true)
+
+  # An immutable renderer, schema, version, and authorization contract.
+  class Component
+    # A ViewComponent opts into these by naming them as initializer keywords.
+    CONTEXT = %i[surface state error].freeze
+    attr_reader :key, :description, :schema, :partial, :component, :policy, :actions, :expose_to, :digest, :version, :context
+    # Builds an immutable component with exactly one trusted renderer.
+    def initialize(key, description:, schema:, partial: nil, component: nil, policy: nil, actions: {}, expose_to: [], version: "1")
+      @key = key.to_s.freeze
+      raise Error.new("INVALID_COMPONENT") unless @key.match?(/\A[a-z][a-z0-9_]{0,63}\z/)
+      @description = Data.reference(description, code: "INVALID_COMPONENT")
+      @version = Data.reference(version.to_s, code: "INVALID_COMPONENT")
+      @schema = Schema.new(schema)
+      if (!!partial == !!component) || (partial && (!partial.is_a?(String) || !partial.match?(/\A[a-zA-Z0-9_\/]+\z/))) || (component && (!component.is_a?(Class) || component.name.nil?))
+        raise Error.new("INVALID_RENDERER")
+      end
+      @partial, @component, @policy = partial&.dup&.freeze, component, policy
+      keywords = component ? component.instance_method(:initialize).parameters.filter_map { |kind, name| name if %i[key keyreq].include?(kind) } : []
+      @context = (CONTEXT & keywords).freeze
+      raise Error.new("INVALID_COMPONENT") if (@context.map(&:to_s) & @schema.json.fetch("properties", {}).keys).any?
+      @expose_to = expose_to.map(&:to_sym).freeze
+      @actions = actions.to_h do |name, definition|
+        name = name.to_s.freeze
+        raise Error.new("INVALID_ACTION") unless name.match?(/\A[a-z][a-z0-9_]{0,63}\z/) && (definition.keys - %i[schema policy handler]).empty? && definition[:handler].respond_to?(:call)
+        [name, Action.new(key: name, schema: Schema.new(definition.fetch(:schema)), policy: definition[:policy], handler: definition[:handler]).freeze]
+      end.freeze
+      @digest = Data.digest(key: @key, version: @version, schema: @schema.json, renderer: @partial || @component.name,
+        actions: @actions.transform_values { |action| action.schema.json }, contract_version: 1).freeze
+      freeze
+    end
+    def authorize!(access) # :nodoc:
+      raise Error.new("NOT_ALLOWED", status: 403) unless policy&.call(access) == true
+    end
+  end
+
+  # Stores explicit component definitions and filters discoverable catalogs.
+  class Registry
+    # Creates an empty, process-local registry.
+    def initialize
+      @components = {}
+      @mutex = Mutex.new
+    end
+    # Registers a component; duplicate keys raise DUPLICATE_COMPONENT.
+    def register(key, **options)
+      component = Component.new(key, **options)
+      @mutex.synchronize do
+        raise Error.new("DUPLICATE_COMPONENT") if @components.key?(component.key)
+        @components[component.key] = component
+      end
+      component
+    end
+    # Returns the named component, or raises UNKNOWN_COMPONENT.
+    def fetch(key)
+      @components.fetch(key.to_s) { raise Error.new("UNKNOWN_COMPONENT", status: 404) }
+    end
+    # Returns explicitly exposed components allowed by discovery policy for scope.
+    def catalog(keys:, scope:, exposure: :agent)
+      raise Error.new("INVALID_SCOPE", status: 403) unless scope.is_a?(Scope)
+      raise Error.new("CATALOG_TOO_LARGE") unless keys.is_a?(Array) && keys.length.between?(1, RailsToolViews.configuration.max_catalog_components) && keys.map(&:to_s).uniq.length == keys.length
+      keys.map { |key| fetch(key) }.select do |component|
+        component.expose_to.include?(exposure) && component.policy&.call(Access.new(actor: scope.actor, tenant: scope.tenant, operation: :discover, props: {}, context_ref: nil)) == true
+      end.freeze
+    end
+  end
+
+  # Process-local host hooks, request limits, and delivery settings.
+  class Configuration
+    attr_accessor :scope_resolver, :agent_adapter, :max_payload_bytes, :max_depth, :max_catalog_components, :max_actions_per_minute, :auto_deliver,
+      :parent_controller, :delivery_lease
+    # Initializes conservative request limits with no host identity or agent adapter.
+    def initialize
+      @max_payload_bytes, @max_depth, @max_catalog_components, @max_actions_per_minute = 32_768, 16, 20, 60
+      @auto_deliver = true
+      # Name the host controller that carries authentication; seconds before an unfinished delivery may be reclaimed.
+      @parent_controller, @delivery_lease = "::ApplicationController", 300
+    end
+  end
+
+  class << self
+    # Returns the process-local component registry.
+    def registry
+      @registry ||= Registry.new
+    end
+    # Returns the process-local configuration.
+    def configuration
+      @configuration ||= Configuration.new
+    end
+    # Yields configuration to the host initializer.
+    def configure
+      yield configuration
+    end
+    # Registers a component; duplicate keys raise DUPLICATE_COMPONENT.
+    def register(key, **options)
+      registry.register(key, **options)
+    end
+    # Clears definitions while retaining configuration; use in Rails reload hooks.
+    def reset_registry!
+      @registry = Registry.new
+    end
+    # Clears definitions and configuration; intended for isolated tests.
+    def reset!
+      @registry, @configuration = Registry.new, Configuration.new
+    end
+  end
+end

data/lib/rails_tool_views/engine.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+module RailsToolViews
+  class Engine < ::Rails::Engine
+    isolate_namespace RailsToolViews
+    # Log redaction lives on this engine's own controller and models, not in the
+    # host-wide filter list, where names like `state` would redact host data too.
+    initializer "rails_tool_views.helpers" do
+      ActiveSupport.on_load(:action_controller_base) { helper RailsToolViews::SurfacesHelper }
+    end
+  end
+end

data/lib/rails_tool_views/runtime.rb

@@ -0,0 +1,221 @@
+# frozen_string_literal: true
+module RailsToolViews
+  class << self
+    # Validates and authorizes props, then returns a persisted Surface. Correlation replays the original presentation.
+    def present(key, props:, scope:, context: nil, correlation: nil)
+      check_scope!(scope)
+      component = registry.fetch(key)
+      props = component.schema.validate!(props)
+      context = Data.identifier(context, code: "INVALID_CONTEXT") if context
+      component.authorize!(access(scope, :present, props: props, context_ref: context))
+      correlation = normalize_correlation(correlation) if correlation
+      request_digest = Data.digest(component: component.key, digest: component.digest, props: props, context: context)
+      lookup = correlation&.merge(actor_ref: scope.actor, tenant_ref: scope.tenant)
+      if lookup && (prior = correlated_presentation(lookup))
+        return correlated_surface(prior, request_digest, scope)
+      end
+      surface = nil
+      Surface.transaction(requires_new: true) do
+        surface = Surface.create!(actor_ref: scope.actor, tenant_ref: scope.tenant, context_ref: context,
+          component_key: component.key, component_digest: component.digest, props: props, state: {})
+        if lookup
+          Presentation.create!(**lookup, surface: surface, request_digest: request_digest,
+            result: { status: "presented", surface_id: surface.id, revision: surface.revision })
+        end
+      end
+      notify("presentation.accepted", surface_id: surface.id, component: component.key, revision: surface.revision)
+      surface
+    rescue ActiveRecord::RecordNotUnique
+      prior = lookup && correlated_presentation(lookup)
+      raise unless prior
+      correlated_surface(prior, request_digest, scope)
+    rescue Error => error
+      notify("presentation.rejected", code: error.code)
+      raise
+    end
+
+    # Returns a compatible Surface after checking scope and current read policy.
+    def restore(id, scope:)
+      check_scope!(scope)
+      surface = Surface.find_by(id: id, actor_ref: scope.actor, tenant_ref: scope.tenant)
+      # A database collation that is not binary (for example a case-insensitive
+      # MySQL or PostgreSQL collation) can match a stored actor, tenant or id
+      # that merely compares equal to the requested one. Only a byte-exact
+      # match may stand in for this scope's Surface, or a lookup could disclose
+      # another actor's or tenant's record.
+      raise Error.new("NOT_FOUND", status: 404) unless surface && exact_match?(surface, id: id.to_s, actor_ref: scope.actor, tenant_ref: scope.tenant)
+      component = compatible_component!(surface)
+      component.authorize!(access(scope, :read, surface: surface, props: surface.props, context_ref: surface.context_ref))
+      surface
+    end
+
+    # Commits an authorized action and returns its receipt. Matching retries replay without executing the handler.
+    def dispatch(id, scope:, action:, arguments:, base_revision:, idempotency_key:, source_component: nil, target: nil)
+      surface = restore(id, scope: scope)
+      raise Error.new("INVALID_SOURCE") if source_component && source_component.to_s != surface.component_key
+      raise Error.new("INVALID_TARGET") if target && target != surface.dom_id
+      component = compatible_component!(surface)
+      definition = component.actions.fetch(action.to_s) { raise Error.new("UNKNOWN_ACTION") }
+      arguments = definition.schema.validate!(arguments, code: "INVALID_ARGUMENTS")
+      raise Error.new("INVALID_REVISION") unless base_revision.is_a?(Integer) && base_revision.positive?
+      idempotency_key = Data.identifier(idempotency_key, code: "INVALID_IDEMPOTENCY_KEY")
+      request_digest = Data.digest(action: definition.key, arguments: arguments, base_revision: base_revision)
+      result = nil
+      surface.with_lock do
+        compatible_component!(surface).authorize!(access(scope, :read, surface: surface, props: surface.props, context_ref: surface.context_ref))
+        request = access(scope, :action, surface: surface, props: surface.props, action: definition.key,
+          arguments: arguments, context_ref: surface.context_ref)
+        raise Error.new("NOT_ALLOWED", status: 403) unless definition.policy&.call(request) == true
+        prior = ActionExecution.find_by(surface_id: surface.id, idempotency_key: idempotency_key)
+        if prior
+          # A non-binary collation could match a different key; only replay the
+          # exact key, and keep the digest check as the second gate.
+          raise Error.new("IDEMPOTENCY_CONFLICT", status: 409) unless prior.idempotency_key == idempotency_key && prior.request_digest == request_digest
+          result = prior.result.symbolize_keys
+          next
+        end
+        raise Error.new("CONFLICT", status: 409) unless surface.revision == base_revision
+        if surface.action_executions.where("created_at >= ?", 1.minute.ago).count >= configuration.max_actions_per_minute
+          raise Error.new("RATE_LIMITED", status: 429)
+        end
+        transition = definition.handler.call(request)
+        raise Error.new("INVALID_TRANSITION", status: 422) unless transition.is_a?(Transition) && transition.state.is_a?(Hash)
+        state = Data.bounded(transition.state)
+        surface.update!(state: state, revision: base_revision + 1)
+        result = { status: "completed", surface_id: surface.id, revision: surface.revision }
+        execution = ActionExecution.create!(surface: surface, actor_ref: scope.actor, action_key: definition.key,
+          base_revision: base_revision, idempotency_key: idempotency_key, request_digest: request_digest, result: result)
+        if transition.agent
+          interaction = AgentInteraction.create!(surface: surface, action_execution: execution,
+            payload: { type: "agent_interaction", surface_id: surface.id, action: definition.key, values: arguments,
+              context_ref: surface.context_ref, revision: surface.revision }, status: configuration.agent_adapter ? "pending" : "skipped")
+          result[:interaction_id] = interaction.id
+          execution.update!(result: result)
+        end
+      end
+      notify("action.executed", surface_id: surface.id, revision: result[:revision], action: definition.key)
+      result
+    rescue ActiveRecord::StaleObjectError, ActiveRecord::TransactionRollbackError, ActiveRecord::LockWaitTimeout
+      # The database rolled the whole action back (deadlock, serialization failure,
+      # lock timeout); retrying with the same key is safe.
+      raise Error.new("CONFLICT", status: 409)
+    rescue ActiveRecord::StatementInvalid => error
+      raise Error.new("CONFLICT", status: 409) if error.cause.class.name.include?("Busy") || error.cause.class.name.include?("Locked")
+      raise
+    rescue Error => error
+      notify(error.code == "CONFLICT" ? "action.conflict" : "action.rejected", code: error.code)
+      raise
+    end
+
+    # The adapter must deduplicate by delivery_key. A crash after remote acceptance
+    # can leave a lease in delivering state; retry is explicit and keeps the key.
+    # Delivers a saved interaction after authorization; retry_failed explicitly retries failed delivery.
+    def deliver(id, scope:, adapter: configuration.agent_adapter, retry_failed: false)
+      interaction = AgentInteraction.find_by(id: id)
+      raise Error.new("NOT_FOUND", status: 404) unless interaction
+      surface = restore(interaction.surface_id, scope: scope)
+      definition = compatible_component!(surface).actions.fetch(interaction.payload.fetch("action")) { raise Error.new("INCOMPATIBLE_COMPONENT", status: 422) }
+      arguments = definition.schema.validate!(interaction.payload.fetch("values"), code: "INVALID_ARGUMENTS")
+      request = access(scope, :action, surface: surface, props: surface.props, action: definition.key, arguments: arguments, context_ref: surface.context_ref)
+      raise Error.new("NOT_ALLOWED", status: 403) unless definition.policy&.call(request) == true
+      claimed = false
+      interaction.with_lock do
+        if %w[completed skipped].include?(interaction.status)
+          next
+        end
+        if interaction.status == "delivering" && interaction.claimed_at && interaction.claimed_at > Time.current - configuration.delivery_lease
+          next
+        end
+        next if interaction.status == "failed" && !retry_failed
+        if adapter.nil?
+          interaction.update!(status: "skipped")
+          next
+        end
+        interaction.update!(status: "delivering", claimed_at: Time.current, attempts: interaction.attempts + 1, error_code: nil)
+        claimed = true
+      end
+      return interaction.reload unless claimed
+      begin
+        adapter.call(Data.freeze_deep(Data.normalize(interaction.payload)), delivery_key: interaction.delivery_key)
+        interaction.update!(status: "completed", claimed_at: nil)
+        notify("agent_returned", surface_id: interaction.surface_id, interaction_id: interaction.id)
+      rescue StandardError => error
+        interaction.update!(status: "failed", error_code: "AGENT_UNAVAILABLE", claimed_at: nil)
+        report(error, "agent_failed", surface_id: interaction.surface_id, interaction_id: interaction.id)
+      end
+      interaction.reload
+    end
+
+    # Renders the trusted component after a fresh restore and authorization check.
+    def render(surface, view_context:, scope:, error: nil)
+      # Never trust an already-loaded object as an authorization decision.
+      surface = restore(surface.id, scope: scope)
+      component = compatible_component!(surface)
+      view_context.render(partial: "rails_tool_views/surfaces/surface", formats: [:html], locals: { surface: surface, definition: component, error: error })
+    rescue Error => failure
+      view_context.render(partial: "rails_tool_views/surfaces/error", formats: [:html], locals: { error: failure })
+    end
+
+    def compatible_component!(surface) # :nodoc:
+      component = registry.fetch(surface.component_key)
+      raise Error.new("INCOMPATIBLE_COMPONENT", status: 422) unless surface.contract_version == 1 && component.digest == surface.component_digest
+      component.schema.validate!(surface.props)
+      component
+    rescue Error => error
+      raise Error.new("INCOMPATIBLE_COMPONENT", status: 422) if %w[UNKNOWN_COMPONENT INVALID_PROPS].include?(error.code)
+      raise
+    end
+
+    # The mounted controller needs CSRF protection, helpers and HTML rendering.
+    def parent_controller # :nodoc:
+      parent = configuration.parent_controller.to_s.constantize
+      return parent if parent <= ::ActionController::Base
+      raise ArgumentError, "RailsToolViews parent_controller must inherit from ActionController::Base; #{parent} does not"
+    end
+
+    def access(scope, operation, **attributes) # :nodoc:
+      Access.new(actor: scope.actor, tenant: scope.tenant, operation: operation, **attributes).freeze
+    end
+
+    def notify(event, **payload) # :nodoc:
+      ActiveSupport::Notifications.instrument("#{event}.rails_tool_views", payload)
+    end
+
+    # Host renderer or adapter code failed behind a rescue. Surface it the way
+    # Rails surfaces handled errors; the event itself stays metadata-only.
+    def report(error, event, **payload) # :nodoc:
+      notify(event, **payload, error_class: error.class.name)
+      Rails.error.report(error, handled: true, severity: :error, context: payload, source: "rails_tool_views")
+      Rails.logger&.error("RailsToolViews #{event} handled #{error.class} (#{error.message}) - #{error.backtrace&.first}")
+    end
+
+    private
+    def check_scope!(scope)
+      raise Error.new("INVALID_SCOPE", status: 403) unless scope.is_a?(Scope)
+    end
+    # True only when every attribute equals the requested value byte for byte,
+    # regardless of the database collation used to find the row.
+    def exact_match?(record, **expected)
+      expected.all? { |attribute, value| record.public_send(attribute) == value }
+    end
+    # Returns the durable presentation for this exact correlation, or nil. A row
+    # that a non-binary collation matched but that is not byte-identical is a
+    # conflict, never a replay of another correlation.
+    def correlated_presentation(lookup)
+      prior = Presentation.find_by(lookup)
+      return nil unless prior
+      return prior if exact_match?(prior, **lookup)
+      raise Error.new("IDEMPOTENCY_CONFLICT", status: 409)
+    end
+    def normalize_correlation(value)
+      raise Error.new("INVALID_CORRELATION") unless value.is_a?(Hash) && (value.keys - %i[adapter call_id context]).empty? && value.keys.sort == %i[adapter call_id context].sort
+      { adapter: Data.identifier(value[:adapter], code: "INVALID_CORRELATION"),
+        call_id: Data.identifier(value[:call_id], code: "INVALID_CORRELATION"),
+        context_ref: Data.identifier(value[:context], code: "INVALID_CORRELATION") }
+    end
+    def correlated_surface(prior, digest, scope)
+      raise Error.new("IDEMPOTENCY_CONFLICT", status: 409) unless prior.request_digest == digest
+      restore(prior.surface_id, scope: scope)
+    end
+  end
+end