hecks 0.2.0 → 0.3.0

data/lib/hecks/runtime/port_operation_interpreter.rb

@@ -0,0 +1,210 @@
+require_relative "interpreting"
+require_relative "command_interpreter/argument_gate"
+require_relative "event"
+require_relative "value"
+require_relative "../naming"
+
+module Hecks
+  module Runtime
+    # The dispatch pipeline for a port operation — called by an adapter living
+    # outside the bluebook entirely, never by the domain itself. Deliberately
+    # a trimmed CommandInterpreter: the same payload gate and coercion
+    # (ArgumentGate, Interpreting#normalize_args), but no `given`, no
+    # `mutations`, no lifecycle, no save. A port operation does not act on an
+    # aggregate instance — it translates an external call into an event in
+    # this domain's own vocabulary, and whatever mutation follows happens
+    # wherever a `policy` reacts to that event, exactly as it would for any
+    # command-emitted one.
+    class PortOperationInterpreter
+      include Interpreting
+      include CommandInterpreter::ArgumentGate
+
+      Context = Struct.new(:domain, :aggregate, :operation, :args, :route, :instance, :result)
+
+      DISPATCH_ORDER = %i[
+        refuse_unknown_arguments refuse_absent_arguments normalize_args resolve_references resolve_route emit
+      ].freeze
+
+      def initialize(registry, rules:)
+        @registry = registry
+        @rules    = rules
+      end
+
+      def call(domain, aggregate, operation, args, route:)
+        ctx = Context.new(domain, aggregate, operation, args)
+        ctx.route = route
+        run_dispatch_order(DISPATCH_ORDER, ctx)
+        ctx.result
+      end
+
+      private
+
+      def step_refuse_unknown_arguments(ctx)
+        step(:refuse_unknown_arguments) { refuse_unknown_arguments(ctx.domain, ctx.aggregate, ctx.operation, ctx.args) }
+      end
+
+      def step_refuse_absent_arguments(ctx)
+        step(:refuse_absent_arguments) { refuse_absent_arguments(ctx.operation, ctx.args, aggregate: ctx.aggregate) }
+      end
+
+      def step_normalize_args(ctx)
+        ctx.args = step(:normalize_args) { normalize_args(ctx.aggregate, ctx.operation, ctx.args) }
+      end
+
+      def step_resolve_references(ctx)
+        step(:resolve_references) { @rules.resolve_references(ctx.domain, ctx.operation, ctx.args) }
+      end
+
+      def step_resolve_route(ctx)
+        ctx.instance = step(:resolve_route) do
+          @registry.repository(ctx.domain, ctx.aggregate).find(ctx.route.aggregate) ||
+            raise(NotFound, "#{ctx.aggregate.hecks_name} #{ctx.route.aggregate.inspect} does not exist")
+        end
+      end
+
+      def step_emit(ctx)
+        ctx.result = step(:emit) { ctx.operation.outbound? ? ask(ctx) : emit(ctx) }
+      end
+
+      # THE DOMAIN CALLING OUT, AND BOTH ENDINGS RECORDED.
+      #
+      # The adapter is found the same way every other port's is — by name,
+      # across whatever adapters this boot loaded — so an `asks` is bound by
+      # an adapter declaring `port "IssueTracker"` and nothing new to learn.
+      #
+      # EVERY FAILURE IS AN ANSWER. A raise from the far side of a boundary is
+      # not an exception in this domain's terms, it is the outside saying no,
+      # and the chapter already named the word for that. So the rescue is
+      # deliberately wide: a timeout, a bad credential, an adapter that does
+      # not exist, a nil where a number was wanted — all of them become the
+      # `refuses` event, carrying what was said. A policy reacts to it, a
+      # retry counter reads it, and nothing has to catch anything.
+      #
+      # AN ASK IS HANDED THE RECORD IT IS ABOUT.
+      #
+      # An INBOUND operation deliberately cannot read state — it is the
+      # anti-corruption boundary, translating a fact from outside, and letting
+      # it read the aggregate would make it a second place rules live. That
+      # rule was written for that direction and does not survive the crossing.
+      #
+      # An outbound one almost always needs the record. `asks "File"` names
+      # `reference_to Ticket` and the adapter needs the ticket's repository,
+      # title and body — which are ON the ticket, and which the policy that
+      # triggered this cannot supply because a command's event payload is its
+      # ARGUMENTS, not its state. Without this, every ask would have to have
+      # its data re-passed through the command that fired it, so the same text
+      # would live in two places and could differ.
+      #
+      # ARGUMENTS WIN over state, because an argument is what THIS call said
+      # and state is what the record happens to hold.
+      def ask(ctx)
+        payload = held_state(ctx).merge(materialise(ctx.args))
+        answer  = adapter_for(ctx).public_send(Naming.snake(ctx.operation.hecks_name), **payload)
+        announce(ctx, ctx.operation.answers, ctx.args.merge(spread(answer)))
+      rescue StandardError => e
+        announce(ctx, ctx.operation.refuses, ctx.args.merge(refusal: { value: "#{e.class}: #{e.message}" }))
+      end
+
+      # THE ANSWER IS SPREAD, NOT NESTED — and that is what makes the loop
+      # close. A policy re-enters its target with the event payload VERBATIM;
+      # it cannot reach inside a key. So an answer tucked under `answered:`
+      # can be read by a human and by nothing else, and the command that
+      # should record the issue number never gets one.
+      #
+      # Spread, the adapter's own keys ARE the arguments of whatever command
+      # reacts to the answering event. Which is a real contract on the adapter
+      # — it must return what that command takes, in the shape the runtime
+      # coerces (`{ number: { value: 43 } }`, not `43`) — and naming it here
+      # is cheaper than a mapping layer nobody could see into.
+      #
+      # A non-Hash answer keeps the old shape: a port that returns a URL
+      # string has nothing to spread, and `answered:` is the honest word for
+      # a single unnamed value.
+      def spread(answer)
+        return { answered: answer } unless answer.is_a?(Hash)
+
+        answer.to_h { |key, value| [key.to_sym, deep_symbolize(value)] }
+      end
+
+      def deep_symbolize(value)
+        case value
+        when Hash  then value.to_h { |k, v| [k.to_sym, deep_symbolize(v)] }
+        when Array then value.map { |element| deep_symbolize(element) }
+        else value
+        end
+      end
+
+      # THE RECORD, IF THERE IS ONE. A record that does not exist yet is not
+      # an error here — the ask still goes, carrying only its arguments, and
+      # whatever the adapter makes of that is its own business. Refusing
+      # would put a second existence check behind the one `resolve_references`
+      # already performed.
+      def held_state(ctx)
+        ctx.instance ? Value.materialize(ctx.instance.state) : {}
+      rescue StandardError
+        {}
+      end
+
+      # THE PORT THIS OPERATION BELONGS TO, found by asking the aggregate
+      # rather than threading it through the call — the dispatcher already
+      # resolved it once to get here, and a second parameter carried purely so
+      # this method can read it would be a parameter every OTHER step ignores.
+      def port_name_for(ctx)
+        owning = ctx.aggregate.ports.find { |port| port.operations.any? { |op| op.equal?(ctx.operation) } }
+        owning&.name or raise WiringError,
+                              "#{ctx.operation.hecks_name} belongs to no port on #{ctx.aggregate.hecks_name}"
+      end
+
+      def adapter_for(ctx)
+        name = port_name_for(ctx)
+        implementations = @registry.adapters.values.select { |adapter| adapter.port == name }
+
+        case implementations.size
+        when 1 then Adapters.const_get(implementations.first.name).new
+        when 0 then raise WiringError, "no adapter implements the #{name} port — nothing can answer #{ctx.operation.hecks_name}"
+        else raise WiringError,
+                   "#{implementations.size} adapters implement the #{name} port " \
+                   "(#{implementations.map(&:name).sort.join(', ')}) — the runtime will not choose for you"
+        end
+      end
+
+      # A Value never crosses the boundary — an adapter is somebody else's
+      # code and should be handed plain data, the same reasoning `JsonDoor`
+      # gives for materialising before it hands anything to an HTTP caller.
+      def materialise(args) = Value.materialize(args)
+
+      def announce(ctx, event_name, payload)
+        event = Event.new(
+          name:        event_name,
+          aggregate:   "#{ctx.domain}::#{ctx.aggregate.hecks_name}",
+          id:          ctx.route.aggregate,
+          payload:     payload,
+          occurred_at: Time.now.utc.iso8601
+        )
+        @registry.event_log << event
+        [event]
+      end
+
+      # THE ONE PLACE THIS DIFFERS FROM CommandRules::Emission — there is no
+      # mutated instance to read an id off, because nothing was hydrated or
+      # saved. The record this event is ABOUT is named by whichever attribute
+      # is a reference to the owning aggregate (PortOperationBuilder#build
+      # already refused to build an operation with none), so its coerced
+      # value — already a plain id, never an object, per
+      # Value::Coercion#refuse_object_reference — is what stamps the event.
+      def emit(ctx)
+        ctx.operation.emits.map do |event_name|
+          event = Event.new(
+            name:        event_name,
+            aggregate:   "#{ctx.domain}::#{ctx.aggregate.hecks_name}",
+            id:          ctx.route.aggregate,
+            payload:     ctx.args,
+            occurred_at: Time.now.utc.iso8601
+          )
+          @registry.event_log << event.emit!
+          event
+        end
+      end
+    end
+  end
+end

