[DanGould]

Audit and rename error types for issue payjoin#749

Summary

• Rename EncapsulationError to DecapsulationError (and internal types)
• Document duplication and naming issues across SessionError,
  CreateRequestError, and the former EncapsulationError

What changed

EncapsulationError was a misnomer: it is exclusively raised when
decapsulating responses (process_response), never during request
encapsulation (create_v2_post_request / create_poll_request, which
produce CreateRequestError). Renamed to DecapsulationError throughout
core and FFI crates, including the InternalValidationError::V2Encapsulation
variant (now V2Decapsulation).

Audit findings

Error type inventory

Type	Location	Variants
InternalCreateRequestError	send v2	Url, Hpke, OhttpEncapsulation, Expired
InternalDecapsulationError (was InternalEncapsulationError)	send v2	Hpke, DirectoryResponse
InternalSessionError	receive v2	ParseUrl, Expired, OhttpEncapsulation, Hpke, DirectoryResponse

Duplication between send and receive error types

InternalSessionError is a superset containing all variants from both
InternalCreateRequestError and InternalDecapsulationError:

Variant	CreateRequest	Decapsulation	Session
Url / ParseUrl	Url	-	ParseUrl
Hpke	x	x	x
OhttpEncapsulation	x	-	x
Expired	x	-	x
DirectoryResponse	-	x	x

Issues requiring maintainer decisions

1. Cross-side deduplication: InternalCreateRequestError and
   InternalSessionError have nearly identical variant sets but serve
   different sides of the protocol (send vs receive). Collapsing them
   requires architectural decisions about shared error types.

2. Decapsulation/Session subset: InternalDecapsulationError is a
   strict subset of InternalSessionError (Hpke + DirectoryResponse).
   Could potentially reuse a shared type.

3. Inconsistent variant naming: Url (send) vs ParseUrl (receive)
   for the same semantic concept (into_url::Error).

4. Hpke variant placement: The Hpke variant in DecapsulationError
   represents HPKE decryption (a distinct crypto operation from OHTTP
   decapsulation). May belong at a different level.

5. process_response return type asymmetry: Send POST returns
   DecapsulationError, send GET returns ResponseError. The asymmetry
   may be intentional (POST only confirms acceptance; GET retrieves and
   validates a full proposal).

Test plan

• cargo clippy --all-targets --keep-going --all-features -- -D warnings
• cargo fmt --all -- --check
• codespell
• nix fmt -- --ci

Disclosure: co-authored by Claude

[coveralls]

Pull Request Test Coverage Report for Build 22572326812

Details

• 1 of 11 (9.09%) changed or added relevant lines in 3 files are covered.
• 1 unchanged line in 1 file lost coverage.
• Overall coverage remained the same at 82.484%

---

Changes Missing Coverage	Covered Lines	Changed/Added Lines	%
payjoin/src/core/send/error.rs	0	2	0.0%
payjoin/src/core/send/v2/error.rs	0	3	0.0%
payjoin/src/core/send/v2/mod.rs	1	6	16.67%

Files with Coverage Reduction	New Missed Lines	%
payjoin/src/core/send/v2/error.rs	1	15.63%

Totals
Change from base Build 22572195695:	0.0%
Covered Lines:	10624
Relevant Lines:	12880

---

💛 - Coveralls

[coderabbitai]

Important

Review skipped

Draft detected.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch session4/issue-749

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[DanGould]

replaced by payjoin#1601