hecks 0.3.0 → 1.0.0

data/lib/hecks/naming.rb

@@ -61,7 +61,21 @@ module Hecks
     def singularize(text)
       word = text.to_s
       return "#{word[0..-4]}y" if word.length > 3 && word.end_with?("ies")
-      return word[0..-2]       if word.length > 1 && word.end_with?("s")
+
+      # `plural`'s OWN second rule adds "es" (not bare "s") after
+      # s/x/z/ch/sh — undone here the same way, or a word `plural`
+      # itself would have suffixed with "es" comes back missing its
+      # own trailing letter ("Boxes" -> "Boxe", not "Box") once this
+      # only ever knew how to drop a bare "s". Checked BEFORE the
+      # bare-"s" rule below: stripping "es" first and confirming what
+      # is left actually ends in one of those five shapes is what
+      # keeps an ordinary "-es" word (e.g. "Invoices" -> "Invoice")
+      # from also losing a letter it never doubled.
+      if word.length > 3 && word.end_with?("es") && word[0..-3].match?(/(s|x|z|ch|sh)\z/)
+        return word[0..-3]
+      end
+
+      return word[0..-2] if word.length > 1 && word.end_with?("s")
 
       word
     end
@@ -117,5 +131,44 @@ module Hecks
       path, _, command = text.rpartition("::")
       path.empty? ? text : "#{path}.#{command}"
     end
+
+    # `emits Account::AccountFrozen` / `on Account::AccountFrozen` — the
+    # event-side twin of `command_ref`, above (ADR 0025, S6 — "events
+    # first-class"). Identical transform (a bare `ScopedConstant`'s last
+    # `::` becomes `.`, a String passes through unchanged for legacy
+    # `shadow_parse` text and for corpus sites this pass didn't migrate —
+    # see that method's own comment for why both rules exist), given its
+    # own name because the two references mean different things even
+    # though the rewrite is byte-identical: an event name is not a
+    # command name that happens to share a format.
+    def event_ref(value) = command_ref(value)
+
+    # `transition Account::AccountDebited => "state"` / `starts_on
+    # Transfer::TransferRequested` / `ends_on Transfer::TransferSettled`
+    # — a process manager's OWN event references (ADR 0025, S6),
+    # DELIBERATELY NOT `event_ref` — found live, not assumed, wiring a
+    # real migrated corpus site into `bin/model_check` for the first
+    # time (2026-08-28): `SagaInterpreter#begin_saga`/`#advance_saga`
+    # match `pm.starts_on`/`pm.handler_for` against `event.name`, which
+    # `CommandRules::Emission#emit` stamps BARE — a command's own
+    # `emits AccountDebited` never carries its aggregate's name at all
+    # (unlike a policy's cross-aggregate `on`, matched instead by
+    # `Naming.demodulise(event.aggregate)` split apart from the bare
+    # name — `PolicyInterpreter#policies_for`). Handing a saga's own
+    # matcher the DOTTED `event_ref` form ("Account.AccountDebited")
+    # would silently name an event no command in the domain ever
+    # actually emits — caught by `bin/model_check`'s own `deaf_handler`/
+    # `deaf_trigger` findings the moment a real qualified corpus site
+    # existed to trip them, not by any unit test in isolation.
+    #
+    # A qualifier is still worth WRITING (`Account::`) — the same
+    # provenance a reader gets from `trigger Account::Debit` — it is
+    # only not worth KEEPING: `demodulise` drops everything but the
+    # final segment, so `Account::AccountDebited` and a bare
+    # `AccountDebited` resolve to the identical stored string. A String
+    # passes through unchanged either way, exactly like `command_ref`'s
+    # own legacy branch — this corpus never spelled one dotted to begin
+    # with, so there is nothing here to strip.
+    def event_name_ref(value) = demodulise(value)
   end
 end

data/lib/hecks/ports/access_control.port

@@ -1,4 +1,9 @@
 Hecks.port "access_control" do
-  verb   "granted_by"
-  signal :reply
+  verb    "granted_by"
+  signal  :reply
+  answers :session_for_identity
+  answers :provision
+  answers :available_roles
+  answers :grant
+  answers :all_people
 end

