hecks 0.2.0 → 1.0.0

data/lib/hecks/vocabulary.rb

@@ -0,0 +1,218 @@
+# GENERATED — projected from the language's own Vocabulary aggregate
+# (lib/hecks/language/bluebook/vocabulary.bluebook).
+#
+# DO NOT EDIT. spec/vocabulary_table_spec.rb re-projects this in memory
+# and refuses a diff, so an edit here fails the ordinary suite.
+#
+# Plain data on purpose — no requires, no dependency on the model —
+# because several of these sets are read while a bluebook is still
+# being parsed. A table that needed the framework to load could not
+# be the table the framework loads with.
+
+module Hecks
+  module Vocabulary
+    TABLES = {
+      "AggregateDispatchOrder" => [
+        {"step"=>"refuse_unknown_arguments"}.freeze,
+        {"step"=>"refuse_absent_arguments"}.freeze,
+        {"step"=>"normalize_args"}.freeze,
+        {"step"=>"refuse_role_mismatch"}.freeze,
+        {"step"=>"resolve_references"}.freeze,
+        {"step"=>"hydrate"}.freeze,
+        {"step"=>"enforce_givens"}.freeze,
+        {"step"=>"admissible_transition"}.freeze,
+        {"step"=>"assign_creation_attributes"}.freeze,
+        {"step"=>"apply_mutations"}.freeze,
+        {"step"=>"advance_lifecycle"}.freeze,
+        {"step"=>"delegate_to_entity"}.freeze,
+        {"step"=>"enforce_ensures"}.freeze,
+        {"step"=>"enforce_invariants"}.freeze,
+        {"step"=>"save"}.freeze,
+        {"step"=>"emit"}.freeze
+      ].freeze,
+      "Comparison" => [
+        {"symbol"=>">=", "compares_less_than"=>"true", "compares_equal"=>"false", "negated"=>"true"}.freeze,
+        {"symbol"=>"<=", "compares_less_than"=>"true", "compares_equal"=>"true", "negated"=>"false"}.freeze,
+        {"symbol"=>"<", "compares_less_than"=>"true", "compares_equal"=>"false", "negated"=>"false"}.freeze,
+        {"symbol"=>">", "compares_less_than"=>"true", "compares_equal"=>"true", "negated"=>"true"}.freeze,
+        {"symbol"=>"==", "compares_less_than"=>"false", "compares_equal"=>"true", "negated"=>"false"}.freeze,
+        {"symbol"=>"!=", "compares_less_than"=>"false", "compares_equal"=>"true", "negated"=>"true"}.freeze
+      ].freeze,
+      "DomainRefusal" => [
+        {"name"=>"AbsentArgument"}.freeze,
+        {"name"=>"AlreadyExists"}.freeze,
+        {"name"=>"AttributeAbsent"}.freeze,
+        {"name"=>"EnsuresNotMet"}.freeze,
+        {"name"=>"GivenNotMet"}.freeze,
+        {"name"=>"InvariantViolation"}.freeze,
+        {"name"=>"LifecycleRefused"}.freeze,
+        {"name"=>"NothingToCorrect"}.freeze,
+        {"name"=>"NotFound"}.freeze,
+        {"name"=>"ProjectionAbsent"}.freeze,
+        {"name"=>"RemoteRefusal"}.freeze,
+        {"name"=>"TypeMismatch"}.freeze,
+        {"name"=>"Unauthorized"}.freeze,
+        {"name"=>"UnknownArgument"}.freeze,
+        {"name"=>"UnknownVerb"}.freeze
+      ].freeze,
+      "EntityDispatchOrder" => [
+        {"step"=>"refuse_unknown_arguments"}.freeze,
+        {"step"=>"refuse_absent_arguments"}.freeze,
+        {"step"=>"normalize_args"}.freeze,
+        {"step"=>"refuse_role_mismatch"}.freeze,
+        {"step"=>"resolve_references"}.freeze,
+        {"step"=>"hydrate_parent"}.freeze,
+        {"step"=>"locate_element"}.freeze,
+        {"step"=>"enforce_givens"}.freeze,
+        {"step"=>"admissible_transition"}.freeze,
+        {"step"=>"apply_mutations"}.freeze,
+        {"step"=>"advance_lifecycle"}.freeze,
+        {"step"=>"enforce_ensures"}.freeze,
+        {"step"=>"enforce_invariants"}.freeze,
+        {"step"=>"save"}.freeze,
+        {"step"=>"emit"}.freeze
+      ].freeze,
+      "FieldHint" => [
+        {"name"=>"email", "pattern"=>"email", "resolves_to"=>"html_type"}.freeze,
+        {"name"=>"url", "pattern"=>"\\b(url|uri|website|link)\\b", "resolves_to"=>"html_type"}.freeze,
+        {"name"=>"tel", "pattern"=>"phone|\\btel(ephone)?\\b", "resolves_to"=>"html_type"}.freeze,
+        {"name"=>"textarea", "pattern"=>"\\b(text|body|note|notes|description|message|comment)\\b", "resolves_to"=>"kind"}.freeze
+      ].freeze,
+      "IncludeHaystack" => [
+        {"type"=>"Array", "strategy"=>"membership"}.freeze,
+        {"type"=>"String", "strategy"=>"substring"}.freeze
+      ].freeze,
+      "LoadOrder" => [
+        {"glob"=>"*.port"}.freeze,
+        {"glob"=>"*.adapter"}.freeze,
+        {"glob"=>"*.bluebook"}.freeze,
+        {"glob"=>"translations/*.bluebook"}.freeze,
+        {"glob"=>"*.hecksagon"}.freeze,
+        {"glob"=>"*.world"}.freeze
+      ].freeze,
+      "MutationOp" => [
+        {"name"=>"set", "sign"=>""}.freeze,
+        {"name"=>"append", "sign"=>""}.freeze,
+        {"name"=>"increment", "sign"=>"1"}.freeze,
+        {"name"=>"decrement", "sign"=>"-1"}.freeze,
+        {"name"=>"multiply", "sign"=>""}.freeze,
+        {"name"=>"clamp", "sign"=>""}.freeze,
+        {"name"=>"remove", "sign"=>""}.freeze,
+        {"name"=>"delegate", "sign"=>""}.freeze,
+        {"name"=>"corrects", "sign"=>""}.freeze
+      ].freeze,
+      "NormalisationStrategy" => [
+        {"name"=>"collapse_whitespace"}.freeze,
+        {"name"=>"replace"}.freeze
+      ].freeze,
+      "Primitive" => [
+        {"name"=>"String"}.freeze,
+        {"name"=>"Integer"}.freeze,
+        {"name"=>"Float"}.freeze,
+        {"name"=>"TrueClass"}.freeze,
+        {"name"=>"FalseClass"}.freeze
+      ].freeze,
+      "QueryComparator" => [
+        {"name"=>"eq"}.freeze,
+        {"name"=>"ne"}.freeze,
+        {"name"=>"gt"}.freeze,
+        {"name"=>"gte"}.freeze,
+        {"name"=>"lt"}.freeze,
+        {"name"=>"lte"}.freeze,
+        {"name"=>"in"}.freeze,
+        {"name"=>"contains"}.freeze,
+        {"name"=>"none_in_state"}.freeze
+      ].freeze,
+      "RefusalTemplate" => [
+        {"refusal"=>"NotFound", "site"=>"creating_no_identity", "template"=>"{command} creates a {aggregate} — pass {identity}:"}.freeze,
+        {"refusal"=>"AlreadyExists", "site"=>"creating_duplicate", "template"=>"{command} creates a {aggregate} that already exists — {identity} {offered}"}.freeze,
+        {"refusal"=>"AlreadyExists", "site"=>"entity_duplicate", "template"=>"a {entity} already exists on {aggregate} — {identity} {offered}"}.freeze,
+        {"refusal"=>"NotFound", "site"=>"acting_no_identity", "template"=>"{command} acts on an existing {aggregate} — pass {identity}:"}.freeze,
+        {"refusal"=>"NotFound", "site"=>"record_missing", "template"=>"no {aggregate} with {identity} {offered}"}.freeze,
+        {"refusal"=>"NotFound", "site"=>"entity_parent_no_identity", "template"=>"{command} acts on a {aggregate}'s {entity} — pass {identity}:"}.freeze,
+        {"refusal"=>"UnknownVerb", "site"=>"entity_unknown", "template"=>"{aggregate} has no entity {entity}"}.freeze,
+        {"refusal"=>"NotFound", "site"=>"entity_element_no_identity", "template"=>"{command} acts on one {entity} — pass {identity}:"}.freeze,
+        {"refusal"=>"NotFound", "site"=>"entity_element_missing", "template"=>"no {entity} with {identity} {wants} on {aggregate} {parent_id}"}.freeze,
+        {"refusal"=>"NotFound", "site"=>"reference_target_missing", "template"=>"no {target} with {heads} {key}"}.freeze,
+        {"refusal"=>"NotFound", "site"=>"read_model_reference_missing", "template"=>"no {aggregate} with reference {offered}"}.freeze,
+        {"refusal"=>"TypeMismatch", "site"=>"read_model_object_reference", "template"=>"{query} refused — a reference is an id, and {field} arrived as an object"}.freeze,
+        {"refusal"=>"UnknownVerb", "site"=>"no_query", "template"=>"{aggregate} has no query {query}"}.freeze,
+        {"refusal"=>"UnknownVerb", "site"=>"entity_query_missing", "template"=>"{entity} has no query {query}"}.freeze,
+        {"refusal"=>"UnknownVerb", "site"=>"entity_holds_no_list", "template"=>"{aggregate} holds no list of {entity}"}.freeze,
+        {"refusal"=>"UnknownVerb", "site"=>"entity_no_command", "template"=>"{entity} has no command {command}"}.freeze,
+        {"refusal"=>"UnknownVerb", "site"=>"aggregate_no_command", "template"=>"{aggregate} has no command {command}"}.freeze,
+        {"refusal"=>"UnknownVerb", "site"=>"port_no_operation", "template"=>"{port} has no operation {operation}"}.freeze,
+        {"refusal"=>"UnknownVerb", "site"=>"no_domain", "template"=>"no domain {domain} loaded (verb {verb})"}.freeze,
+        {"refusal"=>"UnknownVerb", "site"=>"no_read_model", "template"=>"{domain} has no read model {query}"}.freeze,
+        {"refusal"=>"UnknownVerb", "site"=>"not_fully_qualified", "template"=>"{verb} is not a fully-qualified verb (Domain::Aggregate.Command)"}.freeze,
+        {"refusal"=>"UnknownVerb", "site"=>"no_aggregate", "template"=>"{domain} has no aggregate {aggregate}"}.freeze,
+        {"refusal"=>"LifecycleRefused", "site"=>"transition_blocked", "template"=>"{command} refused — {field} is {current}, and {command} moves it only from {allowed}"}.freeze,
+        {"refusal"=>"TypeMismatch", "site"=>"value_object_shape", "template"=>"{name} is a {type} — pass its fields as an object, not {offered}"}.freeze,
+        {"refusal"=>"TypeMismatch", "site"=>"reference_as_object", "template"=>"{command} refused — a reference is an id, and {attribute} arrived as an object{known_by}"}.freeze,
+        {"refusal"=>"TypeMismatch", "site"=>"multi_field_scalar", "template"=>"{type} has multiple fields and cannot stand in for a scalar"}.freeze,
+        {"refusal"=>"TypeMismatch", "site"=>"composite_identity", "template"=>"{type} is a composite identity — an identity must have exactly one field"}.freeze,
+        {"refusal"=>"TypeMismatch", "site"=>"numeric_field", "template"=>"{type}.{field} expects {expected}, got {offered}"}.freeze,
+        {"refusal"=>"TypeMismatch", "site"=>"non_finite_field", "template"=>"{type}.{field} must be a finite number, got {offered}"}.freeze,
+        {"refusal"=>"TypeMismatch", "site"=>"pattern_mismatch", "template"=>"{type}.{field} must match {pattern}, got {offered}"}.freeze,
+        {"refusal"=>"TypeMismatch", "site"=>"arithmetic_amount", "template"=>"{op} of {target} needs an Integer, got {offered}"}.freeze,
+        {"refusal"=>"TypeMismatch", "site"=>"arithmetic_current", "template"=>"{op} of {target} needs an Integer {target}, got {offered}"}.freeze,
+        {"refusal"=>"TypeMismatch", "site"=>"arithmetic_shared_field", "template"=>"{op} of {target} needs a value object with one shared Integer field"}.freeze,
+        {"refusal"=>"UnknownArgument", "site"=>"unknown_args", "template"=>"{command} does not declare {unknown} — it takes {declared}"}.freeze,
+        {"refusal"=>"AbsentArgument", "site"=>"absent_args", "template"=>"{command} was not given {absent} — it takes {declared}"}.freeze,
+        {"refusal"=>"InvariantViolation", "site"=>"closed_set_member", "template"=>"{type} admits {admitted} — got {offered}"}.freeze,
+        {"refusal"=>"InvariantViolation", "site"=>"value_object_invariant", "template"=>"{name} invariant violated — {description} (given {offered})"}.freeze,
+        {"refusal"=>"InvariantViolation", "site"=>"admits_declared_set", "template"=>"{name} admits {admits} — {admitted} — got {offered}"}.freeze,
+        {"refusal"=>"InvariantViolation", "site"=>"undeclared_set", "template"=>"{name} admits {admits}, which this chapter does not declare — a closed set is named Aggregate::SetName, and it must be one the bluebook actually holds"}.freeze,
+        {"refusal"=>"Unauthorized", "site"=>"tenant_required", "template"=>"{query} declares authorize with tenant: {field} — pass {field}: to name which {field} this ask is scoped to"}.freeze,
+        {"refusal"=>"Unauthorized", "site"=>"role_mismatch", "template"=>"{command} refused — role: {role}, and the caller stated {caller_role}"}.freeze,
+        {"refusal"=>"AttributeAbsent", "site"=>"absent_read", "template"=>"{aggregate} {field} is absent on this record — declared, not optional, and added since it was written. Backfill it in a translation (backfill :{field}, default: ...), or declare it optional: true"}.freeze,
+        {"refusal"=>"ProjectionAbsent", "site"=>"absent_read", "template"=>"{aggregate} {field} is not yet projected on this record — declared via projects :{field}, but no rebuild sweep has populated it. Run the sweep, or read {reference}.{remote_field} directly if this rule cannot wait"}.freeze
+      ].freeze,
+      "SignTest" => [
+        {"name"=>"positive?", "compares_via"=>">"}.freeze,
+        {"name"=>"negative?", "compares_via"=>"<"}.freeze,
+        {"name"=>"zero?", "compares_via"=>"=="}.freeze
+      ].freeze,
+      "SizedType" => [
+        {"type"=>"Array"}.freeze,
+        {"type"=>"String"}.freeze,
+        {"type"=>"Hash"}.freeze
+      ].freeze,
+      "ToStringType" => [
+        {"type"=>"String"}.freeze,
+        {"type"=>"Integer"}.freeze,
+        {"type"=>"Float"}.freeze,
+        {"type"=>"TrueClass"}.freeze,
+        {"type"=>"FalseClass"}.freeze,
+        {"type"=>"NilClass"}.freeze
+      ].freeze,
+      "Trigger" => [
+        {"name"=>"refused"}.freeze
+      ].freeze,
+      "VocabularyName" => [
+
+      ].freeze
+    }.freeze
+
+    # THE TERMS — the first field of each row, which for a
+    # one-field vocabulary is the whole of it. Derived ONCE and
+    # frozen rather than mapped per call: these are constant
+    # tables, and a constant that allocates a new array every
+    # time it is read is not one.
+    TERMS = TABLES.transform_values { |rows| rows.map { |row| row.values.first }.freeze }.freeze
+
+    module_function
+
+    # Refuses an unknown name rather than answering nil: a set
+    # the language does not declare is a typo, not an empty set.
+    def fetch(name) = TERMS.fetch(name)
+
+    # The rows whole, for the vocabularies that carry more than
+    # a term — Comparison's own algebra, RefusalTemplate's text.
+    def rows(name) = TABLES.fetch(name)
+
+    def symbols(name) = fetch(name).map(&:to_sym)
+
+    def names = TABLES.keys
+  end
+end

