hecks 1.0.0 → 1.0.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9d056aad218f4fe26394319c5ce486211ac9790022de8159ba23f050a634f5df
-  data.tar.gz: d6fa0c2f693152be740b0c5f658008a6ba71ae9bd80e175e8da78b142f00f133
+  metadata.gz: 82b36c04d3c930c3f3193aeb23d208c170ab95507dfbac4842b8dae59168a732
+  data.tar.gz: 1cac5931a30cf658980cc65cf8c31a90b36deae5460a9ed6846902d51faa4630
 SHA512:
-  metadata.gz: 4ae526f5a34b194a9b3d23751fae0bb6bdee1bcd8011653904d2b324bf4478ee7b4049d96f0b2a74d005a810ac7023d6efa5a8d0639fb079ed8691da93a5f217
-  data.tar.gz: c2b1a7be12ebfbd52ad5cb13ddd1aa7693a7d903d1402c580baad40414a7f3318d7263379658debc502492986956f97b5377681ac93cf5cb36e058c3e1ccfb46
+  metadata.gz: a90f3c1372ac1a9d3755fe3fbc83a9036cea933a9b63f9517bd52e1010c397c6e2dacd21c6a5030b1fdebbca4bb339c1cc651923b20c1bd9aa1160161ccd7d23
+  data.tar.gz: 6d1069bd54229fddc5befad9ff9afb727fba894816895acc59fcfec20000c765e0444cdd0fd23dc9a37a5a3478c209a0005c836f5351483fbadbfbebb7742566

data/lib/hecks/adapters/driven/sql_query_builder.rb

@@ -204,7 +204,7 @@ module Hecks
 
         object = @aggregate.value_object(attribute.type)
         return "" unless object
-        return object.attributes.first.name.to_s if object.attributes.size == 1
+        return object.sole_attribute.name.to_s if object.sole_attribute
 
         raise ArgumentError,
               "#{dialect_name} query adapter cannot compile contains on #{field} — " \

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

@@ -17,13 +17,19 @@ module Hecks
 
         # 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.
+        # group — [[feedback_name_the_scalar_field]]. `adapters/driven/
+        # sql_query_builder.rb` and `fuzzing/invalid_value_generator.rb`
+        # now read through this rather than inlining the check.
+        #
+        # `forms/field_shape.rb`'s own two `attributes.first.name` sites
+        # (`closed_set_options`/`closed_set_field`) look identical but are
+        # NOT the same question — they pick a closed set's DISCRIMINANT
+        # column, and a closed set can be genuinely multi-attribute
+        # (`Runtime::Value::Admission#member_matches?`'s own comment
+        # names a real one: `StatementFrequency`'s `cadence`/
+        # `retention_months`/`paper_fee_cents`). `sole_attribute` would
+        # return `nil` for that shape and break the discriminant lookup —
+        # left as `.first` on purpose, not a missed migration.
         def sole_attribute
           attributes.first if attributes.size == 1
         end

data/lib/hecks/bluebook/dsl/command_builder.rb

@@ -554,6 +554,59 @@ module Hecks
             end
             refuse_unknown_state_sources!(mutation)
           end
+          # A SECOND, SEPARATE pass — not folded into the loop above — so
+          # every mutation's own self-referential import (resolve_bare_set!)
+          # has already landed before any mutation's SOURCE is checked
+          # against the final `attributes` list. `sets :a, to: :b` declared
+          # before `sets :b` (bare, importing :b from the owner) is real
+          # and legal; checking inline, mutation by mutation, would refuse
+          # it for an ordering accident this language has never required
+          # authors to avoid. rubocop's Style/CombinableLoops can't see
+          # that dependency — it only sees two `@mutations.each` calls
+          # back to back — so it's disabled here, not satisfied.
+          # rubocop:disable-next Style/CombinableLoops
+          @mutations.each { |mutation| refuse_unknown_argument_sources!(mutation) }
+        end
+
+        # THE ONES `resolve_source` (CommandRules::Arithmetic) ONLY EVER
+        # READS FROM `args` — never a fallback to the record's own current
+        # state the way `append`'s own per-field resolution legitimately
+        # can (`MutationApplier#resolve_append_source`'s own `instance
+        # [source]` fallback, a real, intentional second meaning this
+        # check must not foreclose). For exactly these five ops, a bare
+        # Symbol source has exactly one legitimate reading — the name of
+        # a declared argument — so anything else is unreachable at
+        # runtime, not merely optional: no caller can ever supply a value
+        # under a name the command never declared (ArgumentGate's own
+        # `refuse_unknown_arguments` already refuses that), so the source
+        # resolves to nil FOREVER, indistinguishable from a legitimately
+        # absent OPTIONAL argument until this check existed to tell them
+        # apart. Mirrors `AggregateBuilder#seal_query_argument`'s
+        # identical shape for a query's own where-clause argument —
+        # same mistake, one construct over.
+        CHECKED_SYMBOL_SOURCE_OPS = %i[set increment decrement multiply remove].freeze
+        private_constant :CHECKED_SYMBOL_SOURCE_OPS
+
+        def refuse_unknown_argument_sources!(mutation)
+          return unless CHECKED_SYMBOL_SOURCE_OPS.include?(mutation.op)
+          return unless mutation.source.is_a?(Symbol)
+          # The bare self-referential shape (`sets :field` alone, `source
+          # == target`) is `resolve_bare_set!`'s own territory, not this
+          # check's — when neither the command nor the owner declares
+          # that name, the MORE SPECIFIC, pre-existing refusal one level
+          # up (`AggregateBuilder#seal_mutation_targets`, checking the
+          # mutation's TARGET against the aggregate's own fields) is the
+          # one that should fire, naming the field as a target problem,
+          # not — confusingly — as a source problem this check would
+          # otherwise misreport it as.
+          return if mutation.source.to_s == mutation.target.to_s
+          return if attributes.any? { |attr| attr.name == mutation.source }
+
+          raise Malformed,
+                "#{@name}'s sets :#{mutation.target} resolves :#{mutation.source} from its " \
+                "arguments, but #{@name} declares no #{mutation.source} attribute — an " \
+                "argument that does not exist resolves to nil, always, never what the " \
+                "caller actually sent"
         end
 
         # `state(:name)` names one of the OWNER'S OWN fields — a snapshot

data/lib/hecks/bluebook/dsl/domain_port_builder.rb

@@ -7,10 +7,28 @@ module Hecks
 
         include WordGate
 
