hecks 3.4.2 → 3.6.0

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

@@ -1,4 +1,4 @@
-require_relative "../../bluebook/hexagon"
+require_relative "../../bluebook/hecksagon"
 require_relative "../../runtime/registry"
 
 module Hecks
@@ -20,21 +20,45 @@ module Hecks
         # @raise [Runtime::WiringError] if the hecksagon has no `persisted_by` bind for the
         #   aggregate, more or fewer than one bind without a role, or any bind with a role
         def resolve(registry, domain, aggregate)
-          hexagon  = registry.hecksagon(domain)
-          declared = registry.default_adapter_for(domain)
-          return default_binding(aggregate, declared || DEFAULT_ADAPTER) unless hexagon
+          hecksagon = registry.hecksagon(domain)
+          declared  = registry.default_adapter_for(domain)
+          return default_binding(aggregate, declared || DEFAULT_ADAPTER) unless hecksagon
 
-          bindings = hexagon.binds_for(aggregate.hecks_name, VERB)
-          bindings = [default_binding(aggregate, declared)] if bindings.empty? && declared
+          bindings = declared_bindings(hecksagon, aggregate, declared)
           raise missing_binding(domain, aggregate) if bindings.empty?
 
+          authoritative_among(bindings, domain, aggregate)
+        end
+
+        # Picks the single roleless bind, refusing any other count and any bind with a role.
+        #
+        # @param bindings [Array<Bluebook::Bind>] the aggregate's binds; not empty
+        # @param domain [String, Symbol] name of the domain, used in refusal messages
+        # @param aggregate [Bluebook::Aggregate] the aggregate the binds belong to
+        # @return [Bluebook::Bind] the authoritative bind
+        # @raise [Runtime::WiringError] if the roleless count is not one, or a role is present
+        def authoritative_among(bindings, domain, aggregate)
           authoritative = bindings.select { |bind| bind.role.nil? || bind.role.empty? }
           raise ambiguous_binding(domain, aggregate, authoritative) unless authoritative.size == 1
-          raise unsupported_roles(domain, aggregate, bindings - authoritative) unless (bindings - authoritative).empty?
+
+          roled = bindings - authoritative
+          raise unsupported_roles(domain, aggregate, roled) unless roled.empty?
 
           authoritative.first
         end
 
+        # Lists the hecksagon's `persisted_by` binds for an aggregate, or the world's default
+        # adapter bind when the hecksagon declares none.
+        #
+        # @param hecksagon [Bluebook::Hexagon] the domain's hecksagon
+        # @param aggregate [Bluebook::Aggregate] the aggregate whose binds are wanted
+        # @param declared [String, nil] the world's default adapter, if any
+        # @return [Array<Bluebook::Bind>] the binds; empty when none and no default exists
+        def declared_bindings(hecksagon, aggregate, declared)
+          bindings = hecksagon.binds_for(aggregate.hecks_name, VERB)
+          bindings.empty? && declared ? [default_binding(aggregate, declared)] : bindings
+        end
+
         # Builds the bind an aggregate gets when its domain declares no hecksagon.
         #
         # @param aggregate [Bluebook::Aggregate] the aggregate to bind
@@ -81,8 +105,8 @@ module Hecks
         # @return [Runtime::WiringError] an error whose message lists each role
         def unsupported_roles(domain, aggregate, bindings)
           Runtime::WiringError.new(
-            "#{domain}::#{aggregate.hecks_name} uses persistence role#{'s' unless bindings.size == 1} " \
-            "#{bindings.map(&:role).map(&:inspect).join(', ')}. Only persisted_by is supported."
+            "#{domain}::#{aggregate.hecks_name} uses persistence role#{"s" unless bindings.size == 1} " \
+            "#{bindings.map { |binding| binding.role.inspect }.join(", ")}. Only persisted_by is supported."
           )
         end
       end

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

@@ -91,17 +91,28 @@ module Hecks
         # @param klass [Class] the adapter's class
         # @return [Module] an anonymous module including `Guarded`, to `extend` onto instances
         def wrapper_for(klass)
