hecks 0.2.0 → 1.0.0

data/lib/hecks/bluebook/assembly/specializer.rb

@@ -0,0 +1,70 @@
+module Hecks
+  module Bluebook
+    class Assembly
+      # THE FIRST SPECIALIZER — a projection of `contracts.rb`'s `fields:` table,
+      # derived from the language's own description of a category instead of
+      # hand-written beside it.
+      #
+      # `Plan` already reads `grammar_registry` to build the judge's walk ; this
+      # reads the same chapter to build the OTHER table this arc's own header
+      # names as duplication — "SPELLED AS THE IR SPELLS THEM," field for field,
+      # for every category simple enough to say so.
+      #
+      # ONE CASE, PROVEN, NOT THE WHOLE TABLE. A field this can speak for is
+      # scalar and not a reference — every other field (a list, a reference, a
+      # fold like Lifecycle) is exactly what `contracts.rb`'s `reads:`/`derived:`
+      # exist to say, and stays hand-written until a later projection learns to
+      # derive readers and folds too. Restricting the claim to what can be
+      # PROVEN CORRECT — checked in spec/specializer_spec.rb against two
+      # independent categories — is the same discipline `derived:` itself
+      # enforces : a claim needs a kind, and this one's kind is "plain, checked."
+      module Specializer
+        module_function
+
+        # `position` IS THE FIRST FOLD THIS RUNS INTO, and it is a universal
+        # one : every category declares `attribute :position, Position` — for
+        # the JUDGE's own walk, `order_by :position` on its `DeclaredIn` ask —
+        # but no `*` constructor takes it as an argument. `contracts.rb`
+        # already says so, in the language every other derived field speaks :
+        # `derived: { position: :walk }`. The language says a category HAS a
+        # position ; it does not say a category's OWN constructor is handed
+        # one, and that second fact is exactly what `fields:` needs to answer.
+        # So this is not silently special-cased — it is the one fold named
+        # here because it is the one fold that is not a lucky accident of
+        # Policy or Handler, but a fact true of every category this arc will
+        # ever reach.
+        DERIVED_EVERYWHERE = %i[position].freeze
+
+        # S17, ADR 0026 — `Handler` is a genuine entity now, nested under
+        # `ProcessManager`, so `.aggregate` alone no longer finds it —
+        # it hangs off some aggregate's own `.entities` instead
+        # (searched recursively, the same reason `Value::Coercion#find_
+        # entity` does: a NESTED entity, like `Dispatch` inside
+        # `Handler`, is not a direct child of any aggregate either).
+        def construct_for(chapter, name)
+          chapter.aggregate(name) || chapter.aggregates.filter_map { |a| find_entity(a, name) }.first
+        end
+
+        def find_entity(construct, name)
+          construct.entities.each do |candidate|
+            return candidate if candidate.hecks_name == name
+
+            found = find_entity(candidate, name)
+            return found if found
+          end
+          nil
+        end
+
+        def fields_for(category)
+          language = construct_for(MetaValidator.grammar_registry.bluebook("Bluebook"), category.to_s)
+          language.attributes.each_with_object({}) do |attribute, fields|
+            next if attribute.list? || attribute.reference?
+            next if DERIVED_EVERYWHERE.include?(attribute.name)
+
+            fields[attribute.name] = [attribute.name, :plain]
+          end
+        end
+      end
+    end
+  end
+end

data/lib/hecks/bluebook/assembly.rb

