hecks 3.4.2 → 3.6.0

data/lib/hecks/runtime/registry/durability_warnings.rb

@@ -0,0 +1,71 @@
+module Hecks
+  module Runtime
+    class Registry
+      # Warns, never refuses, when a domain's reactions or sagas would not survive a crash.
+      # Mixed into {Verification}.
+      module DurabilityWarnings
+        private
+
+        # A domain with policies/a process_manager but no outbox on its bound adapter
+        # (`AppendOnly#outbox?`) runs reactions inline — lost on a crash between a
+        # commit and its reaction. A warning, not a refusal: Memory has an in-process
+        # outbox, so dev/test stays quiet, but file/remote adapters need this to be loud.
+        def warn_undurable_outbox!(hecksagon)
+          bluebook_ir = bluebook(hecksagon.domain)
+          return unless bluebook_ir && reactions_declared?(bluebook_ir)
+
+          anchor = bluebook_ir.aggregates.first or return
+          bind = Ports::Persistence::BindingPolicy.resolve(self, hecksagon.domain, anchor)
+          return if adapter_class(bind.adapter) <= Ports::Persistence::RemoteRuntime
+          return if repository(hecksagon.domain, anchor).outbox?
+
+          warn undurable_outbox_wording(hecksagon, bind)
+        rescue WiringError
+          nil
+        end
+
+        def undurable_outbox_wording(hecksagon, bind)
+          "[hecks] #{hecksagon.domain} declares policies/process_managers but its persistence adapter " \
+            "(#{bind.adapter}) has no outbox — reactions run inline and a crash between a command's commit " \
+            "and its reactions loses them silently. Bind SqlitePersistence or Postgres for a durable outbox " \
+            "(see Runtime::Outbox), or accept in-process-only reactions on purpose."
+        end
+
+        def reactions_declared?(bluebook_ir)
+          !bluebook_ir.process_managers.empty? || any_policy_listens_to?(bluebook_ir)
+        end
+
+        def any_policy_listens_to?(bluebook_ir)
+          emitted = emitted_event_names(bluebook_ir)
+          @declared.bluebooks.each_value.any? do |candidate|
+            candidate.policies.any? { |policy| emitted.include?(policy.event_name.to_s) }
+          end
+        end
+
+        # The name of every event the aggregates' commands and port operations announce.
+        def emitted_event_names(bluebook_ir)
+          bluebook_ir.aggregates.flat_map do |aggregate|
+            aggregate.commands.flat_map(&:emits) +
+              aggregate.ports.flat_map { |port| port.operations.flat_map { |op| [*op.emits, op.answers, op.refuses] } }
+          end.compact.map(&:to_s)
+        end
+
+        # A warning, not a refusal: running sagas on a store with no `save_saga` is
+        # legitimate on purpose in a fast in-memory test/dev boot.
+        def warn_undurable_sagas!(hecksagon)
+          bluebook_ir = bluebook(hecksagon.domain)
+          return unless bluebook_ir
+          return if bluebook_ir.process_managers.empty?
+          return unless saga_persistence(hecksagon.domain).equal?(Ports::Persistence::NULL_SAGA_STORE)
+
+          names = bluebook_ir.process_managers.map(&:name).join(", ")
+          warn "[hecks] #{hecksagon.domain} declares process_manager(s) #{names} but its resolved " \
+               "persistence adapter has no save_saga — saga state advances correctly in-process " \
+               "and is LOST on restart (no checkpoint, no rehydration, no compensation replay). " \
+               "Bind this domain to an adapter that implements save_saga if this process_manager " \
+               "must survive a crash."
+        end
+      end
+    end
+  end
+end

data/lib/hecks/runtime/registry/hecksagon_rules.rb

