Skip to main content

costroid_store/
lib.rs

1//! Costroid's local SQLite usage store — a metadata-only persistent ledger.
2//!
3//! # R4, the Cardinal Rule: the store cannot hold content
4//!
5//! The single [`usage_rows`](USAGE_ROWS_TABLE) table is an **explicit metadata
6//! allowlist** ([`USAGE_ROWS_COLUMNS`]). It persists only the bounded, non-free-text
7//! metadata needed to reconstruct a [`FocusRecord`] on replay (a later milestone) via
8//! [`FocusRecord::unpriced_usage`] plus cost/pricing overrides: token counts, model,
9//! lane, the full priced cost set + the catalog-priced quantity/unit-price columns (all
10//! as decimal *strings*, never floats), the charge timestamp, provider identity, and the
11//! bounded SKU + pricing-category/unit identifiers — so a *priced* row round-trips
12//! byte-identically rather than reverting to the unpriced 0.
13//!
14//! It deliberately **drops every free-text-capable or non-derivable FOCUS column** —
15//! `ChargeDescription` (the derived `"{model} {token_type} tokens"`, re-derived on
16//! replay), `ResourceId` / `ResourceName` / `ResourceType`, `Tags` / `AllocatedTags`,
17//! `SkuPriceDetails`, and the region / sub-account / availability-zone columns. The
18//! store is therefore *structurally incapable* of holding prompt or response content.
19//! The fail-closed [`r4_schema_forbids_free_text_columns`](#) test asserts the DDL
20//! carries none of the forbidden substrings and that every column is in the allowlist —
21//! so adding a column to the DDL without reviewing it fails the build (mirroring the
22//! `CONNECT_ALLOWED` / `SERVER_ALLOWED` fail-closed allowlists).
23//!
24//! # Money is a decimal string, never a float
25//!
26//! Every cost column is stored as a `TEXT` decimal string (mirroring the FOCUS export),
27//! never `f64` — exact decimal arithmetic, no binary-float drift.
28
29use std::path::Path;
30use std::str::FromStr;
31
32use chrono::{DateTime, Utc};
33use costroid_focus::{
34    FocusAccessPath, FocusRecord, LedgerLane, TokenType, UnpricedUsage, FOCUS_VERSION,
35};
36use rusqlite::{Connection, OptionalExtension};
37use rust_decimal::Decimal;
38use thiserror::Error;
39
40/// The schema version of the [`usage_rows`](USAGE_ROWS_TABLE) layout. Bumped whenever
41/// the persisted column set changes so a future replay/migration step can tell shapes
42/// apart. Stamped into [`STORE_META_TABLE`] on open.
43pub const SCHEMA_VERSION: i64 = 7;
44
45/// The one persisted table.
46pub const USAGE_ROWS_TABLE: &str = "usage_rows";
47
48/// The tiny stamp table holding [`SCHEMA_VERSION`] + the [`FOCUS_VERSION`] the rows were
49/// written under (so a later replay/migration can detect a FOCUS-shape change).
50pub const STORE_META_TABLE: &str = "store_meta";
51
52/// The **explicit metadata allowlist** — every column the [`usage_rows`](USAGE_ROWS_TABLE)
53/// table is permitted to carry, and nothing else (R4, the Cardinal Rule).
54///
55/// This is the single source of truth the fail-closed schema test checks the live DDL
56/// against: every real column must be a member, so a column added to the DDL without
57/// also being reviewed into this list fails the test. Each entry is bounded metadata
58/// (an enum string, an identifier, a decimal string, or a timestamp) — never a
59/// free-text-capable or non-derivable FOCUS column.
60pub const USAGE_ROWS_COLUMNS: &[&str] = &[
61    // Time — RFC 3339 (UTC) string; the FOCUS charge-period start of the meter row.
62    "charge_period_start",
63    // Costroid x_ taxonomy — all bounded enum/identifier strings.
64    "x_lane",
65    "x_tool",
66    "x_model",
67    "x_token_type",
68    "x_access_path",
69    "x_pricing_status",
70    "x_estimated", // INTEGER 0/1
71    "x_project",   // nullable; a project path/label, not free-text content
72    // Costs — decimal STRINGS (never floats); raw token count as a decimal string.
73    "billed_cost",
74    "effective_cost",
75    // The remaining FOCUS cost columns a priced row sets — non-null `Decimal`
76    // (`cloud_usage_to_focus` + `apply_pricing` stamp these); decimal STRINGS, never
77    // floats. Dropping them previously reverted a real priced row to the unpriced 0.
78    "list_cost",
79    "contracted_cost",
80    "pricing_currency_effective_cost",
81    "x_consumed_tokens",
82    "billing_currency",
83    // Quantity / unit-price columns a catalog-priced SKU populates (`apply_pricing`) —
84    // nullable `Option<Decimal>` (null on an unpriced row, Some on a priced one);
85    // decimal STRINGS, never floats. Bounded numeric metadata (R4-safe).
86    "consumed_quantity",
87    "pricing_quantity",
88    "list_unit_price",
89    "contracted_unit_price",
90    "pricing_currency_list_unit_price",
91    "pricing_currency_contracted_unit_price",
92    // Provider identity — bounded identifier strings.
93    "service_name",
94    "service_provider_name",
95    "host_provider_name",
96    "invoice_issuer_name",
97    // SKU / pricing identifiers — bounded enum/identifier strings; NOT
98    // `sku_price_details` (dropped, free-text-capable). `sku_price_id`, `pricing_category`,
99    // and `pricing_unit` are populated by `apply_pricing` on a catalog-priced row.
100    "sku_id",
101    "sku_price_id",
102    "sku_meter",
103    "pricing_category",
104    "pricing_unit",
105    // Import provenance — the FOCUS spec version a row was imported from (nullable; a
106    // bounded version string like "1.2", null on non-imported rows). Never content.
107    "x_focus_input_version",
108    // Collector attribution taxonomy — all bounded enum/flag/version strings, never content.
109    "x_sidechain",              // INTEGER 0/1
110    "x_attribution_confidence", // "confident" / "uncertain"
111    "x_collector_version",      // the Costroid version that minted the row
112    // Pricing provenance — the bundled/override snapshot that priced an estimated row
113    // ("{source}@{as_of}#{hash8}"); nullable (null on source-priced/unpriced). Never content.
114    "x_pricing_snapshot_id",
115    // Bedrock application-inference-profile id (bounded system id; nullable, null off-Bedrock).
116    // Never the profile name/tags. Never content.
117    "x_inference_profile_id",
118    // Local-inference economics (M3 / §6.4) — populated on `local_inference`-lane rows, null
119    // off-lane. All bounded numbers (decimal STRINGS) / ids / enum-ish labels — never content.
120    "x_measured_wh",
121    "x_avg_power_watts",
122    "x_hardware_profile",
123    "x_amortized_hw_cost",
124    "x_runtime_kind",
125    "x_benchmark_id",
126    "x_measurement_mode",
127];
128
129/// Substrings that no R4-safe metadata column name — or, by extension, any field name a
130/// downstream consumer (the SQLite store, the loopback server's JSON/HTML views) serializes —
131/// may contain: every free-text-capable or content-bearing shape (R4, the Cardinal Rule). Checked
132/// case-insensitively. Promoted out of the store's test module (M5 T3) so the `costroid-server` R4
133/// test shares one source of truth rather than re-declaring the list.
134///
135/// (`"text"` also catches the SQLite `TEXT` type keyword, so callers checking a DDL string strip
136/// the type tokens first; callers checking real *column/field names* apply it verbatim.)
137pub const FORBIDDEN_SUBSTRINGS: &[&str] = &[
138    "description",
139    "resource",
140    "tags",
141    "content",
142    "prompt",
143    "completion",
144    "message",
145    "text", // catches `sku_price_details`-style free text *and* any *_text column
146    "sku_price_details",
147];
148
149/// `CREATE TABLE` DDL for the [`usage_rows`](USAGE_ROWS_TABLE) metadata-allowlist table.
150///
151/// Exposed as a function so the fail-closed R4 schema test can read the exact DDL the
152/// store applies and assert it carries no free-text column. Column order mirrors
153/// [`USAGE_ROWS_COLUMNS`].
154pub fn usage_rows_ddl() -> String {
155    format!(
156        "CREATE TABLE IF NOT EXISTS {USAGE_ROWS_TABLE} (\n  \
157            id INTEGER PRIMARY KEY,\n  \
158            charge_period_start TEXT NOT NULL,\n  \
159            x_lane TEXT NOT NULL,\n  \
160            x_tool TEXT NOT NULL,\n  \
161            x_model TEXT NOT NULL,\n  \
162            x_token_type TEXT NOT NULL,\n  \
163            x_access_path TEXT NOT NULL,\n  \
164            x_pricing_status TEXT NOT NULL,\n  \
165            x_estimated INTEGER NOT NULL,\n  \
166            x_project TEXT,\n  \
167            billed_cost TEXT NOT NULL,\n  \
168            effective_cost TEXT NOT NULL,\n  \
169            list_cost TEXT NOT NULL,\n  \
170            contracted_cost TEXT NOT NULL,\n  \
171            pricing_currency_effective_cost TEXT NOT NULL,\n  \
172            x_consumed_tokens TEXT NOT NULL,\n  \
173            billing_currency TEXT NOT NULL,\n  \
174            consumed_quantity TEXT,\n  \
175            pricing_quantity TEXT,\n  \
176            list_unit_price TEXT,\n  \
177            contracted_unit_price TEXT,\n  \
178            pricing_currency_list_unit_price TEXT,\n  \
179            pricing_currency_contracted_unit_price TEXT,\n  \
180            service_name TEXT NOT NULL,\n  \
181            service_provider_name TEXT NOT NULL,\n  \
182            host_provider_name TEXT NOT NULL,\n  \
183            invoice_issuer_name TEXT NOT NULL,\n  \
184            sku_id TEXT,\n  \
185            sku_price_id TEXT,\n  \
186            sku_meter TEXT,\n  \
187            pricing_category TEXT,\n  \
188            pricing_unit TEXT,\n  \
189            x_focus_input_version TEXT,\n  \
190            x_sidechain INTEGER NOT NULL,\n  \
191            x_attribution_confidence TEXT NOT NULL,\n  \
192            x_collector_version TEXT NOT NULL,\n  \
193            x_pricing_snapshot_id TEXT,\n  \
194            x_inference_profile_id TEXT,\n  \
195            x_measured_wh TEXT,\n  \
196            x_avg_power_watts TEXT,\n  \
197            x_hardware_profile TEXT,\n  \
198            x_amortized_hw_cost TEXT,\n  \
199            x_runtime_kind TEXT,\n  \
200            x_benchmark_id TEXT,\n  \
201            x_measurement_mode TEXT\n\
202        )"
203    )
204}
205
206/// `CREATE TABLE` DDL for the [`store_meta`](STORE_META_TABLE) stamp table.
207fn store_meta_ddl() -> String {
208    format!(
209        "CREATE TABLE IF NOT EXISTS {STORE_META_TABLE} (\n  \
210            key TEXT PRIMARY KEY,\n  \
211            value TEXT NOT NULL\n\
212        )"
213    )
214}
215
216/// Errors the store can return. Typed (no `unwrap`/`expect`/`panic!`); wraps the
217/// underlying SQLite error and the schema-stamp mismatch case.
218#[derive(Debug, Error)]
219pub enum StoreError {
220    /// A `rusqlite` (SQLite) error — open, prepare, execute, or query failed.
221    #[error("sqlite error: {0}")]
222    Sqlite(#[from] rusqlite::Error),
223
224    /// The opened database carries a `schema_version` the running code does not know how
225    /// to read (a future migration step's job; for now it is a fail-closed mismatch).
226    #[error("unsupported store schema version: found {found}, expected {expected}")]
227    SchemaVersion { found: i64, expected: i64 },
228
229    /// A persisted row could not be reconstructed into a [`FocusRecord`] on replay — a
230    /// malformed stored enum (an `x_lane`/`x_token_type`/`x_access_path` value with no
231    /// `from_focus_str` inverse), an unparseable timestamp, or an unparseable decimal
232    /// string. The store fails closed with this typed error rather than panicking or
233    /// silently substituting a default (which would corrupt the replayed ledger).
234    #[error("failed to reconstruct a FocusRecord from a stored row: {0}")]
235    Reconstruct(String),
236
237    /// Building the FOCUS record from the reconstructed [`UnpricedUsage`] failed — the
238    /// underlying [`costroid_focus::FocusError`] (e.g. an out-of-range timestamp for the
239    /// FOCUS billing-period calculation), surfaced typed.
240    #[error("failed to build a FocusRecord on replay: {0}")]
241    Focus(#[from] costroid_focus::FocusError),
242}
243
244/// The local SQLite usage store. Wraps a single [`rusqlite::Connection`]; the schema is
245/// applied (and the version stamp checked) on open.
246pub struct Store {
247    conn: Connection,
248}
249
250impl Store {
251    /// Open an in-memory store (used by tests and ephemeral runs). The schema is created
252    /// and stamped immediately.
253    pub fn open_in_memory() -> Result<Self, StoreError> {
254        let conn = Connection::open_in_memory()?;
255        Self::from_connection(conn)
256    }
257
258    /// Open (creating if absent) a file-backed store at `path`. The schema is created if
259    /// the file is new, and the version stamp is checked against [`SCHEMA_VERSION`].
260    pub fn open(path: &Path) -> Result<Self, StoreError> {
261        let conn = Connection::open(path)?;
262        Self::from_connection(conn)
263    }
264
265    /// Apply the schema (idempotent), then read/write the version stamp. A pre-existing
266    /// database carrying a different `schema_version` is a fail-closed
267    /// [`StoreError::SchemaVersion`].
268    fn from_connection(conn: Connection) -> Result<Self, StoreError> {
269        conn.execute_batch(&format!("{};\n{};", store_meta_ddl(), usage_rows_ddl()))?;
270
271        let existing: Option<String> = conn
272            .query_row(
273                &format!("SELECT value FROM {STORE_META_TABLE} WHERE key = 'schema_version'"),
274                [],
275                |row| row.get(0),
276            )
277            .optional()?;
278
279        match existing {
280            Some(value) => {
281                let found: i64 = value.parse().unwrap_or(-1);
282                if found != SCHEMA_VERSION {
283                    return Err(StoreError::SchemaVersion {
284                        found,
285                        expected: SCHEMA_VERSION,
286                    });
287                }
288            }
289            None => {
290                conn.execute(
291                    &format!(
292                        "INSERT INTO {STORE_META_TABLE} (key, value) VALUES \
293                         ('schema_version', ?1), ('focus_version', ?2)"
294                    ),
295                    rusqlite::params![SCHEMA_VERSION.to_string(), FOCUS_VERSION],
296                )?;
297            }
298        }
299
300        Ok(Self { conn })
301    }
302
303    /// Insert the whitelisted metadata columns from each [`FocusRecord`]. Runs in a
304    /// single transaction; returns the number of rows inserted.
305    ///
306    /// Only the [`USAGE_ROWS_COLUMNS`] allowlist is read off each record — the derived
307    /// `ChargeDescription` and every free-text-capable / non-derivable FOCUS column are
308    /// never touched (R4).
309    pub fn ingest(&self, rows: &[FocusRecord]) -> Result<usize, StoreError> {
310        let tx = self.conn.unchecked_transaction()?;
311        {
312            let mut stmt = tx.prepare(&format!(
313                "INSERT INTO {USAGE_ROWS_TABLE} (\
314                    charge_period_start, x_lane, x_tool, x_model, x_token_type, \
315                    x_access_path, x_pricing_status, x_estimated, x_project, \
316                    billed_cost, effective_cost, list_cost, contracted_cost, \
317                    pricing_currency_effective_cost, x_consumed_tokens, billing_currency, \
318                    consumed_quantity, pricing_quantity, list_unit_price, \
319                    contracted_unit_price, pricing_currency_list_unit_price, \
320                    pricing_currency_contracted_unit_price, service_name, \
321                    service_provider_name, host_provider_name, invoice_issuer_name, \
322                    sku_id, sku_price_id, sku_meter, pricing_category, pricing_unit, \
323                    x_focus_input_version, x_sidechain, x_attribution_confidence, \
324                    x_collector_version, x_pricing_snapshot_id, x_inference_profile_id, \
325                    x_measured_wh, x_avg_power_watts, x_hardware_profile, \
326                    x_amortized_hw_cost, x_runtime_kind, x_benchmark_id, x_measurement_mode\
327                ) VALUES (\
328                    ?1, ?2, ?3, ?4, ?5, ?6, ?7, ?8, ?9, ?10, ?11, ?12, ?13, ?14, ?15, \
329                    ?16, ?17, ?18, ?19, ?20, ?21, ?22, ?23, ?24, ?25, ?26, ?27, ?28, \
330                    ?29, ?30, ?31, ?32, ?33, ?34, ?35, ?36, ?37, ?38, ?39, ?40, ?41, \
331                    ?42, ?43, ?44\
332                )"
333            ))?;
334
335            for row in rows {
336                stmt.execute(rusqlite::params![
337                    row.charge_period_start.to_rfc3339(),
338                    row.x_lane,
339                    row.x_tool,
340                    row.x_model,
341                    row.x_token_type,
342                    row.x_access_path,
343                    row.x_pricing_status,
344                    i64::from(row.x_estimated),
345                    row.x_project,
346                    row.billed_cost.to_string(),
347                    row.effective_cost.to_string(),
348                    row.list_cost.to_string(),
349                    row.contracted_cost.to_string(),
350                    row.pricing_currency_effective_cost.to_string(),
351                    row.x_consumed_tokens.to_string(),
352                    row.billing_currency,
353                    decimal_opt_to_string(&row.consumed_quantity),
354                    decimal_opt_to_string(&row.pricing_quantity),
355                    decimal_opt_to_string(&row.list_unit_price),
356                    decimal_opt_to_string(&row.contracted_unit_price),
357                    decimal_opt_to_string(&row.pricing_currency_list_unit_price),
358                    decimal_opt_to_string(&row.pricing_currency_contracted_unit_price),
359                    row.service_name,
360                    row.service_provider_name,
361                    row.host_provider_name,
362                    row.invoice_issuer_name,
363                    row.sku_id,
364                    row.sku_price_id,
365                    row.sku_meter,
366                    row.pricing_category,
367                    row.pricing_unit,
368                    row.x_focus_input_version,
369                    i64::from(row.x_sidechain),
370                    row.x_attribution_confidence,
371                    row.x_collector_version,
372                    row.x_pricing_snapshot_id,
373                    row.x_inference_profile_id,
374                    // Local-inference economics (M3): decimal columns as exact strings (never
375                    // floats), the id/enum-ish columns verbatim. Null off the local lane.
376                    decimal_opt_to_string(&row.x_measured_wh),
377                    decimal_opt_to_string(&row.x_avg_power_watts),
378                    row.x_hardware_profile,
379                    decimal_opt_to_string(&row.x_amortized_hw_cost),
380                    row.x_runtime_kind,
381                    row.x_benchmark_id,
382                    row.x_measurement_mode,
383                ])?;
384            }
385        }
386        tx.commit()?;
387        Ok(rows.len())
388    }
389
390    /// The number of rows currently persisted in [`usage_rows`](USAGE_ROWS_TABLE).
391    pub fn row_count(&self) -> Result<usize, StoreError> {
392        let count: i64 = self.conn.query_row(
393            &format!("SELECT COUNT(*) FROM {USAGE_ROWS_TABLE}"),
394            [],
395            |row| row.get(0),
396        )?;
397        Ok(count.max(0) as usize)
398    }
399
400    /// Faithfully reconstruct every persisted row back into a [`FocusRecord`], in
401    /// insertion order (T11 replay).
402    ///
403    /// For each row this rebuilds an [`UnpricedUsage`] from the whitelisted columns —
404    /// the three enums via [`LedgerLane::from_focus_str`] / [`TokenType::from_focus_str`]
405    /// / [`FocusAccessPath::from_focus_str`] (the single source of truth for the
406    /// string↔enum mapping; a malformed stored enum yields a typed
407    /// [`StoreError::Reconstruct`], never a panic or silent default) — calls
408    /// [`FocusRecord::unpriced_usage`] (which re-derives `charge_description` and the
409    /// always-null non-persisted FOCUS columns identically), then applies the stored
410    /// cost/pricing overrides — the full cost set (`billed_cost` / `effective_cost` /
411    /// `list_cost` / `contracted_cost` / `pricing_currency_effective_cost`), the
412    /// catalog-priced quantity/unit-price columns (`consumed_quantity` /
413    /// `pricing_quantity` / `list_unit_price` / `contracted_unit_price` /
414    /// `pricing_currency_list_unit_price` / `pricing_currency_contracted_unit_price`),
415    /// `x_estimated` / `x_pricing_status` / `x_consumed_tokens`, and the stored SKU +
416    /// pricing identifiers (`sku_id` / `sku_price_id` / `sku_meter` / `pricing_category`
417    /// / `pricing_unit`) — so a **source-priced cloud row** OR a **catalog-priced
418    /// dev-tool row** (`x_estimated = false`, `x_pricing_status = "priced"`, a real cost,
419    /// populated unit-price/quantity columns) reconstructs faithfully rather than
420    /// collapsing to the unpriced default.
421    ///
422    /// The store names no `costroid-core` type: the replay-aggregate + export round-trip
423    /// is the caller's (apps/cli) job — this method only rebuilds the records.
424    pub fn all_focus_rows(&self) -> Result<Vec<FocusRecord>, StoreError> {
425        let mut stmt = self.conn.prepare(&format!(
426            "SELECT charge_period_start, x_lane, x_tool, x_model, x_token_type, \
427                x_access_path, x_pricing_status, x_estimated, x_project, billed_cost, \
428                effective_cost, list_cost, contracted_cost, \
429                pricing_currency_effective_cost, x_consumed_tokens, billing_currency, \
430                consumed_quantity, pricing_quantity, list_unit_price, \
431                contracted_unit_price, pricing_currency_list_unit_price, \
432                pricing_currency_contracted_unit_price, service_name, \
433                service_provider_name, host_provider_name, invoice_issuer_name, sku_id, \
434                sku_price_id, sku_meter, pricing_category, pricing_unit, \
435                x_focus_input_version, x_sidechain, x_attribution_confidence, \
436                x_collector_version, x_pricing_snapshot_id, x_inference_profile_id, \
437                x_measured_wh, x_avg_power_watts, x_hardware_profile, \
438                x_amortized_hw_cost, x_runtime_kind, x_benchmark_id, x_measurement_mode \
439             FROM {USAGE_ROWS_TABLE} ORDER BY id"
440        ))?;
441
442        let mut records = Vec::new();
443        let mut query = stmt.query([])?;
444        while let Some(row) = query.next()? {
445            records.push(Self::reconstruct_row(row)?);
446        }
447        Ok(records)
448    }
449
450    /// Reconstruct a single SQLite row into a [`FocusRecord`] (see [`all_focus_rows`]).
451    /// Every fallible step (enum parse, timestamp parse, decimal parse) maps to a typed
452    /// [`StoreError`] — no `unwrap`/`expect`/`panic!`, no silent default.
453    fn reconstruct_row(row: &rusqlite::Row<'_>) -> Result<FocusRecord, StoreError> {
454        // Columns in the SELECT order above.
455        let charge_period_start: String = row.get(0)?;
456        let x_lane: String = row.get(1)?;
457        let x_tool: String = row.get(2)?;
458        let x_model: String = row.get(3)?;
459        let x_token_type: String = row.get(4)?;
460        let x_access_path: String = row.get(5)?;
461        let x_pricing_status: String = row.get(6)?;
462        let x_estimated: i64 = row.get(7)?;
463        let x_project: Option<String> = row.get(8)?;
464        let billed_cost: String = row.get(9)?;
465        let effective_cost: String = row.get(10)?;
466        let list_cost: String = row.get(11)?;
467        let contracted_cost: String = row.get(12)?;
468        let pricing_currency_effective_cost: String = row.get(13)?;
469        let x_consumed_tokens: String = row.get(14)?;
470        let billing_currency: String = row.get(15)?;
471        let consumed_quantity: Option<String> = row.get(16)?;
472        let pricing_quantity: Option<String> = row.get(17)?;
473        let list_unit_price: Option<String> = row.get(18)?;
474        let contracted_unit_price: Option<String> = row.get(19)?;
475        let pricing_currency_list_unit_price: Option<String> = row.get(20)?;
476        let pricing_currency_contracted_unit_price: Option<String> = row.get(21)?;
477        let service_name: String = row.get(22)?;
478        let service_provider_name: String = row.get(23)?;
479        let host_provider_name: String = row.get(24)?;
480        let invoice_issuer_name: String = row.get(25)?;
481        let sku_id: Option<String> = row.get(26)?;
482        let sku_price_id: Option<String> = row.get(27)?;
483        let sku_meter: Option<String> = row.get(28)?;
484        let pricing_category: Option<String> = row.get(29)?;
485        let pricing_unit: Option<String> = row.get(30)?;
486        let x_focus_input_version: Option<String> = row.get(31)?;
487        let x_sidechain: i64 = row.get(32)?;
488        let x_attribution_confidence: String = row.get(33)?;
489        let x_collector_version: String = row.get(34)?;
490        let x_pricing_snapshot_id: Option<String> = row.get(35)?;
491        let x_inference_profile_id: Option<String> = row.get(36)?;
492        // Local-inference economics (M3): decimal columns as strings (parsed below), the
493        // id/enum-ish columns verbatim. Null off the local lane.
494        let x_measured_wh: Option<String> = row.get(37)?;
495        let x_avg_power_watts: Option<String> = row.get(38)?;
496        let x_hardware_profile: Option<String> = row.get(39)?;
497        let x_amortized_hw_cost: Option<String> = row.get(40)?;
498        let x_runtime_kind: Option<String> = row.get(41)?;
499        let x_benchmark_id: Option<String> = row.get(42)?;
500        let x_measurement_mode: Option<String> = row.get(43)?;
501
502        // Enums via the single-source-of-truth inverse: a malformed stored enum is a
503        // typed Reconstruct error, never a panic or a silent default.
504        let lane = LedgerLane::from_focus_str(&x_lane)
505            .ok_or_else(|| StoreError::Reconstruct(format!("unknown x_lane `{x_lane}`")))?;
506        let token_type = TokenType::from_focus_str(&x_token_type).ok_or_else(|| {
507            StoreError::Reconstruct(format!("unknown x_token_type `{x_token_type}`"))
508        })?;
509        let access_path = FocusAccessPath::from_focus_str(&x_access_path).ok_or_else(|| {
510            StoreError::Reconstruct(format!("unknown x_access_path `{x_access_path}`"))
511        })?;
512
513        // Timestamp: RFC 3339 (UTC) back to a DateTime<Utc>.
514        let timestamp = DateTime::parse_from_rfc3339(&charge_period_start)
515            .map_err(|err| {
516                StoreError::Reconstruct(format!(
517                    "unparseable charge_period_start `{charge_period_start}`: {err}"
518                ))
519            })?
520            .with_timezone(&Utc);
521
522        // Decimals: the exact decimal strings back to `Decimal` (never via f64).
523        let billed = parse_decimal("billed_cost", &billed_cost)?;
524        let effective = parse_decimal("effective_cost", &effective_cost)?;
525        let list = parse_decimal("list_cost", &list_cost)?;
526        let contracted = parse_decimal("contracted_cost", &contracted_cost)?;
527        let pricing_currency_effective = parse_decimal(
528            "pricing_currency_effective_cost",
529            &pricing_currency_effective_cost,
530        )?;
531        // Nullable decimals: NULL → None; a present (non-null) value parses exactly or
532        // fails closed (a stored Some that won't parse is malformed data, never legit).
533        let consumed_qty = parse_decimal_opt("consumed_quantity", &consumed_quantity)?;
534        let pricing_qty = parse_decimal_opt("pricing_quantity", &pricing_quantity)?;
535        let list_unit = parse_decimal_opt("list_unit_price", &list_unit_price)?;
536        let contracted_unit = parse_decimal_opt("contracted_unit_price", &contracted_unit_price)?;
537        let pricing_currency_list_unit = parse_decimal_opt(
538            "pricing_currency_list_unit_price",
539            &pricing_currency_list_unit_price,
540        )?;
541        let pricing_currency_contracted_unit = parse_decimal_opt(
542            "pricing_currency_contracted_unit_price",
543            &pricing_currency_contracted_unit_price,
544        )?;
545        let consumed = parse_decimal("x_consumed_tokens", &x_consumed_tokens)?;
546        // `UnpricedUsage::token_count` is a u64; the persisted token count is a whole
547        // decimal. Convert exactly (no fractional tokens) and fail closed otherwise.
548        let token_count = decimal_to_u64("x_consumed_tokens", &consumed)?;
549
550        let input = UnpricedUsage {
551            lane,
552            timestamp,
553            tool: x_tool,
554            model: x_model,
555            token_type,
556            token_count,
557            project: x_project,
558            access_path,
559            service_name,
560            service_provider_name,
561            host_provider_name,
562            invoice_issuer_name,
563            billing_currency,
564        };
565
566        let mut record = FocusRecord::unpriced_usage(input)?;
567        // Apply the stored overrides so a source-priced row reconstructs faithfully —
568        // `unpriced_usage` defaults cost=0 / x_estimated=true / x_pricing_status="missing_price".
569        record.billed_cost = billed;
570        record.effective_cost = effective;
571        // The remaining priced cost columns: `cloud_usage_to_focus`/`apply_pricing` stamp
572        // these on a priced row; restore them verbatim so a real priced row no longer
573        // reverts to the unpriced 0 (the fidelity bug this fix closes).
574        record.list_cost = list;
575        record.contracted_cost = contracted;
576        record.pricing_currency_effective_cost = pricing_currency_effective;
577        // The catalog-priced quantity/unit-price columns (nullable): None on an unpriced
578        // row, Some on a priced one. Restore verbatim.
579        record.consumed_quantity = consumed_qty;
580        record.pricing_quantity = pricing_qty;
581        record.list_unit_price = list_unit;
582        record.contracted_unit_price = contracted_unit;
583        record.pricing_currency_list_unit_price = pricing_currency_list_unit;
584        record.pricing_currency_contracted_unit_price = pricing_currency_contracted_unit;
585        record.x_estimated = x_estimated != 0;
586        record.x_pricing_status = x_pricing_status;
587        // x_consumed_tokens is re-derived as Decimal::from(token_count); apply the stored
588        // decimal verbatim so scale/representation match exactly.
589        record.x_consumed_tokens = consumed;
590        // SKU / pricing identifiers are persisted (nullable); apply them verbatim rather
591        // than keeping the unpriced-default derivation, so a priced row's SKU + pricing
592        // category/unit round-trip.
593        record.sku_id = sku_id;
594        record.sku_price_id = sku_price_id;
595        record.sku_meter = sku_meter;
596        record.pricing_category = pricing_category;
597        record.pricing_unit = pricing_unit;
598        // Import provenance (nullable): None on a non-imported row, Some("1.2") on a
599        // FOCUS-v1.2-imported one. Restore verbatim so an imported row round-trips.
600        record.x_focus_input_version = x_focus_input_version;
601        // Collector attribution taxonomy: restore verbatim so a sidechain/uncertain row
602        // (and the collector version that minted it) round-trips instead of reverting to
603        // the unpriced_usage defaults (false / "confident" / current version).
604        record.x_sidechain = x_sidechain != 0;
605        record.x_attribution_confidence = x_attribution_confidence;
606        record.x_collector_version = x_collector_version;
607        // Pricing provenance (nullable): None on a source-priced/unpriced row, Some on an
608        // estimated one. Restore verbatim so the snapshot stamp round-trips (R8).
609        record.x_pricing_snapshot_id = x_pricing_snapshot_id;
610        // Bedrock inference-profile id (nullable): None off-Bedrock. Restore verbatim.
611        record.x_inference_profile_id = x_inference_profile_id;
612        // Local-inference economics (M3, nullable): None off the local lane. The decimal
613        // columns parse exactly (fail closed on a malformed stored Some); the id/enum-ish
614        // columns restore verbatim. So a `local_inference` row round-trips faithfully.
615        record.x_measured_wh = parse_decimal_opt("x_measured_wh", &x_measured_wh)?;
616        record.x_avg_power_watts = parse_decimal_opt("x_avg_power_watts", &x_avg_power_watts)?;
617        record.x_amortized_hw_cost =
618            parse_decimal_opt("x_amortized_hw_cost", &x_amortized_hw_cost)?;
619        record.x_hardware_profile = x_hardware_profile;
620        record.x_runtime_kind = x_runtime_kind;
621        record.x_benchmark_id = x_benchmark_id;
622        record.x_measurement_mode = x_measurement_mode;
623
624        Ok(record)
625    }
626
627    /// The `x_lane` value of every persisted row, in insertion order — a minimal
628    /// read-back proving the whitelisted metadata round-trips. (Full `FocusRecord`
629    /// reconstruction is [`all_focus_rows`].)
630    pub fn stored_lanes(&self) -> Result<Vec<String>, StoreError> {
631        let mut stmt = self.conn.prepare(&format!(
632            "SELECT x_lane FROM {USAGE_ROWS_TABLE} ORDER BY id"
633        ))?;
634        let rows = stmt.query_map([], |row| row.get::<_, String>(0))?;
635        let mut lanes = Vec::new();
636        for lane in rows {
637            lanes.push(lane?);
638        }
639        Ok(lanes)
640    }
641
642    /// The `billed_cost` decimal string of every persisted row, in insertion order — a
643    /// minimal read-back proving costs round-trip as exact decimal strings (never
644    /// floats).
645    pub fn stored_billed_costs(&self) -> Result<Vec<String>, StoreError> {
646        let mut stmt = self.conn.prepare(&format!(
647            "SELECT billed_cost FROM {USAGE_ROWS_TABLE} ORDER BY id"
648        ))?;
649        let rows = stmt.query_map([], |row| row.get::<_, String>(0))?;
650        let mut costs = Vec::new();
651        for cost in rows {
652            costs.push(cost?);
653        }
654        Ok(costs)
655    }
656}
657
658/// Parse a persisted decimal-string column back into a [`Decimal`] (exact, never via
659/// `f64`), mapping a malformed value to a typed [`StoreError::Reconstruct`].
660fn parse_decimal(column: &str, value: &str) -> Result<Decimal, StoreError> {
661    Decimal::from_str(value)
662        .map_err(|err| StoreError::Reconstruct(format!("unparseable {column} `{value}`: {err}")))
663}
664
665/// Parse a persisted *nullable* decimal-string column: SQL `NULL` → `None`, a present
666/// value through [`parse_decimal`] (exact, never via `f64`; malformed → typed
667/// [`StoreError::Reconstruct`]). Mirrors the FOCUS `Option<Decimal>` columns.
668fn parse_decimal_opt(column: &str, value: &Option<String>) -> Result<Option<Decimal>, StoreError> {
669    match value {
670        Some(text) => Ok(Some(parse_decimal(column, text)?)),
671        None => Ok(None),
672    }
673}
674
675/// Render a nullable [`Decimal`] column for persistence: `Some(d)` → its exact decimal
676/// string (never via `f64`), `None` → SQL `NULL`. The exact inverse of
677/// [`parse_decimal_opt`], so an `Option<Decimal>` column round-trips byte-identically.
678fn decimal_opt_to_string(value: &Option<Decimal>) -> Option<String> {
679    value.as_ref().map(Decimal::to_string)
680}
681
682/// Convert a persisted token-count decimal to the `u64` [`UnpricedUsage::token_count`]
683/// expects. Token counts are whole non-negative integers; a fractional or out-of-range
684/// value fails closed (it would be malformed stored data, never legitimate).
685fn decimal_to_u64(column: &str, value: &Decimal) -> Result<u64, StoreError> {
686    use rust_decimal::prelude::ToPrimitive;
687    if value.fract() != Decimal::ZERO {
688        return Err(StoreError::Reconstruct(format!(
689            "{column} `{value}` is not a whole token count"
690        )));
691    }
692    value.to_u64().ok_or_else(|| {
693        StoreError::Reconstruct(format!(
694            "{column} `{value}` is out of range for a token count"
695        ))
696    })
697}
698
699#[cfg(test)]
700mod tests {
701    // `super::*` already re-exports `DateTime`/`Utc`, the FOCUS enums + `UnpricedUsage` +
702    // `FocusRecord`, and `Decimal` (all now used by the reconstruction path), so the test
703    // module only adds the chrono builders + the billing-currency constant.
704    use super::*;
705    use chrono::{LocalResult, TimeZone};
706    use costroid_focus::DEFAULT_BILLING_CURRENCY;
707
708    fn record(lane: LedgerLane, billed_cents: i64) -> FocusRecord {
709        let timestamp = match Utc.with_ymd_and_hms(2026, 1, 15, 12, 34, 56) {
710            LocalResult::Single(value) => value,
711            LocalResult::Ambiguous(_, _) | LocalResult::None => {
712                panic!("test timestamp should be valid")
713            }
714        };
715        let input = UnpricedUsage {
716            lane,
717            timestamp,
718            tool: "codex".to_string(),
719            model: "example-model".to_string(),
720            token_type: TokenType::Input,
721            token_count: 1_500,
722            project: Some("/work/project".to_string()),
723            access_path: FocusAccessPath::Subscription,
724            service_name: "Codex".to_string(),
725            service_provider_name: "OpenAI".to_string(),
726            host_provider_name: "OpenAI".to_string(),
727            invoice_issuer_name: "OpenAI".to_string(),
728            billing_currency: DEFAULT_BILLING_CURRENCY.to_string(),
729        };
730        let Ok(mut rec) = FocusRecord::unpriced_usage(input) else {
731            panic!("record should build");
732        };
733        // Override the (default-zero) cost to a non-trivial decimal so the round-trip is
734        // non-vacuous: cents -> dollars (e.g. 1234 -> "12.34").
735        let billed = Decimal::new(billed_cents, 2);
736        rec.billed_cost = billed;
737        rec.effective_cost = billed;
738        rec
739    }
740
741    /// R4 — the Cardinal Rule, fail-closed. The live DDL (with the SQLite type keywords
742    /// removed, so the unavoidable `TEXT`/`INTEGER` column types don't false-positive on
743    /// the `text` substring) must contain NONE of the content-bearing substrings, and
744    /// every real column must be in the documented allowlist (so a column added to the
745    /// DDL without review fails this test).
746    #[test]
747    fn r4_schema_forbids_free_text_columns_and_is_allowlist_bounded() {
748        // Strip the SQL type tokens: R4 forbids content-bearing *column names*, not the
749        // SQLite `TEXT` type the metadata columns are necessarily stored as.
750        let ddl = usage_rows_ddl()
751            .to_lowercase()
752            .replace("text", "")
753            .replace("integer", "");
754        for forbidden in FORBIDDEN_SUBSTRINGS {
755            // `text` is checked against column names below, not the type-stripped DDL.
756            if *forbidden == "text" {
757                continue;
758            }
759            assert!(
760                !ddl.contains(forbidden),
761                "R4 violation: usage_rows DDL contains forbidden substring `{forbidden}`:\n{ddl}"
762            );
763        }
764
765        // Every real column (read from the live SQLite schema) must be in the allowlist.
766        let Ok(store) = Store::open_in_memory() else {
767            panic!("in-memory store should open");
768        };
769        let Ok(mut stmt) = store
770            .conn
771            .prepare(&format!("PRAGMA table_info({USAGE_ROWS_TABLE})"))
772        else {
773            panic!("table_info pragma should prepare");
774        };
775        let Ok(rows) = stmt.query_map([], |row| row.get::<_, String>(1)) else {
776            panic!("table_info should query");
777        };
778        let mut columns = Vec::new();
779        for col in rows {
780            let Ok(col) = col else {
781                panic!("column name should read");
782            };
783            columns.push(col);
784        }
785
786        let allow: std::collections::BTreeSet<&str> = USAGE_ROWS_COLUMNS.iter().copied().collect();
787        for col in &columns {
788            // `id` is the synthetic primary key, not a metadata column.
789            if col == "id" {
790                continue;
791            }
792            // No column name may contain a content-bearing substring (this is where the
793            // `text` rule actually bites — e.g. it forbids any `*_text` column).
794            let lower = col.to_lowercase();
795            for forbidden in FORBIDDEN_SUBSTRINGS {
796                assert!(
797                    !lower.contains(forbidden),
798                    "R4 violation: column `{col}` contains forbidden substring `{forbidden}`"
799                );
800            }
801            assert!(
802                allow.contains(col.as_str()),
803                "fail-closed: column `{col}` is in the DDL but NOT in USAGE_ROWS_COLUMNS — \
804                 review it (does it carry content?) before allowlisting it"
805            );
806        }
807        // And the allowlist is non-vacuous / actually realized (no typo'd entry that the
808        // DDL never creates).
809        let real: std::collections::BTreeSet<&str> = columns.iter().map(String::as_str).collect();
810        for allowed in USAGE_ROWS_COLUMNS {
811            assert!(
812                real.contains(allowed),
813                "allowlist column `{allowed}` is not present in the live usage_rows schema"
814            );
815        }
816    }
817
818    /// R4 + faithfulness forcing function (T16): the store's persist-or-drop decision over
819    /// `FocusRecord` is COMPILE-TIME exhaustive. Destructures every field with NO `..`, so
820    /// adding a field to `FocusRecord` fails to COMPILE here (`E0027`) until a human comes
821    /// to this site and consciously decides: PERSIST it (add to `USAGE_ROWS_COLUMNS` + the
822    /// DDL + `ingest` + `reconstruct_row`) or DROP it (re-derived/null on replay). This is
823    /// the exact bug class T11 hit — the store silently dropping a `FocusRecord` field —
824    /// converted from a runtime surprise into a forced compile-time review.
825    #[test]
826    fn store_persist_or_drop_decision_is_field_exhaustive_over_focus_record() {
827        let FocusRecord {
828            // PERSISTED (restored verbatim on replay) — keep in lockstep with
829            // USAGE_ROWS_COLUMNS / ingest / reconstruct_row.
830            billed_cost: _,
831            effective_cost: _,
832            list_cost: _,
833            contracted_cost: _,
834            pricing_currency_effective_cost: _,
835            billing_currency: _,
836            charge_period_start: _,
837            consumed_quantity: _,
838            pricing_quantity: _,
839            list_unit_price: _,
840            contracted_unit_price: _,
841            pricing_currency_list_unit_price: _,
842            pricing_currency_contracted_unit_price: _,
843            service_name: _,
844            service_provider_name: _,
845            host_provider_name: _,
846            invoice_issuer_name: _,
847            sku_id: _,
848            sku_price_id: _,
849            sku_meter: _,
850            pricing_category: _,
851            pricing_unit: _,
852            x_lane: _,
853            x_model: _,
854            x_token_type: _,
855            x_access_path: _,
856            x_estimated: _,
857            x_tool: _,
858            x_project: _,
859            x_pricing_status: _,
860            x_consumed_tokens: _,
861            x_focus_input_version: _,
862            x_sidechain: _,
863            x_attribution_confidence: _,
864            x_collector_version: _,
865            x_pricing_snapshot_id: _,
866            x_inference_profile_id: _,
867            // Local-inference economics (M3): PERSISTED — bounded decimal/id/enum columns,
868            // restored verbatim on replay (in lockstep with USAGE_ROWS_COLUMNS / ingest /
869            // reconstruct_row). Null off the local lane.
870            x_measured_wh: _,
871            x_avg_power_watts: _,
872            x_hardware_profile: _,
873            x_amortized_hw_cost: _,
874            x_runtime_kind: _,
875            x_benchmark_id: _,
876            x_measurement_mode: _,
877            // INTENTIONALLY DROPPED — re-derived identically by `unpriced_usage` on replay
878            // (so the round-trip stays byte-identical) OR a free-text-capable / non-derivable
879            // FOCUS column that R4 forbids the store from retaining at all.
880            billing_account_id: _,           // re-derived (placeholder const)
881            billing_account_name: _,         // re-derived (placeholder const)
882            billing_account_type: _,         // re-derived (placeholder const)
883            billing_period_start: _,         // re-derived from charge_period_start
884            billing_period_end: _,           // re-derived from charge_period_start
885            charge_period_end: _,            // re-derived (start + 1s)
886            charge_category: _,              // re-derived (const "Usage")
887            charge_class: _,                 // re-derived (None)
888            charge_description: _,           // re-derived "{model} {token_type} tokens"
889            charge_frequency: _,             // re-derived (const)
890            service_category: _,             // re-derived (const)
891            service_subcategory: _,          // re-derived (const)
892            provider_name: _,                // re-derived (mirrors service_provider_name)
893            publisher_name: _,               // re-derived (mirrors invoice_issuer_name)
894            invoice_id: _,                   // re-derived (None)
895            sku_price_details: _,            // DROPPED, R4: free-text-capable
896            pricing_currency: _,             // re-derived (== billing_currency)
897            consumed_unit: _,                // re-derived (const "tokens")
898            commitment_discount_category: _, // re-derived (None)
899            commitment_discount_id: _,       // re-derived (None)
900            commitment_discount_name: _,     // re-derived (None)
901            commitment_discount_quantity: _, // re-derived (None)
902            commitment_discount_status: _,   // re-derived (None)
903            commitment_discount_type: _,     // re-derived (None)
904            commitment_discount_unit: _,     // re-derived (None)
905            capacity_reservation_id: _,      // re-derived (None)
906            capacity_reservation_status: _,  // re-derived (None)
907            region_id: _,                    // re-derived (None)
908            region_name: _,                  // re-derived (None)
909            availability_zone: _,            // re-derived (None)
910            resource_id: _,                  // DROPPED, R4: free-text-capable
911            resource_name: _,                // DROPPED, R4: free-text-capable
912            resource_type: _,                // re-derived (None)
913            sub_account_id: _,               // re-derived (None)
914            sub_account_name: _,             // re-derived (None)
915            sub_account_type: _,             // re-derived (None)
916            tags: _,                         // DROPPED, R4: free-text-capable
917            contract_applied: _,             // re-derived (None)
918            allocated_method_id: _,          // re-derived (None)
919            allocated_method_details: _,     // DROPPED, R4: free-text-capable
920            allocated_resource_id: _,        // re-derived (None)
921            allocated_resource_name: _,      // DROPPED, R4: free-text-capable
922            allocated_tags: _,               // DROPPED, R4: free-text-capable
923        } = record(LedgerLane::DeveloperTool, 0);
924    }
925
926    /// Ingest round-trip (metadata only): build several records, ingest, and prove the
927    /// whitelisted lanes + costs persisted exactly.
928    #[test]
929    fn ingest_round_trips_whitelisted_metadata() {
930        let Ok(store) = Store::open_in_memory() else {
931            panic!("in-memory store should open");
932        };
933
934        let rows = [
935            record(LedgerLane::DeveloperTool, 1_234), // "12.34"
936            record(LedgerLane::CloudApi, 50),         // "0.50"
937            record(LedgerLane::LocalInference, 0),    // "0"
938        ];
939
940        let Ok(count) = store.ingest(&rows) else {
941            panic!("ingest should succeed");
942        };
943        assert_eq!(count, 3);
944
945        let Ok(total) = store.row_count() else {
946            panic!("row_count should succeed");
947        };
948        assert_eq!(total, 3);
949
950        let Ok(lanes) = store.stored_lanes() else {
951            panic!("stored_lanes should succeed");
952        };
953        assert_eq!(
954            lanes,
955            vec![
956                "developer_tool".to_string(),
957                "cloud_api".to_string(),
958                "local_inference".to_string(),
959            ]
960        );
961
962        let Ok(costs) = store.stored_billed_costs() else {
963            panic!("stored_billed_costs should succeed");
964        };
965        // Costs round-trip as exact decimal strings (never floats). The decimals keep
966        // their scale (cents -> two fractional digits), so 0 cents is "0.00".
967        assert_eq!(
968            costs,
969            vec!["12.34".to_string(), "0.50".to_string(), "0.00".to_string()]
970        );
971    }
972
973    /// A second ingest appends (transaction-per-call), and the count reflects both.
974    #[test]
975    fn ingest_appends_across_calls() {
976        let Ok(store) = Store::open_in_memory() else {
977            panic!("in-memory store should open");
978        };
979        let Ok(_) = store.ingest(&[record(LedgerLane::DeveloperTool, 100)]) else {
980            panic!("first ingest should succeed");
981        };
982        let Ok(_) = store.ingest(&[
983            record(LedgerLane::CloudApi, 200),
984            record(LedgerLane::CloudApi, 300),
985        ]) else {
986            panic!("second ingest should succeed");
987        };
988        let Ok(total) = store.row_count() else {
989            panic!("row_count should succeed");
990        };
991        assert_eq!(total, 3);
992    }
993
994    /// A **catalog-priced** row mirroring the dominant `apply_pricing` shape: a real,
995    /// priced charge (not an estimate) with EVERY now-persisted priced column set to a
996    /// non-default value — the full cost set (`list_cost`/`contracted_cost`/
997    /// `pricing_currency_effective_cost`), the catalog quantity/unit-price columns
998    /// (`consumed_quantity`/`pricing_quantity`/`list_unit_price`/`contracted_unit_price`/
999    /// the two `pricing_currency_*_unit_price`), and the `sku_price_id`/`pricing_category`/
1000    /// `pricing_unit` identifiers. Built by hand (the store crate cannot depend on
1001    /// `costroid-core`'s `apply_pricing`); the byte-identical-via-`export_focus_csv` proof
1002    /// over a *real* `apply_pricing` row lives in `apps/cli/tests/store_replay.rs`. This is
1003    /// the row whose faithful reconstruction the deciding test below turns on: it must NOT
1004    /// collapse to the unpriced default `unpriced_usage` produces — which, before this fix,
1005    /// silently reverted these columns to 0/None.
1006    fn priced_cloud_record() -> FocusRecord {
1007        let timestamp = match Utc.with_ymd_and_hms(2026, 2, 3, 9, 0, 0) {
1008            LocalResult::Single(value) => value,
1009            LocalResult::Ambiguous(_, _) | LocalResult::None => {
1010                panic!("test timestamp should be valid")
1011            }
1012        };
1013        let input = UnpricedUsage {
1014            lane: LedgerLane::CloudApi,
1015            timestamp,
1016            tool: "anthropic-api".to_string(),
1017            model: "claude-opus".to_string(),
1018            token_type: TokenType::Output,
1019            token_count: 4_096,
1020            project: None,
1021            access_path: FocusAccessPath::Api,
1022            service_name: "Anthropic API".to_string(),
1023            service_provider_name: "Anthropic".to_string(),
1024            host_provider_name: "Anthropic".to_string(),
1025            invoice_issuer_name: "Anthropic".to_string(),
1026            billing_currency: DEFAULT_BILLING_CURRENCY.to_string(),
1027        };
1028        let Ok(mut rec) = FocusRecord::unpriced_usage(input) else {
1029            panic!("priced cloud record should build");
1030        };
1031        // Priced: a real cost, NOT an estimate. Set EVERY now-persisted priced column to a
1032        // value distinct from the unpriced default (0 / None) so the round-trip is
1033        // non-vacuous — a regression to the lossy behavior (these reverting to 0/None)
1034        // fails the equality below.
1035        let cost = Decimal::new(12_345, 4); // 1.2345
1036        rec.billed_cost = cost;
1037        rec.effective_cost = cost;
1038        rec.list_cost = cost;
1039        rec.contracted_cost = cost;
1040        rec.pricing_currency_effective_cost = cost;
1041        // Catalog quantity/unit-price columns — non-default (the unpriced default is None).
1042        let quantity = Decimal::from(4_096);
1043        let per_token = Decimal::new(15, 8); // 0.00000015 — a per-token unit price
1044        rec.consumed_quantity = Some(quantity);
1045        rec.pricing_quantity = Some(quantity);
1046        rec.list_unit_price = Some(per_token);
1047        rec.contracted_unit_price = Some(per_token);
1048        rec.pricing_currency_list_unit_price = Some(per_token);
1049        rec.pricing_currency_contracted_unit_price = Some(per_token);
1050        // SKU + pricing identifiers — non-default (sku_price_id/pricing_category/pricing_unit
1051        // are None on an unpriced row).
1052        rec.sku_price_id = Some("claude-opus:output:standard".to_string());
1053        rec.pricing_category = Some("Standard".to_string());
1054        rec.pricing_unit = Some("tokens".to_string());
1055        rec.x_estimated = false;
1056        rec.x_pricing_status = "priced".to_string();
1057        // Import provenance — a cloud row imported from a FOCUS v1.2 export. Non-default
1058        // (None on a directly-collected row) so the round-trip below is non-vacuous.
1059        rec.x_focus_input_version = Some("1.2".to_string());
1060        // A DISTINCT (non-current) collector version — proves the round-trip restores the
1061        // STORED value, not the current COLLECTOR_VERSION const (a row minted by an older
1062        // Costroid must replay as that older version).
1063        rec.x_collector_version = "0.5.0-test".to_string();
1064        rec
1065    }
1066
1067    /// R4-faithful round-trip (the deciding T11 test): ingest a Vec mixing a developer_tool
1068    /// row AND a fully priced row (every now-persisted priced column set non-default),
1069    /// replay via `all_focus_rows`, and assert the reconstructed rows EQUAL the originals
1070    /// (full `==`). The M1 row types leave every *non-persisted* FOCUS column
1071    /// `None`/derived-identical on both sides (both are built through `unpriced_usage`,
1072    /// which re-derives `charge_description` identically), so the equality is exact, not a
1073    /// persisted-subset compromise — and the persisted priced columns now round-trip
1074    /// instead of reverting to 0/None.
1075    #[test]
1076    fn all_focus_rows_round_trips_records_faithfully_including_priced_cloud() {
1077        let Ok(store) = Store::open_in_memory() else {
1078            panic!("in-memory store should open");
1079        };
1080
1081        // A sidechain (sub-agent) dev-tool row: non-default x_sidechain + uncertain
1082        // attribution, so the collector taxonomy round-trip is non-vacuous.
1083        let mut sidechain_dev = record(LedgerLane::DeveloperTool, 1_234); // estimated, "12.34"
1084        sidechain_dev.x_sidechain = true;
1085        sidechain_dev.x_attribution_confidence = "uncertain".to_string();
1086        // An ESTIMATED row carries the pricing-snapshot stamp (R8); set it non-default so
1087        // its round-trip is non-vacuous (the source-priced cloud row below keeps None).
1088        sidechain_dev.x_pricing_snapshot_id = Some("litellm@2026-06-18#36c8994e".to_string());
1089
1090        // A `local_inference`-lane row (M3): the 7 local economics columns set non-default so
1091        // their round-trip is non-vacuous (they are None on the dev-tool + cloud rows above).
1092        let mut local = record(LedgerLane::LocalInference, 0);
1093        local.x_measured_wh = Some(Decimal::new(44, 4)); // 0.0044 Wh
1094        local.x_avg_power_watts = Some(Decimal::new(1600, 1)); // 160.0 W
1095        local.x_hardware_profile = Some("strix-halo-128gb@2026-06-20".to_string());
1096        local.x_amortized_hw_cost = Some(Decimal::new(21, 4)); // 0.0021
1097        local.x_runtime_kind = Some("ollama".to_string());
1098        local.x_benchmark_id = Some("gemma4-coding-v1".to_string());
1099        local.x_measurement_mode = Some("measured_wallmeter".to_string());
1100
1101        let originals = vec![
1102            sidechain_dev,         // estimated dev-tool sidechain row
1103            priced_cloud_record(), // source-priced cloud_api row
1104            local,                 // local_inference row with the 7 economics columns
1105        ];
1106
1107        let Ok(count) = store.ingest(&originals) else {
1108            panic!("ingest should succeed");
1109        };
1110        assert_eq!(count, 3);
1111
1112        let Ok(reconstructed) = store.all_focus_rows() else {
1113            panic!("all_focus_rows should succeed");
1114        };
1115
1116        // Full structural equality — replay reconstructs the records exactly.
1117        assert_eq!(reconstructed, originals);
1118
1119        // Non-vacuous: the priced row kept its real cost, "priced" status, not-estimated
1120        // flag, and cloud_api lane after the round-trip (it did NOT collapse to the
1121        // unpriced default).
1122        // The estimated dev-tool row's pricing-snapshot stamp survived replay (R8); the
1123        // source-priced cloud row carries no stamp (None) and stays None.
1124        assert_eq!(
1125            reconstructed[0].x_pricing_snapshot_id,
1126            Some("litellm@2026-06-18#36c8994e".to_string())
1127        );
1128        assert!(reconstructed[1].x_pricing_snapshot_id.is_none());
1129
1130        let cloud = &reconstructed[1];
1131        assert_eq!(cloud.x_lane, "cloud_api");
1132        assert_eq!(cloud.x_pricing_status, "priced");
1133        assert!(!cloud.x_estimated);
1134        assert_eq!(cloud.billed_cost, Decimal::new(12_345, 4));
1135        assert_eq!(cloud.effective_cost, Decimal::new(12_345, 4));
1136        assert_eq!(cloud.x_access_path, "api");
1137        assert_eq!(cloud.x_token_type, "output");
1138        assert_eq!(cloud.x_consumed_tokens, Decimal::from(4_096));
1139
1140        // The deciding assertions: every now-persisted priced column survived the
1141        // round-trip at its non-default value. Before this fix these reverted to the
1142        // unpriced default (0 / None) — so each of these would have failed.
1143        assert_eq!(cloud.list_cost, Decimal::new(12_345, 4));
1144        assert_eq!(cloud.contracted_cost, Decimal::new(12_345, 4));
1145        assert_eq!(
1146            cloud.pricing_currency_effective_cost,
1147            Decimal::new(12_345, 4)
1148        );
1149        let quantity = Decimal::from(4_096);
1150        let per_token = Decimal::new(15, 8);
1151        assert_eq!(cloud.consumed_quantity, Some(quantity));
1152        assert_eq!(cloud.pricing_quantity, Some(quantity));
1153        assert_eq!(cloud.list_unit_price, Some(per_token));
1154        assert_eq!(cloud.contracted_unit_price, Some(per_token));
1155        assert_eq!(cloud.pricing_currency_list_unit_price, Some(per_token));
1156        assert_eq!(
1157            cloud.pricing_currency_contracted_unit_price,
1158            Some(per_token)
1159        );
1160        assert_eq!(
1161            cloud.sku_price_id,
1162            Some("claude-opus:output:standard".to_string())
1163        );
1164        assert_eq!(cloud.pricing_category, Some("Standard".to_string()));
1165        assert_eq!(cloud.pricing_unit, Some("tokens".to_string()));
1166        assert_eq!(
1167            cloud.x_focus_input_version,
1168            Some("1.2".to_string()),
1169            "import provenance round-trips (not lost on replay)"
1170        );
1171        assert_eq!(
1172            cloud.x_collector_version, "0.5.0-test",
1173            "the STORED collector version is restored, not the current const"
1174        );
1175        // Guard the unpriced (dev-tool) row's null columns survived as null too — the
1176        // restore must not fabricate Some on a row where apply_pricing never ran.
1177        let dev = &reconstructed[0];
1178        assert_eq!(dev.pricing_quantity, None);
1179        assert_eq!(dev.sku_price_id, None);
1180        assert_eq!(dev.pricing_unit, None);
1181        assert_eq!(dev.list_cost, Decimal::ZERO);
1182        assert_eq!(
1183            dev.x_focus_input_version, None,
1184            "a directly-collected (non-imported) row stays None"
1185        );
1186        assert!(dev.x_sidechain, "the sidechain flag round-trips");
1187        assert_eq!(
1188            dev.x_attribution_confidence, "uncertain",
1189            "uncertain attribution round-trips (not reverted to the confident default)"
1190        );
1191        // The dev-tool + cloud rows carry no local-inference economics (null off-lane); a
1192        // restore must not fabricate Some here.
1193        assert_eq!(dev.x_measured_wh, None);
1194        assert_eq!(dev.x_measurement_mode, None);
1195        assert_eq!(cloud.x_avg_power_watts, None);
1196
1197        // The deciding M3-T3 assertions: every local-inference economics column survived the
1198        // round-trip at its non-default value (a missed store fan-out site would drop one).
1199        let local = &reconstructed[2];
1200        assert_eq!(local.x_lane, "local_inference");
1201        assert_eq!(local.x_measured_wh, Some(Decimal::new(44, 4)));
1202        assert_eq!(local.x_avg_power_watts, Some(Decimal::new(1600, 1)));
1203        assert_eq!(
1204            local.x_hardware_profile,
1205            Some("strix-halo-128gb@2026-06-20".to_string())
1206        );
1207        assert_eq!(local.x_amortized_hw_cost, Some(Decimal::new(21, 4)));
1208        assert_eq!(local.x_runtime_kind, Some("ollama".to_string()));
1209        assert_eq!(local.x_benchmark_id, Some("gemma4-coding-v1".to_string()));
1210        assert_eq!(
1211            local.x_measurement_mode,
1212            Some("measured_wallmeter".to_string())
1213        );
1214    }
1215
1216    /// A malformed stored enum (an `x_lane` with no `from_focus_str` inverse) yields a
1217    /// typed `StoreError::Reconstruct` on replay — never a panic or a silent default.
1218    #[test]
1219    fn all_focus_rows_fails_closed_on_a_malformed_stored_enum() {
1220        let Ok(store) = Store::open_in_memory() else {
1221            panic!("in-memory store should open");
1222        };
1223        let Ok(_) = store.ingest(&[record(LedgerLane::DeveloperTool, 100)]) else {
1224            panic!("ingest should succeed");
1225        };
1226        // Corrupt the persisted enum directly (bypassing the typed ingest path) to simulate
1227        // a malformed/garbage stored value a future migration or external write might leave.
1228        let Ok(_) = store.conn.execute(
1229            &format!("UPDATE {USAGE_ROWS_TABLE} SET x_lane = 'not_a_lane'"),
1230            [],
1231        ) else {
1232            panic!("update should succeed");
1233        };
1234
1235        match store.all_focus_rows() {
1236            Err(StoreError::Reconstruct(msg)) => {
1237                assert!(
1238                    msg.contains("x_lane"),
1239                    "error should name the bad column: {msg}"
1240                );
1241            }
1242            other => panic!("expected a Reconstruct error, got {other:?}"),
1243        }
1244    }
1245}