Usage reconciliation ledger

Implementation

Account-scoped source events have an idempotent identity and exact integer base units. A correction appends a reversal and replacement; original input remains unchanged.

Closing reconciles entries with the total cache, records ingest and posting cutoffs, and freezes a versioned export. Late events and corrections to closed periods wait for an operator to post them into a later open period.

The operator console exposes ingestion, correction review, closing, reconciliation and downloads. SQLite write transactions serialize ingest and close so either the new usage is included or it is recorded as pending.

Checked online SQLite snapshots, restore into a new directory, and a periodic backup command are included. An executed operations rehearsal covers abrupt process exits, recovery and rejected inputs.

Inputs and assumptions

• The January/February 2026 example is synthetic. Calendar periods use UTC.
• Units are API calls, compute minutes and storage GiB-hours. Fractional units allow three decimal places; API calls are integral. No pricing or invoicing is included.
• Python 3.12 and local SQLite replace the earlier PostgreSQL deployment plan. Account-period writes are serialized through SQLite's single writer.

Results

Report figures (2)

Open the full report ↗

Verification

24 tests pass, including duplicate ingestion, exact arithmetic, correction chains, both ingest/close lock orders, immutable exports, cache corruption detection, account isolation and role checks. A separate operations rehearsal passes 19 expected-outcome checks, including process crashes, checked snapshots, restore and a finite backup schedule.

python verify.py
python demo.py
python operations_rehearsal.py

Project files

The ZIP contains the source, inputs, results, and instructions. These files are also available individually.

• Ledger, close and reconciliation rulesledger.py · 19 KB
• API and operator consoleapp.py · 8 KB
• Synthetic source eventsexamples/events.json · 1 KB
• Frozen January exportresults/2026-01-v1.json · 2 KB
• Frozen February exportresults/2026-02-v1.json · 2 KB
• Exported ledger entriesresults/entries.csv · 1 KB
• Executed audit historyresults/audit.json · 2 KB
• Integration test suitetest_ledger.py · 11 KB
• Executed operations and recovery reportoperations-report.html · 10 KB
• Expected and observed operational outcomescompletion.json · 9 KB
• Reproducible crash and recovery scenariosoperations_rehearsal.py · 12 KB
• Checked SQLite backup and restore CLIoperations.py · 5 KB
• Periodic snapshot runnerbackup_schedule.py · 1 KB
• Deployment, recovery and capacity assumptionsOPERATIONS.md · 5 KB

Run locally

Python 3.12+ / SQLite via Python standard library

Extract the ZIP and open a terminal in the usage-reconciliation folder. The README includes setup and usage details.

python app.py --demo
# Open http://127.0.0.1:9090
python verify.py
python demo.py
python build_report.py
python operations_rehearsal.py

Limits

• Localhost-only application with example bearer tokens. Production identity, TLS termination and distributed coordination are not included.
• Closed periods cannot be reopened or restated. Adjustments carry forward under the documented rule; changing that accounting policy needs a new implementation and tests.
• Database triggers prevent ordinary updates to history, but the database owner can change files or schema. This is not a tamper-proof external audit system.
• No monetary prices, tax, invoices, payments, event-stream connector or production capacity claim.
• Checked snapshot/restore and a periodic snapshot runner are included. Restoring an older snapshot still requires a separately retained source journal to recover post-snapshot records; the executed replay drill uses synthetic inputs.