❄ Rime Ledger — Reference

rime-ledger

One house for every IP the Atelier pulls: one row per address, one append-only observation per time it was actually used. Built so that a proxy's history — which project spent it, how far the flow got, why it failed — lives in a single place every project can read, instead of being rediscovered per attempt.

Key Concepts

One row per IP, keyed by the address — ledger/ip-ledger.json is a JSON dict whose key is the IP.
history[] is the real record. The row's scalar fields (outcome, stage_reached, …) only mirror the latest observation, because that is what the other tool in the fleet reads. Every observation is kept forever inside history.
Append-only. Old rows are never rewritten. New facts arrive as new rows or new history entries.
Fresh is computed, not stored. "Fresh" means no observation with a real outcome — pulled, never spent. It is derived on demand so it cannot disagree with the ledger after an IP gets used.
The bridge is a symlink. ~/.rime_ip_ledger.json points at the house copy; it is a convenience path, not a second store.

Entry Points

tools/ledger.py — the CLI: observe, views, audit.
ip_ledger.py (in Tsuzuri's web/ip-ledger skill) — the older writer, whose field vocabulary this tool mirrors so rows from either tool look the same.

High-Level Architecture

A single JSON store is written by one CLI, read by another, and summarised into derived view files. Correctness rests on two things: never overwriting a row, and never letting the store and its views be produced by different truths. Detail in architecture.md.

Module Map

Module	Purpose
`tools`	the CLI — field vocabulary, atomic symlink-safe writes, observe/views/audit
`ledger`	the store itself: row shape, field meanings, the two auxiliary ledgers
`views`	derived summaries: fresh, reusable, by-project
`docs`	the charter, the house README, the field spec, and the hand-off documents

Getting Started

See getting-started.md.