hecks 5.0.0 → 7.0.0

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

@@ -0,0 +1,127 @@
+require "digest"
+require "json"
+
+module Hecks
+  module Runtime
+    # A held era read from the storage shape its mint recorded, answering the bluebook questions an
+    # era's diff, additive rule and coverage check ask of the side they translate from: each
+    # aggregate's name, identity paths and attributes, and each value object's members.
+    #
+    # The shape is what an era is: its hash is the SHA-256 of the shape's canonical JSON, the same
+    # one `StorageShape.mint_hash` takes of a declared bluebook. Nothing here parses held text.
+    class ProjectedBluebook
+      # One attribute or value-object member, by name and type name. The name is a Symbol and the
+      # type name a String, as a declared bluebook answers them.
+      Attribute = Data.define(:name, :type, :list) do
+        # @return [Boolean] whether the attribute holds a list
+        def list? = list
+      end
+
+      # A value object or entity an attribute's type names, with its members.
+      Container = Data.define(:name, :attributes) do
+        # @param name [String, Symbol] a member name
+        # @return [Attribute, nil] the member of that name
+        def attribute(name) = attributes.find { |member| member.name.to_s == name.to_s }
+      end
+
+      # One aggregate of the held shape.
+      class Aggregate
+        attr_reader :name, :identity_paths, :attributes
+
+        # @param shape [Hash{String => Object}] one entry of the projection's `aggregates`
+        def initialize(shape)
+          @name = shape["name"]
+          @identity_paths = Array(shape["identity"])
+          @containers = {}
+          @attributes = Array(shape["attributes"]).map { |attribute| read(attribute) }
+        end
+
+        # @param name [String, Symbol] an attribute name
+        # @return [Attribute, nil] the attribute of that name
+        def attribute(name) = attributes.find { |attribute| attribute.name.to_s == name.to_s }
+
+        # @param type_name [String] a type name an attribute or member names
+        # @return [Container, nil] the value object or entity of that name
+        def value_object(type_name) = @containers[type_name]
+
+        # @return [Array] none: entities are answered as containers by `value_object`
+        def entities = []
+
+        private
+
+        # Reads one attribute or member, keeping the container its type expands to.
+        def read(attribute)
+          type = attribute["type"]
+          type = contain(type) if type.is_a?(Hash)
+          Attribute.new(name: attribute["name"].to_sym, type: type, list: attribute["list"] == true)
+        end
+
+        # Keeps the value object or entity a type expands to, and answers its name.
+        def contain(type)
+          name = type["type"]
+          @containers[name] ||= Container.new(name: name, attributes: Array(type["members"]).map { |member| read(member) })
+          name
+        end
+      end
+
+      attr_reader :projection, :name, :aggregates
+
+      # @param projection [Hash{String => Object}] a storage shape, as `StorageShape.project`
+      #   answers it or as `hecks_eras.held_projection` stores it
+      def initialize(projection)
+        @projection = projection
+        @name = projection["name"]
+        @aggregates = Array(projection["aggregates"]).map { |shape| Aggregate.new(shape) }
+      end
+
+      # @param projection_or_bluebook [Hash, ProjectedBluebook, Object] a storage shape, a view, or
+      #   a declared bluebook
+      # @return [ProjectedBluebook, Object] a storage shape wrapped as a view; anything else as
+      #   given
+      def self.wrap(projection_or_bluebook)
+        projection_or_bluebook.is_a?(Hash) ? new(projection_or_bluebook) : projection_or_bluebook
+      end
+
+      # @param name [String, Symbol] an aggregate name
+      # @return [Aggregate, nil] the aggregate of that name
+      def aggregate(name) = aggregates.find { |aggregate| aggregate.name == name.to_s }
+
+      # @return [nil] a held shape carries no rename marker; the declared bluebook does
+      def formerly_known_as = nil
+
+      # @return [String] the era's hash: the SHA-256 of the shape's canonical JSON
+      def mint_hash = Digest::SHA256.hexdigest(JSON.generate(Canonical.shape(projection)))
+
+      # The storage shape with its keys in the order `StorageShape.project` builds them, so a shape
+      # read back from `jsonb`, which reorders keys, hashes as it did when it was minted.
+      module Canonical
+        module_function
+
+        # @param shape [Hash] a storage shape
+        # @return [Hash] the shape with its keys in canonical order
+        def shape(shape)
+          { "name" => shape["name"], "aggregates" => Array(shape["aggregates"]).map { |aggregate| aggregate(aggregate) } }
+        end
+
+        # @return [Hash] one aggregate's shape in canonical key order
+        def aggregate(aggregate)
+          { "name" => aggregate["name"], "identity" => aggregate["identity"],
+            "lifecycle_field" => aggregate["lifecycle_field"],
+            "attributes" => Array(aggregate["attributes"]).map { |attribute| attribute(attribute) } }
+        end
+
+        # @return [Hash] one attribute's shape in canonical key order
+        def attribute(attribute)
+          { "name" => attribute["name"], "list" => attribute["list"], "type" => type(attribute["type"]) }
+        end
+
+        # @return [String, Hash] a scalar type as given, or a container in canonical key order
+        def type(type)
+          return type unless type.is_a?(Hash)
+
+          { "type" => type["type"], "members" => Array(type["members"]).map { |member| attribute(member) } }
+        end
+      end
+    end
+  end
+end

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

