hecks 7.0.0 → 7.1.0

data/lib/hecks/hecks/deliver/deliver.bluebook

@@ -342,6 +342,7 @@ Hecks.bluebook "Hecks" do
       attribute :onto,     Word,   optional: true
       attribute :from,     RunKey, optional: true
       attribute :landed,   Word,   optional: true
+      attribute :reason,   Report, optional: true
       attribute :report,   Report, optional: true
       attribute :refusal,  Report, optional: true
       identified_by :run
@@ -367,10 +368,12 @@ Hecks.bluebook "Hecks" do
         mark :failure, "refused"
         transition "Record"  => "landed",  from: "requested"
         transition "Clear"   => "retired", from: "requested"
+        transition "Dispose" => "discarded", from: "requested"
+        transition "Spare"   => "refused", from: "requested"
         transition "Refuse"  => "refused", from: "requested"
         transition "Decline" => "refused", from: "requested"
         transition "Convoy"  => "convoyed", from: "requested"
-        mark :terminal, "landed", "refused", "retired", "convoyed"
+        mark :terminal, "landed", "refused", "retired", "discarded", "convoyed"
       end
 
       command "Land" do
@@ -467,6 +470,44 @@ Hecks.bluebook "Hecks" do
         emits RetirementRequested
       end
 
+      command "Discard" do
+        role "Operator"
+        goal "Remove a worktree and delete its branch even though main lacks its commits, for a stated reason: refused for a protected branch, a worktree in use, or uncommitted work"
+
+        attribute :run,      RunKey, sets: true
+        attribute :checkout, Word, optional: true, sets: true
+        attribute :branch,   Word, optional: true, sets: true
+        attribute :onto,     Word, default: "main", sets: true
+        attribute :reason,   Report, sets: true
+        attribute :confirm,  Switch, optional: true, sets: true
+
+        given("a discard says why") { reason.value != "" }
+        given("discards the branch's commits that main lacks needs --confirm; without it this only reports") { confirm.value == true }
+
+        emits DiscardRequested
+      end
+
+      command "Dispose" do
+        role "System"
+        goal "Record that the worktree and its branch were discarded, with the tip they were at"
+
+        reference_to Landing
+        attribute :branch, Word, sets: true
+        attribute :report, Report, sets: true
+
+        emits WorktreeDiscarded
+      end
+
+      command "Spare" do
+        role "System"
+        goal "Record why a worktree was not discarded"
+
+        reference_to Landing
+        attribute :refusal, Report, sets: true
+
+        emits DiscardDeclined
+      end
+
       command "Clear" do
         role "System"
         goal "Record that the worktree and its branch are gone"
@@ -554,6 +595,21 @@ Hecks.bluebook "Hecks" do
       ask     :remove, with: { run: :run }
     end
 
+    policy "DiscardWhenAsked" do
+      on      "Landing.DiscardRequested"
+      ask     :drop_branch, with: { run: :run }
+    end
+
+    policy "RecordTheDiscard" do
+      on      "Landing.DiscardAnswered"
+      trigger Landing::Dispose, with: { branch: :branch, report: :report }
+    end
+
+    policy "RecordTheSparedWorktree" do
+      on      "Landing.DiscardRefused"
+      trigger Landing::Spare, with: { refusal: :refusal }
+    end
+
     policy "RecordTheRetirement" do
       on      "Landing.RemovalAnswered"
       trigger Landing::Clear, with: { branch: :branch, report: :report }
@@ -602,6 +658,7 @@ Hecks.bluebook "Hecks" do
       attribute :full_gate, Switch, optional: true
       attribute :boarded,  Word,   optional: true
       attribute :pushed,   Word,   optional: true
+      attribute :commits,  Count,  optional: true
       attribute :report,   Report, optional: true
       attribute :refusal,  Report, optional: true
       identified_by :run
@@ -623,6 +680,12 @@ Hecks.bluebook "Hecks" do
         attribute :value, Boolean
       end
 
+      # How many commits the branch held that the remote did not, as the boarding began.
+      value_object "Count" do
+        attribute :value, Integer
+        invariant("a count is not negative") { !value.negative? }
+      end
+
       lifecycle :status, default: "requested" do
         mark :failure, "faulted"
         transition "Send"  => "pushed",  from: "requested"
