hecks 6.0.0 → 7.0.0

data/lib/hecks/hecks/adapters/journal_store/readings/sqlite_status/database_reading.rb

@@ -0,0 +1,113 @@
+# frozen_string_literal: true
+
+require_relative "../../../../../adapters/driven/sqlite"
+require_relative "read_only"
+
+module Hecks
+  module Adapters
+    class JournalStore
+      module Readings
+        module SqliteStatus
+          # One SQLite file read against the aggregates bound to it. The file is opened with
+          # read-only (see {ReadOnly}) and only `PRAGMA table_info` and `sqlite_master` are read.
+          class DatabaseReading
+            ADAPTERS = %w[Sqlite SqlitePersistence].freeze
+            # Tables the adapter keeps beside every aggregate's own.
+            ABSENT = "absent: created on first open"
+            SHARED_TABLE = /\A(events|hecks_\w+|sqlite_\w+)\z/
+
+            # The files the registry's aggregates are persisted in, each with its aggregates.
+            #
+            # @param registry [Runtime::Registry] a described registry
+            # @return [Hash{String => Array<Bluebook::Aggregate>}] absolute path to aggregates
+            def self.targets(registry)
+              registry.bluebooks.values.each_with_object({}) do |bluebook, found|
+                bluebook.aggregates.each do |aggregate|
+                  path = path_for(registry, bluebook, aggregate)
+                  (found[path] ||= []) << aggregate if path
+                end
+              end
+            end
+
+            # @return [String, nil] the file the aggregate is bound to, nil unless SQLite
+            def self.path_for(registry, bluebook, aggregate)
+              bind = Ports::Persistence::BindingPolicy.resolve(registry, bluebook.name, aggregate)
+              return unless ADAPTERS.include?(bind.adapter.to_s)
+
+              settings = registry.binding_settings(bluebook.name, Ports::Persistence::VERB, bind.adapter)
+              absolute(registry, registry.with_adapter_defaults(bind.adapter, aggregate, settings))
+            rescue Runtime::WiringError
+              nil
+            end
+
+            # @return [String] the settings' database, resolved against the registry's root
+            def self.absolute(registry, settings)
+              declared = settings.transform_keys(&:to_sym)[:database].to_s
+              declared.start_with?("/") ? declared : File.join(registry.root || Dir.pwd, declared)
+            end
+
+            # @param path [String] the database file
+            # @param aggregates [Array<Bluebook::Aggregate>] the aggregates bound to it
+            def initialize(path, aggregates)
+              @path = path
+              @aggregates = aggregates
+            end
+
+            # @return [Hash] `database`, `tables` (one per aggregate) and `orphans`
+            def row
+              return { database: @path, state: ABSENT, tables: [], orphans: [] } unless File.file?(@path)
+
+              db = ReadOnly.open(@path)
+              present = db.execute("SELECT name FROM sqlite_master WHERE type = 'table'").flatten
+              { database: @path, state: "read", tables: @aggregates.map { |a| table_row(db, present, a) },
+                orphans: orphans(present) }
+            ensure
+              db&.close
+            end
+
+            private
+
+            def table_row(db, present, aggregate)
+              base = { aggregate: aggregate.name, table: aggregate.storage_name }
+              return base.merge(state: ABSENT) unless present.include?(base[:table])
+
+              drift = drift_of(columns(db, base[:table]), expected(aggregate))
+              base.merge(state: drift.key?(:missing) ? "drift" : "ok", **drift)
+            end
+
+            # Column names compare without regard to capitals, as the adapter's open does.
+            def drift_of(held, wanted)
+              held_names = held.map(&:downcase)
+              wanted_names = wanted.map(&:downcase)
+              missing = wanted.reject { |name| held_names.include?(name.downcase) }
+              extra = held.reject { |name| wanted_names.include?(name.downcase) || name.casecmp?("id") }
+              { missing: missing, extra: extra }.reject { |_, names| names.empty? }
+            end
+
+            def columns(db, table)
+              db.execute(%(PRAGMA table_info("#{table.gsub('"', '""')}"))).map { |column| column[1] }
+            end
+
+            # The column names the adapter's codec persists, read without opening the adapter.
+            def expected(aggregate)
+              adapter = Hecks::Adapters::Sqlite.allocate
+              adapter.instance_variable_set(:@aggregate, aggregate)
+              adapter.send(:persisted_fields).map { |field| field[:name].to_s }
+            end
+
+            def orphans(present)
+              known = @aggregates.flat_map { |a| [a.storage_name, "#{a.storage_name}_entries"] }
+              (present - known).grep_v(SHARED_TABLE).map { |name| orphan(name) }
+            end
+
+            def orphan(name)
+              stem = name.delete_suffix("_entries")
+              owner = @aggregates.find { |a| [a.name, a.former_name].compact.map { |n| Naming.snake(n) }.include?(stem) }
+              owner ? { table: name, belongs_to: owner.name, stored_as: owner.storage_name } : { table: name }
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/hecks/hecks/adapters/journal_store/readings/sqlite_status/read_only.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Hecks
+  module Adapters
+    class JournalStore
+      module Readings
+        module SqliteStatus
+          # Opens an existing SQLite file so that reading it creates nothing beside it. A plain
+          # read-only open of a database in write-ahead-log mode makes its `-wal` and `-shm`
+          # files, so a database with no `-wal` file is opened `immutable`, which skips them
+          # altogether. One that has a `-wal` file holds changes the reading must see, and
+          # already has the files a read-only open needs.
+          module ReadOnly
+            UNRESERVED = %r{[^A-Za-z0-9\-._~/]}
+
+            # @param path [String] a database file that exists
+            # @return [SQLite3::Database] the open, read-only database; the caller closes it
+            def self.open(path)
+              require "sqlite3"
+              return SQLite3::Database.new(path, readonly: true) if File.exist?("#{path}-wal")
+
+              SQLite3::Database.new("file:#{escape(path)}?immutable=1",
+                                    flags: SQLite3::Constants::Open::READONLY | SQLite3::Constants::Open::URI)
+            end
+
+            # @return [String] the path with every byte a URI reserves written as a percent escape
+            def self.escape(path) = path.gsub(UNRESERVED) { |char| char.bytes.map { |byte| format("%%%02X", byte) }.join }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/hecks/hecks/adapters/journal_store/readings/sqlite_status.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+require "json"
+require_relative "sqlite_status/database_reading"
+
+module Hecks
+  module Adapters
+    class JournalStore
+      module Readings
+        # How the SQLite databases a domain's worlds name stand against its aggregates. Each file
+        # is opened read-only, never through the adapter (whose open adds missing columns), so the
+        # reading writes nothing and shows the drift before an open heals it or a write meets it.
+        module SqliteStatus
+          # @param domain [Hash, String] the domain directory
+          # @return [Hash] `text:` the status as JSON, one row per database file
+          # @raise [Runtime::NotFound] if the directory cannot be loaded
+          def sqlite_status(domain:)
+            answering { JSON.pretty_generate(SqliteStatus.of(Hecks.describe(plain(domain)).registry)) }
+          end
+
+          # @param registry [Runtime::Registry] a described registry
+          # @return [Array<Hash>] one row per SQLite file, in the order the aggregates name them
+          def self.of(registry)
+            DatabaseReading.targets(registry).map do |path, aggregates|
+              DatabaseReading.new(path, aggregates).row
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/hecks/hecks/adapters/journal_store/readings.rb

@@ -7,6 +7,12 @@ require_relative "edge_audit"
 require_relative "compaction"
 require_relative "readings/scaffolding"
 require_relative "readings/attestation"
+require_relative "readings/composition"
+require_relative "readings/boot_status"
+require_relative "readings/sqlite_status"
+require_relative "readings/event_trace"
+require_relative "readings/projection_audit"
+require_relative "readings/mint_plan"
 
 module Hecks
   module Adapters
@@ -22,6 +28,12 @@ module Hecks
 
         include Scaffolding
         include Attestation
+        include Composition
+        include BootStatus
+        include SqliteStatus
+        include EventTrace
+        include ProjectionAudit
+        include MintPlan
 
         # Words the answer for a domain that holds no era.
         #
@@ -29,7 +41,7 @@ module Hecks
         # @param path [String] the domain path, as the operator typed it
         # @return [String] the sentence
         def self.no_era(name, path)
-          "#{name} holds no era yet. `hecks hold_first #{path} --confirm` holds the first."
+          "#{name} holds no era yet. `hecks era.hold_first! #{path} --confirm` holds the first."
         end
 
         # The edge file that would lead the latest held era to the current shape, as its text.

data/lib/hecks/hecks/adapters/journal_store/reconcile_report.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+module Hecks
+  module Adapters
+    class JournalStore
+      # Words the reconciliation's dry run and its written report, from the rows it planned.
+      module ReconcileReport
+        module_function
+
+        # @param row [Reconciliation::Row] one bluebook's row
+        # @return [String] the block that reports the row's plan
+        def render_row(row)
+          return "#{row.name}: its store keeps no eras, so there is nothing to reconcile" unless row.plan
+
+          plan = row.plan
+          head = "#{row.name}: current #{plan.current}"
+          head += ", latest era #{plan.latest[:ordinal]} (#{plan.latest[:label]})" if plan.latest
+          [head, *verdict_lines(plan)].join("\n")
+        end
+
+        # @param writes [Array<Reconciliation::Row>] the rows whose plans were carried out
+        # @return [String] what was written and deleted, per domain
+        def written(writes)
+          lines = writes.flat_map { |row| written_lines(row.name, row.plan) }
+          ["the audit passed for each composed edge", *lines].join("\n")
+        end
+
+        def written_lines(name, plan)
+          written = plan.write_path ? ["  wrote #{File.basename(plan.write_path)}"] : []
+          ["#{name}: #{plan.labels.join(" -> ")}", *written,
+           *plan.removals.map { |path| "  removed #{File.basename(path)}" }]
+        end
+
+        def verdict_lines(plan)
+          case plan.status
+          when :no_era then ["  no era held yet; nothing to reconcile"]
+          when :refused then ["  verdict: REFUSED — #{plan.refusal}"]
+          when :clean then ["  verdict: clean — nothing to write or delete", "  mints: #{mint_line(plan)}"]
+          else write_lines(plan)
+          end
+        end
+
+        def write_lines(plan)
+          lines = ["  chain: #{plan.labels.join(" -> ")}"]
+          lines << "  would write: #{File.basename(plan.write_path)}" if plan.write_path
+          lines += plan.removals.map { |path| "  would delete: #{File.basename(path)}" }
+          lines << "  verdict: write"
+          lines << "  mints: #{mint_line(plan)}"
+        end
+
+        def mint_line(plan)
+          return "no era on the next boot" unless plan.mints
+
+          "era #{plan.latest[:ordinal] + 1} (#{plan.current}) on the next boot of a copy whose world " \
+            "declares mint_eras true"
+        end
+      end
+    end
+  end
+end

data/lib/hecks/hecks/adapters/journal_store/reconciliation.rb

@@ -0,0 +1,121 @@
+# frozen_string_literal: true
+
+require_relative "held_domain"
+require_relative "edge_audit"
+require_relative "reconcile_report"
+
+module Hecks
+  module Adapters
+    class JournalStore
+      # The `reconcile` change: plans every bluebook of a project against the eras its store holds,
+      # and when every plan is admitted writes the composed edges, deletes the edges they supersede,
+      # and audits each written edge. Reading is the dry run; only `apply_reconcile` writes, and a
+      # refused plan in any domain writes nothing.
+      module Reconciliation
+        # The project directory a reconciliation reads when none is named: the hecks checkout's own
+        # domain directory, whose `translations/` holds the edges of every domain it loads.
+        DEFAULT_PROJECT = File.expand_path("../..", __dir__)
+
+        # One bluebook's plan; `plan` is nil when its store keeps no eras.
+        Row = Struct.new(:name, :plan, keyword_init: true) do
+          def refusal = plan&.refusal
+
+          def status = plan&.status
+
+          def edge = plan&.edge
+        end
+
+        # The dry run: one report of every domain's plan, written nowhere.
+        #
+        # @param domain [Hash, String, nil] the project directory; the checkout's own when absent
+        # @return [Hash] `text:` the report, one block per domain
+        # @raise [Runtime::NotFound] if the project cannot be loaded
+        def reconcile_plan(domain: nil)
+          answering { project_rows(project_path(domain)).map { |row| ReconcileReport.render_row(row) }.join("\n\n") }
+        end
+
+        private
+
+        # Examines nothing: the plans decide what is admitted, and `apply_reconcile` refuses a store
+        # that keeps no eras.
+        def examine_reconcile(_held) = { capable: true }
+
+        def apply_reconcile(held)
+          path = project_path(held[:domain])
+          rows = project_rows(path)
+          refusals = rows.filter_map(&:refusal)
+          unless refusals.empty?
+            raise Runtime::WiringError, "nothing was written; the reconciliation refused:\n  #{refusals.join("\n  ")}"
+          end
+
+          write_reconciled(path, rows.select { |row| row.status == :write })
+        end
+
+        def write_reconciled(path, writes)
+          return "every domain already leads to its current shape — nothing to reconcile." if writes.empty?
+
+          originals = writes.reduce({}) { |found, row| found.merge(Translation::ReconcileFiles.write!(row.plan)) }
+          begin
+            writes.each { |row| audit_written!(path, row) }
+          rescue StandardError
+            Translation::ReconcileFiles.restore!(originals)
+            raise
+          end
+          ReconcileReport.written(writes)
+        end
+
+        # Audits the composed edge a row wrote; a row that only deleted edges has nothing to audit.
+        #
+        # @raise [Runtime::WiringError] when the audit refuses the composed edge
+        def audit_written!(path, row)
+          return unless row.edge
+
+          project = HeldDomain.open(path)
+          domain = HeldDomain.new(project.registry, project.directory, row.name)
+          finding = domain.reading { |lineage| EdgeAudit.call(domain, lineage, domain.held_eras(lineage)) }
+          return if finding.nil? || finding.ok
+
+          raise Runtime::WiringError,
+                "cannot reconcile #{row.name}: the audit refused the composed edge —\n  " \
+                "#{finding.refusals.join("\n  ")}"
+        end
+
+        def project_path(domain) = plain(domain) || DEFAULT_PROJECT
+
+        # @return [Array<Row>] one row per bluebook the project loads, in the registry's order
+        def project_rows(path)
+          project = HeldDomain.open(path)
+          project.bluebook_names.map { |name| bluebook_row(project, name) }
+        end
+
+        def bluebook_row(project, name)
+          domain = HeldDomain.new(project.registry, project.directory, name)
+          return Row.new(name: name) unless domain.capable?
+
+          domain.reading { |lineage| Row.new(name: name, plan: domain_plan(domain, lineage, project)) }
+        end
+
+        def domain_plan(domain, lineage, project)
+          Translation::Reconcile.plan(
+            Translation::Reconcile::Scope.new(
+              domain: domain.domain_name, held: held_labels(domain, lineage), current: current_label(domain),
+              edges: domain.translations.select { |edge| edge.domain == domain.domain_name },
+              files: Translation::EdgeFiles.scan(project.directory), directory: project.directory
+            )
+          )
+        end
+
+        def held_labels(domain, lineage)
+          domain.held_eras(lineage).map do |era|
+            named = domain.named(era)
+            { ordinal: named[:ordinal], label: named[:label] }
+          end
+        end
+
+        def current_label(domain)
+          Runtime::StorageShape.mint_hash(domain.bluebook)[0, Runtime::StorageShape::LABEL_LENGTH]
+        end
+      end
+    end
+  end
+end

data/lib/hecks/hecks/adapters/journal_store/translation_write/shape_edge.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module Hecks
+  module Adapters
+    class JournalStore
+      module TranslationWrite
+        # The edge for a shape that changed under an unchanged label: the scaffold's diff, written from
+        # the label to itself. Only `TranslationWrite` includes it.
+        module ShapeEdge
+          # A line of an edge file that still marks a field as undecided.
+          UNRESOLVED_LINE = /^\s*unresolved /
+
+          private
+
+          # A held label that equals the current one with a different projection: the edge is the
+          # scaffold's diff, from the label to itself. A field the diff cannot decide refuses the write.
+          #
+          # @raise [Runtime::WiringError] when the diff leaves a field or an aggregate to decide
+          def shape_edge_plan(domain, latest, current)
+            diffed = diff_for(domain, latest)
+            refuse_undecided!(domain, "UNCLAIMED #{diffed[:unclaimed].join(", ")}") unless diffed[:unclaimed].empty?
+            text = Translation::Scaffold.render(shape_edge(domain, latest, current, diffed))
+            refuse_undecided!(domain, "unresolved fields") if text.match?(UNRESOLVED_LINE)
+            Plan.new(path: Translation::EdgeFiles.path_for(domain.directory, from: latest[:label], to: current),
+                     text: text, removals: [], labels: [latest[:label], current])
+          end
+
+          def diff_for(domain, latest)
+            Translation::Scaffold.diff(PostgresEra::LineageManager.held_bluebook(latest), domain.bluebook)
+          end
+
+          def shape_edge(domain, latest, current, diffed)
+            Translation::Scaffold::Edge.new(domain: domain.domain_name, from: latest[:label], to: current,
+                                            ordinal: latest[:ordinal] + 1, label: current,
+                                            aggregates: diffed[:aggregates], retired: diffed[:retired])
+          end
+
+          def refuse_undecided!(domain, reason)
+            raise Runtime::WiringError,
+                  "cannot write the translation of #{domain.domain_name}: the shape changed under the same label " \
+                  "and the scaffold leaves #{reason} to decide; write the edge by hand"
+          end
+
+          def already_leads(from, to)
+            Plan.new(message: "one edge already leads #{from} to #{to} — nothing to write.")
+          end
+
+          def edge_plan(domain, from, to, chain)
+            edge = Translation::Compose.compose(domain: domain.domain_name, from: from, to: to, chain: chain)
+            labels = [from, *chain.map(&:to)]
+            stale = Translation::EdgeFiles.stale(domain.directory, domain: domain.domain_name, chain: chain)
+            Plan.new(path: Translation::EdgeFiles.path_for(domain.directory, from: from, to: to),
+                     text: Translation::ComposeRender.render(edge, labels: labels), removals: stale, labels: labels)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/hecks/hecks/adapters/journal_store/translation_write.rb

@@ -0,0 +1,123 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require_relative "held_domain"
+require_relative "edge_audit"
+require_relative "translation_write/shape_edge"
+
+module Hecks
+  module Adapters
+    class JournalStore
+      # The `write_translation` change: composes the chain of edges from the latest held era to the
+      # current shape into one edge, writes it, deletes the intermediate edges only the chain used,
+      # and audits what was written. A refused audit puts the translations directory back as it was.
+      #
+      # Planning is a read; only `apply_write_translation` writes, and only to the domain's own
+      # `translations/` directory.
+      module TranslationWrite
+        # What a write would do: the file it writes and its text, the stale files it deletes, and
+        # the shape labels the chain passes through. `message` alone answers when nothing is to be done.
+        Plan = Struct.new(:message, :path, :text, :removals, :labels, keyword_init: true)
+
+        include ShapeEdge
+
+        private
+
+        def examine_write_translation(held)
+          domain = HeldDomain.open(plain(held[:domain]))
+          return {} unless domain.capable?
+
+          domain.reading do |lineage|
+            translation_plan(domain, lineage)
+            { capable: true, held: domain.held_eras(lineage).size }
+          end
+        end
+
+        def apply_write_translation(held)
+          path = plain(held[:domain])
+          domain = HeldDomain.open(path)
+          plan = domain.reading { |lineage| translation_plan(domain, lineage) }
+          return plan.message if plan.message
+
+          write_and_audit(path, plan)
+          written_report(plan)
+        end
+
+        # Writes the plan, then audits what it wrote; a refusal or a failure restores the files.
+        def write_and_audit(path, plan)
+          originals = write_translation!(plan)
+          begin
+            audit_written_translation!(path)
+          rescue StandardError
+            restore_translations!(originals)
+            raise
+          end
+        end
+
+        # The plan a write would carry out, or the sentence that says none is needed.
+        #
+        # @return [Plan] see `Plan`
+        # @raise [Runtime::WiringError] when the chain cannot be composed into one edge
+        def translation_plan(domain, lineage)
+          eras = domain.held_eras(lineage)
+          return Plan.new(message: "#{domain.domain_name} holds no era yet — nothing to write.") if eras.empty?
+
+          latest = domain.named(eras.last)
+          return Plan.new(message: "#{domain.domain_name} matches era #{latest[:ordinal]} — nothing to write.") if
+            held_shape(latest) == domain.shape
+
+          composed_plan(domain, latest)
+        end
+
+        def held_shape(era) = PostgresEra::LineageManager.held_shape(era)
+
+        def composed_plan(domain, latest)
+          current = Runtime::StorageShape.mint_hash(domain.bluebook)[0, Runtime::StorageShape::LABEL_LENGTH]
+          chain = Translation::Compose.chain(domain.translations, domain: domain.domain_name,
+                                                                  from: latest[:label], to: current)
+          return already_leads(latest[:label], current) if chain.size == 1
+          return shape_edge_plan(domain, latest, current) if chain.empty?
+
+          edge_plan(domain, latest[:label], current, chain)
+        end
+
+        # Writes the composed edge and deletes the stale ones; returns what each file held before.
+        #
+        # @return [Hash{String => String, nil}] each touched path with its earlier text, nil if absent
+        def write_translation!(plan)
+          originals = [plan.path, *plan.removals].to_h { |path| [path, read_if_present(path)] }
+          File.write(plan.path, plan.text)
+          plan.removals.each { |path| FileUtils.rm_f(path) }
+          originals
+        end
+
+        def read_if_present(path) = File.exist?(path) ? File.read(path) : nil
+
+        # Puts each touched file back as `write_translation!` found it.
+        def restore_translations!(originals)
+          originals.each do |path, text|
+            text ? File.write(path, text) : FileUtils.rm_f(path)
+          end
+        end
+
+        # Audits the edge that was just written, as the boot does.
+        #
+        # @raise [Runtime::WiringError] when the audit refuses the composed edge
+        def audit_written_translation!(path)
+          domain = HeldDomain.open(path)
+          finding = domain.reading { |lineage| EdgeAudit.call(domain, lineage, domain.held_eras(lineage)) }
+          return if finding.nil? || finding.ok
+
+          raise Runtime::WiringError,
+                "cannot write the translation of #{domain.domain_name}: the audit refused the composed " \
+                "edge —\n  #{finding.refusals.join("\n  ")}"
+        end
+
+        def written_report(plan)
+          removed = plan.removals.map { |path| "  removed #{File.basename(path)}" }
+          ["wrote #{plan.path}", *removed, "the audit passed: #{plan.labels.join(" -> ")}"].join("\n")
+        end
+      end
+    end
+  end
+end

data/lib/hecks/hecks/adapters/journal_store.rb

@@ -3,6 +3,9 @@
 require_relative "journal_store/examination"
 require_relative "journal_store/changes"
 require_relative "journal_store/readings"
+require_relative "journal_store/translation_write"
+require_relative "journal_store/reconciliation"
+require_relative "journal_store/held_mint"
 
 module Hecks
   module Adapters
@@ -19,6 +22,8 @@ module Hecks
       include Examination
       include Changes
       include Readings
+      include TranslationWrite
+      include Reconciliation
 
       # Accepts the arguments every driven adapter is built with and keeps none of them.
       #
@@ -27,6 +32,17 @@ module Hecks
       # @param root [String, nil] unused
       def initialize(aggregate: nil, settings: {}, root: nil); end
 
+      # Answers the held mint of the Hecks domain: see `HeldMint#answer`.
+      #
+      # @param held [Hash] the `MintHeld` record: `run`, and optionally `rehearsal_verdict`,
+      #   `watermark` and `confirm`
+      # @return [Hash{Symbol => Hash}] `run`, `outcome` and `label`
+      # @raise [Runtime::WiringError] naming why the mint was refused
+      def mint(**held)
+        HeldMint.new.answer(run: plain(held[:run]), confirm: plain(held[:confirm]),
+                            rehearsal_verdict: plain(held[:rehearsal_verdict]), watermark: plain(held[:watermark]))
+      end
+
       private
 
       def plain(argument) = argument.is_a?(Hash) ? argument[:value] : argument

data/lib/hecks/hecks/adapters/landed_work.adapter

@@ -0,0 +1,7 @@
+# Required by name, not relative to this file: a fuzz or model check boots a copy of this directory,
+# and the implementation must load once, from `lib/`, not from the copy.
+require "hecks/hecks/adapters/landed_work"
+
+Hecks.adapter "LandedWork" do
+  port "LandedWork"
+end

data/lib/hecks/hecks/adapters/landed_work.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+require_relative "started_work"
+require_relative "console_capture"
+
+module Hecks
+  module Adapters
+    # The `LandedWork` port's adapter for `Tickets::Work`: finds the open step a landed branch was
+    # cut for, so the bluebook can finish it.
+    #
+    # A branch names its step by the whole branch name, else by the name without a leading `qa/`
+    # (QA's branches carry that prefix, the steps they close do not). Only a `planned` or `started`
+    # step is found; a branch with no step, or one already done or dropped, is refused by name and
+    # the bluebook reacts to neither. It writes nothing.
+    class LandedWork
+      # The prefix QA puts on a branch whose step carries the bare name.
+      QA_PREFIX = "qa/"
+
+      # @param registry [Runtime::Registry, nil] the booted registry whose Work rows are read
+      # @param aggregate [Object, nil] unused
+      def initialize(registry: nil, aggregate: nil)
+        @registry = registry
+      end
+
+      # @param held [Hash] the landing's `branch`
+      # @return [Hash{Symbol => Hash}] `branch:` the key of the open step the branch names
+      # @raise [ConsoleCapture::Failure] when no open step is named by the branch
+      def find_landed_work(**held)
+        branch = plain(held[:branch]).to_s
+        found = (candidates(branch) & open_keys).first
+        raise ConsoleCapture::Failure, "no open step is named #{branch}" unless found
+
+        { branch: { value: found } }
+      end
+
+      private
+
+      def candidates(branch) = [branch, branch.delete_prefix(QA_PREFIX)].reject(&:empty?).uniq
+
+      def open_keys
+        aggregate = StartedWork.work_aggregate(@registry)
+        return [] unless aggregate
+
+        records = @registry.repository("Tickets", aggregate).all
+        records.select { |row| %w[planned started].include?(StartedWork.value(row, :status)) }
+               .map { |row| StartedWork.value(row, :work).to_s }
+      end
+
+      def plain(argument) = argument.is_a?(Hash) ? argument[:value] : argument
+    end
+  end
+end