hecks 0.2.0 → 0.3.0

data/lib/hecks/bluebook/behaviour/hexagon.rb

@@ -0,0 +1,50 @@
+module Hecks
+  module Bluebook
+    module Behaviour
+      # WHAT A HECKSAGON DOES — the lookups over its declared binds.
+      module Hecksagon
+        # Aggregate-specific bind wins when one was declared; otherwise
+        # falls back to a domain-level default (`b.aggregate.nil?` — see
+        # `HecksagonBuilder#method_missing`). Checked directly rather than
+        # via `aggregate_name`/`Naming.demodulise`, which would need its own
+        # nil-handling for the default row.
+        def bind_for(aggregate_name, verb)
+          @binds.find { |b| b.aggregate_name == aggregate_name.to_s && b.verb.to_s == verb.to_s } ||
+            @binds.find { |b| b.aggregate.nil? && b.verb.to_s == verb.to_s }
+        end
+
+        def binds_for(aggregate_name, verb)
+          specific = @binds.select { |b| b.aggregate_name == aggregate_name.to_s && b.verb.to_s == verb.to_s }
+          return specific if specific.any?
+
+          @binds.select { |b| b.aggregate.nil? && b.verb.to_s == verb.to_s }
+        end
+      end
+
+      # WHAT A WORLD DOES — settings lookup, with the adapter-specific
+      # entry falling back to the verb's own.
+      module World
+        def for_verb(verb) = @settings.fetch(verb.to_s, {})
+
+        # The generic `verb` entry (`persisted_by("Heki") do dir :default
+        # end`) only answers for the adapter it actually names — falling
+        # back to it unconditionally applies one adapter's settings to an
+        # unrelated one. Real, corpus-caught bug: a hecksagon binding two
+        # aggregates to two different adapters under the SAME verb (one to
+        # Heki, one to Memory) sent Memory's lookup down Heki's generic
+        # entry, then failed `check_settings` with "Memory does not
+        # declare :dir" — the generic entry's own `settings[:adapter]`
+        # names Heki, not Memory, so the fallback was never actually for
+        # this bind. `{}` is exactly right when nothing was configured for
+        # THIS adapter — Memory, which takes no values at all.
+        def for_binding(verb, adapter)
+          qualified = @settings["#{verb}:#{adapter.to_s.downcase}"]
+          return qualified if qualified
+
+          generic = for_verb(verb)
+          generic[:adapter].to_s.downcase == adapter.to_s.downcase ? generic : {}
+        end
+      end
+    end
+  end
+end

data/lib/hecks/bluebook/behaviour/lifecycle.rb

@@ -0,0 +1,51 @@
+module Hecks
+  module Bluebook
+    module Behaviour
+      # WHAT A LIFECYCLE DOES. Its declared half is a field, a starting
+      # state and a transition list. Everything here READS that — which
+      # states exist, which transition a command takes, and how one
+      # declared transition expands into the several rows the emission
+      # carries when `from` names more than one source state.
+      module Lifecycle
+        def states
+          ([default] + transitions.map { |_command, t| t.target }).uniq
+        end
+
+        def transitions_for(command)
+          transitions.select { |name, _| name == command.to_s }.map { |_, t| t }
+        end
+
+        def target_for(command, current_state = nil)
+          match_transition(command, current_state)&.target
+        end
+
+        private
+
+        # ONE DECLARED TRANSITION IS SEVERAL ROWS when `from` names more
+        # than one source state — the emission carries them flat, so the
+        # fan-out happens here rather than in whatever reads it.
+        def expand(command, transition)
+          sources = transition.from.nil? ? [nil] : Array(transition.from)
+
+          sources.map do |source|
+            { command: command, to_state: transition.target, from_state: source }
+          end
+        end
+
+        def match_transition(command, current_state)
+          matches = transitions_for(command)
+          return nil if matches.empty?
+          return matches.first unless current_state
+
+          matches.find { |t| applies_from?(t, current_state) } || matches.first
+        end
+
+        def applies_from?(transition, current)
+          return true unless transition.from
+
+          Array(transition.from).map(&:to_s).include?(current.to_s)
+        end
+      end
+    end
+  end
+end

