io.github.eternal-roman/ledger

Ledger

Money.from · validateEntry · Ledger.apply. Invalid entries are rejected, never posted.

For agents

Do not add, split, convert, or balance amounts yourself. Call the kernel.

npx -y @eternal-roman/ledger-mcp

{
  "mcpServers": {
    "ledger": { "command": "npx", "args": ["-y", "@eternal-roman/ledger-mcp"] }
  }
}

Then:

1. Read ledger://canon/rules and ledger://canon/workflow.
2. Compute with money_compute. Validate with entry_validate. Post with ledger_post.
3. Prove with ledger_verify_equation + ledger_audit_hash. Never invent an audit hash.
4. Ground treatments with cite_lookup. Bundle proof with artifact_make.

Rules live in AGENTS.md. Protocol: docs/CORE-PROTOCOL.md. Machine index: llms.txt. Full tool list: mcp/.

Host plugins (Grok and compatible) load /ledger-verify, /ledger-audit, /ledger-cite, /ledger-reconcile, /ledger-sim, /ledger-review from this repo. Copy AGENTS.md or skills/ledger/SKILL.md if the host has no plugin loader.

Why this exists

Token-level arithmetic is indifferent to scale, balance, and currency. The kernel is not.

Failure	Kernel
Float drift / sub-scale	Money.from rejects
Unbalanced entry	validateEntry + Ledger.apply reject
Silent currency mix	Per-currency; FX must be explicit
Tamper / non-repro	SHA-256 auditHash (ledger-audit-v2) + determinism harness
Ungrounded treatment	Starter IFRS/GAAP graph via cite_lookup

	Exact money	Double-entry	Immutable + audit hash	Deterministic	No DB	Agent / MCP
Ledger	yes	kernel	yes	yes	yes	yes
dinero.js	yes	—	—	—	yes	—
medici	partial	yes	—	—	MongoDB	—
Formance / TigerBeetle	yes	yes	yes	partial	service	—

Install (library)

npm install @eternal-roman/ledger

import { Money, Account, AccountType, createBalancedEntry, emptyLedger, validateEntry } from '@eternal-roman/ledger';

const cash = new Account('1000', 'Cash', AccountType.Asset);
const equity = new Account('3000', 'Owner Equity', AccountType.Equity);

const contribution = createBalancedEntry(
  'cap-001', '2026-06-21', cash, equity,
  Money.from('10000', 'USD'), 'Initial capital'
);

if (!validateEntry(contribution).ok) throw new Error('Invariant violation');

const ledger = emptyLedger().apply(contribution).ledger;
ledger.balance(cash).toString(); // "10000.00 USD"

ESM and CommonJS. Kernel-only import: @eternal-roman/ledger/core.

Mechanical check (no LLM):

npx ledger-verify --scan .
npx ledger-verify --prove entries.json

Layers on the kernel

All of these emit validated JournalEntrys. None reimplement money.

• Trading / custody — fillToEntries, deposits, withdrawals, taker/maker fees
• Portfolio — FIFO/LIFO/HIFO lots, realized/unrealized P&L, valuePortfolio
• Investing — time- and money-weighted returns, allocation, planRebalance
• Crypto transfers — one-shot or two-phase in-transit + network fees
• IFRS 16 lessee — PV liability, ROU, full schedule, golden-master to the cent
• Close / FX / depreciation / cash flow / reconcile — period locks, CTA, schedules, direct-method cash flow

Asset scales (BTC=8, ETH=18, …) are installed with installAssetScales(defaultAssetRegistry()). Fiat is unchanged. See examples/.

Verify

npm test
npm run verify        # determinism harness
npm run verify:full   # build + typecheck + tests + versions + MCP smoke
npm run eval          # unguarded vs kernel benchmark

Docs

Doc	For
AGENTS.md	Agent contract
llms.txt	Machine-readable map
docs/CORE-PROTOCOL.md	Zero-Skip protocol
docs/SUCCESS-CHECKLIST.md	Pre-ship checklist
docs/ANTI-PATTERNS.md	What the kernel rejects
docs/SCOPE-AND-LAYERS.md	What ships today
mcp/README.md	MCP tools, resources, prompts
CONTRIBUTING.md	Developing this repo

Python kernel port: reference-implementations/python/ (same invariants; install an asset-scale resolver for non-fiat).

License

MIT. See LICENSE.

Disclaimer

Deterministic primitives and verification tools. Not financial, tax, legal, or accounting advice. You are responsible for inputs, assumptions, rates, jurisdiction, and compliance. Tests and benchmarks are due diligence, not a certification. See LICENSE.