{
  "markdown": "# Ledger\n\n<p align=\"center\">\n  <strong>Agents do not do money math in tokens.</strong><br>\n  Exact-decimal double-entry kernel + MCP. Fail-closed. Audit-hashed. Deterministic.\n</p>\n\n<p align=\"center\">\n  <a href=\"https://github.com/eternal-roman/ledger/actions/workflows/ci.yml\"><img src=\"https://github.com/eternal-roman/ledger/actions/workflows/ci.yml/badge.svg\" alt=\"CI\"></a>\n  <a href=\"https://www.npmjs.com/package/@eternal-roman/ledger\"><img src=\"https://img.shields.io/npm/v/@eternal-roman/ledger.svg\" alt=\"npm\"></a>\n  <a href=\"https://www.npmjs.com/package/@eternal-roman/ledger-mcp\"><img src=\"https://img.shields.io/npm/v/@eternal-roman/ledger-mcp.svg\" alt=\"mcp\"></a>\n  <a href=\"LICENSE\"><img src=\"https://img.shields.io/badge/license-MIT-blue.svg\" alt=\"MIT\"></a>\n</p>\n\n`Money.from` · `validateEntry` · `Ledger.apply`. Invalid entries are rejected, never posted.\n\n## For agents\n\nDo not add, split, convert, or balance amounts yourself. Call the kernel.\n\n```bash\nnpx -y @eternal-roman/ledger-mcp\n```\n\n```json\n{\n  \"mcpServers\": {\n    \"ledger\": { \"command\": \"npx\", \"args\": [\"-y\", \"@eternal-roman/ledger-mcp\"] }\n  }\n}\n```\n\nThen:\n\n1. Read `ledger://canon/rules` and `ledger://canon/workflow`.\n2. Compute with `money_compute`. Validate with `entry_validate`. Post with `ledger_post`.\n3. Prove with `ledger_verify_equation` + `ledger_audit_hash`. Never invent an audit hash.\n4. Ground treatments with `cite_lookup`. Bundle proof with `artifact_make`.\n\nRules live in [`AGENTS.md`](AGENTS.md). Protocol: [`docs/CORE-PROTOCOL.md`](docs/CORE-PROTOCOL.md). Machine index: [`llms.txt`](llms.txt). Full tool list: [`mcp/`](mcp/).\n\nHost 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.\n\n## Why this exists\n\nToken-level arithmetic is indifferent to scale, balance, and currency. The kernel is not.\n\n| Failure | Kernel |\n|---|---|\n| Float drift / sub-scale | `Money.from` rejects |\n| Unbalanced entry | `validateEntry` + `Ledger.apply` reject |\n| Silent currency mix | Per-currency; FX must be explicit |\n| Tamper / non-repro | SHA-256 `auditHash` (`ledger-audit-v2`) + determinism harness |\n| Ungrounded treatment | Starter IFRS/GAAP graph via `cite_lookup` |\n\n| | Exact money | Double-entry | Immutable + audit hash | Deterministic | No DB | Agent / MCP |\n|---|---|---|---|---|---|---|\n| **Ledger** | yes | kernel | yes | yes | yes | yes |\n| dinero.js | yes | — | — | — | yes | — |\n| medici | partial | yes | — | — | MongoDB | — |\n| Formance / TigerBeetle | yes | yes | yes | partial | service | — |\n\n## Install (library)\n\n```bash\nnpm install @eternal-roman/ledger\n```\n\n```ts\nimport { Money, Account, AccountType, createBalancedEntry, emptyLedger, validateEntry } from '@eternal-roman/ledger';\n\nconst cash = new Account('1000', 'Cash', AccountType.Asset);\nconst equity = new Account('3000', 'Owner Equity', AccountType.Equity);\n\nconst contribution = createBalancedEntry(\n  'cap-001', '2026-06-21', cash, equity,\n  Money.from('10000', 'USD'), 'Initial capital'\n);\n\nif (!validateEntry(contribution).ok) throw new Error('Invariant violation');\n\nconst ledger = emptyLedger().apply(contribution).ledger;\nledger.balance(cash).toString(); // \"10000.00 USD\"\n```\n\nESM and CommonJS. Kernel-only import: `@eternal-roman/ledger/core`.\n\nMechanical check (no LLM):\n\n```bash\nnpx ledger-verify --scan .\nnpx ledger-verify --prove entries.json\n```\n\n## Layers on the kernel\n\nAll of these emit validated `JournalEntry`s. None reimplement money.\n\n- **Trading / custody** — `fillToEntries`, deposits, withdrawals, taker/maker fees\n- **Portfolio** — FIFO/LIFO/HIFO lots, realized/unrealized P&L, `valuePortfolio`\n- **Investing** — time- and money-weighted returns, allocation, `planRebalance`\n- **Crypto transfers** — one-shot or two-phase in-transit + network fees\n- **IFRS 16 lessee** — PV liability, ROU, full schedule, golden-master to the cent\n- **Close / FX / depreciation / cash flow / reconcile** — period locks, CTA, schedules, direct-method cash flow\n\nAsset scales (BTC=8, ETH=18, …) are installed with `installAssetScales(defaultAssetRegistry())`. Fiat is unchanged. See `examples/`.\n\n## Verify\n\n```bash\nnpm test\nnpm run verify        # determinism harness\nnpm run verify:full   # build + typecheck + tests + versions + MCP smoke\nnpm run eval          # unguarded vs kernel benchmark\n```\n\n## Docs\n\n| Doc | For |\n|---|---|\n| [`AGENTS.md`](AGENTS.md) | Agent contract |\n| [`llms.txt`](llms.txt) | Machine-readable map |\n| [`docs/CORE-PROTOCOL.md`](docs/CORE-PROTOCOL.md) | Zero-Skip protocol |\n| [`docs/SUCCESS-CHECKLIST.md`](docs/SUCCESS-CHECKLIST.md) | Pre-ship checklist |\n| [`docs/ANTI-PATTERNS.md`](docs/ANTI-PATTERNS.md) | What the kernel rejects |\n| [`docs/SCOPE-AND-LAYERS.md`](docs/SCOPE-AND-LAYERS.md) | What ships today |\n| [`mcp/README.md`](mcp/README.md) | MCP tools, resources, prompts |\n| [`CONTRIBUTING.md`](CONTRIBUTING.md) | Developing this repo |\n\nPython kernel port: `reference-implementations/python/` (same invariants; install an asset-scale resolver for non-fiat).\n\n## License\n\nMIT. See [LICENSE](LICENSE).\n\n## Disclaimer\n\nDeterministic 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.\n",
  "bytes": 5468,
  "sha": "ad5f9c0325989d952885ff2a344cb0c66a6ba53721dda4e7271d3ee30ab0c3bc",
  "repo_slug": "eternal-roman/ledger",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_eternal_roman_ledger_372d4049/readme"
}