@@ -10,7 +10,7 @@ module Hecks
 
       # Reduces a bluebook to the parts of its IR that decide what stored data looks like.
       #
-      # @param bluebook [Bluebook::Chapter] the bluebook whose `to_h` dump is projected
+      # @param bluebook [Bluebook::Declaration] the bluebook whose `to_h` dump is projected
       # @return [Hash{String => Object}] `"name"` (the bluebook's name) and `"aggregates"`, an
       #   Array of the Hashes `project_aggregate` builds, sorted by aggregate name
       def project(bluebook)
@@ -25,19 +25,19 @@ module Hecks
 
       # Compares two bluebooks by storage shape alone, ignoring every behavioral difference.
       #
-      # @param held [Bluebook::Chapter] the bluebook a held era was minted from
-      # @param current [Bluebook::Chapter] the bluebook booting now
+      # @param held [Bluebook::Declaration] the bluebook a held era was minted from
+      # @param current [Bluebook::Declaration] the bluebook booting now
       # @return [Boolean] true when both project to an equal structure
       def same?(held, current) = project(held) == project(current)
 
       # The canonical serialization hashed at mint time; stored era names are never recomputed.
-      # @param bluebook [Bluebook::Chapter] the bluebook to serialize
+      # @param bluebook [Bluebook::Declaration] the bluebook to serialize
       # @return [String] compact JSON text of `project(bluebook)`
       def canonical(bluebook) = JSON.generate(project(bluebook))
 
       # Computes the era identity of a bluebook's storage shape.
       #
-      # @param bluebook [Bluebook::Chapter] the bluebook being minted
+      # @param bluebook [Bluebook::Declaration] the bluebook being minted
       # @return [String] 64 lowercase hex characters, the SHA-256 of `canonical(bluebook)`
       def mint_hash(bluebook) = Digest::SHA256.hexdigest(canonical(bluebook))
 
@@ -45,7 +45,7 @@ module Hecks
 
       # Shortens the era identity to the label translation edges and refusals use.
       #
-      # @param bluebook [Bluebook::Chapter] the bluebook being minted
+      # @param bluebook [Bluebook::Declaration] the bluebook being minted
       # @return [String] the first `LABEL_LENGTH` hex characters of `mint_hash(bluebook)`
       def mint_label(bluebook) = mint_hash(bluebook)[0, LABEL_LENGTH]
 

data/lib/hecks/ports/persistence/plugins/era/translation/additive_shape.rb