data/lib/hecks.rb

@@ -1,6 +1,123 @@
-# frozen_string_literal: true
-require 'thor'
-require 'hecks-adapters-dynamodb'
-require 'hecks-plugins-json-validator'
-require_relative 'cli/hecks-cli'
-require_relative 'console/hecks-console'
+require_relative "hecks/version"
+# The closed sets the runtime computes with, generated from
+# vocabulary.bluebook. Plain data, required first, because some of
+# them are read while a bluebook is still being parsed.
+require_relative "hecks/vocabulary"
+require_relative "hecks/rendering"
+require_relative "hecks/naming"
+require_relative "hecks/fqn"
+require_relative "hecks/freezer"
+require_relative "hecks/construct"
+# Before `bluebook` — every construct under `Bluebook` includes or
+# extends this to declare what it emits.
+require_relative "hecks/ir"
+require_relative "hecks/literal"
+require_relative "hecks/facade"
+require_relative "hecks/query_specification"
+
+require_relative "hecks/ports"
+require_relative "hecks/bluebook"
+require_relative "hecks/router"
+
+require_relative "hecks/runtime"
+require_relative "hecks/adapters"
+require_relative "hecks/projector"
+# AFTER the projector registry and its `Target` mixin are both real —
+# every target registers itself as it loads, so this require IS the
+# installation of them.
+require_relative "hecks/projections"
+# AFTER `Projector` (dispatches against the `:cli` projection) and
+# `Ports::Clock` (fills a staleness rule's `now` at the door) both exist.
+require_relative "hecks/facade/cli_door"
+require_relative "hecks/facade/cli_runner"
+require_relative "hecks/storehouse"
+require_relative "hecks/framework"
+require_relative "hecks/embryonaut_bluebook"
+
+module Hecks
+  class LoadOutsideBoot < StandardError; end
+
+  class << self
+    attr_reader :current_registry
+
+    # The loading words below collect into the registry the RUNTIME is
+    # holding open ; booting and that ambient state belong to the runtime
+    # layer, so this module is their facade and Hecks::Runtime is where
+    # they live.
+    # `install_facade:` — see Runtime::Loader.boot. Defaults on; a caller
+    # that only dispatches by FQN string can skip the global sugar.
+    #
+    # `environment:` — RECOVERED, not new: this parameter (and the
+    # `environments/<name>.hecksagon` / `.world` overlay it loads —
+    # see Adapters::Folder#load_domain) existed on a prior commit of
+    # this repo (933d1dd), was vendored out to a real consumer
+    # (lifeadelics/domain), and was then lost from this repo's own
+    # history (no branch here reaches that commit). Ported forward
+    # from the consumer's vendor snapshot — the only surviving copy —
+    # and generalized: the original only loaded a `.hecksagon`
+    # overlay; this also loads a same-named `.world` overlay, both
+    # merged into the base rather than replacing it (Registry#add_hecksagon
+    # / #add_world). hecks never reads ENV itself — a caller
+    # resolves its own env var name and passes the resulting string
+    # straight through, e.g. `Hecks.boot(path, environment:
+    # ENV.fetch("MYAPP_ENV", "development"))`.
+    def boot(path, shared: nil, install_facade: true, environment: nil)
+      Runtime.boot(path, shared: shared, install_facade: install_facade, environment: environment)
+    end
+
+    # `paths` — an explicit list of files to boot (a `.bluebook`, its
+    # `.hecksagon`, optionally a `.world`), loaded in place from wherever
+    # they actually live — see Runtime::Loader.boot_files's own header for
+    # why this exists beside `boot` rather than as a special case of it.
+    def boot_files(paths, shared: nil, install_facade: true, environment: nil)
+      Runtime.boot_files(paths, shared: shared, install_facade: install_facade, environment: environment)
+    end
+
+    def with_registry(registry, &block) = Runtime.with_registry(registry, &block)
+
+    def current_registry = Runtime.current_registry
+
+    # Bind who is dispatching for the duration of the block — checked
+    # against a command's declared `role`, if it has one. Unbound (the
+    # default), a command's role stays exactly what it is without this:
+    # decoration.
+    #
+    # `actor_id` is OPTIONAL — a caller naming only a role is checked by
+    # string equality against the command's own `role`, exactly as
+    # before. A caller that also names WHO it is lets the check run
+    # against a real Governance `RoleAssignment` instead, once the
+    # command's domain has Governance attached — see
+    # `CommandRules::Authorization`'s own header.
+    #
+    # `as_of` and `scope` are OPTIONAL too, same shape — see
+    # `Runtime.as_caller`'s own header for what each does.
+    def as_caller(role:, actor_id: nil, as_of: nil, scope: nil, &block)
+      Runtime.as_caller(role: role, actor_id: actor_id, as_of: as_of, scope: scope, &block)
+    end
+
+    def bluebook(name, version: nil, &block)
+      collect(:add_bluebook, Bluebook::DSL::BluebookBuilder.build(name, version: version, &block))
+    end
+
+    def hecksagon(name, &block) = collect(:add_hecksagon, Bluebook::DSL::HecksagonBuilder.build(name, &block))
+    def port(name, &block) = collect(:add_port, Bluebook::DSL::PortBuilder.build(name, &block))
+    def adapter(name, &block)   = collect(:add_adapter, Bluebook::DSL::AdapterBuilder.build(name, &block))
+    def world(name, &block)     = collect(:add_world, Bluebook::DSL::WorldBuilder.build(name, &block))
+
+    def data_translation(name, from:, to:, &block)
+      collect(:add_translation, Bluebook::DSL::TranslationBuilder.build(name, from: from, to: to, &block))
+    end
+
+    private
+
+    def collect(method, item)
+      unless Runtime.current_registry
+        raise LoadOutsideBoot,
+              "declaration loaded outside a boot — use Hecks.boot(path) rather than requiring the file directly"
+      end
+
+      Runtime.current_registry.public_send(method, item)
+      item
+    end
+  end
+end

