hecks 3.5.0 → 3.7.0

data/lib/hecks/fuzzing/sequence_generator.rb

@@ -9,6 +9,7 @@ require_relative "sequence_generator/step_builder"
 require_relative "sequence_generator/outcome_tracker"
 require_relative "sequence_generator/query_binding"
 require_relative "sequence_generator/adversary"
+require_relative "sequence_generator/prefixing"
 
 module Hecks
   module Fuzzing
@@ -22,6 +23,7 @@ module Hecks
       include OutcomeTracker
       include QueryBinding
       include Adversary
+      include Prefixing
 
       # Creating commands are always eligible; weighting them up reaches an actionable
       # state sooner without starving domains that have few aggregates.
@@ -76,42 +78,24 @@ module Hecks
       # script's `expectations.events` claim. Zero means no interesting state was reached.
       attr_reader :event_count
 
+      # The keywords `.new` takes beyond `seed:` and `steps:`, with their defaults.
+      OPTION_DEFAULTS = { adapter: :memory, adversarial: 0.0, role_draw: 0.0, dry_run: 0.0,
+                          prefix: nil, favor: [] }.freeze
+
       # Takes the same keywords as `.generate`, plus `adapter:` (default `:memory`).
       #
       # @raise [ArgumentError] if `adversarial`, `role_draw`, or `dry_run` is not a
-      #   Numeric between 0.0 and 1.0
-      def initialize(domain_path, seed:, steps:, adapter: :memory, adversarial: 0.0, role_draw: 0.0, dry_run: 0.0,
-                     prefix: nil, favor: [])
-        { adversarial: adversarial, role_draw: role_draw, dry_run: dry_run }.each do |name, fraction|
-          next if fraction.is_a?(Numeric) && fraction.between?(0, 1)
-
-          raise ArgumentError, "#{name}: must be a fraction between 0.0 and 1.0, got #{fraction.inspect}"
-        end
-
-        @domain_path         = domain_path
-        @seed                = seed
-        @step_count          = steps
-        @adapter             = adapter
-        @adversarial         = adversarial.to_f
-        @role_draw           = role_draw.to_f
-        @dry_run             = dry_run.to_f
+      #   Numeric between 0.0 and 1.0, or a keyword is not one `.new` takes
+      def initialize(domain_path, seed:, steps:, **options)
+        settings = OPTION_DEFAULTS.merge(options)
+        validate_options!(settings)
+
+        @domain_path = domain_path
+        @seed        = seed
+        @step_count  = steps
+        configure(settings)
         restart_random(seed)
-        @known_ids           = Hash.new { |h, k| h[k] = [] }
-        @entity_known_ids    = Hash.new { |h, k| h[k] = [] }
-        @appended_identities = Hash.new { |h, k| h[k] = [] }
-        # "Domain::Aggregate" => stored rows a query filters on (query_binding.rb).
-        @written_rows        = Hash.new { |h, k| h[k] = [] }
-        # Role => actor ids granted by this sequence's own `RoleAssignment.Assign` steps.
-        @granted             = Hash.new { |h, k| h[k] = [] }
-        @precedence_caller   = nil
-        @exercised           = Set.new
-        @event_count         = 0
-        @prefix              = prefix
-        @favor               = Array(favor)
-        @own_favor           = @favor
-        @coverage            = []
-        @verbs               = []
-        @attempt             = 0
+        reset_run_state
       end
 
       # Runs the generation against a fresh, isolated boot of the domain.
@@ -125,41 +109,56 @@ module Hecks
           catalog = build_catalog(runtime)
           @verbs  = catalog.values_at(:creating, :instance, :entity_commands, :queries, :entity_queries, :read_models)
                            .flatten.map { |entry| entry[:verb] }.uniq
-
-          steps = []
-          if @prefix
-            realize_prefix(runtime, catalog, @prefix, prefix_limit(@prefix), steps)
-            restart_random(@seed)
-            @favor = @own_favor
-          end
-          @step_count.times { steps << attempt_step(runtime, catalog) }
-          steps.compact
+          generate_steps(runtime, catalog)
         end
       end
 
       private
 
