hecks 0.2.0 → 1.0.0

data/lib/hecks/behaviors/expectations.rb

@@ -0,0 +1,340 @@
+require_relative "ir"
+require_relative "../runtime/loader"
+require_relative "../runtime/errors"
+require_relative "../runtime/value"
+require_relative "../runtime/reaction_invocation"
+require_relative "../ports/persistence/binding_policy"
+
+# Hecks::Behaviors::Expectations
+#
+# One test case, start to finish: take the suite's own runtime (booted
+# once for exactly what its `loads` names, reset to nothing between
+# tests — `runtime_for`), replay `setup` dispatches, dispatch (or query)
+# the command under test, check `expect`. Split out of
+# runner.rb the same way the file-count/sweep concern is split from a
+# single test's own execution.
+#
+# TWO DELIBERATE DEVIATIONS from a prior port of this same idea (read
+# before writing this, not reinvented):
+#
+# 1. A `setup` refusal and a refusal from the command under test are
+#    caught in SEPARATE rescue scopes. The prior port wrapped the whole
+#    test body — setups included — in one `rescue *REFUSAL_CLASSES`, so a
+#    broken setup could spuriously satisfy `expect refused: "..."` if its
+#    own refusal happened to match the expected substring. Here, any
+#    domain refusal during `setup` is unconditionally an ERROR — the
+#    example never got to the situation it claims to test.
+#
+# 2. `emits:` is read off a `registry.event_log` DIFF around the tested
+#    dispatch, not off `Result#events` alone. `Result#events` only holds
+#    the events the OUTERMOST dispatch announced; a policy's own cascade
+#    reenters through the same `Dispatcher#dispatch` (`PolicyInterpreter
+#    #deliver` → `door.reenter` → `dispatch`), and every dispatch's
+#    events — outer and reentrant alike — land in the one shared
+#    `registry.event_log`, in order (`CommandRules::Emission#emit`,
+#    `PortOperationInterpreter#emit`/`#call`). Diffing that log's length
+#    before/after the tested dispatch is the one read that actually sees
+#    a cascade — this DSL has no `kind: :cascade` because cascades are
+#    always on and `emits:` is expected to see them.
+module Hecks
+  module Behaviors
+    module Expectations
+      module_function
+
+      REFUSAL_CLASSES = Hecks::Runtime::DOMAIN_REFUSALS
+      SPECIAL_KEYS = %i[ok refused emits count].freeze
+
+      def run_one(test, suite, runtime: nil)
+        runtime ||= runtime_for(suite)
+        runtime.registry.reset_runtime_state!
+        bluebooks = runtime.registry.bluebooks.values
+
+        current_setup = nil
+        begin
+          test.setups.each do |setup|
+            current_setup = setup
+            dispatch_command(runtime, qualify(setup.command, nil, bluebooks, kind: :command), setup.args)
+          end
+        rescue *REFUSAL_CLASSES => e
+          return error_result(test, "setup #{current_setup&.command.inspect} refused: #{e.message}")
+        end
+
+        run_tested(test, runtime, bluebooks)
+      rescue StandardError => e
+        error_result(test, "#{e.class}: #{e.message}")
+      end
+
+      # ONE BOOT PER SUITE, NOT PER TEST. The isolation a test needs is a
+      # runtime with nothing in it — and a boot of the same files gives
+      # exactly that back for the price of `Registry#reset_runtime_state!`
+      # instead of ~2s of loading, verifying and era-checking the same
+      # bluebook again (chess: 76 behaviours, 155s of which was booting
+      # `chess.bluebook` 76 times). Keyed by the suite's own `loads` AND
+      # their mtimes, so an edited bluebook boots fresh on the next test
+      # rather than running against a stale one — the property a watch
+      # loop or a long rspec session actually relies on. `runtime:` lets
+      # a caller that already holds a booted runtime (a spec, a REPL)
+      # hand it in; it is reset the same way.
+      RUNTIMES      = {}
+      RUNTIMES_LOCK = Mutex.new
+      private_constant :RUNTIMES, :RUNTIMES_LOCK
+
+      def runtime_for(suite)
+        files = Array(suite.loads).map { |path| File.expand_path(path) }
+        key   = files.map { |file| [file, File.exist?(file) ? File.mtime(file).to_f : nil] }
+
+        RUNTIMES_LOCK.synchronize do
+          RUNTIMES[key] ||= boot_and_guard(files)
+        end
+      end
+
+      # `reset_runtime_state!` only drops repository OBJECTS between
+      # tests (registry.rb) — sufficient isolation for `Memory`, whose
+      # `@records` is a plain per-instance ivar, so a fresh object really
+      # is a fresh store. Against anything else (Sqlite, Postgres) the
+      # rows themselves stay put: tests leak into each other, and a
+      # suite booted against a domain's REAL hecksagon writes to a real
+      # database. Refusing that wiring here, at boot, is the same shape
+      # of guard `BindingPolicy` already applies to a missing bind — the
+      # project's identity is refusing bad wiring up front, not
+      # discovering it mid-suite.
+      def boot_and_guard(files)
+        runtime = Hecks::Runtime::Loader.boot_files(files, install_facade: false)
+        guard_memory_only!(runtime)
+        runtime
+      end
+
+      def guard_memory_only!(runtime)
+        runtime.registry.bluebooks.each_value do |bluebook|
+          bluebook.aggregates.each do |aggregate|
+            bind = Ports::Persistence::BindingPolicy.resolve(runtime.registry, bluebook.name, aggregate)
+            next if bind.adapter == Ports::Persistence::DEFAULT_ADAPTER
+
+            raise Malformed,
+                  "#{bluebook.name}::#{aggregate.hecks_name} is persisted_by " \
+                  "#{bind.adapter.inspect}, not #{Ports::Persistence::DEFAULT_ADAPTER.inspect} — " \
+                  "a behaviors suite's `loads` must resolve every aggregate to an in-memory " \
+                  "binding, or tests leak state into each other and write to a real database. " \
+                  "Load a Memory-bound sibling hecksagon instead of the domain's real one — see " \
+                  "examples/pizzas/bluebook/pizzas.behaviors's own `loads` comment for the pattern."
+          end
+        end
+      end
+
+      def run_tested(test, runtime, bluebooks)
+        verb = qualify(test.tests_command, test.on_aggregate, bluebooks, kind: test.kind)
+
+        if test.query?
+          run_query(test, runtime, verb)
+        else
+          run_command(test, runtime, verb)
+        end
+      rescue *REFUSAL_CLASSES => e
+        check_refusal(test, e)
+      end
+
+      def run_command(test, runtime, verb)
+        before = runtime.registry.event_log.length
+        result = dispatch_command(runtime, verb, test.input)
+
+        return fail_result(test, "expected refused: #{test.expect[:refused].inspect} but dispatch succeeded") if test.expect.key?(:refused)
+
+        if (expected_emits = test.expect[:emits])
+          actual = runtime.registry.event_log[before..].map(&:name)
+          return fail_result(test, "expected emits: #{expected_emits.inspect}, got #{actual.inspect}") unless actual == expected_emits
+        end
+
+        check_ok(test) || check_fields(test, settled_state(runtime, verb, result)) || pass_result(test)
+      end
+
+      # A field expectation reads the aggregate AS IT STANDS once the
+      # dispatch and its whole cascade have run — the same "cascades are
+      # always on" reading `emits:` already commits to. `Result#state` is
+      # the wrong source for that: it snapshots the instance the OUTER
+      # dispatch saved, and a policy's own reentrant dispatch (a ply
+      # advancing off a Moved event, a move count bumping) hydrates and
+      # saves a FRESH record afterward — so a field the cascade wrote
+      # read back stale (found live: `expect move_count: 1` got 0 while
+      # `emits:` saw MoveCountBumped in the same test). The repository
+      # holds the settled record; read it back by the id the dispatch
+      # itself answered with.
+      def settled_state(runtime, verb, result)
+        return result.state || {} unless result.respond_to?(:id) && result.id
+
+        domain, rest = verb.split("::", 2)
+        aggregate_name = rest.to_s.split(".", 2).first
+        aggregate = runtime.registry.bluebook(domain)&.aggregate(aggregate_name)
+        return result.state || {} unless aggregate
+
+        record = runtime.registry.repository(domain, aggregate).find(result.id)
+        record ? record.state : (result.state || {})
+      end
+
+      # A behaviors test writes a dispatch the way the guide's own chess
+      # examples do — receiver identity and command facts side by side
+      # (`label: "g", id: "wn", to: { file: 2, rank: 2 }`) — and since
+      # #335 the dispatcher's own `to:` keyword is the ROUTING envelope,
+      # so forwarding those kwargs loose collides the moment a domain
+      # declares a command fact named `to` (chess does: every Move's own
+      # destination). Found live: every such test failed with "to: does
+      # not recognize file, rank" while this guide promised the spelling
+      # works. `ReactionInvocation.build` is #335's own seam for turning
+      # mixed facts into the strict envelope — identities lifted into
+      # `to:`, declared facts into `with:` — so a behaviors dispatch now
+      # goes through the exact same separation a policy's projection
+      # does. A verb that resolves to no command (a port operation —
+      # "Pizzas::Order.PaymentGateway.Receive") keeps the loose
+      # passthrough: its own input already spells the port form's
+      # `to:`/`with:`, which the dispatcher's port branch reads directly.
+      def dispatch_command(runtime, verb, args)
+        invocation = begin
+          Runtime::ReactionInvocation.build(registry: runtime.registry, verb: verb,
+                                            projected: args, explicit: true)
+        rescue Runtime::UnknownVerb
+          nil
+        end
+        return runtime.dispatch(verb, **args) unless invocation
+
+        if invocation.key?(:to)
+          runtime.dispatch(verb, to: invocation[:to], with: invocation[:with])
+        else
+          runtime.dispatch(verb, with: invocation[:with])
+        end
+      end
+
+      def run_query(test, runtime, verb)
+        rows = runtime.query(verb, **test.input)
+
+        return fail_result(test, "expected refused: #{test.expect[:refused].inspect} but the query succeeded") if test.expect.key?(:refused)
+
+        if (expected = test.expect[:count])
+          count = if rows.is_a?(Array)
+                    rows.size
+                  else
+                    (rows.nil? ? 0 : 1)
+                  end
+          return fail_result(test, "expected count: #{expected}, got #{count}") if count != expected
+        end
+
+        return check_ok(test) || pass_result(test) unless field_expectations?(test)
+
+        row = query_row(test, rows)
+        return row if row.is_a?(Result)
+
+        check_ok(test) || check_fields(test, row) || pass_result(test)
+      end
+
+      def field_expectations?(test)
+        test.expect.keys.any? { |key| !SPECIAL_KEYS.include?(key) }
+      end
+
+      # A field expectation on a query names one row's shape, so it only
+      # makes sense once the query has settled on exactly one — the same
+      # reason `expect status: "sold"` on a multi-row answer would be
+      # ambiguous about which row it's describing. `check_fields` itself
+      # stays row-shaped (it already is, for `run_command`'s settled
+      # state); this picks which row it reads.
+      def query_row(test, rows)
+        return rows unless rows.is_a?(Array)
+
+        case rows.size
+        when 1 then rows.first
+        when 0 then fail_result(test, "expect names a field, but the query returned no rows")
+        else fail_result(test, "expect names a field, but the query returned #{rows.size} rows — " \
+                               "narrow it with `input`/`expect count: 1` first")
+        end
+      end
+
+      def check_ok(test)
+        return unless test.expect.key?(:ok)
+
+        expected = test.expect[:ok]
+        return if expected == true || expected.nil?
+
+        fail_result(test, "expect ok: only accepts true — got #{expected.inspect}")
+      end
+
+      def check_fields(test, state)
+        test.expect.each do |key, expected|
+          next if SPECIAL_KEYS.include?(key)
+
+          unless state.key?(key) || state.key?(key.to_s)
+            return fail_result(test, "expect #{key}: names no field on the tested aggregate — " \
+                                     "valid expect keys are ok:, refused:, emits:, count: (queries only), " \
+                                     "or a real field name")
+          end
+
+          actual = normalize(state.key?(key) ? state[key] : state[key.to_s])
+          exp    = normalize(expected)
+          return fail_result(test, "expected #{key}: #{expected.inspect}, got #{actual.inspect}") unless actual == exp
+        end
+        nil
+      end
+
+      def check_refusal(test, error)
+        expected = test.expect[:refused]
+        return error_result(test, "unexpected refusal (#{error.class}): #{error.message}") unless expected
+
+        msg = error.message.to_s
+        # hecks's given/ensures refusals render "Command refused —
+        # <description>" (RefusalWording) ; a behaviors file names just
+        # the description — end_with?/include? bridges the prefix.
+        return pass_result(test) if msg == expected || msg.end_with?(expected) || msg.include?(expected)
+
+        fail_result(test, "expected refused: #{expected.inspect}, got #{msg.inspect}")
+      end
+
+      # The real corpus this DSL is proven against writes VO-typed
+      # `expect` values both ways — bare (`expect kind: "bishop"`) and
+      # wrapped (`expect kind: { value: "bishop" }`). A live record's
+      # field always comes back as a `Hecks::Runtime::Value`;
+      # normalizing BOTH sides to the same bare-scalar-or-plain-hash
+      # shape is the one comparison that accepts either spelling.
+      def normalize(value)
+        return Hecks::Runtime::Value.materialize_unwrapped(value) if value.is_a?(Hecks::Runtime::Value)
+        return normalize(value[:value]) if value.is_a?(Hash) && value.keys == [:value]
+
+        value
+      end
+
+      # A bare `tests`/`setup` command name carries no domain — `loads`
+      # can name more than one bluebook, so resolution searches every
+      # aggregate across every bluebook the suite booted for the one that
+      # actually declares the command. `on:` (when given, only ever on
+      # the TESTED command — `setup` never receives it, see the DSL
+      # contract) narrows the search to one aggregate by name instead of
+      # searching all of them.
+      def qualify(command, on_aggregate, bluebooks, kind:)
+        return command.to_s if command.to_s.include?(".")
+
+        members = kind == :query ? :queries : :commands
+        pairs =
+          if on_aggregate
+            bluebooks.filter_map { |bb| (agg = bb.aggregate(on_aggregate)) && [bb, agg] }
+          else
+            bluebooks.flat_map { |bb| bb.aggregates.map { |agg| [bb, agg] } }
+          end
+        candidates = pairs.select { |_, agg| agg.public_send(members).any? { |m| m.hecks_name == command.to_s } }
+
+        case candidates.size
+        when 0
+          raise ArgumentError, "no aggregate among #{bluebooks.map(&:name).inspect} declares a #{kind} " \
+                               "named #{command.inspect} — say `on:` if it's ambiguous, or check the spelling"
+        when 1
+          bluebook, aggregate = candidates.first
+          "#{bluebook.name}::#{aggregate.name}.#{command}"
+        else
+          owners = candidates.map { |bb, agg| "#{bb.name}::#{agg.name}" }
+          raise ArgumentError, "#{command.inspect} is declared on more than one aggregate (#{owners.join(', ')}) " \
+                               "— say `on:` to disambiguate, or use the dotted FQN"
+        end
+      end
+
+      def pass_result(test) = Result.new(description: test.description, status: :pass, message: nil)
+      def fail_result(test, message)  = Result.new(description: test.description, status: :fail, message: message)
+      def error_result(test, message) = Result.new(description: test.description, status: :error, message: message)
+
+      Result = Struct.new(:description, :status, :message, keyword_init: true)
+    end
+  end
+end