@@ -0,0 +1,124 @@
+module Hecks
+  module Runtime
+    class Registry
+      # The checks a loaded hecksagon owes: roles need an authorization provider, attachments need
+      # their sibling hecksagon, a bounded chapter needs its ACL, and a chapter's declared
+      # capabilities need what they name. Mixed into {Verification}.
+      module HecksagonRules
+        private
+
+        # Checked once against the merged hecksagon so a domain split across multiple
+        # hecksagon files sees every `attaches` declaration first. A role is real
+        # access control only once an authorization provider exists to check it against
+        # (ADR 0025); a provider is recognized by declaring authorization, not by name.
+        def refuse_ungoverned_roles!(hecksagon)
+          return if authorization_provider_for(hecksagon.domain)
+
+          bluebook_ir = bluebook(hecksagon.domain)
+          return unless bluebook_ir
+
+          offender = commands_in(bluebook_ir).find { |command| !command.role.to_s.empty? }
+          return unless offender
+
+          raise WiringError,
+                "#{offender.hecks_fqn} declares role #{offender.role.inspect}, but " \
+                "#{hecksagon.domain}'s hecksagon never #{authorization_attachment_hint} — role is only " \
+                "real access control once an authorization provider is attached to check it against; " \
+                "without that it is silent decoration, the exact defect this refusal exists to catch"
+        end
+
+        # `attaches` loads a bounded context; the consumer must declare the sibling hecksagon
+        # that is its ACL (Governance/Identity/Privacy already do). A vendored package only
+        # loads its `.bluebook` files, so persistence, Governance and the `translates` ACL live
+        # on that sibling too, or cross-context field mapping has nowhere to be written.
+        def refuse_unwired_attachments!(hecksagon)
+          hecksagon.attachments.each do |attachment|
+            next if hecksagon(attachment.chapter_name)
+
+            raise WiringError, unwired_attachment_message(hecksagon, attachment)
+          end
+        end
+
+        def unwired_attachment_message(hecksagon, attachment)
+          chapter_name = attachment.chapter_name
+          what = attachment.vendor? ? "vendored bluebook #{attachment.name.inspect}" : chapter_name.inspect
+          "#{hecksagon.domain} attaches #{what} " \
+            "(bounded context #{chapter_name}) but never declared " \
+            "Hecks.hecksagon #{chapter_name.inspect} — put that sibling " \
+            "(and any `translates` ACL) in context_map.hecksagon; " \
+            "same-name blocks merge, order-independent."
+        end
+
+        # An explicit `bounded` mark on a consumer chapter always needs an ACL. `attaches`
+        # marks the attached chapter bounded and requires the sibling
+        # hecksagon above; they don't require a `translates` on it unless the consumer also
+        # wrote `bounded`.
+        # rust/host Google sign-in reads ir.json's membership/identity keys, never a deploy-time
+        # env var; Membership without Identity means provision cannot Register/Link an identity.
+        def refuse_membership_without_identity!
+          return unless @declared.bluebooks.values.any? { |chapter| chapter.provides?(Bluebook::Capabilities::MEMBERSHIP) }
+          return if @declared.bluebooks.values.any? { |chapter| chapter.provides?(Bluebook::Capabilities::IDENTITY) }
+
+          raise WiringError,
+                "a chapter that provides \"membership\" is loaded, but none provides " \
+                "\"identity\" — rust/host Google sign-in cannot register or link an " \
+                "identity from the hecksagon/world. Attach Identity (`attaches " \
+                "\"Identity\"` plus a sibling Hecks.hecksagon \"Identity\") so the " \
+                "identity verbs are exported onto ir.json, not guessed at deploy."
+        end
+
+        # A hecksagon attaches after its chapter builds, so this is the first point a
+        # declared `:port_operation` capability can be checked against it.
+        def refuse_unresolved_port_operations!
+          @declared.bluebooks.each_value do |chapter|
+            chapter.provides.each { |row| refuse_unresolved_port_operation!(chapter, row) }
+          end
+        end
+
+        def refuse_unresolved_port_operation!(chapter, row)
+          return unless Bluebook::Capabilities::CONTRACTS.dig(row.capability, row.key.to_sym) == :port_operation
+          return if port_operation_declared?(chapter, row.verb)
+
+          raise WiringError,
+                "#{chapter.name} provides #{row.capability.inspect} #{row.key}: #{row.verb.inspect}, " \
+                "but its hecksagon declares no such port operation — declare it with " \
+                "`#{chapter.name}::Aggregate.port \"Port\" do operation \"Operation\" ... end`."
+        end
+
+        def port_operation_declared?(chapter, verb)
+          aggregate_name, port_name, operation_name = verb.split(".", 3)
+          ports = chapter.aggregate(aggregate_name)&.ports || []
+          ports.any? { |port| port.name == port_name && port.operations.any? { |op| op.hecks_name == operation_name } }
+        end
+
+        def refuse_bounded_without_acl!(hecksagon)
+          return unless hecksagon.bounded?
+          return if hecksagon.translates.any?
+
+          raise WiringError,
+                "#{hecksagon.domain} is marked bounded but never declared a " \
+                "translates ACL — a bounded chapter wraps in its own module and " \
+                "cross-context field mapping lives on the hecksagon, not in " \
+                "rust/host and not as a field list on the bluebook. " \
+                "Add `translates \"Name\" do on Foreign::Event; trigger Local::Command, " \
+                "with: { ... } end` (any field) or drop `bounded`."
+        end
+
+        # Derived from whichever framework members actually declare `provides
+        # "authorization"` — never a hardcoded name.
+        def authorization_attachment_hint
+          providers = Framework.providers_of(Bluebook::Capabilities::AUTHORIZATION)
+          return "attaches a chapter that provides \"authorization\" (no framework member declares one)" if providers.empty?
+
+          providers.map { |name| "attaches #{name.inspect}" }.join(" or ")
+        end
+
+        # Every command this domain declares, an aggregate's own and every entity nested
+        # inside one — the same reach dispatch-time role checking needs.
+        def commands_in(bluebook_ir)
+          bluebook_ir.aggregates.flat_map { |aggregate| aggregate.commands + aggregate.entities.flat_map(&:commands) }
+        end
+      end
+    end
+  end
+end

