hecks 4.0.0 → 6.0.0

data/lib/hecks/runtime/value/admission.rb

@@ -28,12 +28,12 @@ module Hecks
         # Unlike `admit_member`, the set is declared elsewhere and named, not written inline.
         #
         # @param owner [Bluebook::Aggregate, Bluebook::Entity, Bluebook::ValueObject] declares
-        #   `attribute`; the walk to the chapter starts here
+        #   `attribute`; the walk to the bluebook starts here
         # @param attribute [Bluebook::Attribute, nil] nil, or one with no `admits:`, checks nothing
         # @param value [Object, nil] a bare scalar or a one-field `Runtime::Value`; nil is skipped
         # @return [Object, nil] `value`, unchanged
         # @raise [Runtime::InvariantViolation] if the value is not a member of the named set,
-        #   or `admits:` names a set no aggregate in the chapter declares
+        #   or `admits:` names a set no aggregate in the bluebook declares
         def admit_declared_set(owner, attribute, value)
           return value if attribute.nil? || attribute.admits.nil? || value.nil?
 
@@ -56,8 +56,8 @@ module Hecks
         #   `attribute`
         # @param attribute [Bluebook::Attribute] an attribute whose `admits` is `"Aggregate::Set"`
         # @return [Array<String>] each member's first-attribute value as a String, in order
-        # @raise [Runtime::InvariantViolation] if `admits` is not qualified, no chapter is
-        #   reachable from `owner`, or the chapter declares no such aggregate or value object
+        # @raise [Runtime::InvariantViolation] if `admits` is not qualified, no bluebook is
+        #   reachable from `owner`, or the bluebook declares no such aggregate or value object
         def admitted_members(owner, attribute)
           set = declared_set(owner, attribute)
           unless set
@@ -70,13 +70,13 @@ module Hecks
           set.members.map { |member| member.to_h[discriminant].to_s }
         end
 
-        # Walks `hecks_owner` links upward until it reaches the chapter.
+        # Walks `hecks_owner` links upward until it reaches the bluebook.
         #
         # @param construct [Bluebook::ValueObject, Bluebook::Entity, Bluebook::Aggregate,
-        #   Bluebook::Chapter, nil] the construct to start from; the chapter answers itself
-        # @return [Bluebook::Chapter, nil] the first construct on the way up that responds to
+        #   Bluebook::Declaration, nil] the construct to start from; the bluebook answers itself
+        # @return [Bluebook::Declaration, nil] the first construct on the way up that responds to
         #   `aggregate`; nil when the chain ends without one
-        def chapter_of(construct)
+        def bluebook_of(construct)
           node = construct
           node = node.hecks_owner while node && !node.respond_to?(:aggregate) && node.respond_to?(:hecks_owner)
           node.respond_to?(:aggregate) ? node : nil
@@ -111,12 +111,12 @@ module Hecks
           member.all? { |field, value| fields[field].to_s == value.to_s }
         end
 
-        # The value object `attribute.admits` names (`"Aggregate::Set"`), when the chapter declares
+        # The value object `attribute.admits` names (`"Aggregate::Set"`), when the bluebook declares
         # it.
         def declared_set(owner, attribute)
           aggregate_name, set_name = attribute.admits.to_s.split("::", 2)
-          chapter = chapter_of(owner)
-          set_name && chapter&.aggregate(aggregate_name)&.value_object(set_name)
+          declaration = bluebook_of(owner)
+          set_name && declaration&.aggregate(aggregate_name)&.value_object(set_name)
         end
 
         # Applies `admits:` to value-object fields too, which never pass through `for_attribute`.

data/lib/hecks/runtime/value/coercion.rb

@@ -55,7 +55,7 @@ module Hecks
         end
 
         # Resolves the value-object class `type` names: `aggregate`'s own
-        # declarations first, then its chapter's other aggregates if they agree.
+        # declarations first, then its bluebook's other aggregates if they agree.
         #
         # @param aggregate [Bluebook::Aggregate, Bluebook::Entity] construct to search first
         # @param type [String, Symbol, #to_s] the declared type name to resolve
@@ -64,10 +64,10 @@ module Hecks
           local = aggregate.value_object(type)
           return local if local
 
