@1aboveio/skills 0.10.0

package/skills/engineering/resolve-release/scripts/finalize-release.mjs

@@ -0,0 +1,526 @@
+#!/usr/bin/env node
+// finalize-release — record a verified release's closure as ONE durable transition (#963).
+//
+// The failure this exists for. Forex v0.1.12 passed serving identity and the prod-active smoke,
+// and the attempt was closed `released` — but the run manifest still read `step: verify` with no
+// top-level `verification`, because assembling that record was a manual act nobody performed.
+// The mandatory post-mortem then raised HIGH stopped-mid-machine and MEDIUM
+// no-verification-record on a release production had already verified: the lease said free, the
+// resume key said mid-exposure, and a resumed session had to reconcile live production to learn
+// a state the standard workflow could have recorded atomically.
+//
+// What this operation is. One standard finalization: it VALIDATES every observation the released
+// path owes — the candidate verdict, the post-authorization fence readings, the serving
+// identity/digest confirmation, the durable-processing quiescence/resume where declared, the
+// live (prod-active) verdict, and the attempt's `released` close — and then, in a single atomic
+// manifest write, records the attempt close (when still open), the top-level `verification`
+// block, and the terminal `step: done`. Any observation missing, stale, mismatched, or
+// internally inconsistent REFUSES, and a refusal writes nothing.
+//
+// Resume. The write is one `writeManifest` rename, so a crash leaves exactly one of two states:
+// `step: verify` with no `verification` (finalize has not happened — run it) or `step: done`
+// with `verification` (it has — re-running re-validates the recorded transition against the
+// `release.*` evidence and no-ops byte-identically; a recorded terminal state that no longer
+// matches the evidence refuses rather than re-asserting it). Any other combination —
+// done-without-verification, verify-with-verification — is a hand-assembled ambiguity and
+// refuses.
+//
+// What it deliberately does NOT do (issue non-goals): the final tag, the GitHub Release, and
+// the evidence-bundle emit/attach are network/durable-artifact operations that stay OUTSIDE
+// this filesystem transaction, and nothing here weakens the observed-production exit criteria —
+// every check below is a comparison against recorded observations, which is what makes a
+// refusal a statement about evidence rather than about the world.
+
+import { isMainModule } from '../../engineering-runtime/scripts/main-module.mjs'
+import {
+  ATTEMPT_CLOSE_CAUSES,
+  appendReleaseStateTransition,
+  readManifest,
+  recordReleaseAttemptState,
+  validate,
+  writeManifest,
+} from '../../resolve-issues/scripts/run-state.mjs'
+import { verifyCompletionArtifact } from './adapter-completion-artifact.mjs'
+import { evaluateFloorReadiness } from './green-gate.mjs'
+
+export const FINALIZER = 'finalize-release.mjs'
+
+const SHA = /^[0-9a-f]{40}$/i
+const nonEmpty = (v) => typeof v === 'string' && v.trim() !== ''
+const isObject = (v) => v != null && typeof v === 'object' && !Array.isArray(v)
+
+function canonical(value) {
+  if (Array.isArray(value)) return `[${value.map(canonical).join(',')}]`
+  if (isObject(value)) {
+    const keys = Object.keys(value).filter((k) => value[k] !== undefined).sort()
+    return `{${keys.map((k) => `${JSON.stringify(k)}:${canonical(value[k])}`).join(',')}}`
+  }
+  return JSON.stringify(value)
+}
+
+const equivalent = (a, b) => canonical(a) === canonical(b)
+
+function requireTime(value, label) {
+  const t = typeof value === 'string' ? Date.parse(value) : NaN
+  if (!Number.isFinite(t)) throw new Error(`${label} must be an ISO timestamp (got ${JSON.stringify(value)})`)
+  return t
+}
+
+function requireObject(value, label) {
+  if (!isObject(value)) throw new Error(`${label} is required and must be an object`)
+  return value
+}
+
+function shaEqual(a, b) {
+  return SHA.test(a) && SHA.test(b) && String(a).toLowerCase() === String(b).toLowerCase()
+}
+
+function digestEqual(a, b) {
+  return nonEmpty(a) && nonEmpty(b) && String(a).toLowerCase() === String(b).toLowerCase()
+}
+
+// ---- the validations ----
+
+function validateAttempt(release) {
+  const attempt = requireObject(release.attempt, 'release.attempt')
+  if (attempt.state === 'open' || attempt.state === 'released') return attempt
+  throw new Error(
+    `release.attempt.state is ${JSON.stringify(attempt.state)} — the finalizer records only the `
+    + 'verified released transition; failed-pre-promotion, rolled-back, revoked and blocked-manual '
+    + 'exits have their own closes (routing.md step 5)',
+  )
+}
+
+function validateCandidate(release) {
+  const identity = requireObject(release.candidateIdentity, 'release.candidateIdentity')
+  if (!SHA.test(identity.sourceSha)) {
+    throw new Error('release.candidateIdentity.sourceSha must be one exact 40-character SHA')
+  }
+  for (const field of ['revision', 'url', 'imageDigest']) {
+    if (!nonEmpty(identity[field])) throw new Error(`release.candidateIdentity.${field} is required`)
+  }
+  if (identity.revision !== release.candidateRevision) {
+    throw new Error(`release.candidateIdentity.revision (${identity.revision}) does not match release.candidateRevision (${release.candidateRevision})`)
+  }
+  if (identity.url !== release.candidateUrl) {
+    throw new Error(`release.candidateIdentity.url (${identity.url}) does not match release.candidateUrl (${release.candidateUrl})`)
+  }
+  const sha = release.candidateSha || release.tagSha || identity.sourceSha
+  if (!SHA.test(sha)) throw new Error('release.candidateSha must be one exact 40-character SHA')
+  if (!shaEqual(identity.sourceSha, sha)) {
+    throw new Error('release.candidateIdentity.sourceSha does not match the recorded candidateSha/tagSha')
+  }
+  if (nonEmpty(release.tagSha) && !shaEqual(release.tagSha, sha)) {
+    throw new Error('release.tagSha does not match the candidate SHA — the final tag must name the verified SHA (principle 10)')
+  }
+
+  const verdict = requireObject(release.candidateVerdict, 'release.candidateVerdict')
+  if (verdict.state !== 'ALIVE') {
+    throw new Error(`release.candidateVerdict.state must be ALIVE on the released path (got ${JSON.stringify(verdict.state)})`)
+  }
+  if (!nonEmpty(verdict.artifactPath)) throw new Error('release.candidateVerdict.artifactPath is required — the verdict names its durable artifact')
+  requireTime(verdict.generatedAt, 'release.candidateVerdict.generatedAt')
+  if (!nonEmpty(verdict.target) || verdict.target !== release.candidateUrl) {
+    throw new Error('release.candidateVerdict.target must be the exact recorded candidateUrl')
+  }
+  return { identity, sha, verdict, verdictAt: Date.parse(verdict.generatedAt) }
+}
+
+function validateFence(manifest, candidate) {
+  const release = manifest.release
+  const fence = requireObject(release.recheckFence, 'release.recheckFence')
+  const gate = requireObject(fence.gate, 'release.recheckFence.gate')
+  if (gate.decision !== 'fire' || gate.phase !== 'shift') {
+    throw new Error(`release.recheckFence.gate must record decision "fire" at phase "shift" (got ${JSON.stringify(gate.decision)}/${JSON.stringify(gate.phase)}) — the pre-exposure gate did not authorize this shift`)
+  }
+  if (!Array.isArray(gate.failed) || gate.failed.length !== 0) {
+    throw new Error(`release.recheckFence.gate.failed must be empty on an authorized shift (got ${JSON.stringify(gate.failed)})`)
+  }
+  const evidence = requireObject(gate.evidence, 'release.recheckFence.gate.evidence')
+  if (evidence.verdict !== 'ALIVE' || evidence.verdictTarget !== release.candidateUrl || evidence.noMutations !== true) {
+    throw new Error('release.recheckFence.gate.evidence must record a read-only ALIVE verdict on the exact candidate URL (verdict, verdictTarget, noMutations)')
+  }
+  if (evidence.generatedAt !== candidate.verdict.generatedAt) {
+    throw new Error('release.recheckFence.gate.evidence.generatedAt does not match the recorded candidateVerdict — the fence evaluated a different verdict artifact')
+  }
+
+  // Freshness as the fence recorded it — a historical reading, re-checked for internal
+  // consistency rather than re-taken: the age must sit inside the recorded window AND agree
+  // with the verdict stamp and the fence's own checkedAt.
+  const age = evidence.verdictAgeMinutes
+  const window = evidence.verdictFreshnessMinutes
+  if (!Number.isFinite(age) || !Number.isFinite(window) || window <= 0) {
+    throw new Error('release.recheckFence.gate.evidence must record verdictAgeMinutes and a positive verdictFreshnessMinutes')
+  }
+  if (age < 0 || age > window) {
+    throw new Error(`the fence recorded a stale verdict: age ${age}m outside the ${window}m window — an expired verdict routes back to 4a, never onward to the shift`)
+  }
+  const fenceAt = requireTime(fence.checkedAt, 'release.recheckFence.checkedAt')
+  const observedAge = (fenceAt - candidate.verdictAt) / 60_000
+  if (observedAge < 0 || observedAge > window || Math.abs(observedAge - age) > 0.01) {
+    throw new Error(`the fence freshness record is inconsistent: recorded age ${age}m but the verdict stamp and fence checkedAt give ${observedAge.toFixed(2)}m`)
+  }
+
+  // The floor the fence recorded must be the floor the manifest still declares — a floor that
+  // moved between the shift and the finalization is exactly the staleness this operation refuses.
+  const floor = evaluateFloorReadiness(manifest, fenceAt)
+  if (!floor.ok) throw new Error(`production floor was not ready at the traffic fence: ${floor.detail}`)
+  if (!equivalent(evidence.floorReadiness, floor.evidence.floorReadiness)) {
+    throw new Error('release.recheckFence.gate.evidence.floorReadiness does not match the manifest\'s current floor readiness record')
+  }
+
+  if (fence.candidateResolvesTo !== candidate.identity.revision) {
+    throw new Error(`release.recheckFence.candidateResolvesTo (${JSON.stringify(fence.candidateResolvesTo)}) does not match the verified candidate revision — the fence must record what the URL resolved to, not a judgment`)
+  }
+  if (fence.candidatePercent !== 0 || fence.previousRevisionPercent !== 100) {
+    throw new Error('release.recheckFence must record the candidate at 0% and the previous revision at exactly 100%')
+  }
+  return { fence, fenceAt }
+}
+
+function validateServing(release, candidate) {
+  const serving = requireObject(release.servingConfirmation, 'release.servingConfirmation')
+  const gate = requireObject(serving.gate, 'release.servingConfirmation.gate')
+  if (gate.decision !== 'accept' || gate.phase !== 'serving') {
+    throw new Error(`release.servingConfirmation.gate must record decision "accept" at phase "serving" (got ${JSON.stringify(gate.decision)}/${JSON.stringify(gate.phase)})`)
+  }
+  if (!Array.isArray(gate.failed) || gate.failed.length !== 0) {
+    throw new Error(`release.servingConfirmation.gate.failed must be empty on an accepted serving confirmation (got ${JSON.stringify(gate.failed)})`)
+  }
+  const evidence = requireObject(gate.evidence, 'release.servingConfirmation.gate.evidence')
+  if (!equivalent(evidence.recorded, candidate.identity)) {
+    throw new Error('release.servingConfirmation.gate.evidence.recorded must be the complete candidateIdentity tuple the serving check ran against')
+  }
+  if (isObject(evidence.serving)) {
+    const live = evidence.serving
+    if (!shaEqual(live.sourceSha, candidate.sha)
+      || live.revision !== candidate.identity.revision
+      || !digestEqual(live.imageDigest, candidate.identity.imageDigest)) {
+      throw new Error('release.servingConfirmation serving tuple does not exactly match the candidate identity (sourceSha, revision, imageDigest)')
+    }
+  } else if (isObject(evidence.fallback)) {
+    // The declared no-attesting-endpoint weakening (pre-flight item 3): the serving revision's
+    // configured digest against the candidate's — a comparison, never a revision-name read.
+    if (!digestEqual(evidence.fallback.servingImageDigest, candidate.identity.imageDigest)) {
+      throw new Error('release.servingConfirmation fallback serving image digest does not match the candidate identity digest')
+    }
+  } else {
+    throw new Error('release.servingConfirmation.gate.evidence records no serving observation — neither the re-attested tuple nor the declared digest fallback')
+  }
+  if (serving.candidatePercent !== 100 || serving.previousRevisionPercent !== 0) {
+    throw new Error('release.servingConfirmation must record the candidate at 100% and the previous revision at 0%')
+  }
+  const servingAt = requireTime(serving.checkedAt, 'release.servingConfirmation.checkedAt')
+  return { serving, servingAt }
+}
+
+function validateQuiescence(manifest, candidate, fenceAt, servingAt, liveAt) {
+  const declared = manifest.envelope && manifest.envelope.durableProcessing
+  if (!isObject(declared) || typeof declared.present !== 'boolean') {
+    throw new Error('envelope.durableProcessing must explicitly declare present true or false — an unasked question is not an absent record (pre-flight item 6)')
+  }
+  const recorded = manifest.release.quiescence
+  if (declared.present === false) {
+    if (recorded !== undefined && recorded !== null) {
+      throw new Error('release.quiescence must be absent when durable processing is declared absent — a record here contradicts the declaration')
+    }
+    return null
+  }
+
+  const q = requireObject(recorded, 'release.quiescence')
+  if (!Array.isArray(q.pauseOrder) || q.pauseOrder.length === 0 || q.pauseOrder.some((s) => !nonEmpty(s))) {
+    throw new Error('release.quiescence.pauseOrder must record the non-empty pause order as executed')
+  }
+  if (!equivalent(q.pauseOrder, declared.pauseOrder)) {
+    throw new Error('release.quiescence.pauseOrder does not match the order declared at pre-flight (envelope.durableProcessing.pauseOrder)')
+  }
+  if (!Array.isArray(q.resumeOrder) || !equivalent(q.resumeOrder, [...q.pauseOrder].reverse())) {
+    throw new Error('release.quiescence.resumeOrder must be the exact reverse of the executed pause order (principle 14)')
+  }
+  const proof = requireObject(q.proof, 'release.quiescence.proof')
+  const readings = Object.entries(proof).filter(([k]) => k !== 'checkedAt')
+  if (readings.length === 0 || 'quiesced' in proof || readings.every(([, v]) => typeof v === 'boolean')) {
+    throw new Error('release.quiescence.proof must record the observed processing-state value (an in-flight count, a queue depth), never `quiesced: true` — the judgment one field deeper')
+  }
+  const pausedAt = requireTime(q.pausedAt, 'release.quiescence.pausedAt')
+  const proofAt = requireTime(proof.checkedAt, 'release.quiescence.proof.checkedAt')
+  const resumedAt = requireTime(q.resumedAt, 'release.quiescence.resumedAt')
+  if (!(pausedAt <= proofAt && proofAt <= fenceAt && fenceAt <= servingAt && servingAt <= resumedAt && resumedAt <= liveAt)) {
+    throw new Error('release.quiescence is not in the durable order pause -> prove-quiescent -> fence -> serving-identity -> reverse-resume -> live (principle 14)')
+  }
+  if (q.servingRevisionAtResume !== candidate.identity.revision) {
+    throw new Error(`release.quiescence.servingRevisionAtResume (${JSON.stringify(q.servingRevisionAtResume)}) must be the verified candidate revision — processing was resumed against a revision nobody confirmed`)
+  }
+  return q
+}
+
+function validateLiveVerdict(manifest, release, fenceAt) {
+  const verdict = requireObject(release.liveVerdict, 'release.liveVerdict')
+  if (verdict.state !== 'ALIVE') {
+    throw new Error(`release.liveVerdict.state must be ALIVE on the released path (got ${JSON.stringify(verdict.state)})`)
+  }
+  if (!nonEmpty(verdict.artifactPath)) throw new Error('release.liveVerdict.artifactPath is required — the active verdict names its durable artifact')
+  const liveAt = requireTime(verdict.generatedAt, 'release.liveVerdict.generatedAt')
+  if (!nonEmpty(verdict.target)) throw new Error('release.liveVerdict.target is required')
+  const floor = evaluateFloorReadiness(manifest, fenceAt)
+  const floorTarget = floor.ok && floor.evidence.floorReadiness && floor.evidence.floorReadiness.target
+  if (nonEmpty(floorTarget) && verdict.target !== floorTarget) {
+    throw new Error(`release.liveVerdict.target (${verdict.target}) does not match the declared prod-active floor target (${floorTarget})`)
+  }
+  return { verdict, liveAt }
+}
+
+// ---- the one transition ----
+
+// The checked completion record and observation blocks the one transition assembles into `verification` — the REQUIRED keys
+// of the terminal record. report.mjs's step-5 reader checks this exact list (via
+// isFinalizedVerification below) instead of accepting any object-valued verification, so the
+// writer's shape and the reader's question share one source.
+const VERIFICATION_OBSERVATIONS = ['adapterCompletion', 'candidate', 'candidateVerdict', 'recheckFence', 'servingConfirmation', 'liveVerdict']
+
+function assembleVerification(release, now, quiescence, adapterCompletion) {
+  return {
+    finalizedAt: now,
+    finalizedBy: FINALIZER,
+    adapterCompletion,
+    candidate: release.candidateIdentity,
+    candidateVerdict: release.candidateVerdict,
+    recheckFence: release.recheckFence,
+    servingConfirmation: release.servingConfirmation,
+    liveVerdict: release.liveVerdict,
+    ...(quiescence ? { quiescence } : {}),
+  }
+}
+
+// The reader-level half of the terminal record: is this the verification block the one
+// transition writes? Presence and shape only — full cross-field consistency is validateAll's
+// job on the write/resume path; a checkpoint reader owes "the required observations are
+// recorded", not a re-verdict. A hand-assembled or empty `verification` (the
+// release-finalization-terminal-proof review finding: `{}` rendered report.mjs's Step 5 done
+// while this finalizer refused the same state) fails here exactly as it fails finalize.
+export function isFinalizedVerification(verification) {
+  if (!isObject(verification)) return false
+  if (verification.finalizedBy !== FINALIZER) return false
+  if (!Number.isFinite(Date.parse(verification.finalizedAt || ''))) return false
+  return VERIFICATION_OBSERVATIONS.every((key) => {
+    const block = verification[key]
+    return isObject(block) && Object.keys(block).length > 0
+  })
+}
+
+function validateAll(manifest) {
+  if (manifest.skill !== 'resolve-release') {
+    throw new Error(`finalize-release requires a resolve-release manifest (got skill ${JSON.stringify(manifest.skill)})`)
+  }
+  const check = validate(manifest)
+  if (!check.ok) throw new Error(`release manifest is invalid before finalization: ${check.errors.join('; ')}`)
+  const release = requireObject(manifest.release, 'release')
+  const attempt = validateAttempt(release)
+  const candidate = validateCandidate(release)
+  const { fenceAt } = validateFence(manifest, candidate)
+  const { servingAt } = validateServing(release, candidate)
+  const { liveAt } = validateLiveVerdict(manifest, release, fenceAt)
+  if (!(candidate.verdictAt <= fenceAt && fenceAt <= servingAt && servingAt <= liveAt)) {
+    throw new Error('the verification evidence is not in the durable order candidate-verdict → fence → serving → live')
+  }
+  const quiescence = validateQuiescence(manifest, candidate, fenceAt, servingAt, liveAt)
+  return { release, attempt, candidate, quiescence }
+}
+
+// Acquires completion evidence, validates, then returns the finalized manifest; the CLI owns the manifest write.
+// Throws with a named reason on any missing, stale, mismatched, or inconsistent observation.
+export function finalizeRelease(manifest, {
+  now = new Date().toISOString(),
+  adapterCompletionArtifact,
+  adapterComponentHead,
+  adapterCompletionSha256,
+} = {}) {
+  requireTime(now, 'now')
+  if (!isObject(manifest)) throw new Error('the manifest must be a JSON object')
+  const adapterCompletion = verifyCompletionArtifact(adapterCompletionArtifact, {
+    expectedComponentHead: adapterComponentHead,
+    expectedSha256: adapterCompletionSha256,
+  })
+  const hasVerification = isObject(manifest.verification)
+
+  if (manifest.step === 'done') {
+    if (!hasVerification) {
+      throw new Error('step is "done" but no top-level verification block is recorded — an ambiguous hand-assembled state; reconcile the manifest by hand, the finalizer will not guess at it')
+    }
+    // Resume: re-validate every observation, then require the recorded terminal state to be
+    // exactly what this operation would have written — anything less is drift, not a resume.
+    const { release, attempt, candidate, quiescence } = validateAll(manifest)
+    if (attempt.state !== 'released' || attempt.closedBy !== ATTEMPT_CLOSE_CAUSES.released) {
+      throw new Error('a finalized manifest must carry the attempt closed released by verified-release')
+    }
+    const expected = assembleVerification(release, null, quiescence, adapterCompletion)
+    const recorded = { ...manifest.verification }
+    delete recorded.finalizedAt
+    delete expected.finalizedAt
+    if (!equivalent(recorded, expected)) {
+      throw new Error('the recorded verification block does not match the re-verified release.* evidence — the terminal state drifted from its observations; reconcile by hand')
+    }
+    if (nonEmpty(manifest.shippedSha) && !shaEqual(manifest.shippedSha, candidate.sha)) {
+      throw new Error('shippedSha does not match the verified candidate SHA')
+    }
+    return { manifest, resumed: true, finalizedAt: manifest.verification.finalizedAt }
+  }
+
+  if (manifest.step !== 'verify') {
+    throw new Error(`finalize-release runs at step "verify" (or "done" on resume); got step ${JSON.stringify(manifest.step)}`)
+  }
+  if (hasVerification) {
+    throw new Error('step is "verify" but a verification block is already recorded — an ambiguous hand-assembled state; reconcile the manifest by hand')
+  }
+
+  const { release, attempt, candidate, quiescence } = validateAll(manifest)
+
+  let out = manifest
+  if (attempt.state === 'open') {
+    // Use the canonical attempt writer for the closure shape and invariants. Its intermediate
+    // history event is intentionally not persisted: finalization is one atomic transition from
+    // verify/open directly to done/released, so the combined event is appended after the full
+    // terminal manifest has been assembled.
+    const evidence = `serving ${candidate.identity.revision} at 100% for ${candidate.sha}; prod-active ALIVE (${release.liveVerdict.artifactPath})`
+    out = recordReleaseAttemptState(out, {
+      state: 'released',
+      closedBy: ATTEMPT_CLOSE_CAUSES.released,
+      evidence,
+    }, { at: now })
+    // #963's transaction clock owns the terminal attempt record; #913's writer clock
+    // independently owns the history event timestamp.
+    out.release.attempt.closedAt = now
+    if (manifest.releaseHistory === undefined) delete out.releaseHistory
+    else out.releaseHistory = structuredClone(manifest.releaseHistory)
+  }
+  out = {
+    ...structuredClone(out),
+    verification: assembleVerification(out.release, now, quiescence, adapterCompletion),
+    step: 'done',
+    shippedSha: candidate.sha,
+    updatedAt: now,
+  }
+  out = appendReleaseStateTransition(manifest, out)
+  const check = validate(out)
+  if (!check.ok) throw new Error(`the finalized manifest is invalid: ${check.errors.join('; ')}`)
+  return { manifest: out, resumed: false, finalizedAt: now }
+}
+
+// ---- CLI ----
+
+const USAGE = `finalize-release — validate a verified release's observations and record the
+terminal closure as one durable transition.
+
+Usage:
+  finalize-release.mjs <run-manifest.json> --adapter-completion-artifact <path>
+    --adapter-component-head <40-hex-sha> --adapter-completion-sha256 <64-hex-sha256>
+    [--now <iso>]
+
+Runs at step "verify" on the released path: validates the candidate verdict, the checked
+isolated-adapter completion artifact under the finalizer-owned suite policy, the
+post-authorization re-check fence, the serving identity/digest confirmation, the
+durable-processing quiescence/resume where declared, and the live prod-active verdict; then, in
+one atomic manifest write, closes the attempt released/verified-release (when still open),
+records the top-level verification block, and advances step to done.
+
+Any missing, stale, mismatched, or inconsistent observation refuses (exit 1) and writes
+nothing. Re-running after success re-validates and no-ops. The final tag, GitHub Release, and
+evidence-bundle emit/attach are separate operations (routing.md step 5); report.mjs runs after
+this transition on the released path.`
+
+export function main(argv, deps = {}) {
+  const args = [...argv]
+  const options = {
+    manifestPath: null,
+    now: null,
+    adapterCompletionArtifact: null,
+    adapterComponentHead: null,
+    adapterCompletionSha256: null,
+  }
+  const positional = []
+  for (let i = 0; i < args.length; i += 1) {
+    const arg = args[i]
+    if (arg === '--help' || arg === '-h') {
+      console.log(USAGE)
+      return 0
+    } else if (arg === '--adapter-completion-artifact') {
+      const value = args[++i]
+      if (value === undefined || value.startsWith('--')) {
+        throw new Error('--adapter-completion-artifact needs a path value')
+      }
+      options.adapterCompletionArtifact = value
+    } else if (arg === '--adapter-component-head') {
+      const value = args[++i]
+      if (value === undefined || value.startsWith('--')) {
+        throw new Error('--adapter-component-head needs a SHA value')
+      }
+      options.adapterComponentHead = value
+    } else if (arg === '--adapter-completion-sha256') {
+      const value = args[++i]
+      if (value === undefined || value.startsWith('--')) {
+        throw new Error('--adapter-completion-sha256 needs a SHA-256 value')
+      }
+      options.adapterCompletionSha256 = value
+    } else if (arg === '--now') {
+      const value = args[++i]
+      if (value === undefined || value.startsWith('--')) throw new Error('--now needs an ISO timestamp value')
+      options.now = value
+    } else if (arg.startsWith('--')) {
+      throw new Error(`unknown argument ${arg}\n\n${USAGE}`)
+    } else {
+      positional.push(arg)
+    }
+  }
+  if (positional.length !== 1) {
+    console.error(USAGE)
+    return 2
+  }
+  if (options.adapterCompletionArtifact == null || options.adapterComponentHead == null
+      || options.adapterCompletionSha256 == null) {
+    console.error(USAGE)
+    return 2
+  }
+  const [manifestPath] = positional
+  const read = deps.readManifest || readManifest
+  const write = deps.writeManifest || writeManifest
+  let manifest
+  try {
+    manifest = read(manifestPath)
+  } catch (error) {
+    console.error(`finalize-release: manifest is not readable JSON: ${manifestPath} — ${error.message || error}`)
+    return 1
+  }
+  if (!isObject(manifest)) {
+    console.error(`finalize-release: manifest is not readable JSON: ${manifestPath}`)
+    return 1
+  }
+  try {
+    const result = finalizeRelease(manifest, {
+      now: options.now || new Date().toISOString(),
+      adapterCompletionArtifact: options.adapterCompletionArtifact,
+      adapterComponentHead: options.adapterComponentHead,
+      adapterCompletionSha256: options.adapterCompletionSha256,
+    })
+    if (!result.resumed) write(manifestPath, result.manifest)
+    console.log(JSON.stringify({
+      ok: true,
+      manifestPath,
+      step: result.manifest.step,
+      resumed: result.resumed,
+      finalizedAt: result.finalizedAt,
+    }, null, 2))
+    return 0
+  } catch (error) {
+    console.error(`finalize-release: ${error.message || error}`)
+    return 1
+  }
+}
+
+if (isMainModule(import.meta.url)) {
+  try {
+    process.exitCode = main(process.argv.slice(2))
+  } catch (error) {
+    console.error(`finalize-release: ${error.message || error}`)
+    process.exitCode = 1
+  }
+}