-        def initialize(name, owner: nil)
-          @name       = name
-          @owner      = owner
-          @operations = []
+        # `legacy_bare_port:` — ONLY `Hecks.port`'s own top-level method
+        # (lib/hecks.rb) passes `true`. `PortBuilder#build` never refused
+        # an empty build (no verb, no signal, nothing) — `Port.new(verb:
+        # nil, signal: :reply)` is a real, allowed shape dsl_spec.rb's own
+        # "a port" tests rely on (`signal`-only, no `verb` at all). The
+        # AGGREGATE-scoped (`BindingProxy#port`) and hecksagon-ROOT
+        # (`HecksagonBuilder#port_impl`) callers both reach this SAME
+        # class with `owner: nil` too when they're building the bare-verb
+        # shape (`port_impl`'s own root-level port can be EITHER shape,
+        # decided only after `build` returns) — so `owner.nil?` cannot be
+        # the discriminator between "old Hecks.port semantics" and "real
+        # DomainPort semantics"; those two callers correctly want the
+        # stricter "declares no verb and no operations" refusal `build`
+        # already raises below, unchanged. Only the literal top-level
+        # `.port` file caller wants the older, looser rule.
+        def initialize(name, owner: nil, legacy_bare_port: false)
+          @name             = name
+          @owner            = owner
+          @operations       = []
+          @signal           = :reply
+          @answers          = []
+          @legacy_bare_port = legacy_bare_port
         end
 
         # WHAT THE OUTSIDE TELLS US — an external fact arriving, translated
@@ -58,18 +76,42 @@ module Hecks
         # coerce-and-assign with nothing else, now executed by
         # `GenericDispatch`.
 
+        # `Hecks.port "x" do verb "y"; signal :effect end`'s own two words,
+        # reachable here too — a bare-verb `DomainPortBuilder.build` falls
+        # back to the SAME `Port` object `PortBuilder` produces (`build`,
+        # below), so any `.port` file can migrate to being parsed by this
+        # builder with zero change to its own text, or to any caller that
+        # reads `.verb`/`.signal` off the `Port` it gets back. Ordinary
+        # `def`s, exactly like `PortBuilder`'s own — `WordGate`'s own
+        # header is explicit that a word answered this way never reaches
+        # its `method_missing`, so no new self-hosted grammar row is
+        # needed for either word under this context.
+        def verb(value)   = @verb = value.to_s
+        def signal(value) = @signal = value.to_sym
+
+        # THE METHOD CONTRACT — `PortBuilder#answers`'s own twin, added
+        # here after the fact: a `.port` file migrated to parse through
+        # this builder (the repoint `lib/hecks.rb#port`'s own comment
+        # describes) can still declare one (`extraction.port`'s own
+        # `answers :canonical`, real, live corpus text) — this builder's
+        # bare-verb fallback needs to carry it through to the same `Port`
+        # object `PortBuilder` itself would have built, or the migration
+        # would silently drop a method-contract check for any `.port`
+        # file that uses this word.
+        def answers(name) = @answers << name.to_sym
+
         def build
           raise Malformed, "#{@name} declares both a verb and operations — a port is one or the other, not both" if @verb && !@operations.empty?
 
-          return Port.new(name: @name, verb: @verb, signal: :reply) if @verb
+          return MetaValidator.call_port(Port.new(name: @name, verb: @verb, signal: @signal, answers: @answers)) if @verb || (@legacy_bare_port && @operations.empty?)
 
           raise Malformed, "#{@name} declares no verb and no operations" if @operations.empty?
 
           DomainPort.new(name: @name, operations: @operations)
         end
 
-        def self.build(name, owner: nil, &block)
-          builder = new(name, owner: owner)
+        def self.build(name, owner: nil, legacy_bare_port: false, &block)
+          builder = new(name, owner: owner, legacy_bare_port: legacy_bare_port)
           builder.instance_eval(&block) if block
           builder.build
         end

data/lib/hecks/bluebook/expression/ast_json.rb