data/lib/hecks/bluebook/behaviour/policy.rb

@@ -0,0 +1,52 @@
+module Hecks
+  module Bluebook
+    module Behaviour
+      # WHAT A POLICY DOES. Its declared half is four plain fields; these
+      # are the readings taken off them.
+      module Policy
+        # The BLUEBOOK's name for this construct, asked the same way of a class
+        # that has crossed over and of an IR object that has not. Collapses into
+        # Construct when this one crosses.
+        def hecks_name = @name
+
+        def event_qualifier = Naming.qualifier(@on_event)
+
+        def event_name = Naming.unqualified(@on_event)
+
+        # WHETHER THIS POLICY FANS OUT — `for_each` names a query, and a
+        # non-empty one turns a single reaction into one dispatch per row
+        # the query answers. Read by the interpreter that runs the fan-out
+        # and by the property that checks it dispatched once per row.
+        def fans_out? = !@for_each.to_s.empty?
+
+        # WHETHER THIS POLICY IS GUARDED — a non-empty `where` decides
+        # whether the policy fires at all, read against the triggering
+        # event's own payload.
+        def guarded? = !@where.to_s.empty?
+
+        # THE FAN-OUT QUERY'S ROUTE, split the way the runtime runs it:
+        # `[query_domain, aggregate_name, query_name]`. The query runs
+        # against the triggering event's OWN domain unless `for_each`
+        # names one ("Domain::Aggregate.query"). Deliberately independent
+        # of `across`/`target_domain`, which name where `trigger` fires,
+        # not where the fan-out's own query runs.
+        def for_each_route(default_domain)
+          path, query_name = @for_each.to_s.split(".", 2)
+          domain, aggregate = path.to_s.include?("::") ? path.split("::", 2) : [default_domain.to_s, path]
+          [domain, aggregate, query_name]
+        end
+
+        # THE ARGUMENT NAME A FAN-OUT DISPATCH mints each matched row's id
+        # under used to be minted HERE, unconditionally, as `<aggregate>
+        # _id` — a real bug: a target command declared ON the very
+        # aggregate it self-references (`Account.Freeze`) is addressed by
+        # its OWN identity field's name, not a synthetic foreign key, and
+        # every such dispatch refused. That question is not this policy's
+        # to answer at all — it depends on the TARGET COMMAND'S OWN
+        # declared shape, not on the aggregate name alone — so it now
+        # lives on `Behaviour::Command#addressing_key_for`, asked of the
+        # resolved target command by `PolicyInterpreter#addressing_key_for`.
+      end
+    end
+  end
+end

data/lib/hecks/bluebook/behaviour/process_manager.rb

@@ -0,0 +1,38 @@
+module Hecks
+  module Bluebook
+    module Behaviour
+      # WHAT A PROCESS MANAGER DOES. Its declared half is the trigger,
+      # the states and the handlers; the compensation half — `saga` — is
+      # DERIVED from the handler that answers a refusal, not declared.
+      module ProcessManager
+        def hecks_name = @name
+
+        def handler_for(event) = @handlers.find { |h| h.event_type == event.to_s }
+
+        # WHETHER A STATE IS ONE THIS PROCEDURE DECLARES — asked of a value
+        # a real run left a saga instance holding (its live or rehydrated
+        # state), the way `Lifecycle#states` is asked of an aggregate's
+        # resting field. A rehydrated instance in a state no handler could
+        # have reached is corruption the durable round-trip introduced.
+        def declares_state?(state) = @states.map(&:to_s).include?(state.to_s)
+
+        def correlation_head = @correlates_by.to_s.split(".").first.to_sym
+
+        # The compensation half of a procedure, read off the handler that
+        # answers REFUSED.
+        #
+        # nil for a procedure with no answer to a refusal, which is a legitimate
+        # thing to be — a hiring pipeline cannot un-interview anybody.
+        def saga
+          leg = handler_for(Bluebook::ProcessManager::REFUSED)
+          return nil unless leg
+
+          Bluebook::Saga.new(trigger: Bluebook::ProcessManager::REFUSED, from_state: leg.from_state,
+                             to_state: leg.to_state, reversals: leg.dispatches)
+        end
+
+        def saga? = !saga.nil?
+      end
+    end
+  end
+end