@@ -685,6 +748,7 @@ Hecks.bluebook "Hecks" do
         attribute :checkout, Word, sets: true
         attribute :boarded,  Word, sets: true
         attribute :pushed,   Word, sets: true
+        attribute :commits,  Count, optional: true, sets: true
         attribute :report,   Report, sets: true
 
 
@@ -735,7 +799,8 @@ Hecks.bluebook "Hecks" do
     policy "RecordThePush" do
       on      "SendTrain.TrainAnswered"
       where   { outcome.value == "pushed" }
-      trigger SendTrain::Send, with: { checkout: :checkout, boarded: :boarded, pushed: :pushed, report: :report }
+      trigger SendTrain::Send, with: { checkout: :checkout, boarded: :boarded, pushed: :pushed, commits: :commits,
+                                       report: :report }
     end
 
     policy "RecordTheRide" do
@@ -771,6 +836,86 @@ Hecks.bluebook "Hecks" do
       ask     :announce, with: { run: :run, pushed: :pushed }
     end
 
+    # What landings left behind is listed after a push, and nothing is removed: a session may still
+    # be working in a worktree whose branch landed, and a clean tree looks the same as a finished one.
+    policy "ListLeftoversWhenPushed" do
+      on      "SendTrain.BranchPushed"
+      ask     :leftovers, with: { run: :run, pushed: :pushed }
+    end
+
+    # The train runs in Memory, in a checkout of its own, so its outcome is recorded where the
+    # boarded checkout keeps its records: the `PushRecords` port runs that checkout's own
+    # `PushOutcome.Record`. A recording that fails is answered `OutcomeUnrecorded` and changes
+    # nothing about the push.
+    policy "RecordThePushedOutcome" do
+      on      "SendTrain.BranchPushed"
+      ask     :record_outcome, with: { run: :run }
+    end
+
+    policy "RecordTheCarriedOutcome" do
+      on      "SendTrain.CarriedByEarlierPush"
+      ask     :record_outcome, with: { run: :run }
+    end
+
+    policy "RecordTheFaultedOutcome" do
+      on      "SendTrain.PushFaulted"
+      ask     :record_outcome, with: { run: :run }
+    end
+
+    # How one boarding of the train ended, recorded by the checkout that boarded it. It is its own
+    # aggregate, not SendTrain, so recording a push in the checkout fires none of the reactions a
+    # push itself has (the launcher refresh, the deploy announcement, the GateAndBoard saga).
+    aggregate "PushOutcome" do
+      description "How one boarding of the push train ended, as the boarded checkout records it: pushed, carried or faulted."
+
+      attribute :run,      OutcomeKey
+      attribute :checkout, Locator
+      attribute :branch,   Locator, optional: true
+      attribute :outcome,  Ending
+      attribute :pushed,   Locator, optional: true
+      attribute :commits,  Tally,  optional: true
+      attribute :report,   Line,   optional: true
+      identified_by :run
+
+      # The boarding's run and how it ended, so a boarding run again is recorded beside the first.
+      value_object "OutcomeKey" do
+        attribute :value, String, matches: :present
+      end
+
+      # A checkout (written with its trailing slash), a branch or a commit.
+      value_object "Locator" do
+        attribute :value, String, matches: :present
+      end
+
+      value_object "Ending" do
+        attribute :value, String, pattern: '\A(pushed|carried|faulted)\z'
+      end
+
+      value_object "Tally" do
+        attribute :value, Integer
+        invariant("a count is not negative") { !value.negative? }
+      end
+
+      value_object "Line" do
+        attribute :value, String
+      end
+
+      command "Record" do
+        role "Operator"
+        goal "Record how one boarding of the push train ended, in the checkout that boarded it"
+
+        attribute :run,      OutcomeKey, sets: true
+        attribute :checkout, Locator, sets: true
+        attribute :branch,   Locator, optional: true, sets: true
+        attribute :outcome,  Ending, sets: true
+        attribute :pushed,   Locator, optional: true, sets: true
+        attribute :commits,  Tally, optional: true, sets: true
+        attribute :report,   Line, optional: true, sets: true
+
+        emits PushRecorded
+      end
+    end
+
     # The request that starts GateAndBoard, under its own identity so the Landing record it leads to
     # is a separate one: Land creates a Landing under the same run key, and that would collide.
     aggregate "Shipment" do
