Local service and operations rehearsal completed

Usage reconciliation

An exact-unit usage ledger with corrections, monthly closes, late-event review and reproducible JSON/CSV exports.

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

Recorded results

Local ledger after closing January and posting a late adjustment to February. Synthetic demonstration data.
Local ledger after closing January and posting a late adjustment to February. Synthetic demonstration data.
The recorded February close combines 8.250 current minutes, 3.125 late minutes and a -2.000-minute correction, totaling 9.375 minutes.
The recorded February close combines 8.250 current minutes, 3.125 late minutes and a -2.000-minute correction, totaling 9.375 minutes.
Machine-readable result summary
{
  "fixture": "synthetic January and February 2026 usage",
  "timezone": "UTC",
  "rule_version": "usage-v1",
  "events": 6,
  "ledger_entries": 7,
  "closed_versions": 2,
  "late_and_correction_adjustments": 2,
  "pending_after_approval": 0,
  "january_compute_minutes": "19.750",
  "january_api_calls": "1250",
  "february_compute_minutes": "9.375",
  "february_components": {
    "late_usage": "3.125",
    "correction_net": "-2.000",
    "current_usage": "8.250"
  },
  "export_hashes": {
    "2026-01": "ab6b4b56bcd199dc98049d771a3d32d441e2796b8d7734aa2cec0df66ff0c79d",
    "2026-02": "6fedc1947e61419ea88b694ba42ce45d80e163e74907177d9535d978c3c8e1a7"
  },
  "assertions": {
    "january_export_unchanged": true,
    "duplicate_not_recounted": true,
    "both_reconciliations_match": true,
    "both_exports_digest_verified": true
  },
  "reconciliations": {
    "2026-01": {
      "period": "2026-01",
      "matches": true,
      "rebuilt": {
        "api_call": {
          "quantity": "1250",
          "base_units": "1250",
          "precision": 0
        },
        "compute_minute": {
          "quantity": "19.750",
          "base_units": "19750",
          "precision": 3
        }
      },
      "cached_base_units": {
        "api_call": "1250",
        "compute_minute": "19750"
      }
    },
    "2026-02": {
      "period": "2026-02",
      "matches": true,
      "rebuilt": {
        "compute_minute": {
          "quantity": "9.375",
          "base_units": "9375",
          "precision": 3
        }
      },
      "cached_base_units": {
        "compute_minute": "9375"
      }
    }
  }
}

Verification

24 of 24 tests passed. Failures: 0. Errors: 0.

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

Verification record

Executed test cases
  • test_ledger.ApiTests.test_auth_and_cross_account
  • test_ledger.ApiTests.test_export_and_csv_formula_safety
  • test_ledger.ApiTests.test_invalid_and_static_paths
  • test_ledger.ApiTests.test_roles
  • test_ledger.LedgerTests.test_adjustment_target_and_duplicate_posting_rejected
  • test_ledger.LedgerTests.test_canonical_idempotency_and_conflicting_duplicate
  • test_ledger.LedgerTests.test_close_idempotency_and_restart_export
  • test_ledger.LedgerTests.test_close_wins_ingest_race_pending
  • test_ledger.LedgerTests.test_closed_export_frozen_after_late_event_and_correction
  • test_ledger.LedgerTests.test_concurrent_duplicate_ingest_once
  • test_ledger.LedgerTests.test_correction_cannot_link_other_account
  • test_ledger.LedgerTests.test_correction_chain_requires_latest_revision
  • test_ledger.LedgerTests.test_correction_replay_and_conflict
  • test_ledger.LedgerTests.test_corrupt_cache_detected_before_close
  • test_ledger.LedgerTests.test_empty_period_close
  • test_ledger.LedgerTests.test_exact_precision_and_no_float
  • test_ledger.LedgerTests.test_immutable_storage_guards
  • test_ledger.LedgerTests.test_ingest_wins_close_race_included
  • test_ledger.LedgerTests.test_large_integer_totals_remain_exact
  • test_ledger.LedgerTests.test_open_correction_is_linked_reversal_and_replacement
  • test_ledger.LedgerTests.test_posting_cutoff_excludes_previously_ingested_unposted_events
  • test_ledger.LedgerTests.test_reordered_import_duplicates_reconcile
  • test_ledger.LedgerTests.test_same_identity_separate_accounts
  • test_ledger.LedgerTests.test_timestamp_timezone_sets_utc_period

Run locally

Python 3.12+ / SQLite via Python standard library

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

Full setup and usage instructions

Source and evidence

Limits