hecks 0.3.0 → 1.0.0

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

@@ -10,7 +10,8 @@ module Hecks
         include RuleReference
         include WordGate
 
-        def initialize(name, chapter_named_givens: {}, chapter_pending_givens: [])
+        def initialize(name, chapter_named_givens: {}, chapter_pending_givens: [],
+                       chapter_entity_named_givens: {}, chapter_entity_pending_givens: [])
           @name          = name
           @value_objects = []
           @commands      = []
@@ -37,6 +38,15 @@ module Hecks
           # here and `BluebookBuilder#resolve_pending_chapter_givens!`
           # for where it drains.
           @chapter_pending_givens = chapter_pending_givens
+          # ONE LEVEL WIDER STILL, PAST THE CHAPTER'S OWN AGGREGATE-LEVEL
+          # POOL — the chapter's own entity-scoped pool, threaded from
+          # `BluebookBuilder#aggregate_impl` the same way
+          # `@chapter_named_givens` is, and passed straight through
+          # (unchanged) to every top-level piece this aggregate builds
+          # (`#drain_pending!`). See `EntityBuilder#given_impl`'s own
+          # comment for what this closes.
+          @chapter_entity_named_givens   = chapter_entity_named_givens
+          @chapter_entity_pending_givens = chapter_entity_pending_givens
           # DEFERRED CONSTRUCTION — `entity`/`command`/`query` push a
           # pending descriptor here instead of building immediately; see
           # `#drain_pending!`'s own comment for why.
@@ -419,6 +429,7 @@ module Hecks
           seal_defaults
           seal_lifecycle_guards
           seal_projected_fields
+          seal_correction_targets
 
           ir = Aggregate.new(
             name:              @name,
@@ -445,8 +456,11 @@ module Hecks
           ir
         end
 
-        def self.build(name, chapter_named_givens: {}, chapter_pending_givens: [], &block)
-          builder = new(name, chapter_named_givens: chapter_named_givens, chapter_pending_givens: chapter_pending_givens)
+        def self.build(name, chapter_named_givens: {}, chapter_pending_givens: [],
+                       chapter_entity_named_givens: {}, chapter_entity_pending_givens: [], &block)
+          builder = new(name, chapter_named_givens: chapter_named_givens, chapter_pending_givens: chapter_pending_givens,
+                              chapter_entity_named_givens: chapter_entity_named_givens,
+                              chapter_entity_pending_givens: chapter_entity_pending_givens)
           builder.instance_eval(&block) if block
           builder.build
         end
@@ -496,6 +510,9 @@ module Hecks
                                       owner_named_givens:              @entity_named_givens,
                                       identity_name_prefix:            "#{Naming.demodulise(@name)}#{Naming.demodulise(name)}",
                                       identity_value_object_installer: ->(value_object) { @value_objects << value_object },
+                                      aggregate_name:                  @name,
+                                      chapter_entity_named_givens:     @chapter_entity_named_givens,
+                                      chapter_entity_pending_givens:   @chapter_entity_pending_givens,
                                 &block)
           end
 
@@ -609,7 +626,17 @@ module Hecks
         # keys: a default that is a Hash is left to `Value.for_attribute`, which
         # is where a wrong FIELD belongs.
         def seal_defaults
-          shapes = @value_objects.map { |shape| shape.hecks_name.to_s }
+          # `closed_sets` TOO, not only `@value_objects` — the exact gap
+          # this method's own comment names: an inline `one_of(...)`
+          # synthesises its value object through `closed_sets`
+          # (AttributeCollector#synthesise_closed_set), never installed
+          # into `@value_objects` until `#build` merges them (see
+          # `#build`'s own `@value_objects + closed_sets`, and
+          # `declared_value_object`'s identical merge). Checking
+          # `@value_objects` alone made this exact attribute — a bare
+          # default on an inline closed set — invisible to the one
+          # check meant to catch it.
+          shapes = (@value_objects + closed_sets).map { |shape| shape.hecks_name.to_s }
 
           attributes.each do |attribute|
             next if attribute.default.nil? || attribute.default.is_a?(Hash)
@@ -683,7 +710,10 @@ module Hecks
               # #step_delegate_to_entity`, which refuses a real one that
               # names no such entity or command). Sealing THIS check
               # against it would refuse every delegating command outright.
