hecks 2.8.0 → 2.9.0

data/lib/hecks/tenancy/bluebook/tenancy.bluebook

@@ -1,15 +1,5 @@
-# ITS OWN BOUNDED CONTEXT, booted centrally like `Deploy` — never
-# attached via `uses_framework` (a framework member's aggregate folds
-# into the ATTACHING domain's own per-boot registry, framework.rb:43-66
-# — since hecks gives each tenant its own separate `Runtime.boot`, a
-# framework-attached Tenant would exist as a single-row copy inside
-# EVERY tenant's own boot, never as one cross-tenant list, defeating
-# this domain's whole point). `Deploy::Tenant` (deploy.bluebook) stays
-# a SEPARATE, validation-only aggregate — a shape check before
-# provisioning; this is the durable, reactable runtime fact that
-# aggregate's own comment named and deliberately deferred. Two
-# different meanings of "Tenant," on purpose, translated at the one
-# explicit seam `tenancy.hecksagon`'s own `translates` line names.
+# Its own bounded context, booted centrally like `Deploy` and never attached via `uses_framework`:
+# an attached Tenant would be a single-row copy in every tenant's boot, not one cross-tenant list.
 Hecks.bluebook "Tenancy" do
   vision "Which tenants exist, which realm and storage each one owns, and whether each is currently allowed to run, is one queryable, historical fact — not scattered across a world-file overlay and a validation-only command."
 
@@ -50,14 +40,8 @@ Hecks.bluebook "Tenancy" do
       attribute :value, String, one_of: ["Active", "Suspended", "Retired"]
     end
 
-    # FIRES AFTER PROVISIONING, NEVER BEFORE — a pure record with no
-    # side effects, dispatched by `tenancy.hecksagon`'s own `translates`
-    # reaction once `Deploy::Tenant.Provision`'s adapter has already
-    # written the world overlay and proven the domain boots. Driving
-    # provisioning FROM this command's own emission would need a
-    # process manager reacting to it — the exact durable-saga cost
-    # `deploy.bluebook`'s own `Tenant` aggregate comment already argued
-    # three local, idempotent, single-process steps don't need.
+    # Fires after provisioning, never before: driving provisioning from this command's emission
+    # would need a process manager, the durable-saga cost `deploy.bluebook` argues against.
     command "Register" do
       goal "Record that a tenant now exists, after its shape has been validated and its schema provisioned"
 
@@ -74,13 +58,8 @@ Hecks.bluebook "Tenancy" do
       emits "TenantRegistered"
     end
 
-    # RECORD-ONLY — nothing today reads `status` before dispatch or
-    # boot, so suspending a tenant here does not yet stop anything from
-    # running. Spelled out in this command's own `goal`, not just a
-    # comment, so it survives into generated docs/corpus rather than
-    # quietly reading as enforced when it isn't — the exact "a dial
-    # says a check runs when nothing runs it" defect class this
-    # project has already been burned by once.
+    # Record-only: nothing reads `status` before dispatch or boot yet. Stated in the `goal` too,
+    # so generated docs do not read it as enforced.
     command "Suspend" do
       goal "Record that a tenant should no longer be treated as active — nothing yet enforces this at dispatch or boot time"
 
@@ -101,11 +80,8 @@ Hecks.bluebook "Tenancy" do
       emits "TenantReactivated"
     end
 
-    # RECORD-ONLY, DELIBERATELY — dropping a live Postgres schema as an
-    # automatic side effect of a command handler would break the pure,
-    # no-adapter-calls-from-a-handler shape every other command in this
-    # corpus holds to. Real teardown, if ever built, is its own
-    # separate, deliberately reviewed tool — never implicit here.
+    # Record-only: dropping a live schema from a command handler would break the pure, no-adapter
+    # handler shape. Teardown, if built, is a separate reviewed tool.
     command "Retire" do
       goal "Record that a tenant is permanently done — real schema teardown is a deliberately separate, manually-run tool, never automatic here"
 

data/lib/hecks/tenancy/bluebook/tenancy.hecksagon

@@ -1,30 +1,13 @@
 Hecks.hecksagon "Tenancy" do
   Tenancy::Tenant.persisted_by("LocalStorage")
 
