feat(billing): reconcile Stripe state from current provider authority

[seonghobae]

Buyer/reliability objective

Refs #488. This stacked Draft adds the bounded orchestration boundary needed for out-of-order Stripe deliveries to trigger current provider reconciliation rather than becoming lifecycle authority themselves.

Exact current stack

• protected develop: 2dcbdc06d3a9e2f87eac42447338e7fcc523dd54;
• exact parent/base feat(billing): surface claim-backed effective plan status #568: feat/stripe-entitlement-billing-status-488@6fcbaa4b85d70d7b7b98bc85e977a25624df32f1;
• exact contributor head: 3e95927c2b28a2b73c2b589c53fdd74a95b01d2a;
• state: Draft and mechanically mergeable;
• no submitted review or inline review thread exists on this exact head.

Any parent, contributor-head, or protected-base movement invalidates ancestry- and head-sensitive evidence until freshly reconciled.

Implemented current-authority contract

server/stripe_billing_reconciliation.mjs now:

• validates local tenant/Subscription authority and required dependency ports before provider I/O;
• fetches the current authoritative Subscription on every trigger, so webhook event identity is optional provenance only and never ordering authority;
• appends the accepted Subscription observation, then validates the persistence receipt is still bound to the exact accepted Subscription before its identity can cross the service boundary;
• when latest_invoice_id exists, fetches the authoritative Invoice using exact organization/Customer/Subscription/Invoice authority and appends it against the just-accepted Subscription observation;
• validates the Invoice persistence receipt against the exact Invoice identity and exact source Subscription observation, preventing a buggy adapter from substituting another durable evidence identity;
• evaluates the durable entitlement claim only after provider evidence persistence;
• validates identity-bearing current and newly applied claim results against the requested organization and Subscription;
• tolerates one optimistic claim-head conflict by refreshing the current durable decision and retrying claim application only, without repeating provider reads or accepted evidence writes;
• propagates a second claim conflict and all non-conflict causal failures; and
• returns only bounded evidence/decision identifiers, never provider payloads, secrets, retry authority, orgs.plan mutation, session state, or RBAC mutation.

TDD and causal hardening

• test-only commit 25fa45155c754e54ce63a96a8a8bd43f0b6ae2e3 added realistic regressions proving Subscription, Invoice/source-observation, and claim identity substitution must fail closed;
• 7cea2f780554ccb4568bb9d9a2d56a67faac53f3 wired that regression into an already-executed package-contract path so the RED evidence could not be vacuous; and
• current production head 3e95927c2b28a2b73c2b589c53fdd74a95b01d2a implements the smallest root-cause fix by treating repository return values as untrusted port data and re-binding their identities before they enter the reconciliation receipt or downstream claim application.

The original module-resolution RED predecessor is historical diagnostic evidence only; this PR is no longer intentionally RED.

Current exact-head evidence

Fresh repository-native workflows for exact contributor head 3e95927c2b28a2b73c2b589c53fdd74a95b01d2a currently remain queued and therefore non-passing:

• Server Tests 32361538176;
• Dependency Review 32361538188; and
• OSV Scanner 32361538771.

There is 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 and merge boundary

This slice does not by itself close #488. It provides the current-provider reconciliation service boundary over the preceding authoritative Subscription/Invoice evidence and durable claim layers; operator recovery, end-to-end deployment/restart/concurrency acceptance, retention/export controls, and release evidence remain broader lifecycle work.

Remain Draft. Do not integrate independently of #568 and its prerequisite #488 stack. After the prerequisite stack reaches protected develop, reconcile this bounded semantic delta onto the resulting live head and regenerate every then-applicable exact-head deterministic/browser/statement/branch/function/line coverage/docstring/SAST/security/dependency/supply-chain/package/provenance/migration/recovery/review gate required by live policy.

[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: a31a26c9-8b23-4397-9f6b-a3d66da25ca1

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