data/lib/hecks/runtime/registry/merging.rb

@@ -0,0 +1,49 @@
+module Hecks
+  module Runtime
+    class Registry
+      # Folds a later `.hecksagon` or `.world` for a domain into the one already registered, so a
+      # base file plus an environment overlay both take effect.
+      module Merging
+        # Concatenates every list-shaped fact from base and overlay. `binds` is additive too:
+        # an overlay rebinding an aggregate is meant to shadow the base's bind at resolution
+        # time, not erase it — `Ports::Persistence::BindingPolicy.resolve`'s "exactly one
+        # authoritative bind" check is what actually catches a genuine double-bind.
+        #
+        # @param base [Bluebook::Hecksagon] the domain's already-registered wiring
+        # @param overlay [Bluebook::Hecksagon] the newly loaded block's own wiring to
+        #   fold in
+        # @return [Bluebook::Hecksagon] a new wiring with every list-shaped fact
+        #   concatenated, `base` then `overlay`
+        def merge_hecksagons(base, overlay)
+          # Order-independent: list facts uniq, so loading context_map before or after the
+          # domain file yields the same merged hecksagon.
+          lists = %i[subscriptions attachments translates].to_h do |facet|
+            [facet, (base.public_send(facet) + overlay.public_send(facet)).uniq]
+          end
+          Bluebook::Hecksagon.new(domain: base.domain, binds: base.binds + overlay.binds,
+                                  bounded: base.bounded? || overlay.bounded?, **lists)
+        end
+
+        # Scalars (`realm`, `latest`, `default_database`, `default_adapter`): the overlay's
+        # value wins when present, else the base's survives. `settings` is a shallow merge
+        # keyed by verb (and `"verb:adapter"`); an overlay key replaces the base's whole
+        # resolved hash for that key, it does not deep-merge within it.
+        #
+        # @param base [Bluebook::World] the domain's already-registered world
+        # @param overlay [Bluebook::World] the newly loaded block's own world to fold in
+        # @return [Bluebook::World] a new world with `overlay`'s scalars winning when
+        #   present, and `settings` shallow-merged, `overlay`'s keys winning
+        def merge_worlds(base, overlay)
+          Bluebook::World.new(
+            domain:           base.domain,
+            realm:            overlay.realm || base.realm,
+            latest:           overlay.latest || base.latest,
+            settings:         base.settings.merge(overlay.settings),
+            default_database: overlay.default_database || base.default_database,
+            default_adapter:  overlay.default_adapter || base.default_adapter
+          )
+        end
+      end
+    end
+  end
+end

data/lib/hecks/runtime/registry/providers.rb