data/lib/hecks/behaviors/ir.rb

@@ -0,0 +1,31 @@
+# Hecks::Behaviors::{TestSetup,TestCase,BehaviorsSuite}
+#
+# The `.behaviors` authoring surface's own IR — plain Structs, holding
+# exactly what `Hecks.behaviors "Name" do ... end` collected. Deliberately
+# NOT part of `Hecks::IR`/`emits_ir` — a behaviors suite is never
+# collected into a domain Registry (see `Hecks.behaviors`), never
+# dispatched through MetaValidator, and carries none of the self-hosted
+# round-trip machinery a real bluebook construct does. It is a test
+# artifact a runner reads on demand, not a domain a boot needs.
+module Hecks
+  module Behaviors
+    TestSetup = Struct.new(:command, :args, keyword_init: true)
+
+    TestCase = Struct.new(:description, :tests_command, :on_aggregate, :kind,
+                          :setups, :input, :expect, keyword_init: true) do
+      # An already-dotted tests_command is a literal FQN; otherwise `on:`
+      # composes with the domain name resolved once setups/the tested
+      # dispatch actually run (see Expectations — the domain isn't known
+      # until `loads` is booted, so it's a runtime concern, not a field
+      # here).
+      def dotted? = tests_command.to_s.include?(".")
+
+      def query? = kind == :query
+    end
+
+    # `loads` — absolute paths, already resolved against the `.behaviors`
+    # file's own directory by the DSL (`BehaviorsBuilder#loads`). `path` is
+    # the `.behaviors` file itself, kept for error messages.
+    BehaviorsSuite = Struct.new(:name, :vision, :loads, :tests, :path, keyword_init: true)
+  end
+end