@@ -0,0 +1,149 @@
+require_relative "evaluator"
+require_relative "resolver"
+
+module Hecks
+  module Bluebook
+    module Expression
+      # ── AST → JSON — walks the REAL Evaluator/Resolver AST (the same
+      # objects a live dispatch parses `given`/`ensures`/invariant text
+      # into — see docs/implemented/guides/running-a-runtime.md's "The
+      # expression grammar") and emits plain, JSON-serializable Ruby
+      # Hashes, tagged by `"op"`.
+      #
+      # THE SAME TWO-METHOD WALK `rust/project/expr_emitter.rb`'s own
+      # `emit_bool`/`emit_resolver` already do, over the SAME AST — that
+      # file's own methods build RUST SOURCE-CODE STRINGS for `rust/
+      # project`'s codegen (`rust/src/kernel::expr::Expr` literals, baked
+      # into a generated domain's own compiled binary); this builds DATA
+      # instead, for a genuinely different consumer with a genuinely
+      # different constraint: `rust/host` can never link the `rust`
+      # (kernel) crate at all (a real, load-bearing build constraint —
+      # `reference_validate.rs`'s own header has the full reasoning: one
+      # path dependency would statically bake every domain's generated
+      # dispatch code into every Lambda binary), so a value object's own
+      # `invariant` predicate has to travel as something `rust/host` can
+      # deserialize and interpret itself, at RUNTIME, from `ir.json` — the
+      # exact same relationship `rust/project`'s own `Expr` literals
+      # already have to the compiled kernel, one layer further out.
+      #
+      # LIVES IN CORE `lib/hecks`, NOT `rust/project/` — `rust/project.rb`
+      # is a separate, downstream toolchain
+      # (`lib/hecks/projector.rb`'s own header: "a whole separate Ruby
+      # program"), never `require`d by core `lib/hecks/bluebook/*.rb`
+      # files (confirmed: no core file does). `value_object.rb`'s own
+      # `invariants:` IR emission needs this for EVERY domain's ordinary
+      # `to_h`/`ir.json` export — golden fixtures, `hecks-parse`'s parity
+      # comparisons, and any deploy artifact, not only a `bin/project_rust`
+      # run — so it belongs beside `Evaluator`/`Resolver` themselves, not
+      # bolted onto a tool that only sometimes runs.
+      #
+      # COMPLETE, not corpus-scoped: every node this grammar admits gets
+      # a real arm, the identical "raise, don't silently drop" discipline
+      # `expr_emitter.rb`'s own `emit_bool`/`emit_resolver` already hold
+      # to — even though, as of this writing, no real corpus VALUE OBJECT
+      # invariant exercises `Include`/`Modulo`/`BlockPredicate`/`Find`/
+      # `Array`/`MatchesRegex`/`Presence`/`Split`/`StartsWith`/`EndsWith`/
+      # `First`/`Last` (only `given`/`ensures` clauses do, elsewhere in
+      # the corpus — a different consumer of this same grammar).
+      # `rust/host/src/expr_json.rs`'s own header names exactly which of
+      # these its interpreter evaluates for real today versus refuses
+      # cleanly — a narrower, deliberate, documented boundary on the
+      # INTERPRETING side, not on this EMITTING side: an author is free
+      # to write ANY real expression in a value object's own `invariant`,
+      # and this always emits it faithfully; whether `rust/host` can yet
+      # CHECK it at mint time is that file's own question to answer, not
+      # this one's to pre-empt by refusing to even try.
+      module AstJson
+        module_function
+
+        def emit_predicate(canonical)
+          emit_bool(Evaluator.parse(canonical))
+        end
+
+        def emit_bool(node)
+          case node
+          when Evaluator::Or  then { "op" => "or", "left" => emit_bool(node.left), "right" => emit_bool(node.right) }
+          when Evaluator::And then { "op" => "and", "left" => emit_bool(node.left), "right" => emit_bool(node.right) }
+          when Evaluator::Not then { "op" => "not", "expr" => emit_bool(node.node) }
+          when Evaluator::Compare
+            { "op" => "compare", "cmp" => emit_comparison(node.operator),
+              "left" => emit_resolver(node.left), "right" => emit_resolver(node.right) }
+          when Evaluator::Include
+            emit_include(node)
+          when Evaluator::Resolve
+            emit_resolver(node.expr)
+          else
+            raise "unhandled evaluator node #{node.class} — no JSON rendering exists for it (lib/hecks/bluebook/expression/ast_json.rb#emit_bool)"
+          end
+        end
+
+        def emit_comparison(op)
+          { "less_than" => op.compares_less_than, "equal" => op.compares_equal, "negated" => op.negated }
+        end
+
+        # The JSON-target sibling of `expr_emitter.rb`'s own
+        # `emit_include` — see that method's own comment for the full
+        # reasoning (a LITERAL array haystack has no `Expr::Include`-
+        # representable shape on EITHER target, kernel or host, so both
+        # rewrite it identically into an OR-of-equalities at emission
+        # time rather than carrying a shape neither interpreter could
+        # evaluate). A non-literal haystack still emits `include`
+        # unchanged.
+        EQ = Evaluator::OPERATORS.find { |op| op.symbol == "==" }
+        private_constant :EQ
+
+        def emit_include(node)
+          return { "op" => "include", "haystack" => emit_resolver(node.haystack), "needle" => emit_resolver(node.needle) } \
+            unless node.haystack.is_a?(Resolver::ArrayLiteral)
+
+          return { "op" => "bool", "value" => false } if node.haystack.elements.empty?
+
+          equalities = node.haystack.elements.map do |element|
+            { "op" => "compare", "cmp" => emit_comparison(EQ), "left" => emit_resolver(node.needle), "right" => emit_resolver(element) }
+          end
+          equalities.reduce { |left, right| { "op" => "or", "left" => left, "right" => right } }
+        end
+
+        def emit_resolver(node)
+          case node
+          when Resolver::IntegerLiteral then { "op" => "int", "value" => node.value }
+          when Resolver::FloatLiteral   then { "op" => "float", "value" => node.value }
+          when Resolver::StringLiteral  then { "op" => "str", "value" => node.value }
+          when Resolver::BoolLiteral    then { "op" => "bool", "value" => node.value }
+          when Resolver::NilLiteral     then { "op" => "nil" }
+          when Resolver::Lookup         then { "op" => "lookup", "path" => node.path }
+          when Resolver::Addition       then { "op" => "add", "left" => emit_resolver(node.left), "right" => emit_resolver(node.right) }
+          when Resolver::SignTest
+            { "op" => "sign_test", "cmp" => emit_comparison(node.operator), "receiver" => emit_resolver(node.receiver) }
+          when Resolver::Empty  then { "op" => "empty", "receiver" => emit_resolver(node.receiver) }
+          when Resolver::ToS    then { "op" => "to_s", "receiver" => emit_resolver(node.receiver) }
+          when Resolver::Modulo then { "op" => "modulo", "receiver" => emit_resolver(node.receiver), "divisor" => emit_resolver(node.divisor) }
+          when Resolver::Size   then { "op" => "size", "receiver" => emit_resolver(node.receiver) }
+          when Resolver::BlockPredicate
+            { "op" => "block_predicate", "mode" => node.mode.to_s, "receiver" => emit_resolver(node.receiver),
+              "param" => node.param.to_s, "predicate" => emit_bool(node.predicate) }
+          when Resolver::Find
+            { "op" => "find", "receiver" => emit_resolver(node.receiver), "param" => node.param.to_s,
+              "predicate" => emit_bool(node.predicate), "path" => node.path.map(&:to_s) }
+          when Resolver::ArrayLiteral
+            { "op" => "array", "elements" => node.elements.map { |element| emit_resolver(element) } }
+          when Resolver::MatchesRegex
+            { "op" => "matches_regex", "receiver" => emit_resolver(node.receiver), "pattern" => node.pattern, "flags" => node.flags }
+          when Resolver::Presence
+            { "op" => "presence", "receiver" => emit_resolver(node.receiver), "negated" => node.negated }
+          when Resolver::Split
+            { "op" => "split", "receiver" => emit_resolver(node.receiver), "separator" => node.separator }
+          when Resolver::StartsWith
+            { "op" => "starts_with", "receiver" => emit_resolver(node.receiver), "substring" => node.substring }
+          when Resolver::EndsWith
+            { "op" => "ends_with", "receiver" => emit_resolver(node.receiver), "substring" => node.substring }
+          when Resolver::First then { "op" => "first", "receiver" => emit_resolver(node.receiver) }
+          when Resolver::Last  then { "op" => "last", "receiver" => emit_resolver(node.receiver) }
+          else
+            raise "unhandled resolver node #{node.class} — no JSON rendering exists for it (lib/hecks/bluebook/expression/ast_json.rb#emit_resolver)"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/hecks/bluebook/expression.rb

@@ -11,3 +11,4 @@ end
 require_relative "expression/canonical_form"
 require_relative "expression/resolver"
 require_relative "expression/evaluator"
+require_relative "expression/ast_json"

data/lib/hecks/bluebook/model_check.rb

@@ -184,7 +184,21 @@ module Hecks
       # forever, since nothing about *entering* it via default implies
       # anything must eventually move it, unlike a state a transition
       # explicitly delivered somewhere.
-      def terminal_exempt(_lifecycle) = []
+      #
+      # Scoped to `default` alone, and only when the lifecycle actually
+      # declares real transitions elsewhere: an EMPTY lifecycle (no
+      # transitions at all) doesn't get this exemption — that's not "a
+      # machine whose entry point deliberately awaits external action,"
+      # it's much more likely a lifecycle nobody finished wiring, and
+      # should still warn (see spec/fixtures/model_check/lifecycle_
+      # findings.bluebook's own Widget::Part, which stays warned on
+      # purpose).
+      def terminal_exempt(lifecycle)
+        return [] if lifecycle.transitions.empty?
+
+        outgoing_sources = lifecycle.transitions.flat_map { |_, t| Array(t.from) }.to_set
+        outgoing_sources.include?(lifecycle.default) ? [] : [lifecycle.default]
+      end
 
       # ── process managers / sagas ──────────────────────────────────────
 

