Persist serving usage ledger for request-cost reconciliation

[seonghobae]

Purpose

--state-db retains workflow and decision records, but the serving CLI still constructs an in-memory cost ledger. A restart can therefore leave retained request evidence without the usage rows needed for cost reconciliation. This PR connects the existing SQL ledger store through an explicit serving-only --usage-ledger-db path.

Contract

• Keep the current in-memory default. When selected, initialize the existing normalized SQL ledger and use one price book for routing and billing.
• Retain HTTP-created usage across server restarts and expose it through the existing authenticated admin usage endpoint.
• Close the connection when serving stops. On POSIX, create new files owner-only and refuse existing symlinks or broadly readable files without modifying them. Refuse blank and SQLite :memory: paths.
• A durable ledger alone is not a complete request-cost cohort. PR Link retained request outcomes to cost ledger attempts #1336 supplies request-to-usage IDs; reconcile against actual persisted rows after the ledger settles and exclude unavailable/incomplete observations.

Verification

• RED: serving CLI rejected --usage-ledger-db; after initial wiring, a regression caught distinct price-book instances; a file-mode assertion caught SQLite's default 0644 creation.
• GREEN: a real HTTP completion, process-lifecycle restart, authenticated admin usage read, and connection closure pass in a project-local Python 3.14 environment.
• 80 CLI/auth/logging/cost-review tests passed under -W error; 59 cost-ledger/boundary/CLI tests passed under the default warning policy. git diff --check and CodeGraph sync passed.

Research and scope

The primary reference for transaction and connection behavior is the Python sqlite3 manual; SQLite's atomic commit documentation describes the single-file durability model. Sigelman et al., Dapper, a Large-Scale Distributed Systems Tracing Infrastructure (Google Technical Report, 2010), https://research.google/pubs/dapper-a-large-scale-distributed-systems-tracing-infrastructure/ , motivates retaining request-level evidence across execution stages. Its PDF is linked rather than redistributed because redistribution permission was not established. This PR reuses the repository's SQL ledger implementation; it introduces no new estimator or billing policy.

Local proof is not a protected merge, hosted Linux acceptance, immutable release, or customer cost baseline. PR #1268 also edits the CLI serve path and currently has a textual merge conflict; integration should retain both changes when that PR is ready.

[coderabbitai]

Warning

Review limit reached

Next included review available in 17 minutes.

Check out review usage here.

View limit details

Limit details: You’ve used the included review currently available.

You've used all free OSS reviews for now. Wait for the free limit to reset to keep reviewing this public repository.

Learn how review limits work.

Review configuration:

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Advanced

Run ID: 56b42676-19e8-4a11-9ec4-7c878f615573

📥 Commits

Reviewing files that changed from the base of the PR and between 8e1f1a8 and 3d6814a.

📒 Files selected for processing (3)

• contextual_orchestrator/__main__.py
• docs/doctoring/autonomous_kpi_runbook.md
• tests/test_cli_usage_ledger.py

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[seonghobae]

Local integration rehearsal at current heads: main@8e1f1a8b + #1227 0b4d2503 + #1320 352ac715 + #1325 95ad076b + #1330 51769164 + #1328 2da4f118 + this PR 3d6814a5 merged without code conflicts. The CLI/runtime-identity/release/SBOM focused suite passed 34 tests with -W error.

Adding #1313 ff1242cc and #1336 2807c041 required one documentation-only conflict resolution that preserved both sections. After building the native receipt module in the isolated worktree, the same seven-module CLI/request-export/provenance/cost-review/runtime-identity/release/SBOM suite passed 124 tests with -W error (scratch integration HEAD 4c4d91da). The initial expanded run failed because this scratch tree had no native module; it passed after the build. The scratch worktree was removed. This is local compatibility evidence only; hosted current-head checks, independent review, merge, immutable release and deployed reconciliation are still required.

[seonghobae]

Exact-head admission correction — 3d6814a55781d01235158b6023bfad7847343f36

Ready is review admission only. Fresh audit against base 8e1f1a8bf3e96e56dc8fcc90ec777883a1d56ce6 found:

• latest terminal workflow blockers: CodeQL PR 36417013333=failure

This PR is moved to Draft/Proposed until the causal owner repair is present on a successor exact head and re-audited. Queued/pending work is neither an additional blocker nor passing evidence. No Close, force push, destructive rebase, manual rerun, synthetic status/approval, merge, auto-merge, or bypass was performed.