-          WRAPPERS_LOCK.synchronize do
-            WRAPPERS[klass] ||= Module.new do
-              include Guarded
-
-              (klass.public_instance_methods - Object.public_instance_methods).each do |name|
-                define_method(name) do |*args, **kwargs, &block|
-                  result = CodecBoundary.within { super(*args, **kwargs, &CodecBoundary.outside_block(block)) }
-                  name == :entries ? CodecBoundary.check_entries!(self, result) : result
-                end
-              end
-            end
+          WRAPPERS_LOCK.synchronize { WRAPPERS[klass] ||= build_wrapper(klass) }
+        end
+
+        # Builds the module whose methods forward to the adapter class's own, inside the boundary.
+        #
+        # @param klass [Class] the adapter's class
+        # @return [Module] an anonymous module including `Guarded`
+        def build_wrapper(klass)
+          wrapper = Module.new { include Guarded }
+          (klass.public_instance_methods - Object.public_instance_methods).each { |name| guard_method(wrapper, name) }
+          wrapper
+        end
+
+        # Defines one guarded method on `wrapper`; `entries` answers are also checked for decoding.
+        #
+        # @param wrapper [Module] the module under construction
+        # @param name [Symbol] the adapter method to guard
+        # @return [Symbol] the defined method name
+        def guard_method(wrapper, name)
+          wrapper.define_method(name) do |*args, **kwargs, &block|
+            result = CodecBoundary.within { super(*args, **kwargs, &CodecBoundary.outside_block(block)) }
+            name == :entries ? CodecBoundary.check_entries!(self, result) : result
           end
         end
 

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

@@ -0,0 +1,10 @@
+module Hecks
+  module Ports
+    # The persistence port's identifying names, loaded before the files that read them.
+    module Persistence
+      NAME = "persistence".freeze
+      VERB = "persisted_by".freeze
+      DEFAULT_ADAPTER = "Memory".freeze
+    end
+  end
+end

data/lib/hecks/ports/persistence/plugins/era/era_check.rb

@@ -128,19 +128,13 @@ module Hecks
       def fallback_source_files(bluebook, directory, domain_files, registry)
         vendored_name = registry && vendored_bluebook_name_for(registry, bluebook.name)
         framework_path = Framework.members[bluebook.name]
+        return [framework_path] if framework_path
+        return vendored_source_for(directory, vendored_name) if vendored_name
+
         attached = Chapters.index.fetch(bluebook.name, [])
+        return attached if attached.any?
 
-        if attached.any? && !framework_path && !vendored_name
-          attached
-        elsif domain_files.size == 1 && !framework_path && !vendored_name
-          domain_files
-        elsif framework_path
-          [framework_path]
-        elsif vendored_name
-          vendored_source_for(directory, vendored_name)
-        else
-          []
-        end
+        domain_files.size == 1 ? domain_files : []
       end
 
       # Recovers the vendored package name behind a bluebook, if some hecksagon vendored it.
@@ -196,11 +190,7 @@ module Hecks
         adapter_name = adapter_for(registry, bluebook.name, first)
         return unless lineage_capable?(registry, adapter_name)
 
-        unless current_text
-          raise WiringError,
-                "cannot boot #{bluebook.name}: bound to a lineage-capable adapter, but no source file for " \
-                "it could be found (checked #{directory.inspect} and the framework registry)"
-        end
+        refuse_missing_source!(bluebook, directory) unless current_text
 
         settings = registry.binding_settings(bluebook.name, Ports::Persistence::VERB, adapter_name)
         registry.adapter_class(adapter_name).era_check!(
@@ -209,6 +199,18 @@ module Hecks
         )
       end
 
+      # Refuses the boot of a lineage-bound bluebook whose source file was not found.
+      #
+      # @param bluebook [Bluebook::Chapter] the bluebook being checked
+      # @param directory [String, nil] the domain's bluebook directory, named in the message
+      # @return [void]
+      # @raise [Runtime::WiringError] always
+      def refuse_missing_source!(bluebook, directory)
+        raise WiringError,
+              "cannot boot #{bluebook.name}: bound to a lineage-capable adapter, but no source file for " \
+              "it could be found (checked #{directory.inspect} and the framework registry)"
+      end
+
       # Refuses the boot when one bluebook's compute rule is bound away from Postgres.
       #
       # A compute rule's SQL is its only implementation, so it cannot

