hecks 0.2.0 → 1.0.0

data/lib/hecks/fuzzing/value_generator.rb

@@ -0,0 +1,200 @@
+require_relative "../runtime/value"
+
+module Hecks
+  module Fuzzing
+    # One attribute, one value — in the exact JSON shape the hand-written
+    # corpus already uses (a value-object-typed attribute is a nested hash keyed
+    # by its own field names ; a reference is the BARE ID of the head it points
+    # at, because that is what a reference is). Everything
+    # returned is a plain, JSON-safe Ruby value : String keys throughout, never
+    # symbols, so a generated step can be dumped straight to JSON.
+    #
+    # Biased toward the edge cases a hand-written corpus tends to under-sample —
+    # empty strings, quotes, commas, unicode, zero, negative numbers — because
+    # `marks.rb` names literal-encoding loss "the largest family of bug in this
+    # codebase," and a fixed corpus of a few dozen examples rarely happens to
+    # exercise the boundary that actually breaks. But mostly not : an attribute
+    # named `email`/`currency` almost always needs a specific shape just to get
+    # PAST its own invariant (`address.include?("@")`, `currency.size == 3`) —
+    # banking's very first fuzz run never got past Customer.Register, because
+    # no plain random word ever contains "@". Reaching deep state matters more
+    # than edge-casing every single field every single time, so the "normal"
+    # path is now name-aware for the couple of shapes that are genuinely
+    # common across domains, and edge cases stay real but less frequent.
+    module ValueGenerator
+      module_function
+
+      EDGE_CASE_PROBABILITY = 0.2
+      INVALID_MEMBER_PROBABILITY = 0.1
+      INVALID_REFERENCE_PROBABILITY = 0.2
+      # `Value.for_attribute` → `fields_for`'s own bare-scalar branch
+      # (lib/hecks/runtime/value/coercion.rb) has accepted a bare
+      # `"large"` in place of `{"value" => "large"}` for any single-field
+      # value object since 86727afd — but until this generator actually
+      # PRODUCES that shape, nothing exercises it: neither the adapter-
+      # agreement gate nor the Rust/WASM `from_json` codegen (rust/project/
+      # json_codec.rb) can ever be caught drifting on a shape they're
+      # never handed.
+      BARE_SCALAR_PROBABILITY = 0.2
+
+      STRING_EDGE_CASES = [
+        "", "x", "with \"quotes\"", "with, a comma", "with a \\backslash",
+        "unicode héllo wörld 🎉", "x" * 200, "  leading and trailing  "
+      ].freeze
+      # PRD 05 (numeric-boundary-coverage) — Bignum (`2**100`, past i64's
+      # own ceiling, which Ruby's own `Integer` has no such ceiling for —
+      # `rust/src/kernel/json.rs`'s own `integral_i64` doc comment names
+      # exactly this: a Rust kernel value CANNOT represent it, so this
+      # exercises a real cross-runtime capability gap, not a Ruby-only
+      # edge) and its negative twin. Both round-trip through Ruby's own
+      # arithmetic/JSON cleanly (confirmed directly: `(2**100).clamp(...)`
+      # and `JSON.generate(2**100)` both just work — Integer has no
+      # ceiling here), so nothing in THIS runtime needed a fix for these;
+      # they're included so a real generated sequence occasionally
+      # produces the value at all, since nothing had, repo-wide, before.
+      INTEGER_EDGE_CASES = [0, -1, 2_147_483_647, -2_147_483_648, 2**100, -(2**100)].freeze
+      # NaN and +/-Infinity — the real find (see `spec/runtime/
+      # numeric_boundary_spec.rb`): `Value::Coercion#check_numeric_fields`
+      # used to let all three sail through untyped-checked (each really
+      # is a Float), reaching either `CommandRules::Arithmetic#clamp`
+      # (raw `ArgumentError`, not a domain refusal) or `JSON.generate`
+      # (`JSON::GeneratorError`, also not a domain refusal) — both fixed
+      # at the source now, so these are safe to generate. -0.0 is
+      # deliberately included too even though it was ALREADY safe
+      # (finite, round-trips through JSON as `-0.0` cleanly) — a signed
+      # zero is exactly the kind of boundary a hand-written corpus never
+      # happens to type, and the fuzzer existing to cover it is the
+      # point.
+      FLOAT_EDGE_CASES = [0.0, -0.0, -0.5, -100.25, Float::NAN, Float::INFINITY, -Float::INFINITY].freeze
+      WORDS = %w[alpha bravo charlie delta echo foxtrot golf hotel india juliet].freeze
+      CURRENCY_CODES = %w[USD EUR GBP JPY].freeze
+
+      # The value for one command/query/value-object attribute. `known_ids` is
+      # `{aggregate_or_entity_name => [scalar id, ...]}`, supplied by the
+      # sequence generator — a reference draws a real id from it most of the
+      # time and a fabricated one sometimes, to exercise NotFound as often as
+      # the happy path.
+      # `context` carries the enclosing value object's own declared name down
+      # into a nested primitive field — `EmailAddress`'s `address` field is
+      # what actually needs to look email-shaped, but the field itself is
+      # just named "address"; the VO's own name is where "email" lives. A
+      # combined hint catches both spellings without needing to guess which
+      # level a domain happened to name the thing on.
+      def value_for(attribute, aggregate, random:, known_ids: {}, context: nil)
+        return reference_value(attribute, random: random, known_ids: known_ids) if attribute.reference?
+
+        # Local first, falling back to a same-chapter identity value object
+        # declared on a sibling aggregate — the exact resolution
+        # `Value.value_object_for` already does for a real dispatch
+        # (runtime/value/coercion.rb). `safe_deposit_boxes.bluebook`'s own
+        # `attribute :customer, CustomerNumber` is declared on SafeDepositBox
+        # but CustomerNumber itself lives on Customer; without this fallback
+        # the generator raised "does not know primitive type" for any such
+        # cross-aggregate identity attribute rather than reusing the same
+        # lookup the runtime relies on.
+        value_object = Runtime::Value.value_object_for(aggregate, attribute.type.to_s)
+        return object_for(value_object, aggregate, random: random, known_ids: known_ids) if value_object
+
+        primitive(attribute.type.to_s, random: random, name: "#{context} #{attribute.name}")
+      end
+
+      def object_for(value_object, aggregate, random:, known_ids:)
+        fields =
+          if value_object.closed_set? && !value_object.members.empty?
+            return invalid_member(value_object, random: random) if random.rand < INVALID_MEMBER_PROBABILITY
+
+            member = value_object.members.sample(random: random)
+            member.to_h { |field, value| [field.to_s, value] }
+          else
+            value_object.attributes.to_h do |field|
+              [field.name.to_s,
+               value_for(field, aggregate, random: random, known_ids: known_ids, context: value_object.hecks_name)]
+            end
+          end
+
+        # `fields.size == 1` — the SAME test `Behaviour::ValueObject#
+        # sole_attribute` names: a genuinely single-field value object,
+        # not merely "this particular closed-set member happened to pick
+        # one field." Unwrapping ONLY here, not in `invalid_member`
+        # above — a deliberately-wrong combination stays a Hash so its
+        # own wrongness is what gets exercised, not a second, unrelated
+        # shape question.
+        return fields.values.first if fields.size == 1 && random.rand < BARE_SCALAR_PROBABILITY
+
+        fields
+      end
+
+      # A combination that (almost certainly) isn't one of the closed set's
+      # admitted rows — deliberately, to exercise the refusal a `one_of`
+      # exists to enforce, not just its happy path.
+      def invalid_member(value_object, random:)
+        value_object.attributes.to_h { |field|
+          [field.name.to_s, primitive(field.type.to_s, random: random, name: field.name.to_s)]
+        }
+      end
+
+      # THE ID ITSELF. This minted `{"value" => id}` back when a reference was
+      # stored wrapped ; the payload gate refuses that shape now, so a fuzzer
+      # still emitting it would have every generated reference refused and
+      # the SILENT guard would report the fuzzer broken rather than
+      # the runtime.
+      def reference_value(attribute, random:, known_ids:)
+        pool = known_ids[attribute.type.target_name.to_s] || []
+        return "missing-#{random.bytes(4).unpack1('H*')}" if pool.empty? || random.rand < INVALID_REFERENCE_PROBABILITY
+
+        pool.sample(random: random)
+      end
+
+      def primitive(type_name, random:, name: nil)
+        case type_name
+        when "String"  then string_value(random, name: name)
+        when "Integer" then integer_value(random)
+        when "Float"   then float_value(random)
+        when "TrueClass", "FalseClass" then random.rand(2).zero?
+        else raise ArgumentError, "ValueGenerator does not know primitive type #{type_name.inspect}"
+        end
+      end
+
+      def string_value(random, name: nil)
+        return STRING_EDGE_CASES.sample(random: random) if random.rand < EDGE_CASE_PROBABILITY
+        return email_value(random) if name&.match?(/email/i)
+        return CURRENCY_CODES.sample(random: random) if name&.match?(/currency/i)
+
+        Array.new(random.rand(1..3)) { WORDS.sample(random: random) }.join(" ")
+      end
+
+      def email_value(random)
+        "#{WORDS.sample(random: random)}@#{WORDS.sample(random: random)}.example"
+      end
+
+      # Skewed positive : `cents.positive?`/`!cents.negative?`-style
+      # invariants are common across this codebase's example domains, and a
+      # sequence that can never get past one never reaches the state a deeper
+      # bug would need. Zero and negative are still real, reachable outcomes —
+      # via the edge-case pool, deliberately, not by starving them entirely.
+      def integer_value(random)
+        return INTEGER_EDGE_CASES.sample(random: random) if random.rand < EDGE_CASE_PROBABILITY
+
+        random.rand(1..1000)
+      end
+
+      def float_value(random)
+        return FLOAT_EDGE_CASES.sample(random: random) if random.rand < EDGE_CASE_PROBABILITY
+
+        random.rand(0.01..1000.0).round(2)
+      end
+
+      # The bare scalar a generated IDENTITY value stands for, for recording into
+      # `known_ids`. An identity is declared as a value object, so this opens one ;
+      # a reference pointing at this record is already that scalar and needs no
+      # opening at all. The two used to be the same reading and are not any more.
+      def scalar_of(identity_value)
+        identity_value.is_a?(Hash) ? identity_value.values.first.to_s : identity_value.to_s
+      end
+
+      def random_id(random)
+        "gen-#{random.bytes(4).unpack1('H*')}"
+      end
+    end
+  end
+end