data/lib/hecks/runtime/query_interpreter.rb

@@ -0,0 +1,254 @@
+require_relative "../naming"
+require_relative "../ports/query"
+require_relative "../ports/query/ordering"
+require_relative "../query_specification/field_path"
+require_relative "../query_specification/common/comparison"
+require_relative "errors"
+require_relative "reference_hop"
+require_relative "refusal_wording"
+require_relative "tenant_scope"
+require_relative "value"
+
+module Hecks
+  module Runtime
+    class QueryInterpreter
+      attr_reader :registry
+
+      def initialize(registry)
+        @registry = registry
+      end
+
+      def call(domain, aggregate, query_name, args)
+        return entity_rows(domain, aggregate, query_name, args) if query_name.include?(".")
+
+        declared = declared_query(aggregate, query_name)
+        args = normalize_args(aggregate, declared, args)
+        declared = TenantScope.apply(declared, args)
+        # AFTER TenantScope, so its synthetic clause is already present
+        # in `.wheres` and rides through as an ordinary LOCAL clause on
+        # the OUTER query. It does not reach the hop's own inner
+        # sub-query against the TARGET aggregate — a hop's target may
+        # not even declare the same tenant boundary, and propagating one
+        # aggregate's tenant scope onto an unrelated aggregate's own
+        # query is a real design question of its own, not answered here.
+        declared = ReferenceHop.apply(declared, args, registry: @registry, domain: domain, aggregate: aggregate)
+
+        repository = @registry.repository(domain, aggregate)
+        # `registry:` is threaded through so a `none_in_state` where-clause
+        # can look its target aggregate up — see
+        # QuerySpecification::Common::Comparison#none_in_state? for the
+        # comparator itself, and for why an ordinary aggregate-level
+        # Memory query needs the registry passed explicitly rather than
+        # closing over an instance variable.
+        if (native = Ports::Query.execute(repository, declared, args,
+                                          context: { domain: domain, aggregate: aggregate, registry: @registry }))
+          records = native
+          # `record.state.merge(id: record.id)` — id LAST, not first. See
+          # Instance#to_h's own comment: an aggregate free to declare its
+          # own attribute literally named `id` has that attribute's own
+          # wrapped value sitting in `record.state[:id]` already; merging
+          # it OVER a `{id:}.merge(state)` used to let it silently
+          # clobber the correct bare identity this row is supposed to
+          # carry.
+          # A QUERY ROW IS AN ANSWER, NOT A HANDLE. Mutating one edits
+          # nobody's state and silently disagrees with the store.
+          return Freezer.deep(records.map { |record| record.state.merge(id: record.id) })
+        end
+
+        Freezer.deep(interpret(repository.all, declared, args, domain: domain))
+      end
+
+      # The REFERENCE answer — this interpreter's own evaluation, never an
+      # adapter's native hook. The fuzzer's query oracle replays every
+      # generated ask through both paths and treats a difference as a
+      # finding: the differential gate the retired cross-runtime harness
+      # should always have been, aimed where the divergence actually
+      # lives — between the engines inside this one runtime.
+      #
+      # A hop clause is answered here by its OWN, deliberately naive
+      # walk (reference_where_holds?) — never Runtime::ReferenceHop's
+      # partition/fold/IN-clause. Sharing that algorithm would have made
+      # this oracle blind to exactly the code the hop feature adds: every
+      # PHASE of a shared fold would still get diffed against the native
+      # adapters, but the fold itself — the empty candidate set, a
+      # duplicate id, a dangling reference, a chain's inside-out
+      # resolution order — would only ever be compared against itself.
+      def reference_call(domain, aggregate, query_name, args)
+        return entity_rows(domain, aggregate, query_name, args) if query_name.include?(".")
+
+        declared = declared_query(aggregate, query_name)
+        args = normalize_args(aggregate, declared, args)
+        declared = TenantScope.apply(declared, args)
+        reference_interpret(@registry.repository(domain, aggregate).all, declared, args,
+                            domain: domain, shape: aggregate)
+      end
+
+      private
+
+      def declared_query(aggregate, query_name)
+        aggregate.query(query_name) ||
+          raise(UnknownVerb, RefusalWording.render("UnknownVerb", "no_query",
+                                                   aggregate: aggregate.hecks_name, query: query_name.inspect))
+      end
+
+      def interpret(records, declared, args, domain: nil)
+        matched = records.select { |r| declared.wheres.all? { |w| where_holds?(w, r, args, domain: domain) } }
+        ordered = ordered(matched, declared.order_by, declared.null_semantics)
+        # OFFSET FIRST, THEN LIMIT — the order SQL means by `LIMIT n
+        # OFFSET m`, and the order Ports::Query::InMemory#execute already
+        # applies (see that file's own comment). This interpreter used to
+        # never read declared.offset at all — offset silently vanished for
+        # any query answered here, not just come out reversed.
+        skipped = declared.offset ? ordered.drop(resolve_query_value(declared.offset.value, args).to_i) : ordered
+        capped  = declared.limit ? skipped.first(resolve_query_value(declared.limit.value, args).to_i) : skipped
+
+        # id LAST — see the native-path comment above; same clobbering
+        # risk for the in-memory reference interpreter's own rows.
+        capped.map { |r| r.state.merge(id: r.id) }
+      end
+
+      # `interpret`'s own twin, for reference_call alone — same
+      # select/order/limit shape, but a clause that hops through a
+      # reference is answered by reference_where_holds? instead of the
+      # plain FieldPath.dig(record, field) `where_holds?` uses (which
+      # has no concept of a reference at all — it would just read the
+      # raw id straight off the record and compare THAT).
+      def reference_interpret(records, declared, args, domain:, shape:)
+        matched = records.select { |r|
+          declared.wheres.all? { |w|
+            reference_where_holds?(w, r, args, domain: domain, shape: shape)
+          }
+        }
+        ordered = ordered(matched, declared.order_by, declared.null_semantics)
+        # OFFSET FIRST, THEN LIMIT — same fix, same reasoning, as
+        # #interpret's own rows above.
+        skipped = declared.offset ? ordered.drop(resolve_query_value(declared.offset.value, args).to_i) : ordered
+        capped  = declared.limit ? skipped.first(resolve_query_value(declared.limit.value, args).to_i) : skipped
+
+        # id LAST — same reasoning, same fix, as interpret's own rows.
+        capped.map { |r| r.state.merge(id: r.id) }
+      end
+
+      # THE NAIVE READING OF A HOP: not a fold, not an id set — for
+      # each candidate row, walk the reference by hand and dig the
+      # field out of whatever it actually points at. A nil reference,
+      # or one that resolves to nothing (a dangling id), makes the
+      # WHOLE clause false outright, whatever the comparator — "points
+      # at a client that is not active" is false for a proposal with no
+      # client at all, the same way it is false for one whose client
+      # really is active; falling through to holds?(clause, nil, args)
+      # instead would answer `ne` wrong (nil != "active" is true).
+      def reference_where_holds?(clause, record, args, domain:, shape:)
+        step = QuerySpecification::HopPath.next_hop(clause.field, shape.attributes)
+        return where_holds?(clause, record, args) unless step
+
+        hop, rest = step
+        inner = QuerySpecification::Common::WhereClause.new(field: rest, op: clause.op, value: clause.value)
+        held = record[hop.attribute.name]
+        reference_ids = hop.attribute.list? ? Array(held) : [held]
+
+        reference_ids.compact.any? do |reference_id|
+          target_record = @registry.repository(domain, hop.target).find(reference_id)
+          next false unless target_record
+
+          reference_where_holds?(inner, target_record, args, domain: domain, shape: hop.target)
+        end
+      end
+
+      def entity_rows(domain, aggregate, dotted, args)
+        entity_name, query_name = Naming.split_dotted(dotted)
+        entity = aggregate.entities.find { |piece| piece.hecks_name == entity_name } ||
+                 raise(UnknownVerb, RefusalWording.render("UnknownVerb", "entity_unknown",
+                                                          aggregate: aggregate.hecks_name, entity: entity_name.inspect))
+        declared = entity.query(query_name) ||
+                   raise(UnknownVerb, RefusalWording.render("UnknownVerb", "entity_query_missing",
+                                                            entity: entity_name, query: query_name.inspect))
+        declared = TenantScope.apply(declared, args)
+        list_attr = aggregate.attributes.find { |a| a.list? && a.type.to_s == entity_name } ||
+                    raise(UnknownVerb, RefusalWording.render("UnknownVerb", "entity_holds_no_list",
+                                                             aggregate: aggregate.hecks_name, entity: entity_name))
+
+        parent_key = Naming.reference_key(aggregate.hecks_name)
+        rows = @registry.repository(domain, aggregate).all.flat_map do |record|
+          Array(record[list_attr.name])
+            .select { |el| declared.wheres.all? { |w| element_where_holds?(w, el, args) } }
+            .map    { |el| { parent_key => record.id }.merge(el) }
+        end
+
+        ordered = ordered_elements(rows, declared.order_by, declared.null_semantics,
+                                   parent_key, entity.identity_heads)
+        declared.limit ? ordered.first(resolve_query_value(declared.limit.value, args).to_i) : ordered
+      end
+
+      def element_where_holds?(clause, element, args)
+        holds?(clause, element[clause.field.to_sym], args)
+      end
+
+      # A row's own key, however the store spells it. A sub-list row is a plain hash
+      # merged from stored state, so its keys arrive as strings from one adapter and
+      # symbols from another — and reading only one spelling gave every row the SAME
+      # identity, which is a tie, which is the exact nondeterminism this tier exists
+      # to remove. It rides `comparable` for the same reason a where-clause does : an
+      # identity is a value object, and `to_s` on one is an OBJECT ADDRESS — a sort key
+      # that differs run to run, which is worse than the store order it replaced.
+      def cell(row, key) = row[key.to_sym] || row[key.to_s]
+
+      # A sub-list row is identified by its PARENT and then its own key : two
+      # entities under different parents can share a sequence, so the parent has
+      # to lead or the tie is not broken at all.
+      #
+      # EVERY KEY THE PIECE IS KNOWN BY, in declaration order, for the same
+      # reason the parent leads: a part that ties is a part that breaks no tie.
+      # This took `identified_by`, which is the SINGLE head and is nil the
+      # moment an identity has two parts — and `cell(row, nil)` calls
+      # `nil.to_sym`, so a query against a composite piece did not sort wrongly,
+      # it raised. A piece known by one key sorts exactly as it did.
+      def ordered_elements(rows, order_by, null_semantics, parent_key, entity_keys)
+        field = order_by&.field
+        Ports::Query::Ordering.apply(
+          rows, order_by, null_semantics,
+          identity: lambda { |row|
+            [row[parent_key].to_s, *Array(entity_keys).map { |key| comparable(cell(row, key)) }]
+          }
+        ) { |row| comparable(QuerySpecification::FieldPath.dig(row, field)) }
+      end
+
+      def where_holds?(clause, record, args, domain: nil)
+        holds?(clause, QuerySpecification::FieldPath.dig(record, clause.field), args, record: record, domain: domain)
+      end
+
+      # The comparator table itself lives in
+      # QuerySpecification::Common::Comparison. This method and
+      # Ports::Query::InMemory#holds? used to carry a copy each and the
+      # two drifted — `none_in_state` reached only one of them, and
+      # `comparable` disagreed about value objects with two numeric
+      # members. What stays here is how a value is REACHED for this
+      # path: the registry is instance state rather than an argument.
+      def holds?(clause, held, args, record: nil, domain: nil)
+        QuerySpecification::Common::Comparison.holds?(
+          clause.op, comparable(held), comparable(resolve_query_value(clause.value, args)), registry: @registry
+        )
+      end
+
+      def resolve_query_value(value, args)
+        value.is_a?(Symbol) ? args[value] : value
+      end
+
+      def normalize_args(aggregate, declared, args)
+        declared.attributes.each_with_object(args.dup) do |attribute, normalized|
+          next unless normalized.key?(attribute.name)
+
+          normalized[attribute.name] = Value.for_attribute(aggregate, attribute, normalized[attribute.name])
+        end
+      end
+
+      def comparable(value) = QuerySpecification::Common::Comparison.comparable(value)
+
+      def ordered(records, order_by, null_semantics = nil)
+        field = order_by&.field
+        Ports::Query::Ordering.apply(records, order_by, null_semantics,
+                                     identity: ->(record) { record.id.to_s }) { |record| comparable(record[field]) }
+      end
+    end
+  end
+end