feat(types): Account v3 projection helpers (billing_entity write-only bank-details guard, reporting_bucket)

[bokelley]

Summary

Spec 3.0.x adds billing_entity (B2B invoicing entity, bank details write-only — MUST NOT serialize on response) and reporting_bucket. Need projection helpers so adopters don't accidentally leak bank details on read.

Design

Bank-details guard

Two options — pick one during implementation:

1. Pydantic model_validator on the Account type that strips billing_entity.bank_details on response serialization
2. Separate AccountResponse projection type with bank details omitted from the model entirely

Option 2 is more explicit and harder to misuse — leaning that way pending discussion.

Migration

Alembic migration template for adopters with existing Account tables to add the new columns:

• billing_entity (JSON column or normalized table)
• reporting_bucket (string column)

Why this matters

Prevents the bank-details-on-read leak that's easy to miss during adopter implementation. The spec is clear that bank details are write-only, but Pydantic's default serialization round-trips everything.

Cross-references

• RFC: docs/proposals/v3-identity-bundle-design.md

🤖 Generated with Claude Code

[bokelley]

Triage

Classification: Feature request (protective — prevents financial PII leakage)
Bucket(s): validation, client (no matching labels exist in repo — gap flagged)
Status: ready-for-human
Milestone: omit

What the experts said:

• security-reviewer: Option 1 (model_validator) has multiple silent bypass paths — model_copy(), direct BusinessEntity serialization, idempotency cache. Option 2 is structurally correct. Also: sync_accounts_response.py defines its own Account type that needs the same guard — not just core/account.py's Account. The request_snapshot = req.model_dump() docstring example silently prescribes writing IBAN/routing numbers into adopter stores; that needs a note or fix independently.
• ad-tech-protocol-expert: bank is a hard MUST NOT per the spec ("writeOnly": true in the JSON Schema + prose in every bundled response schema). Correction to issue: reporting_bucket is NOT write-only — it's a seller-provisioned field buyers actively read to find offline delivery coordinates. Stripping it from an AccountResponse would break the offline-delivery feature. Only billing_entity.bank needs the guard.
• code-reviewer: Option 2 is cleanly achievable via a new projections.py under the existing type-layer convention — BusinessEntityResponse subclasses BusinessEntity with bank: None = None; AccountResponse wraps it. No generated-file edits needed. Four behavioral tests needed (none exist today).

My take: Three experts converge on Option 2 (projection type). The change is non-breaking, but it touches financial PII (IBAN, BIC, routing/account numbers) so human sign-off is appropriate. Two clarifications are needed before implementation: (1) confirm reporting_bucket is intentionally included in AccountResponse (it should be — do not strip it); (2) confirm whether the docstring request_snapshot pattern needs a companion fix in this PR or a separate issue.

Pinging @bokelley.

---

Triaged by Claude Code. Session: https://claude.ai/code/session_019z2Ssr1dspWVWunzQBJJMj

---

Generated by Claude Code