-      # Re-runs the first `limit` attempts of another seed's generation (its own prefix
-      # first), carrying its known ids and exercised verbs into this seed. The prefix is
-      # on top of this seed's budget: taking it out of the budget left too little to explore.
-      def realize_prefix(runtime, catalog, spec, limit, steps)
-        return 0 unless limit.positive?
-
-        inner = spec["prefix"]
-        used  = inner ? realize_prefix(runtime, catalog, inner, [prefix_limit(inner), limit].min, steps) : 0
-        restart_random(Integer(spec.fetch("seed")))
-        @favor = Array(spec["favor"])
-        (limit - used).times { steps << attempt_step(runtime, catalog) }
-        limit
+      def validate_options!(settings)
+        unknown = settings.keys - OPTION_DEFAULTS.keys
+        raise ArgumentError, "unknown keyword: #{unknown.first.inspect}" if unknown.any?
+
+        settings.slice(:adversarial, :role_draw, :dry_run).each do |name, fraction|
+          next if fraction.is_a?(Numeric) && fraction.between?(0, 1)
+
+          raise ArgumentError, "#{name}: must be a fraction between 0.0 and 1.0, got #{fraction.inspect}"
+        end
       end
 
-      # Both streams restart together so a prefix replay draws the same query bindings.
-      def restart_random(seed)
-        @random         = Random.new(seed)
-        @binding_random = Random.new(seed + QueryBinding::BINDING_SEED_OFFSET)
+      def configure(settings)
+        @adapter     = settings[:adapter]
+        @adversarial = settings[:adversarial].to_f
+        @role_draw   = settings[:role_draw].to_f
+        @dry_run     = settings[:dry_run].to_f
+        @prefix      = settings[:prefix]
+        @favor       = Array(settings[:favor])
+        @own_favor   = @favor
       end
 
-      def prefix_limit(spec) = Integer(spec.fetch("steps")).clamp(0, @step_count)
+      # Everything a run accumulates: the ids it has seen, the rows it has written, what it has
+      # exercised, and the coverage it has reached.
+      def reset_run_state
+        @known_ids           = new_pool
+        @entity_known_ids    = new_pool
+        @appended_identities = new_pool
+        # "Domain::Aggregate" => stored rows a query filters on (query_binding.rb).
+        @written_rows        = new_pool
+        # Role => actor ids granted by this sequence's own `RoleAssignment.Assign` steps.
+        @granted             = new_pool
+        reset_progress
+      end
+
+      def reset_progress
+        @precedence_caller = nil
+        @exercised         = Set.new
+        @event_count       = 0
+        @coverage          = []
+        @verbs             = []
+        @attempt           = 0
+      end
+
+      def new_pool = Hash.new { |h, k| h[k] = [] }
 
       def attempt_step(runtime, catalog)
         index = @attempt
@@ -169,15 +168,18 @@ module Hecks
 
         @exercised << entry[:verb]
         @state_before = "-"
-        step =
-          if entry[:query]    then build_query_step(runtime, entry)
-          elsif entry[:model] then build_read_model_step(runtime, entry)
-          else                     build_command_step(runtime, catalog, entry)
-          end
+        step = build_step(runtime, catalog, entry)
         @coverage << [index, coverage_tuple(entry, step)]
         step
       end
 
+      def build_step(runtime, catalog, entry)
+        if entry[:query]    then build_query_step(runtime, entry)
+        elsif entry[:model] then build_read_model_step(runtime, entry)
+        else                     build_command_step(runtime, catalog, entry)
+        end
+      end
+
       # `verb | kind | state before | mutation | outcome`; see CoverageCampaign.
       def coverage_tuple(entry, step)
         kind     = %w[verb query dry_run].find { |key| step.key?(key) }

data/lib/hecks/fuzzing/shrinker/value_simplification.rb