data/lib/hecks/fuzzing.rb

@@ -0,0 +1,12 @@
+module Hecks
+  # The fuzzing toolkit bin/fuzz and bin/generate drive. Not required by
+  # lib/hecks.rb on purpose — a booted domain never needs it.
+  module Fuzzing
+  end
+end
+
+require_relative "fuzzing/value_generator"
+require_relative "fuzzing/invalid_value_generator"
+require_relative "fuzzing/sequence_generator"
+require_relative "fuzzing/replay"
+require_relative "fuzzing/properties"

data/lib/hecks/grammar/evolve.rb

@@ -0,0 +1,324 @@
+module Hecks
+  module Grammar
+    # The file surgery under bin/evolve: reading and rewriting the
+    # aggregate-local KeywordSeed/ArgumentSeed rows as TEXT, so a
+    # proposed word enters the table exactly as a hand would write it
+    # and an admitted one loses its ceremony (an absent status reads as
+    # admitted — the grown-column convention).
+    #
+    # Text, not IR, on purpose: the syntax table is source, its comments
+    # and grouping are part of the declaration, and a rewrite that
+    # round-tripped it through the IR would flatten both. Everything
+    # here touches only bare `member ` lines inside Keyword's own body
+    # (S3, ADR 0025 — no `one_of do ... end` wrapper anymore) and leaves
+    # every other byte alone.
+    module Evolve
+      class Refusal < StandardError; end
+
+      module_function
+
+      # bin/evolve's own `--name value` flag reader. Only consumes the
+      # NEXT argv element as the value when that element doesn't itself
+      # look like a flag — otherwise `--foo --bar` would swallow `--bar`
+      # as `--foo`'s value (and `--bar` would then never be seen at
+      # all), and a value-less `--foo` at the end of argv would bypass
+      # whatever default `foo` promised instead of falling back to it.
+      def option(argv, name, default = nil)
+        index = argv.index("--#{name}")
+        return default unless index
+
+        value = argv[index + 1]
+        value.nil? || value.start_with?("-") ? default : value
+      end
+
+      # The snapshot/restore ceremony bin/evolve wraps every mutating
+      # command in: read every `paths` file, run the block, and put
+      # every file back exactly as it was if the block raises partway
+      # through — `rename`'s keyword-row write followed by its
+      # argument cascade across several files (`cascade_argument_rename`
+      # above) included, not only a declared gate failing after the
+      # block has already returned cleanly (bin/evolve's own `guarded`
+      # still handles that half on its own, since it depends on running
+      # the gate specs, not on anything this method knows about). A
+      # clean return leaves the snapshots unused; the caller decides
+      # from there whether the tree stands.
+      def restore_on_raise(paths)
+        snapshots = paths.to_h { |path| [path, File.read(path)] }
+        yield
+      rescue StandardError
+        snapshots.each { |path, content| File.write(path, content) }
+        raise
+      end
+
+      def syntax_paths
+        Dir.glob(File.expand_path("../language/**/*.bluebook", __dir__)).select do |path|
+          source = File.read(path)
+          source.include?('value_object "KeywordSeed"') || source.include?('value_object "ArgumentSeed"')
+        end
+      end
+
+      # Kept as a narrow compatibility door for callers deliberately doing
+      # single-file surgery. Normal operation uses `syntax_paths` and discovers
+      # the owning concept from the row itself.
+      def syntax_path = syntax_paths.first
+
+      def paths_for(path) = path ? Array(path) : syntax_paths
+
+      # The Keyword one_of's member rows, parsed leniently off the text —
+      # enough to know each row's (word, context, status), which is all
+      # the tool ever asks.
+      def keyword_rows(path = nil)
+        paths_for(path).flat_map do |candidate|
+          blocks = seed_blocks(File.read(candidate), "KeywordSeed")
+          raise Refusal, "source declares no KeywordSeed value object" if path && blocks.empty?
+
+          blocks.flat_map do |block|
+            block.scan(/^\s*member (.+)$/).map do |(cells)|
+              row = cells.scan(/(\w+): "((?:[^"\\]|\\.)*)"/).to_h
+              { word: row["word"], context: row["context"],
+                status: row.fetch("status", "admitted"), was: row["was"] }
+            end
+          end
+        end
+      end
+
+      def propose(word:, context:, body: "none", inner: "", opens: "", fills: "", path: nil)
+        raise Refusal, "#{context}.#{word} is already declared — one row per (word, context, form)" if keyword_rows(path).any? { |row| row[:word] == word && row[:context] == context }
+
+        path = owner_path(context: context, word: word, opens: opens, paths: paths_for(path))
+        source = File.read(path)
+        block  = keyword_blocks(source).find { |candidate| candidate.include?(%(context: "#{context}")) } || keyword_block(source)
+        indent = block[/^(\s*)member /, 1] || "        "
+        row = %(#{indent}member word: "#{word}", context: "#{context}", body: "#{body}", ) +
+              %(inner: "#{inner}", opens: "#{opens}", fills: "#{fills}", status: "proposed"\n)
+
+        # At the END of the one_of — grouping by context is a courtesy of
+        # the hand; a proposed row sits at the bottom until admission,
+        # when whoever admits it may move it home.
+        closing = block.rindex(/^\s*end\s*$/)
+        updated = block[0...closing] + row + block[closing..]
+        File.write(path, source.sub(block, updated))
+      end
+
+      def set_status(word:, context:, to:, path: nil)
+        raise Refusal, "#{to.inspect} is not a station a word's life admits" unless %w[proposed admitted deprecated retired].include?(to)
+
+        path = path_holding_keyword(word, context, paths_for(path))
+        source = File.read(path)
+        block  = keyword_blocks(source).find { |candidate| candidate.lines.any? { |line| member_row?(line, word, context) } }
+        rows   = block.lines.select { |line| member_row?(line, word, context) }
+        raise Refusal, "#{context}.#{word} is not declared" if rows.empty?
+
+        updated = block.lines.map do |line|
+          next line unless member_row?(line, word, context)
+
+          stripped = line.sub(/,\s*status: "[^"]*"/, "")
+          # Admitted is the default and stays UNSPELLED — only a word
+          # entering or leaving the language carries its status.
+          to == "admitted" ? stripped : stripped.sub(/\n\z/, %(, status: "#{to}"\n))
+        end.join
+
+        File.write(path, source.sub(block, updated))
+      end
+
+      # A rename respells the row's word and holds the old spelling in
+      # `was:` — one hop only. Renaming an already-renamed word refuses
+      # until the language grows real eras for its own words; renaming
+      # onto a spelling the context already declares refuses too. The
+      # word's Argument rows follow it — row-aware now, not the blind
+      # substitution this used to be (see `cascade_argument_rename`).
+      def rename(word:, context:, to:, path: nil)
+        row = keyword_rows(path).find { |r| r[:word] == word && r[:context] == context }
+        raise Refusal, "#{context}.#{word} is not declared" unless row
+        raise Refusal, "#{context}.#{word} was already #{row[:was]} — one rename hop, then eras" if row[:was]
+        raise Refusal, "#{context}.#{to} is already declared — a rename cannot land on a living word" if keyword_rows(path).any? { |r| r[:word] == to && r[:context] == context }
+
+        paths = paths_for(path)
+        path = path_holding_keyword(word, context, paths)
+        source = File.read(path)
+        block  = keyword_blocks(source).find { |candidate| candidate.lines.any? { |line| member_row?(line, word, context) } }
+        updated = block.lines.map do |line|
+          next line unless member_row?(line, word, context)
+
+          line.sub(%(word: "#{word}"), %(word: "#{to}"))
+              .sub(/\n\z/, %(, was: "#{word}"\n))
+        end.join
+        source = source.sub(block, updated)
+        File.write(path, source)
+
+        cascade_argument_rename(keyword: word, context: context, to: to, path: paths)
+      end
+
+      def member_row?(line, word, context)
+        line =~ /^\s*member / && line.include?(%(word: "#{word}")) && line.include?(%(context: "#{context}"))
+      end
+
+      def path_holding_keyword(word, context, paths = syntax_paths)
+        paths.find do |candidate|
+          keyword_blocks(File.read(candidate)).any? { |block| block.lines.any? { |line| member_row?(line, word, context) } }
+        end || raise(Refusal, "#{context}.#{word} is not declared")
+      end
+
+      def path_holding_argument(keyword, context, at, named, paths = syntax_paths)
+        paths.find do |candidate|
+          argument_blocks(File.read(candidate)).any? { |block| block.lines.any? { |line| argument_row?(line, keyword, context, at, named) } }
+        end || raise(Refusal, "#{context}.#{keyword}'s argument at #{at.inspect}/named #{named.inspect} is not declared")
+      end
+
+      # A new row belongs wherever that context's existing rows live. File is
+      # intentionally wider than one aggregate; for a new entry point, `opens`
+      # identifies the aggregate concept whose file should own it.
+      def owner_path(context:, word:, opens: "", paths: syntax_paths)
+        if context == "File" && !opens.to_s.empty?
+          aggregate_path = paths.find { |candidate| File.read(candidate).match?(/^\s*aggregate "#{Regexp.escape(opens)}" do$/) }
+          return aggregate_path if aggregate_path
+        end
+
+        paths.find do |candidate|
+          source = File.read(candidate)
+          %w[KeywordSeed ArgumentSeed].any? do |seed|
+            seed_blocks(source, seed).any? { |block| block.include?(%(context: "#{context}")) }
+          end
+        end || raise(Refusal, "no aggregate-local syntax table owns context #{context.inspect} for #{word}")
+      end
+
+      def seed_blocks(source, name)
+        opener = /^([ \t]*)value_object "#{Regexp.escape(name)}" do$/
+        source.to_enum(:scan, opener).map do
+          match = Regexp.last_match
+          start = match.begin(0)
+          indent = match[1]
+          closing = source.index(/^#{Regexp.escape(indent)}end\s*$/, match.end(0))
+          closing = source.index(/\n/, closing) + 1
+          source[start...closing]
+        end
+      end
+
+      def seed_block(source, name, required: false)
+        block = seed_blocks(source, name).first
+        unless block
+          raise Refusal, "source declares no #{name} value object" if required
+
+          return
+        end
+        block
+      end
+
+      # From `value_object "KeywordSeed"` to ITS OWN closing `end` — `member`
+      # rows sit bare now (S3, ADR 0025 — the `one_of do ... end` wrapper
+      # is gone), so the first bare `end` line after the opener already
+      # IS the value object's own, the same fact the original one_of-
+      # nested version of this method leaned on (nothing else nested
+      # inside it either, before or after).
+      def keyword_blocks(source) = seed_blocks(source, "KeywordSeed")
+      def keyword_block(source) = seed_block(source, "KeywordSeed", required: true)
+
+      # ── the Argument rows — a word's own arguments, at last with tooling
+      # of their own rather than the rename-only cascade above. A word may
+      # carry SEVERAL argument rows (one per position, one per named
+      # kwarg), so identity here is the full (keyword, context, at, named)
+      # tuple, not the two-field key a Keyword row answers to.
+
+      def argument_rows(path = nil)
+        paths_for(path).flat_map do |candidate|
+          blocks = seed_blocks(File.read(candidate), "ArgumentSeed")
+          raise Refusal, "source declares no ArgumentSeed value object" if path && blocks.empty?
+
+          blocks.flat_map do |block|
+            block.scan(/^\s*member (.+)$/).map do |(cells)|
+              row = cells.scan(/(\w+): "((?:[^"\\]|\\.)*)"/).to_h
+              { keyword: row["keyword"], context: row["context"], at: row["at"].to_s,
+                named: row["named"].to_s, kind: row["kind"], required: row["required"],
+                fills: row["fills"].to_s, status: row.fetch("status", "admitted") }
+            end
+          end
+        end
+      end
+
+      # `pairs_shape` — for a `pairs` argument that fills ONE field with a
+      # whole key/value list rather than naming a field per pair (the
+      # shape `Handler.dispatch`'s own `with:` already carries). Without
+      # it, `spec/syntax_conformance_spec.rb` reads a pairs argument
+      # naming a single field as a row that "names a single field, which
+      # it cannot fill" — correctly, since the two shapes are genuinely
+      # different and only one of them can be checked the same way.
+      def propose_argument(keyword:, context:, kind:, required: "false", at: "", named: "", fills: "",
+                           pairs_shape: nil, path: nil)
+        if argument_rows(path).any? { |r| argument_identity(r) == [keyword, context, at, named] }
+          raise Refusal, "#{context}.#{keyword}'s argument at #{at.inspect}/named #{named.inspect} is " \
+                         "already declared — one row per (keyword, context, at, named)"
+        end
+
+        path = owner_path(context: context, word: keyword, paths: paths_for(path))
+        source = File.read(path)
+        block  = argument_blocks(source).find { |candidate| candidate.include?(%(context: "#{context}")) } || argument_block(source)
+        indent = block[/^(\s*)member /, 1] || "        "
+        shape = pairs_shape.to_s.empty? ? "" : %(pairs_shape: "#{pairs_shape}", )
+        row = %(#{indent}member keyword: "#{keyword}", context: "#{context}", at: "#{at}", ) +
+              %(named: "#{named}", kind: "#{kind}", required: "#{required}", fills: "#{fills}", ) +
+              shape + %(status: "proposed"\n)
+
+        closing = block.rindex(/^\s*end\s*$/)
+        updated = block[0...closing] + row + block[closing..]
+        File.write(path, source.sub(block, updated))
+      end
+
+      def set_argument_status(keyword:, context:, to:, at: "", named: "", path: nil)
+        raise Refusal, "#{to.inspect} is not a station an argument's life admits" unless %w[proposed admitted deprecated retired].include?(to)
+
+        path = path_holding_argument(keyword, context, at, named, paths_for(path))
+        source = File.read(path)
+        block  = argument_blocks(source).find { |candidate| candidate.lines.any? { |line| argument_row?(line, keyword, context, at, named) } }
+        rows   = block.lines.select { |line| argument_row?(line, keyword, context, at, named) }
+        raise Refusal, "#{context}.#{keyword}'s argument at #{at.inspect}/named #{named.inspect} is not " \
+                       "declared" if rows.empty?
+
+        updated = block.lines.map do |line|
+          next line unless argument_row?(line, keyword, context, at, named)
+
+          stripped = line.sub(/,\s*status: "[^"]*"/, "")
+          to == "admitted" ? stripped : stripped.sub(/\n\z/, %(, status: "#{to}"\n))
+        end.join
+
+        File.write(path, source.sub(block, updated))
+      end
+
+      def argument_row?(line, keyword, context, at, named)
+        line =~ /^\s*member / &&
+          line.include?(%(keyword: "#{keyword}")) && line.include?(%(context: "#{context}")) &&
+          line.include?(%(at: "#{at}")) && line.include?(%(named: "#{named}"))
+      end
+
+      def argument_identity(row) = [row[:keyword], row[:context], row[:at], row[:named]]
+
+      # The rename cascade, ROW-AWARE — only the rows that actually belong
+      # to the renamed word, spelling updated in place, rather than a
+      # blind `gsub` on every `keyword: "word",` substring in the file
+      # (which a coincidentally-matching row elsewhere could have
+      # corrupted, and which read nothing before writing).
+      def cascade_argument_rename(keyword:, context:, to:, path: nil)
+        paths_for(path).each do |candidate|
+          source = File.read(candidate)
+          original = source
+          argument_blocks(source).each do |block|
+            updated = block.lines.map do |line|
+              next line unless line =~ /^\s*member / &&
+                               line.include?(%(keyword: "#{keyword}")) && line.include?(%(context: "#{context}"))
+
+              line.sub(%(keyword: "#{keyword}"), %(keyword: "#{to}"))
+            end.join
+            source = source.sub(block, updated) if updated != block
+          end
+          File.write(candidate, source) if source != original
+        end
+      end
+
+      # From `value_object "ArgumentSeed"` to ITS OWN closing `end` — see
+      # `keyword_block`'s own comment for why the first bare `end` after
+      # the opener is already the right one, now that `member` rows sit
+      # bare (S3, ADR 0025).
+      def argument_blocks(source) = seed_blocks(source, "ArgumentSeed")
+      def argument_block(source) = seed_block(source, "ArgumentSeed", required: true)
+    end
+  end
+end