data/lib/hecks/bluebook/project_register.rb

@@ -16,6 +16,7 @@ module Hecks
 
       def initialize
         @entries = {}
+        @tenant_directories = Hash.new { |hash, key| hash[key] = [] }
       end
 
       def fetch(address) = entries.fetch(address.to_s)
@@ -25,6 +26,7 @@ module Hecks
 
       def register(bluebooks, registry, dispatcher, directory)
         bluebooks.each do |bluebook|
+          refuse_unless_safe_for_second_tenant!(bluebook, registry, directory)
           world = registry.world(bluebook.name)
           realm = world&.realm
           raise MissingRealm, "#{bluebook.name} in #{directory} has no world realm" if realm.to_s.empty?
@@ -62,6 +64,29 @@ module Hecks
 
       private
 
+      # THE ACTUAL "more than one tenant" MOMENT — Runtime::TenantCheck's
+      # own header names this table as the one place real multitenancy
+      # happens: the SAME on-disk directory (one domain, one
+      # `persisted_by` binding) registering a SECOND time, under a
+      # different realm, into this SAME shared route table. A directory's
+      # FIRST registration is never refused here — nothing shares its
+      # data yet, so a plain single-tenant deployment on an ordinary
+      # adapter (Postgres, no schema story) still boots exactly as
+      # before. Only the SECOND (and any later) registration of that
+      # same directory is refused, and refused before this call adds its
+      # routes to the table — so a leaking tenant's requests never
+      # become reachable through `Router#resolve` in the first place.
+      #
+      # Keyed on `directory` + `bluebook.name` only, not realm or
+      # `dispatcher` — two tenants share the identical on-disk domain,
+      # differing only by which realm/environment overlay booted it.
+      def refuse_unless_safe_for_second_tenant!(bluebook, registry, directory)
+        key = [directory, bluebook.name]
+        seen_before = @tenant_directories.key?(key) && @tenant_directories[key].any?
+        Runtime::TenantCheck.refuse_unless_tenant_capable!(registry, bluebook.name) if seen_before
+        @tenant_directories[key] << registry
+      end
+
       def current?(bluebook, world)
         bluebook.version.nil? || world.latest == bluebook.version
       end

data/lib/hecks/bluebook/value_object.rb

@@ -1,4 +1,5 @@
 require_relative "behaviour/value_object"
+require_relative "expression/ast_json"
 
 module Hecks
   module Bluebook
@@ -28,7 +29,15 @@ module Hecks
       emits_ir(
         name:       :hecks_name,
         attributes: many(:attributes),
-        invariants: -> { invariants.map { |rule| { description: rule.description, canonical: rule.canonical } } },
+        # `ast:` — a JSON-serializable rendering of the SAME predicate
+        # `canonical` already spells as text, alongside it rather than
+        # replacing it (`canonical` stays the human-facing/doctest-facing
+        # form; parsing it back would just re-derive what `ast` already
+        # states directly). Ground truth and the full reasoning:
+        # `Expression::AstJson`'s own header — built for `rust/host`'s
+        # own mint-time invariant check (`reference_validate.rs`), which
+        # has no kernel crate to parse `canonical` with.
+        invariants: -> { invariants.map { |rule| { description: rule.description, canonical: rule.canonical, ast: Expression::AstJson.emit_predicate(rule.canonical) } } },
         closed_set: :closed_set?,
         # THE FIELD NAME IS STRINGIFIED, NEVER THE VALUE. A `member` row can
         # hold any of the scalar types an attribute declares — `Integer 84`

data/lib/hecks/fuzzing/invalid_value_generator.rb

@@ -67,11 +67,12 @@ module Hecks
       # scalar cannot stand for anything and the refusal has to say so.
       def scalar_for(attribute, aggregate, random:)
         value_object = aggregate.value_object(attribute.type.to_s)
-        return "a bare scalar" unless value_object && value_object.attributes.size == 1
+        sole = value_object&.sole_attribute
+        return "a bare scalar" unless sole
 
         # One field, so a scalar is legal — corrupt the FIELD's own type instead,
         # which is still a shape the attribute cannot accept.
-        { value_object.attributes.first.name.to_s => ["nested", "array"] }
+        { sole.name.to_s => ["nested", "array"] }
       end
 
       # An attribute the command never declared. `refuse_unknown_arguments` is a

data/lib/hecks/language/hecksagon/domain_port.bluebook

@@ -4,7 +4,9 @@ Hecks.bluebook "Hecksagon" do
 
     identified_by PortName, as: :name
 
-    attribute :verb, PortVerb, optional: true
+    attribute :verb,    PortVerb, optional: true
+    attribute :signal,  PortSignal, optional: true
+    attribute :answers, list_of(PortAnswer)
 
     value_object "PortName" do
       attribute :value, String
@@ -16,6 +18,24 @@ Hecks.bluebook "Hecksagon" do
       invariant("a verb is named") { !value.to_s.empty? }
     end
 
+    # SAME CLOSED SET port.bluebook's own "Port" aggregate declares —
+    # kept as its own local value object rather than shared cross-
+    # chapter, the same way PortVerb already is here.
+    value_object "PortSignal" do
+      attribute :value, String, one_of: ["reply", "effect"]
+    end
+
+    # `answers` — DomainPortBuilder's own twin of PortBuilder#answers
+    # (port.bluebook's "Port" aggregate, same shape), added once a real
+    # `.port` file migrated to parse through this builder (the repoint
+    # `lib/hecks.rb#port`'s own comment describes) used the word
+    # (`extraction.port`'s own `answers :canonical`). Local, not shared
+    # cross-chapter, same reasoning as PortSignal just above.
+    value_object "PortAnswer" do
+      attribute :value, String
+      invariant("an answer names a real method") { !value.to_s.empty? }
+    end
+
     # HOW DOMAINPORT IS SPELLED. These rows live with the concept
     # they describe; SyntaxBoot discovers every aggregate-local seed table.
     # Contexts represented here: DomainPort.
@@ -35,6 +55,8 @@ Hecks.bluebook "Hecksagon" do
       member word: "tells",           context: "DomainPort",    body: "keywords", inner: "PortOperation", opens: "PortOperation", fills: "", calls: "tells_impl"
       member word: "asks",            context: "DomainPort",    body: "keywords", inner: "PortOperation", opens: "PortOperation", fills: "", calls: "asks_impl"
       member word: "verb",            context: "DomainPort",    body: "none",     inner: "",              opens: "",              fills: "verb"
+      member word: "signal",          context: "DomainPort",    body: "none",     inner: "",              opens: "",              fills: "signal"
+      member word: "answers",         context: "DomainPort",    body: "none",     inner: "",              opens: "",              fills: "answers"
 
     end
 
@@ -59,6 +81,8 @@ Hecks.bluebook "Hecksagon" do
       member keyword: "tells",           context: "DomainPort", at: "1", named: "", kind: "text", required: "true", fills: "name"
       member keyword: "asks",            context: "DomainPort", at: "1", named: "", kind: "text", required: "true", fills: "name"
       member keyword: "verb",            context: "DomainPort", at: "1", named: "", kind: "text", required: "true", fills: "verb"
+      member keyword: "signal",          context: "DomainPort", at: "1", named: "", kind: "symbol", required: "true", fills: "signal"
+      member keyword: "answers",         context: "DomainPort", at: "1", named: "", kind: "symbol", required: "true", fills: "answers"
 
       # THE RECEIVING AGGREGATE — PortOperationBuilder's own `reference_to`
       # (inside the block) is refused (#335); this is the sanctioned

data/lib/hecks/runtime/command_interpreter.rb

@@ -48,7 +48,7 @@ module Hecks
       # that sets them runs, same as they were unset locals before that point.
       Context = Struct.new(:domain, :aggregate, :command, :args, :repository, :instance, :transition, :old_state,
                            :result, :correlation, :route, :plan, :strategy, :persistence_outcome, :delegated_events,
-                           :dry_run)
+                           :dry_run, :correction_bindings)
 
       def initialize(registry, rules:)
         @registry = registry
