feat: approval intent receipts, role-route enforcement and operator docs (#220)

[OkeyAmy]

Closes #220

Why this PR exists

#377 was squash-merged by the automation while its squash snapshot still held only the foundation slice — the merge cut happened before the full-scope commits landed on the branch. Upstream main therefore received the state machine, canonical fingerprints, entity and migrations, but not the receipt storage, the service, the REST surface, the enforcement wiring or the docs, and #220 stayed open. This PR carries exactly the four commits that never landed; everything in them was already part of #377's final reviewed state.

What lands here

• Receipt storage. The signed receipt document is kept (jsonb) next to its hash, so verification can be re-run after the fact; verification re-canonicalizes before hashing, so jsonb key order cannot invalidate a receipt. Additive, idempotent migration.
• Lifecycle auditing. The approval flow leaves the same hash-chained trail as every other sensitive surface: maintainer.action.proposed, .cancelled, .executed under a new APPROVAL scope.
• Service. Propose (identical-commitment dedupe, mandatory reason committed to by the fingerprint, self-approval rejected), single-use execution via an atomic conditional claim, signed receipts on completion and failure, cancellation, single and bulk expiry, and post-hoc receipt verification. Proposal evidence fails closed: if the evidence append fails, the intent is cancelled and the caller gets a 503 — nothing stays executable that cannot be evidenced.
• Admin REST surface at /admin/intents (propose, list, get, cancel, expire, receipt verify) behind the same JWT + role + 2FA guard stack as the existing admin controllers. Execution is deliberately not a generic endpoint: an intent is consumed by the route it authorizes, so a caller cannot attach an arbitrary operation to a signed intent.
• Enforcement on the role routes. With MAINTAINER_APPROVAL_INTENTS_ENFORCED on (read per request, default off = byte-identical behaviour), PATCH /admin/users/:id/role requires approvalIntentId in the body and DELETE requires it as a query parameter; the intent must commit to exactly this action, user and role — 409 on mismatch, 428 when absent. The executor is re-checked server-side, and a designated approver is the only permitted executor.
• Operator guide — docs/MAINTAINER_ACTION_APPROVALS.md: endpoints, flag, lifecycle diagram, edge-case table (dedupe, late execution, double-claim races, approver rules, tampered receipts), failure modes (evidence outages, missing signing key) and both rollback paths.

Verification

79 tests across the affected suites — intent foundation, service lifecycle, REST wiring, both migrations, and the admin-role controller including 8 enforcement tests — all green on this branch. npx tsc --noEmit reports nothing for any file here. The repo's pre-existing baseline failures are untouched.

After this merges

#218 (the multi-actor concurrency harness, already written against this code) rebases down to exactly its own five commits and lands as a separate PR with Closes #218.

[drips-wave]

@OkeyAmy Great news! 🎉 Based on an automated assessment of this PR, the linked Wave issue(s) no longer count against your application limits.

You can now already apply to more issues while waiting for a review of this PR. Keep up the great work! 🚀

Learn more about application limits

[github-actions]

Code Review & Auto-Merge — @dorismaduegbunam 🚀

Thank you @OkeyAmy for your contribution!

• PR Title: feat: approval intent receipts, role-route enforcement and operator docs (Trellis API: Add maintainer action approval flow with signed intent receipts #220)
• Author: @OkeyAmy
• Branch: feat/220-approval-intent-completion -> main
• Linked Issues: Closes Trellis API: Add maintainer action approval flow with signed intent receipts #220, Closes Trellis API: Build multi-actor concurrency harness for race-prone mutations #218
• Status: Approved & Merged into main.

Verified code changes and repository requirements. Merging pull request.