data/lib/hecks/ports/persistence/plugins/era/era_guard/shape_diff.rb

@@ -4,6 +4,9 @@ module Hecks
       # Structural signature and diff of aggregate shapes, computed from the IR alone
       # (no file I/O), so the Postgres mint path can call it too.
       module ShapeDiff
+        # The held and current aggregates being compared, with the lineage that may explain drift.
+        Sides = Struct.new(:held_aggregate, :aggregate, :lineage)
+
         # Structural signature of an aggregate: sorted `[name, signature]` pairs per attribute.
         def shape(aggregate)
           aggregate.attributes.map do |attribute|
@@ -42,16 +45,14 @@ module Hecks
 
         # True when a new attribute could be genuinely absent from an existing record (ADR 0025).
         def possibly_absent?(aggregate, attribute)
-          return false if attribute.optional?
-          return false unless attribute.default.nil?
-          return false if attribute.list?
-
-          value_object = aggregate.value_object(attribute.type)
-          return false if value_object&.attributes&.all? { |field| !field.default.nil? }
+          return false if attribute.optional? || !attribute.default.nil? || attribute.list?
 
-          true
+          !fully_defaulted?(aggregate.value_object(attribute.type))
         end
 
+        # True when a value object exists and every member of it carries a default.
+        def fully_defaulted?(value_object) = value_object&.attributes&.all? { |field| !field.default.nil? }
+
         # Held attribute paths that vanished or changed type with no rule explaining them,
         # recursing into value objects as dotted paths ("price.currency"). Additions never count.
         def uncovered_attributes(aggregate, held_aggregate, lineage)
@@ -59,7 +60,8 @@ module Hecks
             current_attribute = aggregate.attribute(held_attribute.name)
             next [held_attribute.name.to_s] unless current_attribute
 
-            diff_type(held_attribute.name.to_s, held_attribute.type, current_attribute.type, held_aggregate, aggregate, lineage)
+            sides = Sides.new(held_aggregate, aggregate, lineage)
+            diff_type(held_attribute.name.to_s, held_attribute.type, current_attribute.type, sides)
           end
 
           return paths unless lineage
@@ -70,24 +72,31 @@ module Hecks
         # Compares one path's held and current types, recursing into shared members.
         # A `list_of` entity is diffed only for member drift; no per-element translation exists, so
         # only a top-level `drop` of the whole list satisfies it.
-        def diff_type(path, held_type, current_type, held_aggregate, aggregate, lineage, seen = [])
-          if held_type != current_type
-            # A declared retype accepts the pair but members are still compared, so drift
-            # hidden under the rename is caught.
-            return [path] unless lineage&.retype?(held_type, current_type)
-          end
+        def diff_type(path, held_type, current_type, sides, seen = [])
+          return [path] if retype_drift?(held_type, current_type, sides.lineage)
           return [] if seen.include?(current_type)
 
-          held_container = nested_type(held_aggregate, held_type)
-          current_container = nested_type(aggregate, current_type)
+          held_container = nested_type(sides.held_aggregate, held_type)
+          current_container = nested_type(sides.aggregate, current_type)
           return [] unless held_container && current_container
 
+          diff_members(path, [held_container, current_container], sides, seen + [current_type])
+        end
+
+        # A declared retype accepts the pair but members are still compared, so drift
+        # hidden under the rename is caught.
+        def retype_drift?(held_type, current_type, lineage)
+          held_type != current_type && !lineage&.retype?(held_type, current_type)
+        end
+
+        # Diffs each member of the held container against the same-named current member.
+        def diff_members(path, containers, sides, seen)
+          held_container, current_container = containers
           held_container.attributes.flat_map do |held_member|
             current_member = current_container.attribute(held_member.name)
             next ["#{path}.#{held_member.name}"] unless current_member
 
-            diff_type("#{path}.#{held_member.name}", held_member.type, current_member.type, held_aggregate, aggregate, lineage,
-                      seen + [current_type])
+            diff_type("#{path}.#{held_member.name}", held_member.type, current_member.type, sides, seen)
           end
         end
       end

data/lib/hecks/ports/persistence/plugins/era/era_guard.rb

