Circuit artifact rotation runbook (without breaking historical verification)

This runbook defines how to rotate Groth16 circuit artifacts while preserving historical attestation verification guarantees.

Invariants

1. No silent rotation: every artifact change is versioned and committed.
2. Manifest is canonical: ARTIFACT_MANIFEST.json pins canonical hashes and zkey path per circuit.
3. Historical attestations remain verifiable via embedded verification key/hash + profile checks.
4. Pin enforcement is explicit: verifier pin checks are enabled by passing circuitRegistry.

Rotation workflow

1. Rebuild circuit artifacts (.wasm, .r1cs, .zkey, .vkey.json).
2. If production path, run MPC ceremony and produce transcript JSON.
3. Update manifest pins:
   • npm run manifest:generate
   • npm run manifest:post-mpc -- --transcript <path> --circuit-dir <dir> --refresh-hashes
4. Update conformance/circuit-registry.example.json from manifest (or equivalent registry source).
5. Run audit suite + terminology checks:
   • npm run test:audit-suite
   • npm run docs:check-terms
6. Commit in provenance order:
   • ceremony artifacts
   • manifest/governance/docs pinning

Backward-compat policy

• Historical attestation validity: determined by embedded proof + embedded verification key + signature + selected verification profile.
• New registry pin mismatch checks only apply when verifier is configured with circuitRegistry and attestation includes circuit metadata.
• Deprecation is explicit: mark circuit as deprecated in registry; do not remove old artifacts until retention window ends.

Upgrade matrix

Attestation	Verifier	Expected result (VDI_VERIFY_STANDARD_V1)	Expected result (VDI_VERIFY_STRICT_V1)
old artifact set	new verifier (no circuitRegistry)	PASS if embedded proof/signature/timestamps pass	PASS if strict checks (revocation + authority binding) pass
old artifact set	new verifier (circuitRegistry enabled)	PASS if circuit_hash matches pin; else VDI_ERR_CIRCUIT_HASH_MISMATCH	same as STANDARD + strict-only checks
new artifact set	old verifier	PASS if schema fields understood and embedded cryptographic checks pass	PASS/FAIL per old strict implementation semantics
new artifact set	new verifier (circuitRegistry enabled)	PASS when manifest/registry pins updated in lockstep	same as STANDARD + strict-only checks

Emergency rollback

1. Revert to prior manifest + registry pins commit.
2. Keep prior artifacts available.
3. Mark bad artifact version deprecated in registry metadata.
4. Re-run npm run artifact:status and attach output to incident ticket.