-  # THE TRANSLATION SEAM — the one explicit place Deploy's "Tenant"
-  # (a validated request) becomes Tenancy's "Tenant" (a durable fact).
-  # `on` deliberately omits the "Deploy::" prefix: PolicyInterpreter
-  # matches by event name plus the emitting aggregate's own demodulised
-  # name only, never the domain (confirmed live — a domain-qualified
-  # `on` silently never matches).
+  # The one seam where Deploy's "Tenant" (a validated request) becomes Tenancy's "Tenant" (a fact).
+  # `on` omits the "Deploy::" prefix: PolicyInterpreter matches event and aggregate name only.
+  # `with:` is required: the event payload also carries the port's dispatch-time args, which
+  # `Register` does not declare and would refuse.
   #
-  # `with:` IS REQUIRED, confirmed live — `TenantProvisioned`'s own
-  # payload is the ANSWER (slug/domain/realm/schema) merged with the
-  # port operation's OWN dispatch-time args (database/adapter,
-  # PortOperationInterpreter#ask's `ctx.args.merge(spread(answer))`),
-  # so the whole payload forwarded verbatim carries two fields
-  # `Register` never declares and gets refused outright.
-  # CHECKED TOGETHER, NOT IN ISOLATION — `bin/model_check`'s own
-  # `deaf_policy` check only sees ONE domain's own emitted events by
-  # default, which would flag this reaction as deaf (it reacts to a
-  # FOREIGN event, not one Tenancy itself emits). Fixed by
-  # `global_emitted_events:`, a cross-domain set `bin/model_check`
-  # builds across every target it boots in one run — run `bin/model_check
-  # lib/hecks/deploy lib/hecks/tenancy` (both targets, one invocation),
-  # not each directory separately, or this reads as a false positive
-  # again. Neither `deploy` nor `tenancy` is in
-  # `Hecks::Corpus::MODEL_CHECK_KINDS`, so the automatic sweep never
-  # reaches this at all, checked or not.
+  # Check with `bin/model_check lib/hecks/deploy lib/hecks/tenancy` in one run; alone, the
+  # reaction to a foreign event reads as a deaf policy.
   translates "RegisterProvisionedTenant" do
     on Tenant::TenantProvisioned
     trigger Tenant::Register, with: { slug: :slug, domain: :domain, realm: :realm, schema: :schema }

data/lib/hecks/vendoring/git_environment.rb

@@ -1,13 +1,7 @@
 module Hecks
   module Vendoring
