mirror of
https://github.com/SHOGGOTH-SECTOR/sica-fondt.git
synced 2026-08-02 17:03:25 +00:00
622b2bd73e
The economy organ was the least-documented named component in the architecture — one line in bus-topology.md, a Pony primitive, and a smoke-test wire. This adds 8 plan specs following the 10-section template: M0 hub, M1 ingestion, M2 digestion core (small-model), M3 cost ledger, M4 budget governor, M5 context yield, M6 provenance chain (S1/S2 compliance), M7 outer-bus exchange. Also updates the plans README index and integration DAG, and resolves bus-topology.md's open item about the organ's placement. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
64 lines
3.5 KiB
Markdown
64 lines
3.5 KiB
Markdown
# 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?).
|