-              next if mutation.op == :delegate
+              # `:corrects` — CommandBuilder#corrects_impl's own comment —
+              # targets an EVENT name, not a field either; checked instead
+              # by `seal_correction_targets`, below.
+              next if [:delegate, :corrects].include?(mutation.op)
               next if known.include?(mutation.target.to_sym)
 
               raise Malformed,
@@ -694,6 +724,88 @@ module Hecks
           end
         end
 
+        # `corrects` — CommandBuilder#corrects_impl's own comment. Runs
+        # once every command in the aggregate is known (the same reason
+        # this is a `seal_*` step rather than living in `corrects_impl`
+        # itself — a command cannot see its own siblings' `emits` while
+        # it is still being built). Two things are checked:
+        #
+        # 1. The named event must be something a SIBLING command here
+        #    actually `emits` — naming an event nothing in this aggregate
+        #    ever announces is a build-time authoring error. (Whether
+        #    THIS record has actually emitted it YET is the dispatch-time
+        #    half — CommandRules::Admissibility#enforce_correction_target.)
+        #
+        # 2. `reverses: true` derives the corrective `sets` from the
+        #    ORIGINAL command's own mutations, rather than the author
+        #    writing them — but only when every one of those mutations is
+        #    STRUCTURALLY invertible with no runtime data: increment/
+        #    decrement, same argument, opposite verb (`sign_for`'s own
+        #    +1/-1 pair — CommandRules::Arithmetic applies `current +
+        #    sign * amount`, so the SAME source with the OPPOSITE sign
+        #    undoes it exactly). Nothing else qualifies today: `set` has
+        #    no such rule at all — inverting it needs the SPECIFIC prior
+        #    value at the moment the original fired, which is per-
+        #    instance runtime data no build-time derivation can have;
+        #    `multiply`/`clamp` are lossy by design (a clamped value's
+        #    own pre-clamp magnitude is not recoverable from the mutation
+        #    at all); `append`/`remove` LOOK symmetric but are not
+        #    reliably so — `append`'s source is a per-field binding hash
+        #    (`append: { name: :name, amount: :amount }`), `remove`'s is
+        #    a single resolved value to match by equality
+        #    (MutationApplier#removed), and collapsing one shape into the
+        #    other correctly needs the target list's own value-object
+        #    field names, not just the mutation's own recorded shape — a
+        #    real gap, left for a follow-on round rather than guessed at
+        #    here. Refuses rather than silently deriving something wrong
+        #    — see docs/decisions/ for the ADR that draws this exact
+        #    line.
+        def seal_correction_targets
+          inverse_op = { increment: :decrement, decrement: :increment }
+          emitted_by = Hash.new { |hash, key| hash[key] = [] }
+          @commands.each { |command| command.emits.each { |event_name| emitted_by[event_name] << command } }
+
+          @commands.each do |command|
+            correction = command.mutations.find { |mutation| mutation.op == :corrects }
+            next unless correction
+
+            event   = correction.target
+            sources = emitted_by[event]
+            if sources.empty?
+              raise Malformed,
+                    "#{@name}.#{command.hecks_name} corrects #{event.inspect}, but nothing " \
+                    "declared on #{@name} ever emits it — corrects names a fact this " \
+                    "aggregate actually announces, not an aspiration"
+            end
+
+            next unless correction.source[:reverses]
+
+            own_mutations = command.mutations.reject { |mutation| mutation.op == :corrects }
+            if own_mutations.any?
+              raise Malformed,
+                    "#{@name}.#{command.hecks_name} declares both corrects #{event.inspect}, " \
+                    "reverses: true AND its own sets — reverses: true means the correction " \
+                    "is DERIVED; write one or the other, never both"
+            end
+
+            derived     = sources.flat_map(&:mutations).reject { |mutation| mutation.op == :corrects }
+            unsupported = derived.reject { |mutation| inverse_op.key?(mutation.op) }
+            if unsupported.any?
+              raise Malformed,
+                    "#{@name}.#{command.hecks_name} corrects #{event.inspect}, reverses: " \
+                    "true, but the command(s) that emit it use " \
+                    "#{unsupported.map(&:op).uniq.join(', ')} — not statically invertible " \
+                    "(set needs the specific prior value, multiply/clamp are lossy) — " \
+                    "declare the corrective sets by hand instead"
+            end
+
+            derived.each do |mutation|
+              command.mutations << Mutation.new(target: mutation.target, op: inverse_op.fetch(mutation.op),
+                                                source: mutation.source)
+            end
+          end
+        end
+
         # A query must ask about a field the aggregate actually HAS — the same
         # seal `then_set` gets, closing the same silence: a where over a field
         # nothing declares matches nothing and refuses nothing, forever, on

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

