feat(agent-mesh): action-bound approval protocol foundation (ADR-0030 step 1)

[Carlos Hernandez (carloshvp)]

Summary

Step 1 of the ADR-0030 migration (section 9): the action-bound, fail-closed approval protocol foundation in agentmesh.governance.approval_protocol.

Purely additive — nothing is wired into the policy evaluator or the legacy agentmesh.governance.approval handlers yet, so no existing import path or behavior changes.

Unblocks implementation of #2478 (require_approval verdict / human + LLM approval chains).

What's included

• digest.py — vendored RFC 8785 JCS canonicalization + sha256_jcs() (no new dependency).
• binding.py — ActionBinding / ActionTarget and the action_digest (ADR section 2): an approval is bound to one exact action; changing any parameter, target, tool schema version, agent, or subject changes the digest.
• models.py — the four protocol objects (PolicyDecisionRecord, ApprovalRequest, ApprovalChainEntry, ApprovalResolution) with hash-linked, self-sealing chain entries (ADR section 3).
• store.py — ApprovalStore durable-store protocol + thread-safe InMemoryApprovalStore with atomic one-time consume() (ADR section 5).
• coordinator.py — ApprovalCoordinator: open → submit (authority-checked, hash-linked) → resolve → 7-point fail-closed execution-time revalidation (ADR section 6).

Fail-closed properties (all test-covered)

• approval authorizes exactly one action digest (parameter swap ⇒ deny);
• valid only within the request's time window (deny even after a grant once expired);
• consumed exactly once;
• LLM advisory votes never satisfy a stage (ADR section 8);
• any mutation of a sealed chain entry is detected (chain_tampered).

Tests

tests/test_approval_protocol.py — 25 tests, all passing.

Deferred to follow-up PRs (per ADR section 9)

• step 2: wire require_approval through PolicyEvaluator / govern
• step 3: legacy ApprovalHandler compatibility adapters
• step 4: versioned webhook contract
• step 5: deprecate timeout auto-approval and body-supplied approver identity (strict mode)
• step 6: non-Python SDK parity (including cross-SDK JCS byte-parity)

Refs #2478. Implements ADR-0030 step 1.

🤖 Generated with Claude Code

[github-actions]

PR Review Summary

Check	Status	Details
🔍 Code Review	⚠️ Missing	No current-run comment
🛡️ Security Scan	⚠️ Missing	No current-run comment
🔄 Breaking Changes	⚠️ Missing	No current-run comment
📝 Docs Sync	⚠️ Missing	No current-run comment
🧪 Test Coverage	⚠️ Missing	No current-run comment

Verdict: ⚠️ AI review incomplete; ready for human review

AI review comments are untrusted advisory output. The summary reports workflow-generated completion status only, not model-authored pass/fail claims.

[Carlos Hernandez (carloshvp)]

ADR-0030 has merged and #2478 is now unblocked. This is step 1 of the ADR section-9 migration (the action-bound approval-protocol foundation) — marking ready for review. Steps 2-6 will follow as separate PRs.

[Imran Siddique (imran-siddique)]

Clean step-1 foundation. JCS canonicalization vendored correctly (no new dep), action digest is deterministic over all execution-relevant fields, validate_for_execution is fail-closed with machine-readable reason codes, and the hash-linked chain entry structure matches ADR-0030 section 4. Purely additive — nothing wired into the evaluator yet, which is exactly right for step 1. Unblocks #2478.