-          chapter = aggregate.respond_to?(:hecks_owner) ? aggregate.hecks_owner : nil
-          return nil unless chapter.respond_to?(:aggregates)
+          declaration = aggregate.respond_to?(:hecks_owner) ? aggregate.hecks_owner : nil
+          return nil unless declaration.respond_to?(:aggregates)
 
-          agreed_value_object(chapter, type)
+          agreed_value_object(declaration, type)
         end
 
         # Normalizes an offered value into `value_object`'s own field Hash, before
@@ -164,9 +164,9 @@ module Hecks
           coerced
         end
 
-        # The one value object every aggregate of the chapter that declares `type` agrees on.
-        def agreed_value_object(chapter, type)
-          matches = chapter.aggregates.filter_map { |candidate| candidate.value_object(type) }
+        # The one value object every aggregate of the bluebook that declares `type` agrees on.
+        def agreed_value_object(declaration, type)
+          matches = declaration.aggregates.filter_map { |candidate| candidate.value_object(type) }
           shapes = matches.group_by do |shape|
             shape.attributes.map { |field| [field.name, field.type.to_s, field.list?, field.optional?] }
           end

data/lib/hecks/runtime/value/field_checks.rb

@@ -30,9 +30,9 @@ module Hecks
         # The refusal every wrong-typed or missing field shares: `type_name`'s `field_name` was
         # offered `offered` where `expected` was declared.
         def numeric_field_mismatch!(type_name, field_name, expected, offered)
-          raise TypeMismatch,
-                RefusalWording.render_site("TypeMismatch", "numeric_field",
-                                           type: type_name, field: field_name, expected: expected, offered: offered)
+          message = RefusalWording.render_site("TypeMismatch", "numeric_field",
+                                               type: type_name, field: field_name, expected: expected, offered: offered)
+          raise TypeMismatch.new(message, attribute: field_name)
         end
 
         # C3.8 boundary check — refuses a mistyped argument before it breaks a predicate.
@@ -52,15 +52,15 @@ module Hecks
 
         def check_numeric_bounds(type_name, field_name, given)
           if given.is_a?(Integer) && !INT64_RANGE.cover?(given)
-            raise TypeMismatch,
-                  RefusalWording.render_site("TypeMismatch", "integer_range",
-                                             type: type_name, field: field_name, offered: Rendering.describe(given))
+            raise TypeMismatch.new(RefusalWording.render_site("TypeMismatch", "integer_range", type: type_name,
+                                                              field: field_name, offered: Rendering.describe(given)),
+                                   attribute: field_name)
           end
           return unless given.is_a?(Float) && !given.finite?
 
-          raise TypeMismatch,
-                RefusalWording.render_site("TypeMismatch", "non_finite_field",
-                                           type: type_name, field: field_name, offered: Rendering.describe(given))
+          raise TypeMismatch.new(RefusalWording.render_site("TypeMismatch", "non_finite_field", type: type_name,
+                                                            field: field_name, offered: Rendering.describe(given)),
+                                 attribute: field_name)
         end
 
         # A value object refuses an undeclared key the same way a command's own
@@ -71,10 +71,10 @@ module Hecks
           return if unknown.empty?
 
           declared = value_object.attributes.map(&:name)
-          raise UnknownArgument,
-                RefusalWording.render_site("UnknownArgument", "unknown_args",
-                                           command: value_object.hecks_name, unknown: unknown,
-                                           declared: declared)
+          raise UnknownArgument.new(RefusalWording.render_site("UnknownArgument", "unknown_args",
+                                                               command: value_object.hecks_name, unknown: unknown,
+                                                               declared: declared),
+                                    attribute: unknown.first)
         end
 
         # C3.7 — every non-optional, non-list field must arrive (or construction

data/lib/hecks/runtime/value/invariant_violation.rb

@@ -1,5 +1,8 @@
+require_relative "../../refused"
+
 module Hecks
   module Runtime
-    class InvariantViolation < StandardError; end
+    # A value object's invariant refused the fields it was built from.
+    class InvariantViolation < Hecks::Refused; end
   end
 end

data/lib/hecks/runtime/value/references.rb

