hecks 6.0.0 → 7.0.0

data/lib/hecks/hecks/custodian.bluebook

@@ -1,1300 +0,0 @@
-Hecks.bluebook "Hecks" do
-  # Custodian: operating a domain, in the Operations module (ADR 0096). Each aggregate here is a
-  # concern a client runs against a domain that is running (ADR 0080, section 2); the tooling for
-  # building one is in tooling.bluebook.
-
-  aggregate "Operation" do
-    description "One thing an operator ran against a domain, and how it ended."
-
-    acknowledges :key_by_value, "any address an operator checks, not only the address of a recorded Host",
-                 of: :url
-
-    attribute :run,          OperationKey
-    attribute :subject,      Subject,    optional: true
-    attribute :script,       Script,     optional: true
-    attribute :verb,         Verb,       optional: true
-    attribute :arguments,    list_of(Word), optional: true
-    attribute :url,          Address,    optional: true
-    attribute :path,         RoutePath,  optional: true
-    attribute :header,       HeaderName, optional: true
-    attribute :scheme,       Scheme,     optional: true
-    attribute :payload,      Payload,    optional: true
-    attribute :payload_file, PayloadFile, optional: true
-    attribute :health_path,  RoutePath,  optional: true
-    attribute :state_path,   RoutePath,  optional: true
-    attribute :email,        Email,      optional: true
-    attribute :name,         PersonName, optional: true
-    attribute :role,         RoleName,   optional: true
-    attribute :claimed,      Switch,     optional: true
-    attribute :row,          RowId,      optional: true
-    attribute :output,       Output,     optional: true
-    attribute :refusal,      Output,     optional: true
-    identified_by :run
-
-    value_object "Switch" do
-      attribute :value, Boolean
-    end
-
-    # The delivery id an outbox row carries, as the stalled-row warning at boot names it.
-    value_object "RowId" do
-      attribute :value, String, matches: :present
-    end
-
-    value_object "OperationKey" do
-      attribute :value, String, matches: :present
-
-      invariant("an operation is named") { !value.to_s.empty? }
-    end
-
-    # What the operation acts on: a domain directory, or a behaviors file or directory.
-    value_object "Subject" do
-      attribute :value, String, matches: :not_empty
-    end
-
-    value_object "Script" do
-      attribute :value, String
-    end
-
-    value_object "Verb" do
-      attribute :value, String, matches: :present
-    end
-
-    # One `name=value` word of the verb a run dispatches.
-    value_object "Word" do
-      attribute :value, String
-    end
-
-    value_object "Address" do
-      attribute :value, String, matches: :http_scheme
-    end
-
-    value_object "RoutePath" do
-      attribute :value, String, pattern: '^/'
-    end
-
-    value_object "HeaderName" do
-      attribute :value, String, matches: :present
-    end
-
-    value_object "Scheme" do
-      attribute :value, String, pattern: '^(timestamped|sha256|hex)$'
-    end
-
-    value_object "Payload" do
-      attribute :value, String
-    end
-
-    value_object "PayloadFile" do
-      attribute :value, String, matches: :not_empty
-    end
-
-    value_object "Output" do
-      attribute :value, String
-    end
-
-    # Who the first administrator is: a person of the domain's membership bluebook.
-    value_object "Email" do
-      attribute :value, String, pattern: '^[^ \t\n\r@]+@[^ \t\n\r@]+$'
-    end
-
-    value_object "PersonName" do
-      attribute :value, String, matches: :not_empty
-    end
-
-    value_object "RoleName" do
-      attribute :value, String, matches: :no_whitespace
-    end
-
-    lifecycle :status, default: "requested" do
-      mark :failure, "failed"
-      transition "Succeed" => "succeeded", from: "requested"
-      transition "Fail"    => "failed",    from: "requested"
-      mark :terminal, "failed", "succeeded"
-    end
-
-    # Runs one verb, or a JSON step list, against the domain: `hecks run [domain] script=steps.json`
-    # or `hecks run [domain] verb=create_pizza arguments=name.value=Margherita`. The signing secret
-    # for SmokeHttp is never an argument: it is read from SMOKE_WEBHOOK_SECRET.
-    command "Run" do
-      role "Operator"
-      goal "Dispatch a verb or a step list against a domain and keep what it reported"
-
-      attribute :run,     OperationKey, sets: true
-      attribute :subject, Subject,       optional: true, sets: true
-      attribute :script,  Script,        optional: true, sets: true
-      attribute :verb,    Verb,          optional: true, sets: true
-      attribute :arguments, list_of(Word), optional: true, sets: true
-
-      given("exactly one of a script and a verb is named: pass script= or verb=, not both") do
-        (script.set? && verb.unset?) || (script.unset? && verb.set?)
-      end
-
-
-      emits RunRequested
-    end
-
-    command "RefreshProjections" do
-      role "Operator"
-      goal "Bring every read-model projection of a domain up to date now"
-
-      attribute :run,     OperationKey, sets: true
-      attribute :subject, Subject, sets: true
-
-
-      emits ProjectionsRefreshRequested
-    end
-
-    # Redelivers what a domain's outbox left behind. A row never claimed is always safe to redeliver. A
-    # row claimed before a crash and never settled may or may not have run its effect, so it is only
-    # named (on stderr, as at boot) unless `claimed.value=true` says the effect is known not to have run,
-    # for every claimed row, or `row.value=<delivery id>` says it for that one row alone.
-    command "RedriveOutbox" do
-      role "Operator"
-      goal "Redeliver the reactions a domain's outbox left undelivered, and name the claimed ones that stalled"
-
-      attribute :run,     OperationKey, sets: true
-      attribute :subject, Subject, sets: true
-      attribute :claimed, Switch, optional: true, sets: true
-      attribute :row,     RowId,  optional: true, sets: true
-
-      given("one claimed row is named, or all of them are: pass row= or claimed=, not both") do
-        row.unset? || claimed.unset?
-      end
-
-
-      emits OutboxRedriveRequested
-    end
-
-    # Settles one stalled claimed row as failed without running its effect, for a row whose effect is
-    # known to have landed or that nobody wants run. It never redelivers; `RedriveOutbox` does that.
-    command "AbandonOutboxRow" do
-      role "Operator"
-      goal "Settle one stalled outbox row as failed, naming it by its delivery id, without running it"
-
-      attribute :run,     OperationKey
-      attribute :subject, Subject
-      attribute :row,     RowId
-
-      sets :run
-      sets :subject
-      sets :row
-
-      emits OutboxRowAbandonRequested
-    end
-
-    command "RunBehaviors" do
-      role "Operator"
-      goal "Run a domain's behavior tests and keep the verdict"
-
-      attribute :run,     OperationKey, sets: true
-      attribute :subject, Subject, sets: true
-
-
-      emits BehaviorsRequested
-    end
-
-    command "OpenConsole" do
-      role "Operator"
-      goal "Open an interactive console on a domain"
-
-      attribute :run,     OperationKey, sets: true
-      attribute :subject, Subject, optional: true, sets: true
-
-
-      emits ConsoleRequested
-    end
-
-    command "SmokeTest" do
-      role "Operator"
-      goal "Dispatch one synthesized call per command and report of a wired domain"
-
-      attribute :run,     OperationKey, sets: true
-      attribute :subject, Subject, optional: true, sets: true
-
-
-      emits SmokeTestRequested
-    end
-
-    command "SmokeHttp" do
-      role "Operator"
-      goal "Check that a running service refuses bad signatures and accepts a good one"
-
-      attribute :run,          OperationKey, sets: true
-      attribute :url,          Address,     optional: true, sets: true
-      attribute :path,         RoutePath, sets: true
-      attribute :header,       HeaderName,  optional: true, sets: true
-      attribute :scheme,       Scheme,      optional: true, sets: true
-      attribute :payload,      Payload,     optional: true, sets: true
-      attribute :payload_file, PayloadFile, optional: true, sets: true
-      attribute :health_path,  RoutePath,   optional: true, sets: true
-      attribute :state_path,   RoutePath,   optional: true, sets: true
-
-
-      emits SmokeHttpRequested
-    end
-
-    # `hecks operation.bootstrap_admin <domain> email=<email> [name=<name>] [role=<role>]`. A
-    # domain whose bluebook `provides "membership"` has nobody who may grant access until someone is
-    # granted it. This admits the person and grants them the role the grant command is gated to
-    # (or `role`), as a caller that names that role and binds no `actor_id`: Governance checks that
-    # caller by the role it states, which is how the first grant gets made (ADR 0025). It is
-    # refused once anyone holds the administrator role (`Admin`, or `Owner`), and the domain's
-    # persistence must be the one the service runs on (`DATABASE_URL`), not Memory.
-    command "BootstrapAdmin" do
-      role "Operator"
-      goal "Admit the first administrator of a domain's membership bluebook and grant them access"
-
-      attribute :run,     OperationKey, sets: true
-      attribute :subject, Subject, sets: true
-      attribute :email,   Email, sets: true
-      attribute :name,    PersonName, optional: true, sets: true
-      attribute :role,    RoleName,   optional: true, sets: true
-
-
-      emits AdminBootstrapRequested
-    end
-
-    command "Succeed" do
-      role "System"
-      goal "Record that the operation ended well, and what it reported"
-
-      reference_to Operation
-      attribute :output, Output, sets: true
-
-
-      emits OperationSucceeded
-    end
-
-    command "Fail" do
-      role "System"
-      goal "Record that the operation was refused or found a problem, and what it said"
-
-      reference_to Operation
-      attribute :refusal, Output, sets: true
-
-
-      emits OperationFailed
-    end
-
-    query "Outcome" do
-      description "How one operation ended: its status, and what it reported or why it failed."
-      attribute :run, OperationKey
-      where(run: :run)
-      order_by :run
-    end
-
-    query "Failed" do
-      description "Every operation that was refused or found a problem."
-      where(status: "failed")
-      order_by :run
-    end
-
-    # A follow's answer: the count to pass back as `since`, the entries past it, and when it looked.
-    value_object "Tail" do
-      attribute :cursor,   Integer
-      attribute :events,   list_of(FollowedEvent)
-      attribute :taken_at, String
-    end
-
-    # One entry of a persisted event log; the payload is its JSON text, since a value object
-    # holds no free-form map.
-    value_object "FollowedEvent" do
-      attribute :name,        String
-      attribute :aggregate,   String
-      attribute :id,          String
-      attribute :payload,     String
-      attribute :occurred_at, String
-    end
-
-    # A launcher answers once, so a follow is a bounded poll: it answers the entries past `since`
-    # and a `cursor` to pass as the next `since`, waiting up to `wait` seconds for the first one.
-    # `hecks follow <domain> --stream` asks again from each cursor and prints every entry as it
-    # arrives, until interrupted (the world's `launcher` setting lists the question under `streams`).
-    query "Follow" do
-      description "A domain's persisted event log past a cursor, for tailing it call by call."
-      attribute :domain,    Subject
-      attribute :aggregate, Verb,    optional: true
-      attribute :since,     Integer, optional: true
-      attribute :from_now,  Boolean, optional: true
-      attribute :wait,      Integer, optional: true
-      attribute :interval,  Float,   optional: true
-      returns Tail
-    end
-  end
-
-  policy "RunWhenRequested" do
-    on      "Operation.RunRequested"
-    ask     :execute, with: { run: :run }
-  end
-
-  policy "RefreshWhenRequested" do
-    on      "Operation.ProjectionsRefreshRequested"
-    ask     :refresh, with: { run: :run }
-  end
-
-  policy "RedriveWhenRequested" do
-    on      "Operation.OutboxRedriveRequested"
-    ask     :redrive, with: { run: :run }
-  end
-
-  policy "AbandonWhenRequested" do
-    on      "Operation.OutboxRowAbandonRequested"
-    ask     :abandon, with: { run: :run }
-  end
-
-  policy "VerifyWhenRequested" do
-    on      "Operation.BehaviorsRequested"
-    ask     :verify, with: { run: :run }
-  end
-
-  policy "SmokeWhenRequested" do
-    on      "Operation.SmokeTestRequested"
-    ask     :smoke, with: { run: :run }
-  end
-
-  policy "BootstrapWhenRequested" do
-    on      "Operation.AdminBootstrapRequested"
-    ask     :bootstrap, with: { run: :run }
-  end
-
-  policy "OpenWhenRequested" do
-    on      "Operation.ConsoleRequested"
-    ask     :open, with: { run: :run }
-  end
-
-  policy "ProbeWhenRequested" do
-    on      "Operation.SmokeHttpRequested"
-    ask     :probe, with: { run: :run }
-  end
-
-  policy "RecordTheOutput" do
-    on      "Operation.OperationAnswered"
-    trigger Operation::Succeed, with: { output: :output }
-  end
-
-  policy "RecordTheFailure" do
-    on      "Operation.OperationRefused"
-    trigger Operation::Fail, with: { refusal: :refusal }
-  end
-
-  aggregate "Host" do
-    description "A running rust/host, and the version and era it last reported."
-
-    attribute :host,     Address
-    attribute :expected, ExpectedFile,  optional: true
-    attribute :timeout,  Seconds,       optional: true
-    attribute :era,      EraId,         optional: true
-    attribute :version,  VersionText,   optional: true
-    attribute :report,   Report,        optional: true
-    attribute :refusal,  Report,        optional: true
-    identified_by :host
-
-    value_object "Address" do
-      attribute :value, String, matches: :http_scheme
-    end
-
-    # The file listing the eras that should be running, one per line.
-    value_object "ExpectedFile" do
-      attribute :value, String, matches: :not_empty
-    end
-
-    value_object "Seconds" do
-      attribute :value, Float
-
-      invariant("a timeout is positive") { value > 0 }
-    end
-
-    value_object "EraId" do
-      attribute :value, String, matches: :present
-    end
-
-    value_object "VersionText" do
-      attribute :value, String
-    end
-
-    value_object "Verdict" do
-      attribute :value, String, pattern: '^(match|unlisted|mismatch)$'
-    end
-
-    value_object "Report" do
-      attribute :value, String
-    end
-
-    lifecycle :status, default: "requested" do
-      mark :failure, "drifted", "unreachable"
-      transition "Recheck" => "requested",   from: %w[observed drifted unreachable]
-      transition "Observe" => "observed",    from: "requested"
-      transition "Drift"   => "drifted",     from: "requested"
-      transition "Lose"    => "unreachable", from: "requested"
-    end
-
-# `hecks check_era <url> expected=era-file [timeout=]` records the first check of a host under
-# its URL. A host is one record, and a creating command cannot repeat an identity, so a later
-# check of the same host is `hecks recheck <url> expected=era-file`. Both are read with
-# `hecks standing <url>`.
-command "CheckEra" do
-      role "Operator"
-      goal "Ask a running host which era it reports, and keep whether it is one that should be running"
-
-      attribute :host,     Address, sets: true
-      attribute :expected, ExpectedFile
-      attribute :timeout,  Seconds, default: 10
-
-      sets :expected
-      sets :timeout
-
-      emits EraCheckRequested
-    end
-
-command "Recheck" do
-  role "Operator"
-  goal "Ask a host already checked which era it reports now"
-
-  reference_to Host
-  attribute :expected, ExpectedFile
-  attribute :timeout,  Seconds, default: 10
-
-  sets :expected
-  sets :timeout
-
-  emits EraRecheckRequested
-end
-
-# The host reported an era the list accepts, or a list that names none.
-    command "Observe" do
-      role "System"
-      goal "Record the version and era a running host reported"
-
-      reference_to Host
-      attribute :era,     EraId, sets: true
-      attribute :version, VersionText, sets: true
-      attribute :report,  Report, sets: true
-
-
-      emits EraObserved
-    end
-
-    # The host reported an era that is not on the list: the finding the roll must stop on.
-    command "Drift" do
-      role "System"
-      goal "Record that a running host reports an era that should not be running"
-
-      reference_to Host
-      attribute :era,     EraId, sets: true
-      attribute :version, VersionText, sets: true
-      attribute :report,  Report, sets: true
-
-
-      emits EraDrifted
-    end
-
-    command "Lose" do
-      role "System"
-      goal "Record that the host could not be reached, or answered no era, and what was said"
-
-      reference_to Host
-      attribute :refusal, Report, sets: true
-
-
-      emits HostLost
-    end
-
-    query "Standing" do
-      description "What one check of a host found: its status, era and version, or why it failed."
-      attribute :host, Address
-      where(host: :host)
-      order_by :host
-    end
-
-    query "Drifted" do
-      description "Every host that reported an era that should not be running."
-      where(status: "drifted")
-      order_by :host
-    end
-  end
-
-  policy "FetchWhenChecked" do
-    on      "Host.EraCheckRequested"
-    ask     :fetch, with: { host: :host }
-  end
-
-policy "FetchWhenRechecked" do
-  on      "Host.EraRecheckRequested"
-  ask     :fetch, with: { host: :host }
-end
-
-policy "RecordTheEra" do
-    on      "Host.EraReported"
-    where   { verdict.value != "mismatch" }
-    trigger Host::Observe, with: { era: :era, version: :version, report: :report }
-  end
-
-  policy "RecordTheDrift" do
-    on      "Host.EraReported"
-    where   { verdict.value == "mismatch" }
-    trigger Host::Drift, with: { era: :era, version: :version, report: :report }
-  end
-
-  policy "RecordTheLostHost" do
-    on      "Host.HostRefused"
-    trigger Host::Lose, with: { refusal: :refusal }
-  end
-
-  # Many agents finish together and each would push, running every pre-push check at once. A
-  # boarding waits its turn behind the push in flight from the same repository, then pushes the
-  # local branch with whatever else has landed on it, or finds an earlier push already carried it.
-  aggregate "PushTrain" do
-    description "One push of a checkout's branch, taken in turn: carried by an earlier push, pushed, or refused."
-
-    attribute :run,      RunKey
-    attribute :branch,   Word,   optional: true
-    attribute :remote,   Word,   optional: true
-    attribute :checkout, Word,   optional: true
-    attribute :full_gate, Switch, optional: true
-    attribute :boarded,  Word,   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 branch, a remote, a directory or a commit.
-    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, "faulted"
-      transition "Push"  => "pushed",  from: "requested"
-      transition "Ride"  => "carried", from: "requested"
-      transition "Fault" => "faulted", from: "requested"
-      transition "Summarize" => "surveyed", from: "requested"
-      mark :terminal, "carried", "faulted", "pushed", "surveyed"
-    end
-
-    command "Board" do
-      role "Operator"
-      goal "Push this checkout's branch once the push ahead of it lands, unless that push already carried it"
-
-      attribute :run,       RunKey, sets: true
-      attribute :branch,    Word, default: "main", sets: true
-      attribute :remote,    Word, default: "origin", sets: true
-      attribute :checkout,  Word, optional: true, sets: true
-      # Run the whole `pre_push` stage, the suite included, which also writes the CI attestation
-      # note; without it the push runs only the `unguarded_push` stage.
-      attribute :full_gate, Switch, optional: true, sets: true
-
-
-      emits BoardingRequested
-    end
-
-    # A survey pushes nothing: it lists every checkout under a directory (`checkout`) whose branch
-    # has commits its remote does not, so what waits to board is known before anything boards.
-    command "Survey" do
-      role "Operator"
-      goal "List every checkout under a directory whose branch has commits its remote does not"
-
-      attribute :run,      RunKey, sets: true
-      attribute :remote,   Word, default: "origin", sets: true
-      attribute :checkout, Word, optional: true, sets: true
-
-
-      emits SurveyRequested
-    end
-
-    command "Summarize" do
-      role "System"
-      goal "Record what a survey found waiting to push"
-
-      reference_to PushTrain
-      attribute :report, Report, sets: true
-
-
-      emits CheckoutsSurveyed
-    end
-
-    # The branch was pushed: every commit on it reached the remote, what this boarding carried and
-    # whatever landed on it while it waited.
-    command "Push" do
-      role "System"
-      goal "Record the commit a boarding pushed"
-
-      reference_to PushTrain
-      attribute :checkout, Word, sets: true
-      attribute :boarded,  Word, sets: true
-      attribute :pushed,   Word, sets: true
-      attribute :report,   Report, sets: true
-
-
-      emits BranchPushed
-    end
-
-    # An earlier push already took the boarded commit to the remote, so this one pushed nothing.
-    command "Ride" do
-      role "System"
-      goal "Record that an earlier push already carried the boarded commit"
-
-      reference_to PushTrain
-      attribute :checkout, Word, sets: true
-      attribute :boarded,  Word, sets: true
-      attribute :report,   Report, sets: true
-
-
-      emits CarriedByEarlierPush
-    end
-
-    command "Fault" do
-      role "System"
-      goal "Record why a boarding could not push"
-
-      reference_to PushTrain
-      attribute :refusal, Report, sets: true
-
-
-      emits PushFaulted
-    end
-
-    query "Outcome" do
-      description "How one boarding ended: pushed, carried by an earlier push, or why it failed."
-      attribute :run, RunKey
-      where(run: :run)
-      order_by :run
-    end
-  end
-
-  policy "CarryWhenBoarded" do
-    on      "PushTrain.BoardingRequested"
-    ask     :carry, with: { run: :run }
-  end
-
-  policy "RecordThePush" do
-    on      "PushTrain.TrainAnswered"
-    where   { outcome.value == "pushed" }
-    trigger PushTrain::Push, with: { checkout: :checkout, boarded: :boarded, pushed: :pushed, report: :report }
-  end
-
-  policy "RecordTheRide" do
-    on      "PushTrain.TrainAnswered"
-    where   { outcome.value == "carried" }
-    trigger PushTrain::Ride, with: { checkout: :checkout, boarded: :boarded, report: :report }
-  end
-
-  policy "RecordTheRefusedPush" do
-    on      "PushTrain.TrainRefused"
-    trigger PushTrain::Fault, with: { refusal: :refusal }
-  end
-
-  policy "SurveyWhenAsked" do
-    on      "PushTrain.SurveyRequested"
-    ask     :tally, with: { run: :run }
-  end
-
-  policy "RecordTheSurvey" do
-    on      "PushTrain.SurveyAnswered"
-    trigger PushTrain::Summarize, with: { report: :report }
-  end
-
-  policy "RecordTheRefusedSurvey" do
-    on      "PushTrain.SurveyRefused"
-    trigger PushTrain::Fault, with: { refusal: :refusal }
-  end
-
-  # Deploys stay by hand: a push that reached the remote says a deploy is ready, and nothing more.
-  policy "AnnounceWhenPushed" do
-    on      "PushTrain.BranchPushed"
-    ask     :announce, with: { run: :run }
-  end
-
-  # A checkout's state, read and never written: nothing needs a raw `git status`, `git diff` or
-  # `git log`. The `Reading` port's adapter answers each query; the aggregate keeps no record.
-  aggregate "Checkout" do
-    description "A look at a checkout: its branch, what it changed and what it committed."
-
-    attribute :checkout, Place
-    identified_by :checkout
-
-    # A directory inside the repository; the current directory when a query names none.
-    value_object "Place" do
-      attribute :value, String, matches: :present
-    end
-
-    value_object "Word" do
-      attribute :value, String, matches: :present
-    end
-
-    value_object "Document" do
-      attribute :text, String
-    end
-
-    query "Status" do
-      description "The checkout's branch, whether it is a linked worktree, where it stands against main and origin/main, and what is changed or untracked."
-      attribute :checkout, Place, optional: true
-      returns Document
-    end
-
-    query "Changes" do
-      description "What the checkout changed since a ref (main by default): the diffstat, or the paths alone."
-      attribute :checkout,   Place,   optional: true
-      attribute :since,      Word,    optional: true
-      attribute :names_only, Boolean, optional: true
-      returns Document
-    end
-
-    query "Log" do
-      description "The commits in a range, newest first (the last 20 when none is named)."
-      attribute :checkout, Place, optional: true
-      attribute :range,    Word,  optional: true
-      returns Document
-    end
-
-    query "Settings" do
-      description "What this copy resolves for each setting that can come from a variable, its own world or a default, and which one supplied it."
-      attribute :domain, Place, optional: true
-      returns Document
-    end
-  end
-
-  # Agents merge straight to local main and clean up what they merged. A landing merges a worktree's
-  # branch onto main, fast-forward first and as a merge commit when main moved; a conflict is
-  # reported and never settled, and nothing is forced or pushed. A retirement removes the worktree
-  # and its branch once the branch is on main, and refuses while it holds uncommitted work or
-  # commits main lacks, so no unpushed work is deleted.
-  aggregate "Landing" do
-    description "One branch landed on local main, or one worktree retired: done, or refused with the reason."
-
-    attribute :run,      RunKey
-    attribute :checkout, Word,   optional: true
-    attribute :branch,   Word,   optional: true
-    attribute :onto,     Word,   optional: true
-    attribute :landed,   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 branch, a directory or a commit.
-    value_object "Word" do
-      attribute :value, String, matches: :present
-    end
-
-    value_object "Report" do
-      attribute :value, String
-    end
-
-    value_object "Document" do
-      attribute :text, String
-    end
-
-    lifecycle :status, default: "requested" do
-      mark :failure, "refused"
-      transition "Record"  => "landed",  from: "requested"
-      transition "Clear"   => "retired", from: "requested"
-      transition "Refuse"  => "refused", from: "requested"
-      transition "Decline" => "refused", from: "requested"
-      mark :terminal, "landed", "refused", "retired"
-    end
-
-    command "Land" do
-      role "Operator"
-      goal "Merge a worktree's branch onto local main: fast-forward when it can be, a merge commit when main moved, never forced, never pushed"
-
-      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
-
-
-      emits LandingRequested
-    end
-
-    command "Record" do
-      role "System"
-      goal "Record the commit main names once the branch is on it"
-
-      reference_to Landing
-      attribute :branch, Word, sets: true
-      attribute :landed, Word, sets: true
-      attribute :report, Report, sets: true
-
-
-      emits BranchLanded
-    end
-
-    command "Refuse" do
-      role "System"
-      goal "Record why a branch could not be landed"
-
-      reference_to Landing
-      attribute :refusal, Report, sets: true
-
-
-      emits LandingRefused
-    end
-
-    command "Retire" do
-      role "Operator"
-      goal "Remove a merged worktree and delete its branch, unless it holds uncommitted work or commits main lacks"
-
-      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
-
-
-      emits RetirementRequested
-    end
-
-    command "Clear" do
-      role "System"
-      goal "Record that the worktree and its branch are gone"
-
-      reference_to Landing
-      attribute :branch, Word, sets: true
-      attribute :report, Report, sets: true
-
-
-      emits WorktreeRetired
-    end
-
-    command "Decline" do
-      role "System"
-      goal "Record why a worktree was kept"
-
-      reference_to Landing
-      attribute :refusal, Report, sets: true
-
-
-      emits RetirementDeclined
-    end
-
-    query "Outcome" do
-      description "How one landing or retirement ended: the commit main names, or why it was refused."
-      attribute :run, RunKey
-      where(run: :run)
-      order_by :run
-    end
-
-    query "Unlanded" do
-      description "Every branch with commits that are not on main, or with uncommitted work, and where its worktree is."
-      attribute :checkout, Word, optional: true
-      attribute :onto,     Word, optional: true
-      returns Document
-    end
-  end
-
-  policy "MergeWhenLanding" do
-    on      "Landing.LandingRequested"
-    ask     :merge, with: { run: :run }
-  end
-
-  policy "RecordTheLanding" do
-    on      "Landing.MergeAnswered"
-    trigger Landing::Record, with: { branch: :branch, landed: :landed, report: :report }
-  end
-
-  policy "RecordTheRefusedLanding" do
-    on      "Landing.MergeRefused"
-    trigger Landing::Refuse, with: { refusal: :refusal }
-  end
-
-  policy "RemoveWhenRetiring" do
-    on      "Landing.RetirementRequested"
-    ask     :remove, with: { run: :run }
-  end
-
-  policy "RecordTheRetirement" do
-    on      "Landing.RemovalAnswered"
-    trigger Landing::Clear, with: { branch: :branch, report: :report }
-  end
-
-  policy "RecordTheKeptWorktree" do
-    on      "Landing.RemovalRefused"
-    trigger Landing::Decline, with: { refusal: :refusal }
-  end
-
-  # The copy of Hecks that runs the train follows what it pushed, so the next boarding and the
-  # records it keeps run the code that landed, not the code that was there when it was set up.
-  policy "KeepTheLauncherCurrent" do
-    on      "PushTrain.BranchPushed"
-    ask     :refresh, with: { run: :run }
-  end
-
-  aggregate "Era" do
-    description "One change to a domain's journal of eras, and how it ended: a store's upkeep."
-
-    acknowledges :key_by_value, "the domain's path, and Introspection declares queries only, so it holds no records and a reference would be refused on every write",
-                 of: :domain
-
-    attribute :run,                 RunKey
-    attribute :domain,              DomainPath
-    attribute :operation,           OperationName, optional: true
-    attribute :winners,             WinnerList,    optional: true
-    attribute :era,                 Ordinal,       optional: true
-    attribute :aggregates,          AggregateList, optional: true
-    attribute :confirm,             Switch,        optional: true
-    attribute :capable,             Switch,        optional: true
-    attribute :held,                Count,         optional: true
-    attribute :forks,               Count,         optional: true
-    attribute :contested,           Count,         optional: true
-    attribute :bound,               Count,         optional: true
-    attribute :candidates,          Count,         optional: true
-    attribute :drifted,             Switch,        optional: true
-    attribute :loadable,            Switch,        optional: true
-    attribute :shape_kept,          Switch,        optional: true
-    attribute :report,              Report,        optional: true
-    attribute :refusal,             Report,        optional: true
-    identified_by :run
-
-    value_object "RunKey" do
-      attribute :value, String, matches: :present
-
-      invariant("a change is named") { !value.to_s.empty? }
-    end
-
-    # The domain whose journal is changed: its directory.
-    value_object "DomainPath" do
-      attribute :value, String, matches: :not_empty
-    end
-
-    value_object "OperationName" do
-      attribute :value, String,
-                pattern: '^(hold_first|merge_tail|reattest|backfill_projections|compact|compact_heki)$'
-    end
-
-    # `id:old,id:new`: which world's record wins for each id both worlds touched since the cut.
-    value_object "WinnerList" do
-      attribute :value, String, pattern: '^[^ \t\n\r,]+:(old|new)(,[^ \t\n\r,]+:(old|new))*$'
-    end
-
-    value_object "Ordinal" do
-      attribute :value, Integer
-
-      invariant("an era is counted from one") { value > 0 }
-    end
-
-    # Aggregate names, comma separated; every aggregate that keeps a journal when absent.
-    value_object "AggregateList" do
-      attribute :value, String, matches: :not_empty
-    end
-
-    value_object "Switch" do
-      attribute :value, Boolean
-    end
-
-    value_object "Count" do
-      attribute :value, Integer
-    end
-
-    value_object "Report" do
-      attribute :value, String
-    end
-
-    lifecycle :status, default: "requested" do
-      mark :failure, "refused"
-      transition "Permit"   => "admitted", from: "requested"
-      transition "Settle"   => "settled",  from: "admitted"
-      transition "Abandon"  => "refused",  from: %w[requested admitted]
-      mark :terminal, "refused", "settled"
-    end
-
-    # The seven requests. Each records what was asked and names its operation; the journal store
-    # then examines the domain and reports facts (`EraExamined`), `Permit` holds the rules that need
-    # those facts, and only an admitted change is made (`EraChanged`). A change that changes
-    # something needs an explicit `--confirm`.
-    command "HoldFirst" do
-      role "Operator"
-      goal "Hold the first era of a domain that holds none, as its first boot would"
-
-      attribute :domain,  DomainPath, sets: true
-      attribute :run,     RunKey, sets: true
-      attribute :confirm, Switch, optional: true, sets: true
-
-      given("holding the first era is confirmed") { confirm.value == true }
-
-      sets :operation, to: "hold_first"
-
-      emits FirstEraRequested
-    end
-
-    command "MergeTail" do
-      role "Operator"
-      goal "Interleave the old world's writes since the cut into the live head, by their ordinals"
-
-      attribute :domain,  DomainPath, sets: true
-      attribute :run,     RunKey, sets: true
-      attribute :winners, WinnerList, optional: true, sets: true
-      attribute :confirm, Switch,     optional: true, sets: true
-
-      given("the merge is confirmed") { confirm.value == true }
-
-      sets :operation, to: "merge_tail"
-
-      emits TailMergeRequested
-    end
-
-    command "Reattest" do
-      role "Operator"
-      goal "Freeze an era's held text as it now stands, after a person has read it"
-
-      attribute :domain,  DomainPath, sets: true
-      attribute :era,     Ordinal, sets: true
-      attribute :run,     RunKey, sets: true
-      attribute :confirm, Switch, optional: true, sets: true
-
-      given("the text is accepted as the era's own") { confirm.value == true }
-
-      sets :operation, to: "reattest"
-
-      emits ReattestRequested
-    end
-
-    command "BackfillProjections" do
-      role "Operator"
-      goal "Store the shape every held era froze with, for the eras that predate it"
-
-      attribute :domain, DomainPath, sets: true
-      attribute :run,    RunKey, sets: true
-
-      sets :operation, to: "backfill_projections"
-
-      emits BackfillRequested
-    end
-
-    command "Compact" do
-      role "Operator"
-      goal "Delete the journal entries a Postgres or Sqlite aggregate has already projected"
-
-      attribute :domain,     DomainPath, sets: true
-      attribute :aggregates, AggregateList, optional: true, sets: true
-      attribute :run,        RunKey, sets: true
-      attribute :confirm,    Switch, optional: true, sets: true
-
-      given("the compaction is confirmed") { confirm.value == true }
-
-      sets :operation, to: "compact"
-
-      emits CompactionRequested
-    end
-
-    command "CompactHeki" do
-      role "Operator"
-      goal "Empty a Heki aggregate's journal, keeping the snapshot"
-
-      attribute :domain,     DomainPath, sets: true
-      attribute :aggregates, AggregateList, optional: true, sets: true
-      attribute :run,        RunKey, sets: true
-      attribute :confirm,    Switch, optional: true, sets: true
-
-      given("the compaction is confirmed") { confirm.value == true }
-
-      sets :operation, to: "compact_heki"
-
-      emits HekiCompactionRequested
-    end
-
-    # The facts the journal store reported, held against the change that was asked for.
-    command "Permit" do
-      role "System"
-      goal "Let a change through only when what was found in the journal allows it"
-
-      reference_to Era
-      attribute :capable,            Switch, sets: true
-      attribute :held,               Count, sets: true
-      attribute :forks,              Count, sets: true
-      attribute :contested,          Count, sets: true
-      attribute :bound,              Count, sets: true
-      attribute :candidates,         Count, sets: true
-      attribute :drifted,            Switch, sets: true
-      attribute :loadable,           Switch, sets: true
-      attribute :shape_kept,         Switch, sets: true
-      attribute :operation,          OperationName, sets: true
-
-      given("the store keeps eras") do
-        capable.value || operation.value == "compact" || operation.value == "compact_heki"
-      end
-      given("no era is held yet") { operation.value != "hold_first" || held.value == 0 }
-      given("an era beyond the first stands before a tail is merged") do
-        operation.value != "merge_tail" || held.value > 1
-      end
-      given("exactly one edge leaves each era") { operation.value != "merge_tail" || forks.value == 0 }
-      given("every record both worlds touched has a named winner") do
-        operation.value != "merge_tail" || contested.value == 0
-      end
-      given("an aggregate matches") do
-        (operation.value != "compact" && operation.value != "compact_heki") || candidates.value > 0
-      end
-      given("no projection reads the journal that would be emptied") do
-        (operation.value != "compact" && operation.value != "compact_heki") || bound.value == 0
-      end
-      given("the held text no longer matches its digest: there is nothing to re-attest") do
-        operation.value != "reattest" || drifted.value
-      end
-      given("the edited text loads as a bluebook: restore a loadable text") do
-        operation.value != "reattest" || loadable.value
-      end
-      given("the edit kept the era's shape, not just its text: restore a text with the original shape") do
-        operation.value != "reattest" || shape_kept.value
-      end
-
-
-      emits EraPermitted
-    end
-
-    command "Settle" do
-      role "System"
-      goal "Record that the admitted change was made, and what it did"
-
-      reference_to Era
-      attribute :report, Report, sets: true
-
-
-      emits EraSettled
-    end
-
-    command "Abandon" do
-      role "System"
-      goal "Record that the change was refused, or could not be made, and why"
-
-      reference_to Era
-      attribute :refusal, Report, sets: true
-
-
-      emits EraAbandoned
-    end
-
-    query "Settlement" do
-      description "What one change did: its status, and the report or the reason it was refused."
-      attribute :run, RunKey
-      where(run: :run)
-      order_by :run
-    end
-
-    query "Abandoned" do
-      description "Every change that was refused or could not be made."
-      where(status: "refused")
-      order_by :run
-    end
-
-    # An answer that is one document of text, exactly as the tool that produced it wrote it.
-    value_object "Document" do
-      attribute :text, String
-    end
-
-    # The reads that used to write. None holds an era or names one: a domain that holds no era
-    # answers "no era held yet", and `hold_first` is the only thing that holds the first.
-    query "ScaffoldTranslation" do
-      description "The edge file that would lead the latest held era to the current shape."
-      attribute :domain, DomainPath
-      returns Document
-    end
-
-    query "AuditTranslation" do
-      description "The audit of the edge that leads the latest held era to the current shape."
-      attribute :domain, DomainPath
-      returns Document
-    end
-
-    query "Attestation" do
-      description "An era's held text as it now stands, and whether it still matches its digest."
-      attribute :domain, DomainPath
-      attribute :era,    Ordinal
-      returns Document
-    end
-
-    query "Compaction" do
-      description "What compacting the domain's journals would delete, without deleting it."
-      attribute :domain,     DomainPath
-      attribute :aggregates, AggregateList, optional: true
-      returns Document
-    end
-  end
-
-  policy "ExamineWhenFirstEraRequested" do
-    on      "Era.FirstEraRequested"
-    ask     :examine, with: { run: :run }
-  end
-
-  policy "ExamineWhenTailMergeRequested" do
-    on      "Era.TailMergeRequested"
-    ask     :examine, with: { run: :run }
-  end
-
-  policy "ExamineWhenReattestRequested" do
-    on      "Era.ReattestRequested"
-    ask     :examine, with: { run: :run }
-  end
-
-  policy "ExamineWhenBackfillRequested" do
-    on      "Era.BackfillRequested"
-    ask     :examine, with: { run: :run }
-  end
-
-  policy "ExamineWhenCompactionRequested" do
-    on      "Era.CompactionRequested"
-    ask     :examine, with: { run: :run }
-  end
-
-  policy "ExamineWhenHekiCompactionRequested" do
-    on      "Era.HekiCompactionRequested"
-    ask     :examine, with: { run: :run }
-  end
-
-  policy "PermitWhenExamined" do
-    on      "Era.EraExamined"
-    trigger Era::Permit, with: {
-      capable: :capable, held: :held, forks: :forks, contested: :contested,
-      bound: :bound, candidates: :candidates,
-      drifted: :drifted, loadable: :loadable, shape_kept: :shape_kept, operation: :operation
-    }
-  end
-
-  # `Permit` refuses when a rule is unmet and emits nothing, so this reaction is its complement:
-  # it holds the same rules negated, so an examined change that is not let through is abandoned
-  # rather than left `requested`.
-  policy "AbandonWhenNotPermitted" do
-    on      "Era.EraExamined"
-    where do
-      (!capable.value && operation.value != "compact" && operation.value != "compact_heki") ||
-        (operation.value == "hold_first" && held.value != 0) ||
-        (operation.value == "merge_tail" && (held.value <= 1 || forks.value != 0 || contested.value != 0)) ||
-        ((operation.value == "compact" || operation.value == "compact_heki") &&
-          (candidates.value <= 0 || bound.value != 0)) ||
-        (operation.value == "reattest" && (!drifted.value || !loadable.value || !shape_kept.value))
-    end
-    trigger Era::Abandon, with: { refusal: "the journal's facts do not admit this change" }
-  end
-
-  # A compaction waits for its seal (ledger.bluebook); every other change is applied at once.
-  policy "ChangeWhenPermitted" do
-    on      "Era.EraPermitted"
-    where do
-      operation.value != "compact" && operation.value != "compact_heki"
-    end
-    ask     :apply, with: { run: :run }
-  end
-
-  policy "RecordTheChange" do
-    on      "Era.EraChanged"
-    trigger Era::Settle, with: { report: :report }
-  end
-
-  policy "RecordTheRefusedChange" do
-    on      "Era.EraRefused"
-    trigger Era::Abandon, with: { refusal: :refusal }
-  end
-
-end