@@ -0,0 +1,91 @@
+module Hecks
+  module Bluebook
+    # A GRAPH BUILT FROM DECLARATIONS, rather than from DSL calls.
+    #
+    # This is the half that lets the language orchestrate. `Reconstruction` reads a
+    # chapter back out of the meta-domain, in declaration order, as plain
+    # declarations — the same shape `to_h` spells. This turns those declarations
+    # into the graph the runtime runs: IR aggregates with their verbs, value
+    # objects, entities and asks, owned by the chapter that declares them.
+    #
+    # It takes a HASH, not a runtime, on purpose. That makes it a pure inverse of
+    # `to_h` and testable without the meta-domain in the picture at all:
+    #
+    #     Assembly.call(built.to_h).to_h == built.to_h
+    #
+    # which is the check `spec/assembly_spec` makes for every chapter in the tree.
+    # Feed it the reconstruction instead and the same code assembles what the
+    # LANGUAGE holds — the only difference being where the declarations came from.
+    #
+    # EVERY FIELD IS READ FROM ONE TABLE. There is no method per category here:
+    # `Contracts` names what the language cannot say about a construct, `Build`
+    # reads it, and the coverage gate holds the table to the language. The first
+    # draft of this file did have a method each, which is the shape the judge used
+    # to have — and the price of that shape was fourteen verbs the language declared
+    # and nothing ever offered.
+    #
+    # What stays hand-written is the CONTAINMENT: which construct holds which.
+    # That is not a field table. (The runtime SURFACE is no longer built here at
+    # all — the door is a per-boot projection, facade/surface.rb.)
+    class Assembly
+      def self.call(declaration) = new(declaration).bluebook
+
+      def initialize(declaration)
+        @declaration = declaration
+      end
+
+      def bluebook
+        aggregates = Array(@declaration[:aggregates]).map { |row| AggregateAssembly.new(row).aggregate }
+        models     = Array(@declaration[:read_models]).map { |row| Build.call("ReadModel", row) }
+
+        chapter = Build.call(
+          "Bluebook", @declaration,
+          aggregates:       aggregates,
+          read_models:      models,
+          policies:         reactions(aggregates),
+          process_managers: Array(@declaration[:process_managers]).map { |row| process_manager(row) }
+        )
+
+        chapter
+      end
+
+      private
+
+      # Every reaction the chapter holds, and each one also handed back to the head
+      # that declared it — the builder keeps a policy in BOTH places, hoisting it onto
+      # the chapter where the runtime reads it while the head keeps its own list. The
+      # language records which head, so the assembly can put it back.
+      def reactions(aggregates)
+        Array(@declaration[:policies]).map { |row| Build.call("Policy", row) }.each do |reaction|
+          next if reaction.aggregate.to_s.empty?
+
+          head = aggregates.find { |held| held.hecks_name == reaction.aggregate }
+          head&.policies&.push(reaction)
+        end
+      end
+
+      def process_manager(row)
+        Build.call("ProcessManager", row,
+                   handlers: Array(row[:handlers]).map { |leg| handler(leg) })
+      end
+
+      def handler(row)
+        Build.call("Handler", row,
+                   dispatches: Array(row[:dispatches]).map { |leg| dispatch(leg) })
+      end
+
+      # `compensates` — a PLAIN HASH on the declaration (`Reconstruction#
+      # dispatch`'s own comment for why), built into the real
+      # `DispatchSpec` its own field actually is by recursing through
+      # THIS SAME method, one level in — the identical move `handler`
+      # itself takes into `dispatches`, one level up. `nil` when there
+      # is nothing to compensate; `Build.call` never sees a
+      # `compensates:` key it does not know how to read either way, the
+      # same reason `compensates` never joined `Contract#fields` at all.
+      def dispatch(row)
+        compensates = row[:compensates] && dispatch(row[:compensates])
+        Build.call("Dispatch", row, compensates: compensates)
+      end
+    end
+  end
+end

data/lib/hecks/bluebook/attribute.rb