data/lib/rubocop/cop/hecks/fallback_hash_lookup.rb

@@ -0,0 +1,90 @@
+module RuboCop
+  module Cop
+    module Hecks
+      # FLAGS THE EXACT SHAPE behind 8+ real bugs already fixed one at a
+      # time across this codebase (Tiers 1-5): `holder[a] || holder[b]` —
+      # the SAME receiver looked up by two different keys, falling back to
+      # the second lookup whenever the first is falsy. `||` cannot tell a
+      # genuinely STORED `false` from a MISSING key — both are falsy in
+      # Ruby — so a real `false` sitting at `holder[a]` is silently
+      # discarded and `holder[b]` (usually absent, so `nil`) is returned
+      # instead. Every one of those 8+ instances was the identical
+      # AST shape with a different pair of keys (most commonly
+      # `h[k.to_sym] || h[k]`, reading a value that could arrive keyed
+      # either by symbol or by string off the wire).
+      #
+      # THE FIX THIS CODEBASE ALREADY CONVERGED ON — see
+      # `lib/hecks/query_specification/field_path.rb#read`, the shared
+      # digger this whole bug class got consolidated behind: check
+      # `key?` FIRST, never fall back through `||`.
+      #
+      #   sym = segment.to_sym
+      #   return current.key?(sym) ? current[sym] : current[segment]
+      #
+      # That method's own comment says it plainly: "`key?` first, never
+      # `||`, because `||` falls through a genuinely-stored `false` to
+      # the OTHER spelling (usually absent) and returns `nil` instead."
+      # This cop exists so the NEXT `holder[a] || holder[b]` gets caught
+      # mechanically, before it becomes bug #9, rather than found by
+      # hand again in a future audit.
+      #
+      # SCOPED TO THE `[]`/`[]` SHAPE ONLY, deliberately — a receiver
+      # method-call is compared by AST structure (`==`, which ignores
+      # source location), so `hash[a] || hash[b]` is flagged whether
+      # `hash` is a local variable, a method call, or a constant, but
+      # `a[k] || b[k]` (DIFFERENT receivers) and `value || default`
+      # (an ordinary default, not a second lookup at all) are both left
+      # alone — neither one can silently drop a stored `false` the way
+      # a same-receiver double-lookup can.
+      #
+      # @example
+      #   # bad — a stored `false` at hash[:active] is discarded
+      #   hash[:active] || hash["active"]
+      #
+      #   # good
+      #   hash.key?(:active) ? hash[:active] : hash["active"]
+      #
+      #   # good — or the shared digger this codebase already has
+      #   Hecks::QuerySpecification::FieldPath.dig(hash, "active")
+      class FallbackHashLookup < Base
+        MSG = "`%<receiver>s[...] || %<receiver>s[...]` falls back to the second lookup " \
+              "whenever the first is falsy — but `||` cannot tell a genuinely stored `false` " \
+              "apart from a missing key, so a real `false` at `%<receiver>s[%<lhs_key>s]` is " \
+              "silently discarded in favor of `%<receiver>s[%<rhs_key>s]` instead of being " \
+              "returned. Use `%<receiver>s.key?(%<lhs_key>s) ? %<receiver>s[%<lhs_key>s] : " \
+              "%<receiver>s[%<rhs_key>s]`, or a shared digger (see `key?` in " \
+              "`Hecks::QuerySpecification::FieldPath#read`), instead."
+
+        # @!method bracket_lookup(node)
+        def_node_matcher :bracket_lookup, "(send $_receiver :[] $_key)"
+
+        def on_or(node)
+          lhs_receiver, lhs_key = bracket_lookup(node.lhs)
+          return unless lhs_receiver
+
+          rhs_receiver, rhs_key = bracket_lookup(node.rhs)
+          return unless rhs_receiver
+
+          # THE STRUCTURAL EQUALITY CHECK — `==` on an AST node (from the
+          # `ast` gem `Node` this compiles down to) compares `type` and
+          # `children` recursively and ignores source location, so
+          # `hash[a] || hash[b]` matches even though the two `hash`
+          # sub-nodes are two distinct node OBJECTS parsed from two
+          # different source ranges. A different receiver on each side
+          # (`a[k] || b[k]`) fails this check and is correctly left alone.
+          return unless lhs_receiver == rhs_receiver
+
+          add_offense(
+            node,
+            message: format(
+              MSG,
+              receiver: lhs_receiver.source,
+              lhs_key:  lhs_key.source,
+              rhs_key:  rhs_key.source
+            )
+          )
+        end
+      end
+    end
+  end
+end

