hecks 6.0.0 → 7.0.0

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/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

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

@@ -0,0 +1,67 @@
+require_relative "../projected_bluebook"
+require_relative "additive_shape"
+
+module Hecks
+  module Translation
+    # The empty edge a shape change needs when no edge file is written.
+    #
+    # A change that scaffolds to no rule, no unresolved line and no retirement, and whose storage
+    # change only adds, carries every row unchanged, so no file has to say so. The boot and the mint
+    # treat it as an empty edge from the held shape to the current one, and the journal records the
+    # era it minted as implicit. Every other change still needs a real edge file.
+    class ImplicitEdge
+      # What the journal stores for an era minted under an implicit edge. A later boot reads
+      # it back, so an audit can tell the edge was never written by hand.
+      RECORD = { kind: "implicit", scaffolded: true }.freeze
+
+      attr_reader :domain, :from, :to
+
+      # @param domain [String] the domain the edge belongs to
+      # @param from [String] the shape label the edge leaves
+      # @param to [String] the shape label the edge reaches
+      def initialize(domain:, from:, to:)
+        @domain = domain
+        @from = from
+        @to = to
+      end
+
+      # An implicit edge declares no aggregate, so it renames, moves, converts and drops nothing.
+      #
+      # @return [Array] always empty
+      def aggregates = []
+
+      # An implicit edge retires no aggregate, as a written edge's `retired` lists none it drops.
+      #
+      # @return [Array] always empty
+      def retired = []
+
+      # @param _name [String, Symbol] an aggregate name
+      # @return [nil] an implicit edge has no rules for any aggregate
+      def for_aggregate(_name) = nil
+
+      # @return [Boolean] always true
+      def implicit? = true
+
+      # The era record a mint writes for this edge, keyed by the label of the era it reaches.
+      #
+      # @return [Hash] `label` and `edge`, as the journal stores them
+      def record = { label: to, edge: RECORD }
+
+      # Whether a storage change needs no edge file: the scaffold finds no rule, no retirement and
+      # no unresolved name, and every aggregate both shapes have only adds: same identity and
+      # lifecycle field, every held attribute held exactly as before (list or scalar included),
+      # and every attribute gained optional. Anything this cannot tell is breaking.
+      #
+      # @param diff [Hash] the scaffold's diff of the held shape against the current one
+      # @param held [Hash, Runtime::ProjectedBluebook, Bluebook::Declaration] the held era's storage
+      #   shape, a view over it, or a declared bluebook
+      # @param current [Bluebook::Declaration] the current bluebook, which says which of its
+      #   attributes are optional
+      # @return [Boolean]
+      def self.qualifies?(diff, held, current)
+        diff[:aggregates].empty? && diff[:retired].empty? && diff[:unclaimed].empty? &&
+          AdditiveShape.additive?(held, current)
+      end
+    end
+  end
+end

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