@@ -0,0 +1,96 @@
+require_relative "behaviour/attribute"
+require_relative "../ir"
+require_relative "../vocabulary"
+require_relative "../naming"
+
+module Hecks
+  module Bluebook
+    class Attribute
+      include Hecks::IR
+      include Behaviour::Attribute
+
+      emits_ir(
+        name:         :name,
+        type:         -> { @type.to_s },
+        list:         :list?,
+        default:      :default,
+        optional:     :optional?,
+        pattern:      :pattern,
+        admits:       :admits,
+        relationship: :relationship
+      )
+
+      attr_reader :name, :type, :default, :pattern, :admits, :relationship
+
+      # A Reference is kept AS ITSELF. Every other type is still a name, and
+      # crosses over as its construct does.
+      #
+      # `admits` names an ALREADY-DECLARED closed set the value must belong
+      # to — `Vocabulary::QueryComparator` — spelled aggregate-qualified
+      # because the set is a value object INSIDE an aggregate, and the
+      # aggregate is the only thing `reference_to` can reach.
+      #
+      # ON THE WIRE, because it is a RULE and not only a typing hint.
+      #
+      # It began as neither. The link existed so a generator could type
+      # `WhereClause.op` as `WhereOp` — a typing convenience, not worth
+      # moving 710 attribute records across eight goldens for. Then `admits`
+      # grew teeth (coercion refuses a non-member) and the argument
+      # inverted: a rule the wire does not carry is one a reader of the IR
+      # cannot enforce, and a bluebook whose meaning depends on the reader
+      # means two things. Proved rather than assumed — the same domain
+      # refused "burnt" through one reading and emitted the event through
+      # another.
+      #
+      # The wire carries the NAME, not the members. A reader resolves it
+      # against the IR it holds, so the members are declared once and
+      # copied nowhere — which is the same reason `admits` exists at all.
+      def initialize(name:, type:, list: false, default: nil, optional: false, pattern: nil,
+                     admits: nil, relationship: nil)
+        @name     = name.to_sym
+        @type     = spell(type)
+        @list     = list
+        @default  = default
+        @optional = optional
+        @pattern  = pattern
+        @admits   = admits&.to_s
+        @relationship = relationship&.to_s
+      end
+
+      # A BARE CONSTANT IN A BLUEBOOK IS A NAME, EVEN WHEN RUBY HAS HEARD OF IT.
+      #
+      # `BluebookBuilder.build` says exactly this and installs a `const_missing`
+      # resolver that hands back the symbol — `attribute :target, Target` becomes
+      # the name "Target" and nothing looks Target up. That works only while the
+      # lookup FAILS, and `Facade::Surface` installs every aggregate name as a
+      # TOP-LEVEL constant (its own comment, and `ConstShim`'s, both say so).
+      #
+      # So in one process: boot a domain with an aggregate named `Target`, then
+      # load a chapter whose own value object is called `Target`, and Ruby
+      # resolves the constant before the hook is ever asked. The chapter is then
+      # built against somebody else's aggregate — silently, with no refusal —
+      # and the attribute stops meaning what the file plainly says.
+      #
+      # DEMODULISED, so both paths spell it the same: `:Target` and
+      # `QualityControl::Target` are both "Target". A plain class stays itself —
+      # `String` demodulises to "String" — so the ordinary case is untouched.
+      # This does not undo the constant leak; it makes the leak unable to change
+      # what a chapter MEANS, which is the part that has to hold.
+      def spell(type)
+        return type if type.is_a?(Reference)
+        return Naming.demodulise(type) if type.is_a?(Module)
+
+        type.to_s
+      end
+      private :spell
+
+      # Held because a declared vocabulary pins it — spec/vocabulary_conformance
+      # holds `Primitive`'s members to this list. The `primitive?` predicate that
+      # used to read it had no caller anywhere and is gone.
+      PRIMITIVES = Hecks::Vocabulary.fetch("Primitive")
+
+      # `type` is spelled, never handed over. A Reference renders as
+      # "Reference<Customer>" here because that is the export's pinned spelling.
+    end
+  end
+end

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