data/lib/hecks/ports/access_control.rb

@@ -47,7 +47,7 @@ module Hecks
         implementations = registry.adapters.values.select { |a| a.port == NAME }
 
         case implementations.size
-        when 1 then Adapters.const_get(implementations.first.name)
+        when 1 then registry.adapter_class(implementations.first.name)
         when 0
           raise Runtime::WiringError,
                 "no adapter implements the #{NAME} port — nothing can answer who's allowed in"

data/lib/hecks/ports/agent.port

@@ -1,4 +1,8 @@
 Hecks.port "agent" do
-  verb   "asked_by"
-  signal :reply
+  verb    "asked_by"
+  signal  :reply
+  answers :ask
+  answers :interpret
+  answers :critique
+  answers :suggest_name
 end

data/lib/hecks/ports/agent.rb

@@ -150,7 +150,7 @@ module Hecks
         implementations = registry.adapters.values.select { |a| a.port == NAME }
 
         case implementations.size
-        when 1 then Adapters.const_get(implementations.first.name)
+        when 1 then registry.adapter_class(implementations.first.name)
         when 0
           raise Runtime::WiringError,
                 "no adapter implements the #{NAME} port — nothing can conduct an interview"

data/lib/hecks/ports/authentication.port

@@ -1,4 +1,6 @@
 Hecks.port "authentication" do
-  verb   "authenticated_by"
-  signal :reply
+  verb    "authenticated_by"
+  signal  :reply
+  answers :authorization_url
+  answers :verify
 end

data/lib/hecks/ports/authentication.rb

@@ -35,7 +35,7 @@ module Hecks
         implementations = registry.adapters.values.select { |a| a.port == NAME }
 
         case implementations.size
-        when 1 then Adapters.const_get(implementations.first.name)
+        when 1 then registry.adapter_class(implementations.first.name)
         when 0
           raise Runtime::WiringError,
                 "no adapter implements the #{NAME} port — nothing can authenticate a sign-in"

data/lib/hecks/ports/authorization.port

@@ -1,4 +1,7 @@
 Hecks.port "authorization" do
-  verb   "authorized_by"
-  signal :reply
+  verb    "authorized_by"
+  signal  :reply
+  answers :holds_role?
+  answers :authorized_as?
+  answers :live_role_for
 end

data/lib/hecks/ports/authorization.rb

@@ -15,21 +15,24 @@ module Hecks
     # A caller decides what to DO with the answer — dispatch under that
     # role, refuse, log, prefer it over some other fallback value — this
     # only answers the question asked. Nothing here binds a
-    # `Runtime::Caller`, and nothing here is consulted by
-    # `CommandRules::Authorization`: that rule still only compares an
-    # ALREADY-BOUND caller's role against a command's, the same as it
-    # always has. `spec/act_as_spec.rb` remains the precedent for the
-    # OTHER shape — two separate registries, queried directly by name —
-    # for whenever Governance is not in the same boot as the caller;
-    # this port is the same two questions asked through one adapter
-    # when it is.
+    # `Runtime::Caller`.
+    #
+    # STALE AS OF THE `as_of`/`scope` split below, this used to also say
+    # nothing here is consulted by `CommandRules::Authorization` — it now
+    # is: `refuse_role_mismatch` calls `holds_role?` directly, once a
+    # caller binds an `actor_id` and the command's domain has Governance
+    # attached (see that rule's own header). `spec/act_as_spec.rb`
+    # remains the precedent for the OTHER shape — two separate
+    # registries, queried directly by name — for whenever Governance is
+    # not in the same boot as the caller; this port is the same
+    # questions asked through one adapter when it is.
     module Authorization
       NAME = "authorization"
 
       module_function
 
-      def holds_role?(registry, actor_id:, role:)
-        adapter(registry).holds_role?(registry, actor_id: actor_id, role: role)
+      def holds_role?(registry, actor_id:, role:, as_of: nil, scope: nil)
+        adapter(registry).holds_role?(registry, actor_id: actor_id, role: role, as_of: as_of, scope: scope)
       end
 
       def authorized_as?(registry, from_role:, to_role:)
