hecks 2.9.0 → 3.0.1

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

@@ -0,0 +1,135 @@
+# frozen_string_literal: true
+
+require "digest"
+require "json"
+require_relative "held_domain"
+require_relative "edge_audit"
+require_relative "compaction"
+
+module Hecks
+  module Adapters
+    class JournalStore
+      # The facts the journal store reports about a change before it is made, for the rules of
+      # Custodian's `Era.Permit` to hold against. Nothing here writes: an examination reads the
+      # domain and its journal and answers numbers and yes-or-no.
+      module Examination
+        # What every fact is until an examination finds otherwise.
+        NEUTRAL = {
+          capable: false, held: 0, forks: 0, contested: 0, edges: 0, bound: 0, candidates: 0,
+          audited: false, rehearsal_needed: false, rehearsal_recorded: false,
+          drifted: false, loadable: false, shape_kept: false
+        }.freeze
+
+        # Examines the domain a change was asked for.
+        #
+        # @param held [Hash] the `Era` record: `operation`, `domain`, and whichever of `winners`,
+        #   `era`, `aggregates` and the rehearsal fields the request carried
+        # @return [Hash{Symbol => Hash}] every fact, as `{ value: x }`, and the request's own
+        #   `operation`, which the reactions to the examination read
+        # @raise [Runtime::NotFound] if the domain cannot be loaded or has no such era
+        def examine(**held)
+          found = send(:"examine_#{plain(held[:operation])}", held)
+          NEUTRAL.merge(found).transform_values { |fact| { value: fact } }
+                 .merge(operation: { value: plain(held[:operation]) })
+        end
+
+        private
+
+        def examine_hold_first(held)
+          domain = HeldDomain.open(plain(held[:domain]), mode: :bare)
+          return {} unless domain.capable?
+
+          { capable: true, held: domain.reading { |lineage| domain.held_eras(lineage).size } }
+        end
+
+        def examine_merge_tail(held)
+          domain = HeldDomain.open(plain(held[:domain]))
+          return {} unless domain.capable?
+
+          domain.reading do |lineage|
+            eras = domain.held_eras(lineage)
+            forks = forks_in(domain, eras)
+            unresolved = eras.size > 1 && forks.zero? ? unresolved_conflicts(domain, lineage, eras, winners(held)) : 0
+            { capable: true, held: eras.size, forks: forks, contested: unresolved }
+          end
+        end
+
+        def examine_reattest(held)
+          domain = HeldDomain.open(plain(held[:domain]), mode: :bare)
+          return {} unless domain.capable?
+
+          ordinal = plain(held[:era])
+          era = domain.reading { |lineage| raw_era(domain, lineage, ordinal) }
+          { capable: true }.merge(text_facts(era))
+        end
+
+        # Whether the held text drifted from its digest and, if so, whether it still loads and
+        # still projects to the shape the era froze with. A text that matches its digest has
+        # nothing to attest, so its shape is not examined.
+        def text_facts(era)
+          return {} if era[:held_digest] == Digest::SHA256.hexdigest(era[:held_text])
+
+          found = Translation::Reattest.verdict(
+            text: era[:held_text], stored_hash: era[:hash],
+            stored_projection: era[:held_projection] && JSON.parse(era[:held_projection])
+          )
+          { drifted: true, loadable: found != :unloadable, shape_kept: %i[cosmetic unnamed].include?(found) }
+        end
+
+        def examine_backfill_projections(held)
+          domain = HeldDomain.open(plain(held[:domain]), mode: :bare)
+          { capable: domain.capable? }
+        end
+
+        def examine_compact(held) = examine_compaction(held, :entries)
+
+        def examine_compact_heki(held) = examine_compaction(held, :heki)
+
+        def examine_compaction(held, kind)
+          compaction = Compaction.new(plain(held[:domain]), aggregates: names(held[:aggregates]), kind: kind)
+          { candidates: compaction.candidates.size, bound: compaction.bound.size }
+        end
+
+        def examine_approve_translation(held)
+          domain = HeldDomain.open(plain(held[:domain]))
+          return {} unless domain.capable?
+
+          domain.reading do |lineage|
+            eras = domain.held_eras(lineage)
+            finding = eras.empty? ? nil : EdgeAudit.call(domain, lineage, eras)
+            next { capable: true, held: eras.size } unless finding
+
+            { capable: true, held: eras.size, edges: finding.leaving, audited: finding.ok }.merge(rehearsal_facts(finding, held))
+          end
+        end
+
+        def rehearsal_facts(finding, held)
+          {
+            rehearsal_needed:   Translation::ApprovalFile.needs_rehearsal?(finding.edge),
+            rehearsal_recorded: Translation::ApprovalFile.rehearsed?(rehearsal_block(held))
+          }
+        end
+
+        # How many eras, before the latest, do not have exactly one edge leading to the next.
+        def forks_in(domain, eras)
+          eras.each_cons(2).count do |from, to|
+            leaving = domain.registry.translations.select do |edge|
+              edge.domain == domain.bluebook.name && edge.from == from[:label]
+            end
+            leaving.size != 1 || leaving.first.to != to[:label]
+          end
+        end
+
+        # Records both worlds wrote since the cut that no winner was named for.
+        def unresolved_conflicts(domain, lineage, eras, named)
+          latest = eras.last
+          chain = PostgresEra::LineageManager.edge_chain(domain.registry, domain.bluebook, eras[0..-2], latest[:label])
+          conflicts = domain.bluebook.aggregates.flat_map do |aggregate|
+            lineage.conflict_ids(aggregate, chain, latest[:ordinal], latest[:watermark].to_i)
+          end
+          conflicts.count { |_, id| !named.key?(id) }
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,163 @@
+# frozen_string_literal: true
+
+require "hecks"
+require "hecks/ports/persistence/plugins/era"
+
+module Hecks
+  module Adapters
+    class JournalStore
+      # A domain directory loaded the way the era tools load it, with the journal store its first
+      # aggregate is bound to.
+      #
+      # `translated` loads the whole domain, translation edges included; `bare` loads the
+      # bluebooks, hecksagons and worlds only, so an edge that does not resolve cannot stop a
+      # text from being attested; `scaffold` loads everything but the edges, since an unresolved
+      # edge file refuses to load and writing it is the point.
+      class HeldDomain
+        MODES = %i[translated bare scaffold].freeze
+
+        attr_reader :registry, :bluebook, :directory, :adapter_name
+
+        # Loads a domain and finds where its eras would be held.
+        #
+        # @param path [String] the domain directory, or the project holding its `bluebook/`
+        # @param mode [Symbol] one of `MODES`
+        # @return [HeldDomain] the loaded domain
+        # @raise [Runtime::NotFound] if the directory does not exist, declares no bluebook, or
+        #   does not load
+        def self.open(path, mode: :translated)
+          raise ArgumentError, "unknown mode #{mode.inspect}" unless MODES.include?(mode)
+
+          loading = Ports::Loading.bootstrap
+          directory = loading.bluebook_directory(path)
+          registry = Runtime::Registry.new(root: File.dirname(directory))
+          load_into(registry, loading, directory, mode)
+          new(registry, directory)
+        rescue Errno::ENOENT
+          raise Runtime::NotFound, "no such domain #{path.inspect}"
+        rescue Bluebook::DSL::Malformed => e
+          raise Runtime::NotFound, "REFUSED at load: #{e.message}"
+        end
+
+        # @api private
+        def self.load_into(registry, loading, directory, mode)
+          environment = ENV.fetch("HECKS_PROJECT_ENVIRONMENT", nil)
+          Hecks.with_registry(registry) do
+            loading.load_library
+            loading.load_project(loading.shared_root(nil, directory))
+            case mode
+            when :translated then loading.load_domain(directory, environment: environment)
+            when :bare then loading.load_each(directory, %w[*.port *.adapter *.bluebook *.hecksagon *.world])
+            else load_scaffold(loading, directory, environment)
+            end
+          end
+        end
+
+        # @api private
+        def self.load_scaffold(loading, directory, environment)
+          loading.load_each(directory, %w[*.port *.adapter])
+          loading.load_bluebooks(directory)
+          loading.load_each(directory, %w[*.hecksagon *.world])
+          return unless environment
+
+          loading.load_each(directory, [File.join("environments", "#{environment}.hecksagon")])
+          loading.load_each(directory, [File.join("environments", "#{environment}.world")])
+        end
+
+        # @param registry [Runtime::Registry] the loaded registry
+        # @param directory [String] the domain's bluebook directory
+        # @raise [Runtime::NotFound] if the registry holds no bluebook, or a bluebook no aggregate
+        def initialize(registry, directory)
+          @registry = registry
+          @directory = directory
+          @bluebook = registry.bluebooks.values.first or raise Runtime::NotFound, "no bluebook in #{directory}"
+          first = @bluebook.aggregates.first or raise Runtime::NotFound, "#{@bluebook.name} declares no aggregates"
+          @adapter_name = Ports::Persistence::BindingPolicy.resolve(registry, @bluebook.name, first).adapter
+        end
+
+        # Whether the store the domain is bound to keeps eras (`EraCheck`'s own question).
+        #
+        # @return [Boolean] true when the adapter is lineage capable
+        def capable? = Runtime::EraCheck.lineage_capable?(registry, adapter_name)
+
+        # Explains, as a refusal, why a domain has no eras.
+        #
+        # @return [String] the sentence
+        def incapable_reason = "#{bluebook.name} is bound to #{adapter_name}, which holds no eras"
+
+        # The settings its journal store is connected with: the world's, and `HECKS_SCHEMA` for a
+        # domain on a shared database, whose schema production takes from the environment.
+        #
+        # @return [Hash] the settings
+        def settings
+          declared = registry.binding_settings(bluebook.name, Ports::Persistence::VERB, adapter_name)
+          ENV["HECKS_SCHEMA"] ? declared.merge(schema: ENV["HECKS_SCHEMA"]) : declared
+        end
+
+        # The text the era is frozen from: the bluebook source as it stands on disk.
+        #
+        # @return [String] the text
+        # @raise [Runtime::NotFound] if no file declares the bluebook
+        def source_text
+          Runtime::EraCheck.source_text_for(bluebook, directory) or
+            raise Runtime::NotFound, "no file under #{directory} declares #{bluebook.name}"
+        end
+
+        # An era with the name it would be minted under, worked out in memory when none was stored.
+        # Naming an era is a write, so a read never does it.
+        #
+        # @param era [Hash] an era as `Lineage#eras` answers it
+        # @return [Hash] the era, with `hash` and `label` filled in
+        def named(era)
+          return era if era[:hash]
+
+          hash = Runtime::StorageShape.mint_hash(PostgresEra::LineageManager.shadow(era[:held_text]))
+          era.merge(hash: hash, label: hash[0, Runtime::StorageShape::LABEL_LENGTH])
+        end
+
+        # The bluebook's storage shape as it stands.
+        #
+        # @return [Hash] the projection `StorageShape.project` answers
+        def shape = Runtime::StorageShape.project(bluebook)
+
+        # Connects to the journal store and yields a lineage over it. Nothing is provisioned, so a
+        # database that holds no eras is left as it is.
+        #
+        # @yield [Lineage] the domain's lineage
+        # @return [Object] the block's value
+        def reading
+          db = PostgresEra.connect_for(bluebook.name, settings)
+          yield PostgresEra::Lineage.new(db, bluebook.name)
+        ensure
+          db&.close
+        end
+
+        # Connects to the journal store, refuses a role that bypasses the write fence unless the
+        # world allows it, provisions the lineage tables, and yields a lineage over it.
+        #
+        # @yield [Lineage] the domain's lineage
+        # @return [Object] the block's value
+        # @raise [Runtime::WiringError] on a superuser connection the world has not allowed
+        def writing
+          db = PostgresEra.connect_for(bluebook.name, settings)
+          lineage = PostgresEra::Lineage.new(db, bluebook.name, formerly_known_as: bluebook.formerly_known_as)
+          lineage.check_fence_applies!(allow_superuser: PostgresEra.setting(settings, :allow_superuser, default: false))
+          lineage.ensure_base!
+          yield lineage
+        ensure
+          db&.close
+        end
+
+        # The eras a lineage holds, without provisioning anything: none when the lineage tables do
+        # not exist yet.
+        #
+        # @param lineage [Lineage] the domain's lineage
+        # @return [Array<Hash>] `Lineage#eras`, verified against their digests; empty when none held
+        def held_eras(lineage)
+          present = lineage.db.exec("SELECT to_regclass('hecks_eras') AS present")[0]["present"]
+          present ? lineage.eras : []
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,187 @@
+# frozen_string_literal: true
+
+require "json"
+require "digest"
+require_relative "held_domain"
+require_relative "edge_audit"
+require_relative "compaction"
+
+module Hecks
+  module Adapters
+    class JournalStore
+      # The queries the journal store answers: what would be scaffolded, how the audit reads, an
+      # era's held text, and what compacting would delete.
+      #
+      # A reading never writes. It provisions nothing, holds no era, names none and writes no file;
+      # a domain that holds no era answers that it holds none, and only `hold_first` holds one.
+      # What a reading refuses is a `Runtime::NotFound`, the refusal a launcher words as an answer.
+      module Readings
+        # Words the answer for a domain that holds no era.
+        #
+        # @param name [String] the domain's name
+        # @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."
+        end
+
+        # The edge file that would lead the latest held era to the current shape, as its text.
+        #
+        # @param domain [Hash, String] the domain directory
+        # @return [Hash] `text:` the `.bluebook` text, under comments saying where to save it and
+        #   what is left to decide
+        # @raise [Runtime::NotFound] if the domain holds no eras, or cannot be loaded
+        def scaffold_translation(domain:)
+          answering do
+            held = HeldDomain.open(plain(domain), mode: :scaffold)
+            refuse_incapable!(held)
+            held.reading { |lineage| scaffold(held, lineage, plain(domain)) }
+          end
+        end
+
+        # The audit of the edge that leads the latest held era to the current shape.
+        #
+        # @param domain [Hash, String] the domain directory
+        # @return [Hash] `text:` the report, ending in what approving needs
+        # @raise [Runtime::NotFound] if the audit refuses, or no edge leads to the current shape
+        def audit_translation(domain:)
+          answering do
+            held = HeldDomain.open(plain(domain))
+            refuse_incapable!(held)
+            held.reading { |lineage| audit(held, lineage, plain(domain)) }
+          end
+        end
+
+        # An era's held text as it now stands, and whether it still matches its digest.
+        #
+        # @param domain [Hash, String] the domain directory
+        # @param era [Hash, Integer] the era's ordinal
+        # @return [Hash] `text:` the digests and the text a person reads before attesting to it
+        # @raise [Runtime::NotFound] if the domain holds no such era
+        def attestation(domain:, era:)
+          answering do
+            held = HeldDomain.open(plain(domain), mode: :bare)
+            refuse_incapable!(held)
+            held.reading { |lineage| attest(held, lineage, plain(era)) }
+          end
+        end
+
+        # What compacting the domain's journals would delete, without deleting anything.
+        #
+        # @param domain [Hash, String] the domain directory
+        # @param aggregates [Hash, String, nil] aggregate names, comma separated
+        # @return [Hash] `text:` one line per journal
+        # @raise [Runtime::NotFound] if the domain cannot be loaded
+        def compaction(domain:, aggregates: nil)
+          answering do
+            lines = %i[entries heki].flat_map do |kind|
+              Compaction.new(plain(domain), aggregates: names(aggregates), kind: kind).preview
+            end
+            lines.empty? ? "no journal of #{plain(domain)} can be compacted" : lines.join("\n")
+          end
+        end
+
+        private
+
+        # Words a lower layer's refusal as the one a query is refused with. `pg` is loaded lazily,
+        # so its error is only named once something has connected.
+        def answering
+          { text: yield }
+        rescue *lower_refusals => e
+          raise Runtime::NotFound, e.message.strip
+        end
+
+        def lower_refusals
+          [Runtime::WiringError, Bluebook::DSL::Malformed, ArgumentError, *(PG::Error if defined?(PG))]
+        end
+
+        def refuse_incapable!(held)
+          raise Runtime::NotFound, held.incapable_reason unless held.capable?
+        end
+
+        def scaffold(held, lineage, path)
+          eras = held.held_eras(lineage)
+          return Readings.no_era(held.bluebook.name, path) if eras.empty?
+
+          latest = held.named(eras.last)
+          shadow = PostgresEra::LineageManager.shadow(latest[:held_text])
+          if Runtime::StorageShape.project(shadow) == held.shape
+            return "#{held.bluebook.name} matches era #{latest[:ordinal]} — nothing to scaffold."
+          end
+
+          edge_text(held, latest, Translation::Scaffold.diff(shadow, held.bluebook))
+        end
+
+        def edge_text(held, latest, diffed)
+          label = Runtime::StorageShape.mint_hash(held.bluebook)[0, Runtime::StorageShape::LABEL_LENGTH]
+          edge = Translation::Scaffold::Edge.new(
+            domain: held.bluebook.name, from: latest[:label], to: label, ordinal: latest[:ordinal] + 1,
+            label: label, aggregates: diffed[:aggregates], retired: diffed[:retired]
+          )
+          text = Translation::Scaffold.render(edge)
+          [*scaffold_notes(edge, text, diffed[:unclaimed]), text].join("\n")
+        end
+
+        def scaffold_notes(edge, text, unclaimed)
+          unresolved = text.scan(/^\s*unresolved /).size
+          notes = ["# Save as translations/#{edge.ordinal}-#{edge.label}.bluebook."]
+          notes << "# #{unresolved} unresolved: decide what each became, then boot." if unresolved.positive?
+          unclaimed.each do |name|
+            notes << "# UNCLAIMED: #{name} existed and now doesn't, and its successor is ambiguous — add " \
+                     "`aggregate \"NewName\", was: #{name.inspect}` (with its rules) or `retired #{name.inspect}`."
+          end
+          notes << "# 0 unresolved: this shape change costs one extra boot and no typing." if notes.size == 1
+          notes
+        end
+
+        def audit(held, lineage, path)
+          eras = held.held_eras(lineage)
+          return Readings.no_era(held.bluebook.name, path) if eras.empty?
+
+          finding = EdgeAudit.call(held, lineage, eras)
+          return "#{held.bluebook.name} stands at era 1 — no edge to audit." unless finding
+          raise Runtime::NotFound, "#{finding.report}\nAUDIT REFUSED." unless finding.ok
+
+          [finding.report, audit_verdict(finding.edge, path)].join("\n")
+        end
+
+        def audit_verdict(edge, path)
+          if Translation::ApprovalFile.needs_rehearsal?(edge)
+            "AUDIT PASSED — this edge carries a compute or rekey rule, and the samples above are its ONLY " \
+              "verification. If they show what you intended, rehearse it against a snapshot and run " \
+              "`hecks approve_translation #{path} --confirm` with the rehearsal; the mint refuses until then."
+          else
+            "AUDIT PASSED — review the samples above; intent is yours to approve."
+          end
+        end
+
+        def attest(held, lineage, ordinal)
+          era = raw_era(held, lineage, ordinal)
+          computed = Digest::SHA256.hexdigest(era[:held_text])
+          name = "#{held.bluebook.name} era #{ordinal}"
+          return "#{name}: the held text matches its digest — nothing to re-attest." if era[:held_digest] == computed
+
+          [
+            "#{name}: the held text does NOT match its recorded digest.",
+            "  recorded: #{era[:held_digest] || '(none)'}", "  computed: #{computed}", shape_line(held, era, ordinal),
+            "The held text AS IT NOW STANDS — the original is gone; this is what you would be attesting to:",
+            "─" * 72, era[:held_text], "─" * 72,
+            "Read it, then `hecks reattest #{held.bluebook.name} era=#{ordinal} --confirm` accepts it."
+          ].join("\n")
+        end
+
+        def shape_line(held, era, ordinal)
+          verdict = Translation::Reattest.shape_guard!(
+            domain: held.bluebook.name, ordinal: ordinal, text: era[:held_text], stored_hash: era[:hash],
+            stored_projection: era[:held_projection] && JSON.parse(era[:held_projection])
+          )
+          if verdict == :cosmetic
+            "  shape:    unchanged — the edit is cosmetic (the text still projects to era #{ordinal}'s minted name)"
+          else
+            "  shape:    era #{ordinal} was never named, so no shape comparison is possible — read carefully"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/hecks/hecks/adapters/journal_store.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/journal_store"
+
+Hecks.adapter "JournalStore" do
+  port "JournalStore"
+end

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

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+require_relative "journal_store/examination"
+require_relative "journal_store/changes"
+require_relative "journal_store/readings"
+
+module Hecks
+  module Adapters
+    # The `JournalStore` port's adapter: reaches the era plugin and the persistence adapters on an
+    # operator's behalf, to examine a domain's journal, change it, or read how it stands.
+    #
+    # `examine` reports the facts Custodian's `Era.Permit` holds against the request, `apply` makes
+    # an admitted change, and the queries (`scaffold_translation`, `audit_translation`,
+    # `attestation`, `compaction`) answer without writing. Every method reuses the era plugin's
+    # own logic (`LineageManager`, `Lineage`, `Translation::*`); only the entry point moved.
+    #
+    # Arguments arrive materialized, so a value object is `{ value: x }`.
+    class JournalStore
+      include Examination
+      include Changes
+      include Readings
+
+      # Accepts the arguments every driven adapter is built with and keeps none of them.
+      #
+      # @param aggregate [Object, nil] unused
+      # @param settings [Hash] unused
+      # @param root [String, nil] unused
+      def initialize(aggregate: nil, settings: {}, root: nil); end
+
+      private
+
+      def plain(argument) = argument.is_a?(Hash) ? argument[:value] : argument
+
+      # Aggregate names, from the comma-separated list a request carries.
+      def names(list) = plain(list).to_s.split(",").map(&:strip).reject(&:empty?)
+
+      # `id:old,id:new` as the map the tail merge takes; the side is what follows the last colon.
+      def winners(held)
+        plain(held[:winners]).to_s.split(",").to_h do |pair|
+          id, _, side = pair.rpartition(":")
+          [id, side]
+        end
+      end
+
+      # The rehearsal a compute or rekey edge is approved on, as the block the file carries. A
+      # rehearsal that names no host version ran on this one, so it records this release.
+      def rehearsal_block(held)
+        block = { "snapshot" => plain(held[:snapshot]), "host_version" => plain(held[:host_version]),
+                  "result" => plain(held[:rehearsal]), "at" => plain(held[:rehearsed_at]) }.compact
+        return nil if block.empty?
+
+        block["host_version"] ||= Hecks::VERSION
+        block
+      end
+
+      # The era as stored, digest unchecked: a text that drifted is what re-attesting is for.
+      def raw_era(domain, lineage, ordinal)
+        present = lineage.db.exec("SELECT to_regclass('hecks_eras') AS present")[0]["present"]
+        (present && lineage.raw_era(ordinal)) or
+          raise Runtime::NotFound, "#{domain.bluebook.name} holds no era #{ordinal}"
+      end
+    end
+  end
+end