@@ -807,6 +952,309 @@ Hecks.bluebook "Hecks" do
       end
     end
 
+    # Main is integrated by a process: every landing onto local main starts a run keyed by the
+    # landed commit, and each run is verified in a clean copy, boarded on the push train and
+    # watched on CI, ending green or red, or parked in needs_human with the reason. The
+    # coordinator drives it with `Integration.advance!`, which dispatches each open run's next step
+    # at top level; a step records itself and waits, so no dispatch runs inside the saga and the
+    # reaction depth stays bounded. Shipment's path joins it: its landing starts a run too, and a
+    # boarding the train already carried is recorded as pushed. A run is checkpointed with the
+    # Landing records that start it, so a copy that keeps those keeps its runs across a restart.
+    # A run in needs_human is taken up again by verifying it again (`Integration.verify!`).
+    process_manager "MainIntegration" do
+      correlates_by :"landed.value"
+      starts_on Landing::BranchLanded
+
+      transition Integration::MainVerificationStarted => "verifying", from: %w[landed needs_human]
+      transition Integration::MainVerified => "verified", from: "verifying"
+      transition Integration::MainBoardingStarted => "boarding", from: "verified"
+      transition Integration::MainPushed => "pushed", from: "boarding"
+      transition Integration::CiObservationStarted => "ci_running", from: %w[pushed ci_running]
+      transition Integration::CiPassed => "green", from: "ci_running"
+      transition Integration::CiFailed => "red", from: "ci_running"
+
+      # A newer landing on main carries this one: the run stops, and the newer run integrates both.
+      transition Integration::IntegrationSuperseded => "superseded", from: %w[verifying boarding]
+
+      transition Integration::MainVerificationFailed => "needs_human", from: "verifying"
+      transition Integration::MainPushRefused => "needs_human", from: "boarding"
+    end
+
+    # One step of integrating main, or one advance of every open run: what was asked, and how it
+    # ended. A step names the landed commit its run is keyed by, and every event it emits carries
+    # it, so the MainIntegration saga hears each one. Each step emits the event that moves the saga
+    # before the one its adapter answers, because policies hear an event before sagas do. The port
+    # adapters do the work: a clean detached copy for a verification, the push train's own copy for
+    # a boarding, and GitHub for the CI run. A boarding refuses by name a range that carries an
+    # agent's trailer, a version change or a release approval, and boards only while no other run is
+    # being pushed or watched.
+    aggregate "Integration" do
+      description "One step of integrating main (verify, board, observe CI) or one advance of the open runs, and how it ended."
+
+      attribute :run,      RunKey
+      attribute :landed,   Word,   optional: true
+      attribute :checkout, Word,   optional: true
+      attribute :confirm,  Switch, optional: true
+      attribute :pushed,   Word,   optional: true
+      attribute :report,   Report, optional: true
+      attribute :refusal,  Report, optional: true
+      identified_by :run
+
+      value_object "RunKey" do
+        attribute :value, String, matches: :present
+      end
+
+      # A commit or a directory.
+      value_object "Word" do
+        attribute :value, String, matches: :present
+      end
+
+      value_object "Report" do
+        attribute :value, String
+      end
+
+      value_object "Switch" do
+        attribute :value, Boolean
+      end
+
+      lifecycle :status, default: "requested" do
+        mark :failure, "failed", "refused", "red"
+        transition "Summarize" => "advanced",   from: "requested"
+        transition "Pass"      => "verified",   from: "requested"
+        transition "Fail"      => "failed",     from: "requested"
+        transition "Send"      => "pushed",     from: "requested"
+        transition "Reject"    => "refused",    from: "requested"
+        transition "Green"     => "passed",     from: "requested"
+        transition "Red"       => "red",        from: "requested"
+        transition "Supersede" => "superseded", from: "requested"
+        mark :terminal, "advanced", "verified", "failed", "pushed", "refused", "passed", "red", "superseded"
+      end
+
+      command "Advance" do
+        role "Operator"
+        goal "Dispatch the next step of every open integration run, once: verify a landed run, board a verified one, observe a pushed one"
+
+        attribute :run,     RunKey, sets: true
+        # Boarding pushes main, so an advance boards only when confirmed; unconfirmed, it says
+        # which boarding it would make.
+        attribute :confirm, Switch, optional: true, sets: true
+
+        emits AdvanceRequested
+      end
+
+      command "Summarize" do
+        role "System"
+        goal "Record what one advance dispatched for each open run"
+
+        reference_to Integration
+        attribute :report, Report, sets: true
+
+        emits IntegrationAdvanced
+      end
+
+      command "Verify" do
+        role "Operator"
+        goal "Verify a landed commit in a clean detached copy of local main: the quick gate, the specs its changes touch, the command names, the CI pipeline and the generated corpus"
+
+        attribute :run,      RunKey, sets: true
+        attribute :landed,   Word, sets: true
+        attribute :checkout, Word, optional: true, sets: true
+
+        emits MainVerificationStarted
+        emits MainVerificationRequested
+      end
+
+      command "Pass" do
+        role "System"
+        goal "Record that a landed commit passed its verification"
+
+        reference_to Integration
+        attribute :landed, Word,   sets: true
+        attribute :report, Report, sets: true
+
+        emits MainVerified
+      end
+
+      command "Fail" do
+        role "System"
+        goal "Record why a landed commit failed its verification, naming the failing checks and files"
+
+        reference_to Integration
+        attribute :landed,  Word,   sets: true
+        attribute :refusal, Report, sets: true
+
+        emits MainVerificationFailed
+      end
+
+      command "Board" do
+        role "Operator"
+        goal "Push a verified commit of main by boarding the push train in its own copy, refusing an agent's trailer, a version change or a release approval"
+
+        attribute :run,      RunKey, sets: true
+        attribute :landed,   Word, sets: true
+        attribute :checkout, Word, optional: true, sets: true
+        attribute :confirm,  Switch, optional: true, sets: true
+
+        given("pushes main to the remote needs --confirm; without it this only reports") { confirm.value == true }
+
+        emits MainBoardingStarted
+        emits MainBoardingRequested
+      end
+
+      command "Send" do
+        role "System"
+        goal "Record the commit the push train pushed, or found already carried"
+
+        reference_to Integration
+        attribute :landed, Word,   sets: true
+        attribute :pushed, Word,   sets: true
+        attribute :report, Report, sets: true
+
+        emits MainPushed
+      end
+
+      command "Reject" do
+        role "System"
+        goal "Record why a verified commit was not pushed"
+
+        reference_to Integration
+        attribute :landed,  Word,   sets: true
+        attribute :refusal, Report, sets: true
+
+        emits MainPushRefused
+      end
+
+      command "Observe" do
+        role "Operator"
+        goal "Read the CI run of a pushed commit on GitHub: passed, failed with the failed jobs, or still running"
+
+        attribute :run,      RunKey, sets: true
+        attribute :landed,   Word, sets: true
+        attribute :checkout, Word, optional: true, sets: true
+
+        emits CiObservationStarted
+        emits CiObservationRequested
+      end
+
+      command "Green" do
+        role "System"
+        goal "Record that CI passed on a pushed commit"
+
+        reference_to Integration
+        attribute :landed, Word,   sets: true
+        attribute :report, Report, sets: true
+
+        emits CiPassed
+      end
+
+      command "Red" do
+        role "System"
+        goal "Record that CI failed on a pushed commit, naming the failed jobs"
+
+        reference_to Integration
+        attribute :landed, Word,   sets: true
+        attribute :report, Report, sets: true
+
+        emits CiFailed
+      end
+
+      command "Supersede" do
+        role "System"
+        goal "Record that a newer commit on main carries a landed one, so its run stops"
+
+        reference_to Integration
+        attribute :landed, Word,   sets: true
+        attribute :report, Report, sets: true
+
+        emits IntegrationSuperseded
+      end
+
+      query "Outcome" do
+        description "How one integration step or advance ended: its report, or why it was refused."
+        attribute :run, RunKey
+        where(run: :run)
+        order_by :run
+      end
+    end
+
+    policy "AdvanceWhenAsked" do
+      on      "Integration.AdvanceRequested"
+      ask     :step, with: { run: :run }
+    end
+
+    policy "RecordTheAdvance" do
+      on      "Integration.AdvanceAnswered"
+      trigger Integration::Summarize, with: { report: :report }
+    end
+
+    policy "RecordTheRefusedAdvance" do
+      on      "Integration.AdvanceRefused"
+      trigger Integration::Summarize, with: { report: :refusal }
+    end
+
+    policy "VerifyMainWhenRequested" do
+      on      "Integration.MainVerificationRequested"
+      ask     :check, with: { run: :run, landed: :landed }
+    end
+
+    policy "RecordTheVerification" do
+      on      "Integration.VerifyAnswered"
+      where   { outcome.value == "verified" }
+      trigger Integration::Pass, with: { landed: :landed, report: :report }
+    end
+
+    policy "RecordTheSupersededVerification" do
+      on      "Integration.VerifyAnswered"
+      where   { outcome.value == "superseded" }
+      trigger Integration::Supersede, with: { landed: :landed, report: :report }
+    end
+
+    policy "RecordTheFailedVerification" do
+      on      "Integration.VerifyRefused"
+      trigger Integration::Fail, with: { landed: :landed, refusal: :refusal }
+    end
+
+    policy "BoardWhenRequested" do
+      on      "Integration.MainBoardingRequested"
+      ask     :embark, with: { run: :run, landed: :landed }
+    end
+
+    policy "RecordTheBoarding" do
+      on      "Integration.BoardAnswered"
+      where   { outcome.value == "pushed" }
+      trigger Integration::Send, with: { landed: :landed, pushed: :pushed, report: :report }
+    end
+
+    policy "RecordTheSupersededBoarding" do
+      on      "Integration.BoardAnswered"
+      where   { outcome.value == "superseded" }
+      trigger Integration::Supersede, with: { landed: :landed, report: :report }
+    end
+
+    policy "RecordTheRefusedBoarding" do
+      on      "Integration.BoardRefused"
+      trigger Integration::Reject, with: { landed: :landed, refusal: :refusal }
+    end
+
+    policy "ObserveWhenRequested" do
+      on      "Integration.CiObservationRequested"
+      ask     :watch, with: { run: :run, landed: :landed }
+    end
+
+    # A CI run still in progress answers `running` and nothing is recorded: the next advance reads
+    # it again.
+    policy "RecordThePassedCi" do
+      on      "Integration.ObserveAnswered"
+      where   { outcome.value == "passed" }
+      trigger Integration::Green, with: { landed: :landed, report: :report }
+    end
+
+    policy "RecordTheFailedCi" do
+      on      "Integration.ObserveAnswered"
+      where   { outcome.value == "failed" }
+      trigger Integration::Red, with: { landed: :landed, report: :report }
+    end
+
     aggregate "ReviewRequest" do
       description "One pull request opened or squash-merged on GitHub, and what GitHub answered."
 