@@ -36,7 +36,9 @@ module Hecks
         # @return [Object, nil] the unwrapped scalar, or nil if it does not apply
         def sole_scalar_identity(value, paths)
           return nil unless value.is_a?(self) && paths.one?
-          return nil unless value.value_object.sole_attribute
+
+          shape = value.value_object
+          return nil unless shape.sole_attribute
 
           materialize_unwrapped(value)
         end
@@ -149,10 +151,11 @@ module Hecks
         # @return [String] `" (Target is known by head1, head2)"`, or `""` if the
         #   target or its identity heads cannot be resolved
         def known_by(attribute)
-          heads = Array(attribute.type.resolve&.identity_heads)
+          target = attribute.target_aggregate
+          heads = Array(target&.identity_heads)
           return "" if heads.empty?
 
-          " (#{attribute.type.target_name} is known by #{heads.join(", ")})"
+          " (#{attribute.target_name} is known by #{heads.join(", ")})"
         end
 
         private
@@ -161,7 +164,7 @@ module Hecks
         def reference_target(attribute, value)
           return nil unless value.is_a?(self) || value.is_a?(Hash)
 
-          target = attribute.type.resolve
+          target = attribute.target_aggregate
           target if target && !target.identity_paths.empty?
         end
 

data/lib/hecks/runtime/value/unwrapping.rb

@@ -0,0 +1,60 @@
+module Hecks
+  module Runtime
+    class Value
+      # The shape a caller is answered with: a single-attribute value object as its bare field,
+      # following the declared types down through nested value objects and lists. Extended into
+      # `Value` beside `Coercion`; `materialize` keeps the wrapped shape stored state depends on.
+      module Unwrapping
+        # `materialize`, but a single-attribute value object unwraps to its bare field. What
+        # `group_by` rows and `Driving::Json.materialize` answer with.
+        #
+        # @param value [Object] the value to materialize; anything that is not a `Runtime::Value`,
+        #   Array or Hash passes through unchanged
+        # @return [Object] `value` with every nested `Runtime::Value` replaced by its own sole
+        #   field's value (recursively unwrapped), or by its own `Hash` of fields when it has
+        #   more than one
+        def materialize_unwrapped(value)
+          case value
+          when self then unwrap_typed(value.value_object, value.raw_fields)
+          when Array then value.map { |item| materialize_unwrapped(item) }
+          when Hash then value.transform_values { |item| materialize_unwrapped(item) }
+          else value
+          end
+        end
+
+        private
+
+        # A value object's fields by its declared attributes. A nested value object is often held
+        # as a plain Hash, so its own type is looked up rather than read off the field.
+        def unwrap_typed(value_object, fields)
+          sole = value_object.sole_attribute
+          return unwrap_field(value_object, sole, fields[sole.name]) if sole
+
+          value_object.attributes.to_h { |attr| [attr.name, unwrap_field(value_object, attr, fields[attr.name])] }
+        end
+
+        def unwrap_field(value_object, attribute, held)
+          case held
+          when Array then held.map { |item| unwrap_field(value_object, attribute, item) }
+          when Hash then unwrap_held_hash(value_object, attribute, held)
+          else materialize_unwrapped(held)
+          end
+        end
+
+        def unwrap_held_hash(value_object, attribute, held)
+          nested = nested_value_object(value_object, attribute.type)
+          return materialize_unwrapped(held) unless nested
+
+          unwrap_typed(nested, held.transform_keys(&:to_sym))
+        end
+
+        # The value object a field's type names, resolved against the aggregate that declares
+        # `value_object`; nil for a primitive, or when the owner is not known.
+        def nested_value_object(value_object, type)
+          owner = value_object.respond_to?(:hecks_owner) ? value_object.hecks_owner : nil
+          owner.respond_to?(:value_object) ? value_object_for(owner, type) : nil
+        end
+      end
+    end
+  end
+end

data/lib/hecks/runtime/value/validation.rb

@@ -121,15 +121,18 @@ module Hecks
         end
 
         # Runs each value-object member of an input list through the same entry point a nested
