feat(billing): charge service fees on Kilo Pass

[jeanduplessis]

Summary

Activates service fees for personal and organization Kilo Pass Checkout and Stripe-advanced invoices while excluding seat value.

Why this change is needed

Kilo Pass billing is more complex than top-ups: subscriptions renew, upgrades prorate, organizations can mix seats and Kilo Pass on one invoice, and Checkout promotions can proportionally discount the fee line. The implementation must charge one fee on eligible Kilo Pass value without changing entitlements or charging seats.

How this is addressed

• Add the fee to personal Kilo Pass Checkout and recurring or immediate invoices.
• Add the fee to organization Kilo Pass Checkout, renewals, and seat-capacity changes.
• Classify mixed invoices so seat lines never enter the fee base.
• Net eligible positive and negative prorations before applying aggregate minor-unit rounding.
• Read the charged fee from the settled Stripe line and record rate deviations instead of issuing corrective charges.

Stack: #5236 → #5262 → #5263 → #5264 → #5265 (this PR) → #5266.

Human Verification

No new product or browser verification was performed while publishing this PR. The completed local validation run covered standard, 20%-discount, and 100%-discount Personal Kilo Pass Checkout; organization Kilo Pass with existing seats; seat-capacity changes; and seat-only exclusion.

Reviewer Notes

Human Reviewer Flags

• The fee line is discountable in hosted Checkout. expected_fee_minor and charged_fee_minor can therefore differ legitimately.
• A 100% promotion can produce a successful charged outcome with zero settled product and zero settled fee.
• Product-restricted coupons are detected as an operational defect signature; the system alerts but never silently creates a corrective charge or refund.
• Mixed seat/Kilo Pass invoices calculate the fee from Kilo Pass value only.

Code Reviewer Agent

Code Reviewer Notes

• Review proration netting and line classifiers before individual route wiring.
• Organization seat-capacity updates can invoice immediately and therefore participate in the same assessment lifecycle.
• Entitlements remain based on product lines, not gross collected cash.

[kilo-code-bot]

Code Review Summary

Status: 2 Issues Found | Recommendation: Address before merge

Executive Summary

The leftover-key renewal skip is fixed, but attach now deletes the staged fee after Stripe has already applied it to draft invoices, then records the assessment as charged.

Overview

Severity	Count
CRITICAL	1
WARNING	1
SUGGESTION	0

Issue Details (click to expand)

CRITICAL

File	Line	Issue
apps/web/src/lib/kilo-pass-org/stripe-adapter.ts	606	Deleting the staged invoice item after detecting it on the invoice removes the fee from draft invoices

WARNING

File	Line	Issue
apps/web/src/lib/kilo-pass-org/stripe-adapter.ts	715	A failed pending-item list skips fee staging instead of creating the item

Files Reviewed (6 files)

• apps/web/src/lib/kilo-pass-org/stripe-adapter.ts - 2 issues
• apps/web/src/lib/kilo-pass-org/stripe-adapter.test.ts - 0 issues
• apps/web/src/lib/stripe/index.ts - 0 issues
• apps/web/src/lib/stripe/index.test.ts - 0 issues
• apps/web/src/routers/kilo-pass-router.ts - 0 issues
• apps/web/src/routers/kilo-pass-router.test.ts - 0 issues

Fix these issues in Kilo Cloud

Previous Review Summary (commit 37349ab)

Current summary above is authoritative. Previous snapshots are kept for context only.

Previous review (commit 37349ab)

Status: 4 Issues Found | Recommendation: Address before merge

Executive Summary

Checkout and seat-capacity writes persist one-shot serviceFeeAssessmentKey values onto long-lived subscriptions, so invoice.created skips every later Kilo Pass renewal.

Overview

Severity	Count
CRITICAL	2
WARNING	2
SUGGESTION	0

Issue Details (click to expand)

CRITICAL

File	Line	Issue
apps/web/src/routers/kilo-pass-router.ts	1221	Writes checkout serviceFeeAssessmentKey onto subscription_data.metadata; renewals inherit it and invoice.created skips the fee
apps/web/src/lib/kilo-pass-org/stripe-adapter.ts	1127	Same leftover-key write for org checkout (org-checkout:<uuid>)
apps/web/src/lib/stripe/index.ts	2248	Same leftover-key write for seat-capacity updates (seat-capacity:...)
apps/web/src/lib/kilo-pass-org/stripe-adapter.ts	624	Attach discards the staged pending fee, then marks missed on non-draft invoices when latest_invoice.lines is not expanded

WARNING

File	Line	Issue
apps/web/src/lib/kilo-pass-org/stripe-adapter.ts	409	Pending assessments are re-prepared and re-staged, so a same-second retry can put two customer-scoped fee items on one invoice
apps/web/src/lib/kilo-pass-org/stripe-adapter.ts	1157	Prepare-failure fallback attaches via invoice: while invoice.created can attach the same draft, racing a second fee

Files Reviewed (7 files)

• apps/web/src/lib/kilo-pass-org/stripe-adapter.ts - 4 issues
• apps/web/src/lib/kilo-pass-org/stripe-adapter.test.ts - 0 issues
• apps/web/src/lib/stripe/index.ts - 1 issue
• apps/web/src/lib/stripe/index.test.ts - 0 issues
• apps/web/src/lib/stripe-3ds.test.ts - 0 issues
• apps/web/src/routers/kilo-pass-router.ts - 1 issue
• apps/web/src/routers/kilo-pass-router.test.ts - 0 issues

Fix these issues in Kilo Cloud

---

_{Reviewed by grok-4.6 · Input: 397.5K · Output: 71.7K · Cached: 2M}

_{Review guidance: REVIEW.md from base branch transaction-service-fee-4-top-ups}

[jeanduplessis]

Addressed the latest Kilo review summary in f7b5df8ae: service-fee assessment keys are no longer written to long-lived personal/org subscription metadata; seat updates expand invoice lines; staged fee items are reused by assessment key and orphan stages are discarded; and prepare-failure fallback attachment is left exclusively to invoice.created to avoid a duplicate-attach race. Added/updated regression coverage for renewal-safe metadata, pending-item reuse, overlap handling, and seat-capacity attachment.