diff --git a/docs/approval-claim.md b/docs/approval-claim.md index cec57ae..3a99d2d 100644 --- a/docs/approval-claim.md +++ b/docs/approval-claim.md @@ -122,6 +122,30 @@ was not issued against a PDP decision — a stated fact rather than a missing key, so a consumer cannot read absence as an oversight. It is not required on every approval, because approvals legitimately exist that no decision preceded. +### What `pdp_digest` can and cannot cover + +`pdp_digest` is recorded **at issue**, and issue precedes the decision — the +claim is step 1, the decision is step 2. So it is necessarily the digest of the +underlying action request *as it stands before any approval claim is embedded +in it*. That is not a design preference; it is forced by ordering. A claim +cannot carry the digest of a document that contains that claim: the value would +have to be known before it could be computed. + +This matters because a PDP may hash `context` into its request digest while a +dual-control pattern carries the claim in `context.approval`. Embedding the +claim then changes the digest of the request carrying it, and a `pdp_digest` +recorded at issue will match neither the full request nor, necessarily, any +particular reconstruction of it. + +The exact rule — which fields the PDP excludes when computing the digest a +claim is bound to, or whether the claim travels alongside the hashed context +rather than inside it — belongs to the PDP's digest contract, not here. This +engine records what it was given at issue and does not compute it. **A consumer +must not guess the exclusion.** Computing a digest under an assumed rule +produces a confident wrong answer, and comparing two digests derived under +different rules fails open in the direction of accepting a claim bound to a +different request. + ### Declared path intent — `binding.pdp_path` `GH-DEC-2026-008` requires `pdp_digest` on the `GH-DEC-2026-003` path. This