@@ -44,7 +47,7 @@ module Hecks
         implementations = registry.adapters.values.select { |a| a.port == NAME }
 
         case implementations.size
-        when 1 then Adapters.const_get(implementations.first.name)
+        when 1 then registry.adapter_class(implementations.first.name)
         when 0
           raise Runtime::WiringError,
                 "no adapter implements the #{NAME} port — nothing can answer a role check"

data/lib/hecks/ports/clock.port

@@ -1,4 +1,5 @@
 Hecks.port "clock" do
-  verb   "timed_by"
-  signal :reply
+  verb    "timed_by"
+  signal  :reply
+  answers :now
 end

data/lib/hecks/ports/clock.rb

@@ -47,7 +47,7 @@ module Hecks
         implementations = registry.adapters.values.select { |a| a.port == NAME }
 
         case implementations.size
-        when 1 then Adapters.const_get(implementations.first.name)
+        when 1 then registry.adapter_class(implementations.first.name)
         when 0
           raise Runtime::WiringError,
                 "no adapter implements the #{NAME} port — nothing can say what time it is"

data/lib/hecks/ports/extraction.port

@@ -1,4 +1,5 @@
 Hecks.port "extraction" do
-  verb   "extracted_by"   
-  signal :reply           
+  verb    "extracted_by"
+  signal  :reply
+  answers :canonical
 end

data/lib/hecks/ports/extraction.rb

@@ -20,7 +20,7 @@ module Hecks
         implementations = registry.adapters.values.select { |a| a.port == NAME }
 
         case implementations.size
-        when 1 then Adapters.const_get(implementations.first.name)
+        when 1 then registry.adapter_class(implementations.first.name)
         when 0
           raise Runtime::WiringError,
                 "no adapter implements the #{NAME} port — nothing can recover a " \

data/lib/hecks/ports/identity_assignment.port

@@ -1,4 +1,5 @@
 Hecks.port "identity_assignment" do
-  verb   "assigned_by"
-  signal :reply
+  verb    "assigned_by"
+  signal  :reply
+  answers :assign
 end

data/lib/hecks/ports/identity_assignment.rb

@@ -30,7 +30,7 @@ module Hecks
         implementations = registry.adapters.values.select { |a| a.port == NAME }
 
         case implementations.size
-        when 1 then Adapters.const_get(implementations.first.name)
+        when 1 then registry.adapter_class(implementations.first.name)
         when 0
           raise Runtime::WiringError,
                 "no adapter implements the #{NAME} port — nothing can assign an identity"

data/lib/hecks/ports/identity_generation.port

@@ -1,4 +1,5 @@
 Hecks.port "identity_generation" do
-  verb   "generated_by"
-  signal :reply
+  verb    "generated_by"
+  signal  :reply
+  answers :uuid
 end

data/lib/hecks/ports/identity_generation.rb

@@ -34,7 +34,7 @@ module Hecks
         implementations = registry.adapters.values.select { |a| a.port == NAME }
 
         case implementations.size
-        when 1 then Adapters.const_get(implementations.first.name)
+        when 1 then registry.adapter_class(implementations.first.name)
         when 0
           raise Runtime::WiringError,
                 "no adapter implements the #{NAME} port — nothing can mint an identity"

data/lib/hecks/ports/identity_resolution.port

@@ -1,4 +1,5 @@
 Hecks.port "identity_resolution" do
-  verb   "resolved_by"
-  signal :reply
+  verb    "resolved_by"
+  signal  :reply
+  answers :resolve
 end

data/lib/hecks/ports/identity_resolution.rb

@@ -25,7 +25,7 @@ module Hecks
         implementations = registry.adapters.values.select { |a| a.port == NAME }
 
         case implementations.size
-        when 1 then Adapters.const_get(implementations.first.name)
+        when 1 then registry.adapter_class(implementations.first.name)
         when 0
           raise Runtime::WiringError,
                 "no adapter implements the #{NAME} port — nothing can resolve an identity"

data/lib/hecks/ports/persistence/append_only.rb

@@ -64,11 +64,32 @@ module Hecks
         def append(entry) = @adapter.append(entry)
         def project(entry) = @adapter.project(entry)
 