@@ -0,0 +1,107 @@
+require_relative "../storage_shape"
+require_relative "../projected_bluebook"
+
+module Hecks
+  module Translation
+    # The one rule for whether a change to an aggregate's storage shape only adds: its identity and
+    # lifecycle field are as they were, every attribute it held is held exactly as before (same
+    # name, same list or scalar form, same type with the same members), and each attribute it gained
+    # is optional. Anything else is breaking, and a caller that cannot tell treats it as breaking.
+    #
+    # The implicit edge and the disposable ledger both ask it, so the two never disagree.
+    #
+    # **Known limits.** A stored projection leaves out `optional` and a lifecycle's states, so an
+    # attribute that became required, or a state that was removed, is seen only when the held side
+    # is a full declaration; between two projections it cannot be told from an unchanged shape.
+    module AdditiveShape
+      # The parts of a projected aggregate besides its attributes that its stored rows depend on.
+      KEYS = %w[identity lifecycle_field].freeze
+
+      module_function
+
+      # @param held [Hash] the held aggregate's projection, as `StorageShape.project` builds it
+      # @param current [Hash] the booting aggregate's projection
+      # @param optional [#call] answers, given a name, whether the booting aggregate declares
+      #   that attribute optional
+      # @param was_optional [#call, nil] answers whether the held aggregate declared an attribute
+      #   optional, or nil when the held side is a projection that does not say
+      # @return [Boolean] whether `current` only adds to `held`
+      def widened?(held, current, optional:, was_optional: nil)
+        return false unless held.values_at(*KEYS) == current.values_at(*KEYS)
+        return false unless (held["attributes"] - current["attributes"]).empty?
+        return false if tightened?(held, optional, was_optional)
+
+        (names(current) - names(held)).all? { |name| optional.call(name) }
+      end
+
+      # Whether an attribute the held declaration marked optional is required now.
+      #
+      # @return [Boolean]
+      def tightened?(held, optional, was_optional)
+        return false unless was_optional
+
+        names(held).any? { |name| was_optional.call(name) && !optional.call(name) }
+      end
+
+      # @return [Array<String>] the attribute names of a projected aggregate
+      def names(projected) = projected["attributes"].map { |attribute| attribute["name"] }
+
+      # Whether every aggregate present in both shapes only adds. A shared aggregate that is
+      # unchanged counts; one the current side lacks or the held side lacks is not this check's
+      # business (the scaffold diff names renames, retirements and new aggregates).
+      #
+      # @param held [Hash, Runtime::ProjectedBluebook, Bluebook::Declaration] the held side
+      # @param current [Bluebook::Declaration] the booting bluebook
+      # @return [Boolean]
+      def additive?(held, current)
+        held_by = by_name(shape_of(held))
+        by_name(Runtime::StorageShape.project(current)).all? do |name, projected|
+          held_by[name].nil? || aggregate_additive?(held, held_by[name], projected, current.aggregate(name))
+        end
+      end
+
+      # @return [Boolean] whether one aggregate present in both shapes only adds
+      def aggregate_additive?(held, before, after, aggregate)
+        states_kept?(held, aggregate) &&
+          widened?(before, after, optional: optional_in(aggregate), was_optional: was_optional_in(held, aggregate.name))
+      end
+
+      # Whether every lifecycle state the held declaration had is still declared. A held side that
+      # is a projection records no states, so it answers true.
+      #
+      # @return [Boolean]
+      def states_kept?(held, aggregate)
+        return true if held.is_a?(Hash) || held.is_a?(Runtime::ProjectedBluebook)
+
+        before = states_of(held.aggregate(aggregate.name))
+        before.nil? || ((before - Array(states_of(aggregate))).empty? && !states_of(aggregate).nil?)
+      end
+
+      # @return [Array<String>, nil] the lifecycle states an aggregate declares; nil without one
+      def states_of(aggregate)
+        lifecycle = aggregate&.lifecycle
+        lifecycle&.states
+      end
+
+      # @return [Hash] the storage shape of any held side
+      def shape_of(held)
+        held = Runtime::ProjectedBluebook.wrap(held)
+        held.is_a?(Runtime::ProjectedBluebook) ? held.projection : Runtime::StorageShape.project(held)
+      end
+
+      # @return [Hash{String => Hash}] each projected aggregate by name
+      def by_name(shape) = shape["aggregates"].to_h { |aggregate| [aggregate["name"], aggregate] }
+
+      # @return [#call] whether the aggregate declares the named attribute optional
+      def optional_in(aggregate) = ->(name) { aggregate&.attribute(name)&.optional? || false }
+
+      # @return [#call, nil] whether the held declaration's aggregate declared the named attribute
+      #   optional; nil for a projection, which does not record it
+      def was_optional_in(held, name)
+        return nil if held.is_a?(Hash) || held.is_a?(Runtime::ProjectedBluebook)
+
+        optional_in(held.aggregate(name))
+      end
+    end
+  end
+end