@@ -27,17 +27,7 @@ module Hecks
       #   `was:` declares it, and no translation retires it
       def check_vanished_aggregates!(registry, bluebook, held_bluebook)
         held_bluebook.aggregates.each do |held_aggregate|
-          claimed = bluebook.aggregates.any? do |aggregate|
-            aggregate.name == held_aggregate.name ||
-              registry.translations.any? do |translation|
-                translation.domain == bluebook.name &&
-                  translation.for_aggregate(aggregate.name)&.was == held_aggregate.name
-              end
-          end
-          claimed ||= registry.translations.any? do |translation|
-            translation.domain == bluebook.name && translation.retired.include?(held_aggregate.name)
-          end
-          next if claimed
+          next if explained?(registry, bluebook, held_aggregate)
 
           raise WiringError,
                 "cannot boot #{bluebook.name}: #{held_aggregate.name} existed and now doesn't, " \
@@ -45,6 +35,36 @@ module Hecks
         end
       end
 
+      # Says whether a held aggregate is accounted for: still present, renamed by a `was:`,
+      # or retired by a translation.
+      #
+      # @param registry [Runtime::Registry] the registry whose translations are searched
+      # @param bluebook [Bluebook::Chapter] the bluebook booting now
+      # @param held_aggregate [Bluebook::Aggregate] the aggregate from the held era
+      # @return [Boolean] true when a current aggregate or a translation explains it
+      def explained?(registry, bluebook, held_aggregate)
+        claimed = bluebook.aggregates.any? do |aggregate|
+          aggregate.name == held_aggregate.name || renamed_from?(registry, bluebook, aggregate, held_aggregate)
+        end
+        claimed || registry.translations.any? do |translation|
+          translation.domain == bluebook.name && translation.retired.include?(held_aggregate.name)
+        end
+      end
+
+      # Says whether a translation declares a current aggregate was the held one.
+      #
+      # @param registry [Runtime::Registry] the registry whose translations are searched
+      # @param bluebook [Bluebook::Chapter] the bluebook booting now
+      # @param aggregate [Bluebook::Aggregate] the current aggregate
+      # @param held_aggregate [Bluebook::Aggregate] the aggregate from the held era
+      # @return [Boolean] true when some translation's `was:` names the held aggregate
+      def renamed_from?(registry, bluebook, aggregate, held_aggregate)
+        registry.translations.any? do |translation|
+          translation.domain == bluebook.name &&
+            translation.for_aggregate(aggregate.name)&.was == held_aggregate.name
+        end
+      end
+
       # Raises the refusal naming every changed path no translation rule explains.
       #
       # The Layer-1 coverage refusal — one wording, shared with whoever
@@ -60,7 +80,7 @@ module Hecks
       def refuse_uncovered!(bluebook, aggregate, uncovered)
         raise WiringError,
               "cannot boot #{bluebook.name}::#{aggregate.name}: its shape changed and " \
-              "#{uncovered.map { |path| render_path(path) }.join(', ')} #{uncovered.size == 1 ? 'is' : 'are'} not " \
+              "#{uncovered.map { |path| render_path(path) }.join(", ")} #{uncovered.size == 1 ? "is" : "are"} not " \
               "explained by any rename, move, convert, retype, or drop. Update bluebook/translations/*.bluebook, e.g. " \
               "#{suggestion(uncovered.first)}."
       end
@@ -79,8 +99,8 @@ module Hecks
       # @raise [Runtime::WiringError] always, carrying the refusal wording
       def refuse_unsafe_addition!(bluebook, aggregate, unsafe)
         raise WiringError,
-              "cannot boot #{bluebook.name}::#{aggregate.name}: #{unsafe.map { |name| ":#{name}" }.join(', ')} " \
-              "#{unsafe.size == 1 ? 'is new and required' : 'are new and required'}, with no default: to fill " \
+              "cannot boot #{bluebook.name}::#{aggregate.name}: #{unsafe.map { |name| ":#{name}" }.join(", ")} " \
+              "#{unsafe.size == 1 ? "is new and required" : "are new and required"}, with no default: to fill " \
               "an existing record and no translation explaining what one should read there. Give it a " \
               "default:, make it optional: true or list_of, or declare bluebook/translations/*.bluebook, e.g. " \
               "`backfill :#{unsafe.first}, default: ...`."