-        def save(instance)
+        # Returns an `Outcome`, not a bare `Instance` — every call site
+        # (`CommandInterpreter`/`EntityInterpreter`'s own `step_save`,
+        # `RebuildSweep#refresh`) reads it that way.
+        #
+        # `expected_version:` requests optimistic-concurrency CAS — commit
+        # only if the stored record's version still matches what THIS
+        # instance was read at. It is `nil` both when a caller explicitly
+        # doesn't want CAS (`RebuildSweep#refresh`'s own projection-field
+        # touch-up, which has no `given` to protect) and when the instance
+        # is brand new (never read from storage, so `instance.version` is
+        # nil) — both cases fall through to the plain, unconditional
+        # `project(entry)` below, byte-for-byte today's behavior. Only an
+        # adapter that both receives a non-nil `expected_version` AND
+        # declares `:optimistic_concurrency` gets CAS treatment; every
+        # other adapter/call site is unaffected.
+        def save(instance, expected_version: nil)
           entry = Entry.new(operation: "save", id: instance.id.to_s, state: instance.state.dup)
           append(entry)
-          project(entry)
-          instance
+          if expected_version && capabilities.include?(:optimistic_concurrency)
+            saved = @adapter.project(entry, expected_version: expected_version)
+            return Outcome.new(status: :stale, instance: instance) if saved.nil?
+
+            return Outcome.new(status: :saved, instance: saved)
+          end
+          saved = @adapter.project(entry)
+          Outcome.new(status: :saved, instance: saved || instance)
         end
 
         def atomic_put(instance, insert_only: false)
@@ -90,7 +111,22 @@ module Hecks
           true
         end
 
-        def record_event(event) = @adapter.record_event(event) if @adapter.respond_to?(:record_event)
+        # NOT an endless `def record_event = ... if ...` — same gotcha as
+        # `events` above, and it bit for real here: this guard evaluated
+        # against `@adapter` at class-body time (nil, always false), so
+        # `record_event` was never defined at all. `emission.rb`'s own
+        # `repository.record_event(event) if repository.respond_to?(:record_event)`
+        # therefore never fired for any adapter, ever — every declared
+        # `emits` was computed and reported in `registry.event_log` (an
+        # in-process array, gone at exit) but never durably recorded.
+        # Caught because a live tail of a domain's own persisted events
+        # found nothing to tail. `sqlite_spec.rb`/`postgres_spec.rb`/
+        # `postgres_era_spec.rb` all call `adapter.record_event` directly,
+        # bypassing this wrapper — which is exactly why no spec noticed.
+        def record_event(event)
+          @adapter.record_event(event) if @adapter.respond_to?(:record_event)
+        end
+
         def query_read_model(domain, model, args, bluebook = nil)
           return unless @adapter.respond_to?(:query_read_model)
 

data/lib/hecks/ports/persistence/execution.rb

@@ -3,7 +3,12 @@ module Hecks
     module Persistence
       # Adapter outcomes are runtime facts, never command lifecycle.
       Outcome = Struct.new(:status, :instance, keyword_init: true) do
-        STATUSES = %i[inserted replaced updated conflicted missing saved].freeze
+        # `:stale` is an optimistic-concurrency conflict on a plain `save`
+        # (someone else committed since this instance was read) — never a
+        # domain refusal, distinct from `:conflicted` (a `creates?`
+        # command's identity already exists, `AlreadyExists`). See
+        # `Runtime::StaleWrite` (runtime/errors.rb) and `AppendOnly#save`.
+        STATUSES = %i[inserted replaced updated conflicted missing saved stale].freeze
 
         def initialize(status:, instance: nil)
           normalized = status.to_sym

data/lib/hecks/ports/persistence/plugin.rb