data/lib/hecks/hecks/adapters/local_files.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/local_files"
+
+Hecks.adapter "LocalFiles" do
+  port "Workspace"
+end

data/lib/hecks/hecks/adapters/local_files.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+require_relative "console_capture"
+require "hecks/cli/project_cli"
+
+module Hecks
+  module Adapters
+    # The `Workspace` port's adapter: writes files into the project the operator is standing in.
+    #
+    # Custodian commands whose whole effect is files on disk ask it, so the journal records that a
+    # write was requested and what came of it, and the writing happens here and nowhere else.
+    class LocalFiles
+      # Accepts the arguments every driven adapter is built with and keeps none of them.
+      #
+      # @param aggregate [Object, nil] unused
+      # @param settings [Hash] unused
+      # @param root [String, nil] unused
+      def initialize(aggregate: nil, settings: {}, root: nil); end
+
+      # Writes a command-line launcher beside each domain of the current directory, or beside the
+      # named ones, through `Hecks::CLI::ProjectCli`. A launcher is a generated file that only
+      # points at its domain, so an existing one is replaced and nothing else is touched.
+      #
+      # @param held [Hash] the `Door` record: `domains` (comma separated paths under the current
+      #   directory; every domain found when absent)
+      # @return [Hash{Symbol => Hash}] `output:` one line per launcher written
+      # @raise [ConsoleCapture::Failure] when no launcher was written
+      def write(**held)
+        domains = plain(held[:domains]).to_s.split(",").map(&:strip).reject(&:empty?)
+        text = ConsoleCapture.answer do
+          CLI::ProjectCli.call(domains, program: "hecks project_cli", root: Dir.pwd, remove_stale_bin: false)
+        end
+        unless text.include?("->")
+          reason = text.strip.empty? ? "no domain found" : text.strip
+          raise ConsoleCapture::Failure, "no launcher written: #{reason}"
+        end
+
+        { output: { value: text } }
+      end
+
+      private
+
+      def plain(argument) = argument.is_a?(Hash) ? argument[:value] : argument
+    end
+  end
+end

data/lib/hecks/hecks/adapters/pg_admin.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/pg_admin"
+
+Hecks.adapter "PgAdmin" do
+  port "PgAdmin"
+end