@@ -62,6 +62,8 @@ module Hecks
                            admits: nil, one_of: nil)
           # moved to the language: FieldName invariant, on Root.Attribute
 
+          refuse_duplicate_attribute!(name)
+
           if type.equal?(UNSET)
             raise Malformed, "#{name} declares no type — attribute :#{name}, SomeType is required, " \
                              "there is no default"
@@ -156,6 +158,7 @@ module Hecks
         private
 
         def relationship_attribute(target, kind, name, optional: false, list: false)
+          refuse_duplicate_attribute!(name)
           attributes << Attribute.new(
             name:         name,
             type:         Reference.new(target),
@@ -183,6 +186,24 @@ module Hecks
                 "with the type-position one_of(...) instead"
         end
 
+        # A NAME DECLARED TWICE ON THE SAME OWNER IS TWO ATTRIBUTES SHARING
+        # ONE NAME, and nothing downstream disambiguates them — every
+        # reader that walks `attributes` looking for one by name
+        # (`seal_mutation_targets`, `seal_query_field`, `projects`'s own
+        # local check, `Instance#[]`, ...) uses `Array#find`/`any?`, which
+        # silently answers whichever declaration happens to come first and
+        # discards the second. Used to boot clean and stay that way : both
+        # declarations survived into the IR, one of them permanently
+        # unreachable by name. Refused HERE, at the one place every owner
+        # (Aggregate/Entity/Command/Query/PortOperation/ValueObject, each
+        # `include AttributeCollector`) mints an attribute through, rather
+        # than taught to each of those readers individually.
+        def refuse_duplicate_attribute!(name)
+          return unless attributes.any? { |attribute| attribute.name == name }
+
+          raise Malformed, "#{name} is declared twice — an attribute name is declared once, not twice"
+        end
+
         # A pattern is refused AT DECLARATION, not when a value first meets it :
         # a regex whose meaning depends on which engine reads it is a defect in
         # the bluebook, and a bluebook that loads is one whose patterns carry

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

@@ -28,6 +28,13 @@ module Hecks
           # what queues here and `#resolve_pending_chapter_givens!`,
           # below, for where it drains.
           @chapter_pending_givens = []
+          # ONE LEVEL WIDER STILL — the CHAPTER-WIDE, ENTITY-SCOPED pool
+          # (the piece analogue of `@chapter_named_givens`, above). See
+          # `EntityBuilder#given_impl`'s own comment for what this
+          # closes; `docs/implemented/resolution-rules/
+          # chapter-entity-given.md` for the full algorithm.
+          @chapter_entity_named_givens   = {}
+          @chapter_entity_pending_givens = []
         end
 
         # Chapter metadata belongs to the composed folder, not whichever file
@@ -85,8 +92,10 @@ module Hecks
         # chapter's own top-level shape is written with it), so also
         # named in GenericDispatch::BOOTSTRAP_CALLS_FALLBACK.
         def aggregate_impl(name, &block)
-          @aggregates << AggregateBuilder.build(name, chapter_named_givens:   @chapter_named_givens,
-                                                      chapter_pending_givens: @chapter_pending_givens, &block)
+          @aggregates << AggregateBuilder.build(name, chapter_named_givens:          @chapter_named_givens,
+                                                      chapter_pending_givens:        @chapter_pending_givens,
+                                                      chapter_entity_named_givens:   @chapter_entity_named_givens,
+                                                      chapter_entity_pending_givens: @chapter_entity_pending_givens, &block)
         end
 
         # `read_model` is the word (ADR 0025 reverts `report` — the IR
@@ -143,6 +152,7 @@ module Hecks
           # `validate_assembled!` there — nothing downstream should ever
           # read an unresolved placeholder's fields.
           resolve_pending_chapter_givens! unless MetaValidator.deferring?
+          resolve_pending_chapter_entity_givens! unless MetaValidator.deferring?
 
           # A CHAPTER MAY BE SPLIT ACROSS FILES (see `self.build`'s own
           # comment). Every check below needs the WHOLE chapter present —
@@ -225,6 +235,47 @@ module Hecks
         end
         private :resolve_pending_chapter_given
 
+        # THE ENTITY-SCOPED ANALOGUE, one level down — see
+        # `#resolve_pending_chapter_givens!`'s own comment; identical
+        # shape, resolved against `@chapter_entity_named_givens` instead.
+        def resolve_pending_chapter_entity_givens!
+          @chapter_entity_pending_givens.each do |entry|
+            resolved = resolve_pending_chapter_entity_given(entry)
+            entry[:placeholder].description = resolved.description
+            entry[:placeholder].canonical   = resolved.canonical
+            entry[:placeholder].predicate   = resolved.predicate
+          end
+          @chapter_entity_pending_givens.clear
+        end
+
+        def resolve_pending_chapter_entity_given(entry)
+          description = entry[:description]
+          candidates  = RuleReference.resolve_owner_keyed(@chapter_entity_named_givens, description)
+
+          if entry[:declared_by]
+            candidates[entry[:declared_by]] ||
+              raise(Malformed,
+                    "#{entry[:entity]}'s given #{description.inspect} names no precondition " \
+                    "#{entry[:declared_by]} declares in this chapter — #{entry[:declared_by]} " \
+                    "either hasn't declared #{description.inspect}, or declared_by: named the " \
+                    "wrong piece")
+          elsif candidates.size == 1
+            candidates.values.first
+          elsif candidates.empty?
+            raise(Malformed,
+                  "#{entry[:entity]}'s given #{description.inspect} names no precondition " \
+                  "any piece in this chapter ever declares — declare it once with a block " \
+                  "(some piece's own given(#{description.inspect}) { ... })")
+          else
+            raise(Malformed,
+                  "#{entry[:entity]}'s given #{description.inspect} is ambiguous across the " \
+                  "chapter's own pieces — #{candidates.keys.join(', ')} each declare a DIFFERENT " \
+                  "predicate under this same description; name which one with declared_by: (e.g. " \
+                  "given(#{description.inspect}, declared_by: #{candidates.keys.first.inspect}))")
+          end
+        end
+        private :resolve_pending_chapter_entity_given
+
         # EVERY WHOLE-CHAPTER CHECK, IN ONE PLACE — the battery `#build`
         # used to run inline, now a pure function of an assembled
         # `Bluebook::Chapter` so `MetaValidator.judge_deferred!` can run
@@ -862,6 +913,24 @@ module Hecks
           # nothing further to check once it matches by name.
           return if remote_attribute.nil? && target.lifecycle&.field.to_s == plan.tail
 
+          # A PROJECTION MAY CHAIN THROUGH ANOTHER PROJECTION (S12, ADR
+          # 0025's own boundary rule, followed through) — `target`'s
+          # OWN projected fields live in `projected_fields`, a
+          # separate list from `attributes`, so a match there is
+          # invisible to the check above even though it names a real,
+          # always-current, stored field. `Transfer.projects
+          # :source_customer_status, from: :"source.customer_status"`
+          # reads Account's own already-projected `customer_status`
+          # this way — Account is one hop from Customer, Transfer is
+          # one hop from Account, and neither aggregate needs to know
+          # about the other's target two hops away. A projected
+          # field's remote value is always a scalar by construction
+          # (`RebuildSweep.remote_value` never copies a reference, a
+          # value object, or a list), so nothing further to check once
+          # it matches by name — same reasoning the lifecycle
+          # fallback just above already applies.
+          return if remote_attribute.nil? && target.projected_fields.any? { |f| f.name.to_s == plan.tail }
+
           unless remote_attribute
             raise Malformed,
                   "#{aggregate.hecks_name}.projects :#{field.name} reads #{target.hecks_name}'s own " \

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

@@ -297,7 +297,7 @@ module Hecks
           end
 
           op, source = named.first
-          @mutations << Mutation.new(target: target.to_sym, op: op, source: source)
+          @mutations << Mutation.new(target: target.to_sym, op: op, source: normalize_append_source(op, source))
         end
 
         # LEGACY UNDER SHADOW-PARSING (S0a's own bridge) — frozen era text
@@ -319,8 +319,23 @@ module Hecks
         # enforces it. This is the first rule to move ACROSS rather than be
         # duplicated : delete the declaration and an unnamed event is accepted,
         # which is what makes the meta-domain load-bearing rather than decorative.
+        #
+        # BARE CONSTANT ACCEPTED (ADR 0025, S6 — "events first-class"),
+        # `emits Account::AccountFrozen`, resolved through `ConstShim` the
+        # same way `trigger`/`dispatch` already resolve a command
+        # reference (`Naming.event_ref`, that method's own header). NOT
+        # yet a REQUIRED spelling, deliberately, unlike `trigger`/
+        # `dispatch`'s own quoted-text refusal: those were safe to refuse
+        # only because command references are already 100% migrated
+        # across the live corpus (verified 2026-08-27) — `emits`/`on`
+        # are not, so refusing the quoted form here would break every
+        # live `.bluebook` site this pass didn't touch, not just frozen
+        # era text `shadow_parse` exists to keep readable. Both forms
+        # are accepted in live source until a full corpus migration
+        # lands and the same refusal this file's `reference_to`/
+        # `trigger_impl` already carry can be added here safely.
         def emits(event_name)
-          @emits << event_name.to_s
+          @emits << Naming.event_ref(event_name)
         end
 
         # THE RECORD'S OWN VALUE AS A MUTATION SOURCE — `sets :positions,
@@ -412,6 +427,57 @@ module Hecks
           @mutations << Mutation.new(target: target.to_s, op: :delegate, source: with)
         end
 
+        # A COMMAND DECLARING WHAT PAST FACT IT AMENDS — the append-only
+        # answer to "what if this record's history turns out to have been
+        # wrong": never rewrite the original event (the log stays exactly
+        # what it was), always append a NEW fact on top. `event` names the
+        # event this command corrects; `as:` optionally binds the located
+        # instance for a `given`/`ensures` to reference, the same shape
+        # `ensures`'s own `old` binding already has; `reason:` is not
+        # descriptive-only the way `goal` is — it is carried as data, the
+        # one thing an audit trail actually needs ("we corrected this, and
+        # here is why"), refused when blank the same way a `given`'s own
+        # description is required to say something.
+        #
+        # STORED AS A MUTATION, not a new Command field — see the
+        # KeywordSeed row's own comment (command.bluebook) for why: this
+        # is the exact same choice `delegates_to` already made, for the
+        # exact same reason. Rides the SAME multi-binding wire shape
+        # `append`/`delegate` use — `as:`/`reason:`/`reverses:` assembled
+        # by hand into one `source` hash, the way `sets_impl` assembles up
+        # to seven kwargs into one `named` hash above.
+        #
+        # `reverses: true` NAMES an intent to auto-derive the corrective
+        # `sets` from the original event's own mutations, rather than the
+        # author writing it — see `AggregateBuilder#seal_correction_targets`,
+        # where that derivation actually happens (it needs every sibling
+        # command in the aggregate already known, which this builder alone
+        # cannot see). MUTUALLY EXCLUSIVE with an explicit `sets` on the
+        # same command — two ways of saying the same thing is exactly the
+        # redundancy `sets`'s own omittable-`to:` rule refuses elsewhere.
+        #
+        # `as:` IS ALWAYS STORED AS TEXT, never left a bare Symbol —
+        # `Mutation#classified_source`/`#appended_fields` (Behaviour::
+        # Mutation) classify any bare Symbol field as `kind: "argument"`,
+        # meaning "resolve this against one of THIS command's own declared
+        # attributes at dispatch time" (append/delegate's own meaning for a
+        # Symbol). `as:` names no such thing — it is a plain label, not yet
+        # wired into the expression evaluator (a future round's work, once
+        # a real runtime consumer exists) — so coercing it to a String here
+        # keeps it out of that machinery entirely rather than silently
+        # miscategorised as an unresolvable argument reference.
+        def corrects_impl(event, as: nil, reason: nil, reverses: false)
+          if reason.to_s.strip.empty?
+            raise Malformed,
+                  "#{@name}'s corrects #{event.inspect} names no reason — a correction " \
+                  "is carried as data (an audit trail needs to say WHY), the same way a " \
+                  "given's own description must say something"
+          end
+
+          @mutations << Mutation.new(target: event.to_s, op: :corrects,
+                                     source: { as: as&.to_s, reason: reason.to_s, reverses: reverses })
+        end
+
         def build
           resolve_implicit_attributes!
 
@@ -618,7 +684,29 @@ module Hecks
           end
 
           op, source = named.first
-          @mutations << Mutation.new(target: target.to_sym, op: op, source: source)
+          @mutations << Mutation.new(target: target.to_sym, op: op, source: normalize_append_source(op, source))
+        end
+
+        # `append:` NORMALLY binds several fields at once (`append: {
+        # name: :name, amount: :amount }`) — `Mutation#appended_fields`/
+        # `MutationApplier#appended`/the meta-validator Judge's own
+        # `mutation_rows` all read `mutation.source` as a Hash
+        # unconditionally. A BARE value (`append: :single_field`, or any
+        # non-Hash literal) is the one-field shorthand: exactly what an
+        # explicit `append: { value: :single_field }` would have meant,
+        # named the same way a single-field value object's own implicit
+        # member already is (`MutationApplier#appended`'s own `:value`
+        # scalar-unwrap). Without this, that shorthand built a Mutation
+        # whose `source` was a bare Symbol, which crashed with a raw
+        # `NoMethodError` on `#transform_values` the moment anything
+        # downstream read it — at dispatch (`MutationApplier#appended`),
+        # at IR emission (`Mutation#appended_fields`), and in the
+        # meta-validator's own Judge (`Readings#mutation_rows`). #138.
+        def normalize_append_source(op, source)
+          return source unless op == :append
+          return source if source.is_a?(::Hash)
+
+          { value: source }
         end
       end
     end

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

@@ -11,7 +11,8 @@ module Hecks
         include WordGate
 
         def initialize(name, owner_value_objects: [], owner_named_givens: {},
-                       identity_name_prefix: nil, identity_value_object_installer: nil)
+                       identity_name_prefix: nil, identity_value_object_installer: nil,
+                       aggregate_name: nil, chapter_entity_named_givens: {}, chapter_entity_pending_givens: [])
           @name         = name
           @commands     = []
           @queries      = []
