Skip to content

SOP-028 — Ledger upkeep (log a transaction)

Guide

<!-- last-reviewed: 2026-06-01 · owner: Finance (Financial Analyst) -->

SOP-028 — Ledger upkeep (log a transaction)

SOP · owner: Finance (Financial Analyst). Layer: SOP/Runbook (docs/canon.md). Field meanings live in docs/financial-system.md; column order is frozen in docs/units/finance/charter.md — not restated. Plan-phase note: finance/ledger-money.csv and finance/ledger-ai.csv do not exist yet; until the Plan→Build gate this runs against the planned schema.

Interface Contract

  • Inputs: money transaction / AI-usage event ← from <usage-data producer> · trigger: usage data ready
  • Inputs: approved cross-rate ← from Finance Director · trigger: spend approved
  • Outputs: updated ledger snapshot → to Archivist · trigger: artifact approved
  • Handoff trigger (in): a transaction is confirmed, or a usage-data feed is delivered, ready to record
  • Handoff trigger (out): the entry is written, verified present, and the ledger snapshot is ready for preservation
  • Definition of Done before handoff:
    • [ ] All required fields present (id, ts, ledger, unit_or_agent, venture, phase, type, qty, unit, usd_equiv, source, note) — no blanks, no guesses
    • [ ] For AI entries, usd_equiv = qty × rate computed from the current finance/rates.csv row; rate version recorded
    • [ ] Entry appended, never overwriting history (corrections reference the original)
    • [ ] Entry re-read and confirmed present and correctly formatted
    • [ ] Budget breach checked — surface immediately if the scope total exceeds its cap
    • [ ] Learnings captured to docs/knowledge/ if the entry surfaced one
    • [ ] Snapshot handed to the Archivist (0 drift)

usage data ready is a registered phrase (docs/handoff-triggers.md, Wave-1 block); spend approved, artifact approved already exist. The usage data ready input declares a placeholder producer (<usage-data producer>), making this the declared fan-in sink for the AI-usage seam (H4): it absorbs every producer of usage data ready → Financial Analyst — Data & Analytics (raw token counts, SOP-062), AI Systems (interpreted model-mix, SOP-065), and the AI Engineer (per-call instrumentation, SOP-067) — as matched (fan-in) rather than a false OVERLAP (interface-contract-spec.md §3.1 R1). The Analyst computes usd_equiv for each.

Purpose

Record every money transaction and AI-usage event accurately, append-only, with no blank required fields and no guessed numbers, so the two ledgers stay a reliable basis for every spend decision and the daily burn-vs-budget line.

When to use

Whenever a monetary transaction is confirmed (subscription, API bill, payout) or an AI-usage event needs recording (token consumption). A paid API call is a dual entry — it touches both ledgers.

Flow

flowchart LR
  A["Event arrives"] --> B{"Which ledger?<br/>(money / AI / both)"}
  B --> C{"All required<br/>fields present?"}
  C -->|no| Q["Ask source —<br/>do not guess"]
  C -->|yes| R["AI? compute usd_equiv<br/>= qty × rate"]
  R --> W["Append entry<br/>(never overwrite)"]
  W --> V["Re-read &amp; verify"]
  V --> BR{"Scope over<br/>cap?"}
  BR -->|yes| FL["Flag breach<br/>immediately"]
  BR -->|no| H["Hand to Archivist"]
  classDef s fill:#1d4ed8,color:#fff,stroke:#1e3a8a
  classDef d fill:#0f766e,color:#fff,stroke:#134e4a
  class A,Q,R,W,V,FL,H s
  class B,C,BR d

Text fallback: event arrives → which ledger (money / AI / both)? → all required fields present? (no → ask the source, never guess) → for AI, compute usd_equiv = qty × rate → append the entry (never overwrite) → re-read and verify → does the scope now exceed its cap? (yes → flag the breach immediately) → hand the snapshot to the Archivist.

Steps

  1. Identify the ledger — money, AI-usage, or both (dual entry).
  2. Collect all required fields per docs/financial-system.md; do not create an entry with a blank required field — ask first.
  3. Apply the cross-rate for AI entries — look up the current model rate in finance/rates.csv; compute usd_equiv = qty × rate; record the rate version. No rate row → stop and request one (Finance Director approves via SOP-027).
  4. Append the entry to the correct ledger file (read current, then append); never overwrite history — a correction is a new entry referencing the original.
  5. Verify by re-reading the file: the row is present and correctly formatted.
  6. Check for breach — if the scope’s running total exceeds the cap in finance/budgets.csv, surface the anomaly immediately (do not wait).
  7. Hand off the updated snapshot to the Archivist; capture any learning.

Roles / approvers

Run by the Financial Analyst (or the Finance Director when the Analyst is unhired). The Analyst records and verifies; the Finance Director approves rate changes (SOP-027) and any spend (SOP-026) — the Analyst does not approve spend or set caps.

Guardrails

  • Never guess — a missing/ambiguous field is a stop, not a fill.
  • Never overwrite history — append-only; corrections reference the original.
  • Never set or change a budget cap or rate — those are the Finance Director’s.
  • Never opine on model selection — that is the AI Systems Director.
  • Never touch the Principal’s personal accounts — PA-only.
  • Do not restate docs/financial-system.md — link to it.

Job aid: JA-028-log-ledger-entry.md. See also: SOP-029 (utilization report) · SOP-027 (cross-rate) · docs/units/finance/charter.md.