@@ -136,18 +156,27 @@ module Hecks
       def parse_bluebook(source, path, shadow:)
         scratch = Registry.new
         loading = Ports::Loading.bootstrap
-        run = lambda do
-          Hecks.with_registry(scratch) do
-            loading.load_library
-            # Held text of a chapter spread over files is several blocks in one string, each
-            # opening the same chapter: judge once after all of them, as a directory load does.
-            Hecks::Bluebook::MetaValidator.defer { Kernel.eval(source, TOPLEVEL_BINDING, path, 1) }
-            Hecks::Bluebook::MetaValidator.judge_deferred!(scratch)
-          end
-        end
+        run = -> { evaluate_into(scratch, loading, source, path) }
         shadow ? Hecks::Bluebook::MetaValidator.while_shadow_parsing(&run) : run.call
         scratch.bluebooks.values.first
       end
+
+      # Loads the library and evaluates the text with the scratch registry current.
+      #
+      # @param scratch [Registry] the throwaway registry the text registers into
+      # @param loading [Object] the bootstrap loader whose `load_library` runs first
+      # @param source [String] the bluebook text to evaluate
+      # @param path [String] the file path reported to `Kernel.eval` as the text's origin
+      # @return [void]
+      def evaluate_into(scratch, loading, source, path)
+        Hecks.with_registry(scratch) do
+          loading.load_library
+          # Held text of a chapter spread over files is several blocks in one string, each
+          # opening the same chapter: judge once after all of them, as a directory load does.
+          Hecks::Bluebook::MetaValidator.defer { Kernel.eval(source, TOPLEVEL_BINDING, path, 1) }
+          Hecks::Bluebook::MetaValidator.judge_deferred!(scratch)
+        end
+      end
     end
   end
 end

data/lib/hecks/ports/persistence/plugins/era/era_tamper.rb

@@ -34,20 +34,26 @@ module Hecks
       #   round-trip; nil when the text declares no bluebook, or when parsing or projecting
       #   raises any `StandardError` or `SyntaxError`
       def project(text, _source_path = nil)
-        file = Tempfile.new(["hecks-tamper-", ".bluebook"])
-        begin
-          file.write(text)
-          file.flush
-          bluebook = EraGuard.shadow_parse(text, file.path)
-        ensure
-          file.close!
-        end
+        bluebook = parse_from_tempfile(text)
         return nil unless bluebook
 
         JSON.parse(JSON.generate(StorageShape.project(bluebook)))
       rescue StandardError, SyntaxError
         nil
       end
+
+      # Parses the text from a tempfile that is removed afterwards.
+      #
+      # @param text [String] the bluebook source
+      # @return [Bluebook::Chapter, nil] the parsed bluebook; nil when the text declares none
+      def parse_from_tempfile(text)
+        file = Tempfile.new(["hecks-tamper-", ".bluebook"])
+        file.write(text)
+        file.flush
+        EraGuard.shadow_parse(text, file.path)
+      ensure
+        file&.close!
+      end
     end
   end
 end

data/lib/hecks/ports/persistence/plugins/era/expected_era.rb

@@ -71,18 +71,29 @@ module Hecks
         # @raise [Unreachable] if the request fails or the status is not `200`
         # @raise [BadResponse] if the body is not JSON or its `era` is not a non-empty string
         def fetch_version(url, timeout:)
-          response = get(version_url(url), timeout)
-          raise Unreachable, "#{version_url(url)} answered #{response.code}" unless response.code == "200"
+          target = version_url(url)
+          response = get(target, timeout)
+          raise Unreachable, "#{target} answered #{response.code}" unless response.code == "200"
 
           document = JSON.parse(response.body)
-          era = document["era"]
-          raise BadResponse, "#{version_url(url)} carries no era" unless era.is_a?(String) && !era.empty?
-
-          { "era" => era, "version" => document["version"].to_s }
+          { "era" => era_in(document, target), "version" => document["version"].to_s }
         rescue JSON::ParserError, TypeError
           raise BadResponse, "#{version_url(url)} did not answer a JSON version document"
         end
 