@@ -30,6 +31,18 @@ module Hecks
           # reference reads from it via `CommandBuilder#
           # reference_named_given`.
           @owner_named_givens = owner_named_givens
+          # ONE LEVEL WIDER STILL — the CHAPTER-WIDE, ENTITY-SCOPED pool
+          # (the piece analogue of `AggregateBuilder#@chapter_named_givens`,
+          # one level down). `@aggregate_name` names THIS piece's own
+          # root, so the write-through below can key itself
+          # "AggregateName.EntityName" — the same dotted addressing
+          # convention `declared_by:` already uses chapter-wide, one
+          # level up. See `#given_impl`'s own comment for what this
+          # closes and `docs/implemented/resolution-rules/
+          # chapter-entity-given.md` for the full algorithm.
+          @aggregate_name = aggregate_name || Naming.demodulise(name)
+          @chapter_entity_named_givens   = chapter_entity_named_givens
+          @chapter_entity_pending_givens = chapter_entity_pending_givens
           # DEFERRED CONSTRUCTION — see `AggregateBuilder#drain_pending!`'s
           # own comment; the identical mechanism, one level down, so a
           # nested piece's own commands (Dispatch inside Handler) see
@@ -150,7 +163,40 @@ module Hecks
         # magic.
         # RENAMED FROM `given` — item #13's full metaprogrammed dispatch
         # (slice 4b), same reasoning as reference_to_impl above.