data/lib/hecks/ports/persistence/plugins/era/translation/audit.rb

@@ -62,9 +62,15 @@ module Hecks
       def samples_for(declared, before, after)
         return rekeyed_samples(before, after) if declared && !declared.rekeys.empty?
 
-        before.keys.sort.first(SAMPLE_SIZE).map { |id| { id: id, before: before[id], after: after[id] } }
+        first_ids(before).map { |id| { id: id, before: before[id], after: after[id] } }
       end
 
+      # The ids a sample shows: the first `SAMPLE_SIZE`, in sorted order.
+      #
+      # @param states [Hash{String => Hash}] state per record id
+      # @return [Array<String>] up to `SAMPLE_SIZE` ids
+      def first_ids(states) = states.keys.sort.first(SAMPLE_SIZE)
+
       # Samples both sides of a rekeying edge separately, each labelled by its own id.
       #
       # A rekey changes the id, so pairing by id would show every `after` as nil.
@@ -74,8 +80,8 @@ module Hecks
       #   `" (before)"` with `:after` nil, then up to `SAMPLE_SIZE` ending in `" (after)"` with
       #   `:before` nil
       def rekeyed_samples(before, after)
-        before.keys.sort.first(SAMPLE_SIZE).map { |id| { id: "#{id} (before)", before: before[id], after: nil } } +
-          after.keys.sort.first(SAMPLE_SIZE).map { |id| { id: "#{id} (after)", before: nil, after: after[id] } }
+        first_ids(before).map { |id| { id: "#{id} (before)", before: before[id], after: nil } } +
+          first_ids(after).map { |id| { id: "#{id} (after)", before: nil, after: after[id] } }
       end
     end
   end

data/lib/hecks/ports/persistence/plugins/era/translation/compose.rb