@@ -135,10 +135,13 @@ module Hecks
           # NotFound/AlreadyExists already get at hydration: "does the
           # fact this command's corrects names even exist" is not a
           # domain rule an author wrote, it is a precondition for the
-          # domain rules to mean anything at all.
-          @rules.enforce_correction_target(ctx.instance, ctx.aggregate, ctx.command, domain: ctx.domain)
+          # domain rules to mean anything at all. Also locates the
+          # correction target itself, if `as:` named one — carried on
+          # `ctx` so `step_enforce_ensures` (the settled-record half)
+          # can bind the SAME name too, not just this pre-mutation half.
+          ctx.correction_bindings = @rules.enforce_correction_target(ctx.instance, ctx.aggregate, ctx.command, domain: ctx.domain)
           @rules.enforce_givens(ctx.instance, ctx.command, ctx.args, domain: ctx.domain,
-                                declaring: ctx.aggregate, parent: ctx.instance)
+                                declaring: ctx.aggregate, parent: ctx.instance, correction: ctx.correction_bindings)
         }
       end
 
@@ -239,7 +242,7 @@ module Hecks
       def step_enforce_ensures(ctx)
         step(:enforce_ensures) {
           @rules.enforce_ensures(ctx.instance, ctx.command, ctx.args, old: ctx.old_state,
-                                 domain: ctx.domain, parent: ctx.instance)
+                                 domain: ctx.domain, parent: ctx.instance, correction: ctx.correction_bindings || {})
         }
       end
 
@@ -260,7 +263,7 @@ module Hecks
           seed_projected_fields(ctx)
           ctx.persistence_outcome = if ctx.strategy == DependencyPlanning::ATOMIC_PUT
                                       # A SECOND CREATION IS NOT A FRESH ONE — see
-                                      # hydrate_legacy_creation's own comment; the
+                                      # hydrate_complete_state's own comment; the
                                       # same refusal, on the same terms, for the
                                       # complete-state path. `insert_only:` asks the
                                       # ADAPTER to decide and refuse ATOMICALLY
@@ -376,19 +379,61 @@ module Hecks
         found.dup
       end
 
-      # Transitional compatibility for live source that has not yet acquired
-      # explicit effects. It is deliberately isolated from the normal routing
-      # and planning path so `reference_to` no longer chooses how a migrated
-      # command hydrates or persists. Wave 8 removes this after the inventory is
-      # empty; frozen eras retain their own shadow parser.
+      # WAVE 8 (equivalence-gap plan, item 1.6) — NOT done, and this
+      # comment now says precisely how far it got, corrected from an
+      # EARLIER version of itself that briefly (same PR, never released)
+      # claimed the inventory was empty and deleted this method outright.
+      # A full corpus audit (`DependencyPlanning::Analyzer.call` against
+      # every `creates?`-true command in all 5 EXAMPLE domains — banking,
+      # pizzas, chess, compliance, roster) found and fixed 4 real
+      # authoring bugs (`Statement.Generate`, `CreatePizza`, `Chess::
+      # Game.Start`, `Roster.Open` — each declared an attribute and
+      # never `sets` it, so the field silently stayed nil on every
+      # created record regardless of what a caller sent), plus a real
+      # `DependencyPlanning::Analyzer` bug for ENTITY-owned commands
+      # (`root_aggregate:`, that class's own header) that surfaced one
+      # more live corpus bug of its own (`payment_cards.bluebook`'s own
+      # `Withdrawal.Dispute`, which never actually checked whether the
+      # card was retired) — all real, all kept.
       #
-      # `ctx.plan.complete_state?` already claimed every command whose plan is
-      # fully resolved in the two branches above `step_hydrate` tries first, so
-      # reaching this check already means the plan is incomplete — an
-      # un-migrated command still routes here on `creates?` alone, the same as
-      # the old `hydrate` did, regardless of whether it happens to have any
-      # mutations (`write_set`). Requiring an EMPTY write_set here refused
-      # every un-migrated creating command that sets even one field.
+      # DELETING THIS METHOD ON THAT BASIS TURNED OUT TO BE WRONG,
+      # caught by running the full suite rather than trusting the
+      # audit's own scope: the 5 example domains are nowhere near the
+      # WHOLE inventory of `creates?`-true commands this fallback
+      # actually carries. Dozens of separate, purpose-built spec
+      # fixtures across the suite (`spec/fixtures/*.bluebook`, and
+      # inline `Hecks.bluebook` blocks declared directly inside
+      # individual spec files — governance, mutation ops, ports,
+      # routing, tenant isolation, sagas, and more) declare their OWN
+      # small `creates?`-true commands the same incomplete way, and
+      # rely on this exact fallback to create anything at all. Deleting
+      # it produced 218 failures across specs with nothing to do with
+      # Wave 8's own subject — confirmed, not guessed, by actually
+      # running `bundle exec rspec` after the deletion, not merely by
+      # extrapolating from the one audited inventory. `spec/fixtures/
+      # till.bluebook`'s own `Till.OpenTill` (missing `sets :number`,
+      # the identical bug shape as the 4 fixed above) was fixed
+      # alongside the four real corpus ones as one instance of this — but
+      # it was one of many, not the last one, and finding the rest is
+      # real, separate, much larger follow-up work this pass does not
+      # attempt: a suite-wide audit of every declared bluebook fixture,
+      # not just the 5 example domains the plan's own text named.
+      #
+      # Transitional compatibility for live source that has not yet
+      # acquired explicit effects, same as it always was — deliberately
+      # isolated from the normal routing and planning path so
+      # `reference_to` no longer chooses how a migrated command hydrates
+      # or persists. A real, future Wave 8 removes this once THAT wider
+      # inventory is empty, not before.
+      #
+      # `ctx.plan.complete_state?` already claimed every command whose
+      # plan is fully resolved in the two branches above `step_hydrate`
+      # tries first, so reaching this check already means the plan is
+      # incomplete — an un-migrated command still routes here on
+      # `creates?` alone, the same as the old `hydrate` did, regardless
+      # of whether it happens to have any mutations (`write_set`).
+      # Requiring an EMPTY write_set here refused every un-migrated
+      # creating command that sets even one field.
       def legacy_implicit_creation?(ctx)
         ctx.route.nil? && ctx.command.creates?
       end