data/lib/hecks/behaviors/rspec.rb

@@ -0,0 +1,42 @@
+require_relative "../behaviors"
+
+# Hecks::Behaviors::RSpec.describe_file(path) — the shim a consumer's
+# `bundle exec rspec` uses to run `.behaviors` files as ordinary examples,
+# one `it` per test, named by the test's own description string. Same
+# shape `spec/guides_spec.rb` uses for doctested guides: the file is
+# PARSED at collection time (cheap — `Behaviors.parse`, no test actually
+# run yet, just enough to know the `it` names), and each test's own
+# `Expectations.run_one` runs lazily inside its own `it`, exactly when
+# rspec actually executes it.
+#
+#   require "hecks/behaviors/rspec"
+#
+#   Dir.glob("bluebook/**/*.behaviors").each do |path|
+#     Hecks::Behaviors::RSpec.describe_file(path)
+#   end
+module Hecks
+  module Behaviors
+    module RSpec
+      module_function
+
+      def describe_file(path)
+        parsed = Behaviors.parse(path)
+
+        ::RSpec.describe(File.basename(path)) do
+          if parsed.parse_error
+            it "loads without a parse error" do
+              raise parsed.parse_error
+            end
+          else
+            parsed.suite.tests.each do |test|
+              it(test.description) do
+                run = Expectations.run_one(test, parsed.suite)
+                raise run.message if run.status != :pass
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/hecks/behaviors/runner.rb