@@ -0,0 +1,155 @@
+# frozen_string_literal: true
+
+require_relative "../../../../../bluebook/translation"
+require_relative "compose_render"
+
+module Hecks
+  module Translation
+    # Composes the chain of translation edges from a held era to the current shape into the one
+    # edge that leads straight there. Rendering the edge as `.bluebook` text is `ComposeRender`.
+    #
+    # Composition is exact only where the chain is unambiguous. An aggregate's field rules (renames,
+    # drops, derives and the rest) may appear in one step of the chain; two steps' rules on the same
+    # aggregate would need their order and names reconciled, and that is a decision for a person.
+    # Aggregate names are followed through every step, so a rename in any step survives into the
+    # composed edge as `was:`.
+    module Compose
+      # The field-level rule lists a `Bluebook::TranslationAggregate` carries.
+      FIELD_RULES = %i[renames moves converts drops retypes derives rekeys backfills splits].freeze
+
+      # The rules no rendering covers yet; a chain that carries one is refused, not guessed at.
+      UNRENDERABLE = %i[rekeys splits].freeze
+
+      module_function
+
+      # Walks the edges that lead one shape label to the next until the current shape.
+      #
+      # @param translations [Array<Bluebook::Translation>] every loaded edge, any domain
+      # @param domain [String] the domain whose edges count
+      # @param from [String] the held era's shape label
+      # @param to [String] the current shape label
+      # A held era whose label is the current one but whose projection differs has no chain to walk:
+      # its one step is the edge from that label to itself, when such an edge exists.
+      #
+      # @return [Array<Bluebook::Translation>] the edges in order; empty when none leads `from` to `to`
+      #   and `from` is `to`
+      # @raise [Runtime::WiringError] when a step has no edge, has two, or the walk loops
+      def chain(translations, domain:, from:, to:)
+        return self_edges(translations, domain, from) if from == to
+
+        steps = []
+        label = from
+        until label == to
+          step = next_step(translations, domain, label, to)
+          raise_loop!(domain, step.to) if [from, *steps.map(&:to)].include?(step.to)
+          steps << step
+          label = step.to
+        end
+        steps
+      end
+
+      # @return [Bluebook::Translation] the one edge from the first step's origin to the last step's target
+      # @raise [Runtime::WiringError] when a step's rules cannot be composed into one edge
+      def compose(domain:, from:, to:, chain:)
+        refuse_unrenderable!(chain)
+        origins, retired, ruled = track_chain(chain)
+        Bluebook::Translation.new(domain: domain, from: from, to: to,
+                                  aggregates: composed_aggregates(origins, ruled),
+                                  retired: retired.reject { |name| origins.key?(name) })
+      end
+
+      def self_edges(translations, domain, label)
+        translations.select { |edge| edge.domain == domain && edge.from == label && edge.to == label }
+      end
+
+      # @return [Bluebook::Translation] the step leaving `label`, the only one that does
+      # @raise [Runtime::WiringError] when none leaves it or two do
+      def next_step(translations, domain, label, to)
+        leaving = translations.select { |edge| edge.domain == domain && edge.from == label }
+        refuse_broken!(domain, label, to) if leaving.empty?
+        refuse_forked!(domain, label, leaving) if leaving.size > 1
+        leaving.first
+      end
+
+      def refuse_broken!(domain, label, to)
+        raise Runtime::WiringError,
+              "cannot compose #{domain}: the edge chain is broken at #{label} — no translation leads " \
+              "#{label} onward to #{to}; restore translations/ or write the missing edge"
+      end
+
+      def refuse_forked!(domain, label, leaving)
+        raise Runtime::WiringError,
+              "cannot compose #{domain}: #{leaving.size} translations leave #{label} " \
+              "(#{leaving.map(&:to).join(", ")}); one must go before the chain can compose"
+      end
+
+      def raise_loop!(domain, label)
+        raise Runtime::WiringError, "cannot compose #{domain}: the edge chain loops back to #{label}"
+      end
+
+      def refuse_unrenderable!(chain)
+        chain.each do |step|
+          step.aggregates.each do |aggregate|
+            next if UNRENDERABLE.all? { |rule| aggregate.public_send(rule).empty? }
+
+            raise Runtime::WiringError,
+                  "cannot compose #{step.domain}: #{aggregate.name} carries a rekey or split, which " \
+                  "composes by hand; write the composed edge yourself"
+          end
+        end
+      end
+
+      # Follows each aggregate from its held name to its current one, and finds the one step that
+      # carries field rules for each origin.
+      #
+      # @return [Array(Hash, Array<String>, Hash)] origins keyed by current name, every retired name,
+      #   and the aggregate carrying field rules for each origin
+      def track_chain(chain)
+        state = { origins: {}, retired: [], ruled: {} }
+        chain.each_with_index { |step, index| track_step(state, step, index) }
+        [state[:origins], state[:retired].uniq, state[:ruled].transform_values(&:last)]
+      end
+
+      def track_step(state, step, index)
+        step.aggregates.each { |aggregate| track_aggregate(state, step.domain, aggregate, index) }
+        state[:retired].concat(step.retired)
+      end
+
+      def track_aggregate(state, domain, aggregate, index)
+        origin = track(state[:origins], aggregate)
+        return if FIELD_RULES.all? { |rule| aggregate.public_send(rule).empty? }
+
+        refuse_two_steps!(domain, aggregate.name, state[:ruled][origin], index) if state[:ruled][origin]
+        state[:ruled][origin] = [index, aggregate]
+      end
+
+      # Records an aggregate under its current name, keeping the name it was held under.
+      def track(origins, aggregate)
+        previous = aggregate.was || aggregate.name
+        origin = origins.delete(previous) || previous
+        origins[aggregate.name] = origin
+      end
+
+      # Builds the composed aggregates: one per aggregate that was renamed or carries field rules.
+      def composed_aggregates(origins, ruled)
+        origins.filter_map do |name, origin|
+          source = ruled[origin]
+          next if source.nil? && origin == name
+
+          composed_aggregate(name, origin, source)
+        end
+      end
+
+      def refuse_two_steps!(domain, name, earlier, index)
+        raise Runtime::WiringError,
+              "cannot compose #{domain}: #{name} has field rules in steps #{earlier.first + 1} and " \
+              "#{index + 1} of the chain; compose those by hand"
+      end
+
+      def composed_aggregate(name, origin, source)
+        rules = source ? FIELD_RULES.to_h { |rule| [rule, source.public_send(rule)] } : {}
+        Bluebook::TranslationAggregate.new(name: name, was: (origin == name ? nil : origin), **rules)
+      end
+    end
+  end
+end