@@ -0,0 +1,139 @@
+module Hecks
+  module Runtime
+    class Registry
+      # Finds the loaded chapter that provides a capability for a domain: authorization, identity,
+      # membership, newsletters, registrations and payments.
+      module Providers
+        # The chapter that answers a role check for `domain`: the domain's own chapter, or
+        # a chapter its hecksagon attaches, that declares `provides "authorization"`.
+        #
+        # @param domain [String, Symbol] the domain whose role checks are being resolved
+        # @return [Bluebook::Chapter, nil] the chapter that answers `domain`'s role
+        #   checks, or nil if none does
+        def authorization_provider_for(domain)
+          names = [domain.to_s, *Array(hecksagon(domain)&.member_chapters)]
+          names.filter_map { |name| bluebook(name) }
+               .find { |chapter| chapter.provides?(Bluebook::Capabilities::AUTHORIZATION) }
+        end
+
+        # Every loaded chapter declaring `provides "authorization"`.
+        #
+        # @return [Array<Bluebook::Chapter>] every loaded chapter that provides
+        #   authorization
+        def authorization_providers
+          bluebooks.values.select { |chapter| chapter.provides?(Bluebook::Capabilities::AUTHORIZATION) }
+        end
+
+        # The chapter that answers "who is this authenticated pair" for `domain`: the
+        # domain's own chapter, or a framework member its hecksagon attaches, that
+        # declares `provides "identity"`.
+        #
+        # @param domain [String, Symbol] the domain whose identity chapter is being resolved
+        # @return [Bluebook::Chapter, nil] the chapter that answers `domain`'s identity
+        #   questions, or nil if none does
+        def identity_provider_for(domain)
+          names = [domain.to_s, *Array(hecksagon(domain)&.member_chapters)]
+          attached = names.filter_map { |name| bluebook(name) }
+                          .find { |chapter| chapter.provides?(Bluebook::Capabilities::IDENTITY) }
+          return attached if attached
+
+          # Falls back to any loaded chapter: a consuming domain often wires Identity as
+          # Hecks.hecksagon "Identity" rather than via `attaches`, so it's loaded but
+          # not listed on the consumer's own hecksagon.
+          bluebooks.values.find { |chapter| chapter.provides?(Bluebook::Capabilities::IDENTITY) }
+        end
+
+        # The chapter that answers "who may sign in" for `domain`: the domain's own
+        # chapter, a framework member, or a vendored embryonaut bluebook it attaches,
+        # that declares `provides "membership"`.
+        #
+        # Vendored packages are included, since membership ships as a vendored
+        # embryonaut_bluebooks chapter, not a framework member.
+        #
+        # @param domain [String, Symbol] the domain whose sign-in aggregate is being resolved
+        # @return [Bluebook::Chapter, nil] the chapter that answers `domain`'s membership
+        #   questions, or nil if none does
+        def membership_provider_for(domain)
+          vendored_provider_for(domain, Bluebook::Capabilities::MEMBERSHIP)
+        end
+
+        # The chapter that answers the guest newsletter signup for `domain`: the domain's
+        # own chapter, a framework member, or a vendored embryonaut bluebook it attaches,
+        # that declares `provides "newsletter"`.
+        #
+        # @param domain [String, Symbol] the domain whose newsletter chapter is being resolved
+        # @return [Bluebook::Chapter, nil] the chapter that answers `domain`'s newsletter
+        #   signup, or nil if none does
+        def newsletter_provider_for(domain)
+          vendored_provider_for(domain, Bluebook::Capabilities::NEWSLETTER)
+        end
+
+        # The chapter that answers sending a newsletter issue for `domain` —
+        # resolved the same way as `newsletter_provider_for`, by what it
+        # declares (`provides "newsletter_issues"`). Nil when none does.
+        #
+        # @param domain [String, Symbol] the domain whose issue-sending chapter is being resolved
+        # @return [Bluebook::Chapter, nil] the chapter that answers `domain`'s issue sending,
+        #   or nil if none does
+        def newsletter_issues_provider_for(domain)
+          vendored_provider_for(domain, Bluebook::Capabilities::NEWSLETTER_ISSUES)
+        end
+
+        # The chapter that answers scheduling sessions and registrations for `domain`,
+        # resolved the same way as `payments_provider_for`, by declaring `provides "registrations"`.
+        #
+        # @param domain [String, Symbol] the domain whose registrations chapter is being resolved
+        # @return [Bluebook::Chapter, nil] the chapter that answers `domain`'s registrations,
+        #   or nil if none does
+        def registrations_provider_for(domain)
+          vendored_provider_for(domain, Bluebook::Capabilities::REGISTRATIONS)
+        end
+
+        # The chapter that owns the business's payment-processor connection for
+        # `domain` — resolved by what it declares (`provides "payment_connection"`).
+        # Nil when none does.
+        #
+        # @param domain [String, Symbol] the domain whose payment-connection chapter is
+        #   being resolved
+        # @return [Bluebook::Chapter, nil] the chapter that owns `domain`'s payment connection,
+        #   or nil if none does
+        def payment_connection_provider_for(domain)
+          vendored_provider_for(domain, Bluebook::Capabilities::PAYMENT_CONNECTION)
+        end
+
+        # The chapter that takes payments for `domain`: the domain's own chapter, a
+        # framework member, or a vendored embryonaut bluebook it attaches, that
+        # declares `provides "payments"`.
+        #
+        # @param domain [String, Symbol] the domain whose payments chapter is being resolved
+        # @return [Bluebook::Chapter, nil] the chapter that takes `domain`'s payments, or nil
+        #   if none does
+        def payments_provider_for(domain)
+          vendored_provider_for(domain, Bluebook::Capabilities::PAYMENTS)
+        end
+
+        # The chapter that provides `capability` for `domain`: the domain's own chapter,
+        # a framework member its hecksagon attaches, or a vendored embryonaut bluebook
+        # it attaches, that declares it.
+        #
+        # Falls back to any loaded chapter, since a consuming domain often wires a
+        # vendored chapter as its own `Hecks.hecksagon "Name"` rather than via
+        # `attaches ... from: :vendor`, so it's loaded but not listed on the consumer's hecksagon.
+        #
+        # @param domain [String, Symbol] the domain the provider is resolved for
+        # @param capability [String] the capability's name, such as
+        #   `Bluebook::Capabilities::MEMBERSHIP`
+        # @return [Bluebook::Chapter, nil] the providing chapter, or nil if none loaded does
+        def vendored_provider_for(domain, capability)
+          hecksagon = hecksagon(domain)
+          names = [domain.to_s, *Array(hecksagon&.member_chapters)]
+          attached = names.filter_map { |name| bluebook(name) }
+                          .find { |chapter| chapter.provides?(capability) }
+          return attached if attached
+
+          bluebooks.values.find { |chapter| chapter.provides?(capability) }
+        end
+      end
+    end
+  end
+end