@@ -0,0 +1,83 @@
+require_relative "traits"
+
+module Hecks
+  module Bluebook
+    module Behaviour
+      # WHAT AN AGGREGATE DOES, as opposed to what it holds.
+      #
+      # The holding half — the field list, the readers, the emission — is
+      # the same list the language already declares in
+      # `language/bluebook/aggregate.bluebook`, said a second and third
+      # time in Ruby. This half is not: derived identity, the name
+      # indexes, the owner stamping and the finders are decisions about
+      # HOW the declared shape is used, and no grammar states them.
+      #
+      # Split so the holding half can be generated from the language
+      # without any of this being in the blast radius of a regeneration.
+      # Everything here is hand-written and permanent.
+      #
+      # The three traits are shared with Entity (and, for `Indexed`,
+      # with Command and PortOperation) — see behaviour/traits.rb on why
+      # they are one module rather than four copies.
+      module Aggregate
+        include Identified
+        include Indexed
+        include Owns
+
+        # An aggregate is a MEMBER of its chapter's namespace — "Pizzas::Pizza" —
+        # where everything else is declared ON its owner and joins with ".".
+        def hecks_separator = "::"
+
+        # THE HOOK THE GENERATED CONSTRUCTOR CALLS once every declared
+        # field is assigned. Nothing here is derivable from the
+        # declaration, which is exactly why it is not generated.
+        def settle
+          derive_identity
+          index_declarations
+          # An entity stamps its own commands and queries when it is
+          # declared, so the chain closes downward from here.
+          stamp(@commands, @value_objects, @entities, @queries)
+          self
+        end
+
+        def index_declarations
+          index_attributes(@attributes)
+          @value_objects_by_name = index_by_hecks_name(@value_objects)
+          @commands_by_name      = index_by_hecks_name(@commands)
+          @queries_by_name       = index_by_hecks_name(@queries)
+          @ports_by_name         = @ports.to_h { |port| [port.name, port] }
+          # S12, ADR 0025 — keyed by SYMBOL, the same convention
+          # `Indexed#attribute` already uses; `GuardState` asks for one
+          # by name at every dispatch, the rebuild sweep walks all of
+          # them once per pass.
+          @projected_fields_by_name = @projected_fields.to_h { |field| [field.name, field] }
+        end
+
+        def projected_field(named) = @projected_fields_by_name[named.to_sym]
+
+        # A value object is a CLASS now, so `name` is Ruby's answer (the constant
+        # path) and the declared name is `hecks_name`. This finder is on its way
+        # out — once an attribute's type IS the class there is nothing to find —
+        # but every consumer still asks by type string, so it stays until they
+        # stop.
+        def value_object(named) = @value_objects_by_name[named.to_s]
+        def port(named)         = @ports_by_name[named.to_s]
+
+        # A PORT IS DECLARED IN THE HECKSAGON, NOT THE BLUEBOOK — the
+        # boundary between the domain and its adapters, in hexagonal terms,
+        # is exactly what a `.hecksagon` file already IS for every other
+        # port (persistence, projection, ...). So this attaches AFTER the
+        # aggregate already exists and is registered — `HecksagonBuilder`
+        # calls it once per `port` declaration, having already stamped each
+        # operation's reference attributes with `declared_in = self`, since
+        # nothing upstream of a hecksagon load does that for it.
+        def add_port(port)
+          @ports << port
+          @ports_by_name[port.name] = port
+        end
+
+        def storage_name = Naming.snake(@name)
+      end
+    end
+  end
+end

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

@@ -0,0 +1,27 @@
+module Hecks
+  module Bluebook
+    module Behaviour
+      # WHAT AN ATTRIBUTE DOES. The declared half — name, type, list,
+      # default, optional, pattern, admits — is what the language states
+      # in `aggregate.bluebook`'s own `Field`. These are the questions
+      # readers ask ABOUT that shape, which no declaration states.
+      module Attribute
+        def list?      = @list
+        def scalar?    = !@list
+        def reference? = @type.is_a?(Reference)
+
+        # MAY THIS FACT BE LEFT OUT?
+        #
+        # Required is the default and by far the common case — a command takes
+        # the arguments it declares, and all of them — so the EXCEPTION is what
+        # gets marked. Marking the other way would annotate almost every
+        # attribute in the corpus to say nothing.
+        #
+        # Only a COMMAND enforces this. An aggregate's own attributes are filled
+        # by the commands that set them, and a value object's by its
+        # constructor ; neither is a payload anyone hands in.
+        def optional? = @optional
+      end
+    end
+  end
+end

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

