hecks 2.9.0 → 3.0.0

data/lib/hecks/quality_control/cli/qa_postgres_role.rb

@@ -0,0 +1,159 @@
+# frozen_string_literal: true
+
+require "pg"
+
+module Hecks
+  module QualityControlCli
+    # The command behind `hecks quality_control create_ledger_role`: creates the ordinary Postgres
+    # role the QA ledger connects as and makes it own the database. It is idempotent, and refuses a
+    # superuser or `BYPASSRLS` role, which the era write-fence cannot bind.
+    #
+    #   hecks quality_control create_ledger_role <database> [--role <role>]   # role defaults to
+    # hecks_qa
+    class QaPostgresRole
+      USAGE = "usage: hecks quality_control create_ledger_role <database> [--role <role>]"
+
+      # `relkind` of each relation to the word `ALTER` takes for it. Partitions are their own
+      # rows; `ALTER TABLE ... OWNER` on the parent does not recurse.
+      KINDS = { "r" => "TABLE", "p" => "TABLE", "S" => "SEQUENCE", "v" => "VIEW", "m" => "MATERIALIZED VIEW" }.freeze
+
+      # Creates the role and hands it the database.
+      #
+      # @param argv [Array<String>] the database, and optionally `--role NAME`
+      # @param out [IO] where the report goes
+      # @param err [IO] where a usage error goes
+      # @return [Integer] 0 once the database is the role's, 1 for a usage error
+      # @raise [SystemExit] when the role is a superuser or `BYPASSRLS`, or the database is missing
+      def self.call(argv, out: $stdout, err: $stderr)
+        new(out: out, err: err).call(argv)
+      end
+
+      # @param out [IO] where the report goes
+      # @param err [IO] where a usage error goes
+      def initialize(out: $stdout, err: $stderr)
+        @out = out
+        @err = err
+      end
+
+      # @param argv [Array<String>] the database, and optionally `--role NAME`
+      # @return [Integer] the exit status
+      # @raise [SystemExit] when the role is a superuser or `BYPASSRLS`, or the database is missing
+      def call(argv)
+        argv = argv.dup
+        role = "hecks_qa"
+        if (index = argv.index("--role"))
+          role = argv[index + 1] or return usage("--role needs a name")
+          argv.slice!(index, 2)
+        end
+        database = argv.shift
+        return usage("no database named") if database.to_s.empty?
+        return usage("unexpected argument #{argv.first.inspect}") unless argv.empty?
+
+        done = []
+        skipped = []
+        admin = PG.connect(dbname: "postgres")
+        create_role(admin, role, done, skipped)
+        take_database(admin, database, role, done, skipped)
+        admin.close
+        take_contents(database, role, done)
+        report(database, role, done, skipped)
+        0
+      end
+
+      private
+
+      def usage(message)
+        @err.puts "hecks quality_control create_ledger_role: #{message}"
+        @err.puts USAGE
+        1
+      end
+
+      def create_role(admin, role, done, skipped)
+        attrs = admin.exec_params("SELECT rolsuper, rolbypassrls FROM pg_roles WHERE rolname = $1", [role])
+        if attrs.ntuples.zero?
+          # CREATE ROLE has no IF NOT EXISTS. Concurrent creates can lose on the catalog index
+          # (unique_violation) rather than duplicate_object, so the block rescues both.
+          admin.exec(<<~SQL)
+            DO $$ BEGIN
+              CREATE ROLE #{admin.quote_ident(role)} LOGIN NOSUPERUSER NOBYPASSRLS NOCREATEDB NOCREATEROLE;
+            EXCEPTION WHEN duplicate_object OR unique_violation THEN NULL;
+            END $$
+          SQL
+          done << "created role #{role} (LOGIN, no SUPERUSER, no BYPASSRLS)"
+        elsif attrs[0]["rolsuper"] == "t" || attrs[0]["rolbypassrls"] == "t"
+          admin.close
+          abort "hecks quality_control create_ledger_role: role #{role} already exists as " \
+                "#{attrs[0]['rolsuper'] == 't' ? 'a superuser' : 'a BYPASSRLS role'} — the era write-fence " \
+                "cannot bite it, which is the exact state this script exists to end. Pick another role, or " \
+                "ALTER ROLE #{role} NOSUPERUSER NOBYPASSRLS first."
+        else
+          skipped << "role #{role} exists, ordinary"
+        end
+      end
+
+      def take_database(admin, database, role, done, skipped)
+        owner = admin.exec_params(
+          "SELECT pg_get_userbyid(datdba) AS owner FROM pg_database WHERE datname = $1", [database]
+        )
+        if owner.ntuples.zero?
+          admin.close
+          abort "hecks quality_control create_ledger_role: no database #{database} — createdb it first (PostgresEra provisions " \
+                "every table it needs on first connect, never the database itself)"
+        end
+        if owner[0]["owner"] == role
+          skipped << "database #{database} already owned by #{role}"
+        else
+          admin.exec("ALTER DATABASE #{admin.quote_ident(database)} OWNER TO #{admin.quote_ident(role)}")
+          done << "database #{database}: owner #{owner[0]['owner']} -> #{role}"
+        end
+      end
+
+      def take_contents(database, role, done)
+        db = PG.connect(dbname: database)
+        quoted_role = db.quote_ident(role)
+        schema_owner = db.exec("SELECT pg_get_userbyid(nspowner) AS owner FROM pg_namespace WHERE nspname = 'public'")
+        if schema_owner.ntuples.positive? && schema_owner[0]["owner"] != role
+          db.exec("ALTER SCHEMA public OWNER TO #{quoted_role}")
+          done << "schema public: owner #{schema_owner[0]['owner']} -> #{role}"
+        end
+        take_relations(db, role, quoted_role, done)
+        take_functions(db, role, quoted_role, done)
+        db.close
+      end
+
+      # relkind: r table, p partitioned table, S sequence, v view, m matview.
+      def take_relations(db, role, quoted_role, done)
+        relations = db.exec_params(<<~SQL, [role])
+          SELECT c.relname, c.relkind, pg_get_userbyid(c.relowner) AS owner
+          FROM pg_class c JOIN pg_namespace n ON n.oid = c.relnamespace
+          WHERE n.nspname = 'public' AND c.relkind IN ('r', 'p', 'S', 'v', 'm') AND pg_get_userbyid(c.relowner) <> $1
+          ORDER BY c.relkind, c.relname
+        SQL
+        relations.each do |row|
+          db.exec("ALTER #{KINDS.fetch(row['relkind'])} #{db.quote_ident(row['relname'])} OWNER TO #{quoted_role}")
+        end
+        done << "#{relations.ntuples} relation(s) in public -> #{role}" if relations.ntuples.positive?
+      end
+
+      def take_functions(db, role, quoted_role, done)
+        functions = db.exec_params(<<~SQL, [role])
+          SELECT p.proname, pg_get_function_identity_arguments(p.oid) AS args
+          FROM pg_proc p JOIN pg_namespace n ON n.oid = p.pronamespace
+          WHERE n.nspname = 'public' AND pg_get_userbyid(p.proowner) <> $1
+          ORDER BY p.proname
+        SQL
+        functions.each do |row|
+          db.exec("ALTER FUNCTION #{db.quote_ident(row['proname'])}(#{row['args']}) OWNER TO #{quoted_role}")
+        end
+        done << "#{functions.ntuples} function(s) in public -> #{role}" if functions.ntuples.positive?
+      end
+
+      def report(database, role, done, skipped)
+        @out.puts "hecks quality_control create_ledger_role: #{database} is #{role}'s"
+        done.each { |line| @out.puts "  did:     #{line}" }
+        skipped.each { |line| @out.puts "  already: #{line}" }
+        @out.puts "  bind it: database \"postgres://#{role}@localhost/#{database}\"" if done.any?
+      end
+    end
+  end
+end

