hecks 3.4.2 → 3.6.0

data/lib/hecks/hecks/adapters/process_pool.rb

@@ -35,6 +35,10 @@ module Hecks
       # Signals passed on to a running child's process group.
       FORWARDED = %w[INT TERM HUP QUIT].freeze
 
+      # The flags of a sweep, and the fields of the record that fill them.
+      SWEEP_FLAGS = { "--seeds" => :seeds, "--steps" => :steps, "--workers" => :workers,
+                      "--adapter" => :adapter }.freeze
+
       class << self
         # @return [#call, nil] runs a child given `(command, env, chdir)` and answers a `Finished`;
         #   a spec replaces it so nothing is started
@@ -54,18 +58,9 @@ module Hecks
       # @return [Hash{Symbol => Hash}] `report:` what the sweep printed
       # @raise [ConsoleCapture::Failure] when the sweep found something, or could not run
       def sweep(**held)
-        if plain(held[:domain]).nil? && !RustWorkspace.new.checkout?
-          raise ConsoleCapture::Failure, "name a domain (hecks fuzz <domain>): sweeping every domain " \
-                                         "needs a hecks checkout"
-        end
-
-        command = [RbConfig.ruby, "-I", LIB, "-e", ENTRY, "--"]
-        command << plain(held[:domain]) if plain(held[:domain])
-        { "--seeds" => :seeds, "--steps" => :steps, "--workers" => :workers, "--adapter" => :adapter }.each do |flag, key|
-          command.push(flag, plain(held[key]).to_s) unless plain(held[key]).nil?
-        end
+        refuse_unnamed_sweep(held)
 
-        answer(run(command))
+        answer(run([RbConfig.ruby, "-I", LIB, "-e", ENTRY, "--", *sweep_words(held)]))
       end
 
       # Starts a child, forwards interrupts to it, and waits for it to end.
@@ -79,27 +74,64 @@ module Hecks
         return starter.call(command, env, chdir) if starter
 
         output = Tempfile.new("process-pool")
+        status = start_and_wait(command, env, spawn_options(output, chdir))
+        Finished.new(File.read(output.path), status)
+      rescue Errno::ENOENT => e
+        Finished.new(e.message, Struct.new(:success?, :exitstatus).new(false, 127))
+      ensure
+        output&.close!
+      end
+
+      private
+
+      # The refusal for a sweep of every domain outside a checkout.
+      def refuse_unnamed_sweep(held)
+        return unless plain(held[:domain]).nil? && !RustWorkspace.new.checkout?
+
+        raise ConsoleCapture::Failure, "name a domain (hecks fuzz <domain>): sweeping every domain " \
+                                       "needs a hecks checkout"
+      end
+
+      # The words after `--`: the domain when named, then each flag the record names.
+      def sweep_words(held)
+        words = []
+        words << plain(held[:domain]) if plain(held[:domain])
+        SWEEP_FLAGS.each { |flag, key| words.push(flag, plain(held[key]).to_s) unless plain(held[key]).nil? }
+        words
+      end
+
+      # The options a child is spawned with: its own process group, its output in `output`.
+      def spawn_options(output, chdir)
         options = { pgroup: true, out: output, err: output }
         options[:chdir] = chdir if chdir
-        # Traps go in before the spawn, so a signal that lands while the child is starting is held
-        # and passed on the moment its pid is known, instead of orphaning it.
+        options
+      end
+
+      # Starts the child and waits for it, passing on the signals sent to this process meanwhile.
+      # Traps go in before the spawn, so a signal that lands while the child is starting is held
+      # and passed on the moment its pid is known, instead of orphaning it.
+      #
+      # @return [Process::Status] how the child ended
+      def start_and_wait(command, env, options)
         pid = nil
         held = []
-        previous = FORWARDED.to_h do |name|
-          [name, trap(name) { pid ? forward(name, pid) : held << name }]
-        end
+        previous = trap_forwarded(held) { pid }
         pid = spawn(env, *command, **options)
         held.each { |name| forward(name, pid) }
