feat(billing): add auditable Checkout reconciliation operations

[seonghobae]

Buyer and operability impact

This bounded stacked #488 slice removes the direct-database-intervention dead end left by reconciliation_required Checkout attempts. It gives an authorized operator adapter a tenant-scoped, credential-safe inspection boundary, an alertable backlog count, and an atomic audited resolution primitive that unblocks Checkout only after authoritative provider evidence has been verified.

Exact current stack and scope

• Current parent: feat(billing): persist Checkout attempt idempotency #511 feat/stripe-checkout-attempt-ledger-488@2743a58c9ac65ab125c3898ec94370a7dc91f095.
• Current child head: 985747c4ed3dc369ee85df48f4923f5050c11209.
• The child is a non-destructive two-parent reconciliation of predecessor child 403c493ac914ab6a397d9504541978c037d6a733 and exact current parent 2743a58c9ac65ab125c3898ec94370a7dc91f095.
• Fresh exact parent→child comparison is ahead-only, zero behind, with the exact parent as merge base and exactly eight reconciliation-scope paths:
  • docs/doctoring/stripe-checkout-reconciliation-operations.md;
  • package.json;
  • server/billing_checkout_attempt.mjs;
  • tests/unit/billing-checkout-attempt.test.mjs;
  • tests/unit/billing-checkout-reconciliation-authority.test.mjs;
  • tests/unit/billing-checkout-reconciliation.test.mjs;
  • tests/unit/billing-checkout-review-regressions.test.mjs;
  • tests/unit/coverage-script-contract.test.mjs.
• The semantic package merge preserves the exact parent’s OpenCode, changelog, contextual-orchestrator attribution/routing, durable-attempt, provider-boundary, toast-accessibility, and cloud-E2E registrations while adding both reconciliation regressions to canonical unit and c8 execution.
• The active-PR doctoring document now names the exact current parent instead of a superseded stack revision.

No auth/session, Clearfolio, attachment, workflow, dependency lockfile, scanner suppression, or branch-protection artifact is changed by the effective child diff.

Implemented reconciliation contract

• adds normalized billing_checkout_reconciliation_events audit state linked to the held attempt and resolving user without copying idempotency keys, secrets, tokens, or credential hashes;
• adds countReconciliationRequired for internal alert/health adapters;
• exposes tenant-filtered safe inspection metadata that never reveals provider retry authority;
• adds tenant-scoped resolveReconciliation for authoritative provider_succeeded or provider_failed outcomes with bounded evidence references;
• makes the state transition and audit insert one SQLite savepoint, so invalid or missing audit authority rolls the attempt back to the held state;
• preserves monotonic timestamps across clock rollback;
• requires a provider session ID only for authoritative success;
• rejects cross-tenant inspection/resolution, malformed identifiers, invalid evidence references, impossible outcomes, and unaudited release; and
• retains normalized schema, foreign-key integrity, credential non-disclosure, and realistic SQLite behavior regressions.

Security and authority boundary

This persistence port does not decide who is an operator and does not treat caller assertions as provider truth. HTTP/service adapters must enforce owner/admin authorization and verify evidence against authoritative Stripe or signed-webhook state before invoking resolution. No self-service or unverified release route is introduced.

Stack repair evidence

The previous child was based on predecessor parent 0b0a9373870860a18ba5fc5f36d660f72354a34b and had diverged after #511 moved. The current repair starts from the exact parent tree, overlays only the eight child-owned paths, and semantically merges package.json. The resulting exact parent→child comparison is zero-behind with no unintended deletion of current parent test, coverage, auth, attachment, Clearfolio, orchestrator, provider, or operability behavior.

Current exact-head evidence

Fresh repository-native workflows for exact child head 985747c4ed3dc369ee85df48f4923f5050c11209 are queued and therefore non-passing:

• Server Tests 32268962547;
• Dependency Review 32268962558; and
• OSV Scanner 32268963156.

The predecessor-head Server Tests, Dependency Review, and OSV successes are diagnostic history only. No formal reviews or inline review threads currently exist on this PR, and no qualifying independent current-head approval exists. Queued, pending, cancelled, skipped-required, neutral, absent, stale, predecessor, status-only, synthetic-only, author-only, or model-only evidence is non-passing.

This PR remains Draft and must not integrate independently of #511, #507, and #505.

Scope boundary

This PR does not yet wire the operator HTTP adapter, expose the backlog count on /api/metrics, verify Stripe webhook signatures, or implement subscription entitlement reconciliation. Those remain bounded #488 follow-on work.

Merge gate

After the prerequisite stack reaches protected develop, reconcile this exact bounded semantic diff onto the resulting live head and rerun every then-applicable CI, browser E2E, coverage/docstring, SAST, security, dependency, supply-chain, package/provenance, migration/recovery, resolved-thread, and qualifying independent-approval gate actually required by live policy. No predecessor-head, author-only, skipped, neutral, status-only, synthetic, or model-only evidence transfers.

Refs #488

[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: bc106d97-1ec0-4c01-acd3-9e45c91d79e0

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

[seonghobae]

@coderabbitai review

[coderabbitai]

⚠️ Action not completed

Review rate limited.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.