@1aboveio/skills 0.10.0

package/skills/engineering/resolve-release/scripts/candidate-identity.mjs

@@ -0,0 +1,904 @@
+// candidate-identity — deterministic, fail-closed candidate discovery for the release lane (issue #433).
+//
+// Principle 12's "out" clause used to end at "revision name and URL discoverable", and step 3
+// then had to WARN that the `candidate` tag URL means "the newest candidate", not "the one I
+// built" — a warning an agent must remember to act on, at exactly the point where a wrong
+// answer validates one candidate under another's identity. This script replaces the warning
+// with a comparison: the tag is keyed to the SHA, the revision and URL come from ONE traffic
+// entry, and the running process attests the tuple. A disagreement becomes an absent or
+// ambiguous read the script REFUSES, not a discrepancy a reader has to notice.
+//
+// Three subcommands, because the sequence really has three steps and the middle one is a
+// network read this script must not take on (principle 12 assigns platform reads to the
+// release lane; a script that shells out to gcloud/curl has taken on deploy mechanics):
+//
+//   candidate-identity.mjs locate  --sha <shipped> --traffic <flattened-traffic>
+//       Selects THE candidate traffic entry — the row tagged `candidate-<short-sha>` for the
+//       promoted SHA — and emits its tag, url, revision and percent. Missing, ambiguous, or a
+//       foreign candidate tag (a second release in flight, principle 7) all REFUSE.
+//   candidate-identity.mjs attest  --sha <shipped> --locate <locate.json> --health <health.json>
+//       Binds the located coordinates to the identity the RUNNING PROCESS attests: source SHA,
+//       revision name, image digest. Emits `release.candidateIdentity` for the manifest.
+//   candidate-identity.mjs serving --sha <shipped> --identity <candidateIdentity.json> --health <live-health.json>
+//       Step 4b's post-shift confirmation: the live service attests the SAME tuple. This is what
+//       replaced comparing image-tag strings — the tuple carries the SHA, the revision AND the
+//       digest, and it comes from the process rather than from the revision's spec.
+//
+// Every subcommand after the first is handed an artifact the previous one wrote, and each one
+// cross-checks that artifact against the identity it CLAIMS to describe before using it — see
+// `tagBacksGuarantee`. Without that, "the record and the live process agree" is a true statement
+// about the wrong release.
+//
+// Contract:
+//   exit 0 = ACCEPT  — identity established (or established under a DECLARED weakening).
+//   exit 1 = REFUSE  — the release stops here; the specific failing ids are named in `failed`.
+//   exit 2 = usage / unreadable-input error — bad flags, unknown subcommand, missing required file.
+//
+// FAIL CLOSED is the invariant, and it has a floor: identity rests on two legs — a SHA-keyed
+// tag and a health attestation — and a repo whose pipeline cannot provide one DECLARES that
+// (`--declare-shared-candidate-tag` / `--declare-no-attestation`, pre-flight item 3), which
+// records the weakened guarantee in the artifact instead of leaving it assumed. An UNdeclared
+// missing leg refuses. BOTH legs missing refuses even when both are declared: nothing keys
+// identity at all then, and a declaration is a statement about a weaker guarantee, never a
+// waiver of the whole check.
+//
+// And a declaration owes a SUBSTITUTE, not just a reason — see `evaluateAttest`'s
+// `e:no-fallback-digest`. A declared weakening has to leave the operator with a check they can
+// actually run; a branch that accepts and records a field the doctrine then sends someone to
+// compare against, having set it to `null`, is worse than one that refuses, because it looks
+// complete. That is the rule this file holds in every branch: **every field of a recorded
+// identity is populated in every branch that accepts, or that branch refuses.**
+//
+// Its other half, and the one that was missing: a field is not made trustworthy by the branch
+// that WROTE it, because the artifact carrying it can be stale, truncated or hand-edited by the
+// time the next subcommand reads it. So **every field an identity record carries is re-derived or
+// revalidated at the hand-off that carries it** — see the field walk below `tagBacksGuarantee`.
+// Re-deriving only the SHA and the tag left an accepted locate artifact with `url: null` minting
+// a candidateIdentity with a hole in it, at exit 0.
+
+import fs from 'node:fs'
+import { parseTraffic, normalizeTrafficPercents, str } from './candidate-traffic.mjs'
+
+export { parseTraffic, normalizeTrafficPercents } from './candidate-traffic.mjs'
+import { isMainModule } from '../../engineering-runtime/scripts/main-module.mjs'
+
+// A short SHA is 7 hex chars (Cloud Build's $SHORT_SHA, git's default abbreviation). Below
+// that, a "prefix match" stops being evidence of anything — 4 hex chars collide across a
+// day's builds — so a shorter tag suffix is not treated as SHA-keyed at all.
+export const MIN_SHORT_SHA = 7
+
+// The floor lives HERE and nowhere else: every SHA this script reads — the shipped SHA, a tag
+// suffix, an attested `sourceSha` — goes through this predicate, so the minimum is enforced
+// once rather than re-asserted per call site. (It was re-asserted in shaMatches at first, where
+// it was unreachable — both operands are already ≥ MIN_SHORT_SHA by the time they get there —
+// and a guard that cannot fire reads as protection while providing none.)
+const SHA_RE = new RegExp(`^[0-9a-f]{${MIN_SHORT_SHA},40}$`, 'i')
+const isSha = (s) => typeof s === 'string' && SHA_RE.test(s)
+
+// Two SHAs identify the same commit when one is a prefix of the other. Health endpoints
+// commonly report $SHORT_SHA while the release lane carries the full one, so an equality-only
+// comparison would fail closed on every healthy release — the wrong kind of strict.
+export function shaMatches(a, b) {
+  if (!isSha(a) || !isSha(b)) return false
+  const [x, y] = [a.toLowerCase(), b.toLowerCase()]
+  const short = x.length <= y.length ? x : y
+  const long = short === x ? y : x
+  return long.startsWith(short)
+}
+
+// An image DIGEST, not an image tag. `algorithm:hex` is the registry-wide form, and requiring
+// it is the point of the field: `myapp:latest` and `myapp:$SHA` are tags — mutable pointers a
+// registry can re-point — and accepting one here would re-admit exactly the image-TAG string
+// comparison the attested tuple replaced.
+const isDigest = (s) => typeof s === 'string' && /^[a-z0-9][a-z0-9+.-]*:[0-9a-f]{32,}$/i.test(s)
+
+// Digest hex is case-insensitive, and `isDigest` accepts either case — so the comparison must
+// too. An endpoint echoing `SHA256:AB…` is naming the SAME artifact, and a strict `!==` would
+// refuse a healthy release on a rendering choice. It fails closed, so it is safe; it is still
+// wrong, and a fail-closed bug spends a release cycle to discover.
+const digestMatches = (a, b) =>
+  typeof a === 'string' && typeof b === 'string' && a.toLowerCase() === b.toLowerCase()
+
+// The candidate's tagged endpoint. A shape, not mere non-emptiness: this is the field the
+// doctrine sends the operator to curl, and `""`, `"n/a"` and `"-"` are all truthy-or-nearly so
+// while naming nothing. A field that cannot be dereferenced is the same defect as a null one —
+// it just survives a truthiness check.
+const isUrl = (s) => typeof s === 'string' && /^https?:\/\/\S+$/i.test(s.trim())
+
+// ---- locate ----
+
+// Does this tag key the candidate to a specific commit, and is that commit ours?
+const DEFAULT_CANDIDATE_TAG_PREFIX = 'candidate-'
+
+function validCandidateTagPrefix(prefix) {
+  return typeof prefix === 'string' && /^[a-z][a-z0-9-]{0,30}-$/.test(prefix)
+}
+
+function classifyTag(tag, sha, candidateTagPrefix = DEFAULT_CANDIDATE_TAG_PREFIX) {
+  if (tag === 'candidate') return 'shared'
+  if (!validCandidateTagPrefix(candidateTagPrefix) || !tag.startsWith(candidateTagPrefix)) {
+    return 'other'
+  }
+  const suffix = tag.slice(candidateTagPrefix.length)
+  if (!/^[0-9a-f]{4,40}$/i.test(suffix)) return 'other'
+  // A suffix below MIN_SHORT_SHA is not SHA-keyed at all (isSha rejects it, so shaMatches is
+  // false) — and it is not a rival either: `candidate-abc123` collides across a day of builds,
+  // so calling it another release's tag would refuse healthy releases on a coincidence.
+  if (!isSha(suffix)) return 'other'
+  return shaMatches(suffix, sha) ? 'ours' : 'foreign'
+}
+
+// ---- the cross-artifact rule (used by attest AND serving) ----
+//
+// THE CLASS: **every identity artifact that flows between subcommands is cross-checked against
+// the identity it claims to describe — in every branch, including the DECLARED weakenings,
+// which are exactly the branches where the other comparisons are absent.**
+//
+// A subcommand that reads a `guarantee` field and believes it has verified nothing. The tag and
+// the SHA carried in the same artifact are the evidence for that claim, so both are re-derived
+// at every hand-off rather than taken at their word. Two comparisons, one per leg:
+//
+//   - the artifact's own SHA against the SHA this subcommand was given — a stale artifact from
+//     an earlier rc describes a different commit, and nothing else notices;
+//   - the artifact's tag against the guarantee it claims — `shaKeyedTag: true` is backed only by
+//     a tag keyed to THIS commit (`ours`), and `shaKeyedTag: false` only by the shared
+//     `candidate` tag. Anything else is an artifact whose claim its own coordinates contradict.
+//
+// What it was missing (the bug this closes): `attest` never compared its `--sha` against the
+// locate artifact's. In the attested branch the tuple comparisons masked it; under
+// `--declare-no-attestation` nothing did. rc.1 dies at SHA_X after `locate` wrote its artifact,
+// the retry mints rc.2 at SHA_Y, a resumed session runs `attest --sha $SHIPPED` (now Y) against
+// X's artifact — and it ACCEPTED, recording `sourceSha: Y` over X's revision, url and tag under
+// `shaKeyedTag: true`. Step 4b then verified X's tag→revision agreement and the digest fallback
+// had no digest to compare, so the release validated one candidate under another's identity.
+export function tagBacksGuarantee(
+  tag,
+  sha,
+  shaKeyedTag,
+  candidateTagPrefix = DEFAULT_CANDIDATE_TAG_PREFIX,
+) {
+  const kind = classifyTag(str(tag), sha, candidateTagPrefix)
+  return shaKeyedTag ? kind === 'ours' : kind === 'shared'
+}
+
+// ---- the field walk (the general form of the rule above) ----
+//
+// THE RULE the table below exists to serve: **every field an identity record carries is
+// re-derived or revalidated at the hand-off that carries it — never carried across on the
+// strength of the upstream artifact's `decision`.** How far that rule is MECHANIZED is stated
+// under the table, and it is not as far as the rule reaches.
+//
+// `tagBacksGuarantee` closed two fields, the SHA and the tag, and stopping there is what let the
+// rest through. An ACCEPTED locate artifact whose `candidate.url` is `null` — stale, hand-edited,
+// or written by an older build of this script — walked straight past `attest`, which re-derived
+// the SHA and the tag, found both fine, and minted a candidateIdentity carrying `url: null` at
+// exit 0. Every downstream reader treats that record as complete, and the one field the operator
+// is sent to dereference is the hole. "Check the SHA and the tag" was never the rule; it was two
+// instances of it.
+//
+// So the walk is expressed as a table rather than a run of `if`s: a field added to either record
+// has to appear here, or it is being carried on trust again. Each row is (field, predicate,
+// failure id) — the predicate takes the value and the context needed to re-derive it, because
+// "revalidate" for `tag` means re-deriving it against the promoted SHA, not checking that a
+// string is present.
+//
+// HOW FAR THIS GOES. The table is HAND-KEPT and nothing detects an omission from it: a field a
+// record carries with no row here crosses UNWALKED, and an ACCEPT says nothing about it. "Every
+// field is revalidated" is therefore the obligation on whoever adds a field, not a property this
+// file enforces — which is why `--help` states the rule at the table's width and sends the reader
+// to regression-checklist row 4a rather than to this exit code. #452 replaces the table with a
+// structurally-validated schema, in which an unrevalidated field cannot exist to be omitted.
+
+// Fields of a locate artifact's candidate entry that flow into candidateIdentity.
+const LOCATE_HANDOFF_FIELDS = [
+  ['tag', (v, { sha, shaKeyedTag, candidateTagPrefix }) =>
+    tagBacksGuarantee(v, sha, shaKeyedTag, candidateTagPrefix), 'e:locate-guarantee-unbacked'],
+  ['url', (v) => isUrl(v), 'e:locate-entry-incomplete'],
+  ['revision', (v) => str(v).length > 0, 'e:locate-entry-incomplete'],
+]
+
+// Fields of a candidateIdentity record, revalidated where `serving` consumes it.
+const IDENTITY_RECORD_FIELDS = [
+  // Two different questions, deliberately two ids: `sourceSha` asks whether this record is THIS
+  // release's, and everything below asks whether the record is self-consistent — so the tag is
+  // checked against the record's OWN sourceSha, not the promoted one, or a stale artifact would
+  // report its every field as broken instead of reporting that it is the wrong artifact.
+  ['sourceSha', (v, { sha }) => shaMatches(v, sha), 'e:identity-sha-mismatch'],
+  ['tag', (v, { recordSha, shaKeyedTag, candidateTagPrefix }) =>
+    tagBacksGuarantee(v, recordSha, shaKeyedTag, candidateTagPrefix), 'e:identity-guarantee-unbacked'],
+  ['imageDigest', (v) => isDigest(v), 'e:identity-guarantee-unbacked'],
+  // WHERE the digest came from is the difference the weakening makes, so it is backed by the
+  // guarantee like everything else: an attested record whose digest is labelled a revision spec
+  // (or the reverse) is telling a reader which comparison they got, wrongly.
+  ['imageDigestSource', (v, { attested }) => v === (attested ? 'attestation' : 'candidate-revision-spec'),
+    'e:identity-guarantee-unbacked'],
+  ['url', (v) => isUrl(v), 'e:identity-record-incomplete'],
+  ['revision', (v) => str(v).length > 0, 'e:identity-record-incomplete'],
+]
+
+// The legs a weakening can be declared on, and the `guarantee` flag each one weakens.
+const WEAKENING_LEGS = [
+  ['sha-keyed-tag', 'shaKeyedTag'],
+  ['health-attestation', 'attested'],
+]
+
+// `guarantee` and `weakenings` are two halves of one statement — the flag and the reason — so
+// each is the evidence for the other and neither is carried alone. A record claiming
+// `shaKeyedTag: false` with an empty `weakenings` is a weakening with no reason recorded, which
+// is the assumption the declaration flags exist to replace; a `weakenings` entry with no matching
+// flag claims a weaker guarantee than the record admits to. Both are stated-vs-actual gaps of the
+// same kind as an unbacked tag.
+export function weakeningsBackGuarantee(weakenings, guarantee, legs = WEAKENING_LEGS) {
+  if (!Array.isArray(weakenings)) return false
+  const g = guarantee && typeof guarantee === 'object' ? guarantee : {}
+  for (const w of weakenings) {
+    if (!w || typeof w !== 'object') return false
+    if (!legs.some(([leg]) => leg === w.leg)) return false
+    // A declaration's REASON is the whole value of declaring — the same rule `declaration()`
+    // enforces at the CLI, re-enforced here because a hand-edited artifact never went through it.
+    if (str(w.reason).length === 0) return false
+  }
+  for (const [leg, flag] of legs) {
+    if (!(flag in g)) continue
+    if (weakenings.some((w) => w.leg === leg) !== (g[flag] === false)) return false
+  }
+  return true
+}
+
+// Run a field table, appending each distinct failure id once and recording what was walked, so
+// the artifact shows which fields were revalidated rather than only which ones failed.
+function walkFields(table, source, ctx) {
+  const failed = []
+  const walked = {}
+  for (const [field, ok, id] of table) {
+    const passed = !!ok(source ? source[field] : undefined, ctx)
+    walked[field] = passed
+    if (!passed && !failed.includes(id)) failed.push(id)
+  }
+  return { failed, walked }
+}
+
+// The locate -> attest hand-off, walked field by field. `locate.decision` is trusted (this side
+// has no traffic read to re-derive it from) but every FACT that decision gated is re-established
+// here, so a stale, truncated or edited artifact refuses instead of being believed.
+export function walkLocateArtifact({ locate, sha }) {
+  const located = locate.evidence.candidate
+  const shaKeyedTag = !!(locate.guarantee && locate.guarantee.shaKeyedTag)
+  const candidateTagPrefix =
+    str(locate.guarantee && locate.guarantee.candidateTagPrefix) || DEFAULT_CANDIDATE_TAG_PREFIX
+  const failed = []
+
+  if (!validCandidateTagPrefix(candidateTagPrefix)) failed.push('e:locate-guarantee-unbacked')
+
+  // The artifact's own subject, first: everything below is only meaningful once this entry is
+  // known to describe the commit being released.
+  const locatedSha = str(locate.evidence && locate.evidence.sha)
+  if (!shaMatches(locatedSha, sha)) failed.push('e:locate-sha-mismatch')
+
+  const fields = walkFields(LOCATE_HANDOFF_FIELDS, located, {
+    sha,
+    shaKeyedTag,
+    candidateTagPrefix,
+  })
+  for (const id of fields.failed) if (!failed.includes(id)) failed.push(id)
+
+  // `percent` does not reach the identity record, but the 0% contract is a fact `locate.decision`
+  // gated (principle 12's out clause), and an artifact whose entry now reads otherwise is not the
+  // one that was accepted. Re-derived like the rest rather than inherited from the decision.
+  if (located.percent !== 0) failed.push('e:locate-traffic-moved')
+
+  if (!weakeningsBackGuarantee(locate.weakenings || [], locate.guarantee, [WEAKENING_LEGS[0]])) {
+    failed.push('e:locate-weakenings-unbacked')
+  }
+
+  return { failed, shaKeyedTag, walked: { sha: shaMatches(locatedSha, sha), ...fields.walked }, locatedSha }
+}
+
+// The attest -> serving hand-off, the same walk over the other record.
+export function walkIdentityRecord({ id, sha }) {
+  const shaKeyedTag = !!(id.guarantee && id.guarantee.shaKeyedTag)
+  const attested = !!(id.guarantee && id.guarantee.attested)
+  const candidateTagPrefix =
+    str(id.guarantee && id.guarantee.candidateTagPrefix) || DEFAULT_CANDIDATE_TAG_PREFIX
+  const fields = walkFields(IDENTITY_RECORD_FIELDS, id, {
+    sha,
+    recordSha: id.sourceSha,
+    shaKeyedTag,
+    attested,
+    candidateTagPrefix,
+  })
+  const failed = [...fields.failed]
+  if (!validCandidateTagPrefix(candidateTagPrefix)) failed.push('e:identity-guarantee-unbacked')
+  if (!weakeningsBackGuarantee(id.weakenings || [], id.guarantee)) failed.push('e:identity-weakenings-unbacked')
+  return { failed, walked: fields.walked }
+}
+
+export function evaluateLocate({
+  sha,
+  traffic,
+  declareSharedTag = null,
+  candidateTagPrefix = DEFAULT_CANDIDATE_TAG_PREFIX,
+}) {
+  const failed = []
+  const weakenings = []
+  if (!isSha(sha)) {
+    return { decision: 'refuse', phase: 'locate', failed: ['e:unusable-shipped-sha'], evidence: { sha } }
+  }
+  if (!validCandidateTagPrefix(candidateTagPrefix)) {
+    return {
+      decision: 'refuse',
+      phase: 'locate',
+      failed: ['e:invalid-candidate-tag-prefix'],
+      evidence: { sha, candidateTagPrefix },
+    }
+  }
+
+  // Normalize here too so a caller that built `traffic.rows` by hand (or re-read a capture
+  // that skipped parseTraffic) still gets the Cloud Run 0%-blank reconstruction.
+  const rows = normalizeTrafficPercents(traffic.rows)
+  const classified = rows.map((r) => ({
+    ...r,
+    kind: classifyTag(r.tag, sha, candidateTagPrefix),
+  }))
+  const ours = classified.filter((r) => r.kind === 'ours')
+  const shared = classified.filter((r) => r.kind === 'shared')
+  const foreign = classified.filter((r) => r.kind === 'foreign')
+
+  let candidate = null
+  let shaKeyedTag = true
+
+  if (ours.length > 1) {
+    // Two traffic entries claiming the same SHA-keyed tag is not a thing a healthy platform
+    // produces; whatever produced it, the read no longer names ONE artifact.
+    failed.push('e:ambiguous-candidate')
+  } else if (ours.length === 1) {
+    candidate = ours[0]
+  } else if (shared.length > 0) {
+    // The pipeline publishes a shared `candidate` tag rather than a SHA-keyed one. That is a
+    // real topology, but it is the WEAKER one — the tag means "the newest candidate" — so it
+    // is usable only when pre-flight item 3 declared it.
+    if (declareSharedTag) {
+      if (shared.length > 1) failed.push('e:ambiguous-candidate')
+      else {
+        candidate = shared[0]
+        shaKeyedTag = false
+        weakenings.push({ leg: 'sha-keyed-tag', reason: declareSharedTag })
+      }
+    } else {
+      failed.push('e:no-sha-keyed-tag')
+    }
+  } else {
+    failed.push('e:candidate-absent')
+  }
+
+  // A candidate tag keyed to a DIFFERENT commit is a second release in flight (principle 7).
+  // Under the shared-tag weakening this can never fire, which is precisely the guarantee the
+  // declaration gives up: there, two releases in flight are indistinguishable from one.
+  const rivals = foreign.map((r) => r.tag)
+  if (shaKeyedTag && candidate) {
+    for (const r of shared) if (r.revision && r.revision !== candidate.revision) rivals.push(r.tag)
+  }
+  if (rivals.length > 0) failed.push('e:second-candidate-in-flight')
+
+  // Revision AND url must come from the SAME entry — that is what makes them describe one
+  // deployment. An entry missing either cannot do that job, however present the tag is. The
+  // percent is read from that same entry and held to principle 12's out clause: the pipeline's
+  // contracted output is a candidate at **0% traffic**, and "the build succeeded but traffic
+  // already moved" is a pipeline defect the release stops on. That stop was prose while the
+  // number sat in this row as evidence for a reader to notice — the one contract fact discovery
+  // read and did not enforce. It is a comparison now, like every other fact here.
+  if (candidate) {
+    if (
+      !isUrl(candidate.url) || !candidate.revision || candidate.percent === null ||
+      !Number.isFinite(candidate.percent) || candidate.percent < 0 || candidate.percent > 100
+    ) {
+      failed.push('e:incomplete-traffic-entry')
+    } else if (candidate.percent !== 0) {
+      failed.push('e:candidate-traffic-moved')
+    }
+  }
+
+  const evidence = {
+    sha,
+    trafficEntries: classified.length,
+    rivalTags: rivals,
+    candidate: candidate
+      ? { tag: candidate.tag, url: candidate.url, revision: candidate.revision, percent: candidate.percent }
+      : null,
+  }
+  return {
+    decision: failed.length === 0 ? 'accept' : 'refuse',
+    phase: 'locate',
+    failed,
+    guarantee: { shaKeyedTag, candidateTagPrefix },
+    weakenings,
+    evidence,
+  }
+}
+
+// ---- attestation reading (shared by attest + serving) ----
+
+// The tuple a health endpoint attests. Field aliases are deliberately narrow: the point is to
+// read a real endpoint's JSON, not to accept anything tuple-shaped.
+export function readAttestation(health) {
+  if (!health || typeof health !== 'object') return { error: 'e:unattested' }
+  const sourceSha = str(health.sourceSha ?? health.sha)
+  const revision = str(health.revision ?? health.revisionName)
+  const imageDigest = str(health.imageDigest ?? health.digest)
+  const missing = []
+  if (!isSha(sourceSha)) missing.push('sourceSha')
+  if (!revision) missing.push('revision')
+  if (!isDigest(imageDigest)) missing.push('imageDigest')
+  if (missing.length > 0) return { error: 'e:incomplete-attestation', missing, read: { sourceSha, revision, imageDigest } }
+  return { tuple: { sourceSha, revision, imageDigest } }
+}
+
+// ---- attest ----
+
+export function evaluateAttest({ sha, locate, health, declareNoAttestation = null, candidateImageDigest = null }) {
+  const failed = []
+  const evidence = {}
+
+  const located = locate && locate.evidence && locate.evidence.candidate
+  const locateAccepted = !!locate && locate.decision === 'accept' && !!located
+  if (!locateAccepted) {
+    return {
+      decision: 'refuse',
+      phase: 'attest',
+      failed: ['e:no-accepted-locate'],
+      evidence: { locateDecision: locate && locate.decision },
+    }
+  }
+  if (!isSha(sha)) {
+    return { decision: 'refuse', phase: 'attest', failed: ['e:unusable-shipped-sha'], evidence: { sha } }
+  }
+
+  const shaKeyedTag = !!(locate.guarantee && locate.guarantee.shaKeyedTag)
+  const weakenings = [...(locate.weakenings || [])]
+  let attested = true
+  let tuple = null
+
+  // Walk the locate artifact field by field BEFORE anything downstream reads its coordinates —
+  // see the field walk above for the rule and the failures it closes. Not "check the SHA and the
+  // tag": every field that flows into the record below, plus the 0% contract the artifact's
+  // `decision` gated, is re-established here.
+  const walk = walkLocateArtifact({ locate, sha })
+  for (const id of walk.failed) failed.push(id)
+  evidence.locatedSha = walk.locatedSha || null
+  evidence.locateFieldWalk = walk.walked
+
+  const read = readAttestation(health)
+  if (read.error) {
+    if (!declareNoAttestation) {
+      failed.push(read.error)
+      if (read.missing) evidence.missingAttestationFields = read.missing
+    } else if (!shaKeyedTag) {
+      // The floor. A declaration weakens a guarantee; it never removes the last leg. With no
+      // SHA-keyed tag AND no attestation there is nothing left that ties this URL to this
+      // commit, so "discovery" would be the agent's belief with a JSON key on it.
+      failed.push('e:unverifiable-identity')
+    } else if (!isDigest(candidateImageDigest)) {
+      // A declaration owes a SUBSTITUTE. Step 4b's fallback for this branch compares the serving
+      // revision's image digest against `candidateIdentity.imageDigest` — and this branch used to
+      // record that field as `null`, so the check the weakest-pipeline repos are sent to could
+      // never match, and an agent reading `null` reads "not applicable" and skips it. The digest
+      // is available without an attesting endpoint: it is the CANDIDATE REVISION's configured
+      // image, a platform read the release lane is already taking beside this one. So the
+      // weakening is declarable only with that substitute in hand.
+      failed.push('e:no-fallback-digest')
+    } else {
+      attested = false
+      weakenings.push({
+        leg: 'health-attestation',
+        reason: declareNoAttestation,
+        // What is compared INSTEAD, recorded next to why — so the weaker guarantee is legible in
+        // the artifact rather than reconstructed from which fields happen to be set.
+        substitute: { imageDigest: candidateImageDigest, source: 'candidate-revision-spec' },
+      })
+    }
+  } else {
+    tuple = read.tuple
+    evidence.attested = tuple
+    if (!shaMatches(tuple.sourceSha, sha)) failed.push('e:sha-mismatch')
+    if (tuple.revision !== located.revision) failed.push('e:revision-mismatch')
+  }
+
+  const identity = {
+    sourceSha: tuple ? tuple.sourceSha : sha,
+    revision: located.revision,
+    imageDigest: tuple ? tuple.imageDigest : isDigest(candidateImageDigest) ? candidateImageDigest : null,
+    // WHERE the digest came from, because that is the whole difference the weakening makes: the
+    // attested one is what the running process reports, the declared one is what the revision was
+    // configured with. Step 4b compares the same kind on both sides either way; a reader of this
+    // record must be able to tell which comparison they are getting without inferring it.
+    imageDigestSource: tuple ? 'attestation' : 'candidate-revision-spec',
+    url: located.url,
+    tag: located.tag,
+    guarantee: {
+      shaKeyedTag,
+      candidateTagPrefix:
+        str(locate.guarantee && locate.guarantee.candidateTagPrefix) || DEFAULT_CANDIDATE_TAG_PREFIX,
+      attested,
+    },
+    weakenings,
+  }
+  evidence.identity = identity
+  evidence.locatedRevision = located.revision
+
+  return {
+    decision: failed.length === 0 ? 'accept' : 'refuse',
+    phase: 'attest',
+    failed,
+    guarantee: identity.guarantee,
+    weakenings,
+    identity: failed.length === 0 ? identity : null,
+    evidence,
+  }
+}
+
+// ---- serving (step 4b, after the shift) ----
+
+export function evaluateServing({ identity, health, sha = null, servingImageDigest = null }) {
+  const failed = []
+  const evidence = {}
+  const id = identity && identity.identity ? identity.identity : identity
+  if (!id || typeof id !== 'object' || !id.revision) {
+    return { decision: 'refuse', phase: 'serving', failed: ['e:no-recorded-identity'], evidence: {} }
+  }
+  evidence.recorded = id
+
+  // The same cross-artifact rule `attest` owes its locate input, and this is the mirror gap it
+  // had: comparing the live tuple against the recorded one proves the record and the process
+  // agree, never that the record is THIS release's. Both branches below depend on it —
+  // including the declared fallback, which refuses to `e:no-attested-tuple` and sends the
+  // operator off to compare digests against *this* record's `imageDigest`. So it runs first: a
+  // record describing another commit is a mismatch to stop on, not a routing decision.
+  // The recorded `guarantee` has two legs and each is backed by a coordinate in the same record:
+  // `shaKeyedTag` by the tag, and BOTH values of `attested` by a usable digest. The digest
+  // requirement is unconditional on purpose: it used to apply only when `attested` was true, which
+  // left the un-attested branch — the one whose whole remaining check IS a digest comparison —
+  // as the single branch permitted to carry `imageDigest: null`. A record with no digest cannot
+  // be confirmed either way, so it refuses here rather than routing to a comparison with nothing
+  // on one side. The rest of the record is walked with it, same rule, same table.
+  const walk = walkIdentityRecord({ id, sha })
+  for (const f of walk.failed) failed.push(f)
+  evidence.identityFieldWalk = walk.walked
+  if (failed.length > 0) return { decision: 'refuse', phase: 'serving', failed, evidence }
+
+  const weakened = { guarantee: id.guarantee, weakenings: id.weakenings || [] }
+
+  if (!(id.guarantee && id.guarantee.attested)) {
+    // This release declared it has no attesting endpoint (pre-flight item 3), so there is no
+    // tuple to re-read — the declared fallback runs instead: the SERVING revision's configured
+    // image digest against the CANDIDATE revision's, both recorded, both real. It is weaker in a
+    // stated way (a revision's spec is not the running process) and it is a comparison, which is
+    // what the branch was missing: the fallback used to be a `# must equal` comment beside a
+    // field this branch left null.
+    if (!isDigest(servingImageDigest)) {
+      return { decision: 'refuse', phase: 'serving', failed: ['e:no-attested-tuple'], ...weakened, evidence }
+    }
+    evidence.fallback = {
+      recordedImageDigest: id.imageDigest,
+      recordedImageDigestSource: id.imageDigestSource ?? null,
+      servingImageDigest,
+      compares: 'revision-spec image digests — not the running process (declared weakening)',
+    }
+    if (!digestMatches(servingImageDigest, id.imageDigest)) failed.push('e:digest-mismatch')
+    return { decision: failed.length === 0 ? 'accept' : 'refuse', phase: 'serving', failed, ...weakened, evidence }
+  }
+
+  const read = readAttestation(health)
+  if (read.error) {
+    failed.push(read.error)
+    if (read.missing) evidence.missingAttestationFields = read.missing
+    return { decision: 'refuse', phase: 'serving', failed, evidence }
+  }
+  evidence.serving = read.tuple
+
+  if (!shaMatches(read.tuple.sourceSha, id.sourceSha)) failed.push('e:sha-mismatch')
+  if (read.tuple.revision !== id.revision) failed.push('e:revision-mismatch')
+  if (!digestMatches(read.tuple.imageDigest, id.imageDigest)) failed.push('e:digest-mismatch')
+
+  return { decision: failed.length === 0 ? 'accept' : 'refuse', phase: 'serving', failed, evidence }
+}
+
+// ---- CLI ----
+
+const USAGE = `candidate-identity — deterministic, fail-closed candidate discovery for the release lane.
+
+Principle 12's candidate handle is keyed to the promoted SHA and attested by the running
+process, so "the newest candidate" and "the one I built" cannot be different things. Every
+missing, ambiguous, or mismatched identity REFUSES; it is never a warning to notice.
+
+Usage:
+  candidate-identity locate  --sha <shipped> --traffic <flattened-traffic-read>
+                             [--candidate-tag-prefix <prefix-ending-in-hyphen>]
+                             [--declare-shared-candidate-tag <reason>]
+      Select THE candidate traffic entry — the row tagged \`candidate-<short-sha>\` for the
+      promoted SHA — and emit its tag/url/revision/percent from that ONE entry.
+        --candidate-tag-prefix     use a repository-declared SHA-keyed namespace such as \`a-\`;
+                                   defaults to \`candidate-\` and is recorded for downstream
+                                   attest/serving cross-artifact validation
+        e:invalid-candidate-tag-prefix  prefix is not a safe lowercase Cloud Run tag prefix
+        e:candidate-absent          no traffic entry carries this SHA's candidate tag
+        e:no-sha-keyed-tag          only a shared \`candidate\` tag exists and pre-flight item 3
+                                    declared no weakening — declare it or fix the pipeline
+        e:ambiguous-candidate       more than one entry claims the candidate tag
+        e:second-candidate-in-flight  a candidate tag keyed to another commit is present, or a
+                                    shared \`candidate\` tag resolves elsewhere (principle 7)
+        e:incomplete-traffic-entry  the entry lacks a url, a revision or a percent, so they
+                                    cannot be read from the same deployment
+        e:candidate-traffic-moved   the candidate is not at 0% traffic — principle 12's out
+                                    clause is a pipeline contract, so a build that shifted
+                                    traffic is a pipeline defect, not a release to continue
+      Input (preferred): gcloud run services describe … --format=json  (full service object or
+             a JSON array of {tag,url,revisionName,percent}; every omitted percent is
+             reconstructed as 0 only when all explicit targets are valid and sum to 100%.
+             Legacy: --flatten='status.traffic[]' --format='value(…tag,url,revisionName,percent)'
+             is still accepted; prefer JSON so Cloud Run's blank 0% column is not the default.
+
+  candidate-identity attest  --sha <shipped> --locate <locate.json> --health <health.json>
+                             [--declare-no-attestation <reason> --candidate-image-digest <digest>]
+      Bind the located coordinates to the tuple the RUNNING PROCESS attests — source SHA,
+      revision name, image digest — and emit \`release.candidateIdentity\` for the manifest.
+        e:unattested                the health read is missing or not an object
+        e:incomplete-attestation    a tuple field is absent or unusable (imageDigest must be a
+                                    real \`algorithm:hex\` DIGEST — an image TAG is not one)
+        e:sha-mismatch              the attested source SHA is not the promoted SHA
+        e:revision-mismatch         the attested revision is not the located revision
+        e:locate-sha-mismatch       the locate artifact describes a DIFFERENT commit than --sha
+                                    (a stale artifact from an earlier rc; see the cross-artifact
+                                    rule below)
+        e:locate-guarantee-unbacked the locate artifact's \`guarantee\` is contradicted by its own
+                                    tag — a claim, not a weaker guarantee
+        e:locate-entry-incomplete   the artifact's candidate entry is missing a url or a revision,
+                                    so a field of the identity record would be recorded unset
+        e:locate-traffic-moved      the artifact's candidate entry no longer reads 0% — the fact
+                                    its own \`decision\` was granted on
+        e:locate-weakenings-unbacked  the artifact's \`weakenings\` and \`guarantee\` disagree: a
+                                    weakening with no flag, or a weakened flag with no reason
+        e:unverifiable-identity     both legs declared away: nothing keys identity at all
+        e:no-fallback-digest        --declare-no-attestation with no usable
+                                    --candidate-image-digest: the weakening would record
+                                    \`imageDigest: null\` and step 4b's fallback compares against
+                                    that field. Read it from the CANDIDATE REVISION's spec —
+                                    \`gcloud run revisions describe <candidate-revision> --region <r>
+                                    --format='value(status.imageDigest)'\` — which needs no
+                                    attesting endpoint.
+        e:no-accepted-locate        the locate step did not accept
+
+  candidate-identity serving --sha <shipped> --identity <candidateIdentity.json>
+                             --health <live-health.json> | --serving-image-digest <digest>
+      Step 4b's post-shift confirmation: the LIVE service attests the same tuple (SHA,
+      revision, digest). Replaces comparing image-tag strings.
+      Under a record carrying the no-attestation weakening there is no tuple to re-read, so pass
+      \`--serving-image-digest\` instead — the SERVING revision's configured image digest, compared
+      against the candidate revision's digest recorded by \`attest\`. Weaker in a stated way (a
+      revision's spec is not the running process), and still a comparison rather than a note.
+        e:no-recorded-identity      no usable candidateIdentity was handed in
+        e:identity-sha-mismatch     the recorded identity describes a different commit than
+                                    --sha, so agreeing with the live process proves nothing
+        e:identity-guarantee-unbacked  the record's \`guarantee\` is contradicted by its own tag,
+                                    by a missing/unusable digest, or by an \`imageDigestSource\`
+                                    naming the other branch's comparison — in EITHER branch: a
+                                    record with no digest cannot be confirmed by the tuple or by
+                                    the fallback, so it stops here
+        e:identity-record-incomplete  the record is missing a url or a revision
+        e:identity-weakenings-unbacked  the record's \`weakenings\` and \`guarantee\` disagree
+        e:no-attested-tuple         this release declared no attesting endpoint and no
+                                    --serving-image-digest was supplied: nothing was compared.
+                                    Take that read and re-run.
+        e:sha-mismatch / e:revision-mismatch / e:digest-mismatch
+
+The cross-artifact rule, and where it stops: an identity artifact handed between subcommands is
+walked against a NAMED TABLE of fields — its own SHA against the --sha it is used with, its
+\`guarantee\` against the tag, digest and \`imageDigestSource\` backing it, its \`weakenings\`
+against that same \`guarantee\`, and the recorded \`url\` and \`revision\` against the predicate
+that makes each usable. Those fields are re-derived here rather than carried across on the
+strength of the upstream artifact's \`decision\`, and the table is applied in EVERY branch,
+including the declared weakenings, which are precisely the branches where the tuple comparisons
+are absent. The table is also the whole of the rule: a field an artifact carries that is not
+listed in it crosses UNWALKED. So an ACCEPT is not a verification of the whole record — read the
+fields you are about to act on, and run regression-checklist row 4a's identity question yourself
+rather than treating this exit code as having answered it.
+
+Declared weakenings (pre-flight item 3): a repo whose pipeline cannot publish a SHA-keyed tag,
+or has no attesting health endpoint, declares it with the matching --declare-* flag and its
+reason. The weakening is then recorded in \`guarantee\`/\`weakenings\` — stated, not assumed. An
+UNdeclared missing leg refuses, and both legs missing refuses even when both are declared.
+
+A declaration also owes a SUBSTITUTE, not only a reason: it must leave the operator a check they
+can run. --declare-no-attestation therefore requires --candidate-image-digest, so the fallback
+step 4b routes to has a real digest on both sides. Every field of an emitted identity is
+populated in every branch that accepts — a branch that cannot populate one refuses instead, since
+a null field the doctrine sends someone to compare against reads as "not applicable" and the
+check silently does not happen.
+
+Exit codes:
+  0  ACCEPT — identity established (possibly under a declared weakening)
+  1  REFUSE — the release stops here; the failing ids are named in \`failed\`
+  2  usage / unreadable-input error
+
+Output: JSON { decision: "accept"|"refuse", phase, failed: [...], guarantee, weakenings, … }
+
+Doctrine (why the tag is SHA-keyed, why one traffic entry, what the tuple proves): principle 12
+and step 3 of SKILL.md.`
+
+function parseArgs(argv) {
+  const opts = {}
+  const positional = []
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i]
+    if (a === '--help' || a === '-h') opts.help = true
+    else if (a.startsWith('--')) opts[a.slice(2)] = argv[++i]
+    else positional.push(a)
+  }
+  return { opts, positional }
+}
+
+// A declaration's REASON is the whole value of declaring: "we have no SHA-keyed tag" recorded
+// with no reason is the assumption again. A flag whose value is missing (it swallowed the next
+// flag) or empty is a usage error, never a silently-accepted weakening.
+function declaration(opts, flag) {
+  if (!(flag in opts)) return { value: null }
+  const v = opts[flag]
+  if (typeof v !== 'string' || v.trim().length === 0 || v.startsWith('--')) {
+    return { error: `--${flag} requires a reason (the weakening is recorded, not assumed)` }
+  }
+  return { value: v.trim() }
+}
+
+function readJson(file, what) {
+  if (!file) return { error: `usage: --${what} <file> is required` }
+  let raw
+  try {
+    raw = fs.readFileSync(file, 'utf8')
+  } catch {
+    return { error: `${what} not readable: ${file}` }
+  }
+  try {
+    return { value: JSON.parse(raw) }
+  } catch {
+    return { error: `${what} is not valid JSON: ${file}` }
+  }
+}
+
+export function main(argv) {
+  const { opts, positional } = parseArgs(argv)
+  const cmd = positional[0]
+
+  if (opts.help || cmd === 'help') {
+    console.log(USAGE)
+    return 0
+  }
+
+  // A missing subcommand fails to the same exit-2 usage error as an unknown one. Exit 0 here
+  // would read as ACCEPT to `candidate-identity … && <continue the release>`.
+  if (cmd !== 'locate' && cmd !== 'attest' && cmd !== 'serving') {
+    const what = cmd ? `unknown command "${cmd}"` : 'no subcommand given'
+    console.error(`candidate-identity: ${what}. Use locate|attest|serving (see --help).`)
+    return 2
+  }
+
+  let result
+  if (cmd === 'locate') {
+    // The declaration is validated FIRST so that a flag which swallowed the next flag as its
+    // "reason" (`--declare-shared-candidate-tag --traffic f`) is diagnosed as the missing
+    // reason it is, rather than as whichever required flag it ate.
+    const declared = declaration(opts, 'declare-shared-candidate-tag')
+    if (declared.error) {
+      console.error(`candidate-identity: ${declared.error}`)
+      return 2
+    }
+    if (!opts.sha) {
+      console.error('candidate-identity: usage: locate requires --sha <shipped>')
+      return 2
+    }
+    if (
+      'candidate-tag-prefix' in opts &&
+      (typeof opts['candidate-tag-prefix'] !== 'string' ||
+        !opts['candidate-tag-prefix'] ||
+        opts['candidate-tag-prefix'].startsWith('--'))
+    ) {
+      console.error('candidate-identity: --candidate-tag-prefix requires a value')
+      return 2
+    }
+    if (!opts.traffic) {
+      console.error('candidate-identity: usage: locate requires --traffic <flattened-traffic-read>')
+      return 2
+    }
+    let text
+    try {
+      text = fs.readFileSync(opts.traffic, 'utf8')
+    } catch {
+      console.error(`candidate-identity: traffic read not readable: ${opts.traffic}`)
+      return 2
+    }
+    const traffic = parseTraffic(text)
+    if (traffic.error) {
+      console.error(`candidate-identity: ${traffic.error}`)
+      return 2
+    }
+    result = evaluateLocate({
+      sha: opts.sha,
+      traffic,
+      declareSharedTag: declared.value,
+      candidateTagPrefix: opts['candidate-tag-prefix'] || DEFAULT_CANDIDATE_TAG_PREFIX,
+    })
+  } else if (cmd === 'attest') {
+    const declared = declaration(opts, 'declare-no-attestation')
+    if (declared.error) {
+      console.error(`candidate-identity: ${declared.error}`)
+      return 2
+    }
+    if (!opts.sha) {
+      console.error('candidate-identity: usage: attest requires --sha <shipped>')
+      return 2
+    }
+    const locate = readJson(opts.locate, 'locate')
+    if (locate.error) {
+      console.error(`candidate-identity: ${locate.error}`)
+      return 2
+    }
+    // An unreadable health file is a REFUSE, not an error: "the endpoint did not answer" is
+    // exactly the case that must never fall through to a shift, and it is decided by the
+    // e:unattested condition, not by the CLI.
+    // The substitute belongs to the declaration, so offering it without one is a mistake worth
+    // naming: with an attesting endpoint the digest comes from the attestation, and an input this
+    // command silently ignored would be exactly the "looks complete" shape the flag exists to fix.
+    if ('candidate-image-digest' in opts && !declared.value) {
+      console.error(
+        'candidate-identity: --candidate-image-digest is the substitute for --declare-no-attestation; ' +
+          'with an attesting endpoint the digest comes from the attestation.',
+      )
+      return 2
+    }
+    const health = opts.health ? readJson(opts.health, 'health') : { error: 'absent' }
+    result = evaluateAttest({
+      sha: opts.sha,
+      locate: locate.value,
+      health: health.error ? null : health.value,
+      declareNoAttestation: declared.value,
+      candidateImageDigest: opts['candidate-image-digest'] ?? null,
+    })
+  } else {
+    // `serving` takes the promoted SHA for the same reason `attest` does: without it this
+    // subcommand can only prove the recorded identity and the live process agree, which is
+    // worth nothing when the record describes another release's candidate.
+    if (!opts.sha) {
+      console.error('candidate-identity: usage: serving requires --sha <shipped>')
+      return 2
+    }
+    const identity = readJson(opts.identity, 'identity')
+    if (identity.error) {
+      console.error(`candidate-identity: ${identity.error}`)
+      return 2
+    }
+    // Same rule on this side: the fallback read is for a record that declared the weakening. On an
+    // attested record the live tuple is available and stronger, so a supplied digest would be an
+    // ignored input standing in for a check that did not run.
+    const record = identity.value && identity.value.identity ? identity.value.identity : identity.value
+    const recordAttested = !!(record && record.guarantee && record.guarantee.attested)
+    if ('serving-image-digest' in opts && recordAttested) {
+      console.error(
+        'candidate-identity: --serving-image-digest is the declared fallback for a record with ' +
+          '`guarantee.attested: false`; this record is attested, so pass --health and compare the tuple.',
+      )
+      return 2
+    }
+    const health = opts.health ? readJson(opts.health, 'health') : { error: 'absent' }
+    result = evaluateServing({
+      identity: identity.value,
+      health: health.error ? null : health.value,
+      sha: opts.sha,
+      servingImageDigest: opts['serving-image-digest'] ?? null,
+    })
+  }
+
+  console.log(JSON.stringify(result, null, 2))
+  return result.decision === 'accept' ? 0 : 1
+}
+
+if (isMainModule(import.meta.url)) {
+  process.exit(main(process.argv.slice(2)))
+}