reasonix

Overview ¶

Package reasonix implements an EVENT-LEVEL adapter for Reasonix (esengine/DeepSeek-Reasonix, MIT).

SURFACE. Reasonix ships a purpose-built usage ledger and this adapter reads that and nothing else:

${REASONIX_STATE_HOME:-${REASONIX_HOME:-~/.reasonix}}/stats/YYYY-MM-DD.jsonl

One append-only JSONL file per writer-local day, one record per completed request. The session transcripts under <root>/projects/**/sessions/ are deliberately NOT read: they carry prompts, reasoning and tool arguments, and they lack the exact counters these records carry. Reasonix's own registry entry says the same thing in the other direction — the transcript overlaps these records and is excluded.

CRITICAL: strictly observational. Files are opened O_RDONLY, never written, never locked, never rotated. Reasonix guards its own appends with <root>/stats/.append.lock; this adapter never touches it.

Records are EVENTS, not cumulative counters ¶

This is the bug class that eats OTEL-shaped and session-state surfaces, so it is settled by evidence rather than by shape. Two proofs, both from this machine:

1. Reasonix indexes its own stats files into a SQLite catalog whose record table is keyed PRIMARY KEY(file_path, byte_offset) with columns source/model_ref/provider/prompt/completion/reasoning/cache_hit/ cache_miss/total/requests/turns, and whose day rollup is built by SUMMING those columns. A cumulative re-export summed that way would be nonsense, so the vendor's own reader treats every line as a delta.
2. Two consecutive live records on this machine read prompt=6207 then prompt=5718. A running total does not go down.

So the collector adds these up; it never diffs them and never takes a max.

Identity is the LINE's CONTENT; the byte offset is only a gate ¶

The dedup key is a hash of the record's own bytes. It carries no path and no read position, so a re-read from zero — a lost checkpoint, a moved REASONIX_HOME, a symlinked root re-pointed — re-derives exactly the same keys and collapses in the store. A key minted from a byte offset would recount every line after any rewrite, and a position is not an identity.

Collision safety comes from the record itself: `ts` is RFC3339 with NANOSECOND precision and sits beside the full counter tuple, so two distinct requests cannot produce identical bytes. The only line that can collide with an already-stored line is a genuine duplicate write, which is exactly what deduplication is for. The trade is deliberate and in the conservative direction the ledger always takes: this can only ever UNDER-count, and an append-only ledger can never take an over-count back.

The byte offset survives as the incremental CHECKPOINT, where being wrong costs a re-read rather than a fact. Offsets are safe on THIS surface — daily files are append-only and every record is newline-terminated (the writer guards record boundaries) — unlike the re-read-in-full transcript surfaces, where a poll re-walks the whole tree and a position-derived key would recount on every pass. The checkpoint is trusted only on pure growth; a shrink or a same-size rewrite re-reads from zero.

Cost: the captured rows are unpriced ¶

The captured Ollama rows carry cost_complete=false and incomplete_reason="no_price", with no amount. This adapter stamps no cost: CostMicroUSD remains nil, and the pricing ladder can value the counters. The exact v1.25.3 writer can also emit optional quoted cost amounts and currencies. They are not mapped here; unknown currencies must never be interpreted as USD. See testdata/live-1.25.3.provenance.md for the versioned writer evidence and the captured surface's limits.

Names and counters ONLY ¶

The record shape is content-free by construction — no prompt, no result, no tool input, no cwd, not even a session id — and the decode is an ALLOW-LIST of the seventeen fields below, so a content field added upstream contributes nothing until this package is taught about it on purpose. Every string field read here is an enum or an identifier: a model ref, a surface name ("cli"), a status ("unavailable"), a reason ("no_price"). privacy.no_raw is satisfied by construction, not by a switch.