data/lib/hecks/runtime/registry/query_verification.rb

@@ -0,0 +1,144 @@
+module Hecks
+  module Runtime
+    class Registry
+      # Holds every declared query to exactly one answer path, and a bound query to an adapter that
+      # implements it. Mixed into {Verification}.
+      module QueryVerification
+        private
+
+        # A query has exactly one answer path. It is derivable when the bluebook says which of the
+        # aggregate's own records it wants (a where, order_by, limit or offset, or no arguments at
+        # all: the plain list) and returns no value object of its own; it is bound when it
+        # `returns` a value object and the hecksagon names the port whose adapter answers it. None
+        # of the two is "no answer path"; both is "two answer paths". A bound query also needs an
+        # adapter behind its port that implements it, found here so it fails at boot rather than
+        # on the first ask.
+        def refuse_unanswerable_queries!
+          @declared.bluebooks.each_value do |chapter|
+            chapter.aggregates.each do |aggregate|
+              refuse_misbound_queries!(chapter, aggregate)
+
+              aggregate.queries.each { |query| refuse_answer_paths!(chapter, aggregate, query) }
+              aggregate.entities.each do |entity|
+                entity.queries.each { |query| refuse_entity_answer_path!(chapter, aggregate, entity, query) }
+              end
+            end
+          end
+        end
+
+        # Counts the query's answer paths (the bindings, plus the derived answer when it exists)
+        # and refuses any count but one, then checks a bound query's shape and adapter.
+        def refuse_answer_paths!(chapter, aggregate, query)
+          where  = "#{chapter.name}::#{aggregate.hecks_name}.#{query.hecks_name}"
+          ports  = aggregate.query_bindings(query.hecks_name)
+          paths  = ports.size + (derivable?(query) ? 1 : 0)
+
+          if paths > 1
+            raise WiringError, "#{where} has two answer paths: #{answer_path_names(query, ports)} — " \
+                               "a query is answered from records or from outside, not both"
+          end
+          return check_bound_query!(chapter, aggregate, query, ports.first) if ports.any?
+          return if paths == 1
+
+          raise WiringError, no_answer_path_message(chapter, aggregate, query, where)
+        end
+
+        # A query that returns nothing and says something about which records it wants, or wants
+        # all of them. One that takes arguments but filters, orders and bounds nothing reads none
+        # of them, so it derives no answer.
+        def derivable?(query)
+          return false if query.returns
+
+          filters_records?(query) || query.attributes.empty?
+        end
+
+        def answer_path_names(query, ports)
+          names = ports.map { |port| "the #{port.name} port" }
+          names.unshift("its records") if derivable?(query)
+          names.join(" and ")
+        end
+
+        def no_answer_path_message(chapter, aggregate, query, where)
+          if query.returns
+            "#{where} has no answer path: it returns #{query.returns}, which only an adapter can " \
+              "answer, and no hecksagon port binds it. Bind it: `#{chapter.name}::#{aggregate.hecks_name}" \
+              ".port \"Port\" do answers_query \"#{query.hecks_name}\" end`."
+          else
+            "#{where} has no answer path: it declares no where and returns nothing, and no hecksagon " \
+              "binds it — its arguments (#{query.attributes.map(&:name).join(", ")}) select nothing. " \
+              "Add a where, or declare what it returns and bind it in the hecksagon."
+          end
+        end
+
+        # Checks what a binding needs to be answerable: a returned value object the aggregate
+        # declares, and one adapter behind the port that implements the query's method.
+        def check_bound_query!(chapter, aggregate, query, port)
+          where = "#{chapter.name}::#{aggregate.hecks_name}.#{query.hecks_name}"
+          refuse_unanswerable_binding!(where, port, query)
+          refuse_authorized_binding!(where, port, query)
+          unless Value.value_object_for(aggregate, query.returns_name)
+            raise WiringError, "#{where} returns #{query.returns_name}, but #{aggregate.hecks_name} " \
+                               "declares no such value object"
+          end
+
+          klass = AdapterLookup.adapter_class(self, port.name, asked: where)
+          AdapterLookup.check_answers!(klass, port.name, Naming.snake(query.hecks_name), query, asked: where)
+        end
+
+        # A bound query returns a value object and filters no stored records.
+        def refuse_unanswerable_binding!(where, port, query)
+          unless query.returns
+            raise WiringError, "#{where} is bound to the #{port.name} port but returns nothing — " \
+                               "declare the value object its answer takes with `returns`"
+          end
+          return unless filters_records?(query)
+
+          raise WiringError, "#{where} has two answer paths: it is bound to the #{port.name} port but " \
+                             "also declares where, order_by or limit over stored records"
+        end
+
+        def refuse_authorized_binding!(where, port, query)
+          return unless query.authorization
+
+          raise WiringError, "#{where} is bound to the #{port.name} port but declares authorize — " \
+                             "an outside answer is never tenant-scoped or authorized, so drop the " \
+                             "authorize or answer the query from records"
+        end
+
+        # An entity's query reads the elements of its aggregate's list, and nothing outside can
+        # be bound to one, so declaring a value object to return leaves it no answer.
+        def refuse_entity_answer_path!(chapter, aggregate, entity, query)
+          where = "#{chapter.name}::#{aggregate.hecks_name}.#{entity.hecks_name}.#{query.hecks_name}"
+          if query.returns
+            raise WiringError, "#{where} has no answer path: it returns #{query.returns}, but " \
+                               "only an aggregate's queries can be bound to a port"
+          end
+          return if derivable?(query)
+
+          raise WiringError, "#{where} has no answer path: it declares no where and returns nothing — its " \
+                             "arguments (#{query.attributes.map(&:name).join(", ")}) select nothing"
+        end
+
+        # Refuses a binding that names a query its aggregate does not declare, or names one twice
+        # on a single port (the DSL already refuses that, so this guards a hand-built port).
+        def refuse_misbound_queries!(chapter, aggregate)
+          aggregate.ports.each do |port|
+            names = port.answered_queries.map(&:name)
+            names.each do |name|
+              where = "#{chapter.name}::#{aggregate.hecks_name}.#{name}"
+              unless aggregate.query(name)
+                raise WiringError, "the #{port.name} port binds #{where}, which the aggregate does not declare"
+              end
+              raise WiringError, "#{where} has two answer paths: the #{port.name} port twice" if names.count(name) > 1
+            end
+          end
+        end
+
+        # A query that says anything about which stored records it wants.
+        def filters_records?(query)
+          !(query.wheres.empty? && query.order_by.nil? && query.limit.nil? && query.offset.nil?)
+        end
+      end
+    end
+  end
+end