-        def given_impl(description, &predicate)
+        #
+        # BARE — NO BLOCK — REFERENCES ANOTHER PIECE'S OWN DECLARATION,
+        # ANYWHERE IN THE CHAPTER, not just a sibling under this same
+        # aggregate — one level wider than round 4's own cross-entity
+        # sharing, mirroring `AggregateBuilder#given_impl`'s own
+        # chapter-wide shape exactly one level down. Real, live corpus
+        # this closes: `Account::LedgerEntry` and `SafeDepositBox::Visit`
+        # — two pieces under two DIFFERENT aggregates — independently
+        # typed `given("customer is active") { parent.customer.status ==
+        # "active" }` byte for byte; neither the aggregate-level chapter
+        # pool (a DIFFERENT canonical — bare `customer.status`, the
+        # wrong scope for a piece's own command) nor the existing
+        # same-aggregate cross-entity pool (`@owner_named_givens`, scoped
+        # to ONE aggregate's own entity tree) could reach across the
+        # aggregate boundary. Resolved against `@chapter_entity_named_
+        # givens`, keyed "AggregateName.EntityName" — see
+        # `#reference_named_chapter_entity_given`'s own comment for the
+        # algorithm and `docs/implemented/resolution-rules/
+        # chapter-entity-given.md` for the full write-up.
+        #
+        # `declared_by:` is a PLAIN STRING ("Account.LedgerEntry"), not a
+        # constant — unlike `AggregateBuilder#given_impl`'s own
+        # `declared_by:`, which names a real aggregate constant. A piece
+        # has no first-class, independently-addressable reference
+        # anywhere in this language (only its owning aggregate does);
+        # inventing one to make this ONE argument spelling symmetrical
+        # with the aggregate-level word is a real, separate, unscoped
+        # feature this fix does not need — ships textual now, the same
+        # way `admits:` shipped textual before its own constant-bridge
+        # existed, revisited only if a genuine, separate need for
+        # constant-addressed pieces shows up later.
+        def given_impl(description, declared_by: nil, &predicate)
+          return reference_named_chapter_entity_given(description, declared_by: declared_by) unless predicate
+
           named = build_rule(Given, description, predicate, owner_name: @name, word: "given",
                               extraction_failure: "its source could not be read, so no other runtime could ever evaluate it")
           @named_givens[description] = named