data/lib/hecks/ports/persistence/plugins/era/translation/compose_render.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+module Hecks
+  module Translation
+    # Renders a composed edge as `.bluebook` text, the form the era gate and the audit read back.
+    module ComposeRender
+      module_function
+
+      # The `.bluebook` text of one edge, with a comment naming the chain it composes.
+      #
+      # @param edge [Bluebook::Translation] the composed edge
+      # @param labels [Array<String>] the shape labels the chain passes through, in order
+      # @return [String] the text, ending in a newline
+      def render(edge, labels: [])
+        lines = [*comment_lines(labels), header(edge)]
+        edge.aggregates.each { |aggregate| lines.concat(aggregate_lines(aggregate)) }
+        edge.retired.each { |name| lines << "  retired #{name.inspect}" }
+        lines << "end"
+        "#{lines.join("\n")}\n"
+      end
+
+      def header(edge)
+        "Hecks.data_translation #{edge.domain.inspect}, from: #{edge.from.inspect}, to: #{edge.to.inspect} do"
+      end
+
+      def comment_lines(labels)
+        return [] if labels.empty?
+
+        ["# Composed from the chain #{labels.join(" -> ")}: the rules of each step, carried into one edge."]
+      end
+
+      def aggregate_lines(aggregate)
+        header = "  aggregate #{aggregate.name.inspect}"
+        header += ", was: #{aggregate.was.inspect}" if aggregate.was
+        ["#{header} do", *rule_lines(aggregate).map { |line| "    #{line}" }, "  end"]
+      end
+
+      # Each field rule as the line that declares it, in the order the bluebook reads.
+      def rule_lines(aggregate)
+        renames(aggregate) + moves(aggregate) + converts(aggregate) + drops(aggregate) +
+          retypes(aggregate) + derives(aggregate) + backfills(aggregate)
+      end
+
+      def renames(aggregate)
+        aggregate.renames.map { |old_name, new_name| "rename #{symbol(old_name)}, to: #{symbol(new_name)}" }
+      end
+
+      def moves(aggregate)
+        aggregate.moves.map { |move| "move #{move.from.inspect}, to: #{move.to.inspect}" }
+      end
+
+      def converts(aggregate)
+        aggregate.converts.map do |convert|
+          "convert #{convert.from.inspect}, to: #{convert.to.inspect}, values: #{convert.values.inspect}"
+        end
+      end
+
+      def drops(aggregate) = aggregate.drops.map { |path| "drop #{path.to_s.inspect}" }
+
+      def retypes(aggregate)
+        aggregate.retypes.map { |retype| "retype #{retype.from.inspect}, to: #{retype.to.inspect}" }
+      end
+
+      def derives(aggregate)
+        aggregate.derives.map do |derive|
+          "derive #{symbol(derive.to)}, as: #{derive.expression.to_s.inspect}"
+        end
+      end
+
+      def backfills(aggregate)
+        aggregate.backfills.map do |backfill|
+          "backfill #{symbol(backfill.name)}, default: #{backfill.default.inspect}"
+        end
+      end
+
+      def symbol(name) = ":#{name}"
+    end
+  end
+end