@@ -0,0 +1,64 @@
+module Hecks
+  module Fuzzing
+    module Shrinker
+      # Pass 3 of the shrinker: offers each surviving argument value a simpler stand-in and keeps
+      # the ones the finding survives. Split out of `Shrinker` so each file holds one idea.
+      module ValueSimplification
+        module_function
+
+        # Offers each surviving argument a simpler value, keeping one the finding survives. Nested
+        # hashes are simplified key by key; a candidate that stops reproducing is rejected.
+        def call(steps, meter, &)
+          steps.each_index do |position|
+            original = Shrinker.args_of(steps[position])
+            next unless original.is_a?(Hash)
+
+            original.each_key do |key|
+              steps = simplify_path(steps, position, [key], meter, &)
+            end
+          end
+          steps
+        end
+
+        # Simplifies the value at `path` inside step `position`'s arguments, recursing into hashes.
+        def simplify_path(steps, position, path, meter, &)
+          value = Shrinker.args_of(steps[position]).dig(*path)
+          if value.is_a?(Hash)
+            return value.each_key.reduce(steps) { |acc, key| simplify_path(acc, position, path + [key], meter, &) }
+          end
+
+          simpler_values(value).each do |replacement|
+            return steps if meter.exhausted?
+
+            candidate = with_value(steps, position, path, replacement)
+            return candidate if meter.try { yield(candidate) }
+          end
+          steps
+        end
+
+        # Simpler stand-ins for `value`, simplest first; none for what is already minimal.
+        def simpler_values(value)
+          candidates =
+            case value
+            when String  then ["", value[0].to_s]
+            when Integer then [0, 1]
+            when Float   then [0.0, 1.0]
+            when Array   then [[], value.first(1)]
+            else []
+            end
+          candidates.uniq.reject { |candidate| candidate == value }
+        end
+
+        def with_value(steps, position, path, replacement)
+          step = steps[position]
+          args = Marshal.load(Marshal.dump(Shrinker.args_of(step)))
+          parent = path.length > 1 ? args.dig(*path[0...-1]) : args
+          parent[path.last] = replacement
+          candidate = steps.map(&:dup)
+          candidate[position] = step.merge("args" => args)
+          candidate
+        end
+      end
+    end
+  end
+end

data/lib/hecks/fuzzing/shrinker.rb

@@ -5,6 +5,8 @@ module Hecks
     #
     # Pass 1 removes step chunks (delta debugging) until the list is 1-minimal.
     # Pass 2 drops argument keys one at a time inside each surviving step.
+    # Pass 3 replaces each surviving argument value with a simpler one (empty, zero, first
+    # element) wherever the finding still reproduces, so a repro reads as small as it is.
     # `budget:` caps candidate checks; when spent, the best candidate so far is returned.
     module Shrinker
       Result = Struct.new(:steps, :attempts, :exhausted, keyword_init: true)
@@ -26,6 +28,7 @@ module Hecks
         meter   = Meter.new(budget)
         current = drop_steps(steps.dup, meter, &reproduces)
         current = drop_arguments(current, meter, &reproduces)
+        current = ValueSimplification.call(current, meter, &reproduces)
         Result.new(steps: current, attempts: meter.used, exhausted: meter.exhausted?)
       end
 
@@ -33,35 +36,34 @@ module Hecks
         current = steps
         chunk = [current.length / 2, 1].max
         loop do
-          changed = false
-          index = 0
-          while index < current.length
-            return current if meter.exhausted?
-
-            candidate = current[0...index] + (current[(index + chunk)..] || [])
-            if candidate.empty?
-              index += chunk
-              next
-            end
-
-            if meter.try { reproduces.call(candidate) }
-              current = candidate
-              changed = true
-            else
-              index += chunk
-            end
-          end
+          swept = sweep(current, chunk, meter, &reproduces)
+          changed = swept.length < current.length
+          current = swept
+          return current if meter.exhausted? || (chunk == 1 && !changed)
+
+          chunk = [chunk / 2, 1].max
+        end
+      end
 
-          if chunk > 1
-            chunk = [chunk / 2, 1].max
-          elsif !changed
-            break
+      # One pass removing `chunk` steps at a time; a removal that still reproduces is kept.
+      #
+      # @return [Array<Hash>] the surviving steps
+      def sweep(current, chunk, meter, &)
+        index = 0
+        while index < current.length && !meter.exhausted?
+          candidate = without_chunk(current, index, chunk)
+          if !candidate.empty? && meter.try { yield(candidate) }
+            current = candidate
+          else
+            index += chunk
           end
         end
         current
       end
 
