feat(admin): add service fee controls and reporting

[jeanduplessis]

Summary

Adds organization exemption controls, fee-aware revenue reporting, and read-only rollout audits for the completed service-fee implementation.

Why this change is needed

The fee cannot be operated safely from Stripe alone. Platform admins need reasoned, historical organization exemptions; finance needs product and fee revenue separated after refunds and disputes; and rollout needs audits for Kilo Pass line classification and unsafe product-restricted coupons.

How this is addressed

• Add an internal organization exemption control with grant/revoke reasons and immutable history.
• Keep exemptions exact-organization, non-inherited, and absent from customer-facing APIs and audit logs.
• Split settled product and fee revenue in admin KPIs, charts, tables, and CSV output.
• Reduce revenue by observed refunds and disputes while exposing missed and exempted fee value separately.
• Add read-only Kilo Pass classification and restricted-coupon audit scripts for release operations.

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

Human Verification

No new product or browser verification was performed while publishing this PR. The completed local validation run covered exemption grant/revoke and access control, non-inheritance, customer-surface privacy, revenue dashboard behavior, a full fee-aware refund, and both audit defect signatures.

Reviewer Notes

Human Reviewer Flags

• Exemption history is internal financial-control data and is intentionally excluded from customer-visible organization audit logs.
• Revenue is recognized from settled assessments, not prepared fee lines, and is adjusted separately for refunds and reversible disputes.
• The audits are read-only by design. They report release blockers but never mutate subscriptions or coupons.
• Production historical-exemption verification and release-environment audit runs remain rollout gates, not claims made by this PR.

Code Reviewer Agent

Code Reviewer Notes

• Exemption decisions are resolved at billing-object creation time and retain the exact history row used.
• Empty and partial admin revenue data are handled explicitly rather than assuming all series exist.
• Audit scripts avoid logging customer contracts, credentials, or unrelated private data.

[kilo-code-bot]

Code Review Summary

Status: No Issues Found | Recommendation: Merge

Executive Summary

This increment rewrites the revenue KPI anti-join to a single-column UNION ALL hash join and paginates Stripe subscription items, resolving both prior warnings with no new issues on the changed lines.

Files Reviewed (3 files)

• apps/web/src/lib/revenueKpi.ts
• apps/web/src/lib/service-fees/kilo-pass-classification-audit-script.test.ts
• apps/web/src/scripts/service-fees/kilo-pass-classification-audit.ts

Previous Review Summaries (3 snapshots, latest commit 598947d)

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

Previous review (commit 598947d)

Status: 2 Issues Found | Recommendation: Address before merge

Executive Summary

This increment only retargets exemption-log and assessment-key wording in plan/ADR docs; the revenue KPI anti-join and Kilo Pass subscription-item truncation warnings remain open on unchanged code.

Overview

Severity	Count
CRITICAL	0
WARNING	2
SUGGESTION	0

Issue Details (click to expand)

WARNING

File	Line	Issue
apps/web/src/lib/revenueKpi.ts	116	Three-column IN anti-join against the settled-assessment CTE cannot use indexes or a hash anti-join over the unfiltered paid credit_transactions scan
apps/web/src/scripts/service-fees/kilo-pass-classification-audit.ts	79	subscription.items.data used without checking has_more; subscriptions with >10 items yield false unclassifiable results and exit 1

Files Reviewed (5 files)

• .plans/service-fees/SPEC.md
• .plans/service-fees/VALIDATION.md
• docs/adr/0004-stripe-service-fee-assessment.md
• apps/web/src/lib/revenueKpi.ts - 1 issue
• apps/web/src/scripts/service-fees/kilo-pass-classification-audit.ts - 1 issue

Fix these issues in Kilo Cloud

Previous review (commit 62a1d45)

Status: 2 Issues Found | Recommendation: Address before merge

Executive Summary

The exemption-history unification is consistent across the admin router, UI, and tests, but the revenue KPI anti-join still risks a quadratic scan on a 60-second dashboard query, and the Kilo Pass audit script still silently truncates Stripe subscription items at 10.

