C9b: bind the rotation kernel to the GitHub App key, with an exact-version verifier

[gunbai-bot]

C9b: the gunbai-ci GitHub App private key (ci-github-app-private-key) becomes the first real subject of the rotation kernel gunbc.auth.secret_rotation, with a verifier that checks one exact key version on demand.

The kernel has NOT actuated. This PR adds nothing that performs add-version or disable. The frontier row in gunbc.doc_graph_roots (secret-version-lifecycle) now says so and names the missing capability: the operator's first live rotation, with a human in the loop.

What lands

• gunbc.auth.ci_app_key_rotation (new module):
  • ci_app_key_rotation_intent: ReceivedOutOfBand (GitHub only creates App private keys in the App settings page; no REST endpoint does), DisableOnly, and a one-consumer roster pinned to the exact new version.
  • ci_app_key_contract: the protection contract, attached to the real subject. Each field is read by something:
    • rotate_by is read by rotation_deadline_standing on every verify run. A passed or unorderable deadline refuses.
    • loss_remedy (reissue at the App settings page) is rendered into the unreadable-key and 401 refusals.
    • restore_test binds the rostered consumer, and the intent's roster is built from it. The retirement plan refuses unless that consumer is proven on the exact new version.
  • verify_app_key_version returns a typed verdict over what the mint observed. It refuses:
    • the alias latest, an empty selector, or anything that is not a version number;
    • an unreadable version, with the HTTP status;
    • a response naming a different version (the join uses resolved_identity_matches_request, so project-number spellings are accepted);
    • a missing or non-201 installation-token exchange.
  • app_key_verdict_evidence turns the verdict into consumer evidence for the kernel: ResolvedVersionObserved when the key mints, ConsumerUnreachable with the cause when it doesn't. It is never success-only.
• fleet-converge mode app_key_version_verify, with a new app_key_version dispatch input:
  • Mints one installation token with versions/N through the same prelude the org-admin step uses. The verifier is one more AppInstallationTokenMint spec on main's github_app_installation_token_prelude (Heal publishes through a credential-isolated boundary, as an App that already existed #11547), with the key ref at the exact version and a new optional observation_record field, so there is still one place key material is written, with the same umask 077, chmod 600 and trap cleanup.
  • The regenerated org_actions_observe and heal-publisher steps are byte-identical.
  • A shell guard admits only a positive decimal version number before the URL is built. The .dag verdict re-applies the same rule (extdeps.cloud.gcp.secret_manager sm_version_id_is_number).
  • The verdict step runs on always(), so a refused mint still gets a typed verdict and a receipt. The receipt is uploaded as the app-key-version-verify artifact.
  • Cost: zero on any run that doesn't select this mode. It is a mode, not a job, and there is no skip toggle.
  • It mutates nothing: no add-version, no disable, no destroy, no GitHub write.
• Kernel:
  • New plan_rotation_retirement puts the read-back first; consumer proofs are joined against the identity that read-back confirmed.
  • Defect fixed: authorize_retirement authorized DisableOnly retirement over an empty roster. A census over zero names is vacuously complete. It now refuses as RetirementCensusReachedNoOne { CensusReachedNoOne { roster_size: 0 } }.

Evidence

test.claim.ci_app_key_rotation_witness, 16 witnesses, each run with the locally built interpreter via gunbc run --function; all returned true.

• Discriminating reds:
  • A 401 mint refuses the rotation, with the cause carried through and no targets, so the prior version stays enabled.
  • A read-back of another version refuses.
  • A payload mismatch refuses.
  • An empty roster refuses as CensusReachedNoOne.
• Verifier reds: alias, non-number, 404, a response about another version, a 401, and a missing token observation.
• Positive control: a mint on v7 plus a confirmed read-back retires exactly v6, with destroy not permitted.
• Empty-roster red confirmed against the old kernel: in a scratch copy with the roster check removed, the witness returned false. The other reds call symbols that don't exist before this change, so they fail to compile there.

For the operator

• rotate_by: 2026-12-18T00:00:00Z is a proposed policy value, 90 days out. Please set it. A completed rotation should move it forward.
• Next act, safe now: dispatch app_key_version_verify with the currently enabled version number. That is the first restore rehearsal, and it answers "does the key in version N actually mint", which nothing could answer before this PR.
• The first live rotation stays an operator act:
  1. Generate a new key in the App settings.
  2. Add it as a new version, once.
  3. Verify that exact version with this mode.
  4. Disable the prior version and read it back.

Out of scope, not touched: the org-admin credential deletion (org_admin_credential is still imported by the shared prelude for its two message functions; that lane owns their move), #11689, #11678.

🤖 Generated with Claude Code