data/lib/hecks/bluebook/behaviour/query.rb

@@ -0,0 +1,10 @@
+module Hecks
+  module Bluebook
+    module Behaviour
+      # WHAT A QUERY DOES beyond holding its declared shape.
+      module Query
+        def attribute(named) = @attributes.find { |a| a.name == named.to_sym }
+      end
+    end
+  end
+end

data/lib/hecks/bluebook/behaviour/read_model.rb

@@ -0,0 +1,29 @@
+module Hecks
+  module Bluebook
+    module Behaviour
+      # WHAT A READ MODEL DOES. Its declared half is the gathered heads
+      # and the query shape; these are readings taken off them.
+      module ReadModel
+        def group_by_fields = @group_by.map { |row| row[:field].to_sym }
+
+        # `!!` rather than a bare `@count` — the DSL/reconstruction
+        # boundary (ReadModel#initialize) already normalises to
+        # `true`/`nil`, so this is belt and braces against a future
+        # caller constructing a ReadModel by hand with `count: false`.
+        def count? = !!@count
+
+        def query_name = Naming.snake(@name)
+
+        # WHICH GATHERED HEAD THE FILTERING APPLIES TO, so the read-model
+        # interpreter can ask this directly rather than re-deriving or
+        # re-checking it.
+        def filtered_head_name
+          return nil unless wheres.any? || order_by || limit || offset || authorization&.tenant ||
+                            @group_by.any? || count? || @median_field
+
+          @aggregate_heads.find { |head| head[:many] }&.fetch(:as)
+        end
+      end
+    end
+  end
+end

data/lib/hecks/bluebook/behaviour/traits.rb

@@ -0,0 +1,81 @@
+module Hecks
+  module Bluebook
+    module Behaviour
+      # THE BEHAVIOUR MORE THAN ONE CONSTRUCT SHARES.
+      #
+      # None of this is new duplication. `attribute(named)` was written
+      # out four separate times — on Aggregate, Entity, Command and
+      # PortOperation — and the identity derivation twice, byte for byte,
+      # for as long as those constructs have existed. Splitting holding
+      # from doing is what made them visible: the same method in four
+      # files reads as four methods, and the same method in four modules
+      # named `Behaviour::*` reads as one repeated.
+      #
+      # Written to work whether the construct is INCLUDED into (an
+      # ordinary object like Aggregate) or EXTENDED into (a class-shaped
+      # one like Command), because every one of them reads instance
+      # variables and nothing else.
+
+      # A CONSTRUCT WHOSE IDENTITY IS A JOIN OF DECLARED PATHS.
+      #
+      # THE PATHS, IN DECLARATION ORDER, because the identity IS their join.
+      # "number.value" says which field carries the identity ; several paths
+      # say the identity is made of several facts, which is what anything
+      # named beneath another thing needs. `identity_heads` are the attributes
+      # those paths start at — what every reader that looks up or coerces an
+      # attribute actually wants — and `identified_by` is the single head,
+      # offered ONLY when there is one path to have a head of. A composite has
+      # no single head, and answering with the first would be a guess ; the
+      # readers that need all of them ask for `identity_heads`.
+      module Identified
+        def derive_identity
+          @identity_paths = Array(@identified_by).map { |path| path.to_s }.reject(&:empty?)
+          @identity_heads = @identity_paths.map { |path| path.split(".").first.to_sym }.uniq
+          @identified_by  = @identity_heads.size == 1 ? @identity_heads.first : nil
+        end
+      end
+
+      # A CONSTRUCT THAT ANSWERS FOR ITS OWN DECLARATIONS BY NAME.
+      #
+      # Indexed once, since the declarations are final by the time the
+      # construct exists — every dispatch asks these finders by name, and a
+      # linear scan repeated on every call was doing work the declared shape
+      # had already settled at boot.
+      #
+      # `index_by_name` takes the collections to index rather than naming
+      # them, because WHICH collections a construct has is exactly the part
+      # that differs: an aggregate has five, an entity three, a command one.
+      module Indexed
+        # Keyed by SYMBOL — an attribute is asked for by its declared
+        # symbol name everywhere in the runtime.
+        def index_attributes(attributes)
+          @attributes_by_name = attributes.to_h { |held| [held.name, held] }
+        end
+
+        # Keyed by STRING and by `hecks_name` — a command, query or value
+        # object is a construct whose Ruby `name` is something else
+        # entirely (a constant path, or nothing at all for an anonymous
+        # class), so the DECLARED name is the only one worth indexing.
+        def index_by_hecks_name(collection)
+          collection.to_h { |held| [held.hecks_name, held] }
+        end
+
+        def attribute(named) = @attributes_by_name[named.to_sym]
+        def command(named)   = @commands_by_name[named.to_s]
+        def query(named)     = @queries_by_name[named.to_s]
+      end
+
+      # A CONSTRUCT THAT OWNS WHAT IT DECLARES.
+      #
+      # Owner links are only ever read lazily — hecks_fqn at ask time,
+      # Reference#resolve at dispatch time — so the moment the construct
+      # is complete is the right stamping point: its declarations are
+      # final, and nothing outside needs to remember to stamp them.
+      module Owns
+        def stamp(*children)
+          children.flatten.each { |child| child.hecks_owner = self }
+        end
+      end
+    end
+  end
+end

