hecks 0.3.0 → 1.0.1

data/lib/hecks/bluebook/chapter.rb

@@ -30,17 +30,27 @@ module Hecks
       IR_VERSION = 1
 
       emits_ir(
-        ir_version:       -> { IR_VERSION },
-        name:             :name,
-        version:          :version,
-        vision:           :vision,
-        classification:   :classification,
-        aggregates:       many(:aggregates),
-        read_models:      many(:read_models),
-        policies:         many(:policies),
-        process_managers: many(:process_managers),
-        attaches_to:      :attaches_to,
-        canonical_form:   -> { Expression::CanonicalForm.table }
+        ir_version:        -> { IR_VERSION },
+        name:              :name,
+        version:           :version,
+        vision:            :vision,
+        classification:    :classification,
+        # M10 — a domain rename (`formerly_known_as "OldName"`) drives a
+        # real Postgres schema rename at boot (EraResolver reads
+        # `bluebook.formerly_known_as` off the live Ruby object) and the
+        # meta-validator's cache key is `SHA256(JSON(bluebook.to_h))` — so
+        # a fact this method didn't spell was a fact two chapters
+        # differing ONLY by their old name could hash identically on,
+        # same as read-model filters before them. Spelled here for the
+        # same reason `version`/`vision` are: a plain field, present
+        # (possibly nil) rather than silently absent.
+        formerly_known_as: :formerly_known_as,
+        aggregates:        many(:aggregates),
+        read_models:       many(:read_models),
+        policies:          many(:policies),
+        process_managers:  many(:process_managers),
+        attaches_to:       :attaches_to,
+        canonical_form:    -> { Expression::CanonicalForm.table }
       )
 
       attr_reader :name, :version, :vision, :aggregates, :policies, :process_managers,

data/lib/hecks/bluebook/command.rb

@@ -39,7 +39,7 @@ module Hecks
       # the tail, which is why a construct with a variable shape needs no
       # new mixin API.
       def to_h
-        return super.merge(fields: appended_fields) if [:append, :delegate].include?(op)
+        return super.merge(fields: appended_fields) if [:append, :delegate, :corrects].include?(op)
 
         super.merge(source: classified_source)
       end

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!
 
@@ -488,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
@@ -618,7 +737,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/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