-        # single
-        # value goes through, so a member's own invariants and nested lists refuse on dispatch
-        # exactly as they do when the list sits directly on a command. The members stay as offered.
+        # single value goes through, so a member's own invariants and nested lists refuse on
+        # dispatch exactly as they do when the list sits directly on a command. The members stay
+        # as offered.
+        #
+        # A bare member is judged too: it wraps into a one-field value object and is refused for
+        # any other, here, before the save, not when the saved record is read back.
         def validate_input_list(aggregate, attribute, fields)
           nested = value_object_for(aggregate, attribute.type)
           return unless nested
 
           Array(fields[attribute.name]).each do |member|
-            next unless member.is_a?(Hash)
+            next if member.is_a?(self)
 
             member_fields = apply_defaults(nested, fields_for(nested, attribute.name, member))
             validate!(nested, normalize_composite_fields(aggregate, nested, member_fields))

data/lib/hecks/runtime/value.rb

@@ -9,12 +9,13 @@ require_relative "value/flags"
 require_relative "value/identifiers"
 require_relative "value/entity_list_coercion"
 require_relative "value/admission"
+require_relative "value/unwrapping"
 
 module Hecks
   module Runtime
     # A typed value object: frozen fields, read by name.
     # Construction lives in value/coercion.rb, field_checks.rb, entity_list_coercion.rb and
-    # admission.rb.
+    # admission.rb; the shape a caller is answered with in unwrapping.rb.
     class Value
       extend FieldChecks
       extend Coercion
@@ -24,6 +25,7 @@ module Hecks
       extend Identifiers
       extend EntityListCoercion
       extend Admission
+      extend Unwrapping
 
       attr_reader :value_object
 
@@ -115,32 +117,6 @@ module Hecks
         end
       end
 
-      # `materialize`, but a single-attribute value object unwraps to its bare field.
-      # Opt-in for `group_by` rows; `materialize` keeps the wrapped shape callers depend on.
-      #
-      # @param value [Object] the value to materialize; anything that is not a `Runtime::Value`,
-      #   Array or Hash passes through unchanged
-      # @return [Object] `value` with every nested `Runtime::Value` replaced by its own sole
-      #   field's value (recursively unwrapped), or by its own `Hash` of fields when it has
-      #   more than one
-      def self.materialize_unwrapped(value)
-        case value
-        when self then unwrap_value_object(value)
-        when Array then value.map { |item| materialize_unwrapped(item) }
-        when Hash then value.transform_values { |item| materialize_unwrapped(item) }
-        else value
-        end
-      end
-
-      def self.unwrap_value_object(value)
-        sole = value.value_object.sole_attribute
-        return materialize_unwrapped(value[sole.name]) if sole
-
-        # Not `value.to_h`: it materializes nested values to Hashes, ending the recursion.
-        value.value_object.attributes.to_h { |attr| [attr.name, materialize_unwrapped(value[attr.name])] }
-      end
-      private_class_method :unwrap_value_object
-
       # Reduces an append-only `list_of` sub-log to its current state: the latest row per `key`.
       # Grouping only; what counts as removed, and the ordering, belong to the caller.
       #

data/lib/hecks/runtime/wasm_plugin.rb

