feat(billing): persist authoritative Stripe invoice observations

[seonghobae]

Buyer/data-integrity objective

Refs #488. This Draft child of #561 persists accepted authoritative Stripe Invoice reads as normalized append-only evidence before any later entitlement claim/application layer. It binds each Invoice permanently to one Subscription and requires the exact accepted Subscription observation that named the Invoice, preserving tenant, Customer, Subscription, and Invoice authority without copying raw provider payloads or entitlement state into the ledger.

Exact current stack

• protected develop: df0fa17bd5035af6455c889022c540b4f439e3d6;
• exact parent/base feat(billing): fetch authoritative Stripe invoice state #561: feat/stripe-invoice-authoritative-read-488@e26164934ddbe7417635b6839e78adf29f6d6197;
• exact contributor head: 2d6b55a214e2b62a034adbe06282d135812ef610;
• exact parent→child comparison: ahead 2, behind 0, exact parent as merge base, seven changed paths, +584/-3;
• CHANGELOG.md +5/-0 and coverage contract +15/-0;
• mechanically mergeable and still Draft.

TDD and focused evidence

Test-only commit fc98edc4fab146bddd918923236a3254d45df291 added tests/unit/stripe-invoice-observation-ledger.test.mjs while the production module did not exist, establishing a realistic RED module-resolution failure. Implementation commit 2d6b55a214e2b62a034adbe06282d135812ef610 added the normalized repository, bootstrap registration, package/coverage integration, doctoring, and additive changelog evidence.

Private focused execution passed all eight ledger subtests and produced 100% line / 100% branch / 100% function coverage for server/stripe_invoice_observation_ledger.mjs. Hosted exact-head CI/security/dependency/review evidence remains authoritative for integration.

Normalized persistence contract

• billing_stripe_invoices stores one Invoice identity permanently bound to one existing Stripe Subscription;
• billing_stripe_invoice_observations appends accepted payment facts and references the exact source_subscription_observation_id that named the Invoice;
• optional verified webhook-event provenance is retained as a foreign key but never used as ordering or entitlement authority;
• organization and Customer identity are not duplicated in the Invoice table because the existing Subscription → Customer → organization relations determine them;
• exact organization, Customer, Subscription, and latest_invoice_id equality is rechecked before any write;
• Invoice rebinding, unknown provenance, malformed lifecycle/arithmetic, and ambiguous local authority fail closed;
• repeated reads append and per-Invoice local observed_at_ms never moves backwards under wall-clock rollback; and
• the savepoint cleanup path releases only after a confirmed rollback, preventing cleanup failure from committing partial evidence or replacing the causal operation error.

Current exact-head evidence

Fresh repository-native workflows for unchanged head 2d6b55a214e2b62a034adbe06282d135812ef610 are queued and therefore non-passing:

• Server Tests 32278332109;
• Dependency Review 32278330847; and
• OSV Scanner 32278331894.

There are no submitted reviews or review threads on this exact head and no qualifying independent current-head approval. Queued, pending, skipped-required, cancelled, absent, neutral-required, failed, stale, predecessor, synthetic, status-only, author-only, or model-only evidence is non-passing.

Scope boundary

This slice does not project current Invoice state, persist entitlement claims, mutate orgs.plan, or grant/revoke access. Current Invoice projection, transactional claim/audit persistence, reversible entitlement application, operator recovery, and end-to-end out-of-order convergence remain subsequent #488 work.

Remain Draft. Do not integrate independently of #561 and its prerequisite stack. Exact-head hosted 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: 3673ca3a-ee15-4088-9efd-c4b8bde74abb

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

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