@@ -0,0 +1,96 @@
+require_relative "expectations"
+
+# Hecks::Behaviors.run(path) / .run_all(dir)
+#
+# Discovery + aggregation. `run_one` (expectations.rb) is the impure edge
+# that actually touches a live runtime; this file finds `.behaviors`
+# files, loads them, and maps their tests through it.
+module Hecks
+  module Behaviors
+    FileResult = Struct.new(:path, :parse_error, :runs, keyword_init: true)
+    SweepResult = Struct.new(:root, :files_swept, :files, :summary, keyword_init: true)
+    ParseResult = Struct.new(:path, :suite, :parse_error, keyword_init: true)
+
+    class LoadOutsideRunner < StandardError; end
+
+    class << self
+      # The `.behaviors` file currently being `Kernel.load`ed, if any —
+      # bound only for the duration of that load (`run`'s own `ensure`),
+      # never left set. `Hecks.behaviors` (lib/hecks/behaviors.rb)
+      # reads this to resolve its own `loads` line relative to the right
+      # file, and to refuse a `.behaviors` file loaded any other way.
+      attr_accessor :loading_path
+
+      # The suite the most recent `Hecks.behaviors` call built — read
+      # once, right after `Kernel.load`, by `run` below, which resets it
+      # to nil before every load so a file that loads without calling
+      # `Hecks.behaviors` at all is never confused for a stale previous
+      # suite (a real bug in a prior port of this idea: compared only
+      # against nil, so after the first successful file in a sweep it
+      # stayed non-nil forever).
+      attr_accessor :last_suite
+
+      # `Kernel.load`s one `.behaviors` file and returns its suite, with
+      # NO test actually executed yet — the cheap half, split out so a
+      # caller that only needs to know what tests exist (the rspec shim,
+      # naming its `it`s at collection time) doesn't pay for running them
+      # until it actually wants to. `Behaviors.loading_path` is bound only
+      # for the duration of the load, and `last_suite` is reset to nil
+      # BEFORE it — a file that loads without ever calling
+      # `Hecks.behaviors` is unambiguously a parse error, never a stale
+      # suite from whatever loaded before it in a sweep (a real bug in a
+      # prior port of this idea: compared only against nil, so after the
+      # first successful file in a sweep it stayed non-nil forever).
+      def parse(path)
+        path = File.expand_path(path)
+        previous_path = loading_path
+        self.loading_path = path
+        self.last_suite = nil
+
+        begin
+          Kernel.load(path)
+        rescue StandardError, ScriptError => e
+          return ParseResult.new(path: path, suite: nil, parse_error: "#{e.class}: #{e.message}")
+        ensure
+          self.loading_path = previous_path
+        end
+
+        suite = last_suite
+        return ParseResult.new(path: path, suite: nil, parse_error: "file loaded but called no Hecks.behaviors") unless suite
+
+        ParseResult.new(path: path, suite: suite, parse_error: nil)
+      end
+
+      # One `.behaviors` file → `FileResult`, every test actually run.
+      def run(path)
+        parsed = parse(path)
+        return FileResult.new(path: parsed.path, parse_error: parsed.parse_error, runs: []) if parsed.parse_error
+
+        runs = parsed.suite.tests.map { |test| Expectations.run_one(test, parsed.suite) }
+        FileResult.new(path: parsed.path, parse_error: nil, runs: runs)
+      end
+
+      # Sweeps every `.behaviors` file under `dir`. Reports the file count
+      # it actually found — a sweep that goes green without saying how
+      # much it looked at is indistinguishable from one that found
+      # nothing to look at.
+      def run_all(dir)
+        files = Dir.glob(File.join(dir, "**", "*.behaviors"))
+        results = files.map { |path| run(path) }
+        SweepResult.new(root: dir, files_swept: files.size, files: results, summary: summarize(results))
+      end
+
+      def summarize(results)
+        runs = results.flat_map(&:runs)
+        {
+          files:        results.size,
+          parse_errors: results.count(&:parse_error),
+          total:        runs.size,
+          passed:       runs.count { |r| r.status == :pass },
+          failed:       runs.count { |r| r.status == :fail },
+          errored:      runs.count { |r| r.status == :error }
+        }
+      end
+    end
+  end
+end