data/lib/hecks/bluebook/behaviour/value_object.rb

@@ -0,0 +1,33 @@
+module Hecks
+  module Bluebook
+    module Behaviour
+      # WHAT A VALUE OBJECT DOES. EXTENDED, not included — a value object
+      # is a CLASS (`Class.new(self)`, one per declared shape), so its
+      # behaviour is singleton behaviour, and the holding half's `absorb`
+      # is what a generated constructor would be.
+      module ValueObject
+        # A one_of DECLARED but left empty used to be indistinguishable from no
+        # one_of at all — both are `members: []` — so the rule about it could
+        # only live in the builder. Recording the declaration lets the language
+        # judge it, the same way an empty attribute NAME survives into the IR
+        # and is judged there.
+        def closed_set? = @closed_set
+
+        def attribute(named) = attributes.find { |held| held.name == named.to_sym }
+
+        # A single-attribute value object (EmailAddress{address},
+        # CustomerNumber{value}) is a NAME for a scalar, not a genuine
+        # group — [[feedback_name_the_scalar_field]]. Four call sites
+        # already inline this exact check (`attributes.size == 1` /
+        # `attributes.first`) — `forms/field_shape.rb` (twice),
+        # `adapters/driven/sql_query_builder.rb`,
+        # `fuzzing/invalid_value_generator.rb` — kept as-is for now
+        # (not migrated to this reader), but any NEW caller should
+        # reach for this rather than add a fifth inline copy.
+        def sole_attribute
+          attributes.first if attributes.size == 1
+        end
+      end
+    end
+  end
+end

data/lib/hecks/bluebook/chapter.rb