data/lib/hecks/ports/persistence/plugins/era/translation/edge_files.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module Hecks
+  module Translation
+    # The edge files of a domain's `translations/` directory, read by their headers.
+    #
+    # A header names the domain and the two shape labels an edge leads between, so a file is found
+    # without loading it: the writer needs to know which files a chain uses before it changes any.
+    module EdgeFiles
+      # One edge file: where it is and the header it declares.
+      Found = Struct.new(:path, :domain, :from, :to, keyword_init: true)
+
+      HEADER = /^Hecks\.data_translation\s+"(?<domain>[^"]+)",\s*from:\s*"(?<from>[^"]+)",\s*to:\s*"(?<to>[^"]+)"/
+
+      module_function
+
+      # @param directory [String] the domain's bluebook directory
+      # @return [Array<Found>] every `translations/*.bluebook` file whose header parses, by path
+      def scan(directory)
+        Dir[File.join(directory, "translations", "*.bluebook")].filter_map do |path|
+          match = HEADER.match(File.read(path))
+          Found.new(path: path, domain: match[:domain], from: match[:from], to: match[:to]) if match
+        end
+      end
+
+      # The files of the edges a composed chain replaces: each leads to a shape the chain passes
+      # through before its last step, so only the chain used it.
+      #
+      # @param directory [String] the domain's bluebook directory
+      # @param domain [String] the domain whose edges count
+      # @param chain [Array<Bluebook::Translation>] the chain being composed, in order
+      # @return [Array<String>] the paths to delete
+      def stale(directory, domain:, chain:)
+        intermediates = chain[0...-1].map(&:to)
+        scan(directory).filter_map do |found|
+          found.path if found.domain == domain && intermediates.include?(found.to)
+        end
+      end
+
+      # @param directory [String] the domain's bluebook directory
+      # @param from [String] the shape label the composed edge leaves
+      # @param to [String] the shape label the composed edge reaches
+      # @return [String] the path the composed edge is written to
+      def path_for(directory, from:, to:)
+        File.join(directory, "translations", "2-#{from}-to-#{to}.bluebook")
+      end
+    end
+  end
+end

data/lib/hecks/ports/persistence/plugins/era/translation/edge_route.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module Hecks
+  module Translation
+    # Finds the run of translation edges that leads one shape label to another. A run is found by
+    # search rather than by walking every label's edges, so an edge that leaves a label off the run
+    # (a fork branch) does not stop the route.
+    module EdgeRoute
+      module_function
+
+      # The shortest run of edges from one label to another.
+      #
+      # @return [Array<Bluebook::Translation>] the edges in order; when `from` is `to`, the self
+      #   edge if one exists, else empty
+      # @raise [Runtime::WiringError] when no run of edges leads `from` to `to`
+      def route(edges, from, to)
+        return edges.select { |edge| edge.from == from && edge.to == from }.first(1) if from == to
+
+        walk(edges, from, to).fetch(to) { raise Runtime::WiringError, "no translation edge leads #{from} to #{to}" }
+      end
+
+      # Breadth-first over labels, keeping the first run found to each one.
+      #
+      # @return [Hash{String => Array<Bluebook::Translation>}] the run to each reached label
+      def walk(edges, from, to)
+        paths = { from => [] }
+        frontier = [from]
+        until frontier.empty? || paths.key?(to)
+          label = frontier.shift
+          extend_runs(paths, frontier, edges, label)
+        end
+        paths
+      end
+
+      def extend_runs(paths, frontier, edges, label)
+        edges.each do |edge|
+          next unless edge.from == label && !paths.key?(edge.to)
+
+          paths[edge.to] = [*paths[label], edge]
+          frontier << edge.to
+        end
+      end
+
+      # @return [Boolean] whether a run of edges leads from one label to another
+      def reachable?(from, to, edges) = reached(from, edges).include?(to)
+
+      # @return [Array<String>] every label reachable from `from`, `from` included
+      def reached(from, edges)
+        seen = [from]
+        frontier = [from]
+        until frontier.empty?
+          label = frontier.shift
+          successors = edges.filter_map { |edge| edge.to if edge.from == label && !seen.include?(edge.to) }
+          seen.concat(successors)
+          frontier.concat(successors)
+        end
+        seen
+      end
+    end
+  end
+end