+        # Reads the era out of a parsed `/version` document.
+        #
+        # @param document [Hash] the parsed document
+        # @param target [String] the URL it came from, named in the refusal
+        # @return [String] the non-empty era
+        # @raise [BadResponse] if the era is not a non-empty string
+        def era_in(document, target)
+          era = document["era"]
+          raise BadResponse, "#{target} carries no era" unless era.is_a?(String) && !era.empty?
+
+          era
+        end
+
         # Compares a reported era with an allow-list.
         #
         # @param era [String] the era the host reported

data/lib/hecks/ports/persistence/plugins/era/lineage/coverage.rb

@@ -0,0 +1,58 @@
+module Hecks
+  module Ports
+    module Persistence
+      class Lineage
+        # Answers whether a translation edge accounts for a path that vanished, or fills one
+        # that arrived; the questions the era diff asks of a lineage.
+        module Coverage
+          # Reports whether some rule accounts for a held path that vanished or changed type.
+          #
+          # A rule covering a whole top-level attribute also covers anything nested
+          # under it; `backfills` only matches a whole name, since a backfill adds an
+          # attribute that is new outright, never a path that existed and moved.
+          #
+          # @param path [String, Symbol] a bare attribute name or a dotted value-object member path
+          # @return [Boolean] true when a rename, move, convert, drop or compute names the path or
+          #   its top-level attribute as its source, or a backfill names the top-level attribute
+          def explains?(path)
+            path = path.to_s
+            top = path.split(".").first
+
+            @renames.key?(top.to_sym) ||
+              sources.any? { |source| source == path || source.split(".").first == top } ||
+              backfilled?(top)
+          end
+
+          # Reports whether some rule gives an existing record a value at a new attribute.
+          #
+          # The destination-side twin of `explains?`, which checks a rule's source; this checks
+          # `@renames.value?` too, since a bare rename fills the destination unconditionally,
+          # the same way a backfill would.
+          #
+          # @param path [String, Symbol] the name of a top-level attribute new in the current shape
+          # @return [Boolean] true when a rename, move, convert or compute lands a value in that
+          #   attribute, or a backfill names it
+          def fills?(path)
+            path = path.to_s
+
+            @renames.value?(path.to_sym) ||
+              destinations.any? { |destination| destination.split(".").first == path } ||
+              backfilled?(path)
+          end
+
+          private
+
+          # Every path a move, convert, compute or drop reads from.
+          def sources
+            [*@moves, *@converts, *@rules.computes].map(&:from) + @drops.map(&:to_s)
+          end
+
+          # Every path a move, convert or compute writes to.
+          def destinations = [*@moves, *@converts, *@rules.computes].map(&:to)
+
+          def backfilled?(name) = @rules.backfills.any? { |backfill| backfill.name.to_s == name }
+        end
+      end
+    end
+  end
+end

data/lib/hecks/ports/persistence/plugins/era/lineage/rewrite.rb