data/lib/hecks/quality_control/cli/qa_pr_check.rb

@@ -0,0 +1,232 @@
+# frozen_string_literal: true
+
+require_relative "../../../hecks"
+# The ledger's `persisted_by "PostgresEra"` binding needs the era plugin, which core does not load.
+require_relative "../../ports/persistence/plugins/era"
+require_relative "../adapters/git_pr"
+
+module Hecks
+  module QualityControlCli
+    # The command behind `hecks quality_control check_pull_requests`: checks CI for every PR the
+    # QualityControl ledger tracks as open (`Patch` and `Improvement`). It starts a `Clearance` per
+    # unsettled head commit and lets the CI port's policies record the verdict.
+    #
+    # Exit codes: 0 nothing to act on; 1 operational error (`gh`, bad sha, ledger boot);
+    # 2 a newly red PR, with the details on stdout. A commit's `Clearance` is minted once and never
+    # re-asked; pending checks are skipped, since the CI port has no way to say "ask again later".
+    class QaPrCheck
+      EXIT_OK = 0
+      EXIT_ERROR = 1
+      EXIT_NEWLY_RED = 2
+
+      USAGE = "usage: hecks quality_control check_pull_requests"
+
+      SHA_PATTERN = /\A[0-9a-fA-F]{7,40}\z/
+
+      # Two worklists, checked the same way. The citation is what a row references: a `Bug` for a
+      # `Patch`, an optional `Angle` for an `Improvement`.
+      WORKLISTS = [
+        { aggregate: "Patch", citation_field: :bug, citation_label: "bug" },
+        { aggregate: "Improvement", citation_field: :angle, citation_label: "angle" }
+      ].freeze
+
+      # Checks every tracked PR.
+      #
+      # @param argv [Array<String>] no arguments; `--help` prints the usage
+      # @param root [String] the repository root, where the ledger's boot directory is found
+      # @param env [Hash{String => String}] `QA_SWEEP_DOMAIN_DIR` points at another ledger
+      # @return [Integer] 0 clean, 1 on an operational error, 2 for a newly red PR
+      # @raise [SystemExit] when given arguments, or the ledger does not boot
+      def self.call(argv, root:, env: ENV)
+        new(root: root, env: env).call(argv)
+      end
+
+      # @param root [String] the repository root
+      # @param env [Hash{String => String}] `QA_SWEEP_DOMAIN_DIR` points at another ledger
+      def initialize(root:, env: ENV)
+        @domain_dir = env.fetch("QA_SWEEP_DOMAIN_DIR", File.join(root, "qa/bluebook"))
+      end
+
+      # @param argv [Array<String>] no arguments; `--help` prints the usage
+      # @return [Integer] the exit status
+      # @raise [SystemExit] when given arguments, or the ledger does not boot
+      def call(argv)
+        unless argv.empty?
+          if %w[-h --help].include?(argv.first)
+            puts USAGE
+            return EXIT_OK
+          end
+          abort "#{USAGE}\nthis script takes no arguments — it checks every PR QualityControl::Patch or " \
+                "QualityControl::Improvement tracks as open, every time"
+        end
+
+        # Every `gh` call goes through the `GitPr` adapter. With `--json`, gh exits 0 whatever the
+        # checks say, so a failure means only that the call did not succeed.
+        @git_pr = Hecks::Adapters::GitPr.new(repo_dir: Dir.pwd)
+        @runtime = boot_ledger
+        worklists = WORKLISTS.to_h { |w| [w, query("#{w[:aggregate]}.Open")] }
+        if worklists.values.all?(&:empty?)
+          puts "no PRs tracked as open by QualityControl::Patch or QualityControl::Improvement — nothing to check"
+          return EXIT_OK
+        end
+
+        check_all(worklists)
+      end
+
+      private
+
+      def boot_ledger
+        Hecks.boot(@domain_dir)
+      rescue StandardError => e
+        abort "the QualityControl ledger did not boot — fix the ledger itself before checking PRs against it " \
+              "(#{e.class}: #{e.message})"
+      end
+
+      def check_all(worklists)
+        newly_red = []
+        operational_errors = []
+        worklists.each do |worklist, rows|
+          rows.each { |row| check_one_pr(row, newly_red, operational_errors, **worklist) }
+        end
+        report_errors(operational_errors)
+        return report_newly_red(newly_red) if newly_red.any?
+        return EXIT_ERROR if operational_errors.any?
+
+        puts
+        puts "clean — every PR QualityControl::Patch or QualityControl::Improvement tracks as open is " \
+             "either already cleared, still running, or was retired this run."
+        EXIT_OK
+      end
+
+      def query(name, **args) = @runtime.query("QualityControl::#{name}", **args)
+
+      # Reads nested row fields by `[]`, because `Hecks::Runtime::Value` does not answer `Hash#dig`.
+      def field(row, *path)
+        path.reduce(row) { |held, key| held.nil? ? nil : held[key] }
+      end
+
+      def clearance_for_commit(sha)
+        query("Clearance.All").find { |row| field(row, :commit, :value) == sha }
+      end
+
+      # Retires a Patch/Improvement whose PR GitHub reports merged or closed; nothing else tells
+      # the ledger. Returns true if it retired one.
+      def retire_if_settled?(view, number, label, aggregate)
+        case view[:state]
+        when "MERGED"
+          @runtime.dispatch_flat("QualityControl::#{aggregate}.Merge", { id: number })
+          puts "#{label}: merged — retired from the worklist"
+          true
+        when "CLOSED"
+          @runtime.dispatch_flat("QualityControl::#{aggregate}.Close", { id: number })
+          puts "#{label}: closed without merging — retired from the worklist"
+          true
+        else
+          false
+        end
+      end
+
+      # Runs a read against `gh`; a failure is appended to `operational_errors` and answers nil.
+      def reading_gh(label, operational_errors)
+        yield
+      rescue Hecks::Adapters::GitPr::CommandFailed => e
+        operational_errors << "#{label}: #{e.message}"
+        nil
+      end
+
+      # True when every check has finished, so a verdict is worth asking for. Pending stays out
+      # here because the CI port cannot express "ask again later".
+      def checks_settled?(number, label, citation, sha, operational_errors)
+        checks = reading_gh(label, operational_errors) { @git_pr.checks(number) }
+        return false unless checks
+
+        if checks.empty?
+          puts "#{label}, #{citation}, #{sha[0, 7]}: gh reports no checks at all yet — skipping this run"
+          return false
+        end
+
+        if checks.any? { |c| c[:bucket] == "pending" }
+          puts "#{label}, #{citation}, #{sha[0, 7]}: checks still running — skipping this run"
+          return false
+        end
+
+        true
+      end
+
+      # Checks one tracked PR, appending to `newly_red` or `operational_errors` in place. The live
+      # head sha is read from gh each run, since a push mints a new commit to clear.
+      def check_one_pr(row, newly_red, operational_errors, aggregate:, citation_field:, citation_label:)
+        number = field(row, :number, :value)
+        cited = field(row, citation_field)
+        citation = cited ? "#{citation_label} #{cited}" : "no #{citation_label} cited"
+        label = "#{aggregate} PR ##{number} (#{field(row, :branch, :value)})"
+
+        view = reading_gh(label, operational_errors) { @git_pr.pull_request(number) }
+        return unless view
+        return if retire_if_settled?(view, number, label, aggregate)
+
+        sha = view[:headRefOid].to_s
+        unless sha.match?(SHA_PATTERN)
+          operational_errors << "#{label}: head commit #{sha.inspect} does not look like a sha — skipping"
+          return
+        end
+
+        if (existing = clearance_for_commit(sha))
+          puts "#{label}, #{citation}, #{sha[0, 7]}: already cleared (#{existing[:status]}) — " \
+               "settled once, not re-checked"
+          return
+        end
+        return unless checks_settled?(number, label, citation, sha, operational_errors)
+
+        ask_the_ledger(sha, label, citation, number, newly_red, aggregate: aggregate)
+      end
+
+      # Starts a Clearance and asks the CI port for a verdict. ClearOnPass/RefuseOnFail settle the
+      # record synchronously, so `find` sees it straight away; a red one is appended to `newly_red`.
+      def ask_the_ledger(sha, label, citation, number, newly_red, aggregate:)
+        ::QualityControl::Clearance.start!(commit: { value: sha })
+        @runtime.dispatch_flat("QualityControl::Clearance.CI.Run", { commit: sha })
+
+        cleared = ::QualityControl::Clearance.find(sha)
+        summary = cleared.summary.to_h[:value]
+
+        if cleared.status == "green"
+          puts "#{label}, #{citation}, #{sha[0, 7]}: CLEARED — #{summary}"
+          return
+        end
+
+        puts "#{label}, #{citation}, #{sha[0, 7]}: RED — #{summary}"
+        newly_red << { aggregate: aggregate, pr: number, citation: citation, commit: sha, refusal: summary }
+      end
+
+      def report_errors(operational_errors)
+        return if operational_errors.empty?
+
+        puts
+        puts "operational error(s):"
+        operational_errors.each { |message| puts "  #{message}" }
+      end
+
+      def report_newly_red(newly_red)
+        puts
+        puts "=" * 72
+        puts "FOUND #{newly_red.length} NEWLY-RED PR(S) — BugCiWatch/ImprovementCiWatch already dispatched " \
+             "the matching Regress for each, by aggregate."
+        puts "An agent picks up the investigation from here: the same judgment"
+        puts "SKILL.md's own \"on a surprising check\" section describes for a sweep's"
+        puts "own find — self-contained fix with a regression test and a draft PR,"
+        puts "or leave the record for something bigger. Never re-verify from this script."
+        puts "=" * 72
+        newly_red.each do |finding|
+          puts
+          puts "aggregate: #{finding[:aggregate]}"
+          puts "citation:  #{finding[:citation]}"
+          puts "pr:        ##{finding[:pr]}"
+          puts "commit:    #{finding[:commit]}"
+          puts "refusal:   #{finding[:refusal]}"
+        end
+        EXIT_NEWLY_RED
+      end
+    end
+  end
+end