@@ -421,9 +466,11 @@ module Hecks
                                                    aggregate: aggregate.hecks_name,
                                                    identity:  identity_reading(aggregate)))
 
-        # A SECOND CREATION IS NOT A FRESH ONE — see hydrate_legacy_creation's
-        # own comment; the same refusal, on the same terms, for the
-        # complete-state path. ONLY when `strategy` will NOT be ATOMIC_PUT:
+        # A SECOND CREATION IS NOT A FRESH ONE — `creates?` on an identity
+        # a record already exists under refuses (`AlreadyExists`) rather
+        # than silently overwriting it, the same refusal `hydrate_prior_
+        # or_initial`'s own body gives for its own complete-but-state-
+        # dependent case, below. ONLY when `strategy` will NOT be ATOMIC_PUT:
         # an atomic-put-capable adapter enforces this itself, atomically,
         # via `insert_only:` in step_save (no read here, no race with the
         # write) — but `strategy_for` already fell back to a plain `save`
@@ -461,8 +508,8 @@ module Hecks
                                                    identity:  identity_reading(aggregate)))
         found = repository.find(id)
 
-        # A SECOND CREATION IS NOT A FRESH ONE — see hydrate_legacy_
-        # creation's own comment; the same refusal, on the same terms, for
+        # A SECOND CREATION IS NOT A FRESH ONE — see hydrate_complete_
+        # state's own comment; the same refusal, on the same terms, for
         # a complete-but-state-dependent command (one with a `given`
         # reading its own prior state, which is what routes here instead
         # of hydrate_complete_state). Gated on `command.creates?`: a

data/lib/hecks/runtime/command_rules/admissibility.rb

@@ -116,7 +116,13 @@ module Hecks
         # parent aggregate reaching ITS OWN customer) resolves the same
         # way `account.customer.status` does for a command-level reference.
         # nil for an aggregate command — CommandInterpreter never passes it.
-        def enforce_givens(subject, command, args, domain:, declaring: nil, parent: nil)
+        # `correction:` — the `{as_name => payload}` bindings
+        # `enforce_correction_target` (above) already located, merged in
+        # LAST so an `as:` name wins the same way `old:` always wins in
+        # `enforce_ensures`, below — it is a fresh local binding a
+        # `corrects` command introduces, not a real argument/state field
+        # a caller could collide with by accident.
+        def enforce_givens(subject, command, args, domain:, declaring: nil, parent: nil, correction: {})
           state = GuardState.new(subject)
           # A RULE MAY ONLY READ WITHIN ITS OWN AGGREGATE BOUNDARY (S12,
           # ADR 0025) — `subject`'s own STORED references are no longer
@@ -135,6 +141,7 @@ module Hecks
           # forbids.
           attrs = args.merge(dereference(domain, command, args))
           attrs = attrs.merge(parent: parent.state) if parent
+          attrs = attrs.merge(correction) unless correction.empty?
           command.givens.each do |given|
             next if Bluebook::Expression::Evaluator.call(given.canonical, state, attrs)
 
@@ -154,20 +161,43 @@ module Hecks
         # event at all — is `AggregateBuilder#seal_correction_targets`;
         # this is the dispatch-time half — has THIS record actually done
         # so yet.
+        #
+        # ALSO LOCATES the matched event now, not just its existence, and
+        # returns a `{as_name => payload}` bindings hash — one entry per
+        # `:corrects` mutation that named an `as:` — so `given`/`ensures`
+        # on a corrects-bearing command can reference the located OLD
+        # event by that name, the same shape `enforce_ensures`'s own
+        # `old:` binding already has (CommandBuilder#corrects_impl's own
+        # comment: `as:` was stored, from the start, specifically to be
+        # wired into the evaluator once a real runtime consumer existed —
+        # this is that consumer). `.reverse.find` — the MOST RECENT
+        # matching event, if this record has somehow emitted the same
+        # correction target more than once; the prior existence-only
+        # check never had to make this choice, so it's a genuinely new
+        # one, made deliberately: `as:` reads as "the instance being
+        # corrected," which is naturally the latest fact on record, not
+        # an arbitrary one.
         def enforce_correction_target(instance, aggregate, command, domain:)
+          bindings = {}
           command.mutations.each do |mutation|
             next unless mutation.op == :corrects
 
             event_key  = "#{domain}::#{aggregate.hecks_name}"
             event_name = mutation.target.to_s
-            next if @registry.event_log.any? do |event|
+            corrected = @registry.event_log.reverse.find do |event|
               event.name == event_name && event.aggregate == event_key && event.id == instance.id
             end
 
-            raise NothingToCorrect,
-                  "#{command.hecks_name} refused — corrects #{event_name}, but " \
-                  "#{event_key} ##{instance.id} has never emitted it"
+            unless corrected
+              raise NothingToCorrect,
+                    "#{command.hecks_name} refused — corrects #{event_name}, but " \
+                    "#{event_key} ##{instance.id} has never emitted it"
+            end
+
+            as = mutation.source[:as]
+            bindings[as.to_sym] = corrected.payload if as && !as.to_s.empty?
           end
+          bindings
         end
 
         # LIFECYCLE STATE AS A COMMAND GUARD (S10, ADR 0025) — `command
@@ -215,16 +245,21 @@ module Hecks
         # Not new to ensures — `given` lives under the same rule — but an
         # ensures is more likely to collide, since it typically re-reads a
         # field the command just took in to mutate it.
-        def enforce_ensures(subject, command, args, old:, domain:, parent: nil)
+        def enforce_ensures(subject, command, args, old:, domain:, parent: nil, correction: {})
           state = GuardState.new(subject)
           # S12, ADR 0025 — same boundary reasoning as enforce_givens
           # above: `subject`'s own stored references are no longer
           # dereferenced here; a `projects`-maintained field is already
           # part of `state`. `command`/`args` still dereferences — a
           # fresh reference-typed ARGUMENT stays in bounds.
-          # `old` still wins over everything, unchanged.
+          # `old` still wins over everything, unchanged. `correction`
+          # (an `as:`-bound corrected event, if this command declares
+          # one) wins right alongside it — a settled-record ensures can
+          # reference the correction target exactly as freely as a
+          # pre-mutation given already can.
           attrs = args.merge(dereference(domain, command, args))
           attrs = attrs.merge(parent: parent.state) if parent