-        _, status = Process.wait2(pid)
-        Finished.new(File.read(output.path), status)
-      rescue Errno::ENOENT => e
-        Finished.new(e.message, Struct.new(:success?, :exitstatus).new(false, 127))
+        Process.wait2(pid).last
       ensure
         previous&.each { |name, handler| trap(name, handler) }
-        output&.close!
       end
 
-      private
+      # Traps every forwarded signal, answering the handlers it replaced.
+      #
+      # @param held [Array<String>] collects the signals that arrive before the pid is known
+      # @yield answers the child's pid, or nil while it is still starting
+      def trap_forwarded(held, &)
+        FORWARDED.to_h do |name|
+          [name, trap(name) { (pid = yield) ? forward(name, pid) : held << name }]
+        end
+      end
 
       def forward(name, pid)
         Process.kill(name, -pid)

data/lib/hecks/hecks/adapters/rust_toolchain.rb

@@ -139,10 +139,8 @@ module Hecks
       # @return [Hash{Symbol => Hash}] `report:` what the benchmark printed
       # @raise [ConsoleCapture::Failure] when it could not run, or the install has no Rust workspace
       def measure(**held)
-        flags = BENCH_FLAGS.filter_map { |flag, key| [flag, plain(held[key]).to_s] unless plain(held[key]).nil? }
-        env = (self.class.workspace || RustWorkspace.new).environment.merge("HECKS_NO_3_0_NOTICE" => "1")
-        command = [RbConfig.ruby, "-I", LIB, "-e", BENCH, "--", *flags.flatten]
-        finished = (self.class.pool || ProcessPool.new).run(command, env: env)
+        command = [RbConfig.ruby, "-I", LIB, "-e", BENCH, "--", *bench_flags(held)]
+        finished = (self.class.pool || ProcessPool.new).run(command, env: bench_environment)
         raise ConsoleCapture::Failure, finished.output.strip unless finished.ok?
 
         { report: { value: finished.output } }
@@ -168,6 +166,16 @@ module Hecks
 
       private
 
+      # The environment the benchmark runs in: the Rust workspace's, without the 3.0 notice.
+      def bench_environment
+        (self.class.workspace || RustWorkspace.new).environment.merge("HECKS_NO_3_0_NOTICE" => "1")
+      end
+
+      # The benchmark's flags, each with its value, for those the record names.
+      def bench_flags(held)
+        BENCH_FLAGS.filter_map { |flag, key| [flag, plain(held[key]).to_s] unless plain(held[key]).nil? }.flatten
+      end
+
       def child(ask, argv)
         result = run(ask, argv)
         raise ConsoleCapture::Failure, message_of(result) unless result.ok?

data/lib/hecks/hecks/adapters/site_toolchain.rb

@@ -22,7 +22,7 @@ module Hecks
       SCRIPTS = { project: "project_site" }.freeze
 
       # The tool's flag for each `SiteProjection` field that takes a value.
-      FLAGS = { "out" => :out, "template" => :template, "extension" => :extension }.freeze
+      FLAGS = { "out" => :out, "template" => :template, "cms" => :cms, "root" => :root, "extension" => :extension }.freeze
 
       # Accepts the arguments every driven adapter is built with and keeps none of them.
       #
@@ -33,16 +33,14 @@ module Hecks
 
       # Writes a project's `routes.ts` from its declared route table, or with `check` only compares.
       #
-      # @param held [Hash] the `SiteProjection` record: `domain`, and `out`, `template`, `extension`
-      #   and `check` when set
+      # @param held [Hash] the `SiteProjection` record: `domain`, and `out`, `template`, `cms`,
+      #   `root`, `extension` and `check` when set
       # @return [Hash{Symbol => Hash}] `output:` one line per file written or found current
       # @raise [ConsoleCapture::Failure] when the route table is refused (an unknown cache class,
       #   a duplicate path), a path or the extension is refused, or under `check` a file is out
       #   of date
       def project(**held)
