@qijenchen/governance 0.1.0-beta.94

package/src/snapshot.mjs

@@ -0,0 +1,520 @@
+import { randomUUID } from 'node:crypto'
+import { realpathSync } from 'node:fs'
+import { cp, mkdir, readFile, rename, rm } from 'node:fs/promises'
+import { basename, dirname, resolve } from 'node:path'
+import { mkdtemp } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import {
+  PACKAGE_VERSION,
+  assertNoSymlinkWithin,
+  canonicalize,
+  compareUtf8Bytes,
+  compareInventories,
+  diagnostic,
+  digest,
+  exists,
+  inventoryFile,
+  inventoryTree,
+  resolveWithin,
+  result,
+  stableJson,
+  treeDigest,
+  writeFileWithMode,
+  writeJsonAtomic,
+} from './common.mjs'
+import {
+  assertArtifactSchema,
+  inspectContract,
+  inspectSkillParity,
+  sourceRecords,
+} from './contract.mjs'
+import {
+  assertClosedGitLocalConfiguration,
+  runClosedGit,
+} from './closed-tool-execution.mjs'
+
+function provenance(contract) {
+  return {
+    generated: true,
+    generator: '@qijenchen/governance',
+    generatorVersion: PACKAGE_VERSION,
+    manifestId: contract.manifest.id,
+    contractDigest: contract.contractDigest,
+    role: contract.roleId,
+  }
+}
+
+function hasFailure(diagnostics) {
+  return diagnostics.some((item) => ['FAIL', 'BLOCK', 'ERROR'].includes(item.outcome))
+}
+
+function applicableRules(contract) {
+  return contract.rules
+    .filter((rule) => rule.appliesToRoles?.includes('*') || rule.appliesToRoles?.includes(contract.roleId))
+    .map((rule) => ({
+      ruleId: rule.ruleId,
+      severity: rule.severity,
+      source: rule.source,
+      blocking: rule.blocking,
+      gateIds: rule.gateIds,
+      providerCoverage: rule.providerCoverage,
+    }))
+    .sort((a, b) => compareUtf8Bytes(a.ruleId, b.ruleId))
+}
+
+function providerAdapter(contract, provider) {
+  return `#!/usr/bin/env node
+// @generated by @qijenchen/governance ${PACKAGE_VERSION}; role=${contract.roleId}; contract=${contract.contractDigest}; DO NOT EDIT.
+import { runHookCli } from '@qijenchen/governance/hook'
+
+await runHookCli({ provider: ${JSON.stringify(provider.id)}, role: ${JSON.stringify(contract.roleId)} })
+`
+}
+
+function provenanceMarkdown(contract, sources, skillParity) {
+  const sourceRows = sources.map((source) => `| ${source.id} | \`${source.path}\` | \`${source.hash}\` |`).join('\n')
+  const parityRows = skillParity.map((item) => `| ${item.id} | ${item.sourceProvider} \`${item.sourceDirectory}\` | ${item.targetProvider} \`${item.targetDirectory}\` | ${item.sourceSkills.length} shared + ${item.requiredTargetExtras.length} target-only |`).join('\n')
+  return `<!-- @generated by @qijenchen/governance ${PACKAGE_VERSION}; role=${contract.roleId}; contract=${contract.contractDigest}; DO NOT EDIT. -->
+# Governance snapshot provenance
+
+- Manifest: \`${contract.manifest.id}\`
+- Role: \`${contract.roleId}\`
+- Contract digest: \`${contract.contractDigest}\`
+- Generator: \`@qijenchen/governance@${PACKAGE_VERSION}\`
+
+No rule prose is copied into this snapshot. Paths and digests point to their canonical owners.
+
+## Canonical inputs
+
+| ID | Owner path | Digest |
+|---|---|---|
+${sourceRows}
+
+## Provider skill parity
+
+| Contract | Source | Target | Expected surface |
+|---|---|---|---|
+${parityRows || '| — | — | — | — |'}
+`
+}
+
+export async function buildExpectedSnapshot(contract, temporaryRepoRoot) {
+  const output = resolveWithin(temporaryRepoRoot, contract.outputDirectory, 'outputDirectory')
+  const lock = resolveWithin(temporaryRepoRoot, contract.lockFile, 'lockFile')
+  await rm(output, { recursive: true, force: true })
+  await rm(lock, { force: true })
+  await mkdir(output, { recursive: true })
+
+  const sources = await sourceRecords(contract)
+  const parity = await inspectSkillParity(contract)
+  const roleProviders = (contract.role?.requiredProviders || [])
+    .map((id) => contract.providers.find((provider) => provider.id === id))
+    .filter(Boolean)
+  const roleGates = (contract.role?.requiredGateIds || [])
+    .map((id) => contract.gates.find((gate) => gate.id === id))
+    .filter(Boolean)
+  const generatedProvenance = provenance(contract)
+
+  const controlPlane = {
+    _provenance: generatedProvenance,
+    schemaVersion: 1,
+    role: contract.roleId,
+    canonicalSources: sources,
+    rules: applicableRules(contract),
+    providers: roleProviders.map((provider) => provider.id),
+    gates: roleGates.map((gate) => gate.id),
+    skillParity: parity.records,
+    registryDigests: contract.registryDigests,
+    schemaDigests: contract.schemaDigests,
+  }
+  await writeFileWithMode(resolve(output, 'control-plane.json'), stableJson(controlPlane), 0o644)
+
+  for (const provider of roleProviders) {
+    await writeFileWithMode(resolve(output, 'providers', `${provider.id}.json`), stableJson({
+      _provenance: generatedProvenance,
+      schemaVersion: 1,
+      provider,
+      applicableRules: applicableRules(contract).map((rule) => ({ ruleId: rule.ruleId, coverage: rule.providerCoverage[provider.id] })),
+    }), 0o644)
+    await writeFileWithMode(resolve(output, 'adapters', `${provider.id}-hook.mjs`), providerAdapter(contract, provider), 0o755)
+  }
+
+  await writeFileWithMode(resolve(output, 'PROVENANCE.md'), provenanceMarkdown(contract, sources, parity.records), 0o644)
+  const files = await inventoryTree(output)
+  const inputDigest = digest({
+    contractDigest: contract.contractDigest,
+    registryDigests: contract.registryDigests,
+    sources,
+    skillParity: parity.records,
+  })
+  const lockBody = {
+    _provenance: generatedProvenance,
+    schemaVersion: 2,
+    role: contract.roleId,
+    outputDirectory: contract.outputDirectory,
+    contractDigest: contract.contractDigest,
+    inputDigest,
+    snapshotDigest: treeDigest(files),
+    sources,
+    skillParity: parity.records,
+    files,
+  }
+  await assertArtifactSchema(contract, 'lock', lockBody)
+  await writeFileWithMode(lock, stableJson(lockBody), 0o644)
+  return { output, lock, files, lockBody, parityDiagnostics: parity.diagnostics }
+}
+
+async function withExpected(contract, callback) {
+  const temporary = await mkdtemp(resolve(tmpdir(), 'qijenchen-governance-'))
+  try {
+    const expected = await buildExpectedSnapshot(contract, temporary)
+    return await callback(expected, temporary)
+  } finally {
+    await rm(temporary, { recursive: true, force: true })
+  }
+}
+
+async function checkWithContract(contract) {
+  return withExpected(contract, async (expected) => {
+    const actualOutput = resolveWithin(contract.repoRoot, contract.outputDirectory, 'outputDirectory')
+    const actualLock = resolveWithin(contract.repoRoot, contract.lockFile, 'lockFile')
+    const expectedInventory = await inventoryTree(expected.output)
+    const actualInventory = await inventoryTree(actualOutput)
+    const diagnostics = compareInventories(expectedInventory, actualInventory, { prefix: contract.outputDirectory })
+    const expectedLock = await inventoryFile(expected.lock, contract.lockFile)
+    const actualLockInventory = await inventoryFile(actualLock, contract.lockFile)
+    diagnostics.push(...compareInventories(expectedLock, actualLockInventory))
+
+    if (actualLockInventory.length) {
+      try {
+        const body = JSON.parse(await readFile(actualLock, 'utf8'))
+        const lockedFiles = Array.isArray(body.files) ? body.files : []
+        diagnostics.push(...compareInventories(lockedFiles, actualInventory, { prefix: contract.outputDirectory }))
+      } catch (error) {
+        diagnostics.push(diagnostic({ ruleId: 'GOV-SNAPSHOT-001', severity: 'critical', kind: 'lock-parse-error', path: contract.lockFile, message: `Governance lock is invalid JSON: ${error.message}` }))
+      }
+    }
+    return { diagnostics, expectedDigest: await snapshotStateDigest(expected.output, expected.lock), actualDigest: await snapshotStateDigest(actualOutput, actualLock) }
+  })
+}
+
+export async function checkRepository(options = {}) {
+  const inspected = await inspectContract(options)
+  if (!inspected.contract || hasFailure(inspected.diagnostics)) return result('check', inspected.diagnostics)
+  const parity = await inspectSkillParity(inspected.contract)
+  const checked = await checkWithContract(inspected.contract)
+  const diagnostics = [...inspected.diagnostics, ...parity.diagnostics, ...checked.diagnostics]
+  const hooksOff = Boolean(options.hooksOff)
+  if (!diagnostics.length) diagnostics.push(diagnostic({ ruleId: 'GOV-SNAPSHOT-001', severity: 'info', kind: 'snapshot-exact', path: inspected.contract.outputDirectory, outcome: 'PASS', expected: checked.expectedDigest, actual: checked.actualDigest, message: `Snapshot is exact${hooksOff ? ' with native hooks disabled' : ''}.` }))
+  return result('check', diagnostics, { role: inspected.contract.roleId, contractDigest: inspected.contract.contractDigest, snapshotDigest: checked.actualDigest, hooksOff })
+}
+
+export async function doctorRepository(options = {}) {
+  const checked = await checkRepository(options)
+  const diagnostics = [...checked.diagnostics]
+  if (!diagnostics.some((item) => ['FAIL', 'BLOCK', 'ERROR'].includes(item.outcome))) {
+    diagnostics.push(diagnostic({ ruleId: 'GOV-CONTRACT-001', severity: 'info', kind: 'contract-valid', path: options.manifestPath || 'canonical/manifest.json', outcome: 'PASS', message: 'Canonical registries, source pointers, providers, gates, skills, snapshot, and lock are coherent.' }))
+  }
+  return result('doctor', diagnostics, checked.data)
+}
+
+async function copyExpectedToStage(expectedOutput, stageOutput) {
+  await cp(expectedOutput, stageOutput, { recursive: true, force: true, preserveTimestamps: false })
+  const entries = await inventoryTree(expectedOutput)
+  for (const entry of entries) {
+    if (entry.type === 'file') {
+      const mode = Number.parseInt(entry.mode, 8)
+      const { chmod } = await import('node:fs/promises')
+      await chmod(resolve(stageOutput, entry.path), mode)
+    }
+  }
+}
+
+// Exported from this module (but not the package entrypoint) so rollback can be
+// fault-injected and proven without weakening the production CLI contract.
+export async function installExpected(contract, expected, { transitionProbe } = {}) {
+  const targetOutput = resolveWithin(contract.repoRoot, contract.outputDirectory, 'outputDirectory')
+  const targetLock = resolveWithin(contract.repoRoot, contract.lockFile, 'lockFile')
+  await assertNoSymlinkWithin(contract.repoRoot, targetOutput, 'outputDirectory')
+  await assertNoSymlinkWithin(contract.repoRoot, targetLock, 'lockFile')
+  const token = `${process.pid}-${randomUUID()}`
+  const stageOutput = resolve(dirname(targetOutput), `.${basename(targetOutput)}.stage-${token}`)
+  const backupOutput = resolve(dirname(targetOutput), `.${basename(targetOutput)}.backup-${token}`)
+  const stageLock = resolve(dirname(targetLock), `.${basename(targetLock)}.stage-${token}`)
+  const backupLock = resolve(dirname(targetLock), `.${basename(targetLock)}.backup-${token}`)
+  let outputBackedUp = false
+  let lockBackedUp = false
+  let outputInstalled = false
+  let lockInstalled = false
+  try {
+    await mkdir(dirname(targetOutput), { recursive: true })
+    await mkdir(dirname(targetLock), { recursive: true })
+    await copyExpectedToStage(expected.output, stageOutput)
+    await cp(expected.lock, stageLock, { force: true })
+    if (await exists(targetOutput)) { await rename(targetOutput, backupOutput); outputBackedUp = true }
+    if (await exists(targetLock)) { await rename(targetLock, backupLock); lockBackedUp = true }
+    await rename(stageOutput, targetOutput); outputInstalled = true
+    if (transitionProbe) await transitionProbe('output-installed')
+    await rename(stageLock, targetLock); lockInstalled = true
+  } catch (error) {
+    const rollbackErrors = []
+    await rm(stageOutput, { recursive: true, force: true }).catch(() => {})
+    await rm(stageLock, { force: true }).catch(() => {})
+    try {
+      if (outputBackedUp) {
+        if (outputInstalled) await rm(targetOutput, { recursive: true, force: true })
+        await rename(backupOutput, targetOutput)
+        outputBackedUp = false
+      } else if (outputInstalled) {
+        await rm(targetOutput, { recursive: true, force: true })
+      }
+    } catch (rollbackError) {
+      rollbackErrors.push(rollbackError)
+    }
+    try {
+      if (lockBackedUp) {
+        if (lockInstalled) await rm(targetLock, { recursive: true, force: true })
+        await rename(backupLock, targetLock)
+        lockBackedUp = false
+      } else if (lockInstalled) {
+        await rm(targetLock, { recursive: true, force: true })
+      }
+    } catch (rollbackError) {
+      rollbackErrors.push(rollbackError)
+    }
+    if (rollbackErrors.length) throw new AggregateError([error, ...rollbackErrors], 'Governance install failed and rollback was incomplete')
+    throw error
+  } finally {
+    if (!outputBackedUp) await rm(backupOutput, { recursive: true, force: true }).catch(() => {})
+    if (!lockBackedUp) await rm(backupLock, { recursive: true, force: true }).catch(() => {})
+  }
+  await rm(backupOutput, { recursive: true, force: true }).catch(() => {})
+  await rm(backupLock, { recursive: true, force: true }).catch(() => {})
+}
+
+export async function generateRepository(options = {}) {
+  const inspected = await inspectContract(options)
+  if (!inspected.contract || hasFailure(inspected.diagnostics)) return result('generate', inspected.diagnostics)
+  const parity = await inspectSkillParity(inspected.contract)
+  const diagnostics = [...inspected.diagnostics, ...parity.diagnostics]
+  if (diagnostics.some((item) => ['FAIL', 'BLOCK', 'ERROR'].includes(item.outcome))) return result('generate', diagnostics)
+  return withExpected(inspected.contract, async (expected) => {
+    await installExpected(inspected.contract, expected)
+    const state = await snapshotState(inspected.contract)
+    diagnostics.push(diagnostic({ ruleId: 'GOV-SNAPSHOT-001', severity: 'info', kind: 'snapshot-generated', path: inspected.contract.outputDirectory, outcome: 'PASS', actual: state.digest, message: 'Canonical snapshot and committed lock were generated atomically.' }))
+    return result('generate', diagnostics, { role: inspected.contract.roleId, contractDigest: inspected.contract.contractDigest, snapshotDigest: state.digest })
+  })
+}
+
+async function snapshotStateDigest(output, lock) {
+  const files = await inventoryTree(output)
+  const lockEntries = await inventoryFile(lock, '__lock__')
+  return treeDigest([...files, ...lockEntries])
+}
+
+export async function snapshotState(contract) {
+  const output = resolveWithin(contract.repoRoot, contract.outputDirectory, 'outputDirectory')
+  const lock = resolveWithin(contract.repoRoot, contract.lockFile, 'lockFile')
+  const files = await inventoryTree(output)
+  const lockEntries = await inventoryFile(lock, '__lock__')
+  return { files, lockEntries, digest: treeDigest([...files, ...lockEntries]) }
+}
+
+function actionFromDiagnostic(item) {
+  const map = {
+    'missing-file': 'add',
+    'extra-file': 'remove',
+    'content-hash-mismatch': 'replace-content',
+    'mode-mismatch': 'replace-mode',
+    'type-mismatch': 'replace-type',
+  }
+  const action = map[item.evidence?.kind]
+  return action ? { action, path: item.evidence.path } : null
+}
+
+export async function planUpgrade(options = {}) {
+  const inspected = await inspectContract(options)
+  if (!inspected.contract || hasFailure(inspected.diagnostics)) return result('upgrade.plan', inspected.diagnostics, undefined, 'FAIL')
+  const parity = await inspectSkillParity(inspected.contract)
+  const diagnostics = [...inspected.diagnostics, ...parity.diagnostics]
+  if (diagnostics.some((item) => ['FAIL', 'BLOCK', 'ERROR'].includes(item.outcome))) return result('upgrade.plan', diagnostics, undefined, 'FAIL')
+  const checked = await checkWithContract(inspected.contract)
+  const actions = checked.diagnostics.map(actionFromDiagnostic).filter(Boolean).sort((a, b) => compareUtf8Bytes(a.path, b.path) || compareUtf8Bytes(a.action, b.action))
+  const plan = canonicalize({
+    schemaVersion: 1,
+    command: 'upgrade.plan',
+    role: inspected.contract.roleId,
+    outputDirectory: inspected.contract.outputDirectory,
+    lockFile: inspected.contract.lockFile,
+    contractDigest: inspected.contract.contractDigest,
+    currentDigest: checked.actualDigest,
+    expectedDigest: checked.expectedDigest,
+    actions,
+  })
+  await assertArtifactSchema(inspected.contract, 'upgradePlan', plan)
+  diagnostics.push(diagnostic({ ruleId: 'GOV-UPGRADE-001', severity: 'info', kind: 'upgrade-plan', path: inspected.contract.outputDirectory, outcome: 'PLAN', expected: checked.expectedDigest, actual: checked.actualDigest, message: `Upgrade plan contains ${actions.length} action(s).` }))
+  if (options.planFile) {
+    const planFile = resolveWithin(inspected.contract.repoRoot, options.planFile, 'planFile')
+    await assertNoSymlinkWithin(inspected.contract.repoRoot, planFile, 'planFile')
+    await writeJsonAtomic(planFile, plan)
+  }
+  return result('upgrade.plan', diagnostics, { plan }, 'PLAN')
+}
+
+export async function applyUpgrade(options = {}) {
+  const inspected = await inspectContract(options)
+  if (!inspected.contract || hasFailure(inspected.diagnostics)) return result('upgrade.apply', inspected.diagnostics)
+  if (!options.planFile) return result('upgrade.apply', [diagnostic({ ruleId: 'GOV-UPGRADE-001', severity: 'critical', kind: 'plan-required', path: '', message: 'upgrade apply requires --plan-file.' })])
+  let plan
+  try {
+    const planFile = resolveWithin(inspected.contract.repoRoot, options.planFile, 'planFile')
+    await assertNoSymlinkWithin(inspected.contract.repoRoot, planFile, 'planFile', { allowMissing: false })
+    plan = JSON.parse(await readFile(planFile, 'utf8'))
+    await assertArtifactSchema(inspected.contract, 'upgradePlan', plan)
+  } catch (error) {
+    return result('upgrade.apply', [diagnostic({ ruleId: 'GOV-UPGRADE-001', severity: 'critical', kind: 'plan-read-error', path: options.planFile, message: `Cannot read upgrade plan: ${error.message}` })])
+  }
+  const current = await snapshotState(inspected.contract)
+  const diagnostics = [...inspected.diagnostics]
+  if (plan.command !== 'upgrade.plan') diagnostics.push(diagnostic({ ruleId: 'GOV-UPGRADE-001', severity: 'critical', kind: 'plan-schema', path: options.planFile, expected: 'upgrade.plan', actual: plan.command, message: 'File is not a governance upgrade plan.' }))
+  if (plan.contractDigest !== inspected.contract.contractDigest) diagnostics.push(diagnostic({ ruleId: 'GOV-UPGRADE-001', severity: 'critical', kind: 'contract-changed', path: options.planFile, expected: plan.contractDigest, actual: inspected.contract.contractDigest, message: 'Canonical contract changed after the plan was created.' }))
+  if (plan.currentDigest !== current.digest) diagnostics.push(diagnostic({ ruleId: 'GOV-UPGRADE-001', severity: 'critical', kind: 'stale-plan', path: inspected.contract.outputDirectory, expected: plan.currentDigest, actual: current.digest, message: 'Generated state changed after the plan was created.' }))
+  if (diagnostics.some((item) => ['FAIL', 'BLOCK', 'ERROR'].includes(item.outcome))) return result('upgrade.apply', diagnostics)
+
+  return withExpected(inspected.contract, async (expected) => {
+    const expectedDigest = await snapshotStateDigest(expected.output, expected.lock)
+    if (expectedDigest !== plan.expectedDigest) {
+      diagnostics.push(diagnostic({ ruleId: 'GOV-UPGRADE-001', severity: 'critical', kind: 'expected-state-changed', path: options.planFile, expected: plan.expectedDigest, actual: expectedDigest, message: 'Expected generated state changed after the plan was created.' }))
+      return result('upgrade.apply', diagnostics)
+    }
+    await installExpected(inspected.contract, expected)
+    diagnostics.push(diagnostic({ ruleId: 'GOV-UPGRADE-001', severity: 'info', kind: 'upgrade-applied', path: inspected.contract.outputDirectory, outcome: 'APPLIED', actual: expectedDigest, message: 'Validated upgrade plan was applied.' }))
+    return result('upgrade.apply', diagnostics, { snapshotDigest: expectedDigest }, 'APPLIED')
+  })
+}
+
+export async function attestRepository(options = {}) {
+  const doctor = await doctorRepository(options)
+  if (doctor.outcome !== 'PASS') return result('attest', doctor.diagnostics)
+  const inspected = await inspectContract(options)
+  const contract = inspected.contract
+  const state = await snapshotState(contract)
+  let gitHead = null
+  let gitTree = null
+  let inGitRepository = false
+  try {
+    const probe = runClosedGit(['rev-parse', '--is-inside-work-tree'], {
+      cwd: contract.repoRoot,
+      timeoutMs: 5000,
+    })
+    inGitRepository = probe.status === 0 && probe.stdout.trim() === 'true'
+  } catch (error) {
+    return result('attest', [diagnostic({
+      ruleId: 'GOV-ATTEST-001',
+      severity: 'critical',
+      kind: 'closed-git-unavailable',
+      path: '',
+      message: `Cannot establish the closed Git runtime required for attestation: ${error.message}`,
+    })])
+  }
+  if (inGitRepository) {
+    try {
+      assertClosedGitLocalConfiguration(contract.repoRoot)
+    } catch (error) {
+      return result('attest', [diagnostic({
+        ruleId: 'GOV-ATTEST-001',
+        severity: 'critical',
+        kind: 'unsafe-git-configuration',
+        path: '',
+        message: error.message,
+      })])
+    }
+    const identity = runClosedGit(['rev-parse', '--show-toplevel', 'HEAD', 'HEAD^{tree}'], {
+      cwd: contract.repoRoot,
+      timeoutMs: 5000,
+    })
+    const identityLines = identity.status === 0 ? identity.stdout.trim().split(/\r?\n/) : []
+    let exactRepositoryRoot = false
+    try {
+      exactRepositoryRoot = identityLines.length > 0
+        && realpathSync(identityLines[0]) === realpathSync(contract.repoRoot)
+    } catch {}
+    if (
+      identityLines.length !== 3
+      || !exactRepositoryRoot
+      || !identityLines.slice(1).every(value => /^(?:[a-f0-9]{40}|[a-f0-9]{64})$/.test(value))
+    ) {
+      return result('attest', [diagnostic({
+        ruleId: 'GOV-ATTEST-001',
+        severity: 'critical',
+        kind: 'git-identity-unavailable',
+        path: '',
+        message: 'Cannot resolve the exact Git commit and tree through the closed Git runtime.',
+      })])
+    }
+    ;[, gitHead, gitTree] = identityLines
+    const status = runClosedGit([
+      'status',
+      '--porcelain=v1',
+      '-z',
+      '--untracked-files=all',
+      '--ignore-submodules=none',
+      '--no-renames',
+    ], {
+      cwd: contract.repoRoot,
+      maxOutputBytes: 32 * 1024 * 1024,
+      output: 'buffer',
+      timeoutMs: 10_000,
+    })
+    if (status.status !== 0 || status.error || status.signal !== null) {
+      return result('attest', [diagnostic({
+        ruleId: 'GOV-ATTEST-001',
+        severity: 'critical',
+        kind: 'git-status-unavailable',
+        path: '',
+        message: 'Cannot resolve the complete worktree state through the closed Git runtime.',
+      })])
+    }
+    const dirty = status.stdout.length > 0
+    if (dirty) return result('attest', [diagnostic({ ruleId: 'GOV-ATTEST-001', severity: 'critical', kind: 'dirty-worktree', path: '', expected: 'clean Git snapshot', actual: 'non-empty porcelain-v1-z status', message: 'Refusing evidence for a dirty worktree; commit the exact checked snapshot first.' })])
+    if (options.gitHead != null && options.gitHead !== gitHead) return result('attest', [diagnostic({ ruleId: 'GOV-ATTEST-001', severity: 'critical', kind: 'git-head-mismatch', path: '', expected: gitHead, actual: options.gitHead, message: '--git-head does not match the checked repository HEAD.' })])
+  } else {
+    // Deterministic fixtures may supply a synthetic subject. Real release evidence is always issued
+    // from a Git repository and signed externally by GitHub OIDC artifact attestation.
+    gitHead = options.gitHead ?? null
+  }
+  const issuedAt = options.issuedAt || new Date().toISOString()
+  if (Number.isNaN(Date.parse(issuedAt))) return result('attest', [diagnostic({ ruleId: 'GOV-ATTEST-001', severity: 'critical', kind: 'invalid-issued-at', path: '', actual: issuedAt, message: '--at must be an ISO-8601 timestamp.' })])
+  const claims = ['snapshot-integrity', 'contract-doctor', 'provider-skill-parity']
+  if (options.hooksOff) claims.push('hook-independent-check')
+  claims.sort()
+  const evidenceDigest = digest({
+    role: contract.roleId,
+    contractDigest: contract.contractDigest,
+    snapshotDigest: state.digest,
+    gitHead,
+    gitTree,
+    claims,
+  })
+  const attestation = canonicalize({
+    _provenance: provenance(contract),
+    schemaVersion: 1,
+    issuedAt: new Date(issuedAt).toISOString(),
+    subject: `${contract.manifest.id}:${contract.roleId}`,
+    role: contract.roleId,
+    contractDigest: contract.contractDigest,
+    snapshotDigest: state.digest,
+    gitHead,
+    gitTree,
+    evidenceDigest,
+    claims,
+  })
+  await assertArtifactSchema(contract, 'attestation', attestation)
+  if (options.attestationFile) {
+    const attestationFile = resolveWithin(contract.repoRoot, options.attestationFile, 'attestationFile')
+    await assertNoSymlinkWithin(contract.repoRoot, attestationFile, 'attestationFile')
+    await writeJsonAtomic(attestationFile, attestation)
+  }
+  const diagnostics = [diagnostic({ ruleId: 'GOV-ATTEST-001', severity: 'info', kind: 'evidence-manifest-issued', path: options.attestationFile || '<stdout>', outcome: 'PASS', actual: evidenceDigest, message: 'Digest-bound evidence manifest issued for the exact claims actually checked; external signing is separate.' })]
+  return result('attest', diagnostics, { attestation })
+}