@@ -0,0 +1,72 @@
+require_relative "traits"
+
+module Hecks
+  module Bluebook
+    module Behaviour
+      # WHAT A CHAPTER DOES. The declared half is the roll-call of what a
+      # bluebook holds; these are the finders over it, plus `verbs` — the
+      # chapter's own list of every dispatchable name, which is derived
+      # from the aggregates rather than declared anywhere.
+      module Chapter
+        include Owns
+
+        # THE HOOK THE GENERATED CONSTRUCTOR CALLS. Three things a
+        # declaration does not state: that a chapter is the ROOT of the
+        # owner chain (nothing declares it, it is what having no owner
+        # MEANS), the ports table — which a `.hecksagon` fills later, so
+        # the bluebook cannot declare it — and stamping its own children,
+        # the same act an Aggregate performs one level down.
+        def settle
+          @hecks_root    = true
+          @ports         = []
+          @ports_by_name = {}
+          stamp(@aggregates, @read_models)
+          self
+        end
+
+        def aggregate(named)  = @aggregates.find { |a| a.name == named.to_s }
+        def read_model(named) = @read_models.find { |model| model.name == named.to_s || model.query_name == named.to_s }
+        def port(named)       = @ports_by_name[named.to_s]
+
+        # A PORT IS DECLARED IN THE HECKSAGON, not the bluebook — so it
+        # attaches after the chapter already exists, the same way an
+        # aggregate's own ports do.
+        def add_port(port)
+          @ports << port
+          @ports_by_name[port.name] = port
+        end
+
+        # Every dispatchable name this chapter answers to, spelled exactly
+        # as Dispatcher#dispatch takes it. Derived from the aggregates,
+        # never declared — which is why Projections::OIDC can hold its own
+        # scope list equal to this and have that mean something.
+        #
+        # Recurses into entities, not just an aggregate's own direct
+        # commands — `Dispatcher#dispatch` already routes a dotted
+        # `Domain::Aggregate.Entity.Command` verb to `EntityInterpreter`
+        # (a command_name with a "." in it), so a verb this method left
+        # out was never "not a verb," only one this list forgot to name.
+        # Ported from the same recursive shape `spec/judge_coverage_spec.rb`
+        # already proved out for the meta-domain's own grammar (S17, ADR
+        # 0026) — entities nest arbitrarily deep (`Dispatch`, inside
+        # `Handler`), so one flat level isn't enough.
+        def verbs
+          @aggregates.flat_map { |agg| aggregate_verbs(agg) }
+        end
+
+        private
+
+        def aggregate_verbs(agg)
+          agg.commands.map { |cmd| "#{@name}::#{agg.hecks_name}.#{cmd.hecks_name}" } +
+            agg.entities.flat_map { |entity| entity_verbs("#{@name}::#{agg.hecks_name}", entity) }
+        end
+
+        def entity_verbs(prefix, entity)
+          dotted = "#{prefix}.#{entity.hecks_name}"
+          entity.commands.map { |cmd| "#{dotted}.#{cmd.hecks_name}" } +
+            entity.entities.flat_map { |piece| entity_verbs(dotted, piece) }
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,116 @@
+require_relative "traits"
+
+module Hecks
+  module Bluebook
+    module Behaviour
+      # WHAT A COMMAND DOES. EXTENDED, not included — a command is a
+      # CLASS, one per declared verb.
+      module Command
+        include Indexed
+
+        # Indexed once — attributes are final once absorbed, and every
+        # dispatch asks this finder by name.
+        def settle
+          index_attributes(@attributes)
+          self
+        end
+
+        # The construct this verb acts upon — the construct itself, not its name.
+        #
+        # A verb declared on an ENTITY always acts on that piece. It never
+        # self-references, because an element is addressed THROUGH its parent —
+        # which means `creates?` answers true for every one of them, and reading
+        # `acts_on` off `creates?` alone would report that `LedgerEntry.Amend`
+        # brings a ledger entry into being. Three of banking's commands were
+        # about to say exactly that, and nothing would have contradicted them.
+        #
+        # On an aggregate, a creating command acts on no existing root, so nil is
+        # the truth: there is nothing there yet.
+        def acts_on
+          # FULLY QUALIFIED, and it has to be: inside `module Behaviour`
+          # the bare name `Entity` resolves to Behaviour::Entity — this
+          # module's SIBLING — not to the construct. Comparing a Class to
+          # a Module answers nil, so the guard silently fell through and
+          # every entity verb reported acting on nothing.
+          return hecks_owner if hecks_owner.is_a?(Class) && hecks_owner < Bluebook::Entity
+
+          creates? ? nil : hecks_owner
+        end
+
+        def creates? = @references.nil?
+
+        # EVERY REASON THIS VERB CAN REFUSE ON A RULE — the descriptions of
+        # its givens AND its ensures, the exact text the runtime quotes
+        # after "refused — " when a guard is not met (see
+        # command_rules/admissibility.rb's GivenNotMet/EnsuresNotMet). A
+        # property that asks "did the runtime only ever refuse for a rule
+        # the language wrote" reads this rather than re-deriving the two
+        # collections; `compact` because a rule's description is optional
+        # (behavior.bluebook's Rule) and an unnamed one quotes nothing.
+        def guard_descriptions = (@givens + @ensures).map(&:description).compact
+
+        # THE ARGUMENT NAME THAT ADDRESSES an instance of `aggregate_name`
+        # for THIS command — the one fact `PolicyInterpreter`'s own
+        # `for_each` fan-out needs and, until this reading existed, had
+        # to guess at (see git blame: `Behaviour::Policy
+        # #fan_out_reference_key`, which hardcoded `<aggregate>_id`
+        # unconditionally and refused every dispatch to a self-
+        # addressing command as a result — `Account.Freeze`, addressed
+        # by `number`/`account`, not `account_id`).
+        #
+        # TWO SHAPES, the same two `CommandBuilder#reference_to` already
+        # tells apart at declare time (command_builder.rb's own comment
+        # on `cross_reference` — "`as:` MEANS a named attribute... a
+        # command can point at another instance of its OWN kind"):
+        #
+        #   SELF-ADDRESSING — `references == aggregate_name` (this verb
+        #   is declared ON the very aggregate it acts on, `reference_to
+        #   Account` on a command Account itself owns). No attribute was
+        #   minted for it at all; the SAME bare key
+        #   `CommandInterpreter::ArgumentGate#reference_key` already
+        #   accepts as "addressing, not describing" is reused here
+        #   rather than re-derived — one door, not two.
+        #
+        #   CROSS-REFERENCING — a real, declared reference-typed
+        #   attribute whose OWN target is `aggregate_name` (`customer_id`
+        #   on `Account.Open`, or whatever `as:` named it). Its NAME is
+        #   the key, exactly as declared — never re-derived from the
+        #   target's name, because an `as:` reference's name and its
+        #   target's snake case can legitimately differ (`Transfer`'s own
+        #   `source`/`destination`, both `Reference<Account>`).
+        #
+        # `nil` when neither shape matches — a CREATING command (nothing
+        # to address yet) or one that simply never references this
+        # aggregate at all. A caller minting a fan-out dispatch is
+        # expected to treat `nil` as "this command cannot be addressed by
+        # a row of this aggregate," not to fall back on a guess.
+        def addressing_key_for(aggregate_name)
+          return Naming.reference_key(aggregate_name) if references.to_s == aggregate_name.to_s
+
+          attributes.find { |attribute| attribute.reference? && attribute.type.target_name.to_s == aggregate_name.to_s }
+                    &.name
+        end
+      end
+
+      # A MUTATION'S OWN READINGS. Included (not extended) — Mutation is
+      # a Struct, so these are instance methods.
+      module Mutation
+        # An APPEND binds several fields at once, each from either a command
+        # ARGUMENT (a Symbol) or a LITERAL. It used to spell the Symbol bare
+        # and inspect the rest, which is the opposite of what a where-clause
+        # did with the same two kinds — see Hecks::Literal.
+        def appended_fields = source.transform_values { |value| Literal.render(value) }
+
+        def classified_source
+          if source.is_a?(Symbol)
+            { kind: "argument", name: source.to_s }
+          elsif source.is_a?(StateRef)
+            { kind: "state", name: source.name.to_s }
+          else
+            { kind: "literal", value: source }
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,25 @@
+require_relative "traits"
+
+module Hecks
+  module Bluebook
+    module Behaviour
+      # WHAT ONE PORT OPERATION DOES.
+      module PortOperation
+        include Indexed
+
+        # An operation declares no reference of its own — the OWNER is
+        # what it acts for, and `identity_attribute` is how that is found.
+        def references = nil
+
+        def identity_attribute(owner_name)
+          @attributes.find { |attribute| attribute.reference? && attribute.type.target_name == owner_name.to_s }
+        end
+      end
+
+      # WHAT A PORT DOES — one finder over its declared operations.
+      module DomainPort
+        def operation(named) = @operations.find { |op| op.hecks_name == named.to_s }
+      end
+    end
+  end
+end

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