data/lib/hecks/runtime/registry/read_repository.rb

@@ -0,0 +1,61 @@
+module Hecks
+  module Runtime
+    class Registry
+      # Chooses the repository a read goes through: a caught-up projection when one is bound,
+      # otherwise the authoritative repository.
+      module ReadRepository
+        # Resolves and memoizes the repository to read `aggregate` from — a caught-up
+        # projection when one is bound and current, otherwise the authoritative repository.
+        #
+        # @param domain [String, Symbol] name of the domain `aggregate` belongs to
+        # @param aggregate [Bluebook::Aggregate] the aggregate to resolve a read
+        #   repository for
+        # @return [Persistence::AppendOnly] the projection repository when one is bound
+        #   and caught up with the authoritative store; the authoritative repository
+        #   otherwise
+        # @raise [Runtime::WiringError] if the authoritative or projection bind cannot
+        #   be resolved
+        def read_repository(domain, aggregate)
+          key = [domain.to_s, aggregate.hecks_name]
+          binding = Ports::Projection.binds_for(self, domain, aggregate).first
+          return repository(domain, aggregate) unless binding
+
+          projection = (@projection_repositories[key] ||=
+                          Ports::Persistence::RepositoryFactory.build(self, domain, aggregate, binding,
+                                                                      recover: true, settings_verb: Ports::Projection::VERB))
+          authoritative = repository(domain, aggregate)
+          projection_current?(projection, authoritative) ? projection : authoritative
+        end
+
+        # Reports whether `projection`'s own journal entries and rows agree with
+        # `authoritative`'s, entry-for-entry.
+        #
+        # @param projection [Persistence::AppendOnly] the projection repository to check
+        # @param authoritative [Persistence::AppendOnly] the authoritative repository to
+        #   check `projection` against
+        # @return [Boolean] true when `projection` holds the same entries and rows as
+        #   `authoritative`, in the same order; false on any mismatch, or if comparing
+        #   them raises
+        def projection_current?(projection, authoritative)
+          entries_match?(projection.entries, authoritative.entries) &&
+            sorted_rows(projection) == sorted_rows(authoritative)
+        rescue StandardError
+          false
+        end
+
+        private
+
+        def entries_match?(projected_entries, source_entries)
+          projected_entries.length == source_entries.length &&
+            projected_entries.zip(source_entries).all? do |projected, source|
+              projected.operation == source.operation && projected.id == source.id && projected.state == source.state
+            end
+        end
+
+        def sorted_rows(repository)
+          repository.all.map(&:to_h).sort_by { |row| row.fetch(:id).to_s }
+        end
+      end
+    end
+  end
+end

data/lib/hecks/runtime/registry/runtime_state.rb

@@ -0,0 +1,27 @@
+module Hecks
+  module Runtime
+    class Registry
+      # What dispatching produces: the event log, the reaction and saga logs, and the saga
+      # instances in flight.
+      #
+      # `saga_dispatch_log` and `policy_dispatch_log` are Ruby-only; unlike `saga_log` and
+      # `reaction_log` (ported byte-for-byte to rust/src/kernel/orchestrate.rs, per
+      # spec/rust_conformance_spec.rb), they carry the raw dispatch-binding inputs
+      # Properties.dispatch_binding_fidelity re-derives.
+      RuntimeState = Struct.new(:event_log, :reaction_log, :reaction_events, :saga_log,
+                                :saga_dispatch_log, :policy_dispatch_log, :saga_instances) do
+        # @return [RuntimeState] every log empty and no saga instances
+        def self.fresh
+          new([], [], {}.compare_by_identity, [], [], [], Hash.new { |hash, key| hash[key] = {} })
+        end
+
+        # Empties every log and drops every saga instance.
+        #
+        # @return [void]
+        def clear
+          to_a.each(&:clear)
+        end
+      end
+    end
+  end
+end