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}