@@ -0,0 +1,68 @@
+require_relative "behaviour/chapter"
+require_relative "../ir"
+
+module Hecks
+  module Bluebook
+    # THE CHAPTER, and no longer the namespace it lives in.
+    #
+    # `Hecks::Bluebook` was briefly a CLASS, because dropping the
+    # old `IR::` segment would otherwise have produced
+    # `Bluebook::Bluebook` — a class shadowing its own enclosing module.
+    # Naming the construct what the code already called it everywhere
+    # (a chapter; this file was already chapter.rb) removes the clash
+    # at the source, so the namespace goes back to being a module.
+    #
+    # Measured before changing: `Bluebook` was used AS a class in five
+    # places and as a namespace in seventy-seven files.
+    class Chapter
+      include Construct
+      include Behaviour::Chapter
+      include Hecks::IR
+
+      # THE SCHEMA'S OWN VERSION — not a domain's `version:` (Banking's
+      # "v1", a business fact the AUTHOR chose), but the shape `to_h`
+      # itself emits. A consumer reading exported IR with no Ruby DSL to
+      # cross-check against (a build-time generator, a stored snapshot)
+      # needs to know WHICH shape it's holding before it can safely
+      # interpret any of the rest of it. Bump this when `to_h`'s own
+      # shape changes in a way a consumer would need to know about —
+      # not when a domain's own declarations change.
+      IR_VERSION = 1
+
+      emits_ir(
+        ir_version:       -> { IR_VERSION },
+        name:             :name,
+        version:          :version,
+        vision:           :vision,
+        classification:   :classification,
+        aggregates:       many(:aggregates),
+        read_models:      many(:read_models),
+        policies:         many(:policies),
+        process_managers: many(:process_managers),
+        attaches_to:      :attaches_to,
+        canonical_form:   -> { Expression::CanonicalForm.table }
+      )
+
+      attr_reader :name, :version, :vision, :aggregates, :policies, :process_managers,
+                  :classification, :read_models, :ports, :formerly_known_as, :attaches_to
+
+      def initialize(name:, version: nil, vision: nil, aggregates: [], policies: [],
+                     process_managers: [], classification: nil, read_models: [], formerly_known_as: nil,
+                     attaches_to: [])
+        @policies         = policies
+        @process_managers = process_managers
+        @name       = name.to_s
+        @hecks_name = @name
+        @hecks_root = true
+        @version    = version&.to_s
+        @vision     = vision
+        @aggregates = aggregates
+        @read_models = read_models
+        @classification = classification&.to_s
+        @formerly_known_as = formerly_known_as&.to_s
+        @attaches_to = Array(attaches_to).map(&:to_s)
+        settle
+      end
+    end
+  end
+end

data/lib/hecks/bluebook/command.rb