data/lib/hecks/behaviors.rb

@@ -0,0 +1,25 @@
+require_relative "behaviors/dsl"
+require_relative "behaviors/expectations"
+require_relative "behaviors/runner"
+
+# The `.behaviors` toolkit `bin/behaviors` and a consumer's own rspec shim
+# (`hecks/behaviors/rspec`) drive. Not required by lib/hecks.rb on
+# purpose — a booted domain never needs it, the same reason `Fuzzing` (see
+# lib/hecks/fuzzing.rb, the shape this file mirrors) is opt-in too.
+module Hecks
+  class << self
+    # `Hecks.behaviors "Name" do ... end` — deliberately NOT routed
+    # through `collect` the way `bluebook`/`hecksagon`/`world` are: a
+    # behaviors suite is a test artifact a runner reads on demand, never
+    # a thing a live domain boot needs, so it has no business landing in
+    # `Runtime.current_registry`.
+    def behaviors(name, &)
+      path = Behaviors.loading_path or
+        raise Behaviors::LoadOutsideRunner,
+              "Hecks.behaviors called outside Hecks::Behaviors.run(path) — " \
+              "a .behaviors file is only ever loaded by the behaviors runner"
+
+      Behaviors.last_suite = Behaviors::BehaviorsBuilder.build(name, source_path: path, &)
+    end
+  end
+end