-      def drop_arguments(steps, meter, &reproduces)
+      def without_chunk(steps, index, chunk) = steps[0...index] + (steps[(index + chunk)..] || [])
+
+      def drop_arguments(steps, meter, &)
         steps.each_index do |position|
           original = args_of(steps[position])
           next unless original.is_a?(Hash)
@@ -69,16 +71,21 @@ module Hecks
           original.each_key do |key|
             return steps if meter.exhausted?
 
-            step      = steps[position]
-            trimmed   = args_of(step).reject { |name, _| name == key }
-            candidate = steps.map(&:dup)
-            candidate[position] = step.merge("args" => trimmed)
-            steps = candidate if meter.try { reproduces.call(candidate) }
+            candidate = without_argument(steps, position, key)
+            steps = candidate if meter.try { yield(candidate) }
           end
         end
         steps
       end
 
+      # A copy of `steps` whose step at `position` lacks the argument `key`.
+      def without_argument(steps, position, key)
+        step = steps[position]
+        candidate = steps.map(&:dup)
+        candidate[position] = step.merge("args" => args_of(step).reject { |name, _| name == key })
+        candidate
+      end
+
       # `key?` first, never `||`, which cannot tell a stored `false` from an absent key.
       def args_of(step)
         step.key?("args") ? step["args"] : step[:args]
@@ -127,7 +134,7 @@ module Hecks
         return [] unless left.is_a?(Hash) && right.is_a?(Hash)
 
         (left.keys | right.keys).reject { |key| left[key] == right[key] }