+          attrs = attrs.merge(correction) unless correction.empty?
           attrs = attrs.merge(old: old)
           command.ensures.each do |rule|
             next if Bluebook::Expression::Evaluator.call(rule.canonical, state, attrs)

data/lib/hecks/runtime/command_rules/arithmetic.rb

@@ -68,9 +68,39 @@ module Hecks
         # made. The real mistake, an absent argument, was never the one refused,
         # which is what fuzz surfaced.
         #
-        # Absent now resolves to nil. Whether it should be REFUSED instead
-        # is a separate question — the language cannot yet say which arguments are
-        # optional, and the meta-domain has plenty that are.
+        # STALE (as of the equivalence-gap plan's own audit): this used to
+        # say "the language cannot yet say which arguments are optional" —
+        # it already can, and always could once `attribute ..., optional:
+        # true` existed (`CommandBuilder#attribute_impl`,
+        # `attribute_collector.rb`): `sets` already sources correctly from
+        # an optional attribute, resolving absent to nil exactly as this
+        # method does, and REFUSING it here would be wrong, not merely
+        # undone work — `TillRoom::Till.TakeIn`'s own `note` (spec/
+        # fixtures/till.bluebook) and Banking's `CardPayment.Authorize`'s
+        # `tags` (payment_cards.bluebook) are real, live commands whose
+        # `sets` mutation is deliberately sourced from an optional
+        # attribute the caller may omit — `spec/runtime/command_rules_spec
+        # .rb`'s own "says an absent OPTIONAL argument is nil, not the
+        # name of the argument" pins exactly this as correct, not pending.
+        # The meta-domain's own self-hosted commands (Command.Declare's
+        # `role`/`goal`/`provenance`/`from`/`position`, and ~35 more sites
+        # across the language) all lean on the identical pattern — nil is
+        # the RIGHT answer for a `sets` sourced from a declared-optional
+        # attribute the caller left out, every time.
+        #
+        # The one thing that WAS still a real, narrow gap — a `sets`
+        # source Symbol naming NOTHING the command declares at all (a
+        # typo, not an optional argument) — silently resolved to nil
+        # forever the same way, indistinguishable at either build or run
+        # time from a legitimate optional absence. Closed at BUILD time
+        # instead of here: `CommandBuilder#refuse_unknown_argument_sources!`
+        # refuses it the moment the `.bluebook` file loads, mirroring
+        # `AggregateBuilder#seal_query_argument`'s identical check for a
+        # query's own where-clause argument. This function stays exactly
+        # what it always was — a pure, unconditional lookup — because by
+        # the time ANY mutation reaches it, the source has already been
+        # proven to name either a real, possibly-optional argument, or a
+        # StateRef/literal; there is nothing left here to refuse.
         def resolve_source(source, args)
           return args[source] if source.is_a?(Symbol)
 

data/lib/hecks/runtime/dependency_planning.rb

@@ -62,13 +62,29 @@ module Hecks
       class Analyzer
         STATEFUL_MUTATIONS = %i[append increment decrement multiply clamp remove].freeze
 
-        def self.call(aggregate:, command:) = new(aggregate, command).call
-
-        def initialize(aggregate, command)
+        # `root_aggregate:` — Wave 8's own audit surfaced a real bug here,
+        # not merely a missing feature: for an ENTITY-owned command,
+        # `EntityInterpreter` calls this with `aggregate:` set to the
+        # ENTITY itself (`element_interpreter.rb`'s own `Analyzer.call
+        # (aggregate: entity, command:)`), so `owner_fields` was always
+        # the entity's own attribute set. A `given`/`ensures` reading
+        # `parent.X` legitimately means the ROOT aggregate's own field —
+        # a genuinely different owner — but `classify_path`'s `:parent`
+        # branch checked that read against `owner_fields` (the entity's),
+        # which can never contain a root-level field, so every entity
+        # command with a real, legitimate `parent.*` read was refused as
+        # unresolved regardless of correctness. Defaults to `aggregate`
+        # (a no-op) for the plain-aggregate case — `CommandInterpreter`'s
+        # own call site never needed to change.
+        def self.call(aggregate:, command:, root_aggregate: aggregate) = new(aggregate, command, root_aggregate).call
+
+        def initialize(aggregate, command, root_aggregate = aggregate)
           @aggregate = aggregate
           @command = command
           @owner_fields = aggregate.attributes.to_set(&:name)
           @owner_fields << aggregate.lifecycle.field.to_sym if aggregate.lifecycle
+          @root_owner_fields = root_aggregate.attributes.to_set(&:name)
+          @root_owner_fields << root_aggregate.lifecycle.field.to_sym if root_aggregate.lifecycle
           # `projects` FIELDS (S12, ADR 0025) ARE OWNER STATE TOO — a
           # `given`/`ensures` reading one (e.g. `customer_status ==
           # "active"`) is reading this record's own stored field, same
@@ -80,9 +96,17 @@ module Hecks
           # a partial mutation, which is exactly right — a projected
           # field's freshness comes from the interpreter reseeding it on
           # save, not from anything a caller-supplied write set carries.
+          # Applies to BOTH `owner_fields` and `root_owner_fields` — an
+          # entity's own `parent.*` read can name the root aggregate's
+          # projected field just as easily as one of its real attributes
+          # (`Banking::Withdrawal.Dispute`'s own `parent.account_customer_
+          # status`, ATMCard's projected field, is a real, live example).
           if aggregate.respond_to?(:projected_fields)
             aggregate.projected_fields.each { |field| @owner_fields << field.name }
           end
+          if root_aggregate.respond_to?(:projected_fields)
+            root_aggregate.projected_fields.each { |field| @root_owner_fields << field.name }
+          end
           @payload_fields = command.attributes.to_set(&:name)
           @state_reads = Set.new
           @payload_reads = Set.new
@@ -115,7 +139,7 @@ module Hecks
 
         private
 
-        attr_reader :aggregate, :command, :owner_fields, :payload_fields,
+        attr_reader :aggregate, :command, :owner_fields, :root_owner_fields, :payload_fields,
                     :state_reads, :payload_reads, :writes, :known_writes, :unresolved
 
         # A fresh Instance supplies these values without reading a stored
@@ -204,13 +228,36 @@ module Hecks
           end
         end
 