@@ -0,0 +1,130 @@
+module Hecks
+  module Ports
+    module Persistence
+      class Lineage
+        # The reference semantics of rename, move, convert, drop and backfill, applied in that
+        # order to a deep copy of one entry's state.
+        module Rewrite
+          private
+
+          def rewrite(state)
+            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) }
+            # Only fills a gap nothing else already filled; dotted-path aware, like apply_drop.
+            @rules.backfills.each { |backfill| apply_backfill(state, backfill) }
+            state
+          end
+
+          def deep_dup(node)
+            case node
+            when Hash then node.transform_values { |value| deep_dup(value) }
+            when Array then node.map { |item| deep_dup(item) }
+            else node
+            end
+          end
+
+          # Snapshots every rename's old key/value before writing any new key, so a
+          # swap (:a<->:b) applies as one permutation instead of losing data when one
+          # rule's destination is another's source.
+          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) }
+            # Every delete finishes before any write, or a swap's first write becomes its
+            # second delete target.
+            state.merge!(snapshot.to_h { |_old_name, new_name, value| [new_name, value] })
+          end
+
+          def apply_drop(state, name)
+            top, member = name.to_s.split(".", 2)
+            top = top.to_sym
+            return state.delete(top) unless member
+
+            nested = state[top]
+            return unless nested.is_a?(Hash)
+
+            nested.delete(member)
+            state.delete(top) if nested.empty?
+          end
+
+          # Dotted-path aware; must stay in step with `hecks_tr_insert` in rule_compiler.rb.
+          def apply_backfill(state, backfill)
+            name = backfill.name.to_s
+            top, member = name.split(".", 2)
+            top = top.to_sym
+
+            if member
+              nested = (state[top] ||= {})
+              nested[member] = backfill.default unless nested.key?(member)
+            else
+              state[top] = backfill.default unless state.key?(top)
+            end
+          end
+
+          # Runs on raw rows, before the state codec decodes anything — decode is
+          # always the last step, so this never sees an adapter's deep-symbolized entry.
+          def apply_move(state, move)
+            old_top, old_member = move.from.split(".", 2)
+            new_top, new_member = move.to.split(".", 2)
+            old_top = old_top.to_sym
+
+            value, present = extract(state, old_top, old_member)
+            return unless present
+
+            insert(state, new_top.to_sym, new_member, value, rule: "move #{move.from} to: #{move.to}")
+          end
+
+          # A convert is a move whose value has nothing in common with its replacement.
+          def apply_convert(state, convert)
+            old_top, old_member = convert.from.split(".", 2)
+            new_top, new_member = convert.to.split(".", 2)
+
+            raw, present = extract(state, old_top.to_sym, old_member)
+            return unless present
+
+            insert(state, new_top.to_sym, new_member, converted(convert, raw), rule: "convert #{convert.from} to: #{convert.to}")
+          end
+
+          # A value missing from the lookup table refuses loudly rather than carry an
+          # unrecognized value silently into the new era.
+          def converted(convert, raw)
+            return convert.values[raw] if convert.values.key?(raw)
+
+            raise Runtime::WiringError,
+                  "cannot translate #{convert.from}: #{raw.inspect} has no mapping in its " \
+                  "convert's values: table. Add #{raw.inspect} => ... to cover it."
+          end
+
+          def extract(state, top, member)
+            return [nil, false] unless state.key?(top)
+            return [state.delete(top), true] unless member
+
+            nested = state[top]
+            return [nil, false] unless nested.is_a?(Hash) && nested.key?(member)
+
+            value = nested.delete(member)
+            state.delete(top) if nested.empty?
+            [value, true]
+          end
+
+          # A destination already holding a non-Hash value (e.g. a bare reference id)
+          # must not be silently nested under — that would be an undeclared drop. The
+          # SQL half (`hecks_tr_insert`) refuses with identical wording.
+          def insert(state, top, member, value, rule:)
+            return state[top] = value unless member
+
+            if state.key?(top) && !state[top].is_a?(Hash)
+              raise Runtime::WiringError,
+                    "cannot #{rule}: #{top} already holds #{state[top].inspect}, not a value this can nest " \
+                    "under — moving into it would discard that value silently. Rename or drop #{top} first."
+            end
+
+            state[top] ||= {}
+            state[top][member] = value
+          end
+        end
+      end
+    end
+  end
+end

data/lib/hecks/ports/persistence/plugins/era/lineage/rules.rb

@@ -0,0 +1,25 @@
+module Hecks
+  module Ports
+    module Persistence
+      class Lineage
+        # The optional rule lists a translation edge carries beyond the four positional ones;
+        # an unknown keyword raises ArgumentError.
+        #
+        # - `retypes` — type names meaning the same shape
+        # - `computes` — SQL-only rules, never applied in process
+        # - `rekeys` — SQL rewrites of identity; only the first is read
+        # - `backfills` — defaults for a new attribute
+        # - `ancestor_name` — the aggregate's name before the edge, if renamed
+        # - `ancestor_storage_name` — snake_case storage name of `ancestor_name`
+        Rules = Struct.new(:retypes, :computes, :rekeys, :backfills, :ancestor_name, :ancestor_storage_name,
+                           keyword_init: true) do
+          # Builds the rules with every list defaulting to empty.
+          #
+          # @param given [Hash] any of the members; an unknown key raises ArgumentError
+          # @return [Rules]
+          def self.build(**given) = new(retypes: [], computes: [], rekeys: [], backfills: [], **given)
+        end
+      end
+    end
+  end
+end