hecks 3.4.1 → 3.5.0

data/lib/hecks/deploy/bluebook/deploy.bluebook

@@ -770,6 +770,1636 @@ Hecks.bluebook "Deploy" do
     trigger CostCheck::Flag, with: { refusal: :refusal }
   end
 
+  aggregate "SmokeRun" do
+    description "One post-deploy smoke: the generated smoke-after-deploy script run, and how it ended."
+
+    attribute :project, Location
+    attribute :script,  Location, optional: true
+    attribute :run,     RunKey
+    attribute :taskdef, TaskDefinition, optional: true
+    attribute :skip,    Switch, optional: true
+    attribute :async,   Switch, optional: true
+    attribute :dry_run, Switch, optional: true
+    attribute :after,   Origin, default: { value: "alone" }
+    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 "Location" do
+      attribute :value, String, pattern: '[^\t\n\r]'
+
+      invariant("a project or script is named by its path") { !value.to_s.empty? }
+    end
+
+    # A task definition family, or family:revision, as the generated script takes it in TASKDEF.
+    value_object "TaskDefinition" do
+      attribute :value, String, pattern: '^[A-Za-z0-9_-]+(:[0-9]+)?$'
+    end
+
+    # What requested the smoke: `alone` for a person, else the roll whose record takes the outcome.
+    value_object "Origin" do
+      attribute :value, String, pattern: '^(alone|service_roll|box_roll)$'
+    end
+
+    value_object "Switch" do
+      attribute :value, Boolean
+    end
+
+    value_object "Report" do
+      attribute :value, String
+    end
+
+    lifecycle :status, default: "requested" do
+      transition "Pass" => "passed", from: "requested"
+      transition "Flag" => "flagged", from: "requested"
+    end
+
+    # `hecks deploy smoke_run.run <project> [script=<path>] [taskdef=<family[:rev]>] [skip=true]
+    # [async=true] [dry_run=true]`. Finds the `smoke-after-deploy.sh` the project's AwsBox projection
+    # generated (`script=` names it when the project holds more than one) and runs it once a roll
+    # has settled: the script waits for the box, dispatches the smoke workflow and follows it.
+    # It only reads AWS; the smoke itself runs on GitHub. Exit 1 when it did not pass, with the
+    # script's own status (20 unsettled, 21 not run, 22 failed, 23 unknown) in the reason.
+    command "Run" do
+      goal "Run a project's generated post-deploy smoke and record whether the live site passed"
+
+      attribute :project, Location
+      attribute :script,  Location, optional: true
+      attribute :run,     RunKey
+      attribute :taskdef, TaskDefinition, optional: true
+      attribute :skip,    Switch, optional: true
+      attribute :async,   Switch, optional: true
+      attribute :dry_run, Switch, optional: true
+      attribute :after,   Origin, default: { value: "alone" }
+
+      sets :project
+      sets :script
+      sets :run
+      sets :taskdef
+      sets :skip
+      sets :async
+      sets :dry_run
+      sets :after
+
+      emits "SmokeRequested"
+    end
+
+    command "Pass" do
+      goal "Record that the smoke passed, was skipped on purpose, or was left running, and what it said"
+
+      reference_to SmokeRun
+      attribute :report, Report
+      attribute :after,  Origin, default: { value: "alone" }
+
+      sets :report
+      sets :after
+
+      emits "SmokePassed"
+    end
+
+    command "Flag" do
+      goal "Record that the smoke failed, did not run or could not be read, and what was said"
+
+      reference_to SmokeRun
+      attribute :refusal, Report
+      attribute :after,   Origin, default: { value: "alone" }
+
+      sets :refusal
+      sets :after
+
+      emits "SmokeFlagged"
+    end
+
+    query "Verdict" do
+      description "What one smoke found: its status, and the report or the reason it was flagged."
+      attribute :run, RunKey
+      where(run: :run)
+      order_by :run
+    end
+
+    query "Flagged" do
+      description "Every smoke that failed, did not run or could not be read."
+      where(status: "flagged")
+      order_by :run
+    end
+  end
+
+  policy "SmokeWhenRequested" do
+    on      "SmokeRun.SmokeRequested"
+    trigger SmokeRun::DeployToolchain::Smoke, with: { run: :run, after: :after }
+  end
+
+  policy "RecordThePassedSmoke" do
+    on      "SmokeRun.SmokeAnswered"
+    trigger SmokeRun::Pass, with: { report: :report, after: :after }
+  end
+
+  policy "RecordTheFlaggedSmoke" do
+    on      "SmokeRun.SmokeRefused"
+    trigger SmokeRun::Flag, with: { refusal: :refusal, after: :after }
+  end
+
+  aggregate "ServiceRoll" do
+    description "One roll of a single service onto the app box: the generated deploy-service script run, and how it ended."
+
+    attribute :project,        Location
+    attribute :script,         Location, optional: true
+    attribute :run,            RunKey
+    attribute :service,        ServiceName
+    attribute :existing_tag,   ImageTag, optional: true
+    attribute :local_image,    ImageName, optional: true
+    attribute :skip_smoke,     Switch, optional: true
+    attribute :taskdef,        TaskDefinition, optional: true
+    attribute :tag,            ImageTag, optional: true
+    attribute :report,         Report, optional: true
+    attribute :smoke,      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 "Location" do
+      attribute :value, String, pattern: '[^\t\n\r]'
+
+      invariant("a project or script is named by its path") { !value.to_s.empty? }
+    end
+
+    # A task definition family, or family:revision, as the generated script takes it in TASKDEF.
+    value_object "TaskDefinition" do
+      attribute :value, String, pattern: '^[A-Za-z0-9_-]+(:[0-9]+)?$'
+    end
+
+    # A container name from the world: lower case words joined by hyphens or underscores.
+    value_object "ServiceName" do
+      attribute :value, String, pattern: '^[a-z0-9][a-z0-9_-]*$'
+    end
+
+    # An ECR image tag, as the script's EXISTING_TAG takes it.
+    value_object "ImageTag" do
+      attribute :value, String, pattern: '^[A-Za-z0-9_][A-Za-z0-9_.-]{0,127}$'
+    end
+
+    # A local image reference to push, as the script's LOCAL_IMAGE takes it.
+    value_object "ImageName" 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
+
+    lifecycle :status, default: "requested" do
+      transition "Complete" => "rolled", from: "requested"
+      transition "Flag" => "flagged", from: "requested"
+      transition "Verify" => "verified", from: "rolled"
+      transition "FlagSmoke" => "flagged", from: "rolled"
+    end
+
+    # `hecks deploy service_roll.run <project> service=<name> [existing_tag=<tag>] [local_image=<ref>]
+    # [skip_smoke=true] [script=<path>]`. Runs the project's generated `deploy-service.sh`: push the
+    # local image under a fresh tag (or reuse `existing_tag`), set the stack's tag parameter, roll
+    # the box. A policy then requests a `SmokeRun`, unless `skip_smoke=true`. Exit 1 when flagged,
+    # with the script's status (2 unknown service, 30 to 38 a refused step, 40 to 42 the box roll's).
+
+    command "Run" do
+      goal "Roll one service's local image onto the box and record whether it took (exit 1 when flagged: 2 unknown service, 30-38 a refused step, 40-42 the box roll)"
+
+      attribute :project,      Location
+      attribute :script,       Location, optional: true
+      attribute :run,          RunKey
+      attribute :service,      ServiceName
+      attribute :existing_tag, ImageTag, optional: true
+      attribute :local_image,  ImageName, optional: true
+      attribute :skip_smoke,   Switch, optional: true
+
+      sets :project
+      sets :script
+      sets :run
+      sets :service
+      sets :existing_tag
+      sets :local_image
+      sets :skip_smoke
+
+      emits "ServiceRollRequested"
+    end
+
+    command "Complete" do
+      goal "Record that the service rolled, with the task definition and tag it rolled"
+
+      reference_to ServiceRoll
+      attribute :report,     Report
+      attribute :taskdef,    TaskDefinition, optional: true
+      attribute :tag,        ImageTag, optional: true
+      attribute :smoke,      Report, optional: true
+
+      sets :report
+      sets :taskdef
+      sets :tag
+      sets :smoke
+
+      emits "ServiceRollCompleted"
+    end
+
+    command "Flag" do
+      goal "Record that the roll failed or could not start, with the script's status and what it said"
+
+      reference_to ServiceRoll
+      attribute :refusal, Report
+
+      sets :refusal
+
+      emits "ServiceRollFlagged"
+    end
+
+    command "Verify" do
+      goal "Record that the smoke the roll requested passed"
+
+      reference_to ServiceRoll
+      attribute :smoke, Report
+
+      sets :smoke
+
+      emits "ServiceRollVerified"
+    end
+
+    command "FlagSmoke" do
+      goal "Record that the roll took but the smoke it requested did not pass, and why"
+
+      reference_to ServiceRoll
+      attribute :smoke,   Report
+      attribute :refusal, Report
+
+      sets :smoke
+      sets :refusal
+
+      emits "ServiceRollSmokeFlagged"
+    end
+
+    query "Verdict" do
+      description "What one roll found: its status, and the report or the reason it was flagged."
+      attribute :run, RunKey
+      where(run: :run)
+      order_by :run
+    end
+
+    query "Flagged" do
+      description "Every roll that failed or could not start."
+      where(status: "flagged")
+      order_by :run
+    end
+  end
+
+  policy "RollServiceWhenRequested" do
+    on      "ServiceRoll.ServiceRollRequested"
+    trigger ServiceRoll::DeployToolchain::RollService, with: { run: :run }
+  end
+
+  policy "RecordTheRolledService" do
+    on      "ServiceRoll.ServiceRollAnswered"
+    trigger ServiceRoll::Complete,
+            with: { report: :report, taskdef: :taskdef, tag: :tag, smoke: :smoke }
+  end
+
+  policy "RecordTheFlaggedServiceRoll" do
+    on      "ServiceRoll.ServiceRollRefused"
+    trigger ServiceRoll::Flag, with: { refusal: :refusal }
+  end
+
+  # Declared after RecordTheRolledService: the roll is recorded before its smoke is requested, and the
+  # smoke is requested from the answer itself because a reaction chain is bounded.
+  policy "SmokeAfterServiceRoll" do
+    on      "ServiceRoll.ServiceRollAnswered"
+    where   { run_smoke.value }
+    trigger SmokeRun::Run, with: { project: :project, run: :run, taskdef: :taskdef, after: :kind }
+  end
+
+  policy "VerifyServiceRollOnPassedSmoke" do
+    on      "SmokeRun.SmokePassed"
+    where   { after.value == "service_roll" }
+    trigger ServiceRoll::Verify, with: { service_roll: :run, smoke: :report }
+  end
+
+  policy "FlagServiceRollOnFlaggedSmoke" do
+    on      "SmokeRun.SmokeFlagged"
+    where   { after.value == "service_roll" }
+    trigger ServiceRoll::FlagSmoke, with: { service_roll: :run, smoke: :refusal, refusal: :refusal }
+  end
+
+  aggregate "BoxRoll" do
+    description "One roll of the whole app box: the generated deploy-box script run, and how it ended."
+
+    attribute :project,    Location
+    attribute :script,     Location, optional: true
+    attribute :run,        RunKey
+    attribute :taskdef,    TaskDefinition, optional: true
+    attribute :tags,       Tags, optional: true
+    attribute :skip_smoke, Switch, optional: true
+    attribute :report,     Report, optional: true
+    attribute :smoke,      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 "Location" do
+      attribute :value, String, pattern: '[^\t\n\r]'
+
+      invariant("a project or script is named by its path") { !value.to_s.empty? }
+    end
+
+    # A task definition family, or family:revision, as the generated script takes it in TASKDEF.
+    value_object "TaskDefinition" do
+      attribute :value, String, pattern: '^[A-Za-z0-9_-]+(:[0-9]+)?$'
+    end
+
+    # `name=tag` pairs separated by spaces, as a project without a task definition names its images.
+    value_object "Tags" do
+      attribute :value, String, pattern: '^[A-Za-z0-9_-]+=[A-Za-z0-9_.-]+( [A-Za-z0-9_-]+=[A-Za-z0-9_.-]+)*$'
+    end
+
+    value_object "Switch" do
+      attribute :value, Boolean
+    end
+
+    value_object "Report" do
+      attribute :value, String
+    end
+
+    lifecycle :status, default: "requested" do
+      transition "Complete" => "rolled", from: "requested"
+      transition "Flag" => "flagged", from: "requested"
+      transition "Verify" => "verified", from: "rolled"
+      transition "FlagSmoke" => "flagged", from: "rolled"
+    end
+
+    # `hecks deploy box_roll.run <project> [taskdef=<family[:rev]> | tags="name=tag ..."]
+    # [skip_smoke=true] [script=<path>]`.
+    # Runs the project's generated `deploy-box.sh`: render the Compose files, push them to the box over
+    # SSM, start the containers and check them. A policy then requests a `SmokeRun`, unless
+    # `skip_smoke=true`. Exit 1 when flagged, with the script's status (40 no instance, 41 the roll
+    # failed, 42 the box unhealthy).
+
+    command "Run" do
+      goal "Roll the app box and record whether it came up healthy (exit 1 when flagged: 40 no instance, 41 roll failed, 42 box unhealthy)"
+
+      attribute :project,    Location
+      attribute :script,     Location, optional: true
+      attribute :run,        RunKey
+      attribute :taskdef,    TaskDefinition, optional: true
+      attribute :tags,       Tags, optional: true
+      attribute :skip_smoke, Switch, optional: true
+
+      sets :project
+      sets :script
+      sets :run
+      sets :taskdef
+      sets :tags
+      sets :skip_smoke
+
+      emits "BoxRollRequested"
+    end
+
+    command "Complete" do
+      goal "Record that the box rolled and answered healthy, and what the script said"
+
+      reference_to BoxRoll
+      attribute :report,     Report
+      attribute :taskdef,    TaskDefinition, optional: true
+      attribute :smoke,      Report, optional: true
+
+      sets :report
+      sets :taskdef
+      sets :smoke
+
+      emits "BoxRollCompleted"
+    end
+
+    command "Flag" do
+      goal "Record that the roll failed or could not start, with the script's status and what it said"
+
+      reference_to BoxRoll
+      attribute :refusal, Report
+
+      sets :refusal
+
+      emits "BoxRollFlagged"
+    end
+
+    command "Verify" do
+      goal "Record that the smoke the roll requested passed"
+
+      reference_to BoxRoll
+      attribute :smoke, Report
+
+      sets :smoke
+
+      emits "BoxRollVerified"
+    end
+
+    command "FlagSmoke" do
+      goal "Record that the roll took but the smoke it requested did not pass, and why"
+
+      reference_to BoxRoll
+      attribute :smoke,   Report
+      attribute :refusal, Report
+
+      sets :smoke
+      sets :refusal
+
+      emits "BoxRollSmokeFlagged"
+    end
+
+    query "Verdict" do
+      description "What one roll found: its status, and the report or the reason it was flagged."
+      attribute :run, RunKey
+      where(run: :run)
+      order_by :run
+    end
+
+    query "Flagged" do
+      description "Every roll that failed or could not start."
+      where(status: "flagged")
+      order_by :run
+    end
+  end
+
+  policy "RollBoxWhenRequested" do
+    on      "BoxRoll.BoxRollRequested"
+    trigger BoxRoll::DeployToolchain::RollBox, with: { run: :run }
+  end
+
+  policy "RecordTheRolledBox" do
+    on      "BoxRoll.BoxRollAnswered"
+    trigger BoxRoll::Complete, with: { report: :report, taskdef: :taskdef, smoke: :smoke }
+  end
+
+  policy "RecordTheFlaggedBoxRoll" do
+    on      "BoxRoll.BoxRollRefused"
+    trigger BoxRoll::Flag, with: { refusal: :refusal }
+  end
+
+  policy "SmokeAfterBoxRoll" do
+    on      "BoxRoll.BoxRollAnswered"
+    where   { run_smoke.value }
+    trigger SmokeRun::Run, with: { project: :project, run: :run, taskdef: :taskdef, after: :kind }
+  end
+
+  policy "VerifyBoxRollOnPassedSmoke" do
+    on      "SmokeRun.SmokePassed"
+    where   { after.value == "box_roll" }
+    trigger BoxRoll::Verify, with: { box_roll: :run, smoke: :report }
+  end
+
+  policy "FlagBoxRollOnFlaggedSmoke" do
+    on      "SmokeRun.SmokeFlagged"
+    where   { after.value == "box_roll" }
+    trigger BoxRoll::FlagSmoke, with: { box_roll: :run, smoke: :refusal, refusal: :refusal }
+  end
+
+  aggregate "DataCopy" do
+    description "One copy of a project's data from the old database into RDS: the generated restore-to-rds script run, and how it ended."
+
+    attribute :project,       Location
+    attribute :script,        Location, optional: true
+    attribute :run,           RunKey
+    attribute :bastion,       Bastion
+    attribute :source,        Host
+    attribute :source_secret, Secret
+    attribute :target,        Host
+    attribute :target_secret, Secret
+    attribute :source_db,     DatabaseName, default: { value: "" }
+    attribute :target_db,     DatabaseName, default: { value: "" }
+    attribute :force,         Switch, optional: true
+    attribute :confirm,       Switch, optional: true
+    attribute :dry_run,       Switch, optional: true
+    attribute :skip_verify,   Switch, optional: true
+    attribute :report,        Report, optional: true
+    attribute :verification,  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 "Location" do
+      attribute :value, String, pattern: '[^\t\n\r]'
+
+      invariant("a project or script is named by its path") { !value.to_s.empty? }
+    end
+
+    # The bastion's EC2 instance id, which both databases are reached through.
+    value_object "Bastion" do
+      attribute :value, String, pattern: '^i-[0-9a-f]+$'
+    end
+
+    value_object "Host" do
+      attribute :value, String, pattern: '^[A-Za-z0-9][A-Za-z0-9.-]*$'
+    end
+
+    # A Secrets Manager id or ARN; the script reads the password from it, so no value travels here.
+    value_object "Secret" do
+      attribute :value, String, pattern: '^[^ \t\n\r]+$'
+    end
+
+    # A database's name; empty leaves it to the generated script's own default.
+    value_object "DatabaseName" do
+      attribute :value, String, pattern: '^[A-Za-z0-9_]*$'
+    end
+
+    value_object "Switch" do
+      attribute :value, Boolean
+    end
+
+    value_object "Report" do
+      attribute :value, String
+    end
+
+    lifecycle :status, default: "requested" do
+      transition "Complete" => "restored", from: "requested"
+      transition "Plan" => "planned", from: "requested"
+      transition "Flag" => "flagged", from: "requested"
+      transition "Confirm" => "verified", from: ["requested", "restored"]
+      transition "Drift" => "drifted", from: ["requested", "restored"]
+      transition "FlagVerification" => "flagged", from: ["requested", "restored"]
+    end
+
+    # `hecks deploy data_copy.restore <project> bastion=<i-...> source=<host> source_secret=<id>
+    # target=<host> target_secret=<id> [source_db=] [target_db=] [force=true] [confirm=true]
+    # [dry_run=true] [skip_verify=true] [script=<path>]`. Runs the project's generated
+    # `restore-to-rds.sh`, which overwrites the target database's schemas, so it refuses unless
+    # `confirm=true` (the refusal names what would be overwritten); `dry_run=true` prints the plan
+    # and runs nothing. A policy then requests a `CopyVerification` under the same run key unless
+    # `skip_verify=true`. Exit 1 when flagged or drifted, with the script's status in the reason.
+    command "Restore" do
+      goal "Copy a project's schemas into RDS and record whether the copy matches (exit 1 when flagged or drifted: 60 old client, 61 target has the schema, 62 restore errors)"
+
+      attribute :project,       Location
+      attribute :script,        Location, optional: true
+      attribute :run,           RunKey
+      attribute :bastion,       Bastion
+      attribute :source,        Host
+      attribute :source_secret, Secret
+      attribute :target,        Host
+      attribute :target_secret, Secret
+      attribute :source_db,     DatabaseName, default: { value: "" }
+      attribute :target_db,     DatabaseName, default: { value: "" }
+      attribute :force,         Switch, optional: true
+      attribute :confirm,       Switch, optional: true
+      attribute :dry_run,       Switch, optional: true
+      attribute :skip_verify,   Switch, optional: true
+
+      sets :project
+      sets :script
+      sets :run
+      sets :bastion
+      sets :source
+      sets :source_secret
+      sets :target
+      sets :target_secret
+      sets :source_db
+      sets :target_db
+      sets :force
+      sets :confirm
+      sets :dry_run
+      sets :skip_verify
+
+      emits "DataCopyRequested"
+    end
+
+    # `hecks deploy data_copy.verify <project> bastion= source= source_secret= target= target_secret=
+    # [source_db=] [target_db=] [script=<path>]`. Compares the two databases with the project's
+    # generated `verify-copy.sh` (structure and exact row counts of every table, nothing unpopulated),
+    # read-only on both, without a restore. A policy requests the `CopyVerification` and its outcome
+    # lands here, the same way it does after a restore. Exit 1 when `drifted` or `flagged`.
+    command "Verify" do
+      goal "Compare two databases without a restore and record whether they match (exit 1 when drifted: 50, or flagged: could not compare)"
+
+      attribute :project,       Location
+      attribute :script,        Location, optional: true
+      attribute :run,           RunKey
+      attribute :bastion,       Bastion
+      attribute :source,        Host
+      attribute :source_secret, Secret
+      attribute :target,        Host
+      attribute :target_secret, Secret
+      attribute :source_db,     DatabaseName, default: { value: "" }
+      attribute :target_db,     DatabaseName, default: { value: "" }
+
+      sets :project
+      sets :script
+      sets :run
+      sets :bastion
+      sets :source
+      sets :source_secret
+      sets :target
+      sets :target_secret
+      sets :source_db
+      sets :target_db
+
+      emits "DataCopyVerifyRequested"
+    end
+
+    command "Complete" do
+      goal "Record that the copy ran, and what the script said"
+
+      reference_to DataCopy
+      attribute :report, Report
+
+      sets :report
+
+      emits "DataCopyCompleted"
+    end
+
+    command "Plan" do
+      goal "Record the plan a dry run printed: what would be copied and overwritten, with nothing run"
+
+      reference_to DataCopy
+      attribute :report, Report
+
+      sets :report
+
+      emits "DataCopyPlanned"
+    end
+
+    command "Flag" do
+      goal "Record that the copy was refused or failed, with the script's status and what it said"
+
+      reference_to DataCopy
+      attribute :refusal, Report
+
+      sets :refusal
+
+      emits "DataCopyFlagged"
+    end
+
+    command "Confirm" do
+      goal "Record that the verification the copy requested found both databases identical"
+
+      reference_to DataCopy
+      attribute :verification, Report
+
+      sets :verification
+
+      emits "DataCopyVerified"
+    end
+
+    command "Drift" do
+      goal "Record that the verification the copy requested found the databases differ, and where"
+
+      reference_to DataCopy
+      attribute :verification, Report
+      attribute :refusal,      Report
+
+      sets :verification
+      sets :refusal
+
+      emits "DataCopyDrifted"
+    end
+
+    command "FlagVerification" do
+      goal "Record that the copy ran but its verification could not be made, and why"
+
+      reference_to DataCopy
+      attribute :verification, Report
+      attribute :refusal,      Report
+
+      sets :verification
+      sets :refusal
+
+      emits "DataCopyVerificationFlagged"
+    end
+
+    query "Verdict" do
+      description "What one copy found: its status, the report, and the reason it was flagged or drifted."
+      attribute :run, RunKey
+      where(run: :run)
+      order_by :run
+    end
+
+    query "Flagged" do
+      description "Every copy that was refused, failed or could not be verified."
+      where(status: "flagged")
+      order_by :run
+    end
+
+    query "Drifted" do
+      description "Every copy whose verification found the two databases differ."
+      where(status: "drifted")
+      order_by :run
+    end
+  end
+
+  policy "CopyDataWhenRequested" do
+    on      "DataCopy.DataCopyRequested"
+    trigger DataCopy::DeployToolchain::CopyData, with: { run: :run }
+  end
+
+  policy "RecordTheCopiedData" do
+    on      "DataCopy.DataCopyAnswered"
+    where   { !planned.value }
+    trigger DataCopy::Complete, with: { report: :report }
+  end
+
+  policy "RecordTheCopyPlan" do
+    on      "DataCopy.DataCopyAnswered"
+    where   { planned.value }
+    trigger DataCopy::Plan, with: { report: :report }
+  end
+
+  policy "RecordTheFlaggedCopy" do
+    on      "DataCopy.DataCopyRefused"
+    trigger DataCopy::Flag, with: { refusal: :refusal }
+  end
+
+  # Declared after RecordTheCopiedData: the copy is recorded before its verification is requested,
+  # and the request comes from the answer itself because a reaction chain is bounded.
+  policy "VerifyAfterCopy" do
+    on      "DataCopy.DataCopyAnswered"
+    where   { run_verify.value }
+    trigger CopyVerification::Run,
+            with: { project: :project, run: :run, bastion: :bastion, source: :source,
+                    source_secret: :source_secret, target: :target, target_secret: :target_secret,
+                    source_db: :source_db, target_db: :target_db }
+  end
+
+  policy "VerifyWhenRequested" do
+    on      "DataCopy.DataCopyVerifyRequested"
+    trigger CopyVerification::Run,
+            with: { project: :project, run: :run, bastion: :bastion, source: :source,
+                    source_secret: :source_secret, target: :target, target_secret: :target_secret,
+                    source_db: :source_db, target_db: :target_db }
+  end
+
+  policy "VerifyDataCopyOnMatch" do
+    on      "CopyVerification.CopyMatched"
+    trigger DataCopy::Confirm, with: { data_copy: :run, verification: :report }
+  end
+
+  policy "DriftDataCopyOnDifference" do
+    on      "CopyVerification.CopyDrifted"
+    trigger DataCopy::Drift, with: { data_copy: :run, verification: :report, refusal: :report }
+  end
+
+  policy "FlagDataCopyOnUnverified" do
+    on      "CopyVerification.CopyUnverified"
+    trigger DataCopy::FlagVerification, with: { data_copy: :run, verification: :refusal, refusal: :refusal }
+  end
+
+  aggregate "CopyVerification" do
+    description "One comparison of two databases holding a project's schemas: the generated verify-copy script run, and what it found."
+
+    attribute :project,       Location
+    attribute :script,        Location, optional: true
+    attribute :run,           RunKey
+    attribute :bastion,       Bastion
+    attribute :source,        Host
+    attribute :source_secret, Secret
+    attribute :target,        Host
+    attribute :target_secret, Secret
+    attribute :source_db,     DatabaseName, default: { value: "" }
+    attribute :target_db,     DatabaseName, default: { value: "" }
+    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 "Location" do
+      attribute :value, String, pattern: '[^\t\n\r]'
+
+      invariant("a project or script is named by its path") { !value.to_s.empty? }
+    end
+
+    value_object "Bastion" do
+      attribute :value, String, pattern: '^i-[0-9a-f]+$'
+    end
+
+    value_object "Host" do
+      attribute :value, String, pattern: '^[A-Za-z0-9][A-Za-z0-9.-]*$'
+    end
+
+    value_object "Secret" do
+      attribute :value, String, pattern: '^[^ \t\n\r]+$'
+    end
+
+    # A database's name; empty leaves it to the generated script's own default.
+    value_object "DatabaseName" do
+      attribute :value, String, pattern: '^[A-Za-z0-9_]*$'
+    end
+
+    value_object "Report" do
+      attribute :value, String
+    end
+
+    lifecycle :status, default: "requested" do
+      transition "Match" => "verified", from: "requested"
+      transition "Differ" => "drifted", from: "requested"
+      transition "Flag" => "flagged", from: "requested"
+    end
+
+    # Runs the project's generated `verify-copy.sh`: structure and exact row counts of every table,
+    # nothing unpopulated. Read-only on both databases. A `DataCopy` requests it, by `data_copy.verify`
+    # or after a restore, and takes its outcome by the shared run key.
+    command "Run" do
+      goal "Compare two databases and record whether they match (exit 1 when drifted: 50 differ, or flagged: could not compare)"
+
+      attribute :project,       Location
+      attribute :script,        Location, optional: true
+      attribute :run,           RunKey
+      attribute :bastion,       Bastion
+      attribute :source,        Host
+      attribute :source_secret, Secret
+      attribute :target,        Host
+      attribute :target_secret, Secret
+      attribute :source_db,     DatabaseName, default: { value: "" }
+      attribute :target_db,     DatabaseName, default: { value: "" }
+
+      sets :project
+      sets :script
+      sets :run
+      sets :bastion
+      sets :source
+      sets :source_secret
+      sets :target
+      sets :target_secret
+      sets :source_db
+      sets :target_db
+
+      emits "CopyVerificationRequested"
+    end
+
+    command "Match" do
+      goal "Record that both databases hold the same structure and row counts"
+
+      reference_to CopyVerification
+      attribute :report, Report
+
+      sets :report
+
+      emits "CopyMatched"
+    end
+
+    command "Differ" do
+      goal "Record that the databases differ, with what the script printed"
+
+      reference_to CopyVerification
+      attribute :report, Report
+
+      sets :report
+
+      emits "CopyDrifted"
+    end
+
+    command "Flag" do
+      goal "Record that the comparison could not be made, and why"
+
+      reference_to CopyVerification
+      attribute :refusal, Report
+
+      sets :refusal
+
+      emits "CopyUnverified"
+    end
+
+    query "Verdict" do
+      description "What one comparison found: its status, and the report or the reason it was flagged."
+      attribute :run, RunKey
+      where(run: :run)
+      order_by :run
+    end
+
+    query "Drifted" do
+      description "Every comparison that found the databases differ."
+      where(status: "drifted")
+      order_by :run
+    end
+
+    query "Flagged" do
+      description "Every comparison that could not be made."
+      where(status: "flagged")
+      order_by :run
+    end
+  end
+
+  policy "CompareCopyWhenRequested" do
+    on      "CopyVerification.CopyVerificationRequested"
+    trigger CopyVerification::DeployToolchain::CompareCopy, with: { run: :run }
+  end
+
+  policy "RecordTheMatchingCopy" do
+    on      "CopyVerification.CopyVerificationAnswered"
+    where   { !drifted.value }
+    trigger CopyVerification::Match, with: { report: :report }
+  end
+
+  policy "RecordTheDriftedCopy" do
+    on      "CopyVerification.CopyVerificationAnswered"
+    where   { drifted.value }
+    trigger CopyVerification::Differ, with: { report: :report }
+  end
+
+  policy "RecordTheUnverifiedCopy" do
+    on      "CopyVerification.CopyVerificationRefused"
+    trigger CopyVerification::Flag, with: { refusal: :refusal }
+  end
+
+  aggregate "BluebookDiff" do
+    description "One report of which bluebook releases a deploy changes: the running image's bluebooks against the ones about to ship."
+
+    attribute :project, Location
+    attribute :script,  Location, optional: true
+    attribute :run,     RunKey
+    attribute :old,     Location, optional: true
+    attribute :new,     Location, 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 "Location" do
+      attribute :value, String, pattern: '[^\t\n\r]'
+
+      invariant("a project, script or file is named by its path") { !value.to_s.empty? }
+    end
+
+    value_object "Report" do
+      attribute :value, String
+    end
+
+    # No outcome is a failure: a report that could not be made is `unavailable`, never `flagged`
+    # (only a malformed request is), because the era check gates a deploy, not this report.
+    lifecycle :status, default: "requested" do
+      transition "Match" => "unchanged", from: "requested"
+      transition "Differ" => "changed", from: "requested"
+      transition "Withhold" => "unavailable", from: "requested"
+      transition "Flag" => "flagged", from: "requested"
+    end
+
+    # `hecks deploy bluebook_diff.run <project> [old=<json> new=<json>] [script=<path>]`. With
+    # `old` and `new` (two `hecks package.verify` outputs) the comparison is made here, offline.
+    # With neither, the project's `bluebooks-diff.sh` reads the running image's bluebooks from the
+    # registry (read-only) and the local image's, and its report is classified. It never fails:
+    # `unchanged`, `changed` or `unavailable` (a lookup failed, or the script is missing). Only
+    # giving one of `old` and `new` is refused, as `flagged`.
+    command "Run" do
+      goal "Report which bluebook releases a deploy changes and record it (never a failure: unchanged, changed or unavailable)"
+
+      attribute :project, Location
+      attribute :script,  Location, optional: true
+      attribute :run,     RunKey
+      attribute :old,     Location, optional: true
+      attribute :new,     Location, optional: true
+
+      sets :project
+      sets :script
+      sets :run
+      sets :old
+      sets :new
+
+      emits "BluebookDiffRequested"
+    end
+
+    command "Match" do
+      goal "Record that the deploy changes no bluebook"
+
+      reference_to BluebookDiff
+      attribute :report, Report
+
+      sets :report
+
+      emits "BluebooksUnchanged"
+    end
+
+    command "Differ" do
+      goal "Record the bluebooks the deploy adds, removes, re-versions or changes in content"
+
+      reference_to BluebookDiff
+      attribute :report, Report
+
+      sets :report
+
+      emits "BluebooksChanged"
+    end
+
+    command "Withhold" do
+      goal "Record that the report could not be made, and why; the deploy carries on"
+
+      reference_to BluebookDiff
+      attribute :report, Report
+
+      sets :report
+
+      emits "BluebookDiffUnavailable"
+    end
+
+    command "Flag" do
+      goal "Record that the request was malformed (only one of old and new), and why"
+
+      reference_to BluebookDiff
+      attribute :refusal, Report
+
+      sets :refusal
+
+      emits "BluebookDiffFlagged"
+    end
+
+    query "Verdict" do
+      description "What one report found: its status and the report."
+      attribute :run, RunKey
+      where(run: :run)
+      order_by :run
+    end
+
+    query "Changed" do
+      description "Every report that found a bluebook release changed."
+      where(status: "changed")
+      order_by :run
+    end
+  end
+
+  policy "DiffWhenRequested" do
+    on      "BluebookDiff.BluebookDiffRequested"
+    trigger BluebookDiff::DeployToolchain::CompareBluebooks, with: { run: :run }
+  end
+
+  policy "RecordTheUnchangedBluebooks" do
+    on      "BluebookDiff.BluebookDiffAnswered"
+    where   { outcome.value == "unchanged" }
+    trigger BluebookDiff::Match, with: { report: :report }
+  end
+
+  policy "RecordTheChangedBluebooks" do
+    on      "BluebookDiff.BluebookDiffAnswered"
+    where   { outcome.value == "changed" }
+    trigger BluebookDiff::Differ, with: { report: :report }
+  end
+
+  policy "RecordTheUnavailableDiff" do
+    on      "BluebookDiff.BluebookDiffAnswered"
+    where   { outcome.value == "unavailable" }
+    trigger BluebookDiff::Withhold, with: { report: :report }
+  end
+
+  policy "RecordTheFlaggedDiff" do
+    on      "BluebookDiff.BluebookDiffRefused"
+    trigger BluebookDiff::Flag, with: { refusal: :refusal }
+  end
+
+  aggregate "PreviewRun" do
+    description "One run of a project's preview script: the per-branch preview stack named, found, listed, deployed, destroyed or signed in to, and how it ended."
+
+    attribute :project, Location
+    attribute :script,  Location, optional: true
+    attribute :run,     RunKey
+    attribute :action,  Action
+    attribute :branch,  Branch, optional: true
+    attribute :confirm, Switch, optional: true
+    attribute :dry_run, Switch, 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 "Location" do
+      attribute :value, String, pattern: '[^\t\n\r]'
+
+      invariant("a project or script is named by its path") { !value.to_s.empty? }
+    end
+
+    # What the script is asked to do; each command sets its own.
+    value_object "Action" do
+      attribute :value, String, pattern: '^(name|url|list|deploy|destroy|login)$'
+    end
+
+    # A git branch name. A preview is never of a production branch.
+    value_object "Branch" do
+      attribute :value, String, pattern: '^[^ \t\n\r]+$'
+
+      invariant("a preview is never of main or master") { value != "main" && value != "master" }
+    end
+
+    value_object "Switch" do
+      attribute :value, Boolean
+    end
+
+    value_object "Report" do
+      attribute :value, String
+    end
+
+    lifecycle :status, default: "requested" do
+      transition "RecordName" => "named", from: "requested"
+      transition "RecordUrl" => "located", from: "requested"
+      transition "RecordList" => "listed", from: "requested"
+      transition "RecordDeploy" => "deployed", from: "requested"
+      transition "RecordDestroy" => "destroyed", from: "requested"
+      transition "RecordLogin" => "signed_in", from: "requested"
+      transition "Plan" => "planned", from: "requested"
+      transition "Flag" => "flagged", from: "requested"
+    end
+
+    # `hecks deploy preview_run.<name|url|list|deploy|destroy|login> <project> [branch=<name>]
+    # [confirm=true] [dry_run=true] [script=<path>]`. Runs the project's `preview.sh` with that
+    # verb; the script derives every name from the branch (the checked-out one unless `branch=`),
+    # refuses `main` and `master`, and only touches stacks under its own prefix. `name`, `url` and
+    # `list` read; `deploy`, `destroy` and `login` write to AWS or read its secrets, so they refuse
+    # unless `confirm=true`, and `dry_run=true` prints the plan and runs nothing. Exit 1 when
+    # flagged, with the script's status (1: it refused or failed) in the reason.
+    command "Name" do
+      goal "Print the names a branch's preview would have, from the project's preview script (no AWS call)"
+
+      attribute :project, Location
+      attribute :script,  Location, optional: true
+      attribute :run,     RunKey
+      attribute :action,  Action, default: { value: "name" }
+      attribute :branch,  Branch, optional: true
+      attribute :confirm, Switch, optional: true
+      attribute :dry_run, Switch, optional: true
+
+      sets :project
+      sets :script
+      sets :run
+      sets :action
+      sets :branch
+      sets :confirm
+      sets :dry_run
+
+      emits "PreviewNameRequested"
+    end
+
+    command "Url" do
+      goal "Print a branch's preview URL, read from its stack"
+
+      attribute :project, Location
+      attribute :script,  Location, optional: true
+      attribute :run,     RunKey
+      attribute :action,  Action, default: { value: "url" }
+      attribute :branch,  Branch, optional: true
+      attribute :confirm, Switch, optional: true
+      attribute :dry_run, Switch, optional: true
+
+      sets :project
+      sets :script
+      sets :run
+      sets :action
+      sets :branch
+      sets :confirm
+      sets :dry_run
+
+      emits "PreviewUrlRequested"
+    end
+
+    command "List" do
+      goal "List every preview stack that exists, read from AWS"
+
+      attribute :project, Location
+      attribute :script,  Location, optional: true
+      attribute :run,     RunKey
+      attribute :action,  Action, default: { value: "list" }
+      attribute :branch,  Branch, optional: true
+      attribute :confirm, Switch, optional: true
+      attribute :dry_run, Switch, optional: true
+
+      sets :project
+      sets :script
+      sets :run
+      sets :action
+      sets :branch
+      sets :confirm
+      sets :dry_run
+
+      emits "PreviewListRequested"
+    end
+
+    command "Deploy" do
+      goal "Create or update a branch's preview from the images built locally (writes to AWS; refuses unless confirm=true)"
+
+      attribute :project, Location
+      attribute :script,  Location, optional: true
+      attribute :run,     RunKey
+      attribute :action,  Action, default: { value: "deploy" }
+      attribute :branch,  Branch, optional: true
+      attribute :confirm, Switch, optional: true
+      attribute :dry_run, Switch, optional: true
+
+      sets :project
+      sets :script
+      sets :run
+      sets :action
+      sets :branch
+      sets :confirm
+      sets :dry_run
+
+      emits "PreviewDeployRequested"
+    end
+
+    command "Destroy" do
+      goal "Tear a branch's preview stack down (writes to AWS; refuses unless confirm=true)"
+
+      attribute :project, Location
+      attribute :script,  Location, optional: true
+      attribute :run,     RunKey
+      attribute :action,  Action, default: { value: "destroy" }
+      attribute :branch,  Branch, optional: true
+      attribute :confirm, Switch, optional: true
+      attribute :dry_run, Switch, optional: true
+
+      sets :project
+      sets :script
+      sets :run
+      sets :action
+      sets :branch
+      sets :confirm
+      sets :dry_run
+
+      emits "PreviewDestroyRequested"
+    end
+
+    command "Login" do
+      goal "Mint a line that signs the deployer in to a preview as its first admin (reads its session secret; refuses unless confirm=true)"
+
+      attribute :project, Location
+      attribute :script,  Location, optional: true
+      attribute :run,     RunKey
+      attribute :action,  Action, default: { value: "login" }
+      attribute :branch,  Branch, optional: true
+      attribute :confirm, Switch, optional: true
+      attribute :dry_run, Switch, optional: true
+
+      sets :project
+      sets :script
+      sets :run
+      sets :action
+      sets :branch
+      sets :confirm
+      sets :dry_run
+
+      emits "PreviewLoginRequested"
+    end
+
+    command "RecordName" do
+      goal "Record the names the script printed"
+
+      reference_to PreviewRun
+      attribute :report, Report
+
+      sets :report
+
+      emits "PreviewNamed"
+    end
+
+    command "RecordUrl" do
+      goal "Record the preview URL the script printed"
+
+      reference_to PreviewRun
+      attribute :report, Report
+
+      sets :report
+
+      emits "PreviewLocated"
+    end
+
+    command "RecordList" do
+      goal "Record the preview stacks the script listed"
+
+      reference_to PreviewRun
+      attribute :report, Report
+
+      sets :report
+
+      emits "PreviewListed"
+    end
+
+    command "RecordDeploy" do
+      goal "Record that the preview was created or updated, and what the script said"
+
+      reference_to PreviewRun
+      attribute :report, Report
+
+      sets :report
+
+      emits "PreviewDeployed"
+    end
+
+    command "RecordDestroy" do
+      goal "Record that the preview was torn down, and what the script said"
+
+      reference_to PreviewRun
+      attribute :report, Report
+
+      sets :report
+
+      emits "PreviewDestroyed"
+    end
+
+    command "RecordLogin" do
+      goal "Record that the sign-in line was minted, and where the script put it"
+
+      reference_to PreviewRun
+      attribute :report, Report
+
+      sets :report
+
+      emits "PreviewSignedIn"
+    end
+
+    command "Plan" do
+      goal "Record the plan a dry run printed: what would run and where, with nothing run"
+
+      reference_to PreviewRun
+      attribute :report, Report
+
+      sets :report
+
+      emits "PreviewPlanned"
+    end
+
+    command "Flag" do
+      goal "Record that the run was refused or failed, with the script's status and what it said"
+
+      reference_to PreviewRun
+      attribute :refusal, Report
+
+      sets :refusal
+
+      emits "PreviewFlagged"
+    end
+
+    query "Verdict" do
+      description "What one run found: its status, the report, and the reason it was flagged."
+      attribute :run, RunKey
+      where(run: :run)
+      order_by :run
+    end
+
+    query "Flagged" do
+      description "Every preview run that was refused or failed."
+      where(status: "flagged")
+      order_by :run
+    end
+  end
+
+  policy "RunPreviewWhenNameRequested" do
+    on      "PreviewRun.PreviewNameRequested"
+    trigger PreviewRun::DeployToolchain::RunPreview, with: { run: :run }
+  end
+
+  policy "RunPreviewWhenUrlRequested" do
+    on      "PreviewRun.PreviewUrlRequested"
+    trigger PreviewRun::DeployToolchain::RunPreview, with: { run: :run }
+  end
+
+  policy "RunPreviewWhenListRequested" do
+    on      "PreviewRun.PreviewListRequested"
+    trigger PreviewRun::DeployToolchain::RunPreview, with: { run: :run }
+  end
+
+  policy "RunPreviewWhenDeployRequested" do
+    on      "PreviewRun.PreviewDeployRequested"
+    trigger PreviewRun::DeployToolchain::RunPreview, with: { run: :run }
+  end
+
+  policy "RunPreviewWhenDestroyRequested" do
+    on      "PreviewRun.PreviewDestroyRequested"
+    trigger PreviewRun::DeployToolchain::RunPreview, with: { run: :run }
+  end
+
+  policy "RunPreviewWhenLoginRequested" do
+    on      "PreviewRun.PreviewLoginRequested"
+    trigger PreviewRun::DeployToolchain::RunPreview, with: { run: :run }
+  end
+
+  policy "RecordThePreviewName" do
+    on      "PreviewRun.PreviewRunAnswered"
+    where   { outcome.value == "named" }
+    trigger PreviewRun::RecordName, with: { report: :report }
+  end
+
+  policy "RecordThePreviewUrl" do
+    on      "PreviewRun.PreviewRunAnswered"
+    where   { outcome.value == "located" }
+    trigger PreviewRun::RecordUrl, with: { report: :report }
+  end
+
+  policy "RecordThePreviewList" do
+    on      "PreviewRun.PreviewRunAnswered"
+    where   { outcome.value == "listed" }
+    trigger PreviewRun::RecordList, with: { report: :report }
+  end
+
+  policy "RecordTheDeployedPreview" do
+    on      "PreviewRun.PreviewRunAnswered"
+    where   { outcome.value == "deployed" }
+    trigger PreviewRun::RecordDeploy, with: { report: :report }
+  end
+
+  policy "RecordTheDestroyedPreview" do
+    on      "PreviewRun.PreviewRunAnswered"
+    where   { outcome.value == "destroyed" }
+    trigger PreviewRun::RecordDestroy, with: { report: :report }
+  end
+
+  policy "RecordThePreviewLogin" do
+    on      "PreviewRun.PreviewRunAnswered"
+    where   { outcome.value == "signed_in" }
+    trigger PreviewRun::RecordLogin, with: { report: :report }
+  end
+
+  policy "RecordThePreviewPlan" do
+    on      "PreviewRun.PreviewRunAnswered"
+    where   { outcome.value == "planned" }
+    trigger PreviewRun::Plan, with: { report: :report }
+  end
+
+  policy "RecordTheFlaggedPreview" do
+    on      "PreviewRun.PreviewRunRefused"
+    trigger PreviewRun::Flag, with: { refusal: :refusal }
+  end
+
+  aggregate "CompanionRoll" do
+    description "One roll of a companion Compose project (a second project beside the app's) onto the box: the project's deploy script run, and how it ended."
+
+    attribute :project,   Location
+    attribute :script,    Location, optional: true
+    attribute :run,       RunKey
+    attribute :companion, Companion, default: { value: "umami" }
+    attribute :taskdef,   TaskDefinition
+    attribute :confirm,   Switch, optional: true
+    attribute :dry_run,   Switch, 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 "Location" do
+      attribute :value, String, pattern: '[^\t\n\r]'
+
+      invariant("a project or script is named by its path") { !value.to_s.empty? }
+    end
+
+    # The companion's name; its script is `deploy-<companion>.sh`.
+    value_object "Companion" do
+      attribute :value, String, pattern: '^[a-z0-9][a-z0-9-]*$'
+    end
+
+    # A task definition revision (or family) the companion's image and settings are read from.
+    value_object "TaskDefinition" do
+      attribute :value, String, pattern: '^[A-Za-z0-9_-]+(:[0-9]+)?$'
+    end
+
+    value_object "Switch" do
+      attribute :value, Boolean
+    end
+
+    value_object "Report" do
+      attribute :value, String
+    end
+
+    lifecycle :status, default: "requested" do
+      transition "Complete" => "rolled", from: "requested"
+      transition "Plan" => "planned", from: "requested"
+      transition "Flag" => "flagged", from: "requested"
+    end
+
+    # `hecks deploy companion_roll.run <project> taskdef=<family:rev> [companion=umami] [confirm=true]
+    # [dry_run=true] [script=<path>]`. Runs the project's `deploy-<companion>.sh`, which reads the
+    # companion's image and settings from the task definition, sends a Compose project and its secret
+    # references to the box over SSM (secret values never travel; the box resolves them), starts it
+    # beside the app's project, and checks it on the box. It writes to the box, so it refuses unless
+    # `confirm=true`; `dry_run=true` prints the plan and runs nothing. Exit 1 when flagged.
+    command "Run" do
+      goal "Roll a companion Compose project onto the box and record the check on the box (refuses unless confirm=true)"
+
+      attribute :project,   Location
+      attribute :script,    Location, optional: true
+      attribute :run,       RunKey
+      attribute :companion, Companion, default: { value: "umami" }
+      attribute :taskdef,   TaskDefinition
+      attribute :confirm,   Switch, optional: true
+      attribute :dry_run,   Switch, optional: true
+
+      sets :project
+      sets :script
+      sets :run
+      sets :companion
+      sets :taskdef
+      sets :confirm
+      sets :dry_run
+
+      emits "CompanionRollRequested"
+    end
+
+    command "Complete" do
+      goal "Record that the companion rolled and passed its check on the box, and what the script printed"
+
+      reference_to CompanionRoll
+      attribute :report, Report
+
+      sets :report
+
+      emits "CompanionRolled"
+    end
+
+    command "Plan" do
+      goal "Record the plan a dry run printed: what would be rolled and where, with nothing run"
+
+      reference_to CompanionRoll
+      attribute :report, Report
+
+      sets :report
+
+      emits "CompanionRollPlanned"
+    end
+
+    command "Flag" do
+      goal "Record that the roll was refused, or the companion did not roll or is not healthy, and why"
+
+      reference_to CompanionRoll
+      attribute :refusal, Report
+
+      sets :refusal
+
+      emits "CompanionRollFlagged"
+    end
+
+    query "Verdict" do
+      description "What one roll found: its status, the report, and the reason it was flagged."
+      attribute :run, RunKey
+      where(run: :run)
+      order_by :run
+    end
+
+    query "Flagged" do
+      description "Every companion roll that was refused, did not roll or was not healthy."
+      where(status: "flagged")
+      order_by :run
+    end
+  end
+
+  policy "RollCompanionWhenRequested" do
+    on      "CompanionRoll.CompanionRollRequested"
+    trigger CompanionRoll::DeployToolchain::RollCompanion, with: { run: :run }
+  end
+
+  policy "RecordTheRolledCompanion" do
+    on      "CompanionRoll.CompanionRollAnswered"
+    where   { !planned.value }
+    trigger CompanionRoll::Complete, with: { report: :report }
+  end
+
+  policy "RecordTheCompanionPlan" do
+    on      "CompanionRoll.CompanionRollAnswered"
+    where   { planned.value }
+    trigger CompanionRoll::Plan, with: { report: :report }
+  end
+
+  policy "RecordTheFlaggedCompanionRoll" do
+    on      "CompanionRoll.CompanionRollRefused"
+    trigger CompanionRoll::Flag, with: { refusal: :refusal }
+  end
+
   aggregate "TemplateComparison" do
     description "One offline comparison of two CloudFormation templates, by logical id."