@@ -0,0 +1,98 @@
+require "json"
+require_relative "errors"
+
+module Hecks
+  module Runtime
+    # Runs a plugin adapter's wasm module: one question in, one answer out.
+    #
+    # A plugin is a WASI command, the same contract the Rust host runs its kernel by. It reads
+    # `{"question": "Bluebook::Aggregate.Query", "args": {...}}` as JSON on stdin and writes
+    # `{"rows": [...]}` or `{"refused": "why"}` as JSON on stdout. It is given no files, network,
+    # environment or arguments, so it answers from its question alone; here its clock and
+    # randomness are fixed too. Both hosts run the same module, so there is one implementation to
+    # trust.
+    module WasmPlugin
+      # How much a plugin may write before it is cut off; the Rust host uses the same cap.
+      STDOUT_CAP = 64 * 1024 * 1024
+
+      @compiled = {}
+      @lock = Mutex.new
+
+      module_function
+
+      # Asks a plugin one question.
+      #
+      # @param adapter [Bluebook::Adapter] the plugin adapter whose module answers
+      # @param question [String] the qualified query, such as `"Calendar::Event.Occurrences"`
+      # @param args [Hash] the query's arguments as plain data, a referenced record as its state
+      # @return [Array<Hash>, Hash] the plugin's rows
+      # @raise [PluginRefusal] if the plugin refuses the question
+      # @raise [WiringError] if the module cannot run or answers something that is not the contract
+      def ask(adapter, question, args)
+        reply = run(adapter, JSON.generate(question: question, args: args))
+        return reply.fetch("rows") if reply.key?("rows")
+        raise PluginRefusal, "#{question}: #{reply["refused"]}" if reply.key?("refused")
+
+        raise WiringError, "#{adapter.name} answered #{question} with neither rows nor a refusal"
+      end
+
+      # Compiles a plugin's module once, so a missing or broken module stops the boot.
+      #
+      # @param adapter [Bluebook::Adapter] the plugin adapter to compile
+      # @return [void]
+      # @raise [WiringError] if the module is missing or is not wasm
+      def compile!(adapter) = compiled(adapter)
+
+      def run(adapter, input)
+        engine, wasm_module, linker = compiled(adapter)
+        output = +""
+        store  = Wasmtime::Store.new(engine, wasi_p1_config: wasi_config(input, output))
+        start(linker.instantiate(store, wasm_module), adapter)
+        JSON.parse(output)
+      rescue JSON::ParserError => e
+        raise WiringError, "#{adapter.name} answered with text that is not JSON: #{e.message}"
+      end
+
+      # The WASI setup a run gets: fixed clock and randomness, `input` on stdin, and stdout
+      # written into `output` up to the cap.
+      def wasi_config(input, output)
+        config = Wasmtime::WasiConfig.new.add_determinism
+        config.set_stdin_string(input).set_stdout_buffer(output, STDOUT_CAP)
+      end
+
+      # A command ends by returning from `_start` or by exiting; only exit code 0 is an answer.
+      def start(instance, adapter)
+        instance.invoke("_start")
+      rescue Wasmtime::WasiExit => e
+        raise WiringError, "#{adapter.name} exited with code #{e.code}" unless e.code.zero?
+      rescue Wasmtime::Trap, Wasmtime::Error => e
+        raise WiringError, "#{adapter.name} failed: #{e.message}"
+      end
+
+      def compiled(adapter)
+        path = adapter.plugin_path
+        @lock.synchronize { @compiled[path] ||= compile(adapter, path) }
+      end
+
+      def compile(adapter, path)
+        require_wasmtime!(adapter)
+        raise WiringError, "#{adapter.name} runs #{adapter.runs}, but there is no #{path}" unless File.file?(path)
+
+        engine = Wasmtime::Engine.new
+        linker = Wasmtime::Linker.new(engine)
+        Wasmtime::WASI::P1.add_to_linker_sync(linker)
+        [engine, Wasmtime::Module.from_file(engine, path), linker]
+      rescue Wasmtime::Error => e
+        raise WiringError, "#{adapter.name} runs #{adapter.runs}, which is not a wasm module: #{e.message}"
+      end
+
+      # Lazy, so a domain that answers no query with a plugin does not need the wasmtime gem.
+      def require_wasmtime!(adapter)
+        require "wasmtime"
+      rescue LoadError
+        raise WiringError, "#{adapter.name} is a wasm plugin, which needs the wasmtime gem: " \
+                           "add `gem \"wasmtime\"` to the Gemfile"
+      end
+    end
+  end
+end

data/lib/hecks/runtime.rb

@@ -35,7 +35,7 @@ module Hecks
       # The registry declarations are currently landing in, or nil outside a boot.
       attr_reader :current_registry
 
-      # Loads a bluebook directory and returns the Dispatcher bound to it. See Loader.boot.
+      # Loads a bluebook directory and returns the Dispatcher bound to it. See `Hecks.boot`.
       #
       #   Hecks::Runtime.boot("examples/pizzas/bluebook")
       #     .dispatch("Pizzas::Pizza.CreatePizza", name: "Margherita")
@@ -44,42 +44,42 @@ module Hecks
       # @param shared [String, nil] a shared-root override
       # @param install_driving [Boolean] whether to install the Ruby facade constants
       # @param environment [String, nil] the environment name for `Adapters::Folder#load_domain`
