feat(billing): project current authoritative subscription observations

[seonghobae]

Buyer/data-integrity objective

Refs #488. This Draft is stacked on #526 and implements a tenant-scoped, read-only projection over accepted authoritative Stripe Subscription observations. It selects current state by explicit local append order, retains ordered Price and source-event provenance, enforces organization isolation, returns immutable values, and never mutates orgs.plan or otherwise infers entitlement.

Stripe webhook arrival order remains non-authoritative. The preceding stack owns provider verification and append-only persistence; this PR only projects already accepted observations.

Exact current stack

Current parent/base: #526 feat/stripe-subscription-observation-ledger-488@b3510f99c79f6994b58902cb5dcb1e7501ee5844.
Current contributor head: f047cd4229aa3d0bdb94eec0155ddda4b21e784a.

Fresh parent→child comparison is ahead-only, 12 commits ahead, zero behind, and has the exact current parent as merge base. The effective delta is exactly six projection/evidence files: CHANGELOG.md, projection doctoring, package.json, server/stripe_subscription_current_projection.mjs, the coverage contract, and the focused projection regression.

Any parent or contributor-head movement invalidates this ancestry statement until freshly reconciled.

Projection contract

• selects newest accepted observation by explicit append identity rather than webhook arrival or provider wall-clock alone;
• preserves ordered Price membership and source-event provenance;
• enforces organization isolation and canonical positive decimal tenant authority before SQL lookup;
• rejects ambiguous tenant spellings such as whitespace, +42, hexadecimal, exponent notation, and leading zeroes;
• returns immutable values;
• never mutates orgs.plan or grants entitlement;
• preserves absence and missingness rather than inventing current state; and
• locks the module and focused suite into the canonical owned-production coverage path.

TDD and reconciliation evidence

The behavior contract preceded the production module. Tenant authority normalization was tightened test-first after current-source review. The branch has since been reconciled non-destructively through multiple parent movements; current exact ancestry is the live parent/head pair above, not the historical SHAs previously recorded in this PR body.

Current exact-head CI/security/review evidence must be freshly classified. Predecessor-head cancellations, successes, model judgments, and reviews are historical and non-authorizing.

Documentation and integration boundary

docs/doctoring/stripe-subscription-current-projection.md records the active-PR/shipped-truth boundary, security and entitlement separation, rollback, test evidence, and primary Stripe/SQLite references. CHANGELOG.md records active Unreleased behavior without claiming protected integration.

Do not merge independently of #526/#525 or the preceding #488 stack. Final integration also requires protected-shipped #523 exact-contributor-head execution attestation (or equivalent), fresh exact-head deterministic/browser/coverage/security/dependency/supply-chain/package/provenance evidence, resolved valid findings, and qualifying independent non-author approval under the live rules.

Pending, queued, skipped-required, cancelled, absent, neutral-required, failed, stale, predecessor, synthetic, status-only, or model-only evidence is non-passing.

[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: 6659d329-b937-4ec2-af7b-40475accf585

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