Expand description
Costroid’s local SQLite usage store — a metadata-only persistent ledger.
§R4, the Cardinal Rule: the store cannot hold content
The single usage_rows table is an explicit metadata
allowlist (USAGE_ROWS_COLUMNS). It persists only the bounded, non-free-text
metadata needed to reconstruct a FocusRecord on replay (a later milestone) via
FocusRecord::unpriced_usage plus cost/pricing overrides: token counts, model,
lane, the full priced cost set + the catalog-priced quantity/unit-price columns (all
as decimal strings, never floats), the charge timestamp, provider identity, and the
bounded SKU + pricing-category/unit identifiers — so a priced row round-trips
byte-identically rather than reverting to the unpriced 0.
It deliberately drops every free-text-capable or non-derivable FOCUS column —
ChargeDescription (the derived "{model} {token_type} tokens", re-derived on
replay), ResourceId / ResourceName / ResourceType, Tags / AllocatedTags,
SkuPriceDetails, and the region / sub-account / availability-zone columns. The
store is therefore structurally incapable of holding prompt or response content.
The fail-closed r4_schema_forbids_free_text_columns test asserts the DDL
carries none of the forbidden substrings and that every column is in the allowlist —
so adding a column to the DDL without reviewing it fails the build (mirroring the
CONNECT_ALLOWED / SERVER_ALLOWED fail-closed allowlists).
§Money is a decimal string, never a float
Every cost column is stored as a TEXT decimal string (mirroring the FOCUS export),
never f64 — exact decimal arithmetic, no binary-float drift.
Structs§
- Store
- The local SQLite usage store. Wraps a single
rusqlite::Connection; the schema is applied (and the version stamp checked) on open.
Enums§
- Store
Error - Errors the store can return. Typed (no
unwrap/expect/panic!); wraps the underlying SQLite error and the schema-stamp mismatch case.
Constants§
- FORBIDDEN_
SUBSTRINGS - Substrings that no R4-safe metadata column name — or, by extension, any field name a
downstream consumer (the SQLite store, the loopback server’s JSON/HTML views) serializes —
may contain: every free-text-capable or content-bearing shape (R4, the Cardinal Rule). Checked
case-insensitively. Promoted out of the store’s test module (M5 T3) so the
costroid-serverR4 test shares one source of truth rather than re-declaring the list. - SCHEMA_
VERSION - The schema version of the
usage_rowslayout. Bumped whenever the persisted column set changes so a future replay/migration step can tell shapes apart. Stamped intoSTORE_META_TABLEon open. - STORE_
META_ TABLE - The tiny stamp table holding
SCHEMA_VERSION+ theFOCUS_VERSIONthe rows were written under (so a later replay/migration can detect a FOCUS-shape change). - USAGE_
ROWS_ COLUMNS - The explicit metadata allowlist — every column the
usage_rowstable is permitted to carry, and nothing else (R4, the Cardinal Rule). - USAGE_
ROWS_ TABLE - The one persisted table.
Functions§
- usage_
rows_ ddl CREATE TABLEDDL for theusage_rowsmetadata-allowlist table.