data/lib/hecks/quality_control/cli/qa_seed_angles.rb

@@ -0,0 +1,142 @@
+# frozen_string_literal: true
+
+require_relative "../../../hecks"
+# The era/lineage plugin has to be loaded before `Hecks.boot` for a real (non-Memory) adapter
+# (ADR 0033).
+require_relative "../../ports/persistence/plugins/era"
+
+module Hecks
+  module QualityControlCli
+    # The command behind `hecks quality_control angle.seed`: seeds the QualityControl ledger's
+    # `Angle` backlog with the practice's starting leads. It is idempotent: only references not
+    # already on file are proposed.
+    class QaSeedAngles
+      # A `resolution:` present means the lead was already chased down: it is proposed,
+      # investigated and built in one pass. Its absence means the lever is still open.
+      SEED = [
+        {
+          reference:  "ANGLE-1",
+          premise:    "None of BUG#1-5 touched saga/process_manager machinery at all, despite this " \
+                      "session having just built a real one (BugCiWatch) — a stress domain specifically " \
+                      "exercising process-manager correlation, multi-step handler chains, and compensation " \
+                      "legs was a natural, and the highest-priority, next target.",
+          citation:   "BugCiWatch (lib/hecks/quality_control/quality_control.bluebook, \"noticing when a fix " \
+                      "stops holding\"); BUG#1-5, none of which touched saga machinery",
+          proposer:   "Claude QA",
+          resolution: "BUG#6 — SagaInterpreter#qualified cannot tell a same-domain nested-entity " \
+                      "command reference (dispatch Manifest::Slot::Fill) apart from a genuine " \
+                      "cross-domain qualifier, so the leg is silently read as targeting a nonexistent " \
+                      "domain and refuses every time; found by qa/stress_domains/waybill on its first " \
+                      "real run, before fuzzing was even needed. PR #530 (merged)."
+        },
+        {
+          reference: "ANGLE-2",
+          premise:   "nested_pieces (qa/stress_domains/nested_pieces) proves two-level ENTITY nesting " \
+                     "fuzzes and dispatches correctly, but nothing in the corpus exercises deep " \
+                     "reference_to HOPS — a chain of reference-typed lookups across aggregates — or a " \
+                     "governance/authorization-shaped construct combined with existence-checking. Entity " \
+                     "nesting and reference hopping are different DSL mechanisms entirely (entity " \
+                     "addressing vs CommandRules::References#resolve_references / " \
+                     "resolve_state_references), and ADR 0037's own Finding 5 already shows reference " \
+                     "resolution is exactly the kind of place Ruby and Rust structurally diverge — a " \
+                     "stress domain built around multi-hop references, or a scope/authorization check " \
+                     "combined with existence-checking, is a genuinely different construct combination " \
+                     "from anything the six bugs found this session actually touched.",
+          citation:  "qa/stress_domains/nested_pieces (entity nesting, not reference hops); " \
+                     "docs/decisions/0037-generated-sequence-fuzz-bridge-found-real-gaps-two-fixed-" \
+                     "three-catalogued.md, Finding 5 (resolve_state_references never ported to Rust)",
+          proposer:  "Claude QA"
+        },
+        {
+          reference: "ANGLE-3",
+          premise:   "BUG#1/#3/#4 were specifically ENGINE-DIVERGENCE bugs — Ruby and Rust disagreeing " \
+                     "on the same dispatch — a class Ruby-only property/exception fuzzing structurally " \
+                     "cannot see, because there is no second engine to disagree with. " \
+                     "spec/rust_conformance_fuzz_spec.rb's own DOMAINS list wires up only pizzas and " \
+                     "banking for CI-gated differential fuzzing. rust/Cargo.toml already declares " \
+                     "compiled-binary features for compliance and roster (plus embryonaut and meta) that " \
+                     "sit unused for this purpose; examples/chess and examples/directory have no Cargo " \
+                     "feature at all — `hecks project_rust` has never regenerated a binary for either. " \
+                     "Widening either list would let differential fuzzing catch a whole bug class " \
+                     "Ruby-only fuzzing cannot, on domains the practice already owns.",
+          citation:  "BUG#1/#3/#4 (engine-divergence bugs); spec/rust_conformance_fuzz_spec.rb DOMAINS " \
+                     "(pizzas/banking only); rust/Cargo.toml [features] (compliance/roster/embryonaut/" \
+                     "meta have binaries and are not wired in; chess/directory have no feature at all)",
+          proposer:  "Claude QA"
+        },
+        {
+          reference: "ANGLE-4",
+          premise:   "lib/hecks/bluebook/model_check.rb's ALLOWED_FINDINGS, " \
+                     "spec/fuzzing/meta_domain_coverage_spec.rb's META_DOMAIN_GUARANTEED_BY_CONSTRUCTION " \
+                     "and META_DOMAIN_KNOWN_GAPS, and ADR 0037's own catalogued Findings 3-5 are all " \
+                     "places where something once labeled 'known, not a bug' could be re-examined — a " \
+                     "gap accepted a year ago is not guaranteed to still be the right call once the " \
+                     "surrounding code has moved. This session's own waybill finding (BUG#6) confirmed a " \
+                     "SECOND instance of exactly the family ALLOWED_FINDINGS[\"quality_control\"] already " \
+                     "named once (Naming.command_ref's bare-constant rewrite conflating a genuine " \
+                     "cross-domain qualifier with mere nesting) — proof the allowlists are themselves a " \
+                     "live source of leads, not just a static ledger of settled questions.",
+          citation:  "lib/hecks/bluebook/model_check.rb ALLOWED_FINDINGS; " \
+                     "spec/fuzzing/meta_domain_coverage_spec.rb META_DOMAIN_GUARANTEED_BY_CONSTRUCTION / " \
+                     "META_DOMAIN_KNOWN_GAPS; docs/decisions/0037-generated-sequence-fuzz-bridge-found-" \
+                     "real-gaps-two-fixed-three-catalogued.md Findings 3-5",
+          proposer:  "Claude QA"
+        }
+      ].freeze
+
+      # Proposes the leads the ledger lacks.
+      #
+      # @param root [String] the repository root, where `qa/bluebook` is the ledger
+      # @param out [IO] where each lead's outcome goes
+      # @return [Integer] 0 once seeded
+      # @raise [SystemExit] when the ledger does not boot
+      def self.call(root:, out: $stdout)
+        new(root: root, out: out).call
+      end
+
+      # @param root [String] the repository root
+      # @param out [IO] where each lead's outcome goes
+      def initialize(root:, out: $stdout)
+        @domain_dir = File.join(root, "qa/bluebook")
+        @out = out
+      end
+
+      # @return [Integer] 0 once seeded
+      # @raise [SystemExit] when the ledger does not boot
+      def call
+        runtime = begin
+          Hecks.boot(@domain_dir)
+        rescue StandardError => e
+          abort "the QualityControl ledger did not boot — fix the ledger itself before seeding it " \
+                "(#{e.class}: #{e.message})"
+        end
+        existing = runtime.query("QualityControl::Angle.All").map { |row| row[:reference][:value] }
+        SEED.each do |angle|
+          if existing.include?(angle[:reference])
+            @out.puts "already on file: #{angle[:reference]}"
+          else
+            propose(angle)
+          end
+        end
+        0
+      end
+
+      private
+
+      def propose(angle)
+        record = ::QualityControl::Angle.propose!(
+          reference: { value: angle[:reference] }, premise: { value: angle[:premise] },
+          citation: { value: angle[:citation] }, proposer: { value: angle[:proposer] },
+          now: { value: Time.now.to_i }
+        )
+        if angle[:resolution]
+          record = record.investigate!
+          record.build!(resolution: { value: angle[:resolution] })
+          @out.puts "proposed, investigated, and built: #{angle[:reference]}"
+        else
+          @out.puts "proposed: #{angle[:reference]}"
+        end
+      end
+    end
+  end
+end

