feat(0.7.1g1P2-2): digest-migration certificate as a first-class authority object (M45/M46/M47)

[GionaGranchelli]

Base

e6e0d69ed2adfa47c6cdfa4485ef30bc184bb881 — the post-merge Epic tip from #470.

Step 2 of TASK-0.7.1g1P2-AUTHORITY-MODEL-RECONCILIATION.md §6.2. The mechanism only, as scoped: type + ledger + loader + the mint/retention/removal lifecycle (M45/M46/M47) with its own fail-closed tests. No certificate-aware consumption, no M40-M44, no P2, no mutation of the 67 admissions.

Scope

Five new files, 843 insertions, nothing modified:

• MutationAuthorityDigestCertificate.kt — the certificate type, its ledger, and the bounded admission-set digest.
• MutationAuthorityDigestCertificateLoader.kt — parses config/quality/mutation-authority-digest-certificates.yml.
• MutationAuthorityDigestCertificateCeremony.kt — the lifecycle: M45, M46, M47.
• Two test files, 22 tests.

No config/quality/** file is touched: no ledger instance is created, because minting the P1M certificate is a later base transition. This change introduces only the machinery that transition will use.

Design

The certificate carries a semantic upgrade of the whole-population authority digest without rewriting historical authority. The 67 P1 authorizations stay bound to their raw-v1 digests and byte-identical; the certificate stands beside them in its own ledger and states, in base authority, that one exact fromDigest is equivalent to one exact toDigest for one exact bounded set of authorizations. M36's payload comparison never sees it, so M36 and M37 stay literally unchanged — no exception branch, no permitted-field list.

Fields exactly as designed: fromAlgorithm, fromDigest, toAlgorithm, toDigest, admissionSetDigest, fromBaseSha, reason. enforcedPayload() is that set, with authorizedBy/authorizedAt excluded as audit-only — so M46 judges byte-identity over bound fields while touching who/when can never manufacture authority.

• M45 mint-time base binding: a newly introduced certificate whose fromBaseSha ≠ the authority base fails. Anti-replay at introduction only, exactly as MutationPopulationAdmission.fromBaseSha.
• M46 retained immutability: a base certificate whose enforced payload differs in any field fails. Correcting a certificate means minting a new one later, never editing a retained one.
• M47 removal custody: a base certificate absent from the candidate fails.

The admission-set recipe (sorted identities joined with a newline plus a trailing newline, SHA-256) is documented as contract, not implementation detail, because whoever mints the P1M certificate must reproduce it exactly and M42 will compare against it.

Deliberate scope boundary — the T19 half

M47 takes its strictly fail-closed half. With no certificate-aware consumption path there is no way to prove a valid consumption, so any disappearance fails. That is documented in the rule, in the type, and in the test — not left as an unfinished branch. A disappearance must never become its own evidence. When M40-M44 land it becomes "unless validly consumed by the same transition", judged against an independently established consumption. This is the T19 boundary flagged during Step 1.

Tests (22)

• Loader shape contract, every fail-closed case: malformed digest, short fromBaseSha, unknown digest semantics, missing reason, absent schemaVersion, duplicate source digest (two certificates claiming one source contradict each other), and a certificate that migrates a digest to itself.
• The admission-set recipe pinned against the real committed 67-admission set (98a9587a…), so the value P1M must reproduce is testable now.
• M45 in both directions, plus the discriminator that binding is enforced at mint only — a retained certificate survives intermediate merges, which is what makes delayed consumption possible.
• M46 driven as a loop over each bound field: adding a field to the type without classifying it into the enforced payload fails this test.
• Audit-only metadata changing without failing, in both directions.
• M47 in both directions, including that a mere absence is never a consumption.

Verification

• ./gradlew :build-logic:test --tests 'dev.tramai.build.quality.MutationAuthorityDigestCertificate*' --rerun-tasks — BUILD SUCCESSFUL, 8 tasks executed
• ./gradlew spotlessKotlinCheck (ratchet-scoped to the base) — BUILD SUCCESSFUL
• ./gradlew verifyStaticAnalysis — no new findings; Detekt baseline unchanged (4792 → 4792, 0 added, 0 removed). Four findings in the first draft were fixed properly, by constants and by restructuring the test builders — not baselined and not suppressed.
• ./gradlew verifyChangePolicy -PchangePolicyBase=e6e0d69… — PASSED, 5 changed files, change class build-logic, no policy violations

Not run

Consumption (M40-M44), certificate-aware M34, the full T1-T19 matrix, and the task-level authority transport for certificates — all Step 3. No P2, no campaign rerun, no baseline regeneration, no classification or evolution change.

Remaining risks

• The 67 admissions remain bound to their raw-v1 digests and are not consumable under authority-v2 until the P1M certificate is minted in a base transition and Step 3 consumes it. That is the designed ordering, not a regression.
• M47 is stricter than its final form until M40-M44 exist (above). Step 3 must relax it only against a proven consumption.
• The certificate ledger file does not exist yet, so every real invocation loads the fail-closed empty ledger. The loader is exercised against fixtures, including the real admission ledger for the set-digest recipe.

[Copilot]

Copilot review overview

🔵 Needs a closer look

This is high-stakes build-authority governance machinery with subtle fail-closed semantics that warrants final human review despite only minor convention findings.

Review effort: Balanced
Findings: 1 · 1

Open (2)

• Resolve repository root by walking up from the working dir · New
• Rename shadowing local variable to avoid name collision · New

What changed in this PR

This PR implements Step 2 of the authority-model reconciliation task, introducing the digest-migration certificate as a first-class, base-side authority object within the build-logic mutation-ratchet governance machinery. The certificate lets the whole-population authority digest be semantically upgraded (raw-v1 → authority-v2) over a bounded, named set of authorizations without rewriting the 67 historical P1 authorizations or touching the M36/M37 admission-payload comparison. The change is mechanism-only: it adds the type, its ledger, a fail-closed loader, and the mint/retention/removal lifecycle (M45/M46/M47), plus tests. It deliberately omits certificate consumption (M40–M44), task wiring, and any config/quality/** ledger instance, all deferred to Step 3.

Changes:

• Adds MutationAuthorityDigestCertificate (immutable type with an audit-excluded enforcedPayload()) and its MutationAuthorityDigestCertificates ledger plus the bounded admission-set digest recipe.
• Adds a shape-only, fail-closed YAML loader and a transition-level ceremony enforcing mint-time base binding (M45), retained immutability (M46), and strictly fail-closed removal custody (M47).
• Adds 22 tests covering loader shape/fail-closed cases, the pinned admission-set digest recipe, and bidirectional lifecycle discriminators.

File	Description
MutationAuthorityDigestCertificate.kt	Certificate type + ledger + admissionSetDigest recipe; documents field semantics and rule ownership.
MutationAuthorityDigestCertificateLoader.kt	Fail-closed, shape-only parser for the certificate YAML; validates every enforcement-critical field.
MutationAuthorityDigestCertificateCeremony.kt	Transition-level M45/M46/M47 lifecycle checks producing VerificationDiagnostics.
MutationAuthorityDigestCertificateLoaderTest.kt	Loader shape contract, fail-closed cases, and the admission-set recipe pinned to the committed 67-admission set.
MutationAuthorityDigestCertificateCeremonyTest.kt	Bidirectional discriminators for M45/M46/M47, including the fail-closed removal half.

The implementation closely and faithfully mirrors the existing sibling MutationPopulationAdmissionLoader/ceremony patterns, is well-documented, and is backed by strong, behavior-level assertions. My two findings are minor convention items (parameter shadowing in the loader; non-robust repo-root resolution in the test) and are documented inline.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.