-      # @return [Runtime::Dispatcher, Runtime::RemoteDispatcher] the dispatcher bound
+      # @return [Runtime::Dispatcher, Adapters::Lambda::RemoteDispatcher] the dispatcher bound
       #   to the booted domain
-      def boot(path, shared: nil, install_driving: true, environment: Runtime::Loader::FROM_ENV)
-        Loader.boot(path, shared: shared, install_driving: install_driving, environment: environment)
+      def boot(path, shared: nil, install_driving: true, environment: Assembly::FROM_ENV)
+        Hecks.boot(path, shared: shared, install_driving: install_driving, environment: environment)
       end
 
-      # Loads a domain's declarations without binding any adapter. See Loader.describe.
+      # Loads a domain's declarations without binding any adapter. See `Hecks.describe`.
       #
       # @param path [String] path to a domain directory, or a file inside one
       # @param shared [String, nil] a shared-root override
       # @param environment [String, nil] the environment overlay; defaults to `HECKS_ENVIRONMENT`
       # @return [Runtime::Loader::Described] the loaded registry, answering `registry`
-      def describe(path, shared: nil, environment: Runtime::Loader::FROM_ENV)
-        Loader.describe(path, shared: shared, environment: environment)
+      def describe(path, shared: nil, environment: Assembly::FROM_ENV)
+        Hecks.describe(path, shared: shared, environment: environment)
       end
 
-      # Finishes a boot from declarations `describe` already loaded. See Loader.boot_described.
+      # Finishes a boot from declarations `describe` already loaded. See `Hecks.boot_described`.
       #
       # @param described [Runtime::Loader::Described] what `describe` answered
       # @param install_driving [Boolean] whether to install the Ruby facade constants
-      # @return [Runtime::Dispatcher, Runtime::RemoteDispatcher] the dispatcher bound
+      # @return [Runtime::Dispatcher, Adapters::Lambda::RemoteDispatcher] the dispatcher bound
       #   to the booted domain
       def boot_described(described, install_driving: true)
-        Loader.boot_described(described, install_driving: install_driving)
+        Hecks.boot_described(described, install_driving: install_driving)
       end
 
-      # Loads only the given files of a domain; otherwise like `boot`. See Loader.boot_files.
+      # Loads only the given files of a domain; otherwise like `boot`. See `Hecks.boot_files`.
       #
       # @param paths [String, Array<String>] one or more file paths within the domain
       # @param shared [String, nil] a shared-root override
       # @param install_driving [Boolean] whether to install the Ruby facade constants
       # @param environment [String, nil] the environment name for the selected-file loader
-      # @return [Runtime::Dispatcher, Runtime::RemoteDispatcher] the dispatcher bound
+      # @return [Runtime::Dispatcher, Adapters::Lambda::RemoteDispatcher] the dispatcher bound
       #   to the booted domain
-      def boot_files(paths, shared: nil, install_driving: true, environment: Runtime::Loader::FROM_ENV)
-        Loader.boot_files(paths, shared: shared, install_driving: install_driving, environment: environment)
+      def boot_files(paths, shared: nil, install_driving: true, environment: Assembly::FROM_ENV)
+        Hecks.boot_files(paths, shared: shared, install_driving: install_driving, environment: environment)
       end
 
       # Bind the ambient registry for the duration of the block, restoring

data/lib/hecks/rust_build/command_schemas.rb

@@ -0,0 +1,27 @@
+require "fileutils"
+require "json"
+require_relative "../projections/command_schema"
+
+module Hecks
+  module RustBuild
+    # `schemas.json` beside a generated domain's `ir.json`: each command's JSON Schema by
+    # `Aggregate/Command`. The host has no Ruby, so it serves what the build projected here.
+    module CommandSchemas
+      FILE = "schemas.json".freeze
+
+      module_function
+
+      # @param bluebook [Bluebook::Declaration] the target domain's bluebook
+      # @param dir [String] the domain's generated directory
+      # @return [String] the path written
+      def write(bluebook, dir)
+        files = Projections::CommandSchema.call(bluebook: bluebook)
+        schemas = files.to_h do |path, text|
+          [path.delete_prefix("#{bluebook.name}/").delete_suffix(".schema.json"), JSON.parse(text)]
+        end
+        FileUtils.mkdir_p(dir)
+        File.join(dir, FILE).tap { |path| File.write(path, "#{JSON.pretty_generate(schemas)}\n") }
+      end
+    end
+  end
+end

