feat(billing): surface claim-backed effective plan status

[seonghobae]

Buyer/access outcome

Refs #488. This Draft child of #565 closes the buyer-visible inconsistency where claim-backed Pro authorization can lift project/member limits while /api/orgs/:id/billing still reports the stored Free plan and the team UI continues offering an upgrade action.

Exact current stack

• exact parent/base feat(billing): apply claim-backed effective plan limits #565: feat/stripe-entitlement-effective-plan-488@c9d21ade938bb7eaba89a37a271bb5eed464c17a;
• exact contributor head: 6fcbaa4b85d70d7b7b98bc85e977a25624df32f1;
• exact parent→child comparison: ahead-only, zero behind, exact parent as merge base, six changed paths;
• state: Draft and mechanically mergeable.

The current head is a non-destructive two-parent reconciliation of predecessor child 258c4687aa1872ef196caceeadc316101a8cca92 with exact current #565. It starts from the repaired effective-plan parent tree and overlays only this slice's six billing-status paths, preserving #564's composite claim-head tenant-integrity constraint and #565's current authorization behavior.

Any parent/head movement invalidates this ancestry statement until freshly reconciled.

Public status contract

server/app.mjs binds the bootstrapped server-owned billing database before public plan-status requests, preserving the same claim authority used by resource-limit checks. Successful /api/orgs/:id/billing responses are normalized so:

• plan names the effective authorization plan currently governing product limits;
• storedPlan separately preserves the durable/manual orgs.plan value for audit and operator diagnosis;
• effective plan identity is accepted only when the legacy route's bounded planName, priceKrw, and complete project/member limits match one known PLANS catalog entry;
• the public adapter accepts no browser-selected claim, decision, Subscription, or Invoice identity; and
• revoked/expired claims immediately return buyer-visible status to Free while explicit stored Pro remains a non-Stripe override.

The API regression uses the real in-memory ScopeWeave billing schema and current entitlement evidence rather than a response-only stub. Unit/package contracts keep the normalizer and API regression in the canonical test paths.

Inherited tenant-integrity repair

Parent #564 now makes billing_stripe_entitlement_claim_heads(subscription_id, decision_id) reference the exact same pair on billing_stripe_entitlement_decisions, preventing a head for one Subscription from consuming another Subscription's entitlement decision. A focused Node DatabaseSync reproduction is GREEN for rejection of cross-Subscription rebind and success of a same-Subscription head advance. This child inherits that exact schema and regression through #565.

Current exact-head evidence

Fresh repository-native workflows for exact head 6fcbaa4b85d70d7b7b98bc85e977a25624df32f1 are queued and therefore non-passing:

• Server Tests 32345893910;
• Dependency Review 32345893874; and
• OSV Scanner 32345894148.

There are no submitted reviews or review threads on this exact head. No predecessor-head, queued, absent, synthetic, status-only, author-only, or model-only evidence is treated as approval.

Scope boundary

This slice surfaces buyer-visible billing truth only. It does not mutate orgs.plan, change authentication or membership/RBAC, issue capabilities, or complete the remaining #488 operator recovery, out-of-order convergence, retention/export, and release-acceptance work.

Remain Draft. Do not integrate independently of #565/#564 and their prerequisite stack. Hosted exact-head deterministic/browser/coverage/security/dependency/supply-chain/review evidence must be terminal and current before integration.

[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: 3d53d40f-8ed8-48d4-8538-158f1a87c5b8

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