@@ -0,0 +1,54 @@
+module Hecks
+  module Ports
+    module Persistence
+      # A tiny, real seam — ADR 0033. Core never names a persistence plugin;
+      # a plugin makes itself known as a side effect of being `require`d, the
+      # same way an adapter's own `.rb` file already registers itself
+      # (`Runtime::Registry#add_adapter`) rather than core listing adapter
+      # names anywhere. `register_plugin` is the ENTIRE contract a plugin
+      # must satisfy: anything responding to `contribute_boot_gates(registry,
+      # gates)` (a no-op is a valid implementation).
+      #
+      # This is deliberately NOT the same registry `Hecks::Projector` uses
+      # (ADR 0027) or `Runtime::BootGates` (ADR 0031) — each of those is
+      # scoped to its own seam (IR-in/artifact-out; per-boot phased gates).
+      # A shared base is deferred until a third registry actually wants one.
+      #
+      # NAME-KEYED, PROCESS-WIDE, NOT PER-BOOT — unlike `BootGates` (one
+      # instance per `Loader.boot` call, because gate REGISTRATION is
+      # capability-conditional per registry), a persistence plugin is either
+      # `require`d into this process or it isn't; there is no "this boot's
+      # registry doesn't need it" case to isolate against, so a plain
+      # module-level hash is the right shape here, not an instantiable class.
+      module Plugin
+        @plugins = {}
+
+        class << self
+          def register(name, plugin)
+            @plugins[name.to_sym] = plugin
+          end
+
+          def registered?(name)
+            @plugins.key?(name.to_sym)
+          end
+
+          def each(&)
+            @plugins.each_value(&)
+          end
+
+          def any? = !@plugins.empty?
+        end
+      end
+
+      # `Ports::Persistence.plugin?(:era)` / `.each_plugin` — the ordinary
+      # call surface; `Plugin.register`/`.registered?`/`.each` stay reachable
+      # directly for a plugin's own file to call at require-time.
+      module_function
+
+      def register_plugin(name, plugin) = Plugin.register(name, plugin)
+      def plugin?(name) = Plugin.registered?(name)
+      def each_plugin(&) = Plugin.each(&)
+      def plugins_loaded? = Plugin.any?
+    end
+  end
+end

data/lib/hecks/{runtime → ports/persistence/plugins/era}/era_check.rb

@@ -1,9 +1,9 @@
-require_relative "../ports/persistence"
-require_relative "../ports/persistence/binding_policy"
-require_relative "../ports/persistence/lineage"
-require_relative "../naming"
-require_relative "../framework"
-require_relative "registry"
+require_relative "../../../../ports/persistence"
+require_relative "../../../../ports/persistence/binding_policy"
+require_relative "lineage"
+require_relative "../../../../naming"
+require_relative "../../../../framework"
+require_relative "../../../../runtime/registry"
 
 module Hecks
   module Runtime
@@ -44,11 +44,46 @@ module Hecks
       # the first refuses toward a scaffold that was never the real
       # drift.
       def check!(registry, directory)
+        check_compute_rules_for_registry!(registry)
+        check_lineage!(registry, directory)
+      end
+
+      # The domain-agnostic half, split out for ADR 0031's boot-gate
+      # registry: a compute rule requires Postgres whatever adapter is
+      # actually bound, so this must run for EVERY registry, the same way
+      # `registry.verify!` does — it is not conditional on any adapter
+      # being lineage-capable, and must never be skipped by
+      # `check_lineage!`'s own capability gate below.
+      def check_compute_rules_for_registry!(registry)
+        registry.bluebooks.each_value { |bluebook| check_compute_rules!(registry, bluebook) }
+      end
+
+      # The capability-gated half — ADR 0031's registered `:era_check`
+      # gate. Registration is conditional on `lineage_capable_registry?`;
+      # `check_bluebook!` below still carries its own per-bluebook
+      # `lineage_capable?` return-early, unchanged, for a registry with a
+      # mix of lineage-capable and plain-adapter bluebooks.
+      def check_lineage!(registry, directory)
         registry.bluebooks.each_value do |bluebook|
           check_bluebook!(registry, bluebook, source_text_for(bluebook, directory), directory: directory)
         end
       end
 
