sica-fondt/core/docs/plans/M3-cost-ledger.md

M3 — Cost ledger

1. Component

The stomach's accounting book: records every resource expenditure across the economy organ and, optionally, across the organism. Every token spent on digestion (M2), every budget check (M4), every outer-bus exchange (M7) — the ledger knows. This is the "money" in "M for money": if it costs something, it's in the ledger.

2. Status / certainty

DESIGN-FIRST · ABSENT. No cost tracking exists anywhere in the system. A2 (energy driver) tracks an internal activation/rest budget but has no concept of external resource costs. Role C3; implementation C1.

3. Language & location

TBD · src/economy/ledger/ or similar. Needs durable-enough storage to survive a session (but the container is ephemeral, so "durable" means in-memory with optional flush — not a database). Could be R (to sit near A2), Pony (bus-native), or a simple append-only log.

4. Does / does-not

• Does: record every resource expenditure as a LedgerEntry (who spent, what action, how much, when); provide totals by organ, by action type, and grand total; answer "how much has been spent?" and "how much is left?" (the latter via M4's budget).
• Does-not: decide whether to spend (M4 governs that); price tools (A2 does); restrict actions (Ada D1 polices); optimize or suggest cheaper paths (that's a future concern, not a ledger's job).

5. Interface contract

• record(entry: LedgerEntry) -> receipt_id. LedgerEntry { organ_id, action, resource_type, amount, timestamp }. resource_type ∈ { input_tokens, output_tokens, compute_ms, api_call }.
• total(filter?) -> num — total spent, optionally filtered by organ/action/resource_type/time range.
• entries(filter?) -> [LedgerEntry] — raw entries for audit.
• The ledger is append-only at runtime — entries are never modified or deleted (the books don't get cooked). A session-start reset is fine (ephemeral container).

6. Dependencies & stubs

• M2 digestion core — primary cost source (reports actual_cost per digestion).
• M4 budget governor — reads totals to compute remaining budget; stub: the ledger is usable without M4 (it just records, doesn't enforce).
• A2 energy driver — potential consumer of cost data for pricing; stub: no integration initially.

7. Invariants / laws

• L1 (C4): the ledger is append-only — no entry is ever mutated or deleted at runtime.
• L2 (C4): completeness — every resource expenditure in the economy organ produces a ledger entry; no "off-books" spending.
• L3 (C3): the ledger is passive — it records, it never blocks or delays an action. Enforcement is M4's job.

8. Build steps

1. Define LedgerEntry shape and the append-only store (in-memory list; consider a ring buffer with a cap if memory is a concern in long sessions).
2. Wire M2 → M3 (digestion cost recording).
3. Implement total and entries queries with filtering.
4. Optional: flush to disk / log file for post-session audit.

9. Tests

Append: entries accumulate, count matches. Immutability: no mutation API exists. Totals: filtered totals match manual sum. Completeness: a mock M2 digestion produces a corresponding ledger entry.

10. Open items

• Whether the ledger scope extends beyond the economy organ to track costs for other organs (MoRAG model calls, SAE compute, Brain inference). Start organ-scoped; expand if needed.
• Storage cap / eviction policy for very long sessions (ring buffer vs unbounded).
• Post-session export format (JSON log? CSV?).