@1aboveio/skills 0.10.0

package/skills/engineering/resolve-issues/scripts/release-state-contract.mjs

@@ -0,0 +1,697 @@
+import { createHash } from 'node:crypto'
+
+// Canonical vocabulary for a resolve-release run manifest and its durable evidence.
+
+export const RELEASE_STEPS = Object.freeze([
+  'intake', 'merge', 'promote', 'deploy', 'validate', 'expose', 'verify', 'discard',
+  'rollback', 'done',
+])
+export const RELEASE_TERMINAL_STEPS = Object.freeze(
+  RELEASE_STEPS.filter((step) => ['discard', 'rollback', 'done'].includes(step)),
+)
+
+export const ATTEMPT_NONTERMINAL_STATE = 'open'
+export const ATTEMPT_TERMINAL_STATES = Object.freeze([
+  'released', 'failed-pre-promotion', 'rolled-back', 'revoked', 'blocked-manual',
+])
+export const ATTEMPT_STATES = Object.freeze([
+  ATTEMPT_NONTERMINAL_STATE,
+  ...ATTEMPT_TERMINAL_STATES,
+])
+export const ATTEMPT_ID_KEY_SAFE = /^[A-Za-z0-9][A-Za-z0-9._-]*$/
+export const ATTEMPT_LEASE_CLOSING_STATES = Object.freeze([
+  'released', 'failed-pre-promotion', 'rolled-back', 'revoked',
+])
+export const ATTEMPT_LEASE_HOLDING_STATES = Object.freeze([
+  ATTEMPT_NONTERMINAL_STATE,
+  'blocked-manual',
+])
+export const ATTEMPT_CLOSE_CAUSES = Object.freeze({
+  released: 'verified-release',
+  'failed-pre-promotion': 'verified-candidate-cleanup',
+  'rolled-back': 'verified-rollback',
+  revoked: 'verified-revocation',
+})
+export const ATTEMPT_TAG_DISPOSITIONS = Object.freeze(['retained'])
+export const ATTEMPT_IN_FLIGHT_STEPS = Object.freeze([
+  'deploy', 'validate', 'expose', 'verify', 'discard', 'rollback',
+])
+
+export const RELEASE_VERDICT_STATES = Object.freeze([
+  'ALIVE', 'DEAD', 'EMPTY', 'CANNOT-RUN', 'BLOCKED',
+])
+
+export const RELEASE_EVENT_KINDS = Object.freeze(['state', 'intent', 'result'])
+export const RELEASE_EVENT_ACTIONS = Object.freeze([
+  'tag', 'candidate', 'traffic', 'processing-control', 'github-release', 'metadata-delivery',
+])
+export const RELEASE_EVENT_OUTCOMES = Object.freeze([
+  'succeeded', 'failed', 'blocked', 'cancelled',
+])
+export const RELEASE_HISTORY_LIMIT = 64
+export const RELEASE_REPLAY_LIMIT = 64
+export const RELEASE_ARTIFACT_LIMIT = 8
+export const RELEASE_LOCATOR_LIMIT = 2048
+
+export const CANONICAL_RELEASE_MANIFEST_FIELDS = Object.freeze([
+  'runSlug', 'skill', 'createdAt', 'updatedAt', 'step', 'envelope', 'release',
+  'verification', 'rollback', 'deploy', 'promotion', 'promotionPr', 'shippedSha',
+  'backMerge', 'targetBranch', 'skillsRoot', 'originalBranch', 'worktree', 'intake',
+  'merges', 'closedIssues', 'epic', 'deliveryMode', 'queueProvider', 'enqueueTrigger',
+  'evidence', 'status', 'notes', 'note', 'productionBranch', 'terminalState',
+  'durableEvidenceDir', 'recheckFence', 'quiescence', 'mergedSha', 'rollbackTarget',
+  'decisions', 'deferrals', 'models', 'units',
+  'releaseHistory',
+])
+
+export const CANONICAL_RELEASE_ENVELOPE_FIELDS = Object.freeze([
+  'repo', 'service', 'version', 'mode', 'deployTrigger', 'deployTriggerReason',
+  'displayVersionPolicy', 'displayVersionPolicyException', 'durableProcessing',
+  'exposureIdentity', 'floorReadiness', 'rollbackPolicy',
+  'candidateDeletableWithoutConfirm', 'reversibilityConfirmed', 'irreversibleContent',
+  'verdictFreshnessMinutes',
+])
+
+export const CANONICAL_RELEASE_FIELDS = Object.freeze([
+  'attempt', 'backMerge', 'blockingFindings', 'burned', 'candidateIdentity',
+  'candidateRevision', 'candidateSha', 'candidateUrl', 'candidateVerdict', 'cutCommit',
+  'ensureGreen', 'fastForwardable', 'floorReadiness', 'integrationCi',
+  'integrationSmoke', 'metadataPr', 'previousRevision', 'prLaneCi', 'quiescence',
+  'productionEndpoints', 'rcTag', 'recheckFence', 'releaseReadiness',
+  'servingConfirmation', 'liveVerdict', 'circuitBreaker', 'tagged', 'tagSha', 'version',
+  'versionPlan',
+])
+
+export const CANONICAL_RELEASE_VERIFICATION_FIELDS = Object.freeze([
+  'finalizedAt', 'finalizedBy', 'candidate', 'candidateVerdict', 'live', 'liveVerdict',
+  'serving', 'servingConfirmation', 'recheckFence', 'quiescence',
+])
+
+export const RELEASE_EVIDENCE_FIELDS = Object.freeze([
+  'attemptId', 'sha', 'buildIdentity', 'terminalState', 'closedBy', 'rcTag',
+  'deployTrigger', 'candidateReceipt', 'candidateVerdict', 'approval',
+  'trafficTransition', 'liveVerdict', 'disposition', 'releaseTag', 'releaseRef',
+  'verification', 'durableProcessing', 'tagDisposition', 'reason', 'failureOwner',
+  'failurePhase', 'emittedAt',
+])
+
+export const RELEASE_STATE_CONTRACT = Object.freeze({
+  terminalSteps: RELEASE_TERMINAL_STEPS,
+  steps: RELEASE_STEPS,
+  attempt: Object.freeze({
+    nonterminalState: ATTEMPT_NONTERMINAL_STATE,
+    terminalStates: ATTEMPT_TERMINAL_STATES,
+    states: ATTEMPT_STATES,
+    leaseClosingStates: ATTEMPT_LEASE_CLOSING_STATES,
+    leaseHoldingStates: ATTEMPT_LEASE_HOLDING_STATES,
+    closeCauses: ATTEMPT_CLOSE_CAUSES,
+    tagDispositions: ATTEMPT_TAG_DISPOSITIONS,
+    inFlightSteps: ATTEMPT_IN_FLIGHT_STEPS,
+  }),
+  verdictStates: RELEASE_VERDICT_STATES,
+  history: Object.freeze({
+    field: 'releaseHistory',
+    limit: RELEASE_HISTORY_LIMIT,
+    replayLimit: RELEASE_REPLAY_LIMIT,
+    kinds: RELEASE_EVENT_KINDS,
+    actions: RELEASE_EVENT_ACTIONS,
+    outcomes: RELEASE_EVENT_OUTCOMES,
+  }),
+  fields: Object.freeze({
+    manifest: CANONICAL_RELEASE_MANIFEST_FIELDS,
+    envelope: CANONICAL_RELEASE_ENVELOPE_FIELDS,
+    release: CANONICAL_RELEASE_FIELDS,
+    verification: CANONICAL_RELEASE_VERIFICATION_FIELDS,
+    evidence: RELEASE_EVIDENCE_FIELDS,
+  }),
+  identity: Object.freeze({
+    repository: Object.freeze(['envelope.repo']),
+    service: Object.freeze(['envelope.service']),
+    model: Object.freeze([
+      'models.implementation', 'models.review', 'units[].implementationModel',
+    ]),
+  }),
+})
+
+const isObject = (value) => value != null && typeof value === 'object' && !Array.isArray(value)
+const nonEmpty = (value) => typeof value === 'string' && value.trim() !== ''
+const validIso = (value) => nonEmpty(value) && Number.isFinite(Date.parse(value)) && new Date(value).toISOString() === value
+
+const CONTROL_CHARACTERS = /[\u0000-\u001f\u007f]/
+const SAFE_NAME = /^[A-Za-z0-9][A-Za-z0-9._-]*$/
+const SAFE_SHA = /^[0-9a-fA-F]{7,64}$/
+const SAFE_REVISION = /^[A-Za-z0-9](?:[A-Za-z0-9-]{0,125}[A-Za-z0-9])?$/
+const SAFE_PR = /^(?:[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+)?#[1-9][0-9]*$/
+
+export const RELEASE_ARTIFACT_TYPES = Object.freeze({
+  'release-state': Object.freeze(['manifest', 'tag']),
+  tag: Object.freeze(['manifest', 'tag', 'sha']),
+  candidate: Object.freeze(['manifest', 'tag', 'sha', 'revision', 'url']),
+  traffic: Object.freeze(['manifest', 'revision', 'url', 'service']),
+  'processing-control': Object.freeze(['manifest', 'service', 'url']),
+  'github-release': Object.freeze(['manifest', 'tag', 'sha', 'url']),
+  'metadata-delivery': Object.freeze(['manifest', 'pull-request', 'sha', 'url', 'tag']),
+})
+
+const MANIFEST_LOCATORS = Object.freeze({
+  'release-state': Object.freeze(['step', 'release.attempt', 'release.attempt.evidence']),
+  tag: Object.freeze(['release.rcTag', 'release.attempt.rcTag', 'release.tagged', 'release.tagSha']),
+  candidate: Object.freeze([
+    'release.candidateIdentity', 'release.candidateRevision', 'release.candidateSha',
+    'release.candidateUrl', 'release.candidateVerdict',
+  ]),
+  traffic: Object.freeze([
+    'release.recheckFence', 'release.previousRevision', 'verification.live',
+    'verification.liveVerdict', 'verification.serving',
+  ]),
+  'processing-control': Object.freeze(['envelope.durableProcessing', 'release.quiescence']),
+  'github-release': Object.freeze(['release.tagged', 'release.tagSha', 'evidence.releaseRef']),
+  'metadata-delivery': Object.freeze(['release.metadataPr']),
+})
+
+function canonicalJson(value) {
+  if (Array.isArray(value)) return `[${value.map(canonicalJson).join(',')}]`
+  if (isObject(value)) return `{${Object.keys(value).sort().map((key) => `${JSON.stringify(key)}:${canonicalJson(value[key])}`).join(',')}}`
+  return JSON.stringify(value)
+}
+
+export function releaseReplayDigest(entry) {
+  const { digest, ...payload } = entry
+  return createHash('sha256').update(canonicalJson(payload)).digest('hex')
+}
+
+function canonicalVersions(manifest) {
+  const candidates = [
+    manifest?.release?.version,
+    typeof manifest?.envelope?.version === 'string' ? manifest.envelope.version : null,
+    manifest?.envelope?.version?.next,
+    manifest?.release?.versionPlan?.version,
+    manifest?.release?.versionPlan?.next,
+  ]
+  return candidates.filter(nonEmpty).map((value) => value.replace(/^v/, ''))
+}
+
+function uniqueLocators(values) {
+  return [...new Set(values.filter(nonEmpty))]
+}
+
+function finalTags(manifest) {
+  return uniqueLocators(canonicalVersions(manifest).map((version) => `v${version}`))
+}
+
+function canonicalLocators(manifest, subject, type) {
+  const release = manifest?.release || {}
+  const envelope = manifest?.envelope || {}
+  const identity = release.candidateIdentity || {}
+  const metadata = release.metadataPr || {}
+  const releaseRef = manifest?.evidence?.releaseRef
+  const releaseRefTag = isObject(releaseRef) ? releaseRef.tag : null
+  const releaseRefUrl = isObject(releaseRef) ? releaseRef.url : releaseRef
+  const rcTags = [release.rcTag, release.attempt?.rcTag]
+
+  const bySubject = {
+    'release-state': {
+      tag: rcTags,
+    },
+    tag: {
+      tag: [...rcTags, ...finalTags(manifest)],
+      sha: [release.candidateSha, release.tagSha, manifest?.shippedSha],
+    },
+    candidate: {
+      tag: rcTags,
+      sha: [release.candidateSha, identity.sourceSha],
+      revision: [release.candidateRevision, identity.revision],
+      url: [release.candidateUrl, identity.url],
+    },
+    traffic: {
+      revision: [
+        release.candidateRevision,
+        release.previousRevision,
+        release.recheckFence?.candidateResolvesTo,
+        manifest?.verification?.live?.revision,
+        manifest?.verification?.serving?.revision,
+      ],
+      url: [
+        release.recheckFence?.trafficUrl,
+        manifest?.verification?.live?.target,
+        manifest?.verification?.liveVerdict?.target,
+        manifest?.verification?.serving?.target,
+      ],
+      service: [envelope.service],
+    },
+    'processing-control': {
+      service: [envelope.service, envelope.durableProcessing?.service, release.quiescence?.service],
+      url: [envelope.durableProcessing?.url, release.quiescence?.url],
+    },
+    'github-release': {
+      tag: [...finalTags(manifest), releaseRefTag],
+      sha: [release.tagSha, manifest?.shippedSha],
+      url: [releaseRefUrl],
+    },
+    'metadata-delivery': {
+      tag: nonEmpty(metadata.version) ? [`v${metadata.version.replace(/^v/, '')}`] : [],
+      sha: [metadata.sha],
+      url: [metadata.url],
+      'pull-request': Number.isSafeInteger(metadata.number) && metadata.number > 0
+        ? [`#${metadata.number}`, nonEmpty(envelope.repo) ? `${envelope.repo}#${metadata.number}` : null]
+        : [],
+    },
+  }
+  return uniqueLocators(bySubject[subject]?.[type] || [])
+}
+
+function tagErrors(locator, label) {
+  const errors = []
+  if (!SAFE_NAME.test(locator) || locator.length > 255 || locator.includes('..') || locator.includes('@{') || /[~^:?*\[\\]/.test(locator) || locator.endsWith('.lock')) {
+    return [`${label} is not a safe Git tag name`]
+  }
+  return errors
+}
+
+const UNSAFE_URL_CODE_POINTS = /[\\\u2215\u2044\uff0f\u29f8\u2024\uff0e\ufe52\uff61]/u
+
+function urlQueryErrors(locator, label) {
+  const queryStart = locator.indexOf('?')
+  if (queryStart === -1) return []
+  let decodedQuery = locator.slice(queryStart + 1).split('#', 1)[0]
+  while (true) {
+    if (CONTROL_CHARACTERS.test(decodedQuery) || decodedQuery.includes('\\')) {
+      return [`${label} query contains a control character or backslash`]
+    }
+    if (!decodedQuery.includes('%')) return []
+    if (/%(?![0-9A-Fa-f]{2})/.test(decodedQuery)) return [`${label} query contains invalid percent encoding`]
+    let next
+    try {
+      next = decodeURIComponent(decodedQuery)
+    } catch {
+      return [`${label} query contains invalid percent encoding`]
+    }
+    if (next === decodedQuery) return []
+    decodedQuery = next
+  }
+}
+
+function urlPathErrors(locator, label) {
+  const authority = locator.match(/^https:\/\/[^/?#]*/i)?.[0]
+  let pathAndQuery = authority ? locator.slice(authority.length) : locator
+  const queryOrFragment = pathAndQuery.search(/[?#]/)
+  let decodedPath = queryOrFragment === -1 ? pathAndQuery : pathAndQuery.slice(0, queryOrFragment)
+  while (true) {
+    if (CONTROL_CHARACTERS.test(decodedPath) || UNSAFE_URL_CODE_POINTS.test(decodedPath)) {
+      return [`${label} contains an unsafe path separator, control, or lookalike`]
+    }
+    if (decodedPath.split('/').some((segment) => segment === '.' || segment === '..')) {
+      return [`${label} may not contain traversal segments`]
+    }
+    if (!decodedPath.includes('%')) return []
+    if (/%(?![0-9A-Fa-f]{2})/.test(decodedPath)) return [`${label} contains invalid percent encoding`]
+    let next
+    try {
+      next = decodeURIComponent(decodedPath)
+    } catch {
+      return [`${label} contains invalid percent encoding`]
+    }
+    if (next.split('/').length !== decodedPath.split('/').length || next.includes('\\')) {
+      return [`${label} percent encoding may not decode to a path separator`]
+    }
+    if (next === decodedPath) return []
+    decodedPath = next
+  }
+}
+
+function urlErrors(locator, label) {
+  let url
+  try {
+    url = new URL(locator)
+  } catch {
+    return [`${label} must be an absolute HTTPS URL`]
+  }
+  const errors = []
+  if (url.protocol !== 'https:' || url.username || url.password || url.hash || !url.hostname) errors.push(`${label} must be an absolute credential-free HTTPS URL without a fragment`)
+  errors.push(...urlPathErrors(locator, label))
+  errors.push(...urlQueryErrors(locator, label))
+  return errors
+}
+
+function locatorErrors(artifact, label, manifest, subject) {
+  const { type, locator } = artifact
+  if (typeof locator !== 'string' || locator.length === 0 || locator !== locator.trim()) return [`${label}.locator must be a non-empty unpadded string`]
+  if (locator.length > RELEASE_LOCATOR_LIMIT) return [`${label}.locator exceeds ${RELEASE_LOCATOR_LIMIT} characters`]
+  if (CONTROL_CHARACTERS.test(locator)) return [`${label}.locator contains control characters`]
+  if (type !== 'url' && (locator.startsWith('/') || /^[A-Za-z]:[\\/]/.test(locator))) return [`${label}.locator may not be an absolute local path`]
+  if (type !== 'url' && locator.split(/[\\/]/).some((segment) => segment === '.' || segment === '..')) return [`${label}.locator may not contain traversal segments`]
+  if (type === 'manifest') {
+    return MANIFEST_LOCATORS[subject]?.includes(locator) ? [] : [`${label}.locator is not a canonical ${subject} manifest field`]
+  }
+  let errors = []
+  if (type === 'tag') errors = tagErrors(locator, `${label}.locator`)
+  else if (type === 'url') errors = urlErrors(locator, `${label}.locator`)
+  if (type === 'sha') {
+    if (!SAFE_SHA.test(locator)) return [`${label}.locator is not a Git SHA`]
+  } else if (type === 'revision' || type === 'service') {
+    if (!SAFE_REVISION.test(locator)) return [`${label}.locator is not a safe ${type} name`]
+  } else if (type === 'pull-request') {
+    if (!SAFE_PR.test(locator)) return [`${label}.locator is not a pull request reference`]
+  } else if (!['tag', 'url', 'sha'].includes(type)) {
+    return [`${label}.type is unknown`]
+  }
+  if (errors.length) return errors
+  if (subject === 'release-state' && type === 'tag') return []
+  const canonical = canonicalLocators(manifest, subject, type)
+  if (canonical.length === 0) return [`${label}.locator has no canonical ${subject} ${type} identity in the manifest`]
+  if (!canonical.includes(locator)) return [`${label}.locator does not match the canonical ${subject} ${type} identity`]
+  return []
+}
+
+function artifactErrors(artifacts, label, manifest, subject) {
+  if (!Array.isArray(artifacts) || artifacts.length === 0) return [`${label}.artifacts must be a non-empty array`]
+  if (artifacts.length > RELEASE_ARTIFACT_LIMIT) return [`${label}.artifacts exceeds ${RELEASE_ARTIFACT_LIMIT}`]
+  const errors = []
+  for (const [index, artifact] of artifacts.entries()) {
+    if (!isObject(artifact) || !nonEmpty(artifact.type) || !nonEmpty(artifact.locator)) {
+      errors.push(`${label}.artifacts[${index}] must be {type, locator} with non-empty strings`)
+    } else if (Object.keys(artifact).some((key) => !['type', 'locator'].includes(key))) {
+      errors.push(`${label}.artifacts[${index}] contains unknown fields`)
+    } else if (!RELEASE_ARTIFACT_TYPES[subject]?.includes(artifact.type)) {
+      errors.push(`${label}.artifacts[${index}].type ${artifact.type} is not allowed for ${subject}`)
+    } else {
+      errors.push(...locatorErrors(artifact, `${label}.artifacts[${index}]`, manifest, subject))
+    }
+  }
+  return errors
+}
+
+function stateShapeErrors(value, label) {
+  if (!isObject(value)) return [`${label} must be an object`]
+  const errors = []
+  if (value.step !== null && !RELEASE_STEPS.includes(value.step)) errors.push(`${label}.step is not canonical`)
+  if (value.attemptState !== null && !ATTEMPT_STATES.includes(value.attemptState)) errors.push(`${label}.attemptState is not canonical`)
+  if (Object.keys(value).some((key) => !['step', 'attemptState'].includes(key))) errors.push(`${label} contains unknown fields`)
+  return errors
+}
+
+function eventErrors(event, expectedSequence, label, manifest) {
+  if (!isObject(event)) return [`${label} must be an object`]
+  const errors = []
+  const common = ['id', 'sequence', 'at', 'kind', 'subject', 'artifacts']
+  if (event.id !== `release-event-${expectedSequence}`) errors.push(`${label}.id must equal release-event-${expectedSequence}`)
+  if (event.sequence !== expectedSequence) errors.push(`${label}.sequence must be contiguous (${expectedSequence})`)
+  if (!validIso(event.at)) errors.push(`${label}.at must be a canonical ISO writer timestamp`)
+  if (!RELEASE_EVENT_KINDS.includes(event.kind)) errors.push(`${label}.kind is not canonical`)
+  if (event.kind === 'state') {
+    errors.push(...artifactErrors(event.artifacts, label, manifest, 'release-state'))
+    const allowed = [...common, 'prior', 'next']
+    if (event.subject !== 'release-state') errors.push(`${label}.subject must be release-state`)
+    errors.push(...stateShapeErrors(event.prior, `${label}.prior`))
+    errors.push(...stateShapeErrors(event.next, `${label}.next`))
+    if (JSON.stringify(event.prior) === JSON.stringify(event.next)) errors.push(`${label} state delta must change`)
+    if (Object.keys(event).some((key) => !allowed.includes(key))) errors.push(`${label} contains unknown fields`)
+  } else {
+    errors.push(...artifactErrors(event.artifacts, label, manifest, event.subject))
+    const allowed = [...common, 'correlationId', 'state', ...(event.kind === 'result' ? ['outcome'] : [])]
+    if (!RELEASE_EVENT_ACTIONS.includes(event.subject)) errors.push(`${label}.subject is not a canonical outward action`)
+    if (!nonEmpty(event.correlationId)) errors.push(`${label}.correlationId must be non-empty`)
+    errors.push(...stateShapeErrors(event.state, `${label}.state`))
+    if (event.kind === 'result' && !RELEASE_EVENT_OUTCOMES.includes(event.outcome)) errors.push(`${label}.outcome is not canonical`)
+    if (event.kind === 'intent' && event.outcome !== undefined) errors.push(`${label}.intent may not carry outcome`)
+    if (Object.keys(event).some((key) => !allowed.includes(key))) errors.push(`${label} contains unknown fields`)
+  }
+  return errors
+}
+
+function replayPayload(event) {
+  const payload = { state: event?.state, artifacts: event?.artifacts }
+  if (event?.kind === 'result') payload.outcome = event.outcome
+  return payload
+}
+
+function replayLedgerErrors(manifest, history) {
+  const actionEvents = history.events.filter((event) => event?.kind === 'intent' || event?.kind === 'result')
+  const summarizedActions = RELEASE_EVENT_ACTIONS.reduce(
+    (total, subject) => total + (history.truncated?.bySubject?.[subject] || 0), 0,
+  )
+  const ledger = history.replayLedger
+  if (ledger === undefined) {
+    return actionEvents.length || summarizedActions
+      ? ['releaseHistory.replayLedger is required for outward-action replay protection']
+      : []
+  }
+  if (!Array.isArray(ledger) || ledger.length > RELEASE_REPLAY_LIMIT) {
+    return [`releaseHistory.replayLedger must be an array bounded at ${RELEASE_REPLAY_LIMIT}`]
+  }
+  const errors = []
+  const correlations = new Set()
+  const identities = new Set()
+  for (const [index, entry] of ledger.entries()) {
+    const label = `releaseHistory.replayLedger[${index}]`
+    if (!isObject(entry)) {
+      errors.push(`${label} must be an object`)
+      continue
+    }
+    const allowed = ['subject', 'correlationId', 'intentSequence', 'intentAt', 'intent', 'resultSequence', 'resultAt', 'result', 'digest']
+    if (Object.keys(entry).some((key) => !allowed.includes(key))) errors.push(`${label} contains unknown fields`)
+    if (!RELEASE_EVENT_ACTIONS.includes(entry.subject)) errors.push(`${label}.subject is not canonical`)
+    if (!nonEmpty(entry.correlationId) || CONTROL_CHARACTERS.test(entry.correlationId) || entry.correlationId.length > 255) errors.push(`${label}.correlationId is malformed`)
+    const identity = `${entry.subject}:${entry.correlationId}`
+    if (identities.has(identity)) errors.push(`${label} duplicates action identity ${identity}`)
+    if (correlations.has(entry.correlationId)) errors.push(`${label} collides on correlationId ${entry.correlationId}`)
+    identities.add(identity)
+    correlations.add(entry.correlationId)
+    if (!Number.isSafeInteger(entry.intentSequence) || entry.intentSequence < 1 || !validIso(entry.intentAt)) errors.push(`${label} has malformed intent sequence/time`)
+    if (!isObject(entry.intent)) errors.push(`${label}.intent must retain canonical payload evidence`)
+    else {
+      errors.push(...stateShapeErrors(entry.intent.state, `${label}.intent.state`))
+      errors.push(...artifactErrors(entry.intent.artifacts, `${label}.intent`, manifest, entry.subject))
+      if (Object.keys(entry.intent).some((key) => !['state', 'artifacts'].includes(key))) errors.push(`${label}.intent contains unknown fields`)
+    }
+    if (entry.result === null) {
+      if (entry.resultSequence !== null || entry.resultAt !== null) errors.push(`${label} unresolved intent must have null result sequence/time`)
+    } else if (!isObject(entry.result)) {
+      errors.push(`${label}.result must be null or canonical payload evidence`)
+    } else {
+      if (!Number.isSafeInteger(entry.resultSequence) || entry.resultSequence <= entry.intentSequence || !validIso(entry.resultAt) || Date.parse(entry.resultAt) < Date.parse(entry.intentAt)) errors.push(`${label} has malformed result sequence/time`)
+      errors.push(...stateShapeErrors(entry.result.state, `${label}.result.state`))
+      errors.push(...artifactErrors(entry.result.artifacts, `${label}.result`, manifest, entry.subject))
+      if (!RELEASE_EVENT_OUTCOMES.includes(entry.result.outcome)) errors.push(`${label}.result.outcome is not canonical`)
+      if (Object.keys(entry.result).some((key) => !['state', 'artifacts', 'outcome'].includes(key))) errors.push(`${label}.result contains unknown fields`)
+    }
+    if (!/^[0-9a-f]{64}$/.test(entry.digest) || releaseReplayDigest(entry) !== entry.digest) errors.push(`${label}.digest does not match canonical replay evidence`)
+  }
+  const sequenceOwners = new Map()
+  for (const [index, entry] of ledger.entries()) {
+    if (!isObject(entry)) continue
+    for (const kind of ['intent', 'result']) {
+      const sequence = entry[`${kind}Sequence`]
+      if (sequence === null || !Number.isSafeInteger(sequence)) continue
+      if (sequenceOwners.has(sequence)) errors.push(`releaseHistory.replayLedger[${index}].${kind}Sequence collides with ${sequenceOwners.get(sequence)}`)
+      sequenceOwners.set(sequence, `replayLedger[${index}].${kind}Sequence`)
+      const retained = history.events.find((event) => event.sequence === sequence)
+      if (sequence > (history.truncated?.throughSequence || 0) && !retained) errors.push(`releaseHistory.replayLedger[${index}].${kind}Sequence is neither compacted nor retained`)
+    }
+  }
+  const byIdentity = new Map(ledger.filter(isObject).map((entry) => [`${entry.subject}:${entry.correlationId}`, entry]))
+  for (const [index, event] of history.events.entries()) {
+    if (event?.kind !== 'intent' && event?.kind !== 'result') continue
+    const entry = byIdentity.get(`${event.subject}:${event.correlationId}`)
+    const kind = event.kind
+    if (!entry || canonicalJson(entry[kind]) !== canonicalJson(replayPayload(event)) || entry[`${kind}Sequence`] !== event.sequence || entry[`${kind}At`] !== event.at) {
+      errors.push(`releaseHistory.events[${index}] does not match replay ledger evidence`)
+    }
+  }
+  if (history.truncated) {
+    const through = history.truncated.throughSequence
+    const compactedBySubject = Object.fromEntries(RELEASE_EVENT_ACTIONS.map((subject) => [subject, 0]))
+    const compactedByKind = { intent: 0, result: 0 }
+    const compactedByOutcome = {}
+    let completedWaitMs = 0
+    let failedWaitMs = 0
+    for (const entry of ledger.filter(isObject)) {
+      if (entry.intentSequence <= through) { compactedBySubject[entry.subject] += 1; compactedByKind.intent += 1 }
+      if (entry.resultSequence !== null && entry.resultSequence <= through) {
+        compactedBySubject[entry.subject] += 1; compactedByKind.result += 1
+        compactedByOutcome[entry.result.outcome] = (compactedByOutcome[entry.result.outcome] || 0) + 1
+        const wait = Date.parse(entry.resultAt) - Date.parse(entry.intentAt)
+        completedWaitMs += wait; if (entry.result.outcome === 'failed') failedWaitMs += wait
+      }
+    }
+    for (const subject of RELEASE_EVENT_ACTIONS) {
+      if (compactedBySubject[subject] !== (history.truncated.bySubject?.[subject] || 0)) errors.push(`releaseHistory.truncated.bySubject.${subject} does not match replay ledger sequence evidence`)
+    }
+    for (const kind of ['intent', 'result']) {
+      if (compactedByKind[kind] !== (history.truncated.byKind?.[kind] || 0)) errors.push(`releaseHistory.truncated.byKind.${kind} does not match replay ledger sequence evidence`)
+    }
+    for (const outcome of RELEASE_EVENT_OUTCOMES) {
+      if ((compactedByOutcome[outcome] || 0) !== (history.truncated.byOutcome?.[outcome] || 0)) errors.push(`releaseHistory.truncated.byOutcome.${outcome} does not match replay ledger sequence evidence`)
+    }
+    if (completedWaitMs !== history.truncated.completedWaitMs) errors.push('releaseHistory.truncated.completedWaitMs does not match replay ledger intervals')
+    if (failedWaitMs !== history.truncated.failedWaitMs) errors.push('releaseHistory.truncated.failedWaitMs does not match replay ledger intervals')
+    const expectedOpen = ledger.filter((entry) => isObject(entry) && entry.intentSequence <= through && (entry.resultSequence === null || entry.resultSequence > through)).map((entry) => ({ subject: entry.subject, correlationId: entry.correlationId, at: entry.intentAt }))
+    if (canonicalJson(expectedOpen) !== canonicalJson(history.truncated.openIntents || [])) errors.push('releaseHistory.truncated.openIntents does not match its compaction boundary')
+  }
+  return errors
+}
+
+export function validateReleaseHistory(manifest) {
+  if (manifest?.skill !== undefined && manifest.skill !== 'resolve-release') return []
+  const history = manifest?.releaseHistory
+  if (history === undefined || history === null) return []
+  if (!isObject(history)) return ['releaseHistory must be an object']
+  const errors = []
+  if (!Array.isArray(history.events)) return ['releaseHistory.events must be an array']
+  if (history.events.length > RELEASE_HISTORY_LIMIT) errors.push(`releaseHistory.events exceeds ${RELEASE_HISTORY_LIMIT}`)
+  errors.push(...replayLedgerErrors(manifest, history))
+  const truncated = history.truncated
+  if (truncated !== undefined) {
+    const allowed = ['count', 'firstSequence', 'firstAt', 'throughSequence', 'throughAt', 'boundary', 'byKind', 'bySubject', 'byOutcome', 'completedWaitMs', 'failedWaitMs', 'openIntents']
+    if (!isObject(truncated) || !Number.isSafeInteger(truncated.count) || truncated.count < 1) {
+      errors.push('releaseHistory.truncated must summarize at least one removed event')
+    } else {
+      if (truncated.firstSequence !== 1 || truncated.throughSequence !== truncated.count) errors.push('releaseHistory.truncated sequence range is inconsistent')
+      if (!validIso(truncated.firstAt) || !validIso(truncated.throughAt)) {
+        errors.push('releaseHistory.truncated timestamps must be canonical ISO values')
+      } else if (Date.parse(truncated.firstAt) > Date.parse(truncated.throughAt)) {
+        errors.push('releaseHistory.truncated timestamp range is reversed')
+      }
+      errors.push(...stateShapeErrors(truncated.boundary, 'releaseHistory.truncated.boundary'))
+      const counterKeys = {
+        byKind: RELEASE_EVENT_KINDS,
+        bySubject: ['release-state', ...RELEASE_EVENT_ACTIONS],
+        byOutcome: RELEASE_EVENT_OUTCOMES,
+      }
+      for (const [field, allowedKeys] of Object.entries(counterKeys)) {
+        if (!isObject(truncated[field]) || Object.values(truncated[field]).some((count) => !Number.isSafeInteger(count) || count < 1)) {
+          errors.push(`releaseHistory.truncated.${field} must contain positive counters`)
+        } else if (Object.keys(truncated[field]).some((key) => !allowedKeys.includes(key))) {
+          errors.push(`releaseHistory.truncated.${field} contains an unknown counter`)
+        }
+      }
+      if (Object.keys(truncated).some((key) => !allowed.includes(key))) errors.push('releaseHistory.truncated contains unknown fields')
+      const counterTotal = (field) => isObject(truncated[field])
+        ? Object.values(truncated[field]).reduce((total, count) => total + (Number.isSafeInteger(count) ? count : 0), 0)
+        : 0
+      if (counterTotal('byKind') !== truncated.count || counterTotal('bySubject') !== truncated.count) errors.push('releaseHistory.truncated event counters do not equal count')
+      if (counterTotal('byOutcome') !== (truncated.byKind?.result || 0)) errors.push('releaseHistory.truncated outcome counters do not equal result count')
+
+      if (!Number.isSafeInteger(truncated.completedWaitMs) || truncated.completedWaitMs < 0) errors.push('releaseHistory.truncated.completedWaitMs must be a non-negative integer')
+      if (!Number.isSafeInteger(truncated.failedWaitMs) || truncated.failedWaitMs < 0 || truncated.failedWaitMs > truncated.completedWaitMs) errors.push('releaseHistory.truncated.failedWaitMs must be between zero and completedWaitMs')
+      if (!Array.isArray(truncated.openIntents) || truncated.openIntents.length > RELEASE_EVENT_ACTIONS.length) {
+        errors.push('releaseHistory.truncated.openIntents must be bounded by the action vocabulary')
+      } else {
+        const subjects = new Set()
+        for (const [index, intent] of truncated.openIntents.entries()) {
+          if (!isObject(intent) || !RELEASE_EVENT_ACTIONS.includes(intent.subject) || !nonEmpty(intent.correlationId) || !validIso(intent.at)) {
+            errors.push(`releaseHistory.truncated.openIntents[${index}] is malformed`)
+          } else if (subjects.has(intent.subject)) {
+            errors.push(`releaseHistory.truncated.openIntents duplicates subject ${intent.subject}`)
+          }
+          subjects.add(intent?.subject)
+        }
+      }
+    }
+  }
+  const firstSequence = truncated?.throughSequence ? truncated.throughSequence + 1 : 1
+  let boundary = isObject(truncated?.boundary) ? truncated.boundary : null
+  history.events.forEach((event, index) => {
+    errors.push(...eventErrors(event, firstSequence + index, `releaseHistory.events[${index}]`, manifest))
+    const priorAt = index === 0 ? truncated?.throughAt : history.events[index - 1]?.at
+    if (validIso(event?.at) && validIso(priorAt) && Date.parse(event.at) < Date.parse(priorAt)) {
+      errors.push(`releaseHistory.events[${index}].at precedes the prior writer event`)
+    }
+    const eventPrior = event?.kind === 'state' ? event.prior : event?.state
+    if (boundary && JSON.stringify(eventPrior) !== JSON.stringify(boundary)) {
+      errors.push(`releaseHistory.events[${index}] does not continue from the prior state boundary`)
+    }
+    if (isObject(eventPrior) && boundary === null) boundary = eventPrior
+    const eventNext = event?.kind === 'state' ? event.next : event?.state
+    if (isObject(eventNext)) boundary = eventNext
+  })
+  const outstanding = new Map((truncated?.openIntents || []).map((intent) => [intent.subject, intent]))
+  for (const [index, event] of history.events.entries()) {
+    if (event.kind === 'intent') {
+      if (outstanding.has(event.subject)) errors.push(`releaseHistory.events[${index}] duplicates unresolved ${event.subject} intent`)
+      outstanding.set(event.subject, event)
+    }
+    if (event.kind === 'result') {
+      const intent = outstanding.get(event.subject)
+      if (!intent || intent.correlationId !== event.correlationId) {
+        errors.push(`releaseHistory.events[${index}] result has no matching unresolved intent`)
+      } else {
+        outstanding.delete(event.subject)
+      }
+    }
+  }
+  const allowedHistory = ['events', 'truncated', 'replayLedger']
+  if (Object.keys(history).some((key) => !allowedHistory.includes(key))) errors.push('releaseHistory contains unknown fields')
+  return errors
+}
+
+export function normalizeReleaseVerdict(value) {
+  if (!isObject(value)) return null
+  const state = value.state ?? value.verdict
+  if (value.state != null && value.verdict != null && value.state !== value.verdict) return null
+  if (!RELEASE_VERDICT_STATES.includes(state)) return null
+  const { verdict, ...rest } = value
+  return { ...rest, state }
+}
+
+export function classifyReleaseManifest(manifest) {
+  const step = manifest?.step
+  const attemptState = manifest?.release?.attempt?.state
+  if (step === 'done' && attemptState === 'released') return 'done'
+  if (step === 'discard' && attemptState === 'failed-pre-promotion') return 'discarded'
+  if (step === 'rollback' && attemptState === 'rolled-back') return 'rolled-back'
+  if (attemptState === 'released') return 'released-but-not-finalized'
+  return 'incomplete'
+}
+
+export function validateReleaseStateVocabulary(manifest) {
+  if (manifest?.skill !== 'resolve-release') return []
+  const errors = []
+  const envelope = isObject(manifest.envelope) ? manifest.envelope : {}
+  const release = isObject(manifest.release) ? manifest.release : {}
+  for (const field of ['repo', 'service']) {
+    if (envelope[field] != null && (typeof envelope[field] !== 'string' || envelope[field].trim() === '')) {
+      errors.push(`envelope.${field} must be a non-empty canonical identity string`)
+    }
+  }
+  if (release.candidateVerdict != null && normalizeReleaseVerdict(release.candidateVerdict) === null) {
+    errors.push('release.candidateVerdict must carry one recognized ALIVE|DEAD|EMPTY|CANNOT-RUN|BLOCKED value via state or verdict; aliases may not conflict')
+  }
+  if (release.productionEndpoints != null) {
+    const endpoints = release.productionEndpoints
+    let canonical = null
+    let service = null
+    try {
+      canonical = new URL(endpoints.canonicalProductionUrl)
+      service = new URL(endpoints.cloudRunServiceUrl)
+    } catch {}
+    const canonicalUrl = canonical && canonical.protocol === 'https:'
+      ? `${canonical.origin}${canonical.pathname.replace(/\/+$/, '')}`
+      : null
+    const serviceUrl = service && service.protocol === 'https:'
+      ? `${service.origin}${service.pathname.replace(/\/+$/, '')}`
+      : null
+    const distinct = canonical && service
+      ? canonical.hostname.toLowerCase() !== service.hostname.toLowerCase()
+      : null
+    const fingerprint = canonicalUrl && serviceUrl
+      ? createHash('sha256').update(JSON.stringify({
+          canonicalProductionUrl: canonicalUrl,
+          cloudRunServiceUrl: serviceUrl,
+        })).digest('hex')
+      : null
+    if (!isObject(endpoints)
+      || endpoints.schemaVersion !== 1
+      || canonicalUrl !== endpoints.canonicalProductionUrl
+      || serviceUrl !== endpoints.cloudRunServiceUrl
+      || endpoints.distinctPublicEdgeHost !== distinct
+      || endpoints.publicEdgeHostname !== (distinct ? canonical.hostname.toLowerCase() : null)
+      || endpoints.configurationFingerprint !== fingerprint
+      || endpoints.canonicalSource !== 'deploy-trigger-config'
+      || endpoints.serviceSource !== 'cloud-run-service'
+      || !Number.isFinite(Date.parse(endpoints.checkedAt))) {
+      errors.push('release.productionEndpoints must be the canonical schemaVersion-1 preflight record with derived HTTPS URLs, applicability, sources, fingerprint, and checkedAt')
+    }
+  }
+  return errors
+}