hecks 6.0.0 → 7.0.0

data/lib/hecks/secrets.rb

@@ -0,0 +1,111 @@
+require "delegate"
+
+module Hecks
+  # The values a world hands an adapter under a `secret` declaration, held by name so any text a
+  # launcher prints can be scrubbed of them: a refusal, a boot note, a settings line, a result or
+  # an exception's message. The adapter that declared the secret gets the value; whatever a person
+  # or a log sees gets `«secret:NAME»`. Redaction follows the declaration, not a guess at a
+  # value's shape, with one addition: the password inside a `database` URL, which the URL
+  # carries without any adapter declaring it.
+  module Secrets
+    MASK     = "«secret:%s»".freeze
+    PASSWORD = %r{://[^:/@\s]+:([^@\s]+)@}
+
+    @held  = {}
+    @mutex = Mutex.new
+
+    module_function
+
+    # Holds one secret value under its name. An empty or non-String value is nothing to hide.
+    #
+    # @param name [#to_s] the declared name
+    # @param value [Object] the value the world supplied
+    # @return [void]
+    def register(name, value)
+      return unless value.is_a?(String) && !value.empty?
+
+      @mutex.synchronize { @held[value] = name.to_s }
+    end
+
+    # Holds every secret an adapter declares out of the settings it is built with, and the
+    # password of its `database` URL when the URL carries one.
+    #
+    # @param adapter [Bluebook::Adapter, nil] the adapter's declaration; nil holds nothing
+    # @param settings [Hash] the settings the world supplied for it
+    # @return [void]
+    def register_settings(adapter, settings)
+      Array(adapter&.secrets).each { |secret| register(secret, settings[secret.to_sym]) }
+      register_database(settings[:database])
+    end
+
+    # Holds the password a `scheme://user:password@host` URL carries, under a fixed name.
+    #
+    # @param url [Object] the database setting; anything but a URL with a password holds nothing
+    # @return [void]
+    def register_database(url)
+      return unless url.is_a?(String) && (found = url.match(PASSWORD))
+
+      register("database password", found[1])
+    end
+
+    # Replaces every held value in the text with its mask, longest value first so a value that
+    # contains another is masked whole.
+    #
+    # @param text [Object] what is about to be printed; a non-String is returned as it is
+    # @return [Object] the text with each held value masked
+    def redact(text)
+      return text unless text.is_a?(String)
+
+      held = @mutex.synchronize { @held.dup }
+      held.keys.sort_by { |value| -value.length }
+          .reduce(text) { |scrubbed, value| scrubbed.gsub(value) { format(MASK, held[value]) } }
+    end
+
+    # Forgets every held value, for a process that boots another domain.
+    # @return [void]
+    def clear! = @mutex.synchronize { @held.clear }
+
+    # Whether any value is held.
+    # @return [Boolean]
+    def any? = @mutex.synchronize { !@held.empty? }
+
+    # The stream, writing through `redact`; a stream already guarded is returned as it is.
+    #
+    # @param io [IO, #write] the stream to guard
+    # @return [Guarded] the guarded stream
+    def guarded(io) = io.is_a?(Guarded) ? io : Guarded.new(io)
+
+    # Guards the process's own output streams, so a `puts`, `warn` or `abort` anywhere in it
+    # prints no held value. A launcher calls it once, right after it loads the gem.
+    #
+    # @return [void]
+    def guard!
+      $stdout = guarded($stdout)
+      $stderr = guarded($stderr)
+    end
+
+    # A stream whose every write passes through `Secrets.redact`. A value split across two
+    # writes is not caught, which the one-call writes `puts`, `warn` and `abort` make never
+    # happens.
+    class Guarded < SimpleDelegator
+      # @param parts [Array<#to_s>] what is written
+      # @return [Integer] the bytes written
+      def write(*parts) = __getobj__.write(*parts.map { |part| Secrets.redact(part.to_s) })
+
+      # @param parts [Array<#to_s>] the lines; an Array prints one line per element
+      # @return [nil]
+      def puts(*parts) = __getobj__.puts(*parts.flatten.map { |part| Secrets.redact(part.to_s) })
+
+      # @param parts [Array<#to_s>] what is printed
+      # @return [nil]
+      def print(*parts) = __getobj__.print(*parts.map { |part| Secrets.redact(part.to_s) })
+
+      # @param part [#to_s] what is appended
+      # @return [Guarded] self
+      def <<(part)
+        write(part)
+        self
+      end
+    end
+  end
+end

data/lib/hecks/shape_ledger/edge_hygiene.rb

@@ -0,0 +1,170 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Hecks
+  module ShapeLedger
+    # Finds the translation edges that no longer earn their file; it deletes nothing. The graph is
+    # a bluebook's edge files plus its recorded implicit moves, aimed at the current shape. A file is:
+    #
+    # - a **self-loop** when its `from` equals its `to`.
+    # - a **fork** branch when two edges leave a label and both reach the current shape; the branch
+    #   with the fewest steps is kept.
+    # - an **orphan** when it lies on no path from a held era (the ledger label, an implicit move's
+    #   start, or the start of a chain) to the current shape. A sole route is never flagged.
+    #
+    # @example
+    #   EdgeHygiene.findings(dir, ledger: {}, shapes: { "Shop" => "bbbbbb1" }, moves: {})
+    module EdgeHygiene
+      # One edge: the file that declares it (nil for a recorded implicit move) and its two labels.
+      Edge = Struct.new(:path, :from, :to)
+
+      # The list beside the ledger of stale edges already known, each a finding key. A listed edge is
+      # reported as a warning and does not fail the check; any other stale edge fails it.
+      KNOWN_FILE = "known_stale_edges.json"
+
+      # One problem: its kind, the bluebook, the file to remove, a stable key naming the edge, and what
+      # to do.
+      Finding = Struct.new(:kind, :domain, :path, :key, :message, keyword_init: true)
+
+      module_function
+
+      # Raises on each stale edge the known list does not name, and warns of those it does.
+      #
+      # @param directory [String] the domain directory holding `translations/`
+      # @return [String] a warning line for each known stale edge, or empty
+      # @raise [ShapeLedger::Failure] naming each other stale edge and the `git rm` that clears it
+      def report(directory, **world)
+        known = known_stale(File.join(directory, KNOWN_FILE))
+        listed, fresh = findings(directory, **world).partition { |finding| known.include?(finding.key) }
+        raise Failure, lines(fresh).join("\n") unless fresh.empty?
+
+        listed.map { |finding| "\nwarning, known stale edge (#{KNOWN_FILE}) #{lines([finding]).first}" }.join
+      end
+
+      # @return [Array<String>] the finding keys of the known stale edges, empty when there is no list
+      def known_stale(path) = File.exist?(path) ? JSON.parse(File.read(path)) : []
+
+      # @param directory [String] the domain directory holding `translations/`
+      # @param ledger [Hash{String => String}] the committed shape ledger
+      # @param shapes [Hash{String => String}] each bluebook's current storage-shape hash
+      # @param moves [Hash{String => Array<Hash>}] the recorded implicit moves
+      # @return [Array<Finding>] every stale edge file, by bluebook
+      def findings(directory, ledger:, shapes:, moves:)
+        files = Translation::EdgeFiles.scan(directory)
+        shapes.flat_map do |name, hash|
+          recorded = moves.fetch(name, [])
+          domain_findings(name, edges_of(files, name) + implicit_edges(recorded), ShapeLedger.label(hash),
+                          held_labels(ledger[name], recorded))
+        end
+      end
+
+      def edges_of(files, name)
+        files.select { |found| found.domain == name }.map { |f| Edge.new(f.path, f.from, f.to) }
+      end
+
+      # @return [Array<String>] one report line per finding, each telling what to do
+      def lines(findings) = findings.map { |finding| "#{finding.domain}: #{finding.message}" }
+
+      # @return [String] the stable name of the edge a finding is about, as `kind:Bluebook:from>to`
+      def key(kind, name, edge) = "#{kind}:#{name}:#{edge.from}>#{edge.to}"
+
+      def implicit_edges(moves) = moves.map { |move| Edge.new(nil, move["from"], move["to"]) }
+
+      def held_labels(held, moves)
+        [(ShapeLedger.label(held) if held), *moves.map { |move| move["from"] }].compact
+      end
+
+      def domain_findings(name, all, current, held)
+        loops, graph = all.partition { |edge| edge.from == edge.to && edge.path }
+        forks = fork_findings(name, graph, current)
+        route = held + entry_labels(graph)
+        loops.map { |edge| loop_finding(name, edge) } + forks +
+          orphan_findings(name, graph, current, route, forks.map(&:path))
+      end
+
+      def loop_finding(name, edge)
+        Finding.new(kind: :self_loop, domain: name, path: edge.path, key: key(:self_loop, name, edge),
+                    message: "self-loop edge #{edge.from} -> #{edge.to} in #{edge.path}; remove it with " \
+                             "`git rm #{edge.path}`")
+      end
+
+      def fork_findings(name, graph, current)
+        graph.group_by(&:from).flat_map do |label, leaving|
+          live = leaving.select { |edge| leads_to?(edge.to, current, graph) }
+          live.size > 1 ? fork_branch_findings(name, label, live, graph, current) : []
+        end
+      end
+
+      def fork_branch_findings(name, label, live, graph, current)
+        keep = live.min_by { |edge| [steps(edge.to, current, graph), edge.path ? 0 : 1] }
+        (live - [keep]).map do |branch|
+          files = branch_files(branch, keep, graph)
+          Finding.new(kind: :fork, domain: name, path: files.first, key: key(:fork, name, branch),
+                      message: fork_message(label, live, keep, branch, files))
+        end
+      end
+
+      def fork_message(label, live, keep, branch, files)
+        leaving = live.map { |edge| "#{edge.from} -> #{edge.to}" }.join(", ")
+        "fork at #{label}: #{live.size} edges leave it and each reaches the current shape (#{leaving}); " \
+          "keep #{keep.from} -> #{keep.to} and #{removal(branch, files)}, or compose the branch into one edge"
+      end
+
+      def removal(branch, files)
+        return "remove the recorded implicit move #{branch.from} -> #{branch.to} from implicit_moves.json" if files.empty?
+
+        "remove the branch with `git rm #{files.join(" ")}`"
+      end
+
+      # The files only the branch carries: edges leaving a label the branch reaches that the kept
+      # route does not also reach.
+      def branch_files(branch, keep, graph)
+        shared = reached_from(keep.to, graph)
+        own = reached_from(branch.to, graph) - shared
+        [branch, *graph.select { |edge| own.include?(edge.from) }].filter_map(&:path).uniq
+      end
+
+      def orphan_findings(name, graph, current, starts, flagged)
+        carried = starts.flat_map { |label| reached_from(label, graph) }
+        graph.select(&:path).reject { |edge| flagged.include?(edge.path) || carried_to?(edge, carried, current, graph) }
+             .map { |edge| orphan_finding(name, edge, current) }
+      end
+
+      def carried_to?(edge, carried, current, graph) = carried.include?(edge.from) && leads_to?(edge.to, current, graph)
+
+      def orphan_finding(name, edge, current)
+        Finding.new(kind: :orphan, domain: name, path: edge.path, key: key(:orphan, name, edge),
+                    message: "orphan edge #{edge.from} -> #{edge.to} in #{edge.path} lies on no route from a " \
+                             "held era to the current shape #{current}; remove it with `git rm #{edge.path}`")
+      end
+
+      # @return [Array<String>] labels no edge leads into: the first shape of each chain
+      def entry_labels(graph) = graph.map(&:from).uniq - graph.map(&:to)
+
+      def leads_to?(label, current, graph) = label == current || reached_from(label, graph).include?(current)
+
+      # @return [Array<String>] every label a chain of edges leads to from one label, itself included
+      def reached_from(label, graph)
+        seen = [label]
+        seen.each { |at| graph.each { |edge| seen << edge.to if edge.from == at && !seen.include?(edge.to) } }
+        seen
+      end
+
+      # @return [Integer, Float] the fewest edges from one label to another, infinite when none
+      def steps(label, current, graph)
+        distance = { label => 0 }
+        graph.size.times { widen(distance, graph) }
+        distance.fetch(current, Float::INFINITY)
+      end
+
+      def widen(distance, graph)
+        graph.each do |edge|
+          next unless distance.key?(edge.from)
+
+          distance[edge.to] = [distance[edge.to], distance[edge.from] + 1].compact.min
+        end
+      end
+    end
+  end
+end

data/lib/hecks/shape_ledger/scope.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module Hecks
+  module ShapeLedger
+    # Which bluebooks the ledger holds. A bluebook is held when its committed persistence is an
+    # era-managed adapter, or when it is a framework member such as Governance, which clients
+    # persist. Every other bluebook is tooling, Memory by its committed world (ADR 0136), with no
+    # database whose eras a shape change could strand.
+    module Scope
+      module_function
+
+      # @param directory [String] the domain directory
+      # @return [Runtime::Registry] its bluebooks as committed: no local or environment overlay
+      def committed_registry(directory)
+        Adapters::FolderOverlay.committed_only { Hecks.describe(directory, environment: nil).registry }
+      end
+
+      # @param registry [Runtime::Registry] the committed registry
+      # @return [Array(Array<String>, Hash{String => String})] the names the ledger holds, and each
+      #   skipped bluebook's name mapped to its committed adapter
+      def of(registry)
+        held, skipped = registry.bluebooks.partition { |name, bluebook| held?(registry, name, bluebook) }
+        [held.map(&:first), skipped.to_h { |name, bluebook| [name, adapter_of(registry, name, bluebook)] }]
+      end
+
+      # @return [Array(Hash, Hash, Hash)] the shapes and the ledger entries of the bluebooks held,
+      #   and the bluebooks skipped
+      def view(registry, path)
+        skipped = of(registry).last
+        [ShapeLedger.shapes_of(registry), ShapeLedger.read(path)].map { |held| held.except(*skipped.keys) } << skipped
+      end
+
+      # @return [String] the line naming the skipped bluebooks, empty when there are none
+      def note(skipped)
+        return "" if skipped.empty?
+
+        "\nskipped #{skipped.size} tooling bluebooks (committed persistence: #{skipped.values.uniq.join(", ")}): " \
+          "#{skipped.keys.join(", ")}"
+      end
+
+      def held?(registry, name, bluebook)
+        Framework.members.key?(name) || Runtime::EraCheck.lineage_capable?(registry, adapter_of(registry, name, bluebook))
+      end
+
+      def adapter_of(registry, name, bluebook)
+        first = bluebook.aggregates.first
+        first ? Runtime::EraCheck.adapter_for(registry, name, first) : Ports::Persistence::DEFAULT_ADAPTER
+      end
+    end
+  end
+end

data/lib/hecks/shape_ledger/status.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+module Hecks
+  module ShapeLedger
+    # The ledger status of each bluebook under a directory, read from the committed ledger and its
+    # edges, never from a database. A status is one of:
+    #
+    # - `current`: the ledger holds the shape the bluebook now has.
+    # - `behind`: the shape the ledger holds leads to the current one. `move` names the implicit
+    #   move the ledger records for that step, or is nil when no such move is recorded.
+    # - `superseded`: the current shape is an older one than the ledger holds.
+    # - `unminted`: the ledger has no entry for the bluebook, or no chain of edges or recorded moves
+    #   leads from what it holds to the current shape.
+    #
+    # @example
+    #   Status.of("lib/hecks/hecks")["bluebooks"]["Governance"]["status"]  # => "current"
+    module Status
+      module_function
+
+      # @param directory [String] the domain directory whose bluebooks the ledger records
+      # @param registry [Runtime::Registry] the domain's loaded registry; loaded here when not given
+      # @return [Hash] `domain`, and `bluebooks`: each bluebook's status row, by name
+      def of(directory, registry: Hecks.describe(directory).registry)
+        path = File.join(directory, FILE)
+        ledger = ShapeLedger.read(path)
+        moves = ShapeLedger.implicit_moves(ShapeLedger.implicit_path(path))
+        edges = ShapeLedger.with_implicit(ShapeLedger.edges_of(registry), moves)
+        bluebooks = registry.bluebooks.slice(*Scope.of(Scope.committed_registry(directory)).first).to_h do |name, bluebook|
+          [name, classify(name, ledger[name], Runtime::StorageShape.mint_hash(bluebook), moves, edges)]
+        end
+        { "domain" => directory, "bluebooks" => bluebooks }
+      end
+
+      # @param name [String] the bluebook's name
+      # @param held [String, nil] the storage-shape hash the ledger holds, nil when it has none
+      # @param now [String] the storage-shape hash of the bluebook as it is now
+      # @param moves [Hash{String => Array<Hash>}] each bluebook's recorded implicit moves
+      # @param edges [Hash{String => Array<Array(String, String)>}] each bluebook's edges and moves
+      # @return [Hash] the bluebook's status row
+      def classify(name, held, now, moves, edges)
+        return unminted(name, now) unless held
+
+        held_label = ShapeLedger.label(held)
+        now_label = ShapeLedger.label(now)
+        return row("current", held_label, now_label) if held_label == now_label
+
+        ahead_of(held_label, now_label, moves.fetch(name, []), edges.fetch(name, []))
+      end
+
+      # @return [Hash] a row for a bluebook the ledger holds no shape for
+      def unminted(name, now)
+        row("unminted", nil, ShapeLedger.label(now), reason: "the ledger holds no shape for #{name}")
+      end
+
+      # Places the current shape against the held one when they differ.
+      #
+      # @return [Hash] a `superseded`, `behind` or `unminted` row
+      def ahead_of(held, now, recorded, edges)
+        return superseded(held, now) if ShapeLedger.reachable?(now, held, edges)
+        return behind(held, now, recorded) if ShapeLedger.reachable?(held, now, edges)
+
+        row("unminted", held, now, reason: "no translation edge or recorded implicit move leads from #{held} to #{now}")
+      end
+
+      # @return [Hash] a row for a shape older than the one the ledger holds
+      def superseded(held, now)
+        row("superseded", held, now, reason: "the current shape #{now} is older than the ledger's #{held}")
+      end
+
+      # @param held [String] the label the ledger holds
+      # @param now [String] the label the bluebook now has
+      # @param recorded [Array<Hash>] the bluebook's recorded implicit moves
+      # @return [Hash] a row for a shape one recorded move or edge ahead of the ledger
+      def behind(held, now, recorded)
+        move = recorded.find { |entry| entry["from"] == held && entry["to"] == now }
+        return row("behind", held, now, move: move) if move
+
+        row("behind", held, now, reason: "no implicit move is recorded from #{held} to #{now}")
+      end
+
+      # @return [Hash] one bluebook's status, with every field present; `source` says it was read
+      #   from the ledger
+      def row(status, held, now, move: nil, reason: nil)
+        { "status" => status, "held" => held, "current" => now, "move" => move, "reason" => reason,
+          "source" => "ledger" }
+      end
+    end
+  end
+end

data/lib/hecks/shape_ledger.rb

@@ -1,6 +1,9 @@
-require "fileutils"
 require "json"
 require "hecks"
+require_relative "ports/persistence/plugins/era/era_check"
+require_relative "shape_ledger/scope"
+require_relative "shape_ledger/status"
+require_relative "shape_ledger/edge_hygiene"
 
 module Hecks
   # The committed record of each bluebook's storage shape, held against the shapes the bluebooks
@@ -10,17 +13,24 @@ module Hecks
   # that at a boot only runs against a real database, which specs and gates do not use, so this one
   # reads nothing but the loaded bluebooks and the committed edges: it needs no database.
   #
+  # It holds only a bluebook whose committed persistence is an era adapter, or a framework member
+  # that clients persist (see `Scope`); tooling is Memory and needs no entry.
+  #
   # @example
-  #   ShapeLedger.check("lib/hecks/hecks")  # => "15 bluebook shapes, each the one the ledger holds"
+  #   ShapeLedger.check("lib/hecks/hecks")  # => "1 bluebook shapes, each ..."
   module ShapeLedger
     # The ledger file, beside the bluebooks it records.
     FILE = "shapes.json".freeze
 
+    # The record beside the ledger of each implicit move: a shape change that carried no edge file
+    # and was settled with `--confirm --additive`. Each bluebook maps to its `{from, to}` moves.
+    IMPLICIT_FILE = "implicit_moves.json".freeze
+
     # The length of the label a translation edge names a shape by.
     LABEL = 6
 
     # What a problem line tells the reader to do.
-    REWRITE = "rewrite the ledger with `hecks conformance_run.check_shape_ledger --confirm --wait`".freeze
+    REWRITE = "rewrite the ledger with `hecks conformance_run.check_shape_ledger! --confirm --wait`".freeze
 
     # Raised with every problem found, or when the ledger cannot be rewritten.
     class Failure < StandardError; end
@@ -31,17 +41,22 @@ module Hecks
     #
     # @param directory [String] the domain directory whose bluebooks the ledger records
     # @param confirm [Boolean] rewrite the ledger when every moved shape has an edge
-    # @param additive [Boolean] with `confirm`, write the empty edge for each shape that moved with
-    #   none, on the operator's word that the change only adds; the mint audits every edge against
-    #   the records it migrates and refuses one that would lose data
+    # @param additive [Boolean] with `confirm`, move the ledger for each shape that moved with no
+    #   edge, on the operator's word that the change only adds. No edge file is written: the boot
+    #   and the mint treat such a move as an implicit empty edge, and the mint refuses any change
+    #   the scaffold does not find to be additive
     # @return [String] the clean verdict, or what was written
     # @raise [Failure] with each problem
     def check(directory, confirm: false, additive: false)
-      registry = Hecks.describe(directory).registry
-      shapes = shapes_of(registry)
-      edges = edges_of(registry)
+      registry = Scope.committed_registry(directory)
       path = File.join(directory, FILE)
-      confirm ? rewrite(path, shapes, edges, directory, additive) : verdict(path, shapes, edges)
+      shapes, ledger, skipped = Scope.view(registry, path)
+      moves = implicit_moves(implicit_path(path))
+      edges = with_implicit(edges_of(registry), moves)
+      return rewrite(path, ledger, shapes, edges, additive) if confirm
+
+      verdict(ledger, shapes, edges) + Scope.note(skipped) +
+        EdgeHygiene.report(directory, ledger: ledger, shapes: shapes, moves: moves)
     end
 
     # @param registry [Runtime::Registry] the loaded bluebooks
@@ -58,6 +73,18 @@ module Hecks
 
     def pairs(edges) = edges.map { |edge| [edge.from, edge.to] }
 
+    # @return [Hash{String => Array<Array(String, String)>}] `edges` with each recorded implicit
+    #   move added as an edge: the boot and the mint read a recorded move as an empty edge
+    def with_implicit(edges, record)
+      record.each_with_object(edges.dup) do |(name, moves), merged|
+        merged[name] = merged.fetch(name, []) + pairs_of(moves)
+      end
+    end
+
+    # @param moves [Array<Hash>] recorded `{"from" => ..., "to" => ...}` moves
+    # @return [Array<Array(String, String)>] the moves as `[from, to]`
+    def pairs_of(moves) = moves.map { |move| [move["from"], move["to"]] }
+
     def label(hash) = hash.to_s[0, LABEL]
 
     # @return [Boolean] whether a chain of edges leads from one label to another
@@ -74,8 +101,8 @@ module Hecks
       fresh
     end
 
-    def verdict(path, shapes, edges)
-      problems = problems(read(path), shapes, edges)
+    def verdict(ledger, shapes, edges)
+      problems = problems(ledger, shapes, edges)
       raise Failure, problems.join("\n") unless problems.empty?
 
       "#{shapes.size} bluebook shapes, each the one the ledger holds"
@@ -100,25 +127,49 @@ module Hecks
     # What to commit: the empty edge covers a change that only adds, and a change that renames or
     # reshapes data needs the rules the scaffold writes from the database that holds the eras.
     def edge_advice(name, from, now)
-      edge = %(Hecks.data_translation "#{name}", from: "#{from}", to: "#{now}" do end)
-      "for a change that only adds, commit this edge under translations/ (as 2-#{now}.bluebook): #{edge}. " \
-        "Data that is renamed or reshaped needs rules: `hecks query era.scaffold_translation " \
-        "domain.value=<directory>` writes them, reading the eras from the database the domain's " \
-        "own world names. A change that only adds is settled in one step " \
-        "by `hecks conformance_run.check_shape_ledger --confirm --additive --wait`"
+      "#{name} moved with no edge. A change that only adds needs no edge file: settle it in one step " \
+        "with `hecks conformance_run.check_shape_ledger! --confirm --additive --wait`, which the boot and " \
+        "the mint treat as an implicit empty edge from #{from} to #{now}. Data that is renamed or reshaped " \
+        "needs rules: `hecks query era.scaffold_translation domain.value=<directory>` writes them, reading " \
+        "the eras from the database the domain's own world names."
     end
 
-    def rewrite(path, shapes, edges, directory, additive)
-      ledger = read(path)
-      written = additive ? write_edges(directory, uncovered_moves(ledger, shapes, edges)) : []
+    def rewrite(path, ledger, shapes, edges, additive)
+      implicit = additive ? uncovered_moves(ledger, shapes, edges) : []
       uncovered = additive ? [] : problems(ledger, shapes, edges).reject { |line| line.include?(REWRITE) }
       raise Failure, uncovered.join("\n") unless uncovered.empty?
 
       File.write(path, "#{JSON.pretty_generate(shapes.sort.to_h)}\n")
-      "wrote #{shapes.size} bluebook shapes to #{path}#{edges_note(written)}"
+      record_implicit(implicit_path(path), implicit)
+      "wrote #{shapes.size} bluebook shapes to #{path}#{implicit_note(implicit)}"
     end
 
-    def edges_note(written) = written.empty? ? "" : " and #{written.size} empty edge(s): #{written.join(", ")}"
+    # Appends each implicit move to the record, once: a move the record already holds is skipped.
+    #
+    # @param path [String] the record file beside the ledger
+    # @param moves [Array<Array(String, String, String)>] `[bluebook, from, to]` for each move
+    # @return [void]
+    def record_implicit(path, moves)
+      return if moves.empty?
+
+      record = implicit_moves(path)
+      moves.each { |name, from, now| append_move(record, name, { "from" => from, "to" => now }) }
+      File.write(path, "#{JSON.pretty_generate(record.sort.to_h)}\n")
+    end
+
+    def append_move(record, name, move)
+      entries = record.fetch(name, [])
+      record[name] = entries.include?(move) ? entries : entries + [move]
+    end
+
+    def implicit_path(path) = File.join(File.dirname(path), IMPLICIT_FILE)
+
+    def implicit_note(moves)
+      return "" if moves.empty?
+
+      named = moves.map { |name, from, now| "#{name} #{from} -> #{now}" }
+      " and #{moves.size} implicit move(s), no edge file: #{named.join(", ")}"
+    end
 
     # @return [Array<Array(String, String, String)>] `[bluebook, from, to]` for each shape that
     #   moved
@@ -133,17 +184,11 @@ module Hecks
       end
     end
 
-    # @return [Array<String>] the paths of the empty edges written
-    def write_edges(directory, moves)
-      FileUtils.mkdir_p(File.join(directory, "translations"))
-      moves.map do |name, from, now|
-        path = File.join(directory, "translations", "2-#{now}.bluebook")
-        File.write(path, %(Hecks.data_translation "#{name}", from: "#{from}", to: "#{now}" do\nend\n))
-        path
-      end
-    end
-
     # @return [Hash{String => String}] the ledger, empty when there is none yet
     def read(path) = File.exist?(path) ? JSON.parse(File.read(path)) : {}
+
+    # @param path [String] the implicit-move record
+    # @return [Hash{String => Array<Hash>}] each bluebook's recorded moves, empty when there is none
+    def implicit_moves(path) = File.exist?(path) ? JSON.parse(File.read(path)) : {}
   end
 end

data/lib/hecks/site/bluebook/site.bluebook

@@ -23,6 +23,7 @@ Hecks.bluebook "Site" do
 
   aggregate "Route" do
     description "The shape of one row of a site's route table: where a path is served from, who may reach it, how it is cached, and where it appears in the navigation."
+    acknowledges :no_command_surface, "a route row is declared data: the table is what a site's bluebook says, and no command changes a row"
 
     identified_by :path
 

data/lib/hecks/storehouse/audit.rb

@@ -4,11 +4,18 @@ module Hecks
     # reading it back as a tail or as the events it announced. Extended onto `Storehouse`.
     module Audit
       # The caller-supplied fields of an audit line, in the order the line spells them.
-      AUDIT_FIELDS = %i[verb summary source role actor_id].freeze
+      AUDIT_FIELDS = %i[verb summary source role actor_id surface].freeze
 
       # A character a log file's name may not carry.
       UNSAFE_NAME_CHARACTER = /[^A-Za-z0-9_-]/
 
+      # The boundary between a lowercase or digit character and an uppercase one, where a
+      # CamelCase word takes an underscore.
+      CAMEL_CASE_BOUNDARY = /([a-z\d])([A-Z])/
+
+      # The last segment of a qualified constant name, such as `TypeMismatch` in `Runtime::TypeMismatch`.
+      UNQUALIFIED_NAME = /[^:]+\z/
+
       # Kept under Hecks::CacheDir, not the domain directory (part of the domain's
       # own state) or the gem directory (read-only once installed).
       # :nodoc:
@@ -27,14 +34,37 @@ module Hecks
       def record!(domain_name, tool:, outcome:, **entry)
         return unless domain_name
 
-        line = { time: Time.now.utc.iso8601, tool: tool }.merge(AUDIT_FIELDS.to_h { |field| [field, entry[field]] })
-                                                         .merge(outcome.slice(:ok, :id, :error, :events)).compact
         FileUtils.mkdir_p(log_root)
-        File.open(log_path(domain_name), "a") { |f| f.puts(JSON.generate(line)) }
+        File.open(log_path(domain_name), "a") { |f| f.puts(JSON.generate(audit_line(tool, outcome, entry))) }
       rescue StandardError
         nil
       end
 
+      # One audit line as a hash: when, the tool, the caller's fields, the outcome's fields, then
+      # the call's duration and refusal kind, with absent values left out.
+      # :nodoc:
+      def audit_line(tool, outcome, entry)
+        fields = AUDIT_FIELDS.to_h { |field| [field, entry[field]] }
+        { time: Time.now.utc.iso8601, tool: tool, **fields, **outcome.slice(:ok, :id, :error, :events),
+          **entry.slice(:duration_ms, :refusal) }.compact
+      end
+
+      # Whole milliseconds since `started`, a CLOCK_MONOTONIC reading.
+      # :nodoc:
+      def elapsed_ms(started)
+        ((Process.clock_gettime(Process::CLOCK_MONOTONIC) - started) * 1000).round
+      end
+
+      # The refusal's class as a snake_case kind, such as `type_mismatch`.
+      # :nodoc:
+      def refusal_kind(error)
+        snake_case(error.class.name[UNQUALIFIED_NAME])
+      end
+
+      # The word with an underscore at each CamelCase boundary, in lowercase.
+      # :nodoc:
+      def snake_case(word) = word.gsub(CAMEL_CASE_BOUNDARY, '\\1_\\2').downcase
+
       # Tails this bus's own dispatch/query/state audit log — a pull-based
       # substitute for a push subscription, since a stdio server answers one
       # request at a time with no channel to push through.