+      # The `:era_check` gate's own registration predicate: true iff at
+      # least one bluebook's own anchor (first) aggregate resolves to a
+      # lineage-capable adapter — mirrors `check_bluebook!`'s existing
+      # per-bluebook anchor check, just asked once, up front, of the
+      # whole registry, so a registry with nothing lineage-capable bound
+      # anywhere never registers the gate at all.
+      def lineage_capable_registry?(registry)
+        registry.bluebooks.each_value.any? do |bluebook|
+          first = bluebook.aggregates.first
+          next false unless first
+
+          lineage_capable?(registry, adapter_for(registry, bluebook.name, first))
+        end
+      end
+
       # The domain's own directory first, matched by name — a real app's
       # directory may hold more than one file once `uses_framework`
       # exists, so ".first" alone can no longer be trusted, the exact
@@ -80,8 +115,6 @@ module Hecks
       end
 
       def check_bluebook!(registry, bluebook, current_text, directory: nil)
-        check_compute_rules!(registry, bluebook)
-
         first = bluebook.aggregates.first
         return unless first
 

data/lib/hecks/{runtime → ports/persistence/plugins/era}/era_guard.rb

@@ -1,67 +1,34 @@
-require "fileutils"
 require_relative "era_guard/shape_diff"
-require_relative "../bluebook/dsl/malformed"
-require_relative "../bluebook/meta_validator"
-require_relative "../naming"
-require_relative "../ports/loading"
-require_relative "../ports/persistence/lineage"
-require_relative "era_check"
-require_relative "registry"
+require_relative "../../../../bluebook/dsl/malformed"
+require_relative "../../../../bluebook/meta_validator"
+require_relative "../../../../ports/loading"
+require_relative "../../../../runtime/registry"
 
 module Hecks
   module Runtime
-    # Detects when a bluebook's storage shape has drifted from what its data
-    # was written under — a rename or restructure with nothing to explain
-    # it. Refuses at boot, before a command can run into the gap and raise
-    # something that only makes sense once you already suspect a rename.
+    # The shape-drift coverage primitives — ADR 0032. Not a driver: nothing
+    # here walks a registry or reads/writes a held snapshot on its own.
+    # `PostgresEra::LineageManager::CoverageCheck` calls `uncovered_
+    # attributes`/`unsafe_additions`/`refuse_uncovered!`/`refuse_unsafe_
+    # addition!`/`check_vanished_aggregates!` directly, per translation
+    # edge, over its own DB-held shapes; `Translation::Reattest` and
+    # `PostgresEra::LineageManager` call `shadow_parse` directly, to read
+    # historical bluebook text under old grammar defaults. Both are real,
+    # independent, currently-shipped consumers.
     #
-    # The held source is a snapshot of the bluebook text as it stood the
-    # last time its shape was accepted. It updates only when a drift is
-    # seen AND covered by a translation — never on every boot, and never
-    # silently when a rename has nothing to explain it.
+    # A prior version of this module ALSO drove its own top-level check —
+    # `check!`/`check_bluebook!`, walking a registry and reading/writing a
+    # held snapshot under `data/eras/*.bluebook` — duplicating, on its own,
+    # the same per-aggregate walk `CoverageCheck` already performs against
+    # `PostgresEra`'s own DB-held shapes. Nothing in production ever called
+    # it (only a direct unit spec did); deleted rather than kept unwired,
+    # per ADR 0032. Wanted again, it's rebuilt informed by `CoverageCheck`'s
+    # real orchestration, not resurrected from here.
     module EraGuard
       extend ShapeDiff
 
       module_function
 
