Turning SLA Breaches Into Collectible Credits
The Situation
Enterprise supplier contracts often include SLA credits. The contract says the vendor owes money when a response window is missed, a ticket sits unresolved, or a delivery rate falls below the promised target. The problem is not the clause. The problem is collection.
The Contract Lifecycle Engine can detect missed obligations. Procurement teams can also find breaches manually or in spreadsheets. But breach evidence does not become cash unless someone calculates the penalty, records both sides of the accounting event, handles disputes, groups the final amounts, and gives AP a credit-note artifact they can act on.
The PRD frames the buyer as a Head of Procurement or VP Vendor Management with more than $5M in annual spend across SLA-heavy suppliers. It also frames the recovery target at $60K-$150K per year on that spend. That is the value gap this system exists to close.
The Cost of Doing Nothing
Missed SLA credits usually leak because the process crosses teams. Legal owns the contract. Operations sees the breach. Procurement owns the vendor relationship. Finance owns settlement. When that handoff lives in email and spreadsheets, nobody owns the full chain.
For a $5M supplier portfolio, even a small leakage rate becomes real money. The PRD's recovery target of $60K-$150K a year is not a growth metric. It is money the contract already gives the buyer permission to collect.
Without an engine, the business either writes off the credits or spends expensive procurement and finance time rebuilding the trail later. By then the supplier has already invoiced, the breach evidence is stale, and the counterparty can dispute the math because there is no deterministic record.
What I Built
I built a settlement engine that turns breach events into penalty accruals, paired ledger entries, dispute reversals, settlement records, and credit-note PDFs.
The first operating path is standalone: operators enter contracts, SLA clauses, and breaches through the HTMX console or upload a fixed-schema CSV. The F# rules engine calculates one of five penalty types. The accrual worker writes the credit row and mirror row together. Disputes and withdrawals write compensation rows instead of editing the past.
The second path connects to the portfolio ecosystem. Contract Lifecycle can feed breached obligations through NATS or REST. Notification Hub can fan out signed breach envelopes. Invoice Recon can receive credit-note posts. Workflow can start dispute escalation. Vendor Performance Intelligence can receive supplier penalty signals.
The difficult part was keeping those integrations optional. Every external client is feature-flagged and disabled by default. If no ecosystem service is configured, the system still produces local PDF credit notes and keeps the ledger complete.
System Flow
Data Model
Architecture Layers
The Decision Log
| Decision | Alternative Rejected | Why |
|---|---|---|
| F# domain layer | C# service logic | Penalty states, no-penalty reasons, ledger directions, and config shapes are safer as typed unions than string flags. |
| Append-only ledger | Updating rows after disputes | Supplier disputes need a trail. Reversals write compensation rows so the original financial fact remains visible. |
| Settlement membership table | Marking ledger rows as settled | Ledger rows cannot change. settlement_ledger_entries tracks collection without weakening the ledger. |
| Fixed CSV import | Custom mapper UI | The PRD excludes custom column mapping, and a fixed header makes ingestion repeatable and testable. |
| Local PDF fallback | Mandatory Invoice Recon posting | Procurement can still collect credits without ecosystem credentials or a live AP integration. |
| Durable outbox | Direct calls to Hub and Invoice Recon | Settlement posting, alerts, and VPI signals need retries, leasing, and idempotency keys. |
| HMAC Hub ingress | Unsigned fanout endpoint | The Hub breach ingress verifies the signature before parsing tenant or breach fields. |
Ecosystem Integration
The engine sits between contract evidence and finance collection. Contract Lifecycle Engine can supply breach events, Invoice Reconciliation Engine can receive credit-note and debit-memo work, and Event-Driven Notification Hub can carry settlement and dispute alerts. Workflow escalation and supplier-risk signals stay behind the same optional client boundary, so the system still runs standalone with no ecosystem dependencies.
Results
The shipped repo has the full local loop: manual or CSV breach entry, deterministic accrual, append-only paired ledger rows, dispute reversal, settlement build, PDF preview/download, and local posting. The business path changes from spreadsheet reconstruction after the fact to same-system collection against the $60K-$150K annual recovery target. The test suite passed in this run with 61 tests across domain, data, application, API, and UI projects.
The strongest proof is the fake staging flow. A Contract Lifecycle event is ingested, accrued into exactly two ledger rows, grouped into a settlement, queued for Invoice Recon, and completed through the outbox with a settlement.posted Hub event.
The dashboard path was load-audited with tooling for 10000 breaches and 5000 settlements, with a 500ms assertion around a single bounded aggregate query. The live deployment was not included because the registry marks the project as not deployed and the Traefik host returned no reachable HTTP response.
The next scaling work is not more penalty math. It is ledger query proof at much larger row counts and live p95 measurement against Invoice Recon. The core accounting contract can stay as it is: calculate from deterministic inputs, write paired rows, and never edit the financial past.