data/lib/hecks/bluebook/aggregate.rb

@@ -0,0 +1,108 @@
+require_relative "behaviour/aggregate"
+
+module Hecks
+  module Bluebook
+    # A FIELD READ THROUGH A `reference_to`, HELD LOCALLY (S12, ADR 0025
+    # — "Consistency across aggregate boundaries") — `projects
+    # :customer_status, from: :"customer.status"` declares that this
+    # aggregate's own `:customer_status` is a COPY of the target's own
+    # `:status`, kept fresh by a rebuild sweep rather than read live at
+    # rule-evaluation time. `reference` names the LOCAL reference
+    # attribute to walk through (`:customer`, minted by this
+    # aggregate's own `reference_to Customer`); `remote_field` names
+    # the SCALAR on the target aggregate to copy.
+    ProjectedField = Struct.new(:name, :reference, :remote_field, keyword_init: true)
+
+    # A construct like every other: the aggregate carries its own identity
+    # and sits in the owner chain between its chapter (a Bluebook) and
+    # everything declared on it. The chain is model objects end to end —
+    # reference resolution and hecks_fqn both walk it.
+    #
+    # THE HOLDING HALF, and nothing else. Every line below restates what
+    # `language/bluebook/aggregate.bluebook` already declares — the field
+    # list, said again as readers, again as constructor keywords, and
+    # again as an emission. That triplication is what a generator removes;
+    # `Behaviour::Aggregate` carries everything that is NOT derivable from
+    # the declaration, so regenerating this file can never be lossy.
+    #
+    # PROTOTYPE: hand-written in the shape a generator would emit, to
+    # prove the seam before the generator exists. `bin/project_model`
+    # would own this file; behaviour/aggregate.rb stays hand-written.
+    class Aggregate
+      include Construct
+      include Hecks::IR
+      include Behaviour::Aggregate
+
+      emits_ir(
+        name:             :name,
+        description:      :description,
+        identified_by:    :identity_paths,
+        attributes:       many(:attributes),
+        value_objects:    many(:value_objects),
+        commands:         many(:commands),
+        invariants:       -> { invariants.map { |rule| { description: rule.description, canonical: rule.canonical } } },
+        # A PRECONDITION SHARED ACROSS COMMANDS, DECLARED ONCE (S10, ADR
+        # 0025) — the aggregate's OWN named `given`s, the declaration a
+        # referencing command's own (already-resolved) `givens` entry
+        # came from. Both sides of "declared once, referenced many"
+        # are real IR, the same shape a value object's TYPE and an
+        # attribute's own reference to it both are.
+        preconditions:    -> { preconditions.map { |rule| { description: rule.description, canonical: rule.canonical } } },
+        # S12, ADR 0025 — deliberately NOT folded into `attributes`:
+        # `EraGuard::ShapeDiff` only ever walks `attributes` to decide
+        # whether a NEW field leaves an existing record with something
+        # genuinely absent, and a projected field's own absence story
+        # is different — a record predating the `projects` declaration
+        # is expected to be missing it until the rebuild sweep runs,
+        # not a shape drift a translation needs to explain.
+        projected_fields: -> {
+          projected_fields.map { |field|
+            { name: field.name.to_s, reference: field.reference.to_s, remote_field: field.remote_field.to_s }
+          }
+        },
+        lifecycle:        one(:lifecycle),
+        entities:         many(:entities),
+        queries:          many(:queries),
+        # ADDITIVE — every domain that declares no port emits `ports: []`,
+        # the same "regenerate deliberately" wire-format change
+        # ir_golden_spec.rb's own header describes; no existing key
+        # moves. See docs/decisions (rust/project/ports.rb) for the
+        # first reader of this.
+        ports:            many(:ports),
+        provenance:       :provenance
+      )
+
+      attr_reader :name, :description, :attributes, :value_objects, :commands, :invariants, :preconditions,
+                  :projected_fields, :identified_by, :identity_paths, :identity_heads, :lifecycle,
+                  :entities, :queries, :policies, :ports, :reference_targets, :provenance
+
+      # Assigns what the language declares, then hands off to the
+      # behaviour's own `settle` — derived identity, name indexes and
+      # owner stamping, none of which the declaration states.
+      def initialize(name:, description: nil, attributes: [], value_objects: [],
+                     commands: [], invariants: [], preconditions: [], projected_fields: [], identified_by: [], lifecycle: nil,
+                     entities: [], queries: [], policies: [], ports: [], reference_targets: [],
+                     provenance: nil)
+        @name              = name.to_s
+        @hecks_name        = @name
+        @description       = description
+        @attributes        = attributes
+        @value_objects     = value_objects
+        @commands          = commands
+        @invariants        = invariants
+        @preconditions     = preconditions
+        @projected_fields  = projected_fields
+        @identified_by     = identified_by
+        @lifecycle         = lifecycle
+        @entities          = entities
+        @queries           = queries
+        @policies          = policies
+        @ports             = ports
+        @reference_targets = reference_targets
+        @provenance        = provenance
+
+        settle
+      end
+    end
+  end
+end