-                                .map { |key| "instances:#{key.to_s.split('#').first}" }
+                                .map { |key| "instances:#{key.to_s.split("#").first}" }
       end
 
       # True when the candidate's signature contains the original's.

data/lib/hecks/fuzzing/target_capabilities.rb

@@ -64,10 +64,16 @@ module Hecks
         capabilities << "postgres_era" if postgres_era_bound?(domain_path)
         capabilities << "translations" if Dir.glob(File.join(domain_path, "**", "translations", "*.bluebook")).any?
         capabilities << "governance" if authorization_attached?(domain_path)
-        capabilities << "role_gated" if any_file?(domain_path, "*.bluebook", ROLE_GATED)
-        capabilities << "tenant" if any_file?(domain_path, "*.bluebook", TENANT_SCOPED)
-        capabilities << "sagas" if any_file?(domain_path, "*.bluebook", PROCESS_MANAGER)
-        capabilities.sort
+        capabilities.concat(declared_capabilities(domain_path)).sort
+      end
+
+      # The capabilities a target's own bluebooks declare, by the construct each one spells.
+      #
+      # @param domain_path [String] filesystem path to the target domain's directory
+      # @return [Array<String>] `role_gated`, `tenant` and `sagas`, for those the bluebooks declare
+      def declared_capabilities(domain_path)
+        { "role_gated" => ROLE_GATED, "tenant" => TENANT_SCOPED, "sagas" => PROCESS_MANAGER }
+          .select { |_, pattern| any_file?(domain_path, "*.bluebook", pattern) }.keys
       end
 
       # Answers whether `mode` can run against a target with `capabilities`.

data/lib/hecks/fuzzing/value_generator.rb

@@ -64,21 +64,31 @@ module Hecks
       # @return [Hash, Object] `{field name => value, ...}`, or the lone value when the
       #   value object has one field and the bare-scalar draw hits
       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
-
-        # Unwrap only a genuinely single-field value object, never `invalid_member`: a wrong
-        # combination stays a Hash so its wrongness is what gets exercised.
+        if value_object.closed_set? && !value_object.members.empty?
+          return invalid_member(value_object, random: random) if random.rand < INVALID_MEMBER_PROBABILITY
+
+          return bare_or_hash(admitted_member(value_object, random), random)
+        end
+
+        bare_or_hash(attribute_fields(value_object, aggregate, random: random, known_ids: known_ids), random)
+      end
+
+      # One admitted row of a closed set, keyed by field name.
+      def admitted_member(value_object, random)
+        value_object.members.sample(random: random).to_h { |field, value| [field.to_s, value] }
+      end
+
+      # A value per declared attribute, keyed by attribute name.
+      def attribute_fields(value_object, aggregate, random:, known_ids:)
+        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
+
+      # Unwrap only a genuinely single-field value object, never `invalid_member`: a wrong
+      # combination stays a Hash so its wrongness is what gets exercised.
+      def bare_or_hash(fields, random)
         return fields.values.first if fields.size == 1 && random.rand < BARE_SCALAR_PROBABILITY
 
         fields
@@ -110,7 +120,7 @@ module Hecks
       #   draw hits
       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
+        return "missing-#{random.bytes(4).unpack1("H*")}" if pool.empty? || random.rand < INVALID_REFERENCE_PROBABILITY
 
         pool.sample(random: random)
       end
@@ -209,7 +219,7 @@ module Hecks
       # @param random [Random] the RNG driving every draw this call makes
       # @return [String] a `"gen-"`-prefixed id with 8 random hex characters
       def random_id(random)
-        "gen-#{random.bytes(4).unpack1('H*')}"
+        "gen-#{random.bytes(4).unpack1("H*")}"
       end
     end
   end

data/lib/hecks/fuzzing.rb

@@ -11,6 +11,7 @@ require_relative "fuzzing/sequence_generator"
 require_relative "fuzzing/nondeterministic"
 require_relative "fuzzing/replay"
 require_relative "fuzzing/shrinker"
+require_relative "fuzzing/shrinker/value_simplification"
 require_relative "fuzzing/properties"
 require_relative "fuzzing/qa_settings"
 require_relative "fuzzing/rotation_priority"
@@ -20,4 +21,6 @@ require_relative "fuzzing/form_census"
 require_relative "fuzzing/target_capabilities"
 require_relative "fuzzing/rust_gap_manifest"
 require_relative "fuzzing/structural_skips"
+require_relative "fuzzing/runtime_coverage"
 require_relative "fuzzing/coverage_campaign"
+require_relative "fuzzing/failure_triage"

data/lib/hecks/gate/stages.yml

@@ -72,6 +72,16 @@ pre_push:
       run: [bundle, exec, exe/hecks, style_run.check_comments, "paths=lib,spec,examples", only=long_block, --wait]
       blocked: a comment block ran past the cap; shorten it.
 
+# The checks a push of only unguarded lanes (`main`) runs in place of pre_push. The slow suite is
+# skipped there; the style checks are not, since an offense that lands on `main` is a red CI run.
+unguarded_push:
+  env:
+    HECKS_ENVIRONMENT: memory
+  checks:
+    - *check_rubocop
+    - *check_comment_style
+    - *check_comment_blocks
+
 # The checks `.githooks/post-commit` runs after each commit. A red one is reported and never
 # blocks the commit; pre_push runs it again as the backstop.
 post_commit:
@@ -104,7 +114,7 @@ ci:
       run: [bundle, exec, exe/hecks, fuzz_run.fuzz, adapter=sqlite, seeds=6, --wait]
       blocked: the SQLite adapter broke a property the Memory adapter held; seeds are 1..N, so the run repeats.
     - id: fuzz_postgres
-      title: fuzz on real Postgres, one worker (every ephemeral boot recreates the same scratch schema)
+      title: fuzz on real Postgres, up to four workers (each in its own scratch schema)
       run: [bundle, exec, exe/hecks, fuzz_run.fuzz, adapter=postgres, seeds=3, steps=20, --wait]
       blocked: the Postgres adapter broke a property the Memory adapter held; it needs PGHOST, PGUSER and PGPASSWORD.
     - id: vocabulary_drift

data/lib/hecks/grammar/evolve/arguments.rb

@@ -0,0 +1,90 @@
+module Hecks
+  module Grammar
+    module Evolve
+      # The edits to ArgumentSeed rows: declare an argument, move it through its stations, and
+      # follow a keyword's respelling. Extended onto `Hecks::Grammar::Evolve`.
+      module Arguments
+        # What `propose_argument` fills in for the cells a caller leaves out.
+        ARGUMENT_DEFAULTS = { required: "false", at: "", named: "", fills: "", pairs_shape: nil }.freeze
+
+        # Declares a new, proposed argument row; pairs_shape marks a `pairs`
+        # argument that fills a whole key/value list, not a single field.
+        #
+        # @param keyword [String] the keyword the argument belongs to
+        # @param context [String] the context the keyword is written in
+        # @param kind [String] the argument's kind
+        # @param fields [Hash] optionally `required:`, `at:`, `named:`, `fills:` and `pairs_shape:`
+        #   cells, and `path:` naming the file(s) to edit
+        # @raise [Refusal] when the row is already declared, or no table owns the context
+        # @raise [ArgumentError] for any other keyword
+        def propose_argument(keyword:, context:, kind:, **fields)
+          check_fields!(fields, ARGUMENT_DEFAULTS.keys + [:path])
+          cells = ARGUMENT_DEFAULTS.merge(fields.except(:path))
+          refuse_declared_argument!(keyword, context, cells, fields[:path])
+          path = owner_path(context: context, word: keyword, paths: paths_for(fields[:path]))
+          append_member(path, context, "ArgumentSeed") { |indent| argument_member(indent, keyword, context, kind, cells) }
+        end
+
+        # @raise [Refusal] when a row with this identity already exists
+        def refuse_declared_argument!(keyword, context, cells, path)
+          identity = [keyword, context, cells[:at], cells[:named]]
+          return unless argument_rows(path).any? { |r| argument_identity(r) == identity }
+
+          raise Refusal, "#{describe_argument(keyword, context, cells[:at], cells[:named])} is " \
+                         "already declared — one row per (keyword, context, at, named)"
+        end
+
+        # @return [String] the new member row, spelled with `indent`
+        def argument_member(indent, keyword, context, kind, cells)
+          shape = cells[:pairs_shape].to_s.empty? ? "" : %(pairs_shape: "#{cells[:pairs_shape]}", )
+          [%(#{indent}member keyword: "#{keyword}", context: "#{context}", at: "#{cells[:at]}", ),
+           %(named: "#{cells[:named]}", kind: "#{kind}", required: "#{cells[:required]}", ),
+           %(fills: "#{cells[:fills]}", #{shape}status: "proposed"\n)].join
+        end
+
+        # @return [String] how a refusal names the argument row
+        def describe_argument(keyword, context, at, named)
+          "#{context}.#{keyword}'s argument at #{at.inspect}/named #{named.inspect}"
+        end
+
+        # Rewrites a declared argument row's status: cell in place.
+        #
+        # @param where [Hash] optionally `at:` and `named:` (default `""`), and `path:`
+        def set_argument_status(keyword:, context:, to:, **where)
+          raise Refusal, "#{to.inspect} is not a station an argument's life admits" unless STATIONS.include?(to)
+
+          at = where.fetch(:at, "")
+          named = where.fetch(:named, "")
+          path = path_holding_argument(keyword, context, at, named, paths_for(where[:path]))
+          rewrite_member_rows(path, "ArgumentSeed", ->(line) { argument_row?(line, keyword, context, at, named) },
+                              "#{describe_argument(keyword, context, at, named)} is not declared") do |line|
+            restatus(line, to)
+          end
+        end
+
+        # Row-aware rename cascade — updates only the argument rows that belong
+        # to the renamed keyword, not a blind gsub across the file.
+        def cascade_argument_rename(keyword:, context:, to:, path: nil)
+          paths_for(path).each do |candidate|
+            original = read_source(candidate)
+            source = argument_blocks(original).reduce(original) do |text, block|
+              respell_argument_keyword(text, block, keyword, context, to)
+            end
+            write_source(candidate, source) if source != original
+          end
+        end
+
+        # @return [String] `text`, with the rows of `block` that belong to `keyword` respelled
+        def respell_argument_keyword(text, block, keyword, context, to)
+          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
+          updated == block ? text : text.sub(block, updated)
+        end
+      end
+    end
+  end
+end

data/lib/hecks/grammar/evolve/keywords.rb

@@ -0,0 +1,81 @@
+module Hecks
+  module Grammar
+    module Evolve
+      # The edits to KeywordSeed rows: declare a word, move it through its stations, respell it.
+      # Extended onto `Hecks::Grammar::Evolve`.
+      module Keywords
+        # What `propose` fills in for the cells a caller leaves out.
+        KEYWORD_DEFAULTS = { body: "none", inner: "", opens: "", fills: "" }.freeze
+
+        # Declares a new, proposed keyword row in the syntax table that owns
+        # `context` (or the aggregate `opens` names, for a File-context word).
+        #
+        # @param word [String] the keyword
+        # @param context [String] the context the keyword is written in
+        # @param fields [Hash] optionally `body:`, `inner:`, `opens:` and `fills:` cells, and
+        #   `path:` naming the file(s) to edit
+        # @raise [Refusal] when the row is already declared, or no table owns the context
+        # @raise [ArgumentError] for any other keyword
+        def propose(word:, context:, **fields)
+          check_fields!(fields, KEYWORD_DEFAULTS.keys + [:path])
+          cells = KEYWORD_DEFAULTS.merge(fields.except(:path))
+          refuse_declared_keyword!(word, context, fields[:path])
+          path = owner_path(context: context, word: word, opens: cells[:opens], paths: paths_for(fields[:path]))
+          append_member(path, context, "KeywordSeed") { |indent| keyword_member(indent, word, context, cells) }
+        end
+
+        # @raise [Refusal] when a row for this word and context already exists
+        def refuse_declared_keyword!(word, context, path)
+          return unless keyword_rows(path).any? { |row| row[:word] == word && row[:context] == context }
+
+          raise Refusal, "#{context}.#{word} is already declared — one row per (word, context, form)"
+        end
+
+        # @return [String] the new member row, spelled with `indent`
+        def keyword_member(indent, word, context, cells)
+          %(#{indent}member word: "#{word}", context: "#{context}", body: "#{cells[:body]}", ) +
+            %(inner: "#{cells[:inner]}", opens: "#{cells[:opens]}", fills: "#{cells[:fills]}", status: "proposed"\n)
+        end
+
+        # Rewrites a declared keyword row's status: cell in place.
+        def set_status(word:, context:, to:, path: nil)
+          raise Refusal, "#{to.inspect} is not a station a word's life admits" unless STATIONS.include?(to)
+
+          rewrite_member_rows(path_holding_keyword(word, context, paths_for(path)), "KeywordSeed",
+                              ->(line) { member_row?(line, word, context) },
+                              "#{context}.#{word} is not declared") { |line| restatus(line, to) }
+        end
+
+        # Respells a keyword row (was: holds the old spelling) — one hop only;
+        # its Argument rows follow, row-aware (see cascade_argument_rename).
+        def rename(word:, context:, to:, path: nil)
+          refuse_rename!(word, context, to, path)
+          paths = paths_for(path)
+          rewrite_member_rows(path_holding_keyword(word, context, paths), "KeywordSeed",
+                              ->(line) { member_row?(line, word, context) },
+                              "#{context}.#{word} is not declared") do |line|
+            line.sub(%(word: "#{word}"), %(word: "#{to}")).sub(/\n\z/, %(, was: "#{word}"\n))
+          end
+          cascade_argument_rename(keyword: word, context: context, to: to, path: paths)
+        end
+
+        # @raise [Refusal] unless the word is declared, not already respelled, and the new
+        #   spelling is free in its context
+        def refuse_rename!(word, context, to, path)
+          rows = keyword_rows(path)
+          row = rows.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]
+
+          refuse_living_word!(rows, context, to)
+        end
+
+        def refuse_living_word!(rows, context, to)
+          return unless rows.any? { |r| r[:word] == to && r[:context] == context }
+
+          raise Refusal, "#{context}.#{to} is already declared — a rename cannot land on a living word"
+        end
+      end
+    end
+  end
+end