@@ -0,0 +1,130 @@
+# frozen_string_literal: true
+
+require_relative "compose"
+require_relative "edge_route"
+require_relative "compose_render"
+require_relative "edge_files"
+
+module Hecks
+  module Translation
+    # Plans `Era.Reconcile` for one domain: the one edge that leads its latest held era to the
+    # current shape, the edge files that edge supersedes, and the named reason a plan is refused.
+    #
+    # Planning reads the held labels, the loaded edges and the edge files, and writes nothing;
+    # `ReconcileFiles` carries out an admitted plan.
+    module Reconcile
+      # What a plan is made from: the domain's name, its held eras (`ordinal:` and `label:`, in
+      # order), the current shape's label, its loaded edges, the edge files of its translations
+      # directory and the directory a composed edge is written under.
+      Scope = Struct.new(:domain, :held, :current, :edges, :files, :directory, keyword_init: true)
+
+      # One domain's plan. `status` is `:no_era`, `:clean`, `:write` or `:refused`; `latest` is the
+      # latest held era (`ordinal:`, `label:`); `edge` is the composed edge when one is needed, and
+      # `removals` the edge files the plan deletes; `refusal` names why a plan is refused.
+      Plan = Struct.new(:domain, :status, :latest, :current, :labels, :edge, :write_path, :text,
+                        :removals, :mints, :refusal, keyword_init: true)
+
+      module_function
+
+      # @param scope [Scope] what the plan is made from
+      # @return [Plan] the plan; `status` is `:refused` with `refusal` naming the reason
+      def plan(scope)
+        return Plan.new(domain: scope.domain, status: :no_era, current: scope.current) if scope.held.empty?
+
+        latest = scope.held.last
+        decide(scope, latest, composition(scope, latest))
+      rescue Runtime::WiringError => e
+        Plan.new(domain: scope.domain, status: :refused, latest: scope.held.last, current: scope.current,
+                 refusal: e.message)
+      end
+
+      # @return [Hash] `chain:` the edges from the latest era, `edge:` the composed edge when the
+      #   chain has more than one step, and `kept:` the edge that already leads to the current shape
+      def composition(scope, latest)
+        chain = EdgeRoute.route(scope.edges, latest[:label], scope.current)
+        return { chain: chain, edge: nil, kept: chain.first } if chain.size <= 1
+
+        edge = Compose.compose(domain: scope.domain, from: latest[:label], to: scope.current, chain: chain)
+        { chain: chain, edge: edge, kept: edge }
+      end
+
+      def decide(scope, latest, composition)
+        removed = superseded(composition, scope.edges, latest)
+        refusal = refusal_for(scope, removed, composition)
+        return refused(scope, latest, refusal) if refusal
+
+        verdict(scope, latest, composition, removed.map { |edge| file_for!(scope, edge) })
+      end
+
+      # The edges a composed plan replaces: every chain step when the chain is composed, and every
+      # other edge leaving the latest held era.
+      def superseded(composition, edges, latest)
+        steps = composition[:chain].size > 1 ? composition[:chain] : []
+        branches = edges.select { |edge| edge.from == latest[:label] && !same?(edge, composition[:kept]) }
+        (steps + branches).uniq { |edge| key(edge) }
+      end
+
+      # The named reason the change is refused: an earlier era still using an edge the change
+      # deletes, or an earlier era the change would leave with no way to the current shape.
+      def refusal_for(scope, removed, composition)
+        after = scope.edges.reject { |edge| removed.any? { |gone| same?(gone, edge) } }
+        after += [composition[:edge]] if composition[:edge]
+        earlier = scope.held[0...-1]
+        still_used(scope.domain, earlier, removed) || uncovered(scope, earlier, after)
+      end
+
+      def still_used(domain, earlier, removed)
+        removed.each do |edge|
+          era = earlier.find { |held| held[:label] == edge.from }
+          next unless era
+
+          return "#{domain}: era #{era[:ordinal]} (#{era[:label]}) still uses the edge #{edge.from} -> " \
+                 "#{edge.to}, which the change would delete"
+        end
+        nil
+      end
+
+      def uncovered(scope, earlier, after)
+        era = earlier.find { |held| !EdgeRoute.reachable?(held[:label], scope.current, after) }
+        return nil unless era
+
+        verb = EdgeRoute.reachable?(era[:label], scope.current, scope.edges) ? "the change would leave" : "no edge leads"
+        "#{scope.domain}: #{verb} era #{era[:ordinal]} (#{era[:label]}) a way to #{scope.current}"
+      end
+
+      def verdict(scope, latest, composition, removal_paths)
+        labels = [latest[:label], *composition[:chain].map(&:to)]
+        edge = composition[:edge]
+        status = edge || removal_paths.any? ? :write : :clean
+        Plan.new(domain: scope.domain, status: status, latest: latest, current: scope.current, labels: labels,
+                 edge: edge, write_path: write_path_for(scope, latest, edge),
+                 text: edge && ComposeRender.render(edge, labels: labels), removals: removal_paths,
+                 mints: latest[:label] != scope.current)
+      end
+
+      def write_path_for(scope, latest, edge)
+        return nil unless edge
+
+        EdgeFiles.path_for(scope.directory, from: latest[:label], to: scope.current)
+      end
+
+      def refused(scope, latest, refusal)
+        Plan.new(domain: scope.domain, status: :refused, latest: latest, current: scope.current, refusal: refusal)
+      end
+
+      # @return [String] the path of the edge file that carries `edge`
+      # @raise [Runtime::WiringError] when no file under the translations directory holds it
+      def file_for!(scope, edge)
+        found = scope.files.find { |file| file.domain == scope.domain && file.from == edge.from && file.to == edge.to }
+        return found.path if found
+
+        raise Runtime::WiringError,
+              "#{scope.domain}: no edge file holds #{edge.from} -> #{edge.to}, so it cannot be removed"
+      end
+
+      def same?(left, right) = !right.nil? && key(left) == key(right)
+
+      def key(edge) = [edge.from, edge.to]
+    end
+  end
+end