@@ -0,0 +1,124 @@
+require_relative "behaviour/command"
+require_relative "../vocabulary"
+
+module Hecks
+  module Bluebook
+    Given = Struct.new(:description, :canonical, :predicate, keyword_init: true)
+
+    Mutation = Struct.new(:target, :op, :source, keyword_init: true) do
+      include Hecks::IR
+      include Behaviour::Mutation
+
+      # `sign:` — item #5 of the whole-project table-unification survey.
+      # `increment`/`decrement`'s own +1/-1 used to be re-derived from the
+      # op NAME by two independent Rust codegen scripts (rust/project/
+      # mutations.rb, rust/codegen/src/mutations.rs — a ternary on
+      # `op == "increment"` in each), even though the fact was already
+      # table-driven on the Ruby runtime side
+      # (Runtime::CommandRules::Arithmetic::MUTATION_OPS, held equal to
+      # Vocabulary::MutationOp by spec/vocabulary_conformance_spec.rb).
+      # Reads `Vocabulary::MutationOp` directly (plain data, no framework
+      # dependency — safe during parsing, same reason `RuleReference`'s
+      # own bootstrap concerns don't apply here) rather than requiring
+      # Runtime::CommandRules from the bluebook/IR layer, which would be a
+      # real layering inversion (runtime depends on bluebook, not the
+      # reverse). "" (not nil) for ops with no sign, matching every other
+      # optional IR text field's own absent-is-empty-string convention.
+      def self.sign_for(op)
+        Hecks::Vocabulary.rows("MutationOp").find { |row| row["name"] == op.to_s }&.fetch("sign", "") || ""
+      end
+
+      emits_ir(target: :target, op: :op, sign: -> { Mutation.sign_for(op) })
+
+      # THE ONE GENUINELY BRANCHING EMISSION in the model: an append (or a
+      # DELEGATE — `CommandBuilder#delegates_to`'s own comment gives the
+      # full reasoning for reusing this exact wire shape rather than
+      # inventing a parallel one) binds several fields at once and carries
+      # `fields:`, everything else carries a single `source:`. Declared
+      # emission covers the fixed head; `super` supplies it and this adds
+      # the tail, which is why a construct with a variable shape needs no
+      # new mixin API.
+      def to_h
+        return super.merge(fields: appended_fields) if [:append, :delegate].include?(op)
+
+        super.merge(source: classified_source)
+      end
+    end
+
+    # A command, as a RUBY CLASS.
+    #
+    # NOT nested as a constant, and that is a finding rather than a shortcut. A
+    # command and a value object may legitimately share a name inside one
+    # aggregate — the language does it six times, and means it: the command
+    # `Argument` is the verb that appends to the `arguments` list whose element
+    # type is the value object `Argument`, and `Plan` reads exactly that pairing.
+    # So `Bluebook::Command::Argument` cannot be both, and a single constant
+    # namespace cannot index a kind-ambiguous name. The same follows for
+    # `hecks_fqn` : `Bluebook::Command.Argument` names both, which is why the judge's
+    # ids only work per-category, each in its own repository. IDENTITY IS
+    # (KIND, FQN), not fqn.
+    #
+    # It is a declaration holder anyway, because that is where the EDGES live.
+    # `acts_on` answers with the owning construct itself — the Aggregate,
+    # or the entity holder for a piece's verb — rather than the name of one.
+    # The invocation door (`pizza.add_topping`) is the facade's business, a
+    # per-boot projection ; no verb method is defined here.
+    class Command
+      extend Construct
+      extend Hecks::IR
+      extend Behaviour::Command
+
+      emits_ir(
+        name:       :hecks_name,
+        role:       :role,
+        goal:       :goal,
+        references: :references,
+        attributes: many(:attributes),
+        givens:     -> { givens.map { |rule| { description: rule.description, canonical: rule.canonical } } },
+        ensures:    -> { ensures.map { |rule| { description: rule.description, canonical: rule.canonical } } },
+        mutations:  many(:mutations),
+        emits:      :emits,
+        # THE LIFECYCLE STATE THIS COMMAND IS ADMISSIBLE FROM (S10, ADR
+        # 0025 — "lifecycle state becomes a command guard") — a GUARD,
+        # not a transition: `command "Debit", from: "open"` replaces
+        # `given("account is open") { status == "open" }`, checked
+        # against the owning construct's own lifecycle field the same
+        # way `admissible_transition` already checks a real state
+        # change, but names no target state and moves nothing. Nil for
+        # a command with no such guard — most commands.
+        from:       -> { from },
+        provenance: :provenance
+      )
+
+      class << self
+        attr_reader :role, :goal, :attributes, :givens, :ensures, :mutations, :emits, :references,
+                    :from, :provenance
+
+        def declare(name:, role: nil, goal: nil, attributes: [], givens: [], ensures: [],
+                    mutations: [], emits: [], references: nil, from: nil, provenance: nil)
+          verb = Class.new(self)
+          verb.hecks_name = name.to_s
+          verb.absorb(role: role, goal: goal, attributes: attributes, givens: givens,
+                      ensures: ensures, mutations: mutations, emits: emits, references: references&.to_s,
+                      from: from, provenance: provenance)
+          verb
+        end
+
+        def absorb(role:, goal:, attributes:, givens:, ensures:, mutations:, emits:, references:,
+                   from: nil, provenance: nil)
+          @role       = role
+          @goal       = goal
+          @attributes = attributes
+          @givens     = givens
+          @ensures    = ensures
+          @mutations  = mutations
+          @emits      = emits
+          @references = references
+          @from       = from
+          @provenance = provenance
+          settle
+        end
+      end
+    end
+  end
+end

data/lib/hecks/bluebook/domain_port.rb

