hecks 0.2.0 → 0.3.0

data/lib/hecks/runtime/reaction_invocation.rb

@@ -0,0 +1,245 @@
+require_relative "../naming"
+require_relative "errors"
+require_relative "identity"
+require_relative "value"
+
+module Hecks
+  module Runtime
+    # Turns facts selected by a policy or process manager into the same
+    # receiver/payload envelope an outside caller uses. Reaction declarations
+    # historically selected both through one `with:` map, so this is the one
+    # compatibility seam that separates receiver identities from facts after
+    # resolving the declaration and before re-entering the dispatcher.
+    module ReactionInvocation
+      Target = Struct.new(:aggregate, :entities, :command, keyword_init: true)
+      # :facts, not :values — Struct.new already defines #values (every
+      # member's own value, in order); naming this field :values silently
+      # shadowed that with the single Hash it actually holds.
+      Scope = Struct.new(:name, :facts, keyword_init: true)
+
+      module_function
+
+      # The holding IR historically represented both an omitted projection and
+      # an explicitly empty `with: {}` as the same empty array. Builders now
+      # preserve declaration presence off-wire; reconstructed/legacy IR falls
+      # back to the old non-empty reading.
+      def projection_declared?(declaration)
+        if declaration.instance_variable_defined?(:@projection_declared)
+          declaration.instance_variable_get(:@projection_declared)
+        else
+          !declaration.with_spec.to_a.empty?
+        end
+      end
+
+      # A reaction's source names resolve lexically, not globally. Policies
+      # supply one event/row scope. Process managers supply current event then
+      # opening-event memory, while correlation is an explicit binding ahead
+      # of both. Missing names are refused here rather than materialized as nil
+      # and accidentally presented as target command facts.
+      def resolve_mapping(with_spec:, scopes:, bindings: {}, label: "reaction")
+        normalized_bindings = bindings.transform_keys(&:to_sym)
+        normalized_scopes = scopes.map do |scope|
+          scope = Scope.new(name: scope.first, facts: scope.last) unless scope.is_a?(Scope)
+          Scope.new(name: scope.name.to_s, facts: scope.facts.transform_keys(&:to_sym))
+        end
+
+        with_spec.to_h do |key, source|
+          value = if !source.is_a?(Symbol)
+                    source
+                  elsif normalized_bindings.key?(source)
+                    normalized_bindings.fetch(source)
+                  else
+                    visible = normalized_scopes.find { |scope| scope.facts.key?(source) }
+                    unless visible
+                      names = normalized_scopes.map(&:name).join(" then ")
+                      raise UnknownArgument,
+                            "#{label}'s with: reads :#{source}, which is not visible in #{names}"
+                    end
+                    visible.facts.fetch(source)
+                  end
+
+          [key.to_sym, Value.materialize(value)]
+        end
+      end
+
+      # A reaction without an explicit projection retains wholesale legacy
+      # forwarding. Choosing `with:` opts into the strict envelope: only target
+      # command attributes enter `with:`, while identities become `to:`.
+      def build(registry:, verb:, projected:, explicit:, passthrough: [], source_receiver: nil)
+        args = projected.transform_keys(&:to_sym)
+        unless explicit
+          return args unless source_receiver
+
+          # Compatibility calls still belong to Dispatcher when the target is
+          # absent: it owns the canonical UnknownVerb wording. Resolution here
+          # is only an optional opportunity to lift same-aggregate Event.id.
+          begin
+            target = resolve_target(registry, verb)
+          rescue UnknownVerb
+            return args
+          end
+          inherited_receiver = source_receiver_for(target, source_receiver)
+          return inherited_receiver ? args.merge(to: inherited_receiver) : args
+        end
+
+        target = resolve_target(registry, verb)
+        inherited_receiver = source_receiver_for(target, source_receiver)
+        facts = command_facts(target.command, args)
+        consumed = facts.keys
+
+        if target.entities.empty? && target.command.creates?
+          refuse_unconsumed!(target.command, args, consumed, passthrough)
+          return { with: facts }
+        end
+
+        aggregate_identity, aggregate_keys = identity_for(
+          target.aggregate,
+          args,
+          aliases:     aggregate_aliases(target),
+          value_owner: target.aggregate
+        )
+        aggregate_identity ||= inherited_receiver
+        require_identity!(verb, target.aggregate, aggregate_identity)
+        consumed.concat(aggregate_keys)
+
+        entity_identities = target.entities.map do |entity|
+          identity, keys = identity_for(
+            entity,
+            args,
+            aliases:     [Naming.reference_key(entity.hecks_name)],
+            value_owner: target.aggregate
+          )
+          require_identity!(verb, entity, identity)
+          consumed.concat(keys)
+          identity
+        end
+
+        refuse_unconsumed!(target.command, args, consumed, passthrough)
+
+        route = if entity_identities.empty?
+                  aggregate_identity
+                else
+                  { aggregate: aggregate_identity, entities: entity_identities }
+                end
+        { to: route, with: facts }
+      end
+
+      def resolve_target(registry, verb)
+        domain, aggregate_name, command_path = Naming.split_verb(verb)
+        raise UnknownVerb, "reaction target #{verb.inspect} is not a qualified command" unless command_path
+
+        bluebook = registry.bluebook(domain)
+        aggregate = bluebook&.aggregate(aggregate_name)
+        raise UnknownVerb, "reaction target #{verb.inspect} does not resolve to an aggregate" unless aggregate
+
+        *entity_names, command_name = command_path.split(".")
+        owner = aggregate
+        entities = entity_names.map do |entity_name|
+          entity = owner.entities.find { |candidate| candidate.hecks_name == entity_name }
+          raise UnknownVerb, "reaction target #{verb.inspect} does not resolve entity #{entity_name.inspect}" unless entity
+
+          owner = entity
+          entity
+        end
+        command = owner.command(command_name)
+        raise UnknownVerb, "reaction target #{verb.inspect} does not resolve to a command" unless command
+
+        Target.new(aggregate: aggregate, entities: entities, command: command)
+      end
+      private_class_method :resolve_target
+
+      def command_facts(command, args)
+        declared = command.attributes.map { |attribute| attribute.name.to_sym }
+        args.slice(*declared)
+      end
+      private_class_method :command_facts
+
+      def aggregate_aliases(target)
+        aliases = [:aggregate, Naming.reference_key(target.aggregate.name)]
+        aliases.unshift(target.command.addressing_key_for(target.aggregate.name)) if target.entities.empty?
+        aliases.compact.uniq
+      end
+      private_class_method :aggregate_aliases
+
+      # Event.id names the aggregate that emitted the event. It can therefore
+      # supply only the receiver of a non-creating command on that SAME root;
+      # it cannot address another aggregate, invent an entity identity, or turn
+      # a creation into a mutation. An explicit projected receiver is resolved
+      # first and remains authoritative.
+      def source_receiver_for(target, source_receiver)
+        return nil unless source_receiver
+        return nil unless target.entities.empty?
+        return nil if target.command.creates?
+
+        source = source_receiver.transform_keys(&:to_sym)
+        source_aggregate = source[:aggregate].to_s
+        same_aggregate = source_aggregate == if source_aggregate.include?("::")
+                                               target.aggregate.hecks_fqn
+                                             else
+                                               target.aggregate.hecks_name
+                                             end
+        return nil unless same_aggregate
+
+        identity = source[:identity]
+        identity.to_s unless identity.nil? || identity.to_s.empty?
+      end
+      private_class_method :source_receiver_for
+
+      def identity_for(construct, args, aliases:, value_owner:)
+        identity = Identity.of(construct, args, value_owner: value_owner)
+        return [identity, construct.identity_heads] if identity
+
+        aliases.each do |key|
+          key = key.to_sym
+          next unless args.key?(key)
+
+          identity = identity_from_alias(construct, args[key], value_owner)
+          return [identity, [key]] if identity
+        end
+
+        return [args[:id].to_s, [:id]] if args.key?(:id) && !args[:id].to_s.empty?
+
+        [nil, []]
+      end
+      private_class_method :identity_for
+
+      def identity_from_alias(construct, held, value_owner)
+        materialized = Value.materialize(held)
+        if materialized.is_a?(Hash)
+          keyed = materialized.transform_keys(&:to_sym)
+          nested = Identity.of(construct, keyed, value_owner: value_owner)
+          return nested if nested
+
+          if construct.identity_paths.one?
+            scalar = Identity.scalar(construct.identity_paths.first, keyed)
+            return scalar.to_s unless scalar.nil? || scalar.to_s.empty?
+          end
+
+          return nil
+        end
+
+        materialized.to_s unless materialized.nil? || materialized.to_s.empty?
+      end
+      private_class_method :identity_from_alias
+
+      def require_identity!(verb, construct, identity)
+        return if identity
+
+        raise TypeMismatch,
+              "reaction target #{verb} needs #{construct.hecks_name}'s receiver identity outside command facts"
+      end
+      private_class_method :require_identity!
+
+      def refuse_unconsumed!(command, args, consumed, passthrough)
+        allowed = consumed.map(&:to_sym) + Array(passthrough).map(&:to_sym)
+        unknown = args.keys - allowed
+        return if unknown.empty?
+
+        raise UnknownArgument,
+              "#{command.hecks_name} reaction projection contains neither receiver identity nor declared command facts: " \
+              "#{unknown.sort.join(', ')}"
+      end
+      private_class_method :refuse_unconsumed!
+    end
+  end
+end