data/lib/hecks/quality_control/cli/qa_seed_targets.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+require_relative "../../../hecks"
+# Load the era plugin before `Hecks.boot` (see hecks run).
+require_relative "../../ports/persistence/plugins/era"
+require_relative "../../fuzzing"
+require_relative "../../corpus"
+
+module Hecks
+  module QualityControlCli
+    # The command behind `hecks quality_control target.seed`: identifies every corpus domain as a
+    # rotation `Target`, printing each one's inferred capabilities. It is idempotent: references
+    # already on file are skipped whatever their status (re-`Identify` refuses).
+    #
+    # It skips `examples/embryonaut` (an external product) and `lib/hecks/framework` (no standalone
+    # Rust binary) on purpose.
+    class QaSeedTargets
+      # Identifies the targets the ledger lacks.
+      #
+      # @param root [String] the repository root
+      # @param env [Hash{String => String}] `QA_SWEEP_DOMAIN_DIR` points at another ledger
+      # @param out [IO] where each target's outcome goes
+      # @return [Integer] 0 once seeded
+      # @raise [SystemExit] when the ledger does not boot or a corpus path is missing
+      def self.call(root:, env: ENV, out: $stdout)
+        new(root: root, env: env, out: out).call
+      end
+
+      # @param root [String] the repository root
+      # @param env [Hash{String => String}] `QA_SWEEP_DOMAIN_DIR` points at another ledger
+      # @param out [IO] where each target's outcome goes
+      def initialize(root:, env: ENV, out: $stdout)
+        @root = root
+        @domain_dir = env.fetch("QA_SWEEP_DOMAIN_DIR", File.join(root, "qa/bluebook"))
+        @out = out
+      end
+
+      # @return [Integer] 0 once seeded
+      # @raise [SystemExit] when the ledger does not boot or a corpus path is missing
+      def call
+        # reference => path relative to the repository root, discovered from the corpus.
+        seed = Hecks::Corpus.rotation_targets(root: @root)
+        runtime = begin
+          Hecks.boot(@domain_dir)
+        rescue StandardError => e
+          abort "the QualityControl ledger did not boot — fix the ledger itself before seeding it " \
+                "(#{e.class}: #{e.message})"
+        end
+        existing = runtime.query("QualityControl::Target.All").map { |row| row[:reference][:value] }
+        seed.each { |reference, path| identify(reference, path, existing) }
+        0
+      end
+
+      private
+
+      def identify(reference, path, existing)
+        capabilities = Hecks::Fuzzing::TargetCapabilities.infer(File.join(@root, path)).join(",")
+        if existing.include?(reference)
+          @out.puts "already on file: #{reference} (#{path}; capabilities #{capabilities})"
+          return
+        end
+        abort "#{reference} names a path that does not exist on disk: #{path}" unless File.directory?(File.join(@root, path))
+
+        ::QualityControl::Target.identify!(reference: { value: reference }, path: { value: path })
+        @out.puts "identified: #{reference} (#{path}; capabilities #{capabilities})"
+      end
+    end
+  end
+end