-    # The environment a `git` subprocess needs so it resolves its repository
-    # from the directory it is pointed at, not from whoever launched Ruby.
-    #
-    # Git exports `GIT_DIR`, `GIT_INDEX_FILE` and their kin to the hooks it
-    # runs (a push from a linked worktree runs `pre-push` this way). Every
-    # `git` that a hook's process tree starts inherits them, and they outrank
-    # both `git -C` and the working directory: a command aimed at a scratch
-    # repository would read, or commit into, the repository that was pushing.
+    # The environment a `git` subprocess needs to target one repository:
+    # inherited GIT_DIR variables outrank `-C` and would redirect it elsewhere.
     module GitEnvironment
       # The variables that pin git to one repository, work tree or index.
       INHERITED = %w[

data/lib/hecks/vendoring/git_source.rb

@@ -4,14 +4,8 @@ require_relative "git_environment"
 
 module Hecks
   module Vendoring
-    # A local git repository read through the `git` executable, never through
-    # its working tree.
-    #
-    # Everything here names a commit and reads what that commit holds, so a
-    # shared checkout with uncommitted edits, or a different branch checked
-    # out, cannot leak into what gets vendored. Every command runs under
-    # {GitEnvironment.clean}, so a `GIT_DIR` inherited from a hook cannot
-    # redirect it to some other repository.
+    # Reads one commit of a local git repository via the `git` executable,
+    # under {GitEnvironment.clean} so an inherited `GIT_DIR` can't redirect it.
     class GitSource
       # @param path [String] a directory that is a git repository (or a
       #   worktree of one)
@@ -57,8 +51,8 @@ module Hecks
 
       # Lists the files directly inside a directory of a commit.
       #
-      # Subdirectories are left out on purpose: a vendored package carries the
-      # top-level files of its subtree and nothing nested beneath.
+      # Subdirectories are excluded on purpose; only the subtree's own
+      # top-level files are vendored.
       #
       # @param ref [String] the commit-ish to read from
       # @param subtree [String] a repository-relative directory, such as `"payments/bluebook"`

data/lib/hecks/vendoring.rb

@@ -5,29 +5,7 @@ require_relative "vendoring/git_source"
 
 module Hecks
   # Pins an exact commit of one directory of another repository into a
-  # project's own tree.
-  #
-  # ## What it is
-  #
-  # A project that consumes a package from a private repository cannot clone
-  # that repository when its image builds, and a live pull would make the build
-  # depend on whatever is checked out. So the files are exported from one
-  # commit, committed into the consumer, and a marker file beside them records
-  # which commit they came from. Only the files directly inside the named
-  # subtree are taken; the source's own specs, ports, adapters and data stay
-  # where they are.
-  #
-  # ## Marker
-  #
-  # `VENDORED_COMMIT` holds the full 40-character commit id and a newline, so
-  # `git -C <source> show <id>:<subtree>` reproduces the vendored files. The
-  # marker sits in `into`, beside the exported directory.
-  #
-  # ## Whole-directory replacement
-  #
-  # A pin replaces `into` entirely, so a file the source dropped does not
-  # linger. Nothing is touched until the export succeeded and the optional
-  # block accepted it.
+  # project's own tree, so a build doesn't depend on a live clone.
   module Vendoring
     # Raised when a pin cannot be made or is refused.
     class Error < StandardError; end
@@ -45,27 +23,17 @@ module Hecks
     #   @return [Array<String>] the exported files' names, sorted
     Pin = Struct.new(:commit, :dir, :files, keyword_init: true)
 
-    # Exports the top-level files of one directory at one commit into `into`.
-    #
-    # The exported files land in `into/<last segment of subtree>/`; the marker
-    # lands in `into` itself. The optional block sees the staged files before
-    # anything is replaced and may raise to refuse the pin.
+    # Exports the top-level files of one directory at one commit into `into`,
+    # replacing it wholly; the optional block may refuse before that happens.
     #
     # @param from [String] path of the local source repository
-    # @param ref [String] the commit-ish to export (branch, tag or commit id)
-    # @param subtree [String] repository-relative directory to export, such as
-    #   `"payments/bluebook"`
+    # @param ref [String] the commit-ish to export
+    # @param subtree [String] repository-relative directory to export
     # @param into [String] the directory to replace with the export
-    # @param glob [String] `File.fnmatch` pattern each exported file's name must match
+    # @param glob [String] pattern each exported file's name must match
     # @param marker [String] name of the file recording the commit
-    # @yield [staged, commit] the staged files, before `into` is touched
-    # @yieldparam staged [String] directory holding the exported files
-    # @yieldparam commit [String] the resolved commit id
-    # @yieldreturn [Hash{String => String}, nil] extra files to write into `into`,
-    #   keyed by file name; nil for none
     # @return [Pin] the commit and where the files landed
-    # @raise [Vendoring::Error] if the source is missing, `ref` names no commit,
-    #   the subtree holds no matching file, or the block refuses
+    # @raise [Vendoring::Error] if the source or a matching file is missing
     def self.pin(from:, ref:, subtree:, into:, glob: "*", marker: MARKER)
       source = GitSource.new(from)
       commit = source.commit(ref)
@@ -83,13 +51,6 @@ module Hecks
     end
 
     # Replaces `into` with the staged files, the marker and any extras.
-    #
-    # @param staged [String] directory holding the exported files
-    # @param into [String] the directory to replace
-    # @param marker [String] marker file name
-    # @param commit [String] commit id the marker records
-    # @param extras [Hash{String => String}] more files to write into `into`
-    # @return [void]
     def self.install(staged, into, marker, commit, extras)
       FileUtils.rm_rf(into)
       FileUtils.mkdir_p(into)

data/lib/hecks/version.rb

@@ -1,16 +1,5 @@
 module Hecks
-  # **Isolated, on purpose** — the gemspec reads this file directly rather
-  # than `require_relative "lib/hecks"` (the whole framework),
-  # specifically so evaluating the gemspec never triggers any of this
-  # gem's own dependencies (prism among them) before Bundler has even
-  # resolved what to install. A real, live chicken-and-egg bug caught
-  # deploying to a Ruby version that doesn't bundle prism for free
-  # (AWS Lambda's ruby3.2): the gemspec's own `require_relative
-  # "lib/hecks"` pulled in adapters/driven/prism.rb's
-  # unconditional `require "prism"`, which failed before Bundler ever
-  # read what the gemspec itself declared as a dependency — declaring
-  # it there, or even in the consuming Gemfile, never closed the gap,
-  # because gemspec evaluation happens before anything Bundler
-  # resolves is actually loadable yet.
-  VERSION = "2.8.0".freeze
+  # Read directly by the gemspec, so this file must never require the
+  # rest of the gem (its dependencies aren't resolved yet at that point).
+  VERSION = "2.9.0".freeze
 end

data/lib/hecks.rb

@@ -42,65 +42,33 @@ require_relative "hecks/embryonaut_bluebook"
 # packaged gem leaves it out (ADR 0066).
 Hecks.autoload(:Corpus, File.expand_path("hecks/corpus", __dir__))
 
-# The root namespace and public facade of the whole DSL/runtime: `Hecks.boot`/
-# `.boot_files` assemble a running domain from `.bluebook`/`.hecksagon`/
-# `.world` files, and `.bluebook`/`.hecksagon`/`.port`/`.adapter`/`.world`/
-# `.data_translation` are the top-level declaration words every such file
-# opens with, each collecting its built construct into the currently booting
-# Registry (`#collect`, private below).
+# Root namespace and public facade of the DSL/runtime: `Hecks.boot`/`.boot_files`
+# assemble a running domain from `.bluebook`/`.hecksagon`/`.world` files.
 module Hecks
   class LoadOutsideBoot < StandardError; end
 
   class << self
-    # 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
-    # (a client site's 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"))`.
-    #
+    # Boots a domain from `path`, assembling a running dispatcher from its
+    # `.bluebook`/`.hecksagon`/`.world` files. hecks never reads ENV itself —
+    # a caller resolves its own env var name and passes it as `environment`.
     # @param path [String] path to a domain directory, or a file inside one
     # @param shared [String, nil] a shared-root override; see `Runtime::Loader.boot`
-    # @param install_facade [Boolean] whether to install the `Widget::Item.Add`-style
-    #   Ruby facade constants for this boot
-    # @param environment [String, nil] the environment name whose
-    #   `environments/<name>.hecksagon`/`.world` overlay, if present, loads after the
-    #   domain's own
-    # @return [Runtime::Dispatcher, Runtime::RemoteDispatcher] the dispatcher bound
-    #   to the booted domain
+    # @param install_facade [Boolean] install the `Widget::Item.Add`-style facade
+    # @param environment [String, nil] env name; its `.hecksagon`/`.world` overlay,
+    #   if present, loads after the domain's own
+    # @return [Runtime::Dispatcher, Runtime::RemoteDispatcher] dispatcher bound to the domain
     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.
-    #
+    # Boots a domain from an explicit list of files (a `.bluebook`, its
+    # `.hecksagon`, optionally a `.world`) instead of a whole directory —
+    # see `Runtime::Loader.boot_files` for why this exists beside `boot`.
     # @param paths [String, Array<String>] one or more file paths within the domain
-    #   to load, instead of the whole directory
     # @param shared [String, nil] a shared-root override; see `Runtime::Loader.boot_files`
-    # @param install_facade [Boolean] whether to install the `Widget::Item.Add`-style
-    #   Ruby facade constants for this boot
-    # @param environment [String, nil] the environment name passed through to the
-    #   selected-file loader
-    # @return [Runtime::Dispatcher, Runtime::RemoteDispatcher] the dispatcher bound
-    #   to the booted domain
+    # @param install_facade [Boolean] install the `Widget::Item.Add`-style facade
+    # @param environment [String, nil] environment name passed to the selected-file loader
+    # @return [Runtime::Dispatcher, Runtime::RemoteDispatcher] dispatcher bound to the domain
     def boot_files(paths, shared: nil, install_facade: true, environment: nil)
       Runtime.boot_files(paths, shared: shared, install_facade: install_facade, environment: environment)
     end
@@ -117,21 +85,8 @@ module Hecks
     # @return [Runtime::Registry, nil] the current registry, or nil outside a boot
     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.
-    #
+    # Binds who is dispatching for the duration of the block, checked against
+    # a command's declared `role`; unbound (the default) is a no-op.
     # @param role [String, Symbol] the role to check the caller against
     # @param actor_id [String, nil] who is calling, checked against a real Governance
     #   `RoleAssignment` when given; string-equality only against `role` when nil
@@ -165,26 +120,16 @@ module Hecks
     # @return [Bluebook::Hecksagon] the built hecksagon
     # @raise [LoadOutsideBoot] if called outside `Hecks.boot`/`.boot_files`
     def hecksagon(name, &) = collect(:add_hecksagon, Bluebook::DSL::HecksagonBuilder.build(name, &))
-    # Repointed to DomainPortBuilder — the migration DomainPort's own
-    # class comment names as its goal, now landed for the top-level
-    # `.port` file callers too (the aggregate-scoped `Thing.port(...)`,
-    # binding_proxy.rb, already went through this builder). Every real
-    # `.port` file only ever spells `verb`/`signal` (no `.port` file
-    # declares operations — that's DomainPort's own newer shape), and
-    # DomainPortBuilder's own bare-verb branch produces the exact same
-    # `Port` object PortBuilder itself did (dsl_spec.rb's own byte-
-    # identity check) — a pure repoint, no behavior change for any
-    # existing caller reading `.verb`/`.signal` off what comes back.
+
+    # Declares a port — a `.port` file's top-level word.
     #
-    # `legacy_bare_port: true` — the one real semantic gap this repoint
-    # would otherwise open: `PortBuilder#build` never refused a
-    # completely empty build (no verb, no signal even), a real shape
-    # dsl_spec.rb's own "a port" tests exercise (`signal`-only, no
-    # `verb`). `DomainPortBuilder`'s own "declares no verb and no
-    # operations" refusal is real and correct for its other two callers
-    # (`BindingProxy#port`, `HecksagonBuilder#port_impl`) — only this,
-    # the literal top-level `.port` file entry point, keeps the older,
-    # looser rule (see `DomainPortBuilder#initialize`'s own comment).
+    # `legacy_bare_port: true` — only this entry point allows a completely
+    # empty port body; see `DomainPortBuilder#initialize`'s own doc.
+    #
+    # @param name [String] the port's name
+    # @yield the port's body, evaluated against a `Bluebook::DSL::DomainPortBuilder`
+    # @return [Bluebook::Port, Bluebook::DomainPort] the built port
+    # @raise [LoadOutsideBoot] if called outside `Hecks.boot`/`.boot_files`
     def port(name, &) = collect(:add_port, Bluebook::DSL::DomainPortBuilder.build(name, legacy_bare_port: true, &))
 
     # Declares an adapter — an `.adapter` file's top-level word.

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

@@ -1,55 +1,15 @@
 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).