data/lib/hecks/hecks/environments/memory.world

@@ -1,8 +1,13 @@
 # The Memory selection for the Hecks domain: nothing is written to a database. Specs and
 # pull-request runs use it (`HECKS_ENVIRONMENT=memory`); a real run keeps the PostgresEra
 # journal named in hecks.world. The overlay's `default_adapter` wins over the base's.
+#
+# The event tap is off as well: the log hecks.world names feeds the owner's pipeline board, and a
+# spec, a gate or a pull-request run must not show up there. A spec that wants the tap builds its
+# own world naming a temporary path.
 Hecks.world "Hecks" do
   default_adapter "Memory"
+  event_log "None"
 end
 
 Hecks.world "Governance" do

data/lib/hecks/hecks/hecks.contextmap

@@ -20,8 +20,16 @@ Hecks.context_map "Hecks" do
   context "QualityControl"
   context "Coder"
   context "Fixer"
+  context "PipelineBoard"
+  context "Pipeline"
 
   # Deploy's `Tenant` is a validated request; Tenancy's `Tenant` is a fact. Tenancy's hecksagon
   # translates Deploy's `TenantProvisioned` into its own `Register`, so Deploy's model never reaches it.
   relate "Deploy" => "Tenancy", as: :anticorruption_layer
+
+  # QualityControl's hecksagon translates the migrate bluebook's `RehearsalAudited` into its own
+  # `RecordRehearsalVerdict`, so the audit's model stays out of QualityControl's Maintenance.
+  relate "Hecks" => "QualityControl", as: :anticorruption_layer
+  # Hecks attaches QualityControl as well, so the pair also shares a kernel, which has no direction.
+  relate "QualityControl" => "Hecks", as: :shared_kernel
 end