@@ -0,0 +1,59 @@
+require_relative "traits"
+
+module Hecks
+  module Bluebook
+    module Behaviour
+      # WHAT AN ENTITY DOES. EXTENDED, not included — an entity is a
+      # CLASS, so this is singleton behaviour.
+      #
+      # `settle` is the same seam an Aggregate has, reached from `absorb`
+      # rather than from a constructor because a declared entity is built
+      # by subclassing rather than by `new`. The traits are the same
+      # ones, which is the whole point of them being traits: an entity's
+      # identity is derived exactly as an aggregate's is, and was written
+      # out twice before anyone could see that.
+      module Entity
+        include Identified
+        include Indexed
+        include Owns
+
+        def settle
+          derive_identity
+          index_declarations
+          self
+        end
+
+        def index_declarations
+          index_attributes(@attributes)
+          @commands_by_name = index_by_hecks_name(@commands)
+          @queries_by_name  = index_by_hecks_name(@queries)
+        end
+
+        # S17, ADR 0026 — `@entities`, now genuinely NESTED entities
+        # (Dispatch, inside Handler) rather than always `[]`. Kept as a
+        # real reader rather than a hardcoded empty list for two
+        # reasons at once: `Value::Coercion#for_attribute` calls
+        # `.entities` on WHATEVER OWNER it is handed — an aggregate's or
+        # an entity's own — the moment it meets ANY `list_of(...)`
+        # attribute (entity-typed or not — `hydrate_entity_list`'s own
+        # fallback, `return value unless entity`, only runs once
+        # `.entities` has already answered) ; and `EntityInterpreter`
+        # now walks a DOTTED chain of entities one level at a time
+        # (`walk_entity_chain`) exactly the way an aggregate's own
+        # `.entities` is walked for its direct children. Entity's own
+        # header comment already promises it stays "structurally
+        # interchangeable with an aggregate" for exactly this reason.
+        def entities = @entities || []
+
+        # A piece OWNS the verbs declared on it, so they can state an
+        # identity — `Banking::Account.Ledger.Deposit` rather than a
+        # command that cannot say what it belongs to. Separate from
+        # `settle` because `declare` stamps AFTER absorbing, once the
+        # subclass that will own them exists. `@entities` too now
+        # (S17, ADR 0026) — a nested entity states its own owner chain
+        # exactly the way a nested command does.
+        def stamp_children = stamp(@commands, @queries, @entities)
+      end
+    end
+  end
+end