# Pathrule Pattern: Invoicing and Tax (1.0.0)
# ::pathrule:package:invoicing-tax

### [RULE] Snapshot every fact printed on an invoice  (path: /src/billing/invoices)
<!-- scope: folder | priority: high | strict -->

Final invoice lines preserve description, quantity, unit amount, currency, tax treatment, parties, and address evidence. Rendering from live catalog or customer records rewrites history when a name, price, tax identifier, or address changes. Enforce this boundary in /src/billing/invoices so invalid work stops before it reaches another subsystem or creates an externally visible side effect.

- Create immutable invoice-line and party snapshots when the invoice is finalized, not when a PDF is later requested.
- Store monetary values as integers in the currency's minor unit and preserve the currency with every amount.
- Retain the tax calculation inputs, jurisdiction result, exemption or reverse-charge evidence, and provider calculation identifier.
- Generate all human and machine exports from the same finalized snapshot.

Verification: Change the live product, customer address, and tax configuration after finalization; confirm the invoice and its regenerated exports remain byte-for-byte equivalent where format permits.

---

### [RULE] Correct finalized invoices with linked documents  (path: /src/billing/invoices)
<!-- scope: folder | priority: high | strict -->

A finalized invoice is never mutated; credits, voids, and replacement documents preserve the original audit chain. In-place edits make ledger totals, customer copies, provider records, and tax reports disagree with no durable explanation. Enforce this boundary in /src/billing/invoices so invalid work stops before it reaches another subsystem or creates an externally visible side effect.

- Restrict mutable drafts and make finalization an explicit, idempotent transition with authorization and audit evidence.
- Represent reductions with a credit note or equivalent linked document and preserve reason, amount, currency, and affected lines.
- Use a replacement document only through the jurisdiction and provider flow the business has approved.
- Keep document numbering unique and allocated by one transactional service, including retries and concurrent finalization.

Verification: Race two finalization requests and retry a correction event; confirm one number is allocated, one immutable original remains, and ledger totals reconcile.

---

### [MEMORY] Tax calculation consumes evidence, not guesses  (path: /src/tax)

A billing country or card country alone may not represent the location evidence, registration, exemption, or product tax category required for a transaction. Define the evidence fields the tax engine receives and the precedence used when sources disagree.

Keep product tax codes separate from marketing categories and version changes prospectively. Record why tax was charged, not charged, or reverse charged with the transaction snapshot. Send uncertain or conflicting evidence to an explicit review or collection path instead of silently selecting a favorable result. Keep the decision explicit at /src/tax; moving it into an incidental caller makes behavior depend on which route happened to execute first.

See /src/billing/invoices for immutable snapshots and /src/webhooks for provider reconciliation. That related boundary consumes this decision and carries the evidence that proves it still holds.

---

### [SKILL] reconcile-invoices  (path: /)

---
name: reconcile-invoices
description: Reconcile internal invoices, provider documents, payments, credits, and tax totals for a closed period.
---

# Reconcile Invoices

Run this procedure whenever the governed surface changes or its operational evidence becomes stale.

1. Freeze the period input set and export internal invoices, provider invoices, payments, refunds, credits, voids, and tax summaries using stable identifiers.
2. Match documents by internal and provider IDs, then compare currency, subtotal, discount, tax, total, paid, credited, and outstanding amounts.
3. Classify mismatches as timing, duplicate event, missing event, configuration, rounding, or manual provider change; never force a balancing row without cause.
4. Resolve or accrue every difference, record evidence and owner, and rerun until the reconciliation is reproducible from the same input set.

Record the decision, failed checks, and follow-up owner with the change. A successful run leaves reproducible evidence that another reviewer can inspect without repeating the investigation from memory.