@@ -0,0 +1,102 @@
+require_relative "behaviour/domain_port"
+
+module Hecks
+  module Bluebook
+    # THE PRIMARY/DRIVING HALF OF HEXAGONAL ARCHITECTURE (Cockburn) — called
+    # BY an adapter living outside the bluebook entirely, never by the
+    # domain calling out. That is already `Hecks.port` (persistence,
+    # projection, extraction, loading) plus `Ports::*` : the secondary/
+    # driven half, unchanged by this.
+    #
+    # An operation carries no `given`/`ensures`/`then_set` — a port is the
+    # anti-corruption boundary that turns an external call into a fact in
+    # this domain's own vocabulary, not a second place business rules live.
+    # Those stay on whatever command a `policy` triggers in reaction to the
+    # event an operation emits.
+    class PortOperation
+      include Hecks::IR
+      include Behaviour::PortOperation
+
+      emits_ir(name: :hecks_name, attributes: many(:attributes), emits: :emits)
+
+      attr_reader :hecks_name, :attributes, :emits, :direction, :answers, :refuses, :to
+
+      # TWO DIRECTIONS THROUGH ONE DOOR.
+      #
+      # `:inbound` is what this class has always been — `tells`, spelled
+      # `operation` before it had a twin: an external fact arriving, turned
+      # into this domain's own event. It emits and that is all; there is no
+      # channel back to whoever called.
+      #
+      # `:outbound` is `asks` — the domain wanting something from outside
+      # and having to live with either answer. It names BOTH: `answers` for
+      # what the adapter came back with, `refuses` for what it said instead.
+      # Naming only the happy one would put the failure somewhere the model
+      # cannot see, which is the whole reason a boundary is worth modelling.
+      def initialize(name:, attributes: [], emits: [], direction: :inbound, answers: nil, refuses: nil, to: nil)
+        @hecks_name = name.to_s
+        @attributes = attributes
+        @emits      = emits
+        @direction  = direction.to_sym
+        @answers    = answers
+        @refuses    = refuses
+        @to         = to
+        @attributes_by_name = attributes.to_h { |attribute| [attribute.name, attribute] }
+      end
+
+      def outbound? = @direction == :outbound
+      def inbound?  = @direction == :inbound
+
+      # No root reference of its own — unlike a command, every attribute
+      # EQUALLY describes the payload, including whichever one identifies
+      # the record its emitted event belongs to. Kept only so
+      # CommandInterpreter::ArgumentGate's `reference_key` can ask for it
+      # without learning this isn't a command.
+
+      # `direction`/`answers`/`refuses` are deliberately OUTSIDE `emits_ir`'s
+      # declared shape and added here only for an outbound operation — an
+      # ordinary inbound one (`tells`, still spelled `operation` everywhere
+      # in the existing corpus) keeps the EXACT prior IR shape, byte for
+      # byte. Pizzas' `PaymentGateway` port is inbound-only and is checked
+      # against `hecks-parse`'s own Rust output for byte-identity
+      # (parser_parity_spec.rb) — the Rust side has no notion of `asks` yet,
+      # so an unconditional new key here would break that parity for a
+      # domain that never asked for the feature. Only a chapter that
+      # actually declares `asks` (this extraction's own QualityControl
+      # ledger, not yet in any Rust-parity corpus) pays for it.
+      # `to` — SAME "deliberately outside emits_ir, merged in only when
+      # present" treatment as direction/answers/refuses just above, and
+      # for the identical reason: an operation still spelled the old way
+      # (`reference_to` inside the block, shadow-parsing only — see
+      # reference_to_impl's own comment) or one that simply hasn't
+      # migrated yet keeps the EXACT prior IR shape, byte for byte,
+      # instead of an unconditional new key breaking parser_parity_spec
+      # for every domain that never touched this.
+      def to_h
+        shape = super
+        shape = shape.merge(direction: @direction.to_s, answers: @answers, refuses: @refuses) unless inbound?
+        shape = shape.merge(to: @to) if @to
+        shape
+      end
+    end
+
+    # A named group of operations an aggregate (or, later, a chapter)
+    # exposes to whatever adapter calls in — the contract that today lives
+    # only as a bare `verb`/`signal` pair in a standalone `.port` file.
+    # Superseding those is the goal ; for now they keep working untouched,
+    # and this is additive.
+    class DomainPort
+      include Hecks::IR
+      include Behaviour::DomainPort
+
+      emits_ir(name: :name, operations: many(:operations))
+
+      attr_reader :name, :operations
+
+      def initialize(name:, operations: [])
+        @name       = name.to_s
+        @operations = operations
+      end
+    end
+  end
+end