data/lib/rubocop/cop/hecks/sequential_hash_rename_in_loop.rb

@@ -0,0 +1,128 @@
+module RuboCop
+  module Cop
+    module Hecks
+      # FLAGS `hash[new] = hash.delete(old)` INSIDE A LOOP — a method that
+      # both READS and WRITES the same hash across a loop's iterations,
+      # in the specific rename/permutation shape this codebase has
+      # already lost real data to once.
+      #
+      # THE BUG THIS IS THE MECHANICAL FOLLOW-UP TO (M27,
+      # docs/audits/2026-08-10-main-bug-audit.md,
+      # docs/audits/2026-08-11-bug-triage.md; fixed in
+      # `Hecks::Ports::Persistence::Lineage#apply_renames`,
+      # lib/hecks/ports/persistence/plugins/era/lineage.rb): a rename
+      # rule set applied one rule at a time, `state[new_name] =
+      # state.delete(old_name)` per rule, against the SAME hash it was
+      # reading from — so a swap (`rename :a, to: :b` alongside `rename
+      # :b, to: :a`) on `{a: 1, b: 2}` collapsed to `{a: 1}`. The first
+      # rule wrote `b: 1` (clobbering the real `b: 2`) before the second
+      # rule ever got a chance to read the value that was supposed to
+      # move to `:a` — sequential edits stepping on each other, not the
+      # simultaneous permutation a rename set actually means. The same
+      # shape loses data identically for ANY chain longer than one link
+      # (`a->b->c->a`), not just a two-element swap.
+      #
+      # THE FIX THIS COP POINTS AT — snapshot every old key's value
+      # FIRST, delete all old keys, THEN write all new keys, so no
+      # rename in the pass ever reads a key this same pass has already
+      # written:
+      #
+      #   snapshot = renames.filter_map { |old_name, new_name| [old_name, new_name, state[old_name]] if state.key?(old_name) }
+      #   snapshot.each { |old_name, _new_name, _value| state.delete(old_name) }
+      #   snapshot.each { |_old_name, new_name, value| state[new_name] = value }
+      #
+      # WHAT THIS COP DOES NOT ATTEMPT — the general checklist item is
+      # broader than any AST pattern can safely automate ("any method
+      # that both reads and writes the same collection across a loop"
+      # covers plenty of correct code too — accumulating into a result
+      # hash, memoizing into a cache). This cop stays narrow and
+      # precise: only the EXACT `recv[x] = recv.delete(y)` shape, same
+      # receiver both sides, inside something that iterates. A single
+      # rename outside any loop is not this bug (nothing else can have
+      # run first); `hash.store(...)` instead of `hash[...] =`, or
+      # `hash.delete(...)` whose result is not immediately written back
+      # into the SAME hash, are not this shape either and are left to
+      # the broader code-review checklist item, not this cop.
+      #
+      # @example
+      #   # bad — one rule at a time against the hash it reads from
+      #   renames.each do |old_name, new_name|
+      #     state[new_name] = state.delete(old_name)
+      #   end
+      #
+      #   # good — snapshot first, then delete, then write: one permutation
+      #   snapshot = renames.filter_map { |old_name, new_name| [old_name, new_name, state[old_name]] if state.key?(old_name) }
+      #   snapshot.each { |old_name, _new_name, _value| state.delete(old_name) }
+      #   snapshot.each { |_old_name, new_name, value| state[new_name] = value }
+      class SequentialHashRenameInLoop < Base
+        MSG = "`%<recv>s[new] = %<recv>s.delete(old)` inside a loop applies one rename at a time against the " \
+              "SAME hash it reads from — a swap (`{a: :b, b: :a}`) on `{a: 1, b: 2}` collapses to `{a: 1}` " \
+              "because the first rule's write clobbers the second rule's read target before it runs (the exact " \
+              "bug fixed for Lineage#apply_renames). Snapshot every old key's value FIRST, delete all old keys, " \
+              "then write all new keys, so the pass applies as one simultaneous permutation instead of a " \
+              "sequence of edits each stepping on the last."
+
+        RESTRICT_ON_SEND = [:[]=].freeze
+
+        LOOP_METHODS = %i[
+          each each_pair each_with_index each_with_object with_index
+          map collect flat_map each_entry each_key each_value
+          inject reduce each_slice each_cons
+        ].freeze
+
+        # `hash[new_name] = hash.delete(old_name)` parses as a `send`
+        # node (indexed assignment has no dedicated node type in Ruby's
+        # own grammar): `(send recv :[]= new_key (send recv2 :delete
+        # old_key))`. `$_recv`/`$_recv2` are captured (not merely
+        # matched) so `same_receiver?` below can compare them
+        # structurally — node-pattern has no built-in "same subtree
+        # twice" backreference, so the equality check is real Ruby, not
+        # the pattern itself.
+        def_node_matcher :rename_write?, <<~PATTERN
+          (send $_recv :[]= _new_key (send $_recv2 :delete _old_key))
+        PATTERN
+
+        def on_send(node)
+          rename_write?(node) do |recv, recv2|
+            next unless same_receiver?(recv, recv2)
+            next unless in_loop?(node)
+
+            add_offense(node, message: format(MSG, recv: recv.source))
+          end
+        end
+
+        private
+
+        # Structural equality (type + children, recursively) — exactly
+        # what `Parser::AST::Node#==` already gives, ignoring source
+        # location, so `state` vs `state` (two separate `send(nil,
+        # :state)` reader calls) and `@state` vs `@state` both count as
+        # "the same collection", not just an identical local variable.
+        def same_receiver?(recv, recv2)
+          recv == recv2
+        end
+
+        # Walks every ancestor looking for something that iterates —
+        # not just the immediate parent, since the offending assignment
+        # may sit one or more non-loop nodes deep inside a loop's block
+        # (an `if` guarding it, say) and still carries the exact same
+        # hazard.
+        def in_loop?(node)
+          node.each_ancestor(:block, :numblock, :for, :while, :until, :while_post, :until_post).any? do |ancestor|
+            loop_ancestor?(ancestor)
+          end
+        end
+
+        def loop_ancestor?(ancestor)
+          case ancestor.type
+          when :for, :while, :until, :while_post, :until_post
+            true
+          when :block, :numblock
+            send_node = ancestor.send_node
+            send_node.send_type? && LOOP_METHODS.include?(send_node.method_name)
+          end
+        end
+      end
+    end
+  end
+end