hecks 5.0.0 → 7.0.0

data/lib/hecks/sentence_form.rb

@@ -0,0 +1,212 @@
+require "digest"
+require "fileutils"
+require "open3"
+require_relative "cache_dir"
+
+module Hecks
+  # A `.bluebook` written as plain sentences (its first line is `Domain: <name>`) rather than in
+  # the Ruby form. The Rust parser is the one reader of the sentences: it renders them as the
+  # Ruby-shaped text that declares the same bluebook, and Ruby evaluates that text under the
+  # sentence file's own path, so the registry records the file the author wrote.
+  module SentenceForm
+    # The repository root, where the parser's build lands under `rust/parser/target/`.
+    ROOT = File.expand_path("../..", __dir__).freeze
+
+    # The line a sentence-form file opens with, after any blank or comment lines.
+    DOMAIN_LINE = /\A\s*Domain:/
+
+    # The first line of a tool's output, without its newline.
+    FIRST_LINE = /\A[^\n]*/
+
+    # A `Hecks.bluebook "Name"` header line, or a `Domain: name` line, capturing the bluebook's
+    # name.
+    BLUEBOOK_HEADER = /\A\s*(?:Hecks\.bluebook\s+"([^"]+)"|Domain:\s*(\S.*?)\s*\z)/
+
+    # Raised when no `hecks-parse` binary can be found.
+    class ParserMissing < StandardError; end
+
+    # Raised when the parser refuses a sentence file; the message is its diagnostic.
+    class Refused < StandardError; end
+
+    module_function
+
+    # @param path [String] a `.bluebook` file
+    # @return [Boolean] whether the file is written as sentences
+    def sentences?(path)
+      first = File.foreach(path).find { |line| !line.strip.empty? && !line.lstrip.start_with?("#") }
+      !first.nil? && first.match?(DOMAIN_LINE)
+    end
+
+    # @param path [String] a bluebook file, in either form
+    # @return [String, nil] the bluebook name its header declares; a `Domain:` line is read as
+    #   the words capitalised and joined, as the parser reads it
+    def declaration_name(path)
+      File.foreach(path) do |line|
+        next unless line =~ BLUEBOOK_HEADER
+
+        return Regexp.last_match(1) || capitalised(Regexp.last_match(2))
+      end
+      nil
+    end
+
+    # @param words [String] the words of a `Domain:` line
+    # @return [String] each word capitalised and the words joined, as the parser reads them
+    def capitalised(words) = words.split.map { |word| word[0].upcase + word[1..] }.join
+
+    # @param text [String] a tool's error output
+    # @return [String] its first line, without the newline
+    def first_line(text) = text.to_s[FIRST_LINE]
+
+    # The Ruby-shaped text of a sentence-form file.
+    #
+    # @param path [String] a sentence-form `.bluebook`
+    # @return [String] Ruby source declaring the same bluebook
+    # @raise [ParserMissing] if `hecks-parse` is not built
+    # @raise [Refused] if the sentences are not ones the parser knows
+    def ruby_text(path)
+      declaration = declaration_name(path) or raise Refused, "#{path}: no `Domain:` line to name the bluebook"
+      out, err, status = Open3.capture3(binary, "render", "--bluebook", declaration, path)
+      raise Refused, first_line(err) unless status.success?
+
+      out
+    end
+
+    # The extension of an examples file: sentences saying who does what to the domain and what
+    # follows, which the behaviors runner runs.
+    EXAMPLES_EXTENSION = ".examples".freeze
+
+    # The first line of an examples file, naming the bluebook the examples are about.
+    EXAMPLES_LINE = /\A\s*Examples for:\s*(\S.*?)\s*\z/
+
+    # @param path [String] a file the behaviors runner was asked to run
+    # @return [Boolean] whether it is an examples file, not a `.behaviors` file
+    def examples?(path) = path.to_s.end_with?(EXAMPLES_EXTENSION)
+
+    # The `.behaviors` text that runs an examples file against its bluebook.
+    #
+    # The bluebook's files are the `.bluebook` beside the examples file with the same stem or, when
+    # there is none, every `.bluebook` there (or in a `bluebook/` folder there) that declares the
+    # bluebook the examples are about.
+    #
+    # @param path [String] an examples file
+    # @return [String] `.behaviors` source
+    # @raise [ParserMissing] if `hecks-parse` is not built
+    # @raise [Refused] if no bluebook file is found or the examples are not ones the parser accepts
+    def behaviors_text(path)
+      declaration = examples_bluebook(path)
+      files = bluebook_files(path, declaration)
+      raise Refused, "#{path}: no .bluebook beside it declares #{declaration}" if files.empty?
+
+      wiring = behaviors_hecksagon(path)
+      also = wiring ? ["--also", wiring] : []
+      out, err, status = Open3.capture3(binary, "examples", "--bluebook", declaration, "--examples", path, *also, *files)
+      raise Refused, first_line(err) unless status.success?
+
+      out
+    end
+
+    # Writes the `.behaviors` text of an examples file where the runner can load it.
+    #
+    # @param path [String] an examples file
+    # @return [String] the generated `.behaviors` file's path
+    def write_behaviors(path)
+      text = behaviors_text(path)
+      dir = CacheDir.path("sentence_form")
+      FileUtils.mkdir_p(dir)
+      generated = File.join(dir, "#{File.basename(path, EXAMPLES_EXTENSION)}-#{Digest::SHA256.hexdigest(text)[0, 16]}.behaviors")
+      File.write(generated, text) unless File.exist?(generated)
+      generated
+    end
+
+    # The Memory-bound hecksagon that answers a bluebook's asks while its examples run: the
+    # `<name>_behaviors.hecksagon` beside the examples file, as Pizzas keeps one beside its own.
+    #
+    # @param path [String] an examples file
+    # @return [String, nil] its absolute path, or nil when there is none
+    def behaviors_hecksagon(path)
+      wiring = File.join(File.dirname(File.expand_path(path)), "#{File.basename(path, EXAMPLES_EXTENSION)}_behaviors.hecksagon")
+      wiring if File.file?(wiring)
+    end
+
+    # @return [String] the bluebook an examples file's first line names, capitalised and joined
+    def examples_bluebook(path)
+      line = File.foreach(path).find { |text| text.match?(EXAMPLES_LINE) }
+      raise Refused, "#{path}: no `Examples for: <bluebook>` line" unless line
+
+      line.match(EXAMPLES_LINE)[1].split.map { |word| word[0].upcase + word[1..] }.join
+    end
+
+    # @return [Array<String>] absolute paths of the `.bluebook` files the examples are about
+    def bluebook_files(path, declaration)
+      dir = File.dirname(File.expand_path(path))
+      same_stem = File.join(dir, "#{File.basename(path, EXAMPLES_EXTENSION)}.bluebook")
+      return [same_stem] if File.file?(same_stem)
+
+      Dir.glob([File.join(dir, "*.bluebook"), File.join(dir, "bluebook", "*.bluebook")])
+         .select { |file| declaration_name(file) == declaration }
+    end
+
+    # Loads a bluebook file in whichever form it is written: sentences through the parser, anything
+    # else as Ruby. Every place that reads a `.bluebook` goes through here, so no boot path accepts
+    # one form and refuses the other.
+    #
+    # @param path [String] a bluebook file, or any other Ruby file
+    # @return [void]
+    def load_file(path)
+      sentences = path.end_with?(".bluebook") && File.file?(path) && sentences?(path)
+      sentences ? load(path) : Kernel.load(path)
+    end
+
+    # Declares the bluebook a sentence-form file holds, in the registry now current.
+    #
+    # The Ruby text is loaded from a file of its own, because a predicate's source is recovered
+    # from the file it was written in; the registry then records the sentence file as the
+    # bluebook's source, not the generated one.
+    #
+    # @param path [String] a sentence-form `.bluebook`
+    # @return [void]
+    def load(path)
+      generated = write_generated(path, ruby_text(path))
+      Kernel.load(generated)
+      point_sources_at(generated, path)
+    end
+
+    # Makes the registry record the sentence file `path` as the source of what `generated` declared.
+    #
+    # @param generated [String] the rendered file that was loaded
+    # @param path [String] the sentence file it came from
+    # @return [void]
+    def point_sources_at(generated, path)
+      registry = Hecks.current_registry
+      registry.bluebook_sources.each_value do |paths|
+        paths.map! { |source| source == generated ? path : source }
+      end
+    end
+
+    # Writes rendered text where Ruby can load it, named by what the text holds so an unchanged
+    # file is written once.
+    #
+    # @param path [String] the sentence file the text was rendered from
+    # @param text [String] the rendered Ruby text
+    # @return [String] the generated file's path
+    def write_generated(path, text)
+      dir = CacheDir.path("sentence_form")
+      FileUtils.mkdir_p(dir)
+      generated = File.join(dir, "#{File.basename(path, ".bluebook")}-#{Digest::SHA256.hexdigest(text)[0, 16]}.bluebook")
+      File.write(generated, text) unless File.exist?(generated)
+      generated
+    end
+
+    # @return [String] the path to `hecks-parse`: `HECKS_PARSE_BIN`, then the release or debug
+    #   build under `rust/parser/target/`, then one on the `PATH`
+    # @raise [ParserMissing] if none exists
+    def binary
+      candidates = [ENV.fetch("HECKS_PARSE_BIN", nil)] +
+                   %w[release debug].map { |profile| File.join(ROOT, "rust/parser/target/#{profile}/hecks-parse") } +
+                   ENV.fetch("PATH", "").split(File::PATH_SEPARATOR).map { |dir| File.join(dir, "hecks-parse") }
+      candidates.compact.find { |path| File.executable?(path) && !File.directory?(path) } or
+        raise ParserMissing, "hecks-parse is not built — run `cargo build --release " \
+                             "--manifest-path rust/parser/Cargo.toml`, or set HECKS_PARSE_BIN"
+    end
+  end
+end

data/lib/hecks/served_options.rb

@@ -1,4 +1,5 @@
 require "rack"
+require_relative "naming"
 
 module Hecks
   # What a domain's world file says it is served by: each `served_by("Adapter") { ... }` line
@@ -48,6 +49,6 @@ module Hecks
       env.fetch(name) { raise ArgumentError, "#{entry[:adapter]}: environment variable #{name} is not set" }
     end
 
-    def snake(name) = name.to_s.gsub(/([a-z\d])([A-Z])/, '\1_\2').downcase
+    def snake(name) = name.to_s.gsub(Naming::CAMEL_BOUNDARY, '\1_\2').downcase
   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