+        # KNOWN, HARMLESS GAP: `corrects ..., as: :name`'s bound name
+        # (admissibility.rb's `enforce_correction_target`/`enforce_givens`/
+        # `enforce_ensures`) isn't special-cased here the way `:old`/
+        # `:parent` are — a given/ensures referencing it falls through to
+        # `unresolved` below (its own field lookup finds no owner/payload
+        # match), same net effect as any other not-yet-optimized command:
+        # `complete_state?` comes back false, so dispatch takes the safe
+        # `hydrate_existing` path instead of the `ATOMIC_PUT` fast path.
+        # Not a correctness bug — `as:`'s runtime binding (a plain `attrs`
+        # merge, exactly like `old:`'s) resolves and evaluates correctly
+        # regardless of what this STATIC analysis concludes — just a real,
+        # deliberately-left optimization gap: closing it would mean
+        # threading "which names this command declares as correction
+        # bindings" into the Analyzer, which doesn't have that per-command
+        # context today. Worth doing alongside `:old`/`:parent`'s own
+        # handling someday, not attempted here.
         def classify_path(path, phase)
           head, nested = path.split(".", 2)
           name = head.to_sym
 
           if name == :parent
             parent_field = nested.to_s.split(".", 2).first
-            if parent_field.empty? || !owner_fields.include?(parent_field.to_sym)
+            # `root_owner_fields` — NOT `owner_fields`. For an entity-owned
+            # command `owner_fields` is the ENTITY's own attribute set;
+            # `parent.X` always means the ROOT aggregate's own field, a
+            # genuinely different owner (`root_aggregate:`'s own header,
+            # above, has the full bug this fixes). Identical for a plain
+            # aggregate command, where root_aggregate defaults to aggregate
+            # itself and the two sets are the same set.
+            if parent_field.empty? || !root_owner_fields.include?(parent_field.to_sym)
               unresolved << "#{path} does not name parent aggregate state"
             else
               state_reads << parent_field.to_sym

data/lib/hecks/runtime/entity_interpreter.rb

@@ -98,7 +98,14 @@ module Hecks
           ctx.chain = chain
           ctx.route = route
           ctx.dry_run = dry_run
-          ctx.plan = DependencyPlanning::Analyzer.call(aggregate: entity, command: command)
+          # `root_aggregate:` — `entity` is the immediate owner (what
+          # `owner_fields` inside the Analyzer means), but a `parent.X`
+          # read inside this command's own given/ensures means the ROOT
+          # aggregate's own field, not the entity's — `aggregate` here IS
+          # that root (this method's own first parameter, never the
+          # entity). See DependencyPlanning::Analyzer.call's own header
+          # for the bug this closes.
+          ctx.plan = DependencyPlanning::Analyzer.call(aggregate: entity, command: command, root_aggregate: aggregate)
           # RESOLVED HERE, ONCE — see CommandInterpreter#call's own comment;
           # `step_hydrate_parent` reads `ctx.repository` without re-fetching.
           ctx.repository = @registry.repository(domain, aggregate)

data/lib/hecks/runtime/read_model_interpreter.rb

@@ -73,10 +73,19 @@ module Hecks
                    [fetch(bluebook, domain, head[:aggregate], reference_id)]
                  elsif rootless
                    # No root to FK-match against — a rootless model reads
-                   # each of its own heads WHOLE, independently. (Multiple
-                   # heads on one rootless model aren't cross-joined
-                   # against each other either — each is its own bulk
-                   # read. A real, deliberate scope limit for now.)
+                   # each of its own heads WHOLE, independently. Multiple
+                   # heads on one rootless model are NEVER cross-joined
+                   # against each other, and there is no DSL to declare
+                   # one if you wanted to — `ReadModelBuilder#include_impl`
+                   # takes only `type`/`as:` (checked directly, not
+                   # assumed), and `group_by` groups this bulk read's own
+                   # output, it names no predicate between two heads.
+                   # Building a cross-join here would mean CHOOSING a join
+                   # semantics (equality on which fields?) nobody has
+                   # declared — a real, deliberate scope limit pending a
+                   # future `include ..., joins: ...`-shaped grammar
+                   # addition (with its own Rust mirror), not a gap this
+                   # interpreter can quietly grow into on its own.
                    records(bluebook, domain, head[:aggregate])
                  else
                    matching(records(bluebook, domain, head[:aggregate])) do |record|

data/lib/hecks/version.rb

@@ -12,5 +12,5 @@ module Hecks
   # it there, or even in the consuming Gemfile, never closed the gap,
   # because gemspec evaluation happens before anything Bundler
   # resolves is actually loadable yet.
-  VERSION = "1.0.0"
+  VERSION = "1.0.1"
 end

data/lib/hecks.rb

@@ -100,7 +100,27 @@ module Hecks
     end
 
     def hecksagon(name, &block) = collect(:add_hecksagon, Bluebook::DSL::HecksagonBuilder.build(name, &block))
-    def port(name, &block) = collect(:add_port, Bluebook::DSL::PortBuilder.build(name, &block))
+    # REPOINTED TO DomainPortBuilder — the migration DomainPort's own
+    # class comment names as its goal, now landed for the top-level
+    # `.port` file callers too (the aggregate-scoped `Thing.port(...)`,
+    # binding_proxy.rb, already went through this builder). Every real
+    # `.port` file only ever spells `verb`/`signal` (no `.port` file
+    # declares operations — that's DomainPort's own newer shape), and
+    # DomainPortBuilder's own bare-verb branch produces the exact same
+    # `Port` object PortBuilder itself did (dsl_spec.rb's own byte-
+    # identity check) — a pure repoint, no behavior change for any
+    # existing caller reading `.verb`/`.signal` off what comes back.
+    #
+    # `legacy_bare_port: true` — the ONE real semantic gap this repoint
+    # would otherwise open: `PortBuilder#build` never refused a
+    # completely empty build (no verb, no signal even), a real shape
+    # dsl_spec.rb's own "a port" tests exercise (`signal`-only, no
+    # `verb`). `DomainPortBuilder`'s own "declares no verb and no
+    # operations" refusal is real and correct for its OTHER two callers
+    # (`BindingProxy#port`, `HecksagonBuilder#port_impl`) — only this,
+    # the literal top-level `.port` file entry point, keeps the older,
+    # looser rule (see `DomainPortBuilder#initialize`'s own comment).
+    def port(name, &block) = collect(:add_port, Bluebook::DSL::DomainPortBuilder.build(name, legacy_bare_port: true, &block))
     def adapter(name, &block)   = collect(:add_adapter, Bluebook::DSL::AdapterBuilder.build(name, &block))
     def world(name, &block)     = collect(:add_world, Bluebook::DSL::WorldBuilder.build(name, &block))
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: hecks
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.0.1
 platform: ruby
 authors:
 - Chris Young
@@ -140,6 +140,7 @@ files:
 - lib/hecks/bluebook/dsl/world_builder.rb
 - lib/hecks/bluebook/entity.rb
 - lib/hecks/bluebook/expression.rb
+- lib/hecks/bluebook/expression/ast_json.rb
 - lib/hecks/bluebook/expression/canonical_form.rb
 - lib/hecks/bluebook/expression/evaluator.rb
 - lib/hecks/bluebook/expression/projection.json