data/lib/hecks/runtime/read_model_interpreter.rb

@@ -0,0 +1,266 @@
+require_relative "../rendering"
+require_relative "errors"
+require_relative "value"
+require_relative "refusal_wording"
+require_relative "tenant_scope"
+require_relative "../ports/query/in_memory"
+require_relative "../query_specification/field_path"
+
+module Hecks
+  module Runtime
+    class ReadModelInterpreter
+      def initialize(registry) = @registry = registry
+
+      def call(domain, model, args)
+        project(domain, model, args)
+      end
+
+      private
+
+      def project(domain, model, args)
+        bluebook = @registry.bluebook(domain)
+        rootless = model.reference_target.nil?
+        # BEFORE the adapter early-return below, so the SQLite path inherits it.
+        # Without this a stale caller passing a wrapped reference gets a
+        # path-dependent answer — an adapter could quietly open the wrapped
+        # reference while the in-process path reads it whole and finds nothing.
+        # Refused up front, identically on every path. Nothing to refuse for
+        # a rootless model — there's no reference argument to have offered
+        # wrong at all.
+        refuse_object_reference(model, args) unless rootless
+        reference_id = reference(args.fetch(model.reference_name)) unless rootless
+        # Computed off the ORIGINAL model, before TenantScope wraps it — the
+        # "which head do options apply to" question is about what the
+        # bluebook author declared, not about the synthetic tenant clause
+        # the wrapper adds underneath.
+        eligible = model.filtered_head_name
+        model = TenantScope.apply(model, args)
+        # A ROOTLESS, `group_by`-declared, or `count`/`median`-declared
+        # model skips the SQLite native escape hatch entirely (there is
+        # no root aggregate to look up a repository FOR when rootless,
+        # and `query_read_model` knows nothing about grouping or
+        # reducing) — always runs the in-process loop below instead.
+        # Correct everywhere ; not SQL-pushed-down for a SQLite-backed
+        # aggregate yet, a real, named limit, not a silent one — the
+        # same one `group_by` already accepted, extended here rather
+        # than narrowed.
+        unless rootless || model.group_by.any? || model.count? || model.median_field
+          repository = @registry.read_repository(domain, bluebook.aggregate(model.reference_target))
+          return repository.query_read_model(domain, model, args, bluebook) if repository.respond_to?(:query_read_model) && repository.adapter.respond_to?(:query_read_model)
+        end
+
+        # ROOT FIRST, ALWAYS — regardless of `include` order in the
+        # bluebook. `read_model_builder.rb`'s own `include` is
+        # documented "Order-independent" (the `:many` flag is resolved
+        # at build time, once `@reference_target` is known), but that
+        # promise was never kept HERE: this loop used to run heads in
+        # their literal declared order and match each "many" head
+        # against whatever was ALREADY in `projected` — empty, the
+        # very first time through, if a many-side head happened to be
+        # declared before the root. A real, live bug (not a guess):
+        # `include Promotion` before `include Item` on a read model
+        # whose root IS Item silently returned an empty array for
+        # Promotion — no error, just a wrong, too-small answer — while
+        # the reverse order worked purely by accident. `partition`,
+        # not `sort_by`: Ruby's `sort_by` is not guaranteed stable,
+        # and correctness here must not depend on it being so by
+        # chance on the current MRI build.
+        root_heads, other_heads = model.aggregate_heads.partition { |head| head[:aggregate] == model.reference_target }
+        projected = []
+        rows_by_as = {}
+        (root_heads + other_heads).each do |head|
+          rows = if head[:aggregate] == model.reference_target
+                   [fetch(bluebook, domain, head[:aggregate], reference_id)]
+                 elsif rootless
+                   # No root to FK-match against — a rootless model reads
+                   # each of its own heads WHOLE, independently. (Multiple
+                   # heads on one rootless model aren't cross-joined
+                   # against each other either — each is its own bulk
+                   # read. A real, deliberate scope limit for now.)
+                   records(bluebook, domain, head[:aggregate])
+                 else
+                   matching(records(bluebook, domain, head[:aggregate])) do |record|
+                     projected.any? do |source|
+                       reference_fields(bluebook.aggregate(head[:aggregate]), source[:aggregate]).any? do |field|
+                         source[:rows].any? { |parent| reference(record[field]) == parent.id }
+                       end
+                     end
+                   end
+                 end
+          rows = Ports::Query::InMemory.execute(rows, model, args) if head[:as] == eligible
+          projected << { aggregate: head[:aggregate], rows: rows }
+          rows_by_as[head[:as]] = head[:many] ? rows : rows.first
+        end
+        # Declared order preserved in the OUTPUT — only the
+        # computation above needed reordering, not what a caller sees
+        # back.
+        heads = model.aggregate_heads.each_with_object({}) { |head, report| report[head[:as]] = rows_by_as[head[:as]] }
+        grouped_head = group_by_target(model, bluebook)
+        reduced_head = aggregation_target(model, bluebook)
+        [heads.each_with_object({}) do |(as, value), out|
+          out[as] = if grouped_head && as == grouped_head[:as]
+                      nest(value.map { |record| Value.materialize_unwrapped(row(record)) }, model.group_by_fields)
+                    elsif reduced_head && as == reduced_head[:as] && model.count?
+                      value.length
+                    elsif reduced_head && as == reduced_head[:as]
+                      median(value, model.median_field)
+                    elsif value.is_a?(Array)
+                      value.map { |record| Value.materialize(row(record)) }
+                    else
+                      Value.materialize(row(value))
+                    end
+        end]
+      end
+
+      # `group_by`'s own declared fields, checked against the ONE
+      # many-side head they apply to (`seal_group_by` already refuses
+      # zero or several) — resolved here, once, rather than re-derived
+      # per row. Raises loudly on a typo'd field name rather than
+      # silently grouping every row into one bucket keyed `nil`.
+      def group_by_target(model, bluebook)
+        return nil unless model.group_by.any?
+
+        target = model.aggregate_heads.find { |head| head[:many] }
+        aggregate = bluebook.aggregate(target[:aggregate])
+        model.group_by_fields.each do |field|
+          next if aggregate.attribute(field)
+          # THE LIFECYCLE FIELD IS A FIELD, and refusing it here was a drift
+          # between two halves of the same language: `where(status: "logged")`
+          # has always been legal on the same aggregate, because a lifecycle
+          # state is stored on the record like anything else — it is simply
+          # declared by `lifecycle :status` rather than by `attribute`.
+          #
+          # It is also the grouping anybody actually wants. "How are we doing"
+          # over a bug ledger IS the count per status, and a report that could
+          # group by every field EXCEPT that one could not answer the question
+          # reports exist for.
+          next if aggregate.lifecycle && aggregate.lifecycle.field.to_sym == field.to_sym
+
+          raise ArgumentError,
+                "#{model.name}'s group_by names #{field.inspect}, but #{target[:aggregate]} " \
+                "declares no such attribute (it declares #{aggregate.attributes.map(&:name).join(', ')})"
+        end
+        target
+      end
+
+      # One level of nesting per field, in `group_by`'s own declared
+      # order — the leaf is the row with every grouped field removed
+      # (already spent, as the keys that reached it). ASSUMES the full
+      # `group_by` path uniquely identifies one row (true for grouping by
+      # an aggregate's own full identity, ConsoleSettings' own real use)
+      # — `leaves.first` silently keeps only the first row when several
+      # share the same full key path. A real, deliberate scope limit:
+      # true multi-row-per-leaf grouping would change the leaf shape
+      # from "one row" to "an array of rows", which no caller needs yet.
+      def nest(rows, fields)
+        field, *rest = fields
+        rows.group_by { |row| row[field] }.transform_values do |group|
+          # Strip ONLY the field just grouped by, not the whole remaining
+          # list — `rest`'s own fields have to survive into the recursive
+          # call below, or the NEXT level groups by a key that's already
+          # gone (found by trying it: a two-field group_by's own second
+          # level came back keyed `nil` for every group, every time).
+          stripped = group.map { |row| row.reject { |key, _| key == field } }
+          rest.empty? ? stripped.first : nest(stripped, rest)
+        end
+      end
+
+      # `count`/`median`'s own declared target — the SAME single
+      # many-side head `group_by_target` resolves, for the same reason
+      # (`seal_aggregation` already refuses zero or several many-side
+      # heads, and refuses count/median declared alongside group_by, so
+      # there is exactly one to name whenever this is asked at all).
+      # Raises loudly on a `median` field that doesn't exist, or exists
+      # but isn't numeric, rather than silently comparing garbage or
+      # averaging strings.
+      def aggregation_target(model, bluebook)
+        return nil unless model.count? || model.median_field
+
+        target = model.aggregate_heads.find { |head| head[:many] }
+        return target unless model.median_field
+
+        aggregate = bluebook.aggregate(target[:aggregate])
+        attribute = aggregate.attribute(model.median_field)
+        unless attribute
+          raise ArgumentError,
+                "#{model.name}'s median names #{model.median_field.inspect}, but #{target[:aggregate]} " \
+                "declares no such attribute (it declares #{aggregate.attributes.map(&:name).join(', ')})"
+        end
+        unless QuerySpecification::FieldPath.numeric?(attribute, []) { |type| aggregate.value_object(type) }
+          raise ArgumentError,
+                "#{model.name}'s median names #{model.median_field.inspect} on #{target[:aggregate]}, " \
+                "which is not numeric — median needs a numeric field (a bare number, or a " \
+                "value object carrying one)"
+        end
+        target
+      end
+
+      # THE STANDARD DEFINITION. An ODD count's median is its one true
+      # middle value, sorted ; an EVEN count's median is the AVERAGE of
+      # its two middle values — the common convention (as opposed to,
+      # say, always taking the lower of the two), and the one this
+      # session's own task named explicitly as the deliberate choice.
+      # An EMPTY collection has no median: nil, not zero, so a caller
+      # cannot mistake "nothing to average" for "the values averaged to
+      # zero". Reuses `Ports::Query::InMemory`'s own field reading
+      # (`FieldPath.dig` + `comparable`) — the same unwrap `where`/
+      # `order_by` already give a value-object-carrying field, so
+      # `median :daily_limit` on a `DailyLimit{cents}` field reads the
+      # same scalar an `order_by :daily_limit` comparison already would.
+      def median(rows, field)
+        values = rows.map { |record| Ports::Query::InMemory.comparable(QuerySpecification::FieldPath.dig(row(record), field)) }
+                     .compact.sort
+        return nil if values.empty?
+
+        middle = values.length / 2
+        values.length.odd? ? values[middle] : (values[middle - 1] + values[middle]) / 2.0
+      end
+
+      def fetch(bluebook, domain, aggregate_name, id)
+        @registry.read_repository(domain, bluebook.aggregate(aggregate_name)).find(id) ||
+          raise(NotFound, RefusalWording.render("NotFound", "read_model_reference_missing",
+                                                aggregate: aggregate_name, offered: Rendering.describe(id)))
+      end
+
+      def records(bluebook, domain, aggregate_name)
+        aggregate = bluebook.aggregate(aggregate_name)
+        aggregate ? @registry.read_repository(domain, aggregate).all : []
+      end
+
+      # A stored reference holds the target's id inside the REFERENCE
+      # ATTRIBUTE's own declared shape, so reading it is reading that shape —
+      # a different thing from the identity unwrap that was removed. An
+      # IDENTITY is declared as a path and followed (Runtime::Identity) ; a
+      # reference has no path of its own, and `Value.scalar` refuses a
+      # composite rather than guessing which field was meant.
+      #
+      # Storing the scalar itself would remove this reading altogether. That
+      # is a change to how references are STORED, not to how identities are
+      # declared, so it is not made here.
+      # An ask names itself where a command would name itself, and says the
+      # same thing about the same shape. `Value.refuse_object_reference` is
+      # not reused because it speaks of a COMMAND and its attribute ; a read
+      # model has a query name and one declared reference.
+      def refuse_object_reference(model, args)
+        offered = args.fetch(model.reference_name, nil)
+        return unless offered.is_a?(Hash) || offered.is_a?(Value)
+
+        raise TypeMismatch,
+              RefusalWording.render("TypeMismatch", "read_model_object_reference",
+                                    query: model.query_name, field: model.reference_name)
+      end
+
+      # A reference is the id, in the argument and in the stored row alike.
+      def reference(value) = value.to_s
+
+      def reference_fields(aggregate, target)
+        aggregate.attributes
+                 .select { |attribute| attribute.reference? && attribute.type.target_name == target.to_s }
+                 .map(&:name)
+      end
+
+      def matching(records) = records.select { |record| yield(record) }.sort_by(&:id)
+      def row(record) = record.to_h
+    end
+  end
+end