-        flags = FLAGS.filter_map { |flag, key| "--#{flag}=#{located(key, held[key])}" unless plain(held[key]).nil? }
-        flags << "--check" if plain(held[:check]) == true
-        result = Codebase::RubyChild.new(Codebase::Tree.new).capture(SCRIPTS.fetch(:project), *flags,
+        result = Codebase::RubyChild.new(Codebase::Tree.new).capture(SCRIPTS.fetch(:project), *project_flags(held),
                                                                      located(:domain, held[:domain]))
         raise ConsoleCapture::Failure, message_of(result) unless result.ok?
 
@@ -62,10 +60,7 @@ module Hecks
       #   cannot be read, or the two differ; the message is the report
       def compare(**held)
         edge = edge_of(located(:domain, held[:domain]), located(:template, held[:template]))
-        live = live_configuration(held)
-        live_edge = Projections::Site::LiveEdge
-        comparison = live_edge.new(edge, live, expect_new: words(held[:expect_new]),
-                                               refs:       live_edge.refs_from(plain(held[:refs]))).call
+        comparison = compared(edge, live_configuration(held), held)
         raise ConsoleCapture::Failure, comparison.to_s unless comparison.clean?
 
         { output: { value: comparison.to_s } }
@@ -73,6 +68,20 @@ module Hecks
 
       private
 
+      # The flags `project_site` is run with: each the record names, and `--check` when asked.
+      def project_flags(held)
+        flags = FLAGS.filter_map { |flag, key| "--#{flag}=#{located(key, held[key])}" unless plain(held[key]).nil? }
+        flags << "--check" if plain(held[:check]) == true
+        flags
+      end
+
+      # The comparison of the project's edge with the live configuration.
+      def compared(edge, live, held)
+        live_edge = Projections::Site::LiveEdge
+        live_edge.new(edge, live, expect_new: words(held[:expect_new]),
+                                  refs:       live_edge.refs_from(plain(held[:refs]))).call
+      end
+
       # The project's checked edge, read the way `project_site` reads it.
       def edge_of(root, template = nil)
         registry = nil

data/lib/hecks/hecks/adapters/terminal.rb

@@ -40,7 +40,7 @@ module Hecks
         launcher = self.class.launcher
         launcher ? CLI::Console.call(domain, launcher: launcher) : CLI::Console.call(domain)
 
-        { output: { value: "console session ended (#{domain || 'pizzas'})" } }
+        { output: { value: "console session ended (#{domain || "pizzas"})" } }
       end
 
       # Hands the process over to the MCP door until the client closes stdin. The door writes its
@@ -52,14 +52,7 @@ module Hecks
       # @raise [ConsoleCapture::Failure] when the process is not set up for stdio: the door
       #   refused to start, and said why on stderr
       def serve(**held)
-        argv = plain(held[:stdio]) ? ["--stdio"] : []
-        server = self.class.server
-        if server
-          server.call(argv)
-        else
-          require "hecks/cli/mcp"
-          CLI::Mcp.call(argv)
-        end
+        run_door(plain(held[:stdio]) ? ["--stdio"] : [])
 
         { output: { value: "mcp door closed" } }
       rescue SystemExit => e
@@ -83,6 +76,17 @@ module Hecks
 
       private
 
+      # Hands the process to the server a spec set, or else to the real MCP door.
+      def run_door(argv)
+        server = self.class.server
+        if server
+          server.call(argv)
+        else
+          require "hecks/cli/mcp"
+          CLI::Mcp.call(argv)
+        end
+      end
+
       def plain(argument) = argument.is_a?(Hash) ? argument[:value] : argument
     end
   end

data/lib/hecks/hecks/codebase.bluebook

@@ -960,6 +960,7 @@ Hecks.bluebook "Hecks" do
     attribute :operation, Operation, optional: true
     attribute :confirm,   Switch, optional: true
     attribute :check,     Switch, optional: true
+    attribute :live,      Switch, optional: true
     attribute :gate,      GateName, optional: true
     attribute :checkout,  Switch, optional: true
     attribute :report,    Report, optional: true
@@ -1027,6 +1028,24 @@ Hecks.bluebook "Hecks" do
       emits ProjectCiGatesRequested
     end
 
+    command "ProjectLanes" do
+      role "Maintainer"
+      goal "Project the Lane rows into the rulesets and the promotion workflow, or with live compare GitHub's rulesets"
+
+      attribute :check,   Switch, optional: true
+      attribute :live,    Switch, optional: true
+      attribute :run,     RunKey
+      attribute :confirm, Switch, optional: true
+
+      sets :check
+      sets :live
+      sets :run
+      sets :confirm
+      sets :operation, to: "project_lanes"
+
+      emits ProjectLanesRequested
+    end
+
     command "ProjectToolsDoc" do
       role "Maintainer"
       goal "Write the launcher forms of docs/tools.md from the RetiredScript rows, or with check only compare them"
@@ -1121,6 +1140,11 @@ Hecks.bluebook "Hecks" do
     trigger RegenerationRun::SourceTree::Examine, with: { run: :run }
   end
 
+  policy "ExamineWhenProjectLanesRequested" do
+    on      "RegenerationRun.ProjectLanesRequested"
+    trigger RegenerationRun::SourceTree::Examine, with: { run: :run }
+  end
+
   policy "ExamineWhenProjectToolsDocRequested" do
     on      "RegenerationRun.ProjectToolsDocRequested"
     trigger RegenerationRun::SourceTree::Examine, with: { run: :run }
@@ -2365,6 +2389,7 @@ Hecks.bluebook "Hecks" do
     attribute :no_wait,        Switch, optional: true
     attribute :checkout,       Switch, optional: true
     attribute :branch,         Word, optional: true
+    attribute :release_lane,   Word, optional: true
     attribute :on_origin,      Switch, optional: true
     attribute :clean,          Switch, optional: true
     attribute :version,        Version, optional: true
@@ -2465,6 +2490,7 @@ Hecks.bluebook "Hecks" do
       reference_to PublishingRun
       attribute :checkout,       Switch
       attribute :branch,         Word
+      attribute :release_lane,   Word
       attribute :on_origin,      Switch
       attribute :clean,          Switch
       attribute :version,        Version
@@ -2476,8 +2502,10 @@ Hecks.bluebook "Hecks" do
       attribute :ships_from,     Checkout
 
       given("needs a hecks checkout: hecks.gemspec stands beside lib/") { checkout.value }
-      given("a release is cut from main: switch to main first") { branch.value == "main" }
-      given("main is origin/main: merge the release PR, then pull") { on_origin.value }
+      given("a release is cut from the release lane (the Lane row that feeds a tag): switch to it first") do
+        branch.value == release_lane.value
+      end
+      given("the release lane is its origin: wait for the release commit to be promoted, then pull") { on_origin.value }
       given("the working tree is clean: commit or discard changes first") { clean.value }
       given("the client package is at the gem's version: bump the package first") do
         client_version.value == version.value
@@ -2489,6 +2517,7 @@ Hecks.bluebook "Hecks" do
 
       sets :checkout
       sets :branch
+      sets :release_lane
       sets :on_origin
       sets :clean
       sets :version
@@ -2585,8 +2614,9 @@ Hecks.bluebook "Hecks" do
   policy "AcceptTheReleaseWhenExamined" do
     on      "PublishingRun.PublishingExamined"
     where   { operation.value == "publish" }
-    trigger PublishingRun::Accept, with: { checkout: :checkout, branch: :branch, on_origin: :on_origin,
-                                           clean: :clean, version: :version, client_version: :client_version,
+    trigger PublishingRun::Accept, with: { checkout: :checkout, branch: :branch, release_lane: :release_lane,
+                                           on_origin: :on_origin, clean: :clean, version: :version,
+                                           client_version: :client_version,
                                            changelog: :changelog, tag_state: :tag_state, head: :head,
                                            ir_version: :ir_version, ships_from: :ships_from }
   end
@@ -2603,7 +2633,7 @@ Hecks.bluebook "Hecks" do
     on      "PublishingRun.PublishingExamined"
     where do
       operation.value == "publish" &&
-        (!checkout.value || branch.value != "main" || !on_origin.value || !clean.value ||
+        (!checkout.value || branch.value != release_lane.value || !on_origin.value || !clean.value ||
           client_version.value != version.value || !changelog.value || tag_state.value == "elsewhere")
     end
     trigger PublishingRun::Fault, with: { refusal: "a release rule is not met: check the branch, tree, versions, CHANGELOG and tag" }
@@ -2666,4 +2696,291 @@ Hecks.bluebook "Hecks" do
     on      "PublishingRun.PublishingRefused"
     trigger PublishingRun::Fault, with: { refusal: :refusal }
   end
+
+  # Promotion: moving a lane forward onto a commit that has passed every `RequiredCheck`. The
+  # adapter reads the facts (does the lane exist, where its head stands, where each check stands
+  # against the commit) and `Accept` holds the rules, so what makes a commit fit for the lane is
+  # decided here and in the Lane and RequiredCheck rows, never by the workflow that runs
+  # `hecks promotion_run.promote`. Without --confirm the run is a rehearsal: it names the move it
+  # would make and makes none. A real run fast-forwards the lane (never forces it) and moves the
+  # tag the lane `feeds`, forward only; a lane that already holds the commit still has its tag
+  # brought up to the lane's head, so a half-finished run is finished by the next.
+  #
+  # A commit is certified by the checks of that exact commit. With `commit` named, that commit is
+  # the one judged, and no other is ever put in its place. Without it, the commit is the newest
+  # one of the followed lane (first-parent, a bounded way back) that every `RequiredCheck` passed
+  # on and that fast-forwards the lane, so the outcome never depends on which push's CI run
+  # started the promotion; when none qualifies the refusal names what the lane's head is
+  # waiting on.
+  aggregate "PromotionRun" do
+    description "One move of a lane onto a commit, or the rehearsal of it: judged by the facts, then carried out."
+
+    attribute :run,        RunKey
+    attribute :operation,  Operation, optional: true
+    attribute :confirm,    Switch, optional: true
+    attribute :lane,       Word
+    attribute :commit,     Word, optional: true
+    attribute :checkout,   Switch, optional: true
+    attribute :lane_known, Switch, optional: true
+    attribute :green,      Switch, optional: true
+    attribute :descends,   Switch, optional: true
+    attribute :head,       Word, optional: true
+    attribute :behind_hours, Hours, optional: true
+    attribute :limit_hours,  Hours, optional: true
+    attribute :alert_key,    Word, optional: true
+    attribute :promoted,   Switch, optional: true
+    attribute :reason,     Report, optional: true
+    attribute :report,     Report, optional: true
+    attribute :refusal,    Report, optional: true
+    identified_by :run
+
+    value_object "RunKey" do
+      attribute :value, String, pattern: '[^ \t\n\r]'
+
+      invariant("a run is named") { !value.to_s.empty? }
+    end
+
+    value_object "Operation" do
+      attribute :value, String, pattern: '[^ \t\n\r]'
+    end
+
+    value_object "Switch" do
+      attribute :value, Boolean
+    end
+
+    value_object "Report" do
+      attribute :value, String
+    end
+
+    # A branch name, or a commit.
+    value_object "Word" do
+      attribute :value, String, pattern: '[^ \t\n\r]'
+    end
+
+    # How long a lane has stood behind the lane it follows, or how long its row lets it.
+    value_object "Hours" do
+      attribute :value, Integer
+    end
+
+    lifecycle :status, default: "requested" do
+      transition "Accept"   => "accepted",  from: "requested"
+      transition "Observe"  => "observed",  from: "requested"
+      transition "Complete" => "completed", from: %w[accepted observed]
+      transition "Fault"    => "faulted",   from: %w[requested accepted]
+      transition "Lag"      => "faulted",   from: "observed"
+    end
+
+    # Looks at a lane and moves nothing: faults when it has stood behind the lane it follows for
+    # longer than its `Lane` row allows, which files a finding. A lane whose row allows no lag is
+    # never late.
+    command "Watch" do
+      role "Maintainer"
+      goal "Fault when a lane has stood behind the lane it follows for longer than its Lane row allows"
+
+      attribute :lane,      Word
+      attribute :run,       RunKey
+      attribute :alert_key, Word
+
+      sets :lane
+      sets :run
+      sets :alert_key
+      sets :operation, to: "watch"
+
+      emits WatchRequested
+    end
+
+    command "Promote" do
+      role "Maintainer"
+      goal "Move a lane onto a commit that has passed every required check, or with no --confirm rehearse the move"
+
+      attribute :lane,    Word
+      attribute :commit,  Word, optional: true
+      attribute :run,     RunKey
+      attribute :confirm, Switch, optional: true
+
+      sets :lane
+      sets :commit
+      sets :run
+      sets :confirm
+      sets :operation, to: "promote"
+
+      emits PromoteRequested
+    end
+
+    # What the tree and the remote reported, held against the rules of a promotion: the adapter
+    # supplies the facts and the givens decide.
+    command "Accept" do
+      role "System"
+      goal "Let a lane move only in a hecks checkout, onto a commit that is green on every required check and contains the lane's head"
+
+      reference_to PromotionRun
+      attribute :checkout,   Switch
+      attribute :lane_known, Switch
+      attribute :green,      Switch
+      attribute :descends,   Switch
+      attribute :commit,     Word
+      attribute :head,       Word, optional: true
+
+      given("needs a hecks checkout: hecks.gemspec stands beside lib/") { checkout.value }
+      given("the lane is one of the Lane rows, and follows another lane") { lane_known.value }
+      given("every RequiredCheck is green on the commit: wait for the checks, or fix the red one") { green.value }
+      given("the commit is on the lane it follows and contains the lane's head: a lane only moves forward") { descends.value }
+
+      sets :checkout
+      sets :lane_known
+      sets :green
+      sets :descends
+      sets :commit
+      sets :head
+
+      emits PromotionAccepted
+    end
+
+    # What the tree and the remote reported about a watched lane, held against the rules of a
+    # watch: it needs a hecks checkout and a lane that follows another.
+    command "Observe" do
+      role "System"
+      goal "Let a lane be judged late or on time only in a hecks checkout, for a lane that follows another"
+
+      reference_to PromotionRun
+      attribute :checkout,     Switch
+      attribute :lane_known,   Switch
+      attribute :behind_hours, Hours
+      attribute :limit_hours,  Hours
+      attribute :alert_key,    Word
+      attribute :promoted,     Switch
+      attribute :reason,       Report
+
+      given("needs a hecks checkout: hecks.gemspec stands beside lib/") { checkout.value }
+      given("the lane is one of the Lane rows, and follows another lane") { lane_known.value }
+
+      sets :checkout
+      sets :lane_known
+      sets :behind_hours
+      sets :limit_hours
+      sets :alert_key
+      sets :promoted
+      sets :reason
+
+      emits LaneObserved
+    end
+
+    command "Complete" do
+      role "System"
+      goal "Record that the promotion was carried out or rehearsed, or the lane was on time, and what it reported"
+
+      reference_to PromotionRun
+      attribute :report,   Report
+      attribute :promoted, Switch
+
+      sets :report
+      sets :promoted
+
+      emits PromotionCompleted
+    end
+
+    # A lane that has stood behind the lane it follows for longer than its Lane row allows.
+    command "Lag" do
+      role "System"
+      goal "Record that a lane is late, and what it is waiting on, under the alert key that names its finding"
+
+      reference_to PromotionRun
+      attribute :refusal,   Report
+      attribute :alert_key, Word
+
+      sets :refusal
+      sets :alert_key
+
+      emits LaneLagged
+    end
+
+    command "Fault" do
+      role "System"
+      goal "Record that the promotion was refused or could not be carried out, and why"
+
+      reference_to PromotionRun
+      attribute :refusal, Report
+
+      sets :refusal
+
+      emits PromotionFaulted
+    end
+
+    query "PromotionOutcome" do
+      description "How one promotion ended: its status, and what it reported or why it failed."
+      attribute :run, RunKey
+      where(run: :run)
+      order_by :run
+    end
+
+    query "PromotionFaulted" do
+      description "Every promotion that was refused or could not be carried out."
+      where(status: "faulted")
+      order_by :run
+    end
+  end
+
+  policy "ExamineWhenPromoteRequested" do
+    on      "PromotionRun.PromoteRequested"
+    trigger PromotionRun::SourceTree::Examine, with: { run: :run }
+  end
+
+  policy "ExamineWhenWatchRequested" do
+    on      "PromotionRun.WatchRequested"
+    trigger PromotionRun::SourceTree::Examine, with: { run: :run }
+  end
+
+  policy "ObserveWhenWatchExamined" do
+    on      "PromotionRun.PromotionExamined"
+    where   { operation.value == "watch" }
+    trigger PromotionRun::Observe, with: { checkout: :checkout, lane_known: :lane_known, behind_hours: :behind_hours,
+                                           limit_hours: :limit_hours, alert_key: :alert_key, promoted: :promoted,
+                                           reason: :reason }
+  end
+
+  policy "FaultWhenWatchCannotBeJudged" do
+    on      "PromotionRun.PromotionExamined"
+    where   { operation.value == "watch" && (!checkout.value || !lane_known.value) }
+    trigger PromotionRun::Fault, with: { refusal: :reason }
+  end
+
+  policy "LagWhenLaneLate" do
+    on      "PromotionRun.LaneObserved"
+    where   { behind_hours.value > limit_hours.value }
+    trigger PromotionRun::Lag, with: { refusal: :reason, alert_key: :alert_key }
+  end
+
+  policy "CompleteWhenLaneOnTime" do
+    on      "PromotionRun.LaneObserved"
+    where   { behind_hours.value <= limit_hours.value }
+    trigger PromotionRun::Complete, with: { report: :reason, promoted: :promoted }
+  end
+
+  policy "AcceptPromotionWhenExamined" do
+    on      "PromotionRun.PromotionExamined"
+    where   { operation.value == "promote" }
+    trigger PromotionRun::Accept, with: { checkout: :checkout, lane_known: :lane_known, green: :green,
+                                          descends: :descends, commit: :commit, head: :head }
+  end
+
+  policy "FaultPromotionWhenNotAccepted" do
+    on      "PromotionRun.PromotionExamined"
+    where   { operation.value == "promote" && (!checkout.value || !lane_known.value || !green.value || !descends.value) }
+    trigger PromotionRun::Fault, with: { refusal: :reason }
+  end
+
+  policy "PerformPromotionWhenAccepted" do
+    on      "PromotionRun.PromotionAccepted"
+    trigger PromotionRun::SourceTree::Perform, with: { run: :run }
+  end
+
+  policy "RecordPromotionOutcome" do
+    on      "PromotionRun.PromotionAnswered"
+    trigger PromotionRun::Complete, with: { report: :report, promoted: :promoted }
+  end
+
+  policy "RecordPromotionFault" do
+    on      "PromotionRun.PromotionRefused"
+    trigger PromotionRun::Fault, with: { refusal: :refusal }
+  end
 end

data/lib/hecks/hecks/custodian.bluebook

@@ -121,6 +121,7 @@ Hecks.bluebook "Hecks" do
     attribute :profile, ProfileName, optional: true
     attribute :strict,  Switch,      optional: true
     attribute :report,  Report,      optional: true
+    attribute :checked, Checked,     optional: true
     attribute :refusal, Report,      optional: true
     identified_by :run
 
@@ -146,6 +147,13 @@ Hecks.bluebook "Hecks" do
       attribute :value, String
     end
 
+    # How many domains the report examined, counted from its headers so a reader need not.
+    value_object "Checked" do
+      attribute :value, Integer
+
+      invariant("a count is not negative") { value >= 0 }
+    end
+
     lifecycle :status, default: "requested" do
       transition "Pass" => "clean",   from: "requested"
       transition "Flag" => "flagged", from: "requested"
@@ -173,9 +181,11 @@ Hecks.bluebook "Hecks" do
       goal "Record that the analysis left no error"
 
       reference_to ModelCheckRun
-      attribute :report, Report
+      attribute :report,  Report
+      attribute :checked, Checked
 
       sets :report
+      sets :checked
 
       emits ModelCheckPassed
     end
@@ -214,7 +224,7 @@ Hecks.bluebook "Hecks" do
 
   policy "RecordTheClean" do
     on      "ModelCheckRun.ModelCheckAnswered"
-    trigger ModelCheckRun::Pass, with: { report: :report }
+    trigger ModelCheckRun::Pass, with: { report: :report, checked: :checked }
   end
 
   policy "RecordTheFlag" do