+      # Flags `holder[a] || holder[b]`: the same receiver looked up by two keys, falling back
+      # to the second when the first is falsy.
       #
-      # ## The fix
-      #
-      # 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.
-      #
-      # ## Scope
-      #
-      # 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.
+      # `||` cannot tell a stored `false` from a missing key, so a real `false` at `holder[a]` is
+      # discarded. Different receivers (`a[k] || b[k]`) and plain defaults are left alone.
       #
       # @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")
+      #   hash[:active] || hash["active"]                      # bad
+      #   hash.key?(:active) ? hash[:active] : hash["active"]  # good
       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` " \
@@ -96,3 +56,5 @@ module RuboCop
     end
   end
 end
+
+# AST `==` ignores source location, so two parses of the same receiver compare equal.

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

@@ -1,67 +1,17 @@
 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 follows up on
-      #
-      # 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.
+      # Flags `hash[new] = hash.delete(old)` inside a loop.
+      # Applying renames one at a time to the hash being read loses data on swaps and chains.
       #
       # @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
+      #   # bad
+      #   renames.each { |old, new| state[new] = state.delete(old) }
       #
-      #   # 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 }
+      #   # good: snapshot the values, delete every old key, then write the new keys
+      #   pairs = renames.select { |old, _| state.key?(old) }.map { |old, new| [new, state[old]] }
+      #   renames.each_key { |old| state.delete(old) }
+      #   pairs.each { |new, value| state[new] = 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}` " \
@@ -78,22 +28,12 @@ module RuboCop
           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.
+        # Indexed assignment parses as a `send`. Both receivers are captured because node-pattern
+        # has no backreference; `same_receiver?` compares them.
         def_node_matcher :rename_write?, <<~PATTERN
           (send $_recv :[]= _new_key (send $_recv2 :delete _old_key))
         PATTERN
 
-        # Flags a `recv[new] = recv.delete(old)` write inside a loop, same receiver both sides.
-        #
-        # @param node [RuboCop::AST::SendNode] the `[]=` send node being visited
-        # @return [void]
         def on_send(node)
           rename_write?(node) do |recv, recv2|
             next unless same_receiver?(recv, recv2)
@@ -105,20 +45,11 @@ module RuboCop
 
         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.
+        # Checks every ancestor: a guard node may sit between the assignment and the loop block.
         def in_loop?(node)
           node.each_ancestor(:block, :numblock, :for, :while, :until, :while_post, :until_post).any? do |ancestor|
             loop_ancestor?(ancestor)