@1aboveio/skills 0.10.0

package/skills/engineering/resolve-release/scripts/evidence-bundle.mjs

@@ -0,0 +1,1014 @@
+// evidence-bundle — the durable release-evidence bundle, emitted once per release attempt (#441).
+//
+// WHY THIS EXISTS. Principle 5 is that the loop exits on OBSERVED production state, observed
+// twice — the candidate at 0%, then the live service after the shift. Step 4b's proof-of-execution
+// captures those observations, but they land in the RUN MANIFEST, which is session-scoped
+// (`run-state.mjs`'s job), plus whatever the transcript happens to hold. So the evidence that a
+// release was verified — the thing the central principle rests on — does not reliably outlive the
+// session that produced it, and a FAILED attempt is worse: it leaves a deleted revision, a normal
+// issue, and nothing durably linking the two. This script makes the evidence a first-class,
+// immutable artifact with a defined lifetime, keyed to the immutable attempt id AND its terminal
+// state (principle 10), so a post-incident question is answerable months later without the originating
+// session. The state is in the key because one attempt can reach two terminal states in sequence — a
+// lease-holding `blocked-manual` hold that recovers on the SAME attempt and closes `released` — and
+// each of those exits owes its own durable record (see the filename section).
+//
+// KEYED ON THE ATTEMPT ID, NOT THE RC TAG (#599). It used to be the rc tag, and that made the whole
+// artifact unreachable on three of the four declarable trigger shapes: branch push, the legacy final
+// tag, and "no deployed surface" all mint NO rc, so a terminal exit on them had no key to write
+// under — and inventing one would fabricate the very artifact the bundle exists to make trustworthy.
+// The attempt id exists on EVERY shape by construction, because the Release Attempt Lease opens at
+// the promotion authorization rather than at the mint. Two consequences worth stating:
+//   - `rcTag` is demoted to an ordinary recorded field. It is still REQUIRED where an rc exists, and
+//     an absent one must be DECLARED (`deployTrigger` naming a shape that mints none) rather than
+//     merely omitted — otherwise dropping the old `e:missing-rc-tag` would silently let an rc-shaped
+//     release emit a durable record that forgot the tag it shipped under.
+//   - Bundles written BEFORE #599 are unaffected: one carrying only `rcTag` still keys, validates
+//     and locates (the key falls back to it), so `v1.2.0-rc.1--released.json` stays byte-identical.
+// The id itself is `<version>-attempt.<n>` on all four shapes and is minted, not composed — see
+// `attemptIdFor` / `nextAttemptId` below for why the version alone was not a usable key.
+// The final tag was rejected as the key: it exists only after verification, which would leave a
+// FAILED no-rc attempt with no key — precisely the case the bundle exists for.
+//
+// THE MANIFEST IS THE WORKING STATE; THE BUNDLE IS THE DURABLE RECORD. They are different things
+// (#441's AC says so): the manifest is mutable working state the run reads and rewrites at every
+// transition; the bundle is written ONCE, at a terminal exit, and never rewritten. This script
+// does not touch the manifest and `run-state.mjs` does not write bundles.
+//
+// KEYS OFF #432'S ENUM, NEVER A PARALLEL ONE. A bundle is emitted per TERMINAL attempt state, and
+// those states are the Release Attempt Lease's — imported from `run-state.mjs` (ATTEMPT_TERMINAL_STATES,
+// ATTEMPT_CLOSE_CAUSES, ATTEMPT_TAG_DISPOSITIONS). Adding or renaming a terminal state there breaks
+// this module's tests, which is the point: the bundle CONSUMES the state machine, it does not
+// re-implement the enum.
+//
+// EMITTED ON EVERY TERMINAL PATH. `released` (verified), `failed-pre-promotion` (pre-exposure
+// discard), `rolled-back` (post-exposure), `revoked`, `blocked-manual`. A failed attempt is
+// validated exactly as strictly as a successful one — each state carries its OWN required
+// observation set (`REQUIRED_BY_STATE`), so "a failed attempt is as well-evidenced as a successful
+// one" is a schema rule, not an aspiration. What it is NOT: it does not degrade into workflow logs
+// alone, a mutable summary, or final-tag-only evidence (which would lose every failed attempt).
+//
+// FAILS CLOSED. An incomplete or malformed bundle REFUSES — an under-populated durable record that
+// looks complete is worse than none, the same reading candidate-identity.mjs takes on a null field
+// the doctrine later compares against. And a bundle that CLAIMS an observation its state never took
+// (a pre-exposure discard carrying a post-shift live verdict) refuses too: the point of a per-state
+// schema is that the evidence present is evidence that was actually produced.
+//
+// IMMUTABLE ONCE WRITTEN (AC5). A mutable summary is not evidence. `emit` refuses to overwrite an
+// existing bundle for an (attempt id, terminal state) with DIFFERENT content; an evidence-identical
+// re-emit (a resumed session re-running the same close) is a resume-safe no-op that keeps the first
+// write. Immutability is per (id, state): a DIFFERENT terminal state for the same attempt (the
+// recovery case above) is a new, legal bundle, not an overwrite. Only the `emittedAt` write-stamp is
+// exempt from the comparison — it is metadata about the write, not the evidence. The guarantee kept
+// its exact shape across #599; only what identifies the attempt changed.
+//
+// Contract:
+//   validate --bundle <file>            exit 0 valid · 1 invalid (failing ids in `failed`) · 2 usage
+//   emit     --bundle <file> --dir <d>  validate then write immutably to <d>/<attemptId>--<state>.json;
+//                                        exit 0 written/no-op · 1 invalid-or-immutability-violation · 2 usage
+//   path     --attempt-id <id> --dir <d> [--state <s>]  with --state, print the one file for that
+//                                        (id, state); without it, list every bundle for the attempt
+//                                        (reachable by id alone — one attempt can hold >1 bundle).
+//                                        `--rc-tag <tag>` is the pre-#599 spelling and still resolves,
+//                                        because a pre-#599 bundle IS keyed by its rc tag.
+
+import fs from 'node:fs'
+import path from 'node:path'
+
+import {
+  ATTEMPT_TERMINAL_STATES,
+  ATTEMPT_CLOSE_CAUSES,
+  ATTEMPT_TAG_DISPOSITIONS,
+  ATTEMPT_ID_KEY_SAFE,
+  RELEASE_EVIDENCE_FIELDS,
+} from '../../resolve-issues/scripts/release-state-contract.mjs'
+import { shaMatches } from './candidate-identity.mjs'
+import { classifyFailureOwner, classifyFailurePhase } from './version-postmortem.mjs'
+import { isMainModule } from '../../engineering-runtime/scripts/main-module.mjs'
+
+// The bundle's terminal-state roster is #432's, re-exported so callers (and the test) key off ONE
+// list. Never redefine the five values here — import them.
+export const BUNDLE_TERMINAL_STATES = ATTEMPT_TERMINAL_STATES
+export const BUNDLE_FIELDS = RELEASE_EVIDENCE_FIELDS
+
+// Present on every bundle regardless of terminal state. `attemptId` replaced `rcTag` here in #599 —
+// see `bundleKey` for the pre-#599 fallback that keeps existing bundles keyed and valid.
+export const REQUIRED_ALWAYS = ['attemptId', 'sha', 'buildIdentity', 'terminalState']
+
+// The four declarable deploy-trigger shapes (SKILL.md pre-flight item 5 / references/versioning.md
+// §5). The bundle carries the declaration so that an ABSENT rc tag is a decided absence with a
+// checkable reason rather than an undeclared skip — principle 13's own distinction.
+export const DEPLOY_TRIGGER_SHAPES = ['rc-tag', 'branch-push', 'final-tag', 'no-deploy']
+
+// The three shapes that mint no rc at step 3. `rc-tag` is the only one that does, and it is the only
+// one whose bundle owes an `rcTag`. Derived from the roster above rather than written out twice, so
+// a fifth shape cannot be added on one side only.
+export const NO_RC_TRIGGER_SHAPES = DEPLOY_TRIGGER_SHAPES.filter((s) => s !== 'rc-tag')
+
+// The observation set each terminal state owes ON TOP of REQUIRED_ALWAYS, on a DEPLOYED shape.
+// This table is the whole "a failed attempt is as well-evidenced as a successful one" rule made
+// mechanical. It applies to `rc-tag`, `branch-push` and `final-tag`, and — because an UNDECLARED
+// shape is every pre-#599 bundle, all of which deployed — to an undeclared one too. `no-deploy`
+// has its own table below (#604); see `requiredFor`, which is the only thing that should read
+// either of these:
+//   - released         — the full verified path: both principle-5 observations (candidateVerdict at
+//                        0%, liveVerdict after the shift), the exposure approval, the traffic
+//                        transition, and the candidate receipt.
+//   - failed-pre-promotion — a candidate-validation discard carries the candidate receipt, the
+//                        4a verdict (the DEAD/EMPTY/cannot-run that stopped it), and cleanup.
+//                        A deployed pre-candidate failure carries its verified disposition instead:
+//                        it has no candidate receipt/verdict to claim. Neither form exposed, so it
+//                        owes NO liveVerdict and NO trafficTransition — claiming one is refused.
+//   - rolled-back      — post-exposure: it DID shift, so it owes the transition + the live verdict
+//                        that went unhealthy + the rollback disposition.
+//   - revoked          — a deliberately abandoned attempt: the disposition, and tagDisposition
+//                        "retained" (principle 10 — revocation revokes the attempt, never the tag).
+//                        It abandoned WITHOUT shipping, so like failed-pre-promotion it owes NO
+//                        liveVerdict and NO trafficTransition, and claiming one is refused below.
+//   - blocked-manual   — parked on an operator: a reason and the disposition (what is being waited
+//                        on). It holds the lease, so unlike the four above it carries NO closedBy.
+export const REQUIRED_BY_STATE = {
+  released: ['candidateReceipt', 'candidateVerdict', 'approval', 'trafficTransition', 'liveVerdict'],
+  'failed-pre-promotion': ['candidateReceipt', 'candidateVerdict', 'disposition'],
+  'rolled-back': ['candidateReceipt', 'candidateVerdict', 'approval', 'trafficTransition', 'liveVerdict', 'disposition'],
+  revoked: ['disposition', 'tagDisposition'],
+  'blocked-manual': ['reason', 'disposition'],
+}
+
+// A failed pre-candidate attempt has no candidate receipt or candidate verdict by definition.
+// It still binds the attempt, SHA, build identity, close cause, and verified disposition through
+// REQUIRED_ALWAYS plus this state-specific set; any candidate/exposure observation is fabricated.
+export const REQUIRED_BY_STATE_PRE_CANDIDATE = {
+  'failed-pre-promotion': ['disposition'],
+}
+
+// ---- the required set is (terminal state × TRIGGER SHAPE), not the state alone (#604) ----
+//
+// #599 made the KEY reachable on the three shapes that mint no rc. The required CONTENT above
+// stayed keyed to a DEPLOYMENT, and on `no-deploy` — a shape #599 itself added — all five of
+// `released`'s fields are artifacts only a deployment produces: a 0%-traffic candidate, a smoke
+// against it, an exposure authorization, a traffic shift, a live service. None can exist there, so
+// that shape could never reach a valid terminal bundle at all, and this repo's `v0.5.0` shipped
+// with NO bundle for exactly that reason — principle 5's "a durable bundle at every terminal exit"
+// quietly excluding a shape the skill offers at pre-flight, which is the state #599 was filed to end.
+//
+// The principle does not change: a bundle carries the evidence its shape actually produced, and
+// refuses to claim an observation nobody took. What changes is that "what the shape produced" stops
+// being ASSUMED to include a deployment. So the deployed shapes are untouched — `released` still
+// owes all five, and a deployed release that cannot produce them is still not releasable — and
+// `no-deploy` owes what it does produce: the version identity and immutable tag (`releaseTag`), the
+// Release reference (`releaseRef`), and the verification evidence standing in for principle 5's two
+// observations (`verification` — in a no-deploy repo, CI plus the full suite on the tagged SHA, and
+// the consumer-facing read that shows the artifact resolvable at the tag; versioning.md §5).
+//
+// THIS MAKES THE REQUIREMENT SATISFIABLE; IT MUST NOT MAKE IT OPTIONAL. Two halves, and the second
+// is the one a widening would drop: the fields above are required per shape (`requiredFor`), AND the
+// five deployment fields are FORBIDDEN on `no-deploy` (`DEPLOY_EVIDENCE_FIELDS` below) — a no-deploy
+// bundle asserting a traffic transition is the same fabrication `EXPOSURE_FORBIDDEN` already refuses,
+// read per shape instead of per state.
+//
+// Only three states differ, because only three of them named deployment artifacts: `revoked`
+// (disposition + tagDisposition) and `blocked-manual` (reason + disposition) owe nothing a
+// deployment produces, so they are shape-independent and are NOT restated here — `requiredFor`
+// falls through to the table above for them, which is what keeps one rule in one place.
+//
+// The final tag is cut only AFTER verification on this shape (versioning.md §5), so a no-deploy
+// attempt that never got there has no tag and no Release: `failed-pre-promotion` owes the
+// verification that stopped it and the cleanup record, and only the two post-publication states
+// owe `releaseTag`/`releaseRef`.
+export const REQUIRED_BY_STATE_NO_DEPLOY = {
+  released: ['releaseTag', 'releaseRef', 'verification'],
+  'failed-pre-promotion': ['verification', 'disposition'],
+  'rolled-back': ['releaseTag', 'releaseRef', 'verification', 'disposition'],
+}
+
+// The five fields that only a deployment can produce. Required on the deployed shapes at the states
+// above; REFUSED on `no-deploy`, at EVERY terminal state including `blocked-manual` — the carve-out
+// that lets a deployed `blocked-manual` carry exposure evidence exists because it can legitimately
+// be parked POST-shift at step 4b, and on a shape with no traffic there is no post-shift to park in.
+export const DEPLOY_EVIDENCE_FIELDS = ['candidateReceipt', 'candidateVerdict', 'approval', 'trafficTransition', 'liveVerdict']
+
+// The one reader of both tables. A shape that is absent, null or unknown falls through to the
+// deployed set: an undeclared shape is every pre-#599 bundle (all deployed), and an unknown one is
+// already refused by `e:unknown-deploy-trigger` — neither may take the SMALLER required set, because
+// "unrecognised" must never be the cheap way to owe less.
+export function requiredFor(terminalState, deployTrigger, failurePhase = null) {
+  // A no-deploy release never creates a candidate, but it has its own required verification
+  // evidence. Keep that shape-specific contract ahead of the deployed pre-candidate failure set.
+  if (deployTrigger === 'no-deploy' && REQUIRED_BY_STATE_NO_DEPLOY[terminalState]) {
+    return REQUIRED_BY_STATE_NO_DEPLOY[terminalState]
+  }
+  if (failurePhase === 'pre-candidate' && REQUIRED_BY_STATE_PRE_CANDIDATE[terminalState]) {
+    return REQUIRED_BY_STATE_PRE_CANDIDATE[terminalState]
+  }
+  return REQUIRED_BY_STATE[terminalState]
+}
+
+// The states that ended WITHOUT shipping, so a live post-shift verdict or a traffic transition on
+// one is not missing evidence, it is fabricated evidence: `failed-pre-promotion` (discarded before
+// exposure) and `revoked` (deliberately abandoned without shipping — SKILL.md:433). NOT
+// `blocked-manual`: it can legitimately be parked at step 4b, POST-shift, so partial exposure
+// evidence on it is real, not a lie — it must stay allowed.
+const EXPOSURE_FORBIDDEN = {
+  'failed-pre-promotion': ['liveVerdict', 'trafficTransition'],
+  revoked: ['liveVerdict', 'trafficTransition'],
+}
+
+// NULL IS ABSENCE, EVERYWHERE IN THIS SCHEMA (#604's second finding, generalised). `"rcTag": null`
+// used to produce `e:unusable-rc-tag` while OMITTING the key validated — and null is the natural
+// thing for a generator to write for "this shape has none". The same trap sat one layer down on the
+// forbidden fields, where `"liveVerdict": null` on a pre-exposure discard read as a CLAIMED
+// observation and refused. One rule, applied at every optional-field decision: a key written null
+// is a key that is not there. It is deliberately NOT applied to the required fields' own content
+// checks, because those already answer correctly — a required object that is null is missing, and
+// `e:missing-*` is exactly what it should say.
+const absent = (v) => v === undefined || v === null
+
+const isObject = (v) => v != null && typeof v === 'object' && !Array.isArray(v)
+const nonEmptyString = (v) => typeof v === 'string' && v.trim().length > 0
+// An observation field is a non-empty object; `reason` and `tagDisposition` are strings, handled
+// on their own so the message names what each one is.
+const nonEmptyObject = (v) => isObject(v) && Object.keys(v).length > 0
+
+// EVIDENCE A DURABLE RECORD MAY CARRY AS PROSE OR AS A STRUCTURE (#604 fix round). The bundle is a
+// record a human reads months later, and a Release URL and a verification statement are naturally
+// STRINGS — so requiring an object rejected the spelling a human writes, and said
+// `e:missing-release-ref` about a field that was right there. Which spelling is right depends on
+// one question, and only one: does anything CROSS-CHECK a field inside it?
+//   - `releaseRef` / `verification` — nothing does. `{ ci: "green" }` is no more checkable than
+//     "CI green", so the object requirement bought no soundness and only cost a spelling. Both.
+//   - `candidateReceipt` — its `sourceSha` IS cross-checked (`e:receipt-sha-mismatch`), and a
+//     string receipt would slip past that guard silently. Object only, and the four fields beside
+//     it stay object-only with it rather than splitting the deployment set on a technicality.
+//   - `releaseTag` — a NAME that is compared against the attempt's version. String only.
+const proseOrStructure = (v) => nonEmptyString(v) || nonEmptyObject(v)
+const PROSE_OR_STRUCTURE_FIELDS = new Set(['releaseRef', 'verification'])
+
+// A SHA the bundle can bind to: git's default abbreviation floor, same as candidate-identity.
+const isSha = (s) => typeof s === 'string' && /^[0-9a-f]{7,40}$/i.test(s)
+
+// ---- validation ----
+//
+// Returns { valid, failed: [id...] }. FAIL CLOSED: any missing, malformed, or fabricated field
+// appends an id and flips `valid` false. The ids are kebab e:* strings so a caller can branch on
+// which invariant broke, the same shape candidate-identity.mjs uses.
+
+const DURABLE_RECEIPT_SCHEMA = 'resolve-release/durable-processing-receipt@1'
+const DURABLE_PAUSE_ORDER = ['database-admission', 'worker-scheduling']
+const DURABLE_RESUME_ORDER = [...DURABLE_PAUSE_ORDER].reverse()
+
+function exactList(actual, expected) {
+  return Array.isArray(actual)
+    && actual.length === expected.length
+    && actual.every((value, index) => value === expected[index])
+}
+
+function validDurableReceipt(receipt) {
+  return nonEmptyObject(receipt)
+    && receipt.schema === DURABLE_RECEIPT_SCHEMA
+    && nonEmptyObject(receipt.writer)
+    && nonEmptyString(receipt.writer.id)
+    && nonEmptyString(receipt.writtenAt)
+    && Number.isFinite(Date.parse(receipt.writtenAt))
+}
+
+function validateDurableProcessing(value, add) {
+  if (!isObject(value) || typeof value.present !== 'boolean') {
+    add('e:unusable-durable-processing')
+    return
+  }
+  if (value.present === false) {
+    if (Object.keys(value).some((field) => field !== 'present')) {
+      add('e:stateless-carries-durable-processing-receipt')
+    }
+    return
+  }
+  if (!validDurableReceipt(value.preflight)) {
+    add('e:durable-processing-preflight-missing')
+    return
+  }
+  if (!exactList(value.preflight.pauseOrder, DURABLE_PAUSE_ORDER)) {
+    add('e:durable-processing-pause-order-invalid')
+  }
+  if (!exactList(value.preflight.resumeOrder, DURABLE_RESUME_ORDER)) {
+    add('e:durable-processing-preflight-resume-order-invalid')
+  }
+  if (!Number.isSafeInteger(value.preflight.quiescence?.timeoutMs)
+    || value.preflight.quiescence.timeoutMs <= 0
+    || value.preflight.evidenceSchema !== DURABLE_RECEIPT_SCHEMA) {
+    add('e:durable-processing-preflight-contract-incomplete')
+  }
+  const hasUp = !absent(value.up)
+  const hasUnwind = !absent(value.unwind)
+  if (hasUp === hasUnwind) {
+    add('e:durable-processing-sequence-ambiguous')
+    return
+  }
+  const sequence = hasUp ? value.up : value.unwind
+  if (!validDurableReceipt(value.down) || !validDurableReceipt(sequence)) {
+    add('e:durable-processing-sequence-missing')
+    return
+  }
+  if (!Number.isSafeInteger(value.down.proof?.generation) || !nonEmptyString(value.down.proof?.fence)) {
+    add('e:durable-processing-fence-missing')
+  }
+  if (hasUp) {
+    if (['blocked', 'refused'].includes(value.down.state)) {
+      add('e:blocked-down-requires-unwind')
+    }
+    if (value.down.state !== 'ready-to-shift' || value.down.proof?.observed?.blockers !== 0) {
+      add('e:durable-processing-not-quiescent')
+    }
+    if (!nonEmptyObject(value.down.shiftFence)) add('e:durable-processing-shift-fence-missing')
+    if (sequence.state !== 'restored') add('e:durable-processing-restoration-unproven')
+    const traffic = sequence.trafficProof
+    const identitiesDeclared = nonEmptyString(sequence.incumbentRevision)
+      && nonEmptyString(sequence.candidateRevision)
+      && sequence.incumbentRevision !== sequence.candidateRevision
+    const candidateRestored = identitiesDeclared
+      && sequence.servingRevisionAtResume === sequence.candidateRevision
+      && isObject(traffic)
+      && traffic.incumbentRevision === sequence.incumbentRevision
+      && traffic.candidateRevision === sequence.candidateRevision
+      && traffic.candidatePercent === 100
+      && traffic.incumbentPercent === 0
+    const incumbentRestored = identitiesDeclared
+      && sequence.servingRevisionAtResume === sequence.incumbentRevision
+      && isObject(traffic)
+      && traffic.incumbentRevision === sequence.incumbentRevision
+      && traffic.candidateRevision === sequence.candidateRevision
+      && traffic.incumbentPercent === 100
+      && traffic.candidatePercent === 0
+    if (!candidateRestored && !incumbentRestored) {
+      add('e:post-shift-traffic-proof-invalid')
+    }
+    if (nonEmptyObject(value.down.shiftFence)
+      && (value.down.shiftFence.generation !== value.down.proof?.generation
+        || value.down.shiftFence.fence !== value.down.proof?.fence)) {
+      add('e:durable-processing-shift-fence-mismatch')
+    }
+  } else {
+    if (!['blocked', 'refused'].includes(value.down.state)) add('e:unwind-without-pre-shift-failure')
+    if (!absent(value.down.shiftFence)) add('e:blocked-down-carries-shift-fence')
+    if (sequence.state !== 'unwound') add('e:blocked-down-requires-unwind')
+    const traffic = sequence.trafficProof
+    if (!isObject(traffic) || traffic.incumbentPercent !== 100 || traffic.candidatePercent !== 0
+      || traffic.incumbentRevision !== sequence.servingRevisionAtResume) {
+      add('e:pre-shift-traffic-proof-invalid')
+    }
+  }
+  if (!exactList(sequence.resumeOrder, DURABLE_RESUME_ORDER)) add('e:durable-processing-resume-order-invalid')
+  if (!nonEmptyString(sequence.servingRevisionAtResume)) add('e:durable-processing-serving-revision-missing')
+}
+
+export function validateBundle(bundle) {
+  const failed = []
+  const add = (id) => { if (!failed.includes(id)) failed.push(id) }
+
+  if (!isObject(bundle)) return { valid: false, failed: ['e:not-an-object'] }
+  for (const field of Object.keys(bundle)) {
+    if (!BUNDLE_FIELDS.includes(field)) add(`e:unknown-field-${kebab(field)}`)
+  }
+
+  if (!absent(bundle.durableProcessing)) {
+    validateDurableProcessing(bundle.durableProcessing, add)
+  }
+
+
+  // The key. `attemptId ?? rcTag` (bundleKey) so a pre-#599 bundle — which carries only the rc tag,
+  // and whose attempt id was that tag — stays keyed, valid and locatable.
+  //
+  // VALIDATE AND EMIT MUST AGREE. The key has to be WRITABLE, not merely present: without this
+  // second check `validate` exits 0 on a bundle `emit` then refuses with an unsafe-key error, and
+  // the operator is told a durable record is good by the only command that can tell them so before
+  // the write. Same predicate as `bundleFilename`, applied at the same point in the contract.
+  const key = bundleKey(bundle)
+  if (!nonEmptyString(key)) add('e:missing-attempt-id')
+  else if (!SAFE_KEY.test(key)) add('e:unsafe-attempt-id')
+
+  // `rcTag` is now an ordinary recorded field, but its ABSENCE must be declared, never implied.
+  // Dropping the old `e:missing-rc-tag` outright would be a guard that silently widens: an rc-shaped
+  // release could then emit a durable record that forgot the tag it shipped under, and nothing
+  // downstream re-asks. So: present -> it must be usable; absent -> `deployTrigger` must name one of
+  // the three shapes that mint no rc.
+  if (!absent(bundle.deployTrigger) && !DEPLOY_TRIGGER_SHAPES.includes(bundle.deployTrigger)) {
+    add('e:unknown-deploy-trigger')
+  }
+  // ...and the converse, which is the same rule read from the other side: a bundle DECLARING a
+  // shape that mints no rc, while carrying one, is a record that contradicts itself. One of the
+  // two statements is false and nothing downstream can tell which, so it is refused in the same
+  // shape as the other declaration failures rather than accepted as harmless extra evidence. An
+  // UNDECLARED shape carrying a tag stays valid — that is every pre-#599 bundle.
+  // `rcTag: null` is `rcTag` ABSENT, not a present-but-unusable tag (#604) — see `absent` above.
+  if (!absent(bundle.rcTag)) {
+    if (!nonEmptyString(bundle.rcTag)) add('e:unusable-rc-tag')
+    else if (NO_RC_TRIGGER_SHAPES.includes(bundle.deployTrigger)) add('e:rc-tag-on-no-rc-shape')
+  } else if (!NO_RC_TRIGGER_SHAPES.includes(bundle.deployTrigger)) {
+    add('e:undeclared-missing-rc-tag')
+  }
+
+  if (!isSha(bundle.sha)) add(nonEmptyString(bundle.sha) ? 'e:unusable-sha' : 'e:missing-sha')
+
+  // buildIdentity is an object; if it carries a sha it must be THIS release's — a build record for
+  // another commit bound into this bundle is the same class of error as a stale candidate receipt.
+  // Same missing/unusable split as the required loop below: it stays object-only (its `sha` is
+  // cross-checked, exactly like the candidate receipt's), but a PRESENT one is never called missing.
+  if (absent(bundle.buildIdentity)) add('e:missing-build-identity')
+  else if (!nonEmptyObject(bundle.buildIdentity)) add('e:unusable-build-identity')
+  else if (!absent(bundle.buildIdentity.sha) && !(isSha(bundle.sha) && shaMatches(bundle.buildIdentity.sha, bundle.sha))) {
+    add('e:build-identity-sha-mismatch')
+  }
+
+  const state = bundle.terminalState
+  if (!BUNDLE_TERMINAL_STATES.includes(state)) {
+    // Without a known state there is no required set to check — the state IS the router.
+    add('e:unknown-terminal-state')
+    return { valid: false, failed }
+  }
+
+  // The four lease-closing states each have exactly ONE accepted close cause (#432's map, reused).
+  // blocked-manual holds the lease and carries none — a closedBy on it is a mis-recorded close.
+  const expectedCause = ATTEMPT_CLOSE_CAUSES[state]
+  if (expectedCause) {
+    if (bundle.closedBy !== expectedCause) add('e:close-cause-mismatch')
+  } else if (!absent(bundle.closedBy)) {
+    // ...and `closedBy: null` on the lease-HOLDING state is a key that is not there (#604), not a
+    // mis-recorded close. The four closing states are untouched: a null there still fails the
+    // exact-cause check above, because null is not the cause they owe.
+    add('e:blocked-manual-carries-close-cause')
+  }
+
+  // The required set is (state × shape) — `requiredFor`, never either table directly (#604).
+  const failurePhase = classifyFailurePhase(bundle)
+  const required = requiredFor(state, bundle.deployTrigger, failurePhase)
+
+  // A pre-candidate failure has no candidate evidence by definition. Accepting any of these
+  // fields would turn a pre-candidate bundle into a contradictory record that a later reader
+  // cannot reconcile with its stamped phase.
+  if (failurePhase === 'pre-candidate' && bundle.deployTrigger !== 'no-deploy') {
+    for (const field of ['candidateReceipt', 'candidateVerdict', 'approval', 'trafficTransition', 'liveVerdict']) {
+      if (!absent(bundle[field])) add(`e:${kebab(field)}-on-pre-candidate`)
+    }
+  }
+
+  // MISSING AND UNUSABLE ARE DIFFERENT FAILURES, AND THE ID MUST SAY WHICH (#604 fix round).
+  // `e:missing-release-ref` on a key that is right there is a message asserting one thing while the
+  // check tests another — it sends the next reader to look for a field they already wrote. Absent
+  // (or null, which is absence here) -> `e:missing-*`; present but carrying nothing this schema can
+  // use -> `e:unusable-*`. It is the split `sha` and `rcTag` already made, applied to every field
+  // the required set names. The VERDICT is unchanged in every case: both refuse.
+  for (const field of required) {
+    const value = bundle[field]
+    if (field === 'tagDisposition') {
+      // Its id already names the shape rather than claiming absence, so it keeps its own message.
+      if (!ATTEMPT_TAG_DISPOSITIONS.includes(bundle.tagDisposition)) add('e:bad-tag-disposition')
+      continue
+    }
+    if (absent(value)) {
+      add(`e:missing-${kebab(field)}`)
+      continue
+    }
+    // `reason` and `releaseTag` are strings; the two prose-or-structure fields take either; every
+    // remaining required field is a structured observation (see `proseOrStructure` above for why
+    // the deployment five must stay that way).
+    const usable = field === 'reason' || field === 'releaseTag'
+      ? nonEmptyString(value)
+      : PROSE_OR_STRUCTURE_FIELDS.has(field)
+        ? proseOrStructure(value)
+        : nonEmptyObject(value)
+    if (!usable) add(`e:unusable-${kebab(field)}`)
+  }
+
+  // The final tag IS the version claim on a no-deploy shape — the only one there is, since nothing
+  // was deployed. So bind it to the attempt whose record this is, the same cross-artifact rule the
+  // receipt and buildIdentity get bound by: a bundle whose durable record pairs one attempt's id
+  // with another release's tag contradicts itself, and nothing downstream can tell which half is
+  // true. Compared on the version alone (`v0.5.0-attempt.1` -> `v0.5.0`) and with a leading `v`
+  // normalised off BOTH sides, because a repo may spell its version `0.5.0` while its tag is
+  // `v0.5.0` — the check is for a DIFFERENT release, not for a different spelling.
+  if (required.includes('releaseTag') && nonEmptyString(bundle.releaseTag) && nonEmptyString(key)) {
+    if (versionKey(bundle.releaseTag) !== versionKey(attemptVersion(key))) add('e:release-tag-version-mismatch')
+  }
+
+  // The candidate receipt is the release.candidateIdentity tuple; where a state requires it, bind
+  // it to this release's SHA so a receipt copied from an earlier rc refuses (the cross-artifact
+  // rule candidate-identity enforces at every hand-off, applied to the durable record).
+  if (required.includes('candidateReceipt') && nonEmptyObject(bundle.candidateReceipt)) {
+    if (!isSha(bundle.sha) || !shaMatches(bundle.candidateReceipt.sourceSha, bundle.sha)) add('e:receipt-sha-mismatch')
+  }
+
+  // A state that never shipped must not carry exposure evidence — fabricated, not merely spare.
+  // The id names the state so failed-pre-promotion and revoked are distinguishable in `failed`.
+  // `null` is an absent field here too (#604): writing `"liveVerdict": null` to mean "there was
+  // none" is not a claim, and refusing it taught generators to omit keys they had no way to know
+  // were forbidden.
+  for (const field of EXPOSURE_FORBIDDEN[state] ?? []) {
+    if (!absent(bundle[field])) add(`e:exposure-claimed-${state}`)
+  }
+
+  // ...and the same rule read per SHAPE rather than per state (#604). On `no-deploy` there is no
+  // candidate, no exposure, no traffic and no live service, so ANY of the five is an observation
+  // nobody took — at every terminal state, `blocked-manual` included. The id names the field and
+  // the shape, matching `e:rc-tag-on-no-rc-shape`, so a generator is told which key to drop.
+  if (bundle.deployTrigger === 'no-deploy') {
+    for (const field of DEPLOY_EVIDENCE_FIELDS) {
+      if (!absent(bundle[field])) add(`e:${kebab(field)}-on-no-deploy`)
+    }
+  }
+
+  return { valid: failed.length === 0, failed }
+}
+
+const kebab = (s) => s.replace(/[A-Z]/g, (m) => '-' + m.toLowerCase())
+
+// The version an attempt id was minted for: `v0.5.0-attempt.1` -> `v0.5.0`. A key with no ordinal
+// (a pre-#599 rc-tag key, or an id composed by hand before the convention) is returned unchanged —
+// this is a comparison helper, not a validator, and the key's own legality is checked above.
+const attemptVersion = (key) => (typeof key === 'string' ? key.replace(ATTEMPT_ORDINAL, '') : key)
+// Plain, v-prefixed, and npm package-scoped tags bind to the same semantic version.
+//
+// Exported because the @1aboveio/skills release gate binds a package-scoped tag to package semver
+// with the same split (#998). It is a COMPARISON helper, not a validator: it normalises a leading
+// `v` away and returns an unparseable input unchanged, so a caller that needs "this tag is legal"
+// must add its own strictness on top rather than read a non-throw as a pass.
+export const versionKey = (v) => {
+  if (typeof v !== 'string') return v
+  const trimmed = v.trim()
+  const packageSeparator = trimmed.lastIndexOf('@')
+  const version = packageSeparator > 0 ? trimmed.slice(packageSeparator + 1) : trimmed
+  return version.replace(/^v/, '')
+}
+
+// ---- filename keyed by (attempt id, terminal state) ----
+//
+// The key is (attempt id, terminal state), NOT the id alone. WHY THE STATE IS IN THE KEY: one
+// attempt can legitimately reach two terminal states IN SEQUENCE, because #432 makes
+// `blocked-manual` a lease-HOLDING state that clears on the SAME attempt via operator recovery, and
+// the attempt id (like the rc tag it may carry) is immutable throughout (principle 10 — no new rc is
+// minted for a recovery). So an attempt can park at `blocked-manual` (owed its own bundle — AC2
+// lists it), then recover and close `released`; an id-only key would make the `released` emit
+// collide with the stale `blocked-manual` bundle and be refused, losing the attempt's actual final
+// outcome. Keying by (id, state) lets both durable records coexist while immutability still holds
+// per (id, state).
+//
+// Attempt ids are tag-shaped (`v0.5.0-attempt.2`, or on a pre-#599 bundle the rc tag `v1.4.0-rc.2`
+// itself — single dashes) and terminal states are single-kebab like `blocked-manual`, so the `--`
+// separator cannot collide with either half: `v1.4.0-rc.2--released` and `v1.4.0-rc.2--blocked-manual` are two
+// distinct, unambiguous filenames. The job here is to REFUSE anything unsafe (a traversal-shaped or
+// empty id, or a state outside #432's enum) rather than silently sanitizing it into a different key.
+// Imported from run-state.mjs, never re-declared: the manifest refuses an unkeyable attempt id at
+// the WRITE and this module refuses it at the emit, and two regexes for one rule is how those two
+// refusals drift into disagreeing about which attempts have a durable record.
+const SAFE_KEY = ATTEMPT_ID_KEY_SAFE
+
+// ---- minting the attempt id: unique per ATTEMPT, not per version ----
+//
+// WHY A CONVENTION AT ALL (#599 fix round 2). Keying on the attempt id only helps if the id is
+// unique per attempt, and step 3's first spelling — "the version being cut" — is not: doctrine
+// deliberately re-cuts the SAME version on a retry, and both failure tiers reuse the terminal
+// state. So attempt 1 of v2.0.0 wrote `v2.0.0--failed-pre-promotion.json`, its retry failed the
+// same way, and the immutability guarantee (working exactly as designed) refused the second emit —
+// the second failure's durable record lost, which is the one thing this artifact exists to
+// prevent. Pre-#599 the key was the rc tag, which carries its own per-attempt ordinal, so the
+// change to an attempt id is what introduced the collision.
+//
+// THE CONVENTION IS `<version>-attempt.<n>`, ON ALL FOUR SHAPES. It is deliberately NOT
+// shape-dependent, and in particular the rc shape does NOT reuse its rc tag: decision 1 opens the
+// lease at the promotion AUTHORIZATION, which is before the mint, so at the moment the id is
+// written no rc tag exists yet on any shape. It mirrors the rc tag's own `-rc.<n>` ordinal so the
+// two read alike, and it is SAFE_KEY-legal by construction rather than by the author remembering.
+//
+// AND THE ORDINAL IS READ, NOT REMEMBERED. `nextAttemptId` derives it from the bundles already in
+// the durable evidence dir — the same "look at what exists, mint the next" move `version.mjs rc`
+// makes for rc tags. A caller composing the id by hand still gets the legality check (below) and
+// run-state's spent-id refusal, but the mint is the path doctrine points at.
+//
+// WHAT THAT DOES AND DOES NOT BUY — stated exactly, because an overclaim here is what let two
+// review rounds each close one route into this class and miss the next. Reading the dir makes the
+// mint free of collision with every attempt that has CLOSED, and only that. It is not a
+// self-sufficient uniqueness guarantee, and the two things it does not cover are covered elsewhere
+// or deliberately deferred:
+//   - an attempt still IN FLIGHT has emitted no bundle and does not move the ordinal. Closed by
+//     the Release Attempt Lease precondition — step 3 mints only on `free`, and an in-flight
+//     attempt reads `held` while a reaped manifest reads `unknown`. Neither authorizes a mint.
+//   - two sessions minting concurrently, before either emits. Deferred to #509 with the rest of
+//     lease atomicity (the take is a check-then-act read, advisory by design).
+// And it holds at all only if the read actually happened, which is why `nextAttemptId` rethrows
+// every readdir failure but ENOENT instead of treating an unreadable dir as an empty one.
+//
+// Pre-#599 bundles are a DIFFERENT namespace (`v1.4.0-rc.2--released.json`) and cannot collide
+// with `<version>-attempt.<n>`, so they neither shift the ordinal nor are shifted by it.
+const ATTEMPT_ORDINAL = /-attempt\.(\d+)$/
+
+export function attemptIdFor(version, ordinal) {
+  if (!nonEmptyString(version)) throw new Error('attemptIdFor: a version is required — the attempt id is <version>-attempt.<n>')
+  if (ATTEMPT_ORDINAL.test(version)) {
+    throw new Error(`attemptIdFor: ${JSON.stringify(version)} already carries an attempt ordinal — pass the version being cut (v2.0.0), not an attempt id`)
+  }
+  if (!Number.isInteger(ordinal) || ordinal < 1) {
+    throw new Error(`attemptIdFor: the ordinal must be a positive integer (attempts count from 1); got ${JSON.stringify(ordinal)}`)
+  }
+  const id = `${version}-attempt.${ordinal}`
+  if (!SAFE_KEY.test(id)) {
+    throw new Error(`attemptIdFor: version ${JSON.stringify(version)} yields the unsafe attempt id ${JSON.stringify(id)} — the id keys a file, so it must be a plain name (no slashes, no traversal, no "#")`)
+  }
+  return id
+}
+
+// The next free ordinal for this version, read off the durable evidence dir.
+//
+// A MISSING dir (ENOENT) means no attempt has emitted yet, which is ordinal 1 — the one case where
+// absence really is emptiness, because the dir is created by the first emit. An UNREADABLE dir is
+// NOT that case and never was: EACCES, ENOTDIR (a `--dir` typo pointing at a file), ELOOP, EMFILE
+// are a dir that could not be read, and answering "no attempts yet" off one hands back an ordinal
+// that may already be SPENT — two attempts under one key, which is the whole thing the ordinal
+// exists to prevent. It is the same "reading absence as freedom" the lease refuses one file away
+// (`run-state.mjs` attemptLeaseStatus answers `unknown`, NOT `free`, when there is no manifest).
+// So: rethrow anything that is not ENOENT, and let the caller fail closed.
+//
+// What this does and does not guarantee, stated precisely because a claim of more was itself the
+// bug: the ordinal is read off bundles, and a bundle exists only after a TERMINAL exit. So this
+// mint is free of collision with every CLOSED attempt, by construction. An attempt still in flight
+// has emitted nothing and does not move the ordinal — that route is closed by the Release Attempt
+// Lease precondition (step 3 mints only on `free`; an in-flight attempt reads `held` and a reaped
+// manifest reads `unknown`, and neither authorizes a mint), not by this function. Two sessions
+// minting concurrently before either emits is the remaining route, deferred to #509 with the rest
+// of lease atomicity.
+export function nextAttemptId(version, dir) {
+  if (!nonEmptyString(version)) throw new Error('nextAttemptId: a version is required')
+  if (ATTEMPT_ORDINAL.test(version)) {
+    throw new Error(`nextAttemptId: ${JSON.stringify(version)} already carries an attempt ordinal — pass the version being cut (v2.0.0), not an attempt id`)
+  }
+  let entries
+  try {
+    entries = fs.readdirSync(dir)
+  } catch (e) {
+    if (e.code !== 'ENOENT') throw e
+    entries = []
+  }
+  let highest = 0
+  for (const entry of entries) {
+    if (!entry.endsWith('.json')) continue
+    const [key] = entry.slice(0, -'.json'.length).split('--')
+    if (!key.startsWith(`${version}-attempt.`)) continue
+    const m = ATTEMPT_ORDINAL.exec(key)
+    if (m) highest = Math.max(highest, Number(m[1]))
+  }
+  return attemptIdFor(version, highest + 1)
+}
+
+// The bundle's key. `rcTag` is the pre-#599 fallback and is exactly right for the bundles that used
+// it: they WERE keyed by their rc tag, so an existing `v1.2.0-rc.1--released.json` keeps its
+// filename and stays locatable rather than being re-keyed by a schema change.
+export function bundleKey(bundle) {
+  return isObject(bundle) ? (bundle.attemptId ?? bundle.rcTag) : undefined
+}
+
+export function bundleFilename(attemptId, terminalState) {
+  if (!nonEmptyString(attemptId)) throw new Error('bundleFilename: an attempt id is required (the bundle is keyed by it; a pre-#599 bundle is keyed by its rc tag)')
+  if (!SAFE_KEY.test(attemptId)) {
+    throw new Error(`bundleFilename: unsafe attempt id ${JSON.stringify(attemptId)} — it keys a file, so it must be a plain name (no slashes, no traversal)`)
+  }
+  if (!BUNDLE_TERMINAL_STATES.includes(terminalState)) {
+    throw new Error(`bundleFilename: a terminal state is required and must be one of ${BUNDLE_TERMINAL_STATES.join(' | ')} — the bundle is keyed by (attempt id, terminal state) so one attempt's two terminal exits (e.g. a blocked-manual hold and its later released close) do not collide; got ${JSON.stringify(terminalState)}`)
+  }
+  return `${attemptId}--${terminalState}.json`
+}
+
+// The evidence content, minus the write-stamp — what "same bundle" means for immutability. Keys are
+// recursively sorted so the comparison is stable across property order (a stored bundle read back
+// from disk vs an in-memory one can differ only in key order for identical evidence). A recursive
+// canonicalizer, NOT JSON.stringify's replacer-array — that filters NESTED keys too, which would
+// silently drop the content of `disposition`, `candidateVerdict`, etc. from the comparison and let
+// a different-content re-emit read as identical.
+function canonical(v) {
+  if (Array.isArray(v)) return `[${v.map(canonical).join(',')}]`
+  if (v != null && typeof v === 'object') {
+    return `{${Object.keys(v).sort().map((k) => `${JSON.stringify(k)}:${canonical(v[k])}`).join(',')}}`
+  }
+  return JSON.stringify(v)
+}
+function evidenceCanonical(bundle) {
+  const { emittedAt, ...evidence } = bundle
+  return canonical(evidence)
+}
+
+// ---- emit: immutable once written ----
+//
+// Validates, then writes `<dir>/<attemptId>--<terminalState>.json`. If a bundle already exists for
+// this (attempt id, terminal state):
+//   - evidence-identical (differs only in emittedAt) -> resume-safe NO-OP, the first write stands;
+//   - different content                              -> REFUSE (AC5, the bundle is immutable).
+// A DIFFERENT terminal state for the same attempt is a different file (a recovery stays on the same
+// attempt and the same rc — principle 10), so it is a new, legal record rather than a collision.
+// Returns { path, noop, emittedAt }.
+// The close-time classification stamp (#962). A failure bundle leaves the lane with the
+// NORMALIZED failure owner and phase recorded on it — #961's taxonomy, computed at the moment
+// the record is written, so the durable attempt carries the classification rather than every
+// later reader re-deriving it (the version post-mortem and the rc circuit breaker both read it
+// back verbatim; a derived value here is exactly what `classifyFailureOwner`'s rule 1 calls the
+// declared extension point). A bundle whose author already declared `failureOwner` (top-level
+// or in the disposition) keeps the declaration — whoever recorded the failure closest to it
+// knows more than the heuristic — and a non-failure terminal state gets neither field, because
+// there is no failure to own. The stamp is a pure function of the bundle, so a resumed
+// re-emit recomputes the identical record and stays the resume-safe no-op.
+export function stampFailureClassification(bundle) {
+  if (!isObject(bundle)) return bundle
+  const failure = classifyFailureOwner(bundle)
+  if (!failure) return bundle
+  const out = { ...bundle }
+  const declared = nonEmptyString(out.failureOwner)
+    || (isObject(out.disposition) && nonEmptyString(out.disposition.failureOwner))
+  if (!declared) out.failureOwner = failure.owner
+  if (!nonEmptyString(out.failurePhase)) {
+    const phase = classifyFailurePhase(bundle)
+    if (phase) out.failurePhase = phase
+  }
+  return out
+}
+
+export function emitBundle({ bundle, dir, at = new Date().toISOString() }) {
+  const classified = stampFailureClassification(bundle)
+  const { valid, failed } = validateBundle(classified)
+  if (!valid) throw new Error(`evidence-bundle: refusing to emit an invalid bundle — ${failed.join(', ')}`)
+  if (!nonEmptyString(dir)) throw new Error('evidence-bundle: emit requires a --dir to write the durable record into')
+
+  const file = path.join(dir, bundleFilename(bundleKey(classified), classified.terminalState))
+  const stamped = { ...classified, emittedAt: at }
+
+  // The existsSync-then-writeFileSync check is not atomic against a concurrent emitter (TOCTOU).
+  // That concurrency-safety half is deferred to #509; here the Release Attempt Lease serializes
+  // attempts in practice, so this guard stays advisory-immutability. No behaviour change owed here.
+  if (fs.existsSync(file)) {
+    let existing
+    try {
+      existing = JSON.parse(fs.readFileSync(file, 'utf8'))
+    } catch {
+      throw new Error(`evidence-bundle: a bundle already exists at ${file} but is unreadable — refusing to overwrite (the bundle is immutable once written)`)
+    }
+    if (evidenceCanonical(existing) === evidenceCanonical(stamped)) {
+      return { path: file, noop: true, emittedAt: existing.emittedAt ?? null }
+    }
+    throw new Error(`evidence-bundle: a bundle for attempt "${bundleKey(bundle)}" in terminal state "${bundle.terminalState}" already exists at ${file} with different content — the bundle is immutable once written (principle 10 / #441 AC5); a re-emit for the same (attempt id, state) must be byte-identical evidence. A recovery stays on the SAME attempt and closes at a DIFFERENT terminal state, which is its own bundle — it never overwrites this one.`)
+  }
+
+  fs.mkdirSync(dir, { recursive: true })
+  fs.writeFileSync(file, JSON.stringify(stamped, null, 2) + '\n')
+  return { path: file, noop: false, emittedAt: at }
+}
+
+// ---- CLI ----
+
+const USAGE = `evidence-bundle — the durable release-evidence bundle, one per release attempt (#441).
+
+The run manifest is the working state; this bundle is the DURABLE record — written once at a
+terminal exit, keyed to the immutable ATTEMPT ID and its terminal state (principle 10), immutable
+once written per (attempt id, state). One attempt can reach two terminal states in sequence (a
+blocked-manual hold that recovers on the same attempt and closes released), so each exit is its own
+bundle. A failed attempt is validated as strictly as a successful one; each terminal state owes its
+own evidence. The key is the attempt id, not the rc tag (#599): three of the four declarable trigger
+shapes mint no rc, and a terminal exit on those had no key at all. On the rc shape the attempt id IS
+the rc tag, so bundles written before #599 keep their filenames and stay locatable.
+
+The attempt id is <version>-attempt.<n> on EVERY shape — unique per ATTEMPT, not per version,
+because a retry re-cuts the same version and both failure tiers reuse the terminal state, so a
+version-keyed retry would collide with the attempt it is retrying and lose its record. It is NOT
+the rc tag on any shape: the lease opens at the promotion authorization, before the mint, so no rc
+tag exists yet when the id is written. Mint it with \`next-attempt-id\` rather than composing it.
+
+Schema (JSON): {
+  attemptId, sha, buildIdentity,                     # always required; buildIdentity.sha, if set, must match sha
+                                                     # attemptId must be able to key a file — validate
+                                                     # refuses one emit could not write
+                                                     # (a pre-#599 bundle keys off rcTag instead)
+  rcTag,                                             # recorded, not the key; REQUIRED where an rc exists —
+                                                     # an absent one must be declared by deployTrigger below,
+                                                     # and a declared no-rc shape must NOT carry one
+  deployTrigger,                                     # one of ${DEPLOY_TRIGGER_SHAPES.join(' | ')} (pre-flight item 5);
+                                                     # ${NO_RC_TRIGGER_SHAPES.join('/')} mint no rc, so they declare the absence
+  terminalState,                                     # one of ${BUNDLE_TERMINAL_STATES.join(' | ')}  (#432's enum)
+  closedBy,                                          # the state's ONE verified close cause (#432); absent on blocked-manual
+                                                     # a deployed failed-pre-promotion bundle with no candidate evidence
+                                                     # is a pre-candidate failure: it owes disposition only and must
+                                                     # carry no candidateReceipt/candidateVerdict/exposure evidence
+  candidateReceipt,                                  # release.candidateIdentity tuple; sourceSha bound to sha
+  candidateVerdict, liveVerdict,                     # principle 5's two observations (0% candidate, post-shift live)
+  approval, trafficTransition, disposition,          # exposure authorization, the 0->100 shift, the cleanup/rollback/revocation record
+                                                     # the five above are DEPLOYMENT evidence: required on the
+                                                     # deployed shapes, REFUSED on no-deploy (#604)
+  releaseTag,                                        # the no-deploy shape's immutable final tag — the only version
+                                                     # claim there is; a STRING, because it is compared against the
+                                                     # attempt's version (a leading "v" is normalised off both sides)
+  releaseRef, verification,                          # the rest of the no-deploy shape's evidence: the GitHub Release,
+                                                     # and the verification standing in for principle 5's two
+                                                     # observations (CI + the full suite on the tagged SHA, and the
+                                                     # consumer-facing read). EITHER SPELLING — a plain string
+                                                     # ("https://…/releases/tag/v0.5.0", "CI green, 1590/1590") or an
+                                                     # object ({"url": "…"}); nothing cross-checks a field inside
+                                                     # them, so prose is evidence too
+  tagDisposition,                                    # "retained" — required for revoked
+  reason,                                            # required for blocked-manual
+  emittedAt                                          # stamped by emit; excluded from the immutability comparison
+}
+A field written NULL is a field that is ABSENT — "rcTag": null is no rc tag, not an unusable one, and
+"liveVerdict": null on a state that never shipped is not a claimed observation (#604). Null is never
+a way to satisfy a required field: a required object that is null is missing, and says so.
+
+MISSING and UNUSABLE are different failures and the id says which: e:missing-<field> means the key is
+not there (or is null); e:unusable-<field> means it IS there and carries nothing this schema can use.
+A present field is never reported missing. The five deployment fields above stay OBJECTS — the
+candidate receipt's sourceSha is cross-checked, and a prose receipt would slip past that guard.
+
+Required-by-state x SHAPE (#604) — the table is a property of both, because "what evidence exists"
+is a property of both. On the three DEPLOYED shapes (${DEPLOY_TRIGGER_SHAPES.filter((s) => s !== 'no-deploy').join(', ')}), and on an
+undeclared shape (every pre-#599 bundle deployed):
+  ${Object.entries(REQUIRED_BY_STATE).map(([s, f]) => `${s} -> ${f.join(',')}`).join('\n  ')}
+On no-deploy — a versioned artifact nobody deploys, so there is no candidate, no exposure, no traffic
+and no live service to observe; the states not listed are shape-independent and take the set above:
+  ${Object.entries(REQUIRED_BY_STATE_NO_DEPLOY).map(([s, f]) => `${s} -> ${f.join(',')}`).join('\n  ')}
+and it must carry NONE of ${DEPLOY_EVIDENCE_FIELDS.join(', ')} — at any
+terminal state. This makes the requirement satisfiable on that shape; it does not make it optional.
+
+Usage:
+  evidence-bundle validate --bundle <file>            0 valid · 1 invalid (ids in \`failed\`) · 2 usage
+  evidence-bundle emit     --bundle <file> --dir <d>  validate then write immutably to
+                                                      <d>/<attemptId>--<terminalState>.json
+                                                      0 written or resume-safe no-op · 1 invalid or
+                                                      immutability violation · 2 usage
+  evidence-bundle next-attempt-id --version <v> --dir <d>
+                                                      print the attempt id step 3 opens the lease
+                                                      under: <version>-attempt.<n>, with n read
+                                                      off the bundles already in <d>. Unique per
+                                                      ATTEMPT (a retry re-cuts the same version,
+                                                      so the version alone collides) and key-legal
+                                                      by construction. Free of collision with every
+                                                      CLOSED attempt; an IN-FLIGHT one has emitted
+                                                      no bundle, so call this only on a FREE lease
+                                                      (concurrent mints: #509). Fails closed on a
+                                                      durable dir it cannot read —
+                                                      only ENOENT (nothing emitted yet) is
+                                                      ordinal 1. 0 minted · 2 usage or unreadable
+                                                      dir
+  evidence-bundle path     --attempt-id <id> --dir <d> [--state <s>]
+                                                      with --state, print the one file for that
+                                                      (id, state); without it, list every bundle
+                                                      written for the attempt (reachable by id
+                                                      alone, without the originating session).
+                                                      Without --state this REFUSES (2) a dir it
+                                                      cannot read rather than reporting it empty;
+                                                      an absent dir holds no bundles (0, silent).
+                                                      --rc-tag <tag> is the pre-#599 spelling and
+                                                      still resolves on the rc shape.
+
+Doctrine: resolve-release/SKILL.md step 5 (emitted at every terminal exit) and its Definition of
+done (which reports the bundle location). On the verified path the released bundle is attached to the
+GitHub Release; every attempt's bundles are indexed by attempt id (one per terminal state reached).`
+
+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 }
+}
+
+function readJson(file, what) {
+  if (!nonEmptyString(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
+  }
+
+  if (cmd !== 'validate' && cmd !== 'emit' && cmd !== 'path' && cmd !== 'next-attempt-id') {
+    console.error(`evidence-bundle: ${cmd ? `unknown command "${cmd}"` : 'no subcommand given'}. Use validate|emit|path|next-attempt-id (see --help).`)
+    return 2
+  }
+
+  // Minting the attempt id is a READ of the durable dir, so it answers at the promotion
+  // authorization — before anything has been written for this attempt, which is exactly when
+  // step 3 needs it.
+  if (cmd === 'next-attempt-id') {
+    if (!nonEmptyString(opts.version)) {
+      console.error('evidence-bundle: usage: next-attempt-id requires --version <v> (the version being cut)')
+      return 2
+    }
+    if (!nonEmptyString(opts.dir)) {
+      console.error('evidence-bundle: usage: next-attempt-id requires --dir <durable-evidence-dir> — the ordinal is read off the bundles already written, never remembered')
+      return 2
+    }
+    try {
+      console.log(nextAttemptId(opts.version, opts.dir))
+      return 0
+    } catch (e) {
+      console.error(`evidence-bundle: ${e.message}`)
+      return 2
+    }
+  }
+
+  if (cmd === 'path') {
+    // `--rc-tag` is the pre-#599 spelling, kept because on the rc shape the attempt id IS the rc
+    // tag, so every existing caller and every existing bundle still resolves through it.
+    const key = nonEmptyString(opts['attempt-id']) ? opts['attempt-id'] : opts['rc-tag']
+    if (!nonEmptyString(key)) {
+      console.error('evidence-bundle: usage: path requires --attempt-id <id> (or the pre-#599 --rc-tag <tag>)')
+      return 2
+    }
+    if (!nonEmptyString(opts.dir)) {
+      console.error('evidence-bundle: usage: path requires --dir <dir>')
+      return 2
+    }
+    // With --state: print the one deterministic file for that (id, state). It is pure derivation,
+    // so it answers even before the bundle is written. Without --state: one attempt can hold more
+    // than one bundle (one per terminal state — a recovery stays on the same attempt), so list every
+    // bundle that EXISTS for it, which keeps "reachable by the key alone, without the session" (AC4)
+    // true when you do not yet know which terminal state the attempt reached.
+    if (nonEmptyString(opts.state)) {
+      let name
+      try {
+        name = bundleFilename(key, opts.state)
+      } catch (e) {
+        console.error(`evidence-bundle: ${e.message}`)
+        return 2
+      }
+      console.log(path.join(opts.dir, name))
+      return 0
+    }
+    if (!SAFE_KEY.test(key)) {
+      console.error(`evidence-bundle: unsafe attempt id ${JSON.stringify(key)} — must be a plain name (no slashes, no traversal)`)
+      return 2
+    }
+    const prefix = `${key}--`
+    let entries
+    // Same rule as the mint above, aimed at the reader: ENOENT is a dir the first emit has not
+    // created yet, so it genuinely holds no bundles (exit 0, no output). Any OTHER read failure is
+    // a dir nobody read, and listing nothing off it reports "this attempt has no bundles" for an
+    // attempt that has them — which is how an operator concludes a spent key is free.
+    try {
+      entries = fs.readdirSync(opts.dir)
+    } catch (e) {
+      if (e.code !== 'ENOENT') {
+        console.error(`evidence-bundle: ${opts.dir} could not be read (${e.code}) — refusing to report "no bundles" off a directory that was never read; an unreadable dir is not an empty one`)
+        return 2
+      }
+      entries = []
+    }
+    for (const f of entries.filter((f) => f.startsWith(prefix) && f.endsWith('.json')).sort()) {
+      console.log(path.join(opts.dir, f))
+    }
+    return 0
+  }
+
+  const read = readJson(opts.bundle, 'bundle')
+  if (read.error) {
+    console.error(`evidence-bundle: ${read.error}`)
+    return 2
+  }
+
+  if (cmd === 'validate') {
+    const result = validateBundle(read.value)
+    console.log(JSON.stringify(result, null, 2))
+    if (!result.valid) console.error(`evidence-bundle: INVALID — ${result.failed.join(', ')}`)
+    return result.valid ? 0 : 1
+  }
+
+  // emit
+  if (!nonEmptyString(opts.dir)) {
+    console.error('evidence-bundle: usage: emit requires --dir <dir>')
+    return 2
+  }
+  try {
+    const { path: p, noop } = emitBundle({ bundle: read.value, dir: opts.dir })
+    console.log(JSON.stringify({ path: p, noop }, null, 2))
+    if (noop) console.error(`evidence-bundle: ${p} already holds this exact evidence — resume-safe no-op (immutable once written).`)
+    else console.error(`evidence-bundle: wrote ${p}`)
+    return 0
+  } catch (e) {
+    console.error(`evidence-bundle: ${e.message}`)
+    return 1
+  }
+}
+
+if (isMainModule(import.meta.url)) {
+  process.exit(main(process.argv.slice(2)))
+}