-      def check!(registry, directory)
-        registry.bluebooks.each_value { |bluebook| check_bluebook!(registry, bluebook, directory) }
-      end
-
-      def check_bluebook!(registry, bluebook, directory)
-        current_text = EraCheck.source_text_for(bluebook, directory)
-        return unless current_text
-
-        era_dir   = File.join(registry.root, "data", "eras")
-        held_path = File.join(era_dir, "#{Naming.snake(bluebook.name)}.bluebook")
-
-        FileUtils.mkdir_p(era_dir)
-        unless File.exist?(held_path)
-          File.write(held_path, current_text)
-          return
-        end
-
-        held_bluebook = shadow_parse(File.read(held_path, encoding: "UTF-8"), held_path)
-        drifted = false
-
-        bluebook.aggregates.each do |aggregate|
-          lineage = Ports::Persistence::Lineage.for(registry, bluebook.name, aggregate)
-          held_aggregate = held_bluebook.aggregate(lineage&.ancestor_name || aggregate.name)
-          next unless held_aggregate
-          next if shape(aggregate) == shape(held_aggregate)
-
-          drifted = true
-          uncovered = uncovered_attributes(aggregate, held_aggregate, lineage)
-          refuse_uncovered!(bluebook, aggregate, uncovered) unless uncovered.empty?
-
-          unsafe = unsafe_additions(aggregate, held_aggregate, lineage)
-          refuse_unsafe_addition!(bluebook, aggregate, unsafe) unless unsafe.empty?
-        end
-
-        check_vanished_aggregates!(registry, bluebook, held_bluebook)
-        File.write(held_path, current_text) if drifted
-      end
-
       # An aggregate that existed in the held text and answers to no
       # current name — renamed silently, with nothing declaring `was:` to
       # explain where its data went — is exactly the disease this guards
@@ -87,8 +54,9 @@ module Hecks
         end
       end
 
-      # The Layer-1 coverage refusal — one wording, whoever detects the
-      # gap (the file-store boot check here, or Postgres's mint path).
+      # The Layer-1 coverage refusal — one wording, shared with whoever
+      # calls it (today, `PostgresEra::LineageManager::CoverageCheck`'s
+      # own mint-time coverage check).
       def refuse_uncovered!(bluebook, aggregate, uncovered)
         raise WiringError,
               "cannot boot #{bluebook.name}::#{aggregate.name}: its shape changed and " \

data/lib/hecks/ports/persistence/{lineage.rb → plugins/era/lineage.rb}

@@ -1,6 +1,6 @@
-require_relative "../../naming"
-require_relative "append_only"
-require_relative "../../runtime/registry"
+require_relative "../../../../naming"
+require_relative "../../append_only"
+require_relative "../../../../runtime/registry"
 
 module Hecks
   module Ports
@@ -91,7 +91,7 @@ module Hecks
           # value-object hash, and a shallow dup would quietly mutate
           # the caller's copy of the original entry.
           state = deep_dup(entry.state)
-          @renames.each { |old_name, new_name| state[new_name] = state.delete(old_name) if state.key?(old_name) }
+          apply_renames(state, @renames)
           @moves.each { |move| apply_move(state, move) }
           @converts.each { |convert| apply_convert(state, convert) }
           @drops.each { |name| apply_drop(state, name) }
@@ -183,6 +183,33 @@ module Hecks
           end
         end
 
+        # M27 (docs/audits/2026-08-10-main-bug-audit.md,
+        # docs/audits/2026-08-11-bug-triage.md) — SIMULTANEOUS, not
+        # sequential: `state[new] = state.delete(old)` per rename, run
+        # one rule at a time against the SAME hash it was reading from,
+        # loses data the instant one rule's destination is another
+        # rule's source. A swap (`rename :a, to: :b` alongside
+        # `rename :b, to: :a`) on `{a: 1, b: 2}` used to produce
+        # `{a: 1}` — the first rule wrote `b: 1` over the real `b: 2`
+        # before the second rule ever got a chance to read it, and the
+        # value the whole edge was supposed to preserve (2, moved to
+        # `:a`) was gone. The standard fix: snapshot every rule's OLD
+        # key and value from `state` FIRST, then remove every old key
+        # and only THEN write every new key — a rename never reads a
+        # key this same pass has already written to, so a swap or a
+        # longer chain applies as one permutation, not a sequence of
+        # edits each stepping on the last.
+        def apply_renames(state, renames)
+          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) }
+          # rubocop:disable Style/CombinableLoops -- NOT combinable: a swap
+          # (:a<->:b) needs every delete done before any write, or the first
+          # rename's write becomes the second rename's delete target — see
+          # this method's own comment above.
+          snapshot.each { |_old_name, new_name, value| state[new_name] = value }
+          # rubocop:enable Style/CombinableLoops
+        end
+
         def apply_drop(state, name)
           name = name.to_s
           top, member = name.split(".", 2)