hecks 5.0.0 → 7.0.0

data/lib/hecks/ci_pipeline/ci_pipeline.bluebook

@@ -0,0 +1,938 @@
+# CI pipeline: the GitHub Actions workflows under .github/workflows are a projection of
+# this bluebook, as generated Rust is a projection of a domain. A workflow file, its jobs
+# and their steps, the gates that skip work, the edges that order jobs, the corpus the
+# jobs share, and the build that passes or fails are written down here. The projector
+# reads these rows and writes the YAML; a check compares the committed file with the rows.
+#
+# Nothing here runs a job or reads GitHub. The Runner port answers what happened in a
+# build, and the Cache port answers whether a corpus is held. Both are declared in
+# ci_pipeline.ports.hecksagon.
+#
+# A client declares its workflows as `member` rows of value objects in its own bluebook, as a
+# site declares its routes (the Site bluebook): a `Workflow` row per file, then a `Trigger`, a
+# `Secret`, a `Job`, a `Need`, an `Output`, an `Env`, a `Step` and a `StepInput` row each, all
+# flat and joined by workflow and job name. The Workflow, JobSpec and Step aggregates below name
+# the fields those rows carry and the closed sets their values come from. `hecks
+# regeneration_run.project_ci_pipeline` reads the rows and writes the files.
+#
+# A job's `needs:` is a `Need` row. The policies at the end of this bluebook are the same edges as
+# a build sees them, as events: they decide when a job in one build queues, and write nothing.
+#
+# CiSpeed's Run and JobTiming record what this bluebook's Build and Job already know. When
+# CiSpeed reads them, the Runner port answers from these rows, not from a second record.
+
+Hecks.bluebook "CiPipeline" do
+  vision "A workflow file is what its rows say: a job runs after what it needs, a skipped gate leaves its dependents runnable, a build passes only when every required job settled, and a corpus is regenerated once and shared."
+
+  supporting
+
+  # One workflow file under .github/workflows. The file name is its identity. `reusable` means the
+  # file is called by other workflows, so the projector writes `workflow_call`; a Workflow row
+  # carries no such flag, because its `workflow_call` Trigger row says the same. A `Secret` row
+  # names one secret a called workflow takes and whether the caller must pass it. `note` is the
+  # comment the file opens with, one line per line of text.
+  aggregate "Workflow" do
+    description "One workflow file: its name, the events that start it, concurrency, whether other workflows call it, and the secrets it takes."
+
+    identified_by :name
+
+    attribute :name,               WorkflowName
+    attribute :display_name,       WorkflowText
+    attribute :note,               WorkflowText, optional: true
+    attribute :concurrency_group,  WorkflowText, optional: true
+    attribute :cancel_in_progress, Switch, optional: true
+    attribute :reusable,           Switch
+    attribute :triggers,           list_of(Trigger)
+    attribute :secrets,            list_of(SecretName)
+    attribute :check,              Switch, optional: true
+
+    value_object "WorkflowName" do
+      # The file name under .github/workflows, such as `ci-rspec.yml`.
+      attribute :value, String, pattern: '^[a-z][a-z0-9-]*[.]yml$'
+      invariant("a workflow is named by its file") { !value.to_s.empty? }
+    end
+
+    value_object "WorkflowText" do
+      attribute :value, String
+    end
+
+    # The events the projector writes under `on:`. `schedule` is not here: its cron text is not
+    # expressible yet, so the scheduled workflows stay hand-written.
+    value_object "Trigger" do
+      attribute :value, String, one_of: %w[push_main pull_request workflow_call workflow_dispatch]
+    end
+
+    value_object "SecretName" do
+      # A repository secret the file passes in, such as HECKS_CI_ATTEST_KEY.
+      attribute :value, String, pattern: '^[A-Z][A-Z0-9_]*$'
+    end
+
+    value_object "Switch" do
+      attribute :value, Boolean
+    end
+
+    # A digest of the projected YAML, or of the committed file: a hex SHA-256.
+    value_object "ProjectionDigest" do
+      attribute :value, String, pattern: '^[0-9a-f]{64}$'
+    end
+
+    command "Declare" do
+      role "CI engineer"
+      goal "Write down one workflow file: its name, whether other workflows call it, and its concurrency"
+
+      attribute :name,               WorkflowName
+      attribute :display_name,       WorkflowText
+      attribute :concurrency_group,  WorkflowText, optional: true
+      attribute :cancel_in_progress, Switch, optional: true
+      attribute :reusable,           Switch
+
+      sets :name
+      sets :display_name
+      sets :concurrency_group
+      sets :cancel_in_progress
+      sets :reusable
+
+      emits "WorkflowDeclared"
+    end
+
+    command "Trigger" do
+      role "CI engineer"
+      goal "Name one event that starts this workflow"
+
+      reference_to Workflow
+      attribute :event, Trigger
+
+      sets :triggers, append: { value: :event }
+
+      emits "WorkflowTriggerAdded"
+    end
+
+    command "Secret" do
+      role "CI engineer"
+      goal "Name one repository secret this workflow passes in, so a caller must pass it too"
+
+      reference_to Workflow
+      attribute :secret, SecretName
+
+      sets :secrets, append: { value: :secret }
+
+      emits "WorkflowSecretAdded"
+    end
+
+    # Writes the file from the rows, or with check only compares the committed file with the rows.
+    command "Project" do
+      role "CI engineer"
+      goal "Project the workflow's rows into its file, or with check only compare the committed file"
+
+      reference_to Workflow
+      attribute :check, Switch, optional: true
+
+      sets :check
+
+      emits "WorkflowProjectionRequested"
+    end
+
+    # A verdict is given only under check. The two verdicts are separate commands, because a policy
+    # can read only an event's name, so the verdict has to be carried by the event's name.
+    command "ReportCurrent" do
+      role "CI engineer"
+      goal "Say the committed file is the projection of its rows"
+
+      reference_to Workflow
+      attribute :projected, ProjectionDigest
+      attribute :on_disk,   ProjectionDigest
+
+      given("a verdict is given under check") { check.value == true }
+      given("the committed file matches its projection") { projected.value == on_disk.value }
+
+      emits "WorkflowCurrent"
+    end
+
+    command "ReportStale" do
+      role "CI engineer"
+      goal "Report that the committed file differs from its projection, under check"
+
+      reference_to Workflow
+      attribute :projected, ProjectionDigest
+      attribute :on_disk,   ProjectionDigest
+
+      given("a stale projection is reported under check") { check.value == true }
+      given("the committed file differs from its projection") { projected.value != on_disk.value }
+
+      emits "WorkflowStale"
+    end
+
+    query "All" do
+      description "Every workflow file, by name."
+      order_by :name
+    end
+  end
+
+  # One job as the workflow file declares it: the YAML facts the projector writes, its gate, its
+  # steps, and its shard count. A job's run in one build is a Job below, which refers back here by
+  # name. Shards: `shard_total` is the one count; every shard leg checks its index against it. A
+  # job whose total is above one gets a matrix named `shard_axis` with a leg for each number from
+  # one to the total, and its legs never cancel one another, so every leg reports its timing. A
+  # step's command may write `%{shard_total}` where the total belongs, so the count is stated once.
+  # `needs` names the jobs of the same workflow this one waits for, and `outputs` the values its
+  # steps hand to the jobs that need it. `note` is the comment above the job.
+  aggregate "JobSpec" do
+    description "One job as its workflow file declares it: runner, time limit, permissions, gate, condition, steps, and shard total."
+
+    identified_by :name
+
+    attribute :name,            JobName
+    reference_to Workflow
+    attribute :runner,          RunnerLabel
+    attribute :timeout_minutes, TimeoutMinutes
+    # Empty when the job takes the workflow's default permissions.
+    attribute :permissions,     Permissions, optional: true
+    attribute :required,        Switch
+    attribute :gate,            GateName
+    # The job's `if:` as the projector writes it. Empty when the job always runs.
+    attribute :condition,       Condition
+    attribute :shard_total,     ShardTotal
+    attribute :shard_axis,      ShardAxis, optional: true
+    attribute :shards,          list_of(ShardIndex)
+    attribute :note,            JobNote, optional: true
+    attribute :needs,           list_of(JobName)
+    attribute :outputs,         list_of(JobOutput)
+    attribute :env,             list_of(EnvVar)
+    attribute :steps,           list_of(Step)
+    attribute :step_inputs,     list_of(StepInput)
+
+    value_object "JobName" do
+      attribute :value, String, matches: :present
+      invariant("a job is named") { !value.to_s.empty? }
+    end
+
+    value_object "WorkflowName" do
+      attribute :value, String, pattern: '^[a-z][a-z0-9-]*[.]yml$'
+    end
+
+    # A runner label such as `ubuntu-latest`.
+    value_object "RunnerLabel" do
+      attribute :value, String, matches: :present
+    end
+
+    value_object "TimeoutMinutes" do
+      attribute :value, Integer
+      invariant("a job has a positive time limit") { value.positive? }
+    end
+
+    # The `permissions:` block as one line, such as `contents: read`; several scopes are separated
+    # by a comma and a space, as in `contents: read, checks: read`.
+    value_object "Permissions" do
+      attribute :value, String, matches: :present
+    end
+
+    # A gate names a path or release-only check that skips work a change cannot affect. Empty means
+    # the job is not gated.
+    value_object "GateName" do
+      attribute :value, String, default: ""
+    end
+
+    value_object "Condition" do
+      attribute :value, String, default: ""
+    end
+
+    value_object "ShardTotal" do
+      attribute :value, Integer, default: 1
+      invariant("a sharded job has at least one shard") { value.positive? }
+    end
+
+    value_object "ShardIndex" do
+      attribute :value, Integer
+      invariant("a shard is numbered from one") { value.positive? }
+    end
+
+    # The matrix's name, as a step reads it: `${{ matrix.group }}` for the axis `group`.
+    value_object "ShardAxis" do
+      attribute :value, String, pattern: '^[a-z][a-z0-9_]*$'
+    end
+
+    # The comment written above a job, one line per line of text.
+    value_object "JobNote" do
+      attribute :value, String, default: ""
+    end
+
+    # One entry of a job's `outputs:`: the value a step hands to the jobs that need this one.
+    value_object "JobOutput" do
+      attribute :key,   OutputKey
+      attribute :value, OutputValue
+    end
+
+    value_object "OutputKey" do
+      attribute :value, String, pattern: '^[a-z][a-z0-9_]*$'
+    end
+
+    value_object "OutputValue" do
+      attribute :value, String, matches: :present
+    end
+
+    # One step of a job, in order. `name` is the step's handle within its job, which a StepInput
+    # names; it is never written into the file. `title` is the `name:` the workflow shows, `id` the
+    # `id:` other steps read outputs by, and `note` the comment above the step. `uses` names a
+    # composite action in this repo or a pinned action from outside it; `run` is one shell command.
+    # Exactly one of the two is set.
+    value_object "Step" do
+      attribute :name,      StepName
+      attribute :title,     StepTitle, optional: true
+      attribute :id,        StepId, optional: true
+      attribute :uses,      ActionRef
+      attribute :run,       StepRun
+      attribute :condition, Condition
+      attribute :note,      JobNote, optional: true
+    end
+
+    value_object "StepName" do
+      attribute :value, String, matches: :present
+    end
+
+    value_object "StepTitle" do
+      attribute :value, String, default: ""
+    end
+
+    value_object "StepId" do
+      attribute :value, String, pattern: '^[a-z][a-z0-9_-]*$'
+    end
+
+    # The composite actions under .github/actions, and the pinned actions the workflows use. A
+    # step that runs a command names none, which is the empty member. An action is added here when a
+    # workflow first uses it.
+    value_object "ActionRef" do
+      attribute :value, String, one_of: [
+        "",
+        "./.github/actions/cargo-cache", "./.github/actions/check-attestation",
+        "./.github/actions/generated-rust",
+        "./.github/actions/ghcr-binary-cache-restore", "./.github/actions/ghcr-binary-cache-save",
+        "./.github/actions/hecks-environment", "./.github/actions/postgres",
+        "./.github/actions/require-result", "./.github/actions/rust-toolchain",
+        "./.github/actions/setup-ruby", "./.github/actions/wasm-toolchain",
+        "./.github/actions/write-attestation",
+        "actions/cache@v4", "actions/cache/restore@v4", "actions/cache/save@v4",
+        "actions/checkout@v4", "actions/download-artifact@v4", "actions/setup-node@v4",
+        "actions/upload-artifact@v4"
+      ]
+    end
+
+    value_object "StepRun" do
+      attribute :value, String, default: ""
+    end
+
+    # The `with:` input of a `uses` step, keyed by the step's name.
+    value_object "StepInput" do
+      attribute :step,  StepName
+      attribute :key,   InputKey
+      attribute :value, InputValue
+    end
+
+    value_object "InputKey" do
+      attribute :value, String, matches: :present
+    end
+
+    value_object "InputValue" do
+      attribute :value, String, default: ""
+    end
+
+    # One `env:` entry of a job, such as `BUNDLE_WITHOUT` set to `development`.
+    value_object "EnvVar" do
+      attribute :key,   EnvName
+      attribute :value, EnvValue
+    end
+
+    value_object "EnvName" do
+      attribute :value, String, pattern: '^[A-Z][A-Z0-9_]*$'
+    end
+
+    value_object "EnvValue" do
+      attribute :value, String, default: ""
+    end
+
+    value_object "Switch" do
+      attribute :value, Boolean
+    end
+
+    command "Declare" do
+      role "CI engineer"
+      goal "Write down one job of a workflow: its runner, time limit, permissions, gate, and shard total"
+
+      attribute :name,            JobName
+      reference_to Workflow
+      attribute :runner,          RunnerLabel
+      attribute :timeout_minutes, TimeoutMinutes
+      attribute :permissions,     Permissions
+      attribute :required,        Switch
+      attribute :gate,            GateName
+      attribute :condition,       Condition
+      attribute :shard_total,     ShardTotal
+
+      sets :name
+      sets :workflow
+      sets :runner
+      sets :timeout_minutes
+      sets :permissions
+      sets :required
+      sets :gate
+      sets :condition
+      sets :shard_total
+
+      emits "JobSpecDeclared"
+    end
+
+    command "AddStep" do
+      role "CI engineer"
+      goal "Add one step to the end of a job, as a composite action or a shell command"
+
+      reference_to JobSpec
+      attribute :step_name, StepName
+      attribute :uses,      ActionRef
+      attribute :run,       StepRun
+      attribute :condition, Condition
+
+      given("a step either uses an action or runs a command, not both") do
+        (uses.value != "" && run.value == "") || (uses.value == "" && run.value != "")
+      end
+
+      sets :steps, append: { name: :step_name, uses: :uses, run: :run, condition: :condition }
+
+      emits "StepAdded"
+    end
+
+    command "AddEnv" do
+      role "CI engineer"
+      goal "Set one environment variable for every step of a job"
+
+      reference_to JobSpec
+      attribute :key,   EnvName
+      attribute :value, EnvValue
+
+      sets :env, append: { key: :key, value: :value }
+
+      emits "EnvAdded"
+    end
+
+    command "AddStepInput" do
+      role "CI engineer"
+      goal "Pass one `with:` input to a step of a job"
+
+      reference_to JobSpec
+      attribute :step,  StepName
+      attribute :key,   InputKey
+      attribute :value, InputValue
+
+      sets :step_inputs, append: { step: :step, key: :key, value: :value }
+
+      emits "StepInputAdded"
+    end
+
+    # One matrix leg. Its index must be within the shard total, which is the only count the job
+    # states; the matrix size the projector writes is that same total.
+    command "PlanShard" do
+      role "CI engineer"
+      goal "Plan one shard leg of a sharded job, numbered within the shard total"
+
+      reference_to JobSpec
+      attribute :index, ShardIndex
+
+      given("a shard index is within the shard total") do
+        index.value >= 1 && index.value <= shard_total.value
+      end
+
+      sets :shards, append: { value: :index }
+
+      emits "ShardPlanned"
+    end
+
+    query "All" do
+      description "Every declared job, by name."
+      order_by :name
+    end
+  end
+
+  # One job's run within one build. Its identity is the job's name, because a policy's `with:` can
+  # only copy an event field or write a literal, so an edge into a named job can address it only by
+  # name; the build it belongs to is a reference. The `needs`
+  # edges are policies below; `needs_total` is the number of edges into this job, so Queue can
+  # wait for all of them. A gated job queues only when its change touches the gate, else it is skipped.
+  aggregate "Job" do
+    description "One job of one build: what it waits for, and whether it was queued, started, passed, failed, or skipped by its gate."
+
+    identified_by :name
+
+    reference_to CiRun, as: :build
+    attribute :name,        JobName
+    attribute :required,    Switch
+    attribute :gate,        GateName
+    attribute :needs_total, Count
+    attribute :needs_settled, Count
+    attribute :seconds,     JobSeconds
+
+    lifecycle :status, default: "waiting" do
+      transition "Queue" => "queued",  from: "waiting"
+      transition "Start" => "running", from: "queued"
+      transition "Pass"  => "passed",  from: "running"
+      transition "Fail"  => "failed",  from: "running"
+      transition "Skip"  => "skipped", from: ["waiting", "queued"]
+    end
+
+    value_object "BuildId" do
+      attribute :value, String, matches: :present
+      invariant("a build is identified") { !value.to_s.empty? }
+    end
+
+    value_object "JobName" do
+      attribute :value, String, matches: :present
+      invariant("a job is named") { !value.to_s.empty? }
+    end
+
+    value_object "Switch" do
+      attribute :value, Boolean
+    end
+
+    value_object "GateName" do
+      attribute :value, String, default: ""
+    end
+
+    value_object "Count" do
+      attribute :value, Integer, default: 0
+      invariant("a count is not negative") { !value.negative? }
+    end
+
+    value_object "JobSeconds" do
+      attribute :value, Integer, default: 0
+      invariant("a job's wall time is not negative") { !value.negative? }
+    end
+
+    command "Declare" do
+      role "CI engineer"
+      goal "Write down one job of a build, the edges into it, and whether a gate can skip it"
+
+      reference_to CiRun, as: :build
+      attribute :name,        JobName
+      attribute :required,    Switch
+      attribute :gate,        GateName
+      attribute :needs_total, Count
+
+      sets :build
+      sets :name
+      sets :required
+      sets :gate
+      sets :needs_total
+
+      emits "JobDeclared"
+    end
+
+    # One edge into this job is met: its upstream passed, was skipped by its gate, or its corpus is
+    # ready. Refused once every edge is met, so an extra edge cannot queue the job early.
+    command "Satisfy" do
+      role "CI engineer"
+      goal "Count one edge into a job as met"
+
+      reference_to Job
+
+      given("an edge is met once") { needs_settled.value < needs_total.value }
+
+      sets :needs_settled, increment: { value: 1 }
+
+      emits "Satisfied"
+    end
+
+    # A job queues only once every edge into it is met. A gated job queues only when its change
+    # touches the gate; otherwise Skip is the answer.
+    command "Queue" do
+      role "CI engineer"
+      goal "Queue a job once every job it needs has passed or been skipped"
+
+      reference_to Job
+      attribute :touched, Switch
+
+      given("every need is settled first") { needs_settled.value == needs_total.value }
+      given("a gated job queues only when its change touches the gate") do
+        gate.value.empty? || touched.value
+      end
+
+      emits "Queued"
+    end
+
+    command "Start" do
+      role "CI engineer"
+      goal "Start a queued job on its runner"
+
+      reference_to Job
+
+      emits "Started"
+    end
+
+    command "Pass" do
+      role "CI engineer"
+      goal "Record that a job passed, with its wall time and whether it was required"
+
+      reference_to Job
+      attribute :of_job,       JobName
+      attribute :was_required, Switch
+      attribute :of_build,     BuildId
+      attribute :seconds,  JobSeconds
+
+      given("the restated name is the job's own") { of_job.value == name.value }
+      given("the restated flag is the job's own") { was_required.value == required.value }
+      given("the restated build is the job's own") { of_build.value == build }
+
+      sets :seconds
+
+      emits "Passed"
+    end
+
+    command "Fail" do
+      role "CI engineer"
+      goal "Record that a job failed, with its wall time and whether it was required"
+
+      reference_to Job
+      attribute :was_required, Switch
+      attribute :of_build,     BuildId
+      attribute :seconds,  JobSeconds
+
+      given("the restated flag is the job's own") { was_required.value == required.value }
+      given("the restated build is the job's own") { of_build.value == build }
+
+      sets :seconds
+
+      emits "Failed"
+    end
+
+    # A gate skips its job only when the change does not touch what the gate guards.
+    command "Skip" do
+      role "CI engineer"
+      goal "Skip a gated job, because the change does not touch what its gate guards"
+
+      reference_to Job
+      attribute :of_job,       JobName
+      attribute :was_required, Switch
+      attribute :of_build,     BuildId
+      attribute :touched,  Switch
+
+      given("the restated name is the job's own") { of_job.value == name.value }
+      given("the restated flag is the job's own") { was_required.value == required.value }
+      given("the restated build is the job's own") { of_build.value == build }
+      given("a gate skips its job only when the change does not touch it") do
+        !gate.value.empty? && !touched.value
+      end
+
+      emits "Skipped"
+    end
+
+    query "Waiting" do
+      description "Jobs not yet queued, by build."
+      where(status: "waiting")
+      order_by :build
+    end
+  end
+
+  # One CI run of one commit. It passes only when every required job has passed or been skipped by
+  # its gate, and fails when one required job fails. Required jobs are counted as they land.
+  aggregate "CiRun" do
+    description "One CI run of one commit: how many of its required jobs passed, were skipped, or failed, and whether the run passed or failed."
+
+    identified_by :build
+
+    attribute :build,          BuildId
+    attribute :commit,         CommitSha
+    attribute :required_total, Count
+    attribute :passed,         Count
+    attribute :skipped,        Count
+    attribute :failed,         Count
+
+    lifecycle :status, default: "pending" do
+      transition "Start" => "running", from: "pending"
+      transition "Pass"  => "passed",  from: "running"
+      transition "Fail"  => "failed",  from: ["pending", "running"]
+    end
+
+    value_object "BuildId" do
+      # A GitHub run id for a CI run on GitHub, or a local run's own id.
+      attribute :value, String, matches: :present
+      invariant("a build is identified") { !value.to_s.empty? }
+    end
+
+    value_object "CommitSha" do
+      # A full or abbreviated git commit hash, lowercase hex.
+      attribute :value, String, pattern: '^[0-9a-f]{7,40}$'
+    end
+
+    value_object "Count" do
+      attribute :value, Integer, default: 0
+      invariant("a count is not negative") { !value.negative? }
+    end
+
+    value_object "Document" do
+      attribute :text, String
+    end
+
+    command "Open" do
+      role "CI engineer"
+      goal "Open a build of one commit, with the number of required jobs it waits for"
+
+      attribute :build,          BuildId
+      attribute :commit,         CommitSha
+      attribute :required_total, Count
+
+      sets :build
+      sets :commit
+      sets :required_total
+
+      emits "BuildOpened"
+    end
+
+    command "Start" do
+      role "CI engineer"
+      goal "Start a build's jobs running"
+
+      reference_to CiRun
+
+      emits "BuildStarted"
+    end
+
+    command "CountPass" do
+      role "CI engineer"
+      goal "Count one required job as passed"
+
+      reference_to CiRun
+
+      given("a pass is counted while the build runs") { status == "running" }
+
+      sets :passed, increment: { value: 1 }
+
+      emits "PassCounted"
+    end
+
+    command "CountSkip" do
+      role "CI engineer"
+      goal "Count one required job as skipped by its gate, which settles it"
+
+      reference_to CiRun
+
+      given("a skip is counted while the build runs") { status == "running" }
+
+      sets :skipped, increment: { value: 1 }
+
+      emits "SkipCounted"
+    end
+
+    command "CountFailure" do
+      role "CI engineer"
+      goal "Count one required job as failed"
+
+      reference_to CiRun
+
+      given("a failure is counted while the build runs") { status == "running" }
+
+      sets :failed, increment: { value: 1 }
+
+      emits "FailureCounted"
+    end
+
+    # Refused until every required job is settled and none failed. That refusal is the answer
+    # "not yet", and the build keeps running.
+    command "Pass" do
+      role "CI engineer"
+      goal "Mark the build passed, once every required job passed or was skipped and none failed"
+
+      reference_to CiRun
+
+      given("every required job passed or was skipped by its gate") do
+        passed.value + skipped.value == required_total.value
+      end
+      given("no required job failed") { failed.value == 0 }
+
+      emits "BuildPassed"
+    end
+
+    command "Fail" do
+      role "CI engineer"
+      goal "Mark the build failed, because a required job failed"
+
+      reference_to CiRun
+
+      given("a required job failed") { failed.value > 0 }
+
+      emits "BuildFailed"
+    end
+
+    # The answer the runner gives for one build: its jobs' wall times and conclusion. An adapter
+    # answers it; this bluebook never fetches.
+    query "Reading" do
+      description "One build as the runner reports it: each job's wall time and the conclusion. An adapter answers it; this bluebook never fetches."
+      attribute :build, BuildId
+      returns Document
+    end
+
+    # The chain of jobs, each waiting on the one before, whose wall times add up to the build's.
+    # An adapter computes it from the Job seconds and the needs policies; this bluebook only asks.
+    query "CriticalPath" do
+      description "The chain of jobs that sets a build's wall time, from Job seconds and the needs edges. An adapter answers it."
+      attribute :build, BuildId
+      returns Document
+    end
+
+    query "All" do
+      description "Every build, by build id."
+      order_by :build
+    end
+  end
+
+  # The generated Rust a build's jobs share, addressed by a key derived from its named inputs. A
+  # miss regenerates it once, and every job that needs it waits for that one regeneration.
+  aggregate "Corpus" do
+    description "The generated Rust one build shares: its cache key, whether the cache held it, and whether it was regenerated and saved."
+
+    identified_by :build
+
+    attribute :build, BuildId
+    attribute :key,   CacheKey
+
+    lifecycle :status, default: "unknown" do
+      transition "Hit"         => "ready",   from: "unknown"
+      transition "Miss"        => "missing", from: "unknown"
+      transition "Materialize" => "ready",   from: "missing"
+    end
+
+    value_object "BuildId" do
+      attribute :value, String, matches: :present
+      invariant("a build is identified") { !value.to_s.empty? }
+    end
+
+    # The cache address: a hex SHA-256 of the named inputs.
+    value_object "CacheKey" do
+      attribute :value, String, pattern: '^[0-9a-f]{64}$'
+    end
+
+    value_object "Document" do
+      attribute :text, String
+    end
+
+    command "Open" do
+      role "CI engineer"
+      goal "Open the corpus a build shares, under the cache key of its inputs"
+
+      attribute :build, BuildId
+      attribute :key,   CacheKey
+
+      sets :build
+      sets :key
+
+      emits "CorpusOpened"
+    end
+
+    command "Hit" do
+      role "CI engineer"
+      goal "Record that the cache held the corpus, so no job regenerates it"
+
+      reference_to Corpus
+
+      emits "Hit"
+    end
+
+    command "Miss" do
+      role "CI engineer"
+      goal "Record that the cache did not hold the corpus, so it must be regenerated"
+
+      reference_to Corpus
+
+      emits "Miss"
+    end
+
+    # Once only: a second Materialize is refused, because the corpus is already ready.
+    command "Materialize" do
+      role "CI engineer"
+      goal "Record that the corpus was regenerated, once for every job that shares it"
+
+      reference_to Corpus
+
+      emits "Materialized"
+    end
+
+    command "Save" do
+      role "CI engineer"
+      goal "Save a regenerated corpus under its key, so the next build hits"
+
+      reference_to Corpus
+
+      given("only a ready corpus is saved") { status == "ready" }
+
+      emits "Saved"
+    end
+
+    # The answer the cache gives for one key. An adapter answers it.
+    query "Lookup" do
+      description "Whether the cache holds the corpus for a key. An adapter answers it."
+      attribute :key, CacheKey
+      returns Document
+    end
+  end
+
+  # Edges into ci-rspec.yml's rspec_shard job. Each edge is declared once, here, and is the only
+  # source of `needs:` for that job. The attestation edge is met by a pass or by a skip.
+  policy "SatisfyRspecShardOnAttestationPassed" do
+    on      "Job.Passed"
+    where   { of_job.value == "ci_attestation_rspec" }
+    trigger Job::Satisfy, with: { job: "rspec_shard" }
+  end
+
+  policy "SatisfyRspecShardOnAttestationSkipped" do
+    on      "Job.Skipped"
+    where   { of_job.value == "ci_attestation_rspec" }
+    trigger Job::Satisfy, with: { job: "rspec_shard" }
+  end
+
+  # The corpus edge is met by a hit, or by a regeneration after a miss.
+  policy "SatisfyRspecShardOnCorpusHit" do
+    on      "Corpus.Hit"
+    trigger Job::Satisfy, with: { job: "rspec_shard" }
+  end
+
+  policy "SatisfyRspecShardOnCorpusMaterialized" do
+    on      "Corpus.Materialized"
+    trigger Job::Satisfy, with: { job: "rspec_shard" }
+  end
+
+  # A miss regenerates the corpus once; the jobs that share it wait on that one regeneration.
+  policy "MaterializeOnCorpusMiss" do
+    on      "Corpus.Miss"
+    trigger Corpus::Materialize, with: { corpus: :build }
+  end
+
+  # Only required jobs are counted toward their build.
+  policy "CountRequiredPass" do
+    on      "Job.Passed"
+    where   { was_required.value }
+    trigger CiRun::CountPass, with: { build: :of_build }
+  end
+
+  policy "CountRequiredSkip" do
+    on      "Job.Skipped"
+    where   { was_required.value }
+    trigger CiRun::CountSkip, with: { build: :of_build }
+  end
+
+  policy "CountRequiredFailure" do
+    on      "Job.Failed"
+    where   { was_required.value }
+    trigger CiRun::CountFailure, with: { build: :of_build }
+  end
+
+  # Refused until every required job is settled, which is the "not yet" answer.
+  policy "PassBuildOnPassCounted" do
+    on      "CiRun.PassCounted"
+    trigger CiRun::Pass, with: { build: :build }
+  end
+
+  policy "PassBuildOnSkipCounted" do
+    on      "CiRun.SkipCounted"
+    trigger CiRun::Pass, with: { build: :build }
+  end
+
+  policy "FailBuildOnFailureCounted" do
+    on      "CiRun.FailureCounted"
+    trigger CiRun::Fail, with: { build: :build }
+  end
+end