docs: add payment evidence frame specification

[chopmob-cloud]

Summary

This PR adds docs/topics/payment-evidence-frame.md, a standalone specification page for the Payment Evidence Frame (PEF) -- a transport-agnostic JSON envelope for wrapping payment lifecycle receipts in A2A task artifacts.

PEF addresses a practical orchestration problem: when a payment agent returns a receipt as an artifact, the orchestrator needs to identify the receipt type, hold a stable reference ID that survives re-serialisation and late signing, and detect tampering -- all without parsing the inner domain format.

The document covers:

• Overview -- what PEF is and why it exists in A2A
• claim_type taxonomy -- five closed-enum values (payment_admission, payment_settlement, payment_cancellation, payment_refund, composite_verdict)
• Frame fields table -- all required and optional fields with types and semantics
• frame_id derivation -- deterministic SHA-256 over JCS-canonical preimage (frame_id and signature excluded)
• Task artifact usage -- annotated JSON example showing how a payment agent attaches a PEF artifact conforming to the A2A Artifact/Part proto schema
• frame_id stability -- rationale for excluding signature from the preimage so late signing does not invalidate recorded identifiers
• Reference implementations -- Apache 2.0 Python and TypeScript packages
• Normative references -- IETF I-D draft-hopley-x402-payment-evidence-frame, RFC 8785 (JCS), RFC 9421 (HTTP Message Signatures)

The page is also added to the mkdocs nav under Documentation, after Extensions.

IETF I-D: https://datatracker.ietf.org/doc/draft-hopley-x402-payment-evidence-frame/

Closes #1769

---

AlgoVoi (chopmob-cloud) -- Acquisition enquiries: https://docs.algovoi.co.uk/acquisition

[gemini-code-assist]

Code Review

This pull request introduces a new documentation page for the Payment Evidence Frame (PEF) and integrates it into the project's navigation. The review feedback correctly identifies that the example JSON for the task artifact does not conform to the Artifact and Part schemas defined in a2a.proto, and provides a corrected ProtoJSON structure.

[gemini-code-assist]

The example JSON and description do not align with the Artifact and Part schemas defined in a2a.proto. In the A2A protocol, an Artifact does not have type, mimeType, or data fields directly. Instead, it contains a list of parts, where each Part has a media_type and a data field (which holds the structured JSON payload).

Here is the corrected description and JSON representation conforming to the A2A protocol's ProtoJSON representation:

A payment agent attaches a PEF as an A2A task artifact. The artifact contains a single part with media_type: "application/json", where the data field carries the complete frame object.

Example artifact for a settlement confirmation:

{
  "artifactId": "artifact-uuid-123",
  "name": "Payment Evidence",
  "parts": [
    {
      "mediaType": "application/json",
      "data": {
        "pef_version": "1",
        "claim_type": "payment_settlement",
        "receipt_format": "settlement-attestation-v1",
        "frame_provider_did": "did:web:payments.example.com",
        "frame_timestamp_ms": 1748563200000,
        "canon_version": "urn:x402:canonicalisation:jcs-rfc8785-v1",
        "receipt": {
          "status": "SETTLED",
          "chain": "base",
          "tx_hash": "0x3c4f1e2a...",
          "settled_at_ms": 1748563195000
        },
        "receipt_hash": "sha256:a1b2c3d4e5f6...",
        "frame_id": "sha256:3c4f1e2a9b8d..."
      }
    }
  ]
}

[Poke-nushi]

Thanks for putting this together. PEF looks useful as a payment-specific evidence frame for A2A task artifacts.

I wanted to clarify one boundary before #1769 is treated as fully resolved.

My original question in #1769 was broader than payment lifecycle receipts. It was about where verifier-side trust / permit / admission / attenuation / receipt artifacts for risky external actions should live relative to A2A.

Payment evidence can be one important evidence type. But the broader relying-party admission problem may still involve actor/principal linkage, runtime evidence, task-scoped permits, status/freshness/replay checks, local policy, attenuation semantics, verifier-side admission receipts, and post-execution linkage.

Would it make sense to treat this PR as a payment-specific partial answer to #1769, and either keep the broader verifier-side boundary discussion open or split it into a follow-up placement issue?

I am not suggesting that A2A core should own all of this. A small by-reference metadata surface, with full admission / evidence / receipt artifacts outside A2A core, may be enough.

[chopmob-cloud]

Thanks for the framing. That boundary is accurate.

PEF is explicitly payment-specific: payment-lifecycle evidence covering authorisation, settlement, compliance verdict, and linkage back to the initiating task. It is not a general-purpose admission or attenuation frame.

The broader surface you describe in #1769 — actor/principal linkage, runtime evidence, task-scoped permits, status/freshness/replay, local policy, attenuation semantics, verifier-side admission receipts, post-execution linkage — is a distinct and larger problem. This PR does not attempt to resolve it.

Treating this PR as a payment-specific partial answer to #1769 and keeping the broader discussion open (or splitting into a follow-up placement issue) makes sense. The by-reference metadata surface you mention is the right shape: a small anchor in A2A core, with full admission/evidence/receipt artefacts living outside.

On our production side, the payment-specific slice maps to two artefacts: a compliance receipt (allow/refer/deny decision record, written before any side effect) and a settlement attestation (outcome record, written after). Those cover the payment evidence chain. The broader admission/attenuation layer — non-payment risky actions, principal linkage, task-scoped permits — sits outside that surface and is not addressed by PEF.

AlgoVoi (chopmob-cloud) -- Acquisition enquiries: https://docs.algovoi.co.uk/acquisition