data/lib/hecks/runtime/rebuild_sweep.rb

@@ -0,0 +1,74 @@
+module Hecks
+  module Runtime
+    # THE OUT-OF-BAND HALF OF `projects` (S12, ADR 0025 — "Consistency
+    # across aggregate boundaries"). A projected field is never written
+    # by the command that reads it — nothing at dispatch time takes a
+    # live cross-aggregate read the way `CommandRules::References
+    # #dereference` still does — so this is the one place a projected
+    # field's value actually gets copied over: walk every record of the
+    # OWNING aggregate, resolve each of its own `projected_fields`
+    # through the reference it names, and `save` the local copy.
+    #
+    # EXPLICIT AND CALLABLE, NOT AUTOMATIC — no on-boot detection of a
+    # freshly-declared `projects` with no held-era precedent, no
+    # generated `Policy#for_each` reaction keeping it live in real
+    # time as the target changes. Both are real extensions this same
+    # ADR section describes; both are deliberately deferred. This is
+    # the mechanism a caller reaches for by hand — `bin/rebuild
+    # Domain::Aggregate`, a scheduled job, whatever the deployment
+    # needs — proven to work end to end before either automatic
+    # trigger is built on top of it.
+    #
+    # NEEDS NO NEW ADAPTER CAPABILITY. `find`/`all`/`save` are the same
+    # three primitives every real adapter already answers identically
+    # (`Ports::Persistence::AppendOnly#save` — append, then project,
+    # the same for Memory/Postgres/SQLite/D1/Heki) — confirmed by
+    # direct reading before this was built, not assumed.
+    module RebuildSweep
+      module_function
+
+      # One aggregate's own projected fields, refreshed across every
+      # record it holds. Returns how many records actually changed —
+      # `save` only runs when a projected value would differ from what
+      # is already stored, so re-running a sweep with nothing having
+      # moved on the target side touches the append log not at all.
+      def call(registry, domain, aggregate)
+        return 0 if aggregate.projected_fields.empty?
+
+        repository = registry.repository(domain, aggregate)
+        repository.all.count { |record| refresh(registry, domain, aggregate, record, repository) }
+      end
+
+      def refresh(registry, domain, aggregate, record, repository)
+        changed = false
+
+        aggregate.projected_fields.each do |field|
+          value = remote_value(registry, domain, aggregate, record, field)
+          next if value.nil?
+          next if record.key?(field.name) && record[field.name] == value
+
+          record[field.name] = value
+          changed = true
+        end
+
+        repository.save(record) if changed
+        changed
+      end
+
+      # `nil` when the reference itself does not resolve in this
+      # chapter (a cross-domain target left "unfollowed" the same way
+      # References#dereference already leaves one) or when the record
+      # names no target at all — an optional reference nobody set.
+      def remote_value(registry, domain, aggregate, record, field)
+        target = aggregate.attribute(field.reference)&.type&.resolve
+        return nil unless target
+
+        id = record[field.reference]
+        return nil if id.nil?
+
+        remote = registry.repository(domain, target).find(id.to_s)
+        remote&.[](field.remote_field)
+      end
+    end
+  end
+end