@@ -163,6 +209,17 @@ module Hecks
           # by coincidence, same as an aggregate-level given already
           # tolerates today).
           @owner_named_givens[description] ||= named
+          # WRITE-THROUGH, PER OWNER — the chapter-wide analogue of the
+          # line above, keyed by [description, this piece's own dotted
+          # "Aggregate.Entity" name] rather than description alone, the
+          # identical reasoning `AggregateBuilder#given_impl`'s own
+          # chapter write-through gives: two DIFFERENT pieces (anywhere
+          # in the chapter) independently declaring the SAME description
+          # are two DISTINCT candidates a later bare reference chooses
+          # between (via `declared_by:` once there is more than one),
+          # never silently merged into one slot.
+          @chapter_entity_named_givens[description] ||= {}
+          @chapter_entity_named_givens[description]["#{@aggregate_name}.#{@name}"] ||= named
         end
 
         # A PIECE'S OWN SHAPE RULE (S10, ADR 0025's own "Rules" shape,
@@ -203,16 +260,81 @@ module Hecks
         end
 
         def self.build(name, owner_value_objects: [], owner_named_givens: {},
-                       identity_name_prefix: nil, identity_value_object_installer: nil, &block)
+                       identity_name_prefix: nil, identity_value_object_installer: nil,
+                       aggregate_name: nil, chapter_entity_named_givens: {}, chapter_entity_pending_givens: [], &block)
           builder = new(name, owner_value_objects: owner_value_objects, owner_named_givens: owner_named_givens,
                               identity_name_prefix: identity_name_prefix,
-                              identity_value_object_installer: identity_value_object_installer)
+                              identity_value_object_installer: identity_value_object_installer,
+                              aggregate_name: aggregate_name,
+                              chapter_entity_named_givens: chapter_entity_named_givens,
+                              chapter_entity_pending_givens: chapter_entity_pending_givens)
           builder.instance_eval(&block) if block
           builder.build
         end
 
         private
 
