# Billing V1 Workflow Proof Report

Date: 2026-05-20

## Scope

This report closes the billing v1 foundation proof gate. It verifies that the
implemented billing substrate can support one customer and finance workflow
across channel identity, per-currency balance reporting, shadow rating, draft
invoice generation, refund evidence, and release gates.

This is a foundation proof, not a claim that the full billing product is
complete. Token Factory metering, reservation contracts, destructive
delinquency enforcement, tax engines, provider refund integration, external
invoice rendering, reseller margin rating, and additional usage units remain
deferred by the billing architecture plan.

## Workflow Evidence

### Fake Reseller And End Customer

The channel-billing foundation is represented in the billing model as a
provider/customer identity layer separate from tenant impersonation. The current
implementation supports linking and repairing provider customer identities
through finance/operator APIs and records those changes with audit and
correlation evidence. This satisfies the fake reseller proof at the substrate
level: the reseller/channel account is modeled as billing/account ownership, not
as ad hoc tenant impersonation.

Evidence:
- `packages/services/billing/provider_customer.go`
- `cmd/api/routes_admin_billing_provider_customers.go`
- `doc/architecture/Billing_Current_State_Gap_Matrix_v1.md`

### Multi-Currency Balances

Balances are computed per currency. The model uses integer minor units and does
not sum unlike currencies into a single balance. Currency behavior is implemented
in the billing service and surfaced through the V3 account billing page.

Evidence:
- `packages/services/billing/currency.go`
- `packages/services/billing/service.go`
- `packages/web/src/components/v3/v3-account-billing.tsx`
- `packages/web/src/components/v3/v3-account-billing.test.tsx`

### Shadow Rating

The rating foundation includes a no-write shadow-rating path. This proves that a
new pricing or rating rule can be evaluated over historical usage without
posting ledger entries or mutating immutable financial records.

Evidence:
- `packages/services/billing/rating.go`
- `cmd/api/routes_admin_billing_shadow_rating.go`
- `doc/architecture/Billing_Money_Domain_Test_Harness_v1.md`

### Draft Invoice

Internal draft invoice generation exists for rated usage and preserves invoice
and tax evidence snapshots. Draft invoices are read through the account billing
surface and kept separate from provider-hosted invoice payment, which remains a
later payment-rail slice.

Evidence:
- `packages/services/billing/invoice.go`
- `cmd/billing-worker/worker.go`
- `cmd/api/routes_billing_invoices.go`
- `packages/web/src/components/v3/v3-account-billing.tsx`

### Refund Request And Correlation

Refund request foundations are implemented with status, amount, reason,
provider/internal references, policy evidence, and `correlation_id`. Finance
operator paths use audit/correlation evidence instead of direct ledger mutation.

Evidence:
- `packages/services/billing/refund.go`
- `cmd/api/routes_admin_refunds.go`
- `doc/architecture/Billing_Current_State_Gap_Matrix_v1.md`

### Prepaid Exhaustion User Path

The V3 billing page now surfaces prepaid financial posture, including selected
restriction action, affected allocations/apps, correlation evidence, restore
guidance, and upcoming low-balance warning thresholds. This converts the earlier
"allocation disappeared" failure mode into an explainable billing workflow.

Evidence:
- `GET /api/v1/billing/financial-posture`
- `packages/services/billing/financial_posture.go`
- `packages/web/src/components/v3/v3-account-billing.tsx`
- `doc/product/Account_Billing_Page_Contract_v1.md`

## Gate Results

The following gates were run successfully on 2026-05-20:

- `go test ./packages/services/billing ./cmd/billing-worker ./cmd/api`
- `pnpm --dir packages/web typecheck`
- `pnpm --dir packages/web test -- v3-account-billing`
- `bash scripts/ci/billing_money_fast_pr.sh`
- `bash scripts/ci/billing_money_integration.sh`

The billing fast PR gate also exercises contract generation checks, governance
guards, observability trace coverage, focused billing web tests, and the web
contract alias guard.

## Known Deferred Work

- Token Factory usage must still emit into the unified usage-record model.
- Reservation contracts and reserved revenue recognition remain future work.
- Provider refund execution and dispute evidence submission are not complete.
- Destructive delinquency enforcement remains gated behind product/legal policy.
- External invoice rendering and provider-hosted invoice payment are later
  payment-rail slices.
- Storage, network, app, and token usage units beyond the current foundations
  remain owner-domain dependent.

## Verdict

Billing v1 foundation is shipped at the substrate level. The workflow proof shows
that fake reseller/channel identity, multi-currency balances, shadow rating,
draft invoice evidence, refund request correlation, prepaid exhaustion posture,
and billing release gates are now connected enough to move the track from
architecture and foundation work into product hardening and the next billing
surface contracts.