feat(billing): project current Stripe invoice evidence

[seonghobae]

Buyer/data-integrity objective

Refs #488. This Draft child of #562 exposes a tenant-scoped read-only projection over accepted authoritative Stripe Invoice observations so the entitlement-policy layer can consume one explicit current payment fact without consulting webhook arrival order or mutable provider/wall-clock timestamps.

Exact current stack

• protected develop: df0fa17bd5035af6455c889022c540b4f439e3d6;
• exact parent/base feat(billing): persist authoritative Stripe invoice observations #562: feat/stripe-invoice-observation-ledger-488@2d6b55a214e2b62a034adbe06282d135812ef610;
• exact contributor head: 50c1a4005d8fcd408ccdbd49672204d571df37e3;
• exact parent→child comparison: ahead 4, behind 0, exact parent as merge base, six changed paths, +370/-3;
• CHANGELOG.md +4/-0.

TDD and focused evidence

Test-only commit ca90045244d1ae5dba71b612ddfa8df20a725181 introduced the projection regression before the production module existed. Production commit f56daa783f28e51f28e61d5899e2109b112d765b implemented the read-only projection; follow-up commit 843ac4ad295e5c13217cb5f12321508b8112cdd1 locked its source/test registration through a focused package contract, and 50c1a4005d8fcd408ccdbd49672204d571df37e3 recorded active Unreleased behavior.

Private focused execution passed all six projection subtests and produced 100% line / 100% branch / 100% function coverage for server/stripe_invoice_current_projection.mjs and its focused suite.

Projection contract

• selects the current accepted Invoice observation by highest append-only observation_id, not webhook receipt, provider creation/paid time, or local wall-clock timestamp;
• scopes every read through Invoice → Subscription → Customer → organization;
• rejects non-canonical tenant spellings and malformed bounded Invoice/Subscription filters before SQL use;
• getCurrentInvoice returns one immutable current payment fact or null for absent/foreign authority;
• listCurrentInvoices returns one immutable latest observation per tenant-owned Invoice, with optional Subscription narrowing;
• preserves exact source Subscription observation and optional verified event provenance; and
• performs no schema mutation, orgs.plan mutation, entitlement claim write, or access grant/revoke.

Scope boundary

This slice does not persist entitlement claims or apply authorization. Transactional claim/audit persistence, reversible grant/revoke application, operator recovery, and end-to-end out-of-order convergence remain subsequent #488 work.

Remain Draft. Do not integrate independently of #562 and its prerequisite stack. Hosted exact-head deterministic/browser/coverage/security/dependency/supply-chain/review evidence must be regenerated on the unchanged final head.

[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.

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: c0cc0a99-3699-48c8-b1fe-ac6465cea9ef

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

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

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

[coderabbitai]

Caution

Review failed

An error occurred during the review process. Please try again later.

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

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