+        # PRIMITIVE 2 (RuleReference#resolve_owner_keyed) — the CHAPTER-
+        # WIDE, ENTITY-SCOPED analogue of `AggregateBuilder#
+        # reference_named_chapter_given`; the three branches below are
+        # this construct's OWN refusal wording, not shared, matching that
+        # method's own precedent (`declared_by:` only exists on `given`
+        # so far, at either scope). UNRESOLVED is deferred, not raised
+        # here — see `#pending_chapter_entity_given`, below.
+        #
+        # WRITES THROUGH TO `@owner_named_givens` TOO — not just
+        # `@named_givens` — or this piece resolving a description via the
+        # WIDER, chapter pool would leave the NARROWER, same-aggregate
+        # pool (`EntityBuilder#given_impl`'s own block-form write-through)
+        # never populated for this description, breaking any SIBLING
+        # piece's existing command-level bare reference
+        # (`CommandBuilder#reference_named_given`) that depends on it —
+        # real, live corpus: `SafeDepositBox::KeyIssuance.Return`'s own
+        # bare `given("customer is active")` resolves through
+        # `@owner_named_givens`, populated by `Visit`'s declaration
+        # whether `Visit` types the predicate itself OR (now) references
+        # `Account::LedgerEntry`'s instead — this write keeps that
+        # working unchanged either way, `||=` so nothing here overrides
+        # an actual local declaration if one is ever added later.
+        def reference_named_chapter_entity_given(description, declared_by:)
+          verify_resolves_via!("given", "Entity", "owner_keyed")
+          candidates = resolve_owner_keyed(@chapter_entity_named_givens, description)
+
+          named =
+            if declared_by
+              candidates[declared_by] || pending_chapter_entity_given(description, declared_by: declared_by)
+            elsif candidates.size == 1
+              candidates.values.first
+            elsif candidates.empty?
+              pending_chapter_entity_given(description, declared_by: nil)
+            else
+              raise(Malformed,
+                    "#{@aggregate_name}::#{@name}'s given #{description.inspect} is ambiguous " \
+                    "across the chapter's own pieces — #{candidates.keys.join(', ')} each declare " \
+                    "a DIFFERENT predicate under this same description; name which one with " \
+                    "declared_by: (e.g. given(#{description.inspect}, declared_by: " \
+                    "#{candidates.keys.first.inspect}))")
+            end
+
+          @named_givens[description] = named
+          @owner_named_givens[description] ||= named
+        end
+
+        # A CHAPTER MAY BE SPLIT ACROSS FILES — the identical reason
+        # `AggregateBuilder#pending_chapter_given` defers rather than
+        # raising the moment a bare reference outruns what's loaded so
+        # far. Hands back a PLACEHOLDER `Given`, embedded by Ruby object
+        # reference in this piece's own `preconditions`, and queues the
+        # request in `@chapter_entity_pending_givens` —
+        # `BluebookBuilder#resolve_pending_chapter_entity_givens!`
+        # mutates it in place once every file in the chapter has loaded.
+        def pending_chapter_entity_given(description, declared_by:)
+          placeholder = Given.new(description: description, canonical: nil, predicate: nil)
+          @chapter_entity_pending_givens << { entity: "#{@aggregate_name}.#{@name}", description: description,
+                                               declared_by: declared_by, placeholder: placeholder }
+          placeholder
+        end
+
         # A PIECE'S OWN `one_of` LANDS ON ITS AGGREGATE. A type-position
         # `one_of("never_moved", "moved")` on an entity attribute
         # synthesizes a closed-set value object — and until this, that