data/lib/hecks/runtime/reference_hop.rb

@@ -0,0 +1,99 @@
+require "delegate"
+require_relative "../query_specification/common/where_clause"
+require_relative "../query_specification/common/options"
+require_relative "../query_specification/hop_path"
+require_relative "../ports/query"
+require_relative "registry"
+
+module Hecks
+  module Runtime
+    # `TenantScope`'s sibling — a hop folds to a synthetic `in`
+    # where-clause the exact same way a tenant boundary folds to a
+    # synthetic `eq` one, so every engine that already reads `.wheres`
+    # answers a hop for free, with no per-engine code and no way for
+    # one engine to forget it.
+    #
+    # A hop's own filtering never happens here — RESOLVING one hop
+    # means running one ordinary, adapter-agnostic query against the
+    # hop's TARGET aggregate (through the same Ports::Query boundary
+    # any other query goes through), and folding the ids it answers
+    # back in as a local membership check. A multi-hop chain resolves
+    # from the FAR END inward: `fold` only ever peels off the head hop
+    # (QuerySpecification::HopPath.next_hop, the one-step primitive),
+    # and hands everything still left in the tail to a recursive
+    # `apply` call — so hop 2, hop 3, and so on each get resolved by
+    # their own ordinary query against their own target, one recursion
+    # level at a time, never by this module trying to see the whole
+    # chain at once. It terminates because each recursion is over a
+    # strictly shorter dotted string, and
+    # BluebookBuilder#validate_query_hops! already refused any chain
+    # deep enough to matter before this ever runs.
+    module ReferenceHop
+      module_function
+
+      def apply(declared, args, registry:, domain:, aggregate:)
+        hopped, local = declared.wheres.partition { |clause| QuerySpecification::HopPath.hop_head?(clause.field, aggregate.attributes) }
+        return declared if hopped.empty?
+
+        folded = hopped.map { |clause| fold(clause, args, registry: registry, domain: domain, aggregate: aggregate) }
+        Folded.new(declared, local + folded)
+      end
+
+      def fold(clause, args, registry:, domain:, aggregate:)
+        step = QuerySpecification::HopPath.next_hop(clause.field, aggregate.attributes)
+        hop, rest = step
+
+        # A guarantee BluebookBuilder#validate_query_hops! already gave
+        # this exact clause before the domain ever booted. Held anyway:
+        # an unresolvable target folding silently to "matches
+        # everything" is precisely the failure shape this whole feature
+        # exists to close, and a hop that can no longer resolve (a
+        # target aggregate unloaded after boot, say) is a real fact
+        # worth a real error, not a query that quietly stops filtering.
+        unless hop&.target
+          raise WiringError,
+                "#{clause.field} hops through a reference this domain cannot resolve " \
+                "right now — the chapter seal already checked this once; something " \
+                "changed between then and this dispatch"
+        end
+
+        inner = QuerySpecification::Common::WhereClause.new(field: rest, op: clause.op, value: clause.value)
+        ids   = matching_ids(domain, hop.target, [inner], args, registry: registry)
+
+        QuerySpecification::Common::WhereClause.new(field: hop.attribute.name, op: "in", value: ids)
+      end
+
+      # Every id the inner clause admits on the hop's TARGET — one
+      # whole, ordinary query against the target's own repository,
+      # through the very same Ports::Query boundary the outer ask
+      # uses, so a hop is answered by whatever engine the target
+      # aggregate is actually bound to (which may not be the engine
+      # the OUTER aggregate is bound to at all) rather than by a
+      # second reading of the comparators.
+      def matching_ids(domain, target, wheres, args, registry:)
+        spec       = apply(QuerySpecification::Common::Options.new(wheres: wheres), args,
+                           registry: registry, domain: domain, aggregate: target)
+        repository = registry.repository(domain, target)
+        rows       = Ports::Query.execute(repository, spec, args, context: { domain: domain, aggregate: target }) ||
+                     Ports::Query::InMemory.execute(repository.all, spec, args)
+
+        rows.map { |row| row.id.to_s }.uniq
+      end
+
+      # Never returned to a caller that might call an IR-level method
+      # (`to_h`, …) whose OWN internal `wheres` read would resolve
+      # against the original object, not this override — the exact
+      # caution TenantScope::Scoped's own comment gives, for the exact
+      # same reason: SimpleDelegator only intercepts calls made
+      # directly on the wrapper.
+      class Folded < SimpleDelegator
+        def initialize(declared, wheres)
+          super(declared)
+          @wheres = wheres
+        end
+
+        def wheres = @wheres
+      end
+    end
+  end
+end