# Billing Ledger Contract Fixtures

Machine-readable product, accounting, provider, tax, and operator-control vectors for the PDF2HTML billing boundary. Hosts compose `@platform-modules/billing`, `@platform-modules/ledger`, and transactional persistence; these fixtures define the observable contract.

## Exact-value and identity rules

All quantities, cent amounts, timestamps, versions, ledger deltas, and other bigint-capable values are canonical decimal **strings**. JSON numbers are forbidden. A purchase is server-owned canonical state: owner, quantity, unit amount, exact item subtotal, currency, jurisdiction, and registration version. Payment webhooks are accepted only when quantity, amount, currency, jurisdiction, and owner exactly match that purchase.

Provider receipts and economic claims are separate records. A receipt binds provider event ID to payload SHA-256 and provider object ID. Reusing an event ID with another hash or object binding is a fail-closed conflict. An economic claim binds the provider object to one purchase effect. Both records and any ledger append commit atomically. Every webhook also carries retrieved `providerTruth`; signature status, payment state, amount, currency, jurisdiction, owner, quantity, and tax are derived from that truth and the canonical purchase rather than from a declared expected outcome.

Each case carries machine-checked evidence metadata using Draft 2020-12 `date-time`, `uri`, `email`, and `uuid` formats. Required negative self-tests corrupt each formatted field so a missing or inactive `FormatChecker` cannot produce a false pass.

Refund credits are never calculated from an event delta. For canonical purchase quantity `Q`, item subtotal cents `S`, and provider-reported cumulative refunded item-subtotal cents `R`:

```
target_reversed = Q                    when R == S
                  floor(Q * R / S)     otherwise
append_delta = -(target_reversed - previously_reversed)
```

The full-refund branch assigns the integer-allocation residual deterministically. Taxes, shipping, discounts outside the canonical item subtotal, and repeated delivery cannot change the allocation.

## Conversion and compensation

Conversion state uses a charge cycle, funding kind (`customer` or `goodwill`), and explicit lifecycle state. A customer-funded debit may be compensation-eligible; a goodwill retry is not. A terminal failure can compensate an eligible active customer debit once, never a job identifier or retry attempt in isolation.

## Jurisdiction and operator controls

Jurisdiction registrations carry `evaluatedAt` and `databaseNow` as cross-checks, but neither those fields nor the fixture's `authoritativeJurisdictionTime` is an oracle. Each case references an immutable receipt in the validator's independently authenticated jurisdiction-time authority/config channel. The validator verifies that trusted source, config version, and receipt signature, requires every mutable clock to match the receipt, and derives `validFrom <= trusted receipt timestamp < expiresAt` from the receipt timestamp. Coherently rewinding fixture-owned clocks therefore cannot authorize a purchase. The purchase pins both the registration version and its authorization-source version. Operator adjustments bind a deterministic `operator_authorization_registry` source, source version, authorization version, validity window, scope, request time, and canonical payload hash. Positive and negative adjustments are append-only. Same-key/same-hash replay is an audited no-op; same-key/different-hash replay is an audited conflict.

## Expected state

Each case asserts structured purchases, provider receipts, economic claims, cycles, adjustments, cumulative refund state, ledger appends, net balance, spendable balance, and deficit. Concurrent cases use a typed `exactly_one_correlated_winner` constraint with named alternatives and a matching winner; no prose `one_of` placeholders are permitted.

## Validation

`validate.py` requires `jsonschema[format]`, validates the schema itself and every case with Draft 2020-12 plus active format checking, then checks referential integrity, uniqueness, ledger arithmetic, projections, receipt binding, purchase totals, refund allocation, and correlated winners. Missing `jsonschema` or its format dependencies exits nonzero with `BLOCKED` or fails the public malformed-format self-tests; it never silently falls back to partial validation.

Run complete validation only on an approved Debian build host using the repository's proven direct SSH route. Install validator dependencies on that remote host only. Do not install dependencies or execute validation on the workstation.