data/lib/hecks/rust_build/conformance/surface.rb

@@ -23,18 +23,55 @@ module Hecks
             "events"    => result[:events].map { |event| event_surface(event) },
             "refusals"  => result[:refusals].map { |refusal| refusal_surface(refusal) }
           }
-          dry_runs = dry_run_surface(result[:dry_runs])
-          surface["dry_runs"] = dry_runs unless dry_runs.empty?
-          surface
+          surface.merge(read_only_surface(result)).merge(cross_domain_surface(result[:cross_domain]))
+        end
+
+        # What each `across` policy delivered (policy, target verb, payload), omitted when none did.
+        def cross_domain_surface(deliveries)
+          rows = JSON.parse(JSON.generate(deliveries || []))
+          rows.empty? ? {} : { "cross_domain" => rows }
+        end
+
+        # The dry runs and validations, each omitted when the script has none.
+        def read_only_surface(result)
+          dry_runs = dry_run_surface(result[:dry_runs], result[:dry_run_traces])
+          validations = JSON.parse(JSON.generate(result[:validations] || []))
+          { "dry_runs" => dry_runs, "validations" => validations }.reject { |_, entries| entries.empty? }
         end
 
         def refusal_surface(refusal)
           { "verb" => refusal[:verb], "error" => refusal[:error], "kind" => refusal[:kind]&.split("::")&.last }
         end
 
-        # `verb` and `ok` only, as `Hecks::Fuzzing::Differential` compares; omitted when none.
-        def dry_run_surface(dry_runs)
-          dry_runs.map { |dry| { "verb" => dry[:verb].to_s, "ok" => dry[:ok] } }
+        # The stages whose every refusal both engines list.
+        COLLECTED_STAGES = %w[givens ensures invariants].freeze
+
+        # In the arguments stage Rust lists the unknown and absent names, one refusal each; a
+        # coercion mismatch it raises alone, so a run with one is compared on `ok` alone.
+        LISTED_ARGUMENT_CLASSES = %w[AbsentArgument UnknownArgument].freeze
+
+        # `verb` and `ok`, as `Hecks::Fuzzing::Differential` compares, and for a run refused where
+        # both engines list every refusal, each one's kind, stage, attribute, path and rule.
+        def dry_run_surface(dry_runs, traces = [])
+          dry_runs.zip(traces).map do |dry, trace|
+            reasons = trace&.dig(:validation, :reasons) unless dry[:ok]
+            { "verb" => dry[:verb].to_s, "ok" => dry[:ok] }.merge(collected_refusals(reasons))
+          end
+        end
+
+        # @param reasons [Array<Array>, nil] each as `[kind, stage, attribute, path, rule, class]`
+        # @return [Hash] `{"refusals" => reasons}` without the class, if both engines list them all
+        def collected_refusals(reasons)
+          return {} unless reasons&.any? && listed_in_full?(reasons)
+
+          { "refusals" => reasons.map { |reason| reason.first(5) } }
+        end
+
+        def listed_in_full?(reasons)
+          stage = reasons.first[1]
+          return true if COLLECTED_STAGES.include?(stage)
+
+          stage == "arguments" && reasons.all? { |reason| LISTED_ARGUMENT_CLASSES.include?(reason.last) }
         end
 
         def event_surface(event)
@@ -47,7 +84,13 @@ module Hecks
         def normalize(theirs)
           strip_snapshot_flags(theirs["instances"])
           strip_timestamps(theirs["events"])
-          theirs
+          theirs.merge(cross_domain_surface(kernel_deliveries(theirs["cross_domain_reactions"])))
+        end
+
+        # The kernel's per-step cross-domain reactions as one list of policy, target verb and
+        # payload.
+        def kernel_deliveries(per_step)
+          Array(per_step).flatten.map { |row| row.slice("policy", "target_verb", "payload") }
         end
 
         def strip_snapshot_flags(instances)