@1aboveio/skills 0.10.0

package/skills/engineering/resolve-issues/scripts/component-candidate.mjs

@@ -0,0 +1,962 @@
+import {
+  AUTHORIZATION_BOUNDARY_KINDS,
+  REOPEN_REASONS,
+  classifyRoundMetadata,
+  completedReviewRounds,
+  deliveryFlow,
+  deliveryMode,
+  deliveryProvider,
+  DELIVERY_MAX_NUDGES,
+  validateDeliveryAttempt,
+} from './fix-rounds.mjs'
+import {
+  checksForPhase,
+  validatePublishOnlyEvidence,
+  validateQueueExecutionArtifact,
+  validateRequiredCheckExecution,
+  validateRequiredCheckPlan,
+} from '../../engineering-runtime/scripts/required-check-plan.mjs'
+import { normalizeChangedSurfaces } from './round-metadata.mjs'
+import { completionBlockers, effectiveUnitKind } from './unit-lifecycle.mjs'
+import { reconciliationErrors } from './reconcile-contained-unit-prs.mjs'
+
+export const COMPONENT_CANDIDATE_STATES = ['assembling', 'frozen', 'authorized']
+export const COMPONENT_ROUND_CLASSES = ['unit-discovery', 'integration-fix', 'terminal-authorization']
+export const COMPONENT_ASSEMBLY_RESULTS = ['clean', 'conflict']
+export const COMPONENT_TEST_RESULTS = ['green', 'red', 'not-run']
+
+const REOPEN_BOUNDARY_KIND = {
+  'ci-red': 'ci',
+  'head-rewritten': 'head',
+  'contract-revised': 'contract',
+  'integration-finding': 'integration',
+  // #941 / epic-876: external bot/human CHANGES_REQUESTED after independent PASS
+  'external-review': 'head',
+}
+const SHA_RE = /^[0-9a-f]{7,64}$/i
+const clone = (value) => structuredClone(value)
+const isObject = (value) => value != null && typeof value === 'object' && !Array.isArray(value)
+const nonEmpty = (value) => typeof value === 'string' && value.trim().length > 0
+const same = (left, right) => JSON.stringify(left) === JSON.stringify(right)
+const unique = (values) => Array.isArray(values) && new Set(values).size === values.length
+
+function assertExactObject(value, allowed, label) {
+  if (!isObject(value)) throw new Error(`${label} must be an object`)
+  const unknown = Object.keys(value).filter((key) => !allowed.includes(key))
+  if (unknown.length) throw new Error(`${label} has unknown property ${unknown[0]}`)
+}
+
+function assertSha(value, label) {
+  if (!nonEmpty(value) || !SHA_RE.test(value)) throw new Error(`${label} must be a 7-64 character hexadecimal SHA`)
+}
+
+function componentAndUnits(manifest, componentId) {
+  const components = Array.isArray(manifest?.components) ? manifest.components : []
+  const component = components.find((entry) => entry?.id === componentId)
+  if (!component) throw new Error(`component candidate: no component ${componentId} in this run`)
+  if (!Array.isArray(component.units) || !component.units.length || !unique(component.units) || component.units.some((id) => !nonEmpty(id))) {
+    throw new Error(`component candidate ${componentId}: units must be a non-empty unique array of unit ids`)
+  }
+  const byId = new Map((Array.isArray(manifest?.units) ? manifest.units : []).map((unit) => [unit?.id, unit]))
+  for (const id of component.units) if (!byId.has(id)) throw new Error(`component candidate ${componentId}: unit ${id} is not in the run roster`)
+  return { component, byId }
+}
+
+function boundary(value, label) {
+  assertExactObject(value, ['kind', 'value'], label)
+  if (!AUTHORIZATION_BOUNDARY_KINDS.includes(value.kind)) throw new Error(`${label}.kind must be one of ${AUTHORIZATION_BOUNDARY_KINDS.join('|')}`)
+  if (!nonEmpty(value.value)) throw new Error(`${label}.value must be a non-empty string`)
+  return clone(value)
+}
+
+function typedPreliminaryReview(entry, headSha, label) {
+  if (!isObject(entry) || entry.verdict !== 'PASS' || entry.headSha !== headSha) return null
+  if (classifyRoundMetadata(entry).legacy) return null
+  if (!Number.isInteger(entry.round) || entry.round < 1) throw new Error(`${label}.round must be a positive integer`)
+  if (!['code', 'evidence'].includes(entry.reviewSubject)) throw new Error(`${label} needs typed reviewSubject`)
+  return {
+    round: entry.round,
+    verdict: entry.verdict,
+    headSha: entry.headSha,
+    reviewSubject: entry.reviewSubject,
+    authorizationBoundary: boundary(entry.authorizationBoundary, `${label}.authorizationBoundary`),
+  }
+}
+
+function legacyRoundAuthority(entry, headSha) {
+  if (!isObject(entry) || entry.verdict !== 'PASS' || entry.headSha !== headSha) return null
+  if (!classifyRoundMetadata(entry).legacy) return null
+  const allowed = ['round', 'verdict', 'headSha', 'themeIds', 'scope', 'at', 'evidenceClasses', 'productionMoved']
+  if (Object.keys(entry).some((key) => !allowed.includes(key))) return null
+  if (!Number.isInteger(entry.round) || entry.round < 1 || typeof entry.productionMoved !== 'boolean') return null
+  return entry
+}
+
+function deepReviewAuthority(entry, headSha) {
+  if (!isObject(entry) || entry.verdict !== 'PASS' || entry.headSha !== headSha) return null
+  const hasThemes = Object.prototype.hasOwnProperty.call(entry, 'themes')
+  const hasFindings = Object.prototype.hasOwnProperty.call(entry, 'findings')
+  const allowed = hasThemes
+    ? ['round', 'verdict', 'themes', 'oracleEscalation', 'round1Depth', 'headSha']
+    : ['round', 'verdict', 'findings', 'oracleEscalation', 'round1Depth', 'headSha']
+  if (Object.keys(entry).some((key) => !allowed.includes(key))) return null
+  if (!Number.isInteger(entry.round) || entry.round < 1 || hasThemes === hasFindings) return null
+  if (hasThemes && !Array.isArray(entry.themes)) return null
+  if (hasFindings && !Array.isArray(entry.findings)) return null
+  return entry
+}
+
+function legacyPreliminaryReview(unit, headSha) {
+  const candidates = []
+  for (const [index, entry] of unit.rounds.entries()) {
+    const valid = legacyRoundAuthority(entry, headSha)
+    if (valid) candidates.push({ entry: valid, source: 'rounds', sourceRank: 0, index })
+  }
+  for (const [index, entry] of unit.reviewHistory.entries()) {
+    const valid = deepReviewAuthority(entry, headSha)
+    if (valid) candidates.push({ entry: valid, source: 'reviewHistory', sourceRank: 1, index })
+  }
+  candidates.sort((left, right) => left.entry.round - right.entry.round
+    || left.sourceRank - right.sourceRank
+    || left.index - right.index)
+  const selected = candidates.at(-1)
+  if (!selected) return null
+  return {
+    round: selected.entry.round,
+    verdict: selected.entry.verdict,
+    headSha: selected.entry.headSha,
+    reviewSubject: 'unknown',
+    authorizationBoundary: 'unknown',
+    legacy: true,
+    source: selected.source,
+  }
+}
+
+function preliminaryEvidence(unit, componentId) {
+  if (unit?.lastVerdict !== 'PASS') throw new Error(`component candidate ${componentId}: unit ${unit?.id} is not preliminarily ready (lastVerdict must be PASS)`)
+  assertSha(unit?.pushedSha, `component candidate ${componentId}: unit ${unit?.id}.pushedSha`)
+  if (unit.rounds !== undefined && !Array.isArray(unit.rounds)) throw new Error(`component candidate ${componentId}: unit ${unit.id}.rounds must be an array`)
+  if (unit.reviewHistory !== undefined && !Array.isArray(unit.reviewHistory)) throw new Error(`component candidate ${componentId}: unit ${unit.id}.reviewHistory must be an array`)
+  const rounds = Array.isArray(unit.rounds) ? unit.rounds : []
+  const reviewHistory = Array.isArray(unit.reviewHistory) ? unit.reviewHistory : []
+  const typed = rounds
+    .map((entry, index) => typedPreliminaryReview(entry, unit.pushedSha, `component candidate ${componentId}: unit ${unit.id}.rounds[${index}]`))
+    .filter(Boolean)
+    .at(-1)
+  const preliminaryReview = typed ?? legacyPreliminaryReview({ rounds, reviewHistory }, unit.pushedSha)
+  if (!preliminaryReview) {
+    throw new Error(`component candidate ${componentId}: unit ${unit?.id} needs a preliminary PASS on its exact pushed head`)
+  }
+  return {
+    unitId: unit.id,
+    headSha: unit.pushedSha,
+    pr: nonEmpty(unit.pr) ? unit.pr : null,
+    preliminaryReview,
+    reviewRoundCount: completedReviewRounds(unit),
+  }
+}
+
+function assertIncludedUnits(component, includedUnits) {
+  if (!Array.isArray(includedUnits) || !includedUnits.length || !unique(includedUnits) || includedUnits.some((id) => !nonEmpty(id))) {
+    throw new Error(`component candidate ${component.id}: includedUnits must be a non-empty unique array`)
+  }
+  const members = new Set(component.units)
+  for (const id of includedUnits) if (!members.has(id)) throw new Error(`component candidate ${component.id}: included unit ${id} is not owned by this component`)
+  const ordered = component.units.filter((id) => includedUnits.includes(id))
+  if (!same(ordered, includedUnits)) throw new Error(`component candidate ${component.id}: includedUnits must follow component unit order`)
+}
+
+function integratedResult(value, componentId) {
+  assertExactObject(value, ['assembly', 'tests', 'conflicts', 'failedTests'], `component candidate ${componentId}.integrated`)
+  if (!COMPONENT_ASSEMBLY_RESULTS.includes(value.assembly)) throw new Error(`component candidate ${componentId}: integrated.assembly must be ${COMPONENT_ASSEMBLY_RESULTS.join('|')}`)
+  if (!COMPONENT_TEST_RESULTS.includes(value.tests)) throw new Error(`component candidate ${componentId}: integrated.tests must be ${COMPONENT_TEST_RESULTS.join('|')}`)
+  if (!Array.isArray(value.conflicts) || value.conflicts.some((conflict) => !isObject(conflict) || !nonEmpty(conflict.unit) || !Array.isArray(conflict.files) || conflict.files.some((file) => !nonEmpty(file)))) {
+    throw new Error(`component candidate ${componentId}: integrated.conflicts must be [{ unit, files[] }]`)
+  }
+  if (!Array.isArray(value.failedTests) || value.failedTests.some((test) => !nonEmpty(test))) throw new Error(`component candidate ${componentId}: integrated.failedTests must be an array of test ids`)
+  if (value.assembly === 'clean' && value.conflicts.length) throw new Error(`component candidate ${componentId}: clean assembly cannot carry conflicts`)
+  if (value.assembly === 'conflict' && !value.conflicts.length) throw new Error(`component candidate ${componentId}: conflict assembly must name conflicts`)
+  if (value.tests === 'green' && value.failedTests.length) throw new Error(`component candidate ${componentId}: green integrated tests cannot carry failures`)
+  if (value.tests === 'red' && !value.failedTests.length) throw new Error(`component candidate ${componentId}: red integrated tests must name failed tests`)
+  return clone(value)
+}
+
+function integrationFix(value, componentId) {
+  assertExactObject(value, ['owner', 'reason', 'changedSurfaces'], `component candidate ${componentId}.integrationFix`)
+  if (value.owner !== 'integration') throw new Error(`component candidate ${componentId}: integration-fix owner must be "integration"; unit branches retain their passed heads`)
+  if (!nonEmpty(value.reason)) throw new Error(`component candidate ${componentId}: integration-fix requires a reason`)
+  return { owner: 'integration', reason: value.reason.trim(), changedSurfaces: normalizeChangedSurfaces(value.changedSurfaces) }
+}
+
+function candidateBase(existing) {
+  if (isObject(existing)) return clone(existing)
+  return { state: 'assembling', generation: 1, updates: [], frozen: null, authorizations: [], reopens: [] }
+}
+
+function transitionResult(out, componentId) {
+  const errors = validateComponentCandidates(out)
+  if (errors.length) throw new Error(`component candidate ${componentId}: invalid transition result: ${errors[0]}`)
+  return out
+}
+
+function positivePr(value) {
+  if (Number.isInteger(value) && value > 0) return value
+  const match = String(value ?? '').match(/(?:^|#)(\d+)$/)
+  return match ? Number(match[1]) : null
+}
+
+function initializedDelivery(manifest, component, candidate, authorization) {
+  const mode = deliveryMode(manifest)
+  const provider = deliveryProvider(manifest)
+  if (!['direct', 'queue'].includes(mode)) throw new Error(`component candidate ${component.id}: deliveryMode must be direct|queue`)
+  if (mode === 'queue' && !['mergify', 'github'].includes(provider)) {
+    throw new Error(`component candidate ${component.id}: queue delivery requires queueProvider mergify|github before terminal authorization`)
+  }
+  const pr = authorization.ci.pr
+  const publishedPr = positivePr(component.pr)
+  if (publishedPr != null && publishedPr !== pr) {
+    throw new Error(`component candidate ${component.id}: terminal CI PR ${pr} does not match published component PR ${publishedPr}`)
+  }
+  const prior = isObject(component.delivery) ? component.delivery : null
+  if (prior?.outcome === 'merged' || prior?.outcome === 'handed-back') {
+    throw new Error(`component candidate ${component.id}: terminal delivery outcome ${prior.outcome} cannot be re-authorized`)
+  }
+  return {
+    pr,
+    generation: candidate.generation,
+    authorizedHeadSha: authorization.headSha,
+    mode,
+    provider: mode === 'queue' ? provider : null,
+    attempts: Array.isArray(prior?.attempts) ? clone(prior.attempts) : [],
+    observations: Array.isArray(prior?.observations) ? clone(prior.observations) : [],
+    watch: null,
+    queueExecution: null,
+    outcome: null,
+    outcomeAt: null,
+    mergedSha: null,
+    mergedAt: null,
+    blockedOn: null,
+  }
+}
+
+function componentDeliveryContext(manifest, componentId, generation, headSha) {
+  const { component, byId } = componentAndUnits(manifest, componentId)
+  const candidate = candidateBase(component.candidate)
+  const authorization = Array.isArray(candidate.authorizations)
+    ? candidate.authorizations.findLast((entry) => entry?.generation === generation)
+    : null
+  if (candidate.state !== 'authorized' || generation !== candidate.generation || authorization?.generation !== generation) {
+    throw new Error(`component delivery ${componentId}: generation ${generation} is not the currently authorized component generation ${candidate.generation}`)
+  }
+  if (headSha !== candidate.frozen?.headSha || authorization.headSha !== headSha) {
+    throw new Error(`component delivery ${componentId}: ${headSha} is not the authorized frozen component HEAD ${candidate.frozen?.headSha ?? '(missing)'}`)
+  }
+  const delivery = component.delivery
+  if (!isObject(delivery) || delivery.generation !== generation || delivery.authorizedHeadSha !== headSha) {
+    throw new Error(`component delivery ${componentId}: canonical delivery record is stale or missing for authorized generation ${generation}`)
+  }
+  for (const id of component.units) {
+    const unit = byId.get(id)
+    if (effectiveUnitKind(unit) !== 'implementation') throw new Error(`component delivery ${componentId}: member ${id} is not an implementation unit`)
+    if (unit.status !== 'merge-ready') throw new Error(`component delivery ${componentId}: member ${id} is ${unit.status}, not merge-ready`)
+    const blocked = completionBlockers(manifest, unit)
+    if (blocked.length) throw new Error(`component delivery ${componentId}: member ${id} has incomplete completion dependencies: ${blocked.join(', ')}`)
+    if (unit.delivery !== undefined) throw new Error(`component delivery ${componentId}: member ${id} carries a unit delivery record; shared delivery must be canonical on the component`)
+  }
+  return { component, candidate, authorization, byId, delivery }
+}
+
+function deliveryObservation(value, label) {
+  assertExactObject(value, ['at', 'queueState', 'position', 'unmetConditions', 'ack'], label)
+  if (!nonEmpty(value.at)) throw new Error(`${label}.at is required`)
+  if (!nonEmpty(value.queueState)) throw new Error(`${label}.queueState is required`)
+  if (value.unmetConditions !== undefined && (!Array.isArray(value.unmetConditions) || value.unmetConditions.some((condition) => !nonEmpty(condition)))) {
+    throw new Error(`${label}.unmetConditions must be an array of non-empty strings`)
+  }
+  if (value.ack !== undefined && (!isObject(value.ack) || !['reaction', 'payload'].includes(value.ack.kind) || !nonEmpty(value.ack.ref))) {
+    throw new Error(`${label}.ack requires {kind: reaction|payload, ref}`)
+  }
+  return clone(value)
+}
+
+export function recordComponentDeliveryAttempt(manifest, componentId, payload) {
+  assertExactObject(payload, ['generation', 'headSha', 'attempt'], `record-component-delivery-attempt ${componentId}`)
+  if (!Number.isSafeInteger(payload.generation) || payload.generation < 1) throw new Error(`record-component-delivery-attempt ${componentId}.generation must be a positive integer`)
+  assertSha(payload.headSha, `record-component-delivery-attempt ${componentId}.headSha`)
+  const out = clone(manifest)
+  const { component, delivery } = componentDeliveryContext(out, componentId, payload.generation, payload.headSha)
+  if (delivery.outcome != null) throw new Error(`component delivery ${componentId} already reached terminal outcome ${delivery.outcome}`)
+  const attemptErrors = validateDeliveryAttempt(payload.attempt, delivery.mode, `component delivery ${componentId} attempt`, delivery.provider)
+  if (attemptErrors.length) throw new Error(attemptErrors[0])
+  if (payload.attempt.headSha !== payload.headSha) throw new Error(`component delivery ${componentId}: attempt must target the authorized component HEAD ${payload.headSha}`)
+  if (payload.attempt.pr !== undefined && positivePr(payload.attempt.pr) !== delivery.pr) throw new Error(`component delivery ${componentId}: attempt PR must equal component PR ${delivery.pr}`)
+  const sameGeneration = delivery.attempts.filter((attempt) => attempt?.generation === payload.generation)
+  if (sameGeneration.some((attempt) => attempt.action === payload.attempt.action)) {
+    throw new Error(`component delivery ${componentId}: exactly one ${payload.attempt.action} attempt is allowed for authorized generation ${payload.generation}; duplicate enqueue/merge refused`)
+  }
+  component.delivery = {
+    ...delivery,
+    attempts: [...delivery.attempts, {
+      generation: payload.generation,
+      ...clone(payload.attempt),
+      ...(delivery.mode === 'queue' ? { pr: delivery.pr } : {}),
+    }],
+  }
+  return transitionResult(out, componentId)
+}
+
+export function recordComponentDeliveryObservation(manifest, componentId, payload) {
+  assertExactObject(payload, ['generation', 'headSha', 'observation'], `record-component-delivery-observation ${componentId}`)
+  if (!Number.isSafeInteger(payload.generation) || payload.generation < 1) throw new Error(`record-component-delivery-observation ${componentId}.generation must be a positive integer`)
+  assertSha(payload.headSha, `record-component-delivery-observation ${componentId}.headSha`)
+  const out = clone(manifest)
+  const { component, delivery } = componentDeliveryContext(out, componentId, payload.generation, payload.headSha)
+  if (delivery.mode !== 'queue') throw new Error(`component delivery ${componentId}: direct delivery has no queue observations`)
+  if (delivery.outcome != null) throw new Error(`component delivery ${componentId} already reached terminal outcome ${delivery.outcome}`)
+  const observation = deliveryObservation(payload.observation, `component delivery ${componentId} observation`)
+  const previous = isObject(delivery.watch) ? delivery.watch : null
+  const position = observation.position ?? null
+  const unmetConditions = observation.unmetConditions ?? previous?.unmetConditions ?? null
+  const conditionKey = (value) => Array.isArray(value) ? value.join('\u0000') : ''
+  const moved = !previous || previous.queueState !== observation.queueState || (previous.position ?? null) !== position
+    || conditionKey(previous.unmetConditions) !== conditionKey(unmetConditions)
+  component.delivery = {
+    ...delivery,
+    observations: [...delivery.observations, { generation: payload.generation, headSha: payload.headSha, ...observation }],
+    watch: {
+      firstObservedAt: previous?.firstObservedAt ?? observation.at,
+      lastObservedAt: observation.at,
+      lastChangeAt: moved ? observation.at : previous.lastChangeAt,
+      queueState: observation.queueState,
+      position,
+      polls: (previous?.polls ?? 0) + 1,
+      ...(unmetConditions == null ? {} : { unmetConditions }),
+    },
+  }
+  return transitionResult(out, componentId)
+}
+
+export function recordComponentDeliveryNudge(manifest, componentId, payload) {
+  assertExactObject(payload, ['generation', 'headSha', 'nudge'], `record-component-delivery-nudge ${componentId}`)
+  if (!Number.isSafeInteger(payload.generation) || payload.generation < 1) throw new Error(`record-component-delivery-nudge ${componentId}.generation must be a positive integer`)
+  assertSha(payload.headSha, `record-component-delivery-nudge ${componentId}.headSha`)
+  assertExactObject(payload.nudge, ['at', 'command', 'ref'], `record-component-delivery-nudge ${componentId}.nudge`)
+  const out = clone(manifest)
+  const { component, delivery } = componentDeliveryContext(out, componentId, payload.generation, payload.headSha)
+  const flow = deliveryFlow(out)
+  if (!flow?.supportsNudge) throw new Error(`component delivery ${componentId}: the ${flow?.key ?? 'unresolved'} flow has no queue re-evaluation nudge`)
+  if (!isObject(delivery.watch)) throw new Error(`component delivery ${componentId}: record a queue observation before a nudge`)
+  const nudges = Array.isArray(delivery.watch.nudges) ? [...delivery.watch.nudges] : []
+  if (nudges.length >= DELIVERY_MAX_NUDGES) throw new Error(`component delivery ${componentId}: already spent its ${DELIVERY_MAX_NUDGES} nudge(s)`)
+  const at = nonEmpty(payload.nudge.at) ? payload.nudge.at : new Date().toISOString()
+  nudges.push({ at, command: nonEmpty(payload.nudge.command) ? payload.nudge.command : flow.ops.nudge, ...(nonEmpty(payload.nudge.ref) ? { ref: payload.nudge.ref } : {}) })
+  component.delivery = { ...delivery, watch: { ...delivery.watch, nudges } }
+  return transitionResult(out, componentId)
+}
+
+function validatedQueueExecution(componentId, delivery, authorization, value) {
+  if (value === undefined) return null
+  assertExactObject(value, ['artifact', 'evidence'], `component delivery ${componentId}.queueExecution`)
+  if (!nonEmpty(value.artifact)) throw new Error(`component delivery ${componentId}.queueExecution.artifact is required`)
+  const plan = authorization.ci?.requiredCheckPlan
+  const validation = validateQueueExecutionArtifact(plan, value.evidence, {
+    expectedRepository: plan?.repository,
+    expectedPr: delivery.pr,
+    expectedPrHeadSha: delivery.authorizedHeadSha,
+    label: `component delivery ${componentId}.queueExecution.evidence`,
+  })
+  if (!validation.ok) throw new Error(validation.errors[0])
+  return clone(value)
+}
+
+export function recordComponentDeliveryOutcome(manifest, componentId, payload) {
+  assertExactObject(payload, ['generation', 'headSha', 'outcome', 'at', 'mergedSha', 'mergedAt', 'blockedOn', 'queueExecution'], `record-component-delivery-outcome ${componentId}`)
+  if (!Number.isSafeInteger(payload.generation) || payload.generation < 1) throw new Error(`record-component-delivery-outcome ${componentId}.generation must be a positive integer`)
+  assertSha(payload.headSha, `record-component-delivery-outcome ${componentId}.headSha`)
+  if (!['merged', 'handed-back'].includes(payload.outcome)) throw new Error(`record-component-delivery-outcome ${componentId}.outcome must be merged|handed-back`)
+  const out = clone(manifest)
+  const { component, authorization, delivery, byId } = componentDeliveryContext(out, componentId, payload.generation, payload.headSha)
+  if (delivery.outcome != null) throw new Error(`component delivery ${componentId} already reached terminal outcome ${delivery.outcome}`)
+  let queueExecution = null
+  if (payload.outcome === 'merged') {
+    assertSha(payload.mergedSha, `record-component-delivery-outcome ${componentId}.mergedSha`)
+    const requiredAction = delivery.mode === 'queue' ? 'enqueue' : 'merge'
+    if (!delivery.attempts.some((attempt) => attempt.generation === payload.generation && attempt.action === requiredAction)) {
+      throw new Error(`component delivery ${componentId}: merged outcome requires a recorded ${requiredAction} attempt in the authorized generation`)
+    }
+    const queueProofRequired = checksForPhase(authorization.ci?.requiredCheckPlan, 'queue-head').length > 0
+    if (delivery.mode === 'direct' && payload.queueExecution !== undefined) throw new Error(`component delivery ${componentId}: direct delivery cannot carry queue-execution evidence`)
+    if (delivery.mode === 'queue' && queueProofRequired && payload.queueExecution === undefined) throw new Error(`component delivery ${componentId}: successful queue delivery requires validated queue-execution evidence`)
+    queueExecution = validatedQueueExecution(componentId, delivery, authorization, payload.queueExecution)
+  } else {
+    if (!nonEmpty(payload.blockedOn)) throw new Error(`record-component-delivery-outcome ${componentId}.blockedOn is required for handed-back`)
+    if (payload.queueExecution !== undefined) throw new Error(`component delivery ${componentId}: handed-back cannot claim queue-execution success`)
+  }
+  component.delivery = {
+    ...delivery,
+    queueExecution,
+    outcome: payload.outcome,
+    outcomeAt: nonEmpty(payload.at) ? payload.at : new Date().toISOString(),
+    mergedSha: payload.outcome === 'merged' ? payload.mergedSha : null,
+    mergedAt: payload.outcome === 'merged' && nonEmpty(payload.mergedAt) ? payload.mergedAt : null,
+    blockedOn: payload.outcome === 'handed-back' ? payload.blockedOn : null,
+  }
+  for (const id of component.units) {
+    const unit = byId.get(id)
+    unit.disposition = payload.outcome === 'merged' ? 'delivered' : 'handed-back'
+    unit.deliveryRef = { componentId, generation: payload.generation }
+  }
+  return transitionResult(out, componentId)
+}
+
+export function recordComponentCandidate(manifest, componentId, payload, { at = new Date().toISOString() } = {}) {
+  // targetBaseSha optional (#944 / epic-867): the fetched origin/<targetBranch> tip at
+  // this assemble/re-ALIVE. Stored as components[].baseShaAtAssemble so mergeable can
+  // refuse when the trunk moved without a re-verify.
+  assertExactObject(payload, ['roundClass', 'branch', 'headSha', 'includedUnits', 'integrated', 'integrationFix', 'targetBaseSha'], `record-component-candidate ${componentId}`)
+  if (!['unit-discovery', 'integration-fix'].includes(payload.roundClass)) throw new Error(`record-component-candidate ${componentId}: roundClass must be unit-discovery|integration-fix`)
+  if (!nonEmpty(payload.branch)) throw new Error(`record-component-candidate ${componentId}: branch is required`)
+  assertSha(payload.headSha, `record-component-candidate ${componentId}.headSha`)
+  if (payload.targetBaseSha !== undefined) assertSha(payload.targetBaseSha, `record-component-candidate ${componentId}.targetBaseSha`)
+
+  const out = clone(manifest)
+  const { component, byId } = componentAndUnits(out, componentId)
+  assertIncludedUnits(component, payload.includedUnits)
+  const candidate = candidateBase(component.candidate)
+  if (candidate.state !== 'assembling') throw new Error(`component candidate ${componentId} is ${candidate.state}; reopen it before moving the candidate head`)
+  const prior = candidate.updates.at(-1)
+  if (prior?.headSha === payload.headSha) throw new Error(`component candidate ${componentId}: candidate head did not move`)
+  if (prior?.branch && prior.branch !== payload.branch) throw new Error(`component candidate ${componentId}: integration branch cannot move from ${prior.branch} to ${payload.branch}`)
+  if (prior) {
+    const current = new Set(payload.includedUnits)
+    if (prior.includedUnits.some((id) => !current.has(id))) throw new Error(`component candidate ${componentId}: included units cannot shrink; unit ownership/evidence must be preserved`)
+  }
+
+  const unitEvidence = payload.includedUnits.map((id) => preliminaryEvidence(byId.get(id), componentId))
+  let fix = null
+  if (payload.roundClass === 'integration-fix') {
+    fix = integrationFix(payload.integrationFix, componentId)
+    if (!prior || !same(prior.includedUnits, payload.includedUnits) || !same(prior.unitEvidence, unitEvidence)) {
+      throw new Error(`component candidate ${componentId}: integration-fix must preserve included units and unit heads byte-for-byte; record changed unit evidence as unit-discovery`)
+    }
+  } else {
+    if (payload.integrationFix !== undefined) throw new Error(`component candidate ${componentId}: unit-discovery cannot carry integrationFix`)
+    if (prior && same(prior.unitEvidence, unitEvidence)) throw new Error(`component candidate ${componentId}: unit-discovery must add or update unit candidate evidence`)
+  }
+
+  candidate.updates.push({
+    roundClass: payload.roundClass,
+    generation: candidate.generation,
+    branch: payload.branch,
+    headSha: payload.headSha,
+    includedUnits: clone(payload.includedUnits),
+    unitEvidence,
+    integrated: integratedResult(payload.integrated, componentId),
+    ...(fix ? { integrationFix: fix } : {}),
+    at,
+  })
+  component.candidate = candidate
+  if (payload.targetBaseSha !== undefined) {
+    component.baseShaAtAssemble = payload.targetBaseSha
+    // A re-ALIVE against a new trunk tip invalidates any prior enqueue-base attestation.
+    delete component.baseShaAtEnqueue
+  }
+  return transitionResult(out, componentId)
+}
+
+// #944 / epic-867: record the fetched target tip immediately before delivery. Direct
+// delivery owns target integration, so its enqueue/merge attestation must still equal the
+// assembled base. A queue provider owns speculative target integration: it may observe a
+// newer descendant tip, while the live delivery gate proves baseShaAtAssemble remains in
+// that target history and tests the immutable PR head on the synthetic queue branch.
+export function recordComponentTargetBase(manifest, componentId, payload, { at = new Date().toISOString() } = {}) {
+  assertExactObject(payload, ['phase', 'baseSha'], `record-component-target-base ${componentId}`)
+  if (!['assemble', 'enqueue'].includes(payload.phase)) {
+    throw new Error(`record-component-target-base ${componentId}: phase must be assemble|enqueue`)
+  }
+  assertSha(payload.baseSha, `record-component-target-base ${componentId}.baseSha`)
+  const out = clone(manifest)
+  const { component } = componentAndUnits(out, componentId)
+  if (payload.phase === 'assemble') {
+    component.baseShaAtAssemble = payload.baseSha
+    delete component.baseShaAtEnqueue
+  } else {
+    if (!nonEmpty(component.baseShaAtAssemble)) {
+      throw new Error(`record-component-target-base ${componentId}: baseShaAtAssemble is required before enqueue attestation — re-assemble/re-ALIVE with targetBaseSha first`)
+    }
+    const queueOwned = out.deliveryMode === 'queue'
+    // Direct delivery must integrate the exact live tip before merge. Queue delivery only
+    // records the observed tip here; ancestry is deliberately not trusted from manifest
+    // data and is proved live by combine-and-verify before enqueue.
+    if (!queueOwned && component.baseShaAtAssemble !== payload.baseSha) {
+      throw new Error(`record-component-target-base ${componentId}: target tip ${payload.baseSha} advanced past baseShaAtAssemble ${component.baseShaAtAssemble} — target-drift path: back-merge/reassemble, re-verify, re-ALIVE, then re-attest`)
+    }
+    component.baseShaAtEnqueue = payload.baseSha
+    component.targetIntegrationOwner = queueOwned ? 'queue' : 'source'
+  }
+  component.targetBaseRecordedAt = at
+  return out
+}
+
+// Pure policy over live ancestry facts. Direct delivery requires exact-tip integration.
+// Queue delivery permits forward movement only when the recorded assembly base is still an
+// ancestor of the live target; the queue then proves compatibility on its synthetic head.
+// Absent assemble base remains a legacy no-signal shape.
+export function targetBaseDrift({ baseShaAtAssemble, baseShaAtEnqueue, liveTargetSha, deliveryMode = 'direct', assembleBaseIsAncestor = false } = {}) {
+  if (!nonEmpty(baseShaAtAssemble)) {
+    return { drifted: false, reasons: [] }
+  }
+  if (!nonEmpty(liveTargetSha)) {
+    return { drifted: true, reasons: ['live target SHA is unavailable — target integration ancestry cannot be proved'] }
+  }
+  if (baseShaAtAssemble === liveTargetSha) {
+    // Tip still at assemble base — enqueue attestation optional when tip is unchanged.
+    return { drifted: false, reasons: [] }
+  }
+  if (deliveryMode === 'queue' && assembleBaseIsAncestor) {
+    return { drifted: false, reasons: [] }
+  }
+  // Direct delivery may re-attest only after integrating and re-verifying the new tip.
+  if (deliveryMode !== 'queue' && nonEmpty(baseShaAtEnqueue) && baseShaAtEnqueue === liveTargetSha) {
+    return { drifted: false, reasons: [] }
+  }
+  const reason = deliveryMode === 'queue'
+    ? `recorded assembly base ${baseShaAtAssemble} is not an ancestor of live target ${liveTargetSha} — queue-owned speculative integration accepts forward target movement, never rewritten or divergent target history`
+    : `target trunk moved since assemble (baseShaAtAssemble ${baseShaAtAssemble} → live ${liveTargetSha}) without re-ALIVE / baseShaAtEnqueue matching the new tip — back-merge, re-verify CI/smoke, delta integrated review, then record-component-target-base enqueue (epic-867/#944)`
+  return { drifted: true, reasons: [reason] }
+}
+
+export function freezeComponentCandidate(manifest, componentId, payload, { at = new Date().toISOString() } = {}) {
+  assertExactObject(payload, ['headSha'], `freeze-component-candidate ${componentId}`)
+  assertSha(payload.headSha, `freeze-component-candidate ${componentId}.headSha`)
+  const out = clone(manifest)
+  const { component, byId } = componentAndUnits(out, componentId)
+  const candidate = candidateBase(component.candidate)
+  if (candidate.state !== 'assembling') throw new Error(`component candidate ${componentId} must be assembling before freeze (got ${candidate.state})`)
+  const latest = candidate.updates.at(-1)
+  const complete = latest && same(latest.includedUnits, component.units)
+  const clean = latest?.integrated?.assembly === 'clean' && latest?.integrated?.tests === 'green'
+    && latest.integrated.conflicts.length === 0 && latest.integrated.failedTests.length === 0
+  const currentUnitEvidence = complete ? component.units.map((id) => preliminaryEvidence(byId.get(id), componentId)) : []
+  const current = complete && same(latest.unitEvidence, currentUnitEvidence)
+  if (!latest || latest.headSha !== payload.headSha || !complete || !clean || !current) {
+    throw new Error(`component candidate ${componentId}: freeze requires the latest exact head with the complete component, clean assembly, and green integrated tests`)
+  }
+  candidate.state = 'frozen'
+  candidate.frozen = {
+    generation: candidate.generation,
+    headSha: latest.headSha,
+    branch: latest.branch,
+    includedUnits: clone(latest.includedUnits),
+    unitEvidence: clone(latest.unitEvidence),
+    authorizationBoundary: { kind: 'integration', value: latest.headSha },
+    at,
+  }
+  component.candidate = candidate
+  return transitionResult(out, componentId)
+}
+
+function terminalEvidence(payload, component, candidate, unitById = component.__unitById) {
+  assertExactObject(payload, ['headSha', 'ci', 'review', 'smoke'], `authorize-component-candidate ${component.id}`)
+  const head = candidate.frozen?.headSha
+  assertSha(payload.headSha, `authorize-component-candidate ${component.id}.headSha`)
+  if (candidate.state !== 'frozen' || payload.headSha !== head) throw new Error(`component candidate ${component.id}: terminal authorization must target the exact frozen HEAD`)
+
+  assertExactObject(payload.ci, ['headSha', 'status', 'artifact', 'pr', 'jobs', 'requiredCheckPlan', 'publishOnlyEvidence'], `component candidate ${component.id}.ci`)
+  assertExactObject(payload.review, ['headSha', 'verdict', 'reviewSubject', 'highRisk', 'authorizationBoundary', 'checklist', 'scanFindings', 'artifact'], `component candidate ${component.id}.review`)
+  assertExactObject(payload.smoke, ['headSha', 'status', 'artifact', 'reason'], `component candidate ${component.id}.smoke`)
+  for (const [name, evidence] of [['CI', payload.ci], ['review', payload.review], ['smoke', payload.smoke]]) {
+    if (evidence.headSha !== head) throw new Error(`component candidate ${component.id}: terminal ${name} headSha must equal the exact frozen HEAD ${head}`)
+  }
+  if (payload.ci.status !== 'green') throw new Error(`component candidate ${component.id}: exact-head integrated CI must be green`)
+  if (!Number.isInteger(payload.ci.pr) || payload.ci.pr < 1) throw new Error(`component candidate ${component.id}: exact-head integrated CI requires a positive PR number`)
+  const plan = validateRequiredCheckPlan(payload.ci.requiredCheckPlan, { expectedHeadSha: head, requireEvidence: true, label: `component candidate ${component.id}.ci.requiredCheckPlan` })
+  if (!plan.ok) throw new Error(plan.errors[0])
+  const publishOnly = validatePublishOnlyEvidence(payload.ci.requiredCheckPlan, payload.ci.publishOnlyEvidence, { expectedHeadSha: head, expectedRepository: payload.ci.requiredCheckPlan.repository, expectedPr: payload.ci.pr, label: `component candidate ${component.id}.ci.publishOnlyEvidence` })
+  if (!publishOnly.ok) throw new Error(publishOnly.errors[0])
+  const execution = validateRequiredCheckExecution(payload.ci.requiredCheckPlan, payload.ci.jobs, { expectedHeadSha: head })
+  if (!execution.ok) throw new Error(`component candidate ${component.id}: required-check-plan execution invalid: ${execution.errors[0]}`)
+  for (const [name, evidence] of [['CI', payload.ci], ['review', payload.review], ['smoke', payload.smoke]]) {
+    if (!nonEmpty(evidence.artifact)) throw new Error(`component candidate ${component.id}: terminal ${name} requires an artifact locator`)
+  }
+  const reviewBoundary = boundary(payload.review.authorizationBoundary, `component candidate ${component.id}.review.authorizationBoundary`)
+  if (payload.review.verdict !== 'PASS' || payload.review.reviewSubject !== 'code' || payload.review.checklist !== 'PASS' || payload.review.scanFindings !== 0) {
+    throw new Error(`component candidate ${component.id}: terminal integrated review must PASS code on the exact head with checklist PASS and zero scan findings`)
+  }
+  if (reviewBoundary.kind !== 'integration' || reviewBoundary.value !== head) throw new Error(`component candidate ${component.id}: terminal review authorization boundary must be the component HEAD`)
+  const highRisk = candidate.frozen.unitEvidence.some((evidence) => {
+    const unit = unitById?.get(evidence.unitId)
+    return unit?.highRisk === true
+  })
+  if (highRisk && payload.review.highRisk !== true) throw new Error(`component candidate ${component.id}: high-risk integrated review is mandatory`)
+  const smokeAlive = payload.smoke.status === 'ALIVE'
+  const smokeNA = payload.smoke.status === 'not-applicable' && nonEmpty(payload.smoke.reason)
+  if (!smokeAlive && !smokeNA) throw new Error(`component candidate ${component.id}: smoke must be ALIVE, or not-applicable with a reason`)
+  return { ci: clone(payload.ci), review: { ...clone(payload.review), authorizationBoundary: reviewBoundary }, smoke: clone(payload.smoke) }
+}
+
+function legacyTerminalEvidence(payload, component, candidate, unitById = component.__unitById) {
+  assertExactObject(payload, ['headSha', 'ci', 'review', 'smoke'], `legacy component authorization ${component.id}`)
+  const head = candidate.frozen?.headSha
+  assertSha(payload.headSha, `legacy component authorization ${component.id}.headSha`)
+  if (candidate.state !== 'frozen' || payload.headSha !== head) throw new Error(`legacy component authorization ${component.id} must target the exact frozen HEAD`)
+
+  assertExactObject(payload.ci, ['headSha', 'status', 'artifact', 'jobs'], `legacy component authorization ${component.id}.ci`)
+  assertExactObject(payload.review, ['headSha', 'verdict', 'reviewSubject', 'highRisk', 'authorizationBoundary', 'checklist', 'scanFindings', 'artifact'], `legacy component authorization ${component.id}.review`)
+  assertExactObject(payload.smoke, ['headSha', 'status', 'artifact', 'reason'], `legacy component authorization ${component.id}.smoke`)
+  for (const [name, evidence] of [['CI', payload.ci], ['review', payload.review], ['smoke', payload.smoke]]) {
+    if (evidence.headSha !== head) throw new Error(`legacy component authorization ${component.id}: ${name} headSha must equal ${head}`)
+    if (!nonEmpty(evidence.artifact)) throw new Error(`legacy component authorization ${component.id}: ${name} requires an artifact locator`)
+  }
+  if (payload.ci.status !== 'green') throw new Error(`legacy component authorization ${component.id}: exact-head CI must be green`)
+  const reviewBoundary = boundary(payload.review.authorizationBoundary, `legacy component authorization ${component.id}.review.authorizationBoundary`)
+  if (payload.review.verdict !== 'PASS' || payload.review.reviewSubject !== 'code' || payload.review.checklist !== 'PASS' || payload.review.scanFindings !== 0) {
+    throw new Error(`legacy component authorization ${component.id}: integrated review must PASS code with checklist PASS and zero scan findings`)
+  }
+  if (reviewBoundary.kind !== 'integration' || reviewBoundary.value !== head) throw new Error(`legacy component authorization ${component.id}: review boundary must bind the component HEAD`)
+  const highRisk = candidate.frozen.unitEvidence.some((evidence) => unitById?.get(evidence.unitId)?.highRisk === true)
+  if (highRisk && payload.review.highRisk !== true) throw new Error(`legacy component authorization ${component.id}: high-risk integrated review is mandatory`)
+  const smokeAlive = payload.smoke.status === 'ALIVE'
+  const smokeNA = payload.smoke.status === 'not-applicable' && nonEmpty(payload.smoke.reason)
+  if (!smokeAlive && !smokeNA) throw new Error(`legacy component authorization ${component.id}: smoke must be ALIVE, or not-applicable with a reason`)
+  return { ci: clone(payload.ci), review: { ...clone(payload.review), authorizationBoundary: reviewBoundary }, smoke: clone(payload.smoke) }
+}
+
+export function authorizeComponentCandidate(manifest, componentId, payload, { at = new Date().toISOString() } = {}) {
+  const out = clone(manifest)
+  const { component, byId } = componentAndUnits(out, componentId)
+  const candidate = candidateBase(component.candidate)
+  const evidence = terminalEvidence(payload, component, candidate, byId)
+  candidate.state = 'authorized'
+  const authorization = {
+    roundClass: 'terminal-authorization',
+    generation: candidate.generation,
+    headSha: payload.headSha,
+    authorizationBoundary: clone(evidence.review.authorizationBoundary),
+    ...evidence,
+    at,
+  }
+  candidate.authorizations.push(authorization)
+  component.candidate = candidate
+  component.authorizationBoundary = clone(evidence.review.authorizationBoundary)
+  component.delivery = initializedDelivery(out, component, candidate, authorization)
+  return transitionResult(out, componentId)
+}
+
+export function reopenComponentCandidate(manifest, componentId, payload, { at = new Date().toISOString() } = {}) {
+  assertExactObject(payload, ['reopenReason', 'authorizationBoundary'], `reopen-component-candidate ${componentId}`)
+  if (!REOPEN_REASONS.includes(payload.reopenReason)) throw new Error(`reopen-component-candidate ${componentId}: reopen reason must be one of ${REOPEN_REASONS.join('|')}`)
+  const nextBoundary = boundary(payload.authorizationBoundary, `reopen-component-candidate ${componentId}.authorizationBoundary`)
+  if (nextBoundary.kind !== REOPEN_BOUNDARY_KIND[payload.reopenReason]) throw new Error(`reopen-component-candidate ${componentId}: reopen reason ${payload.reopenReason} requires authorizationBoundary.kind ${REOPEN_BOUNDARY_KIND[payload.reopenReason]}`)
+
+  const out = clone(manifest)
+  const { component } = componentAndUnits(out, componentId)
+  const candidate = candidateBase(component.candidate)
+  if (!['frozen', 'authorized'].includes(candidate.state)) throw new Error(`component candidate ${componentId}: only a frozen or authorized candidate can reopen`)
+  if (component.delivery?.outcome === 'merged' || component.delivery?.outcome === 'handed-back') {
+    throw new Error(`component candidate ${componentId}: terminal component delivery cannot reopen`)
+  }
+  const priorBoundary = candidate.state === 'authorized' ? component.authorizationBoundary : candidate.frozen?.authorizationBoundary
+  if (!isObject(priorBoundary)) throw new Error(`component candidate ${componentId}: prior authorization boundary is missing`)
+  if (same(priorBoundary, nextBoundary)) throw new Error(`component candidate ${componentId}: authorizationBoundary must change when the candidate reopens`)
+  candidate.reopens.push({
+    fromGeneration: candidate.generation,
+    fromHeadSha: candidate.frozen?.headSha ?? null,
+    reopenReason: payload.reopenReason,
+    priorAuthorizationBoundary: clone(priorBoundary),
+    authorizationBoundary: nextBoundary,
+    at,
+  })
+  candidate.generation += 1
+  candidate.state = 'assembling'
+  candidate.frozen = null
+  component.candidate = candidate
+  component.authorizationBoundary = nextBoundary
+  return transitionResult(out, componentId)
+}
+
+export function componentRoundProfile(component) {
+  const candidate = isObject(component?.candidate) ? component.candidate : {}
+  const updates = Array.isArray(candidate.updates) ? candidate.updates : []
+  const authorizations = Array.isArray(candidate.authorizations) ? candidate.authorizations : []
+  const unitDiscovery = updates.filter((entry) => entry?.roundClass === 'unit-discovery').length
+  const integrationFix = updates.filter((entry) => entry?.roundClass === 'integration-fix').length
+  const terminalAuthorization = authorizations.filter((entry) => entry?.roundClass === 'terminal-authorization').length
+  return { unitDiscovery, integrationFix, terminalAuthorization, total: unitDiscovery + integrationFix + terminalAuthorization }
+}
+
+function captureError(errors, fn) {
+  try { fn() } catch (error) { errors.push(error.message) }
+}
+
+function validateStoredUnitEvidence(evidence, label, errors) {
+  captureError(errors, () => assertExactObject(evidence, ['unitId', 'headSha', 'pr', 'preliminaryReview', 'reviewRoundCount'], label))
+  if (!isObject(evidence)) return
+  if (!nonEmpty(evidence.unitId)) errors.push(`${label}.unitId must be a non-empty string`)
+  captureError(errors, () => assertSha(evidence.headSha, `${label}.headSha`))
+  if (evidence.pr !== null && !nonEmpty(evidence.pr)) errors.push(`${label}.pr must be null or a non-empty string`)
+  if (!Number.isInteger(evidence.reviewRoundCount) || evidence.reviewRoundCount < 1) errors.push(`${label}.reviewRoundCount must be a positive integer`)
+  const review = evidence.preliminaryReview
+  const legacy = review?.legacy === true
+  const allowed = legacy
+    ? ['round', 'verdict', 'headSha', 'reviewSubject', 'authorizationBoundary', 'legacy', 'source']
+    : ['round', 'verdict', 'headSha', 'reviewSubject', 'authorizationBoundary']
+  captureError(errors, () => assertExactObject(review, allowed, `${label}.preliminaryReview`))
+  if (!isObject(review)) return
+  if (!Number.isInteger(review.round) || review.round < 1) errors.push(`${label}.preliminaryReview.round must be a positive integer`)
+  if (review.verdict !== 'PASS') errors.push(`${label}.preliminaryReview.verdict must be PASS`)
+  if (review.headSha !== evidence.headSha) errors.push(`${label}.preliminaryReview must target the evidence head`)
+  if (legacy) {
+    if (review.reviewSubject !== 'unknown') errors.push(`${label}.preliminaryReview legacy reviewSubject must be unknown`)
+    if (review.authorizationBoundary !== 'unknown') errors.push(`${label}.preliminaryReview legacy authorizationBoundary must be unknown`)
+    if (!['rounds', 'reviewHistory'].includes(review.source)) errors.push(`${label}.preliminaryReview legacy source must be rounds|reviewHistory`)
+  } else {
+    if (!['code', 'evidence'].includes(review.reviewSubject)) errors.push(`${label}.preliminaryReview.reviewSubject must be code|evidence`)
+    captureError(errors, () => boundary(review.authorizationBoundary, `${label}.preliminaryReview.authorizationBoundary`))
+  }
+}
+
+function validateStoredAuthorization(manifest, component, candidate, authorization, label, errors, { allowLegacyCiEvidence = false } = {}) {
+  captureError(errors, () => assertExactObject(authorization, ['roundClass', 'generation', 'headSha', 'authorizationBoundary', 'ci', 'review', 'smoke', 'at'], label))
+  if (!isObject(authorization)) return
+  if (authorization.roundClass !== 'terminal-authorization') errors.push(`${label}.roundClass must be terminal-authorization`)
+  if (!Number.isInteger(authorization.generation) || authorization.generation < 1 || authorization.generation > candidate.generation) errors.push(`${label}.generation is invalid`)
+  const updates = Array.isArray(candidate.updates) ? candidate.updates : []
+  const update = updates.filter((entry) => entry?.generation === authorization.generation).at(-1)
+  if (!update || update.headSha !== authorization.headSha) errors.push(`${label} must authorize the latest update in its generation`)
+  const validationCandidate = {
+    ...candidate,
+    state: 'frozen',
+    frozen: { headSha: authorization.headSha, unitEvidence: clone(update?.unitEvidence ?? []) },
+  }
+  const unitById = new Map((Array.isArray(manifest?.units) ? manifest.units : []).map((unit) => [unit?.id, unit]))
+  const legacyCi = allowLegacyCiEvidence
+    && isObject(authorization.ci)
+    && Object.keys(authorization.ci).every((key) => ['headSha', 'status', 'artifact', 'jobs'].includes(key))
+    && !Object.hasOwn(authorization.ci, 'requiredCheckPlan')
+  const validateEvidence = legacyCi ? legacyTerminalEvidence : terminalEvidence
+  captureError(errors, () => validateEvidence({
+    headSha: authorization.headSha,
+    ci: authorization.ci,
+    review: authorization.review,
+    smoke: authorization.smoke,
+  }, component, validationCandidate, unitById))
+  if (!same(authorization.authorizationBoundary, authorization.review?.authorizationBoundary)) errors.push(`${label}.authorizationBoundary must equal the terminal review boundary`)
+}
+
+function validateStoredComponentDelivery(manifest, component, candidate, index, errors) {
+  const delivery = component?.delivery
+  const label = `components[${index}] (${component?.id ?? 'unknown'}).delivery`
+  const unitById = new Map((Array.isArray(manifest?.units) ? manifest.units : []).map((unit) => [unit?.id, unit]))
+  const memberIds = Array.isArray(component?.units) ? component.units : []
+
+  // Compatibility is absence-based, not schemaVersion-based: #1009 can migrate a valid
+  // pre-feature manifest to v2 without inventing delivery facts. Such records retain the
+  // legacy unit reader until the component is terminally re-authorized, which creates this
+  // canonical record. Once present, member unit delivery duplication is refused below.
+  if (delivery === undefined || delivery === null) return
+  captureError(errors, () => assertExactObject(delivery, ['pr', 'generation', 'authorizedHeadSha', 'mode', 'provider', 'attempts', 'observations', 'watch', 'queueExecution', 'outcome', 'outcomeAt', 'mergedSha', 'mergedAt', 'blockedOn', 'reconciliations'], label))
+  if (!isObject(delivery)) return
+  if (!Number.isSafeInteger(delivery.pr) || delivery.pr < 1) errors.push(`${label}.pr must be a positive integer`)
+  const publishedPr = positivePr(component.pr)
+  if (publishedPr != null && publishedPr !== delivery.pr) errors.push(`${label}.pr must equal the published component PR ${publishedPr}`)
+  if (!Number.isSafeInteger(delivery.generation) || delivery.generation < 1) errors.push(`${label}.generation must be a positive integer`)
+  captureError(errors, () => assertSha(delivery.authorizedHeadSha, `${label}.authorizedHeadSha`))
+  if (!['direct', 'queue'].includes(delivery.mode)) errors.push(`${label}.mode must be direct|queue`)
+  if (delivery.mode === 'direct' && delivery.provider !== null) errors.push(`${label}.provider must be null for direct delivery`)
+  if (delivery.mode === 'queue' && !['mergify', 'github'].includes(delivery.provider)) errors.push(`${label}.provider must be mergify|github for queue delivery`)
+  if (delivery.mode !== deliveryMode(manifest)) errors.push(`${label}.mode must equal the run deliveryMode`)
+  if (delivery.provider !== (delivery.mode === 'queue' ? deliveryProvider(manifest) : null)) errors.push(`${label}.provider must equal the run queueProvider`)
+
+  const authorization = Array.isArray(candidate?.authorizations)
+    ? candidate.authorizations.findLast((entry) => entry?.generation === delivery.generation)
+    : null
+  if (!authorization || authorization.headSha !== delivery.authorizedHeadSha) errors.push(`${label} must bind an existing terminal authorization generation and head`)
+  if (candidate?.state === 'authorized' && (candidate.generation !== delivery.generation || candidate.frozen?.headSha !== delivery.authorizedHeadSha)) {
+    errors.push(`${label} must bind the currently authorized frozen component generation`)
+  }
+
+  if (!Array.isArray(delivery.attempts)) errors.push(`${label}.attempts must be an array`)
+  else {
+    const attemptKeys = new Set()
+    for (const [attemptIndex, attempt] of delivery.attempts.entries()) {
+      const at = `${label}.attempts[${attemptIndex}]`
+      if (!isObject(attempt)) { errors.push(`${at} must be an object`); continue }
+      if (!Number.isSafeInteger(attempt.generation) || attempt.generation < 1) errors.push(`${at}.generation must be a positive integer`)
+      const { generation, ...storedAttempt } = attempt
+      errors.push(...validateDeliveryAttempt(storedAttempt, delivery.mode, at, delivery.provider))
+      const key = `${generation}:${attempt.action}`
+      if (attemptKeys.has(key)) errors.push(`${at} duplicates the ${attempt.action} attempt for generation ${generation}`)
+      attemptKeys.add(key)
+      const attemptAuthorization = Array.isArray(candidate?.authorizations)
+        ? candidate.authorizations.find((entry) => entry?.generation === generation)
+        : null
+      if (!attemptAuthorization || attempt.headSha !== attemptAuthorization.headSha) errors.push(`${at}.headSha must equal its generation's authorized component HEAD`)
+      if (delivery.mode === 'queue' && positivePr(attempt.pr) !== delivery.pr) errors.push(`${at}.pr must equal component delivery PR ${delivery.pr}`)
+    }
+  }
+  if (!Array.isArray(delivery.observations)) errors.push(`${label}.observations must be an array`)
+  else for (const [observationIndex, observation] of delivery.observations.entries()) {
+    const at = `${label}.observations[${observationIndex}]`
+    captureError(errors, () => assertExactObject(observation, ['generation', 'headSha', 'at', 'queueState', 'position', 'unmetConditions', 'ack'], at))
+    if (!isObject(observation)) continue
+    const observationAuthorization = Array.isArray(candidate?.authorizations)
+      ? candidate.authorizations.find((entry) => entry?.generation === observation.generation)
+      : null
+    if (!observationAuthorization || observation.headSha !== observationAuthorization.headSha) errors.push(`${at}.headSha must equal its generation's authorized component HEAD`)
+    captureError(errors, () => deliveryObservation({ at: observation.at, queueState: observation.queueState, ...(observation.position !== undefined ? { position: observation.position } : {}), ...(observation.unmetConditions !== undefined ? { unmetConditions: observation.unmetConditions } : {}), ...(observation.ack !== undefined ? { ack: observation.ack } : {}) }, at))
+  }
+  if (delivery.mode === 'direct' && (delivery.observations?.length || delivery.watch != null)) errors.push(`${label}: direct delivery cannot carry queue observations or a watch`)
+  if (delivery.watch !== null && !isObject(delivery.watch)) errors.push(`${label}.watch must be null or an object`)
+  if (isObject(delivery.watch)) {
+    const unknownWatch = Object.keys(delivery.watch).filter((key) => !['firstObservedAt', 'lastObservedAt', 'lastChangeAt', 'queueState', 'position', 'polls', 'nudges', 'unmetConditions'].includes(key))
+    if (unknownWatch.length) errors.push(`${label}.watch has unknown property ${unknownWatch[0]}`)
+    for (const field of ['firstObservedAt', 'lastObservedAt', 'lastChangeAt', 'queueState']) if (!nonEmpty(delivery.watch[field])) errors.push(`${label}.watch.${field} is required`)
+    if (!Number.isSafeInteger(delivery.watch.polls) || delivery.watch.polls < 1) errors.push(`${label}.watch.polls must be a positive integer`)
+    if (delivery.watch.nudges !== undefined) {
+      if (!Array.isArray(delivery.watch.nudges) || delivery.watch.nudges.length > DELIVERY_MAX_NUDGES) errors.push(`${label}.watch.nudges must contain at most ${DELIVERY_MAX_NUDGES} entries`)
+      else for (const [nudgeIndex, nudge] of delivery.watch.nudges.entries()) {
+        const at = `${label}.watch.nudges[${nudgeIndex}]`
+        captureError(errors, () => assertExactObject(nudge, ['at', 'command', 'ref'], at))
+        if (!isObject(nudge) || !nonEmpty(nudge.at) || !nonEmpty(nudge.command)) errors.push(`${at} requires at and command`)
+      }
+    }
+  }
+  if (delivery.outcome !== null && !['merged', 'handed-back'].includes(delivery.outcome)) errors.push(`${label}.outcome must be null|merged|handed-back`)
+  if (delivery.outcome != null && !nonEmpty(delivery.outcomeAt)) errors.push(`${label}.outcomeAt is required for a terminal outcome`)
+  if (delivery.outcome === 'merged') {
+    captureError(errors, () => assertSha(delivery.mergedSha, `${label}.mergedSha`))
+    const requiredAction = delivery.mode === 'queue' ? 'enqueue' : 'merge'
+    if (!Array.isArray(delivery.attempts) || !delivery.attempts.some((attempt) => attempt?.generation === delivery.generation && attempt.action === requiredAction)) {
+      errors.push(`${label}: merged outcome requires a ${requiredAction} attempt in the authorized generation`)
+    }
+    const queueRequired = checksForPhase(authorization?.ci?.requiredCheckPlan, 'queue-head').length > 0
+    if (delivery.mode === 'direct' && delivery.queueExecution != null) errors.push(`${label}: direct delivery cannot carry queueExecution evidence`)
+    if (delivery.mode === 'queue' && queueRequired && !isObject(delivery.queueExecution)) errors.push(`${label}: merged queue delivery requires queueExecution evidence`)
+    if (delivery.mode === 'queue' && isObject(delivery.queueExecution)) captureError(errors, () => validatedQueueExecution(component.id, delivery, authorization, delivery.queueExecution))
+  }
+  if (delivery.outcome === 'handed-back') {
+    if (!nonEmpty(delivery.blockedOn)) errors.push(`${label}.blockedOn is required for handed-back`)
+    if (delivery.mergedSha != null || delivery.mergedAt != null || delivery.queueExecution != null) errors.push(`${label}: handed-back delivery cannot carry merge or queue-execution success evidence`)
+  }
+  if (delivery.outcome === null && (delivery.outcomeAt != null || delivery.mergedSha != null || delivery.mergedAt != null || delivery.blockedOn != null || delivery.queueExecution != null)) errors.push(`${label}: nonterminal delivery cannot carry terminal evidence`)
+
+  for (const id of memberIds) {
+    const unit = unitById.get(id)
+    if (!unit) continue
+    if (unit.delivery !== undefined) errors.push(`${label}: member ${id} must not duplicate canonical attempts or observations in units[].delivery`)
+    if (delivery.outcome != null) {
+      const expected = delivery.outcome === 'merged' ? 'delivered' : 'handed-back'
+      if (unit.disposition !== expected) errors.push(`${label}: terminal outcome must atomically derive disposition ${expected} for member ${id}`)
+      if (!same(unit.deliveryRef, { componentId: component.id, generation: delivery.generation })) errors.push(`${label}: member ${id}.deliveryRef must bind this component generation`)
+    }
+  }
+}
+
+function candidateErrors(manifest, component, index, options = {}) {
+  const c = component?.candidate
+  if (c === undefined || c === null) return []
+  const at = `components[${index}] (${component?.id ?? 'unknown'}).candidate`
+  const errors = []
+  if (!isObject(c)) return [`${at} must be an object`]
+  const unknown = Object.keys(c).filter((key) => !['state', 'generation', 'updates', 'frozen', 'authorizations', 'reopens'].includes(key))
+  if (unknown.length) errors.push(`${at} has unknown property ${unknown[0]}`)
+  if (!COMPONENT_CANDIDATE_STATES.includes(c.state)) errors.push(`${at}.state must be one of ${COMPONENT_CANDIDATE_STATES.join('|')}`)
+  if (!Number.isInteger(c.generation) || c.generation < 1) errors.push(`${at}.generation must be a positive integer`)
+  for (const key of ['updates', 'authorizations', 'reopens']) if (!Array.isArray(c[key])) errors.push(`${at}.${key} must be an array`)
+  const updates = Array.isArray(c.updates) ? c.updates : []
+  for (const [i, update] of updates.entries()) {
+    const label = `${at}.updates[${i}]`
+    captureError(errors, () => assertExactObject(update, ['roundClass', 'generation', 'branch', 'headSha', 'includedUnits', 'unitEvidence', 'integrated', 'integrationFix', 'at'], label))
+    if (!isObject(update)) continue
+    if (!['unit-discovery', 'integration-fix'].includes(update.roundClass)) errors.push(`${label} has invalid roundClass`)
+    if (!Number.isInteger(update.generation) || update.generation < 1 || update.generation > c.generation) errors.push(`${label}.generation is invalid`)
+    if (i > 0 && update.generation < updates[i - 1]?.generation) errors.push(`${label}.generation cannot move backwards`)
+    if (!nonEmpty(update.branch)) errors.push(`${label}.branch is required`)
+    captureError(errors, () => assertSha(update.headSha, `${label}.headSha`))
+    captureError(errors, () => assertIncludedUnits(component, update.includedUnits))
+    if (!Array.isArray(update.unitEvidence) || update.unitEvidence.length !== update.includedUnits?.length) {
+      errors.push(`${label}.unitEvidence must match includedUnits`)
+    } else {
+      update.unitEvidence.forEach((evidence, evidenceIndex) => validateStoredUnitEvidence(evidence, `${label}.unitEvidence[${evidenceIndex}]`, errors))
+      if (!same(update.unitEvidence.map((evidence) => evidence?.unitId), update.includedUnits)) errors.push(`${label}.unitEvidence order must match includedUnits`)
+    }
+    captureError(errors, () => integratedResult(update.integrated, component.id))
+    if (update.roundClass === 'integration-fix') captureError(errors, () => integrationFix(update.integrationFix, component.id))
+    else if (update.integrationFix !== undefined) errors.push(`${label}: unit-discovery cannot carry integrationFix`)
+    const prior = updates[i - 1]
+    if (prior) {
+      if (prior.branch !== update.branch) errors.push(`${label}: integration branch cannot move`)
+      if (prior.headSha === update.headSha) errors.push(`${label}: candidate head must move`)
+      if (prior.includedUnits?.some((id) => !update.includedUnits?.includes(id))) errors.push(`${label}: included units cannot shrink`)
+      if (update.roundClass === 'integration-fix' && (!same(prior.includedUnits, update.includedUnits) || !same(prior.unitEvidence, update.unitEvidence))) errors.push(`${label}: integration-fix must preserve unit evidence byte-for-byte`)
+      if (update.roundClass === 'unit-discovery' && same(prior.unitEvidence, update.unitEvidence)) errors.push(`${label}: unit-discovery must change unit evidence`)
+    }
+  }
+  const reopens = Array.isArray(c.reopens) ? c.reopens : []
+  if (reopens.length !== c.generation - 1) errors.push(`${at}.reopens must contain one typed transition for every completed generation`)
+  for (const [i, reopen] of reopens.entries()) {
+    const label = `${at}.reopens[${i}]`
+    captureError(errors, () => assertExactObject(reopen, ['fromGeneration', 'fromHeadSha', 'reopenReason', 'priorAuthorizationBoundary', 'authorizationBoundary', 'at'], label))
+    if (!isObject(reopen)) continue
+    if (reopen.fromGeneration !== i + 1) errors.push(`${label}.fromGeneration must preserve generation order`)
+    const generationHead = updates.filter((entry) => entry?.generation === reopen.fromGeneration).at(-1)?.headSha
+    if (reopen.fromHeadSha !== generationHead) errors.push(`${label}.fromHeadSha must equal that generation's latest candidate head`)
+    if (!REOPEN_REASONS.includes(reopen.reopenReason)) errors.push(`${label}.reopenReason is invalid`)
+    const priorBoundary = (() => { try { return boundary(reopen.priorAuthorizationBoundary, `${label}.priorAuthorizationBoundary`) } catch (error) { errors.push(error.message); return null } })()
+    const nextBoundary = (() => { try { return boundary(reopen.authorizationBoundary, `${label}.authorizationBoundary`) } catch (error) { errors.push(error.message); return null } })()
+    if (nextBoundary && nextBoundary.kind !== REOPEN_BOUNDARY_KIND[reopen.reopenReason]) errors.push(`${label}.authorizationBoundary.kind does not match reopenReason`)
+    if (priorBoundary && (priorBoundary.kind !== 'integration' || priorBoundary.value !== reopen.fromHeadSha)) errors.push(`${label}.priorAuthorizationBoundary must bind the prior frozen component HEAD`)
+    if (priorBoundary && nextBoundary && same(priorBoundary, nextBoundary)) errors.push(`${label}.authorizationBoundary must change`)
+  }
+  const authorizations = Array.isArray(c.authorizations) ? c.authorizations : []
+  for (const [i, authorization] of authorizations.entries()) {
+    validateStoredAuthorization(manifest, component, c, authorization, `${at}.authorizations[${i}]`, errors, options)
+    if (i > 0 && authorization?.generation <= authorizations[i - 1]?.generation) errors.push(`${at}.authorizations[${i}].generation must increase`)
+  }
+  if (c.state === 'assembling' && c.frozen != null) errors.push(`${at}: assembling candidate cannot carry a current frozen boundary`)
+  if (['frozen', 'authorized'].includes(c.state)) {
+    captureError(errors, () => assertExactObject(c.frozen, ['generation', 'headSha', 'branch', 'includedUnits', 'unitEvidence', 'authorizationBoundary', 'at'], `${at}.frozen`))
+    if (!isObject(c.frozen)) errors.push(`${at}: ${c.state} candidate requires frozen evidence`)
+    else {
+      const latest = updates.filter((entry) => entry?.generation === c.generation).at(-1)
+      if (!latest || latest.headSha !== c.frozen.headSha) errors.push(`${at}: frozen head must equal the latest update in its generation`)
+      if (c.frozen.generation !== c.generation) errors.push(`${at}: frozen generation must equal the current generation`)
+      if (c.frozen.branch !== latest?.branch) errors.push(`${at}: frozen branch must equal the latest update branch`)
+      if (!same(c.frozen.includedUnits, component.units)) errors.push(`${at}: frozen candidate must include the complete component`)
+      if (!same(c.frozen.unitEvidence, latest?.unitEvidence)) errors.push(`${at}: frozen unit evidence must equal the latest update`)
+      const byId = new Map((Array.isArray(manifest?.units) ? manifest.units : []).map((unit) => [unit?.id, unit]))
+      const currentEvidence = Array.isArray(component.units)
+        ? component.units.map((id) => { try { return preliminaryEvidence(byId.get(id), component.id) } catch (error) { errors.push(error.message); return null } })
+        : []
+      if (!currentEvidence.includes(null) && !same(c.frozen.unitEvidence, currentEvidence)) errors.push(`${at}: frozen unit evidence is stale against the current unit heads`)
+      if (latest?.integrated?.assembly !== 'clean' || latest?.integrated?.tests !== 'green' || latest?.integrated?.conflicts?.length || latest?.integrated?.failedTests?.length) errors.push(`${at}: frozen candidate requires clean assembly and green tests`)
+      const frozenBoundary = (() => { try { return boundary(c.frozen.authorizationBoundary, `${at}.frozen.authorizationBoundary`) } catch (error) { errors.push(error.message); return null } })()
+      if (frozenBoundary && (frozenBoundary.kind !== 'integration' || frozenBoundary.value !== c.frozen.headSha)) errors.push(`${at}: frozen authorization boundary must bind the integration HEAD`)
+    }
+  }
+  if (c.state === 'authorized') {
+    const latest = authorizations.at(-1)
+    if (!latest || latest.generation !== c.generation || latest.headSha !== c.frozen?.headSha) errors.push(`${at}: authorized candidate requires terminal authorization on the frozen head in this generation`)
+    if (!same(component.authorizationBoundary, latest?.authorizationBoundary)) errors.push(`${at}: component authorizationBoundary must equal terminal component HEAD boundary`)
+  }
+  const roster = new Set((Array.isArray(manifest?.units) ? manifest.units : []).map((unit) => unit?.id))
+  for (const id of Array.isArray(component.units) ? component.units : []) if (!roster.has(id)) errors.push(`${at}: component unit ${id} is not in the roster`)
+  validateStoredComponentDelivery(manifest, component, c, index, errors)
+  return errors
+}
+
+export function validateComponentCandidates(manifest, options = {}) {
+  if (manifest?.components === undefined || manifest?.components === null) return []
+  if (!Array.isArray(manifest.components)) return ['components must be an array']
+  const errors = []
+  const ids = new Set()
+  manifest.components.forEach((component, index) => {
+    if (!isObject(component) || !nonEmpty(component.id)) errors.push(`components[${index}] requires a non-empty id`)
+    else if (ids.has(component.id)) errors.push(`components[${index}] duplicates component id ${component.id}`)
+    else ids.add(component.id)
+    errors.push(...candidateErrors(manifest, component, index, options))
+  })
+  errors.push(...reconciliationErrors(manifest))
+  return errors
+}