@@ -257,6 +379,9 @@ module Hecks
                                       owner_named_givens:              @owner_named_givens,
                                       identity_name_prefix:            "#{@identity_name_prefix}#{Naming.demodulise(name)}",
                                       identity_value_object_installer: @identity_value_object_installer,
+                                      aggregate_name:                  @aggregate_name,
+                                      chapter_entity_named_givens:     @chapter_entity_named_givens,
+                                      chapter_entity_pending_givens:   @chapter_entity_pending_givens,
                                 &block)
           end
 

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

@@ -11,9 +11,24 @@ module Hecks
           @name = name
         end
 
-        # `on` — item #13's full metaprogrammed dispatch, slice 1
-        # (whole-project table-unification survey): a bare, kind-driven
-        # coerce-and-assign, now executed by `GenericDispatch`.
+        # `on Account::AccountFrozen` — A BARE CONSTANT ACCEPTED (ADR
+        # 0025, S6 — "events first-class"), resolved through `ConstShim`
+        # the same way `trigger`/`dispatch` already resolve a command
+        # reference (`Naming.event_ref`, that method's own header). NOT
+        # a required spelling yet, unlike `trigger`'s own quoted-text
+        # refusal — see `policy.bluebook`'s own KeywordSeed comment for
+        # why: event names aren't 100% migrated across the live corpus
+        # the way command references are, so both `on "Account.
+        # AccountFrozen"` (quoted) and `on Account::AccountFrozen`
+        # (bare) stay admitted until a full migration lands.
+        #
+        # RENAMED FROM the generic single-fill coercion — item #13's
+        # full metaprogrammed dispatch, slice 1 (whole-project
+        # table-unification survey), now overridden here the same way
+        # `trigger_impl` overrides its own generic default.
+        def on_impl(event_ref)
+          @on_event = Naming.event_ref(event_ref)
+        end
 
         # `with:` — WHAT THE TRIGGER IS GIVEN, when the event's own shape
         # is not it. Omitted, the whole event payload forwards verbatim,