Overview

Severity	Count
CRITICAL	0
WARNING	2
SUGGESTION	0

Issue Details (click to expand)

WARNING

File	Line	Issue
apps/web/src/lib/revenueKpi.ts	116	Three-column IN anti-join against the settled-assessment CTE cannot use indexes or a hash anti-join over the unfiltered paid credit_transactions scan
apps/web/src/scripts/service-fees/kilo-pass-classification-audit.ts	79	subscription.items.data used without checking has_more; subscriptions with >10 items yield false unclassifiable results and exit 1

Files Reviewed (6 files)

• apps/web/src/app/admin/components/OrganizationAdmin/OrganizationAdminServiceFeeExemption.tsx
• apps/web/src/lib/revenueKpi.test.ts
• apps/web/src/lib/revenueKpi.ts - 1 issue
• apps/web/src/routers/organizations/organization-admin-router.test.ts
• apps/web/src/routers/organizations/organization-admin-router.ts
• apps/web/src/scripts/service-fees/kilo-pass-classification-audit.ts - 1 issue

Fix these issues in Kilo Cloud

Previous review (commit 16483ed)

Status: 2 Issues Found | Recommendation: Address before merge

Executive Summary

The exemption UI, admin router endpoints, revenue split, and read-only audits are well structured and well tested, but the new revenue KPI anti-join risks a quadratic scan on a 60-second auto-refreshing dashboard query, and the Kilo Pass audit script silently truncates Stripe subscription items at 10, which can falsely fail the release gate.

Overview

Severity	Count
CRITICAL	0
WARNING	2
SUGGESTION	0

Issue Details (click to expand)

WARNING

File	Line	Issue
apps/web/src/lib/revenueKpi.ts	116	Three-column IN anti-join against the settled-assessment CTE cannot use indexes or a hash anti-join over the unfiltered paid credit_transactions scan
apps/web/src/scripts/service-fees/kilo-pass-classification-audit.ts	79	subscription.items.data used without checking has_more; subscriptions with >10 items yield false unclassifiable results and exit 1

Files Reviewed (20 files)

• apps/web/src/app/admin/api/organizations/hooks.ts
• apps/web/src/app/admin/components/OrganizationAdmin/OrganizationAdminDashboard.tsx
• apps/web/src/app/admin/components/OrganizationAdmin/OrganizationAdminServiceFeeExemption.dialog-state.test.ts
• apps/web/src/app/admin/components/OrganizationAdmin/OrganizationAdminServiceFeeExemption.dialog-state.ts
• apps/web/src/app/admin/components/OrganizationAdmin/OrganizationAdminServiceFeeExemption.tsx
• apps/web/src/app/admin/components/RevenueDailyChart.tsx
• apps/web/src/app/admin/components/RevenueStats.tsx
• apps/web/src/app/admin/revenue/page.tsx
• apps/web/src/app/admin/revenue/revenue-dashboard-status.test.ts
• apps/web/src/app/admin/revenue/revenue-dashboard-status.ts
• apps/web/src/lib/revenueKpi.test.ts
• apps/web/src/lib/revenueKpi.ts - 1 issue
• apps/web/src/lib/service-fees/kilo-pass-classification-audit.test.ts
• apps/web/src/lib/service-fees/kilo-pass-classification-audit.ts
• apps/web/src/lib/service-fees/restricted-coupon-audit.test.ts
• apps/web/src/lib/service-fees/restricted-coupon-audit.ts
• apps/web/src/routers/organizations/organization-admin-router.test.ts
• apps/web/src/routers/organizations/organization-admin-router.ts
• apps/web/src/scripts/service-fees/kilo-pass-classification-audit.ts - 1 issue
• apps/web/src/scripts/service-fees/restricted-coupon-audit.ts

Fix these issues in Kilo Cloud

---

_{Reviewed by grok-4.6 · Input: 151.8K · Output: 9.3K · Cached: 537K}

_{Review guidance: REVIEW.md from base branch transaction-service-fee-5-kilo-pass}