# Steps `dev/ci_contract.py` permits to name a tool, and the reason each does.
#
# An entry is `workflow.yml:Step name`, or a bare `workflow.yml` for a lane
# whose conversion has not started. Every line is a debt with an owner, not a
# dispensation: the file exists so the unconverted surface is a number someone
# can burn down instead of a silence.

# --- runner-plane -----------------------------------------------------------
# Acts on the MACHINE, not the product, so there is no local recipe it could
# be hiding. These belong with the runner fleet's own job hooks and
# operations.
binaries.yml:Return the workspace to the runner's user
acquisition.yml:Return the workspace to the runner's user
acquisition.yml:Install what acquisition itself needs
hardware.yml:Put Homebrew and user binaries on PATH

# --- pending ----------------------------------------------------------------
# The three interpreter heredocs and the raw vault check that stood here are
# gone. The heredocs became `dev/guards/test_interpreter_pin.py`, which
# asserts more than they did and holds on every platform and on a laptop; the
# vault check became `just check-vault` and joined `check-all`, which is what
# retired the job that existed only to run it.

# The GPU tier's environment: provision the pinned Qdrant binary, start and
# stop the resident service behind a 25-line pwsh poll loop. Recipes needed:
# `rag-service-start`, `rag-service-stop` - which vaultspec-a2a already has by
# those exact names, over the same service.
hardware.yml:Provision the pinned Qdrant binary the GPU tier requires
hardware.yml:Start the resident service the GPU tier borrows from
hardware.yml:Stop the resident service

# The distribution smoke check, run by path against a built wheel and sdist.
# Recipe needed: `test-smoke` - vaultspec-core and cadrumo have the same two
# steps, against the same kind of artifact, with three different spellings.
publish.yml:Smoke test (wheel)
publish.yml:Smoke test (sdist)

# Release-plane bookkeeping that is genuinely CI-only (`gh` calls, a checksum
# aggregation over downloaded artifacts, a push to the channel root) mixed
# with work that should be a recipe. Recipes needed:
# `release-checksums` (the inherited-SHA merge, duplicated in vaultspec-core),
# `release-publish` (the tap commit and its push-retry loop).
binaries.yml:Aggregate checksums
binaries.yml:Commit the Scoop manifest and Homebrew formula
binaries.yml:Require artifacts on the published release
binaries.yml:Ask the acquisition check to try this release
binaries.yml:Promote a repaired release back to latest
publish.yml:Generate checksums
publish.yml:Publish to PyPI
publish.yml:Hold the release as a prerelease
release-please.yml:Regenerate and push uv.lock
release-please.yml:Dispatch the merge gate for the release pull request
publish.yml:Trigger Binaries workflow

# Downloads the published binary onto a machine with no checkout and asks
# whether the dynamic loader accepts it. Recipe needed: `test-acquisition`,
# shared in shape with vaultspec-core's three-OS version of the same lane.
acquisition.yml:Acquire the published binaries
acquisition.yml:The loader must accept them
acquisition.yml:Extract the stable executables
acquisition.yml:The loader must accept the extracted executables

# Provisions the interpreter for a job that never enters the project
# environment: the binaries build runs under a bare `--no-project` python by
# design, and the smoke test installs the matrix interpreter to run an
# isolated wheel. `just init` would build a project venv neither one uses.
binaries.yml:Install Python
publish.yml:Install Python

# These release steps intentionally retain shell-level artifact and GitHub
# bookkeeping: they consume the release event and cannot be reproduced by a
# local recipe without changing the publication boundary.
binaries.yml:Build the wheel
binaries.yml:Validate the wheel matches the release tag
binaries.yml:Assert every declared target archive ready
release-please.yml:Hold the release out of latest until artifacts are complete
release-please.yml:Trigger Publish workflow

# Turns the merge gate's job results, or an earlier gate check on the same
# commit, into the one required verdict. It reads GitHub's own check state,
# which has no local meaning, so there is no recipe it could be hiding.
merge-gate.yml:Every full check passed on this commit

# These steps bind release validation to the commit selected from the tag.
# They are Git identity bookkeeping, not a reusable source validation command.
# The two resolvers run on a hosted runner with no checkout, so no recipe
# exists there to call: they read the public remote before anything executes.
publish.yml:Resolve exact release SHA
binaries.yml:Require a release tag that resolves to the requested commit
hardware.yml:Require the exact commit
publish.yml:Require the exact release commit
binaries.yml:Require the exact release commit
binaries.yml:Require the acquisition check for this release

# Reads the fleet's own scheduling state before any work is dispatched to it:
# one derives the selectors from the matrix at the release commit, the other
# asks GitHub which runners carry them and are online. Neither describes the
# product, and the preflight body is a generated block shared across the fleet
# whose parity check requires it byte-identical, so neither can become a local
# recipe without breaking what it is for.
binaries.yml:Derive every selector the build matrix names
binaries.yml:Every required selector has an online runner
