Summary
The reporting reconciler handles ledger polling, snapshot restart, deduplication, retries, receipt creation, and receipt submission, but it requires every adopter to provide a custom inspect(context) callback for the security- and interoperability-critical resource path.
The SDK therefore does not yet deliver the intended “SDK-managed polling, deduplication, file retrieval, validation, and retries” experience.
What adopters must currently reinvent
- retrieve a manifest/resource with destination credentials;
- verify manifest SHA-256 and every file's size/checksum;
- enforce manifest-last completeness;
- parse the declared format/compression;
- validate rows against the pinned schema contract;
- safely fetch and digest-check report-definition/schema/canonicalization contracts;
- recompute row counts, control totals, and RFC 8785 canonical content digests;
- distinguish transient retrieval failures from permanent integrity failures;
- return the exact
ReportingObservation needed for a receipt.
Our seller/buyer vertical slice had to implement this callback manually before it could prove that both parties shared the same billing totals.
Proposed SDK surface
- Keep the callback as an advanced escape hatch.
- Add a built-in manifest/file inspector driven by a pluggable
ReportingResourceReader and credential provider.
- Ship readers/adapters for ordinary HTTPS and object-store resources, with warehouse/native-commit adapters as separate packages or interfaces.
- Reuse the SDK's hardened canonical-reference fetch policy: HTTPS, DNS/IP pinning and private-range rejection, redirect policy, byte/time limits, digest-before-parse, bundled schema dialect, and local-fragment-only references.
- Return typed, stable failure codes suitable for retry versus rejected receipt.
- Add one conformance fixture that retrieves a manifest, verifies files, detects corruption/missing objects, recomputes totals/digest, and creates an accepted receipt.
Related protocol/implementation PRs: adcontextprotocol/adcp#6953 and #6953's Python implementation in #1095.
Summary
The reporting reconciler handles ledger polling, snapshot restart, deduplication, retries, receipt creation, and receipt submission, but it requires every adopter to provide a custom
inspect(context)callback for the security- and interoperability-critical resource path.The SDK therefore does not yet deliver the intended “SDK-managed polling, deduplication, file retrieval, validation, and retries” experience.
What adopters must currently reinvent
ReportingObservationneeded for a receipt.Our seller/buyer vertical slice had to implement this callback manually before it could prove that both parties shared the same billing totals.
Proposed SDK surface
ReportingResourceReaderand credential provider.Related protocol/implementation PRs: adcontextprotocol/adcp#6953 and #6953's Python implementation in #1095.