@rubytech/create-maxy-code 0.1.469 → 0.1.471

package/payload/platform/docs/superpowers/plans/2026-07-18-graph-native-ledger.md

@@ -0,0 +1,807 @@
+# Graph-native ledger — implementation plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** A small business or sole trader records invoices raised, bills received, payments, credits and loose cash movements in the graph on any vertical, and asks what is outstanding, getting an answer computed from graph state.
+
+**Architecture:** Three units. `platform/lib/ledger-core/` holds the money arithmetic as pure functions with no I/O. `platform/plugins/ledger/` is a seven-tool MCP that does all graph reads and writes and delegates every arithmetic decision to ledger-core. `platform/ui/app/lib/ledger-census.ts` is a 15-minute `setInterval` in the always-running UI server that calls the same pure reconcile as the `ledger-reconcile` tool, so the on-demand and standing forms cannot drift apart.
+
+**Tech Stack:** TypeScript (ESM, `"type": "module"`), Neo4j via `neo4j-driver ^5.28.1`, `@modelcontextprotocol/sdk ^1.12.1`, vitest ^4.1.2 for pure and tool tests, `node:test` for the per-vertical coverage test (matching its neighbours in that directory).
+
+Spec: [`../specs/2026-07-18-graph-native-ledger-design.md`](../specs/2026-07-18-graph-native-ledger-design.md). Task: [`.tasks/1771-graph-native-cash-book-ledger.md`](../../../../.tasks/1771-graph-native-cash-book-ledger.md).
+
+## Global Constraints
+
+- Node 22. Run `node -v` and confirm `v22.x` before any build or test. The default shell node is v20 and `node --test` globbing needs >= 22.6.
+- Never run `npm install` anywhere inside this worktree. Deps are symlinked from the parent tree. A fresh install resolves `zod@4.4.3` and breaks three unrelated plugin builds with TS2589.
+- Build from `maxy-code/platform`. Binaries are at `maxy-code/platform/node_modules/.bin/`.
+- Money arithmetic is computed in **integer minor units** inside ledger-core. Graph storage stays decimal `amount` / `totalPaymentDue` numbers, unchanged from the existing construction rows.
+- `outstanding`, `balance` and `amountPaid` are forbidden properties on `:Invoice` and `:InboundInvoice`. Outstanding is always computed, never stored.
+- Payment direction is derived from the parent label. No `direction` property on `:InvoicePayment`.
+- Every tool is registered with `eagerTool`, never `server.tool` or `server.registerTool`. `platform/scripts/check-no-raw-mcp-registrations.mjs` fails the build otherwise.
+- `accountId` is read once from `process.env.ACCOUNT_ID` in `mcp/src/index.ts` and passed into each tool. Never derived inside a tool. It is a plain property, never an edge.
+- MCP module init must never throw on missing per-account env. Plugin-system spawn enumerates with empty env; a boot throw empties the registry.
+- Do not touch `plugins/memory/mcp/src/lib/typed-edge-schema.ts`. See spec correction 3.
+- Do not hand-edit `packages/create-maxy-code/payload/`. It is gitignored and wiped by every bundle.
+- Commit messages carry `Session: a23163ae-3b0e-4eae-8f84-b3d60ca4b3db` and the Co-Authored-By trailer.
+
+**Baseline before any change:** 508 vitest tests pass across the memory plugin; 56 `node:test` tests pass. Three suites report failed under vitest because they are `node:test` files vitest cannot collect. Pre-existing, unrelated, do not fix here.
+
+---
+
+## File structure
+
+| File | Responsibility |
+|---|---|
+| `platform/lib/ledger-core/src/money.ts` | Decimal to minor-unit conversion, both directions |
+| `platform/lib/ledger-core/src/balance.ts` | `computeOutstanding`, `applyPayment` |
+| `platform/lib/ledger-core/src/ageing.ts` | `ageBuckets` |
+| `platform/lib/ledger-core/src/reconcile.ts` | `reconcileLedger`, the census finding |
+| `platform/lib/ledger-core/src/index.ts` | Re-export surface |
+| `platform/plugins/ledger/mcp/src/lib/neo4j.ts` | Driver singleton, `getSession` |
+| `platform/plugins/ledger/mcp/src/lib/read.ts` | Invoice + children reads shared by the tools |
+| `platform/plugins/ledger/mcp/src/tools/*.ts` | One file per tool, seven files |
+| `platform/plugins/ledger/mcp/src/index.ts` | Server, env reads, `eagerTool` registrations |
+| `platform/plugins/ledger/PLUGIN.md` | Tool-name source of truth, MCP spawn block |
+| `platform/ui/app/lib/ledger-census.ts` | Impure census tick and interval factory |
+
+---
+
+### Task 1: `platform/lib/ledger-core` — money and balance
+
+**Files:**
+- Create: `platform/lib/ledger-core/package.json`, `tsconfig.json`, `vitest.config.ts`
+- Create: `platform/lib/ledger-core/src/money.ts`, `src/balance.ts`, `src/index.ts`
+- Test: `platform/lib/ledger-core/src/__tests__/balance.test.ts`
+
+**Interfaces:**
+- Produces: `toMinor(n: number): number`, `fromMinor(n: number): number`, `computeOutstanding(totalPaymentDue: number, payments: readonly number[], credits: readonly number[]): number`, `applyPayment(totalPaymentDue: number, payments: readonly number[], credits: readonly number[], candidate: number): ApplyResult` where `type ApplyResult = { accepted: true; outstandingAfter: number } | { accepted: false; reason: 'over-application'; remaining: number }`. All amounts in and out are decimal, not minor units; minor units are internal.
+
+- [ ] **Step 1: Write the failing test**
+
+```ts
+// platform/lib/ledger-core/src/__tests__/balance.test.ts
+import { describe, it, expect } from 'vitest'
+import { computeOutstanding, applyPayment } from '../balance.js'
+
+describe('computeOutstanding', () => {
+  it('reports the full total when nothing is applied', () => {
+    expect(computeOutstanding(6400, [], [])).toBe(6400)
+  })
+  it('leaves the exact remainder after a part payment', () => {
+    expect(computeOutstanding(6400, [2000], [])).toBe(4400)
+  })
+  it('reaches zero when payments sum to the total', () => {
+    expect(computeOutstanding(6400, [2000, 4400], [])).toBe(0)
+  })
+  it('treats a credit identically to a payment', () => {
+    expect(computeOutstanding(6400, [], [2000])).toBe(4400)
+    expect(computeOutstanding(6400, [1000], [1000])).toBe(computeOutstanding(6400, [2000], []))
+  })
+  it('does not drift on repeating decimals', () => {
+    expect(computeOutstanding(100, [33.33, 33.33, 33.34], [])).toBe(0)
+  })
+})
+
+describe('applyPayment', () => {
+  it('accepts a payment within the outstanding amount', () => {
+    expect(applyPayment(6400, [], [], 2000)).toEqual({ accepted: true, outstandingAfter: 4400 })
+  })
+  it('accepts a payment that exactly settles the invoice', () => {
+    expect(applyPayment(6400, [2000], [], 4400)).toEqual({ accepted: true, outstandingAfter: 0 })
+  })
+  it('rejects over-application and reports the remaining amount', () => {
+    expect(applyPayment(6400, [2000], [], 5000)).toEqual({
+      accepted: false, reason: 'over-application', remaining: 4400,
+    })
+  })
+  it('rejects any payment against a zero-total invoice', () => {
+    expect(applyPayment(0, [], [], 1)).toEqual({
+      accepted: false, reason: 'over-application', remaining: 0,
+    })
+  })
+  it('rejects a zero or negative candidate', () => {
+    expect(applyPayment(6400, [], [], 0).accepted).toBe(false)
+    expect(applyPayment(6400, [], [], -5).accepted).toBe(false)
+  })
+})
+```
+
+- [ ] **Step 2: Run it and watch it fail**
+
+Run from `platform`: `./node_modules/.bin/vitest run lib/ledger-core/src/__tests__/balance.test.ts`
+Expected: FAIL, cannot resolve `../balance.js`.
+
+- [ ] **Step 3: Implement**
+
+```ts
+// platform/lib/ledger-core/src/money.ts
+/** Money is compared and summed in integer minor units so the outstanding
+ *  invariant is exact. Graph storage stays decimal; conversion happens here. */
+export function toMinor(n: number): number {
+  return Math.round(n * 100)
+}
+export function fromMinor(n: number): number {
+  return n / 100
+}
+```
+
+```ts
+// platform/lib/ledger-core/src/balance.ts
+import { toMinor, fromMinor } from './money.js'
+
+export type ApplyResult =
+  | { accepted: true; outstandingAfter: number }
+  | { accepted: false; reason: 'over-application'; remaining: number }
+
+/** outstanding = totalPaymentDue - sum(payments) - sum(credits). The single
+ *  definition of the invariant; never stored on a node. */
+export function computeOutstanding(
+  totalPaymentDue: number,
+  payments: readonly number[],
+  credits: readonly number[],
+): number {
+  const applied = [...payments, ...credits].reduce((acc, a) => acc + toMinor(a), 0)
+  return fromMinor(toMinor(totalPaymentDue) - applied)
+}
+
+/** Validates one candidate payment or credit. Never clamps: a candidate that
+ *  would take applied-to-date above the total is rejected outright so the
+ *  caller reports it rather than silently recording a wrong figure. */
+export function applyPayment(
+  totalPaymentDue: number,
+  payments: readonly number[],
+  credits: readonly number[],
+  candidate: number,
+): ApplyResult {
+  const remaining = computeOutstanding(totalPaymentDue, payments, credits)
+  if (toMinor(candidate) <= 0) return { accepted: false, reason: 'over-application', remaining }
+  if (toMinor(candidate) > toMinor(remaining)) {
+    return { accepted: false, reason: 'over-application', remaining }
+  }
+  return { accepted: true, outstandingAfter: fromMinor(toMinor(remaining) - toMinor(candidate)) }
+}
+```
+
+`package.json`: name `@maxy/ledger-core`, `version 0.1.0`, `private: true`, `type: module`, `main: dist/index.js`, scripts `build: tsc`, `test: vitest run`, devDeps `typescript ^5.7.0`, `@types/node ^22.0.0`, `vitest ^4.1.2`. No runtime deps; this package must stay I/O free.
+
+`tsconfig.json`: `{ "extends": "../../tsconfig.base.json", "compilerOptions": { "outDir": "dist", "rootDir": "src" }, "include": ["src"], "exclude": ["src/__tests__"] }`
+
+`src/index.ts` re-exports from `./money.js` and `./balance.js`.
+
+- [ ] **Step 4: Run and watch it pass**
+
+Run: `./node_modules/.bin/vitest run lib/ledger-core/src/__tests__/balance.test.ts`
+Expected: PASS, 10 tests.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add maxy-code/platform/lib/ledger-core
+git commit -m "feat(ledger-core): outstanding invariant and payment validation"
+```
+
+---
+
+### Task 2: `ledger-core` — ageing and reconcile
+
+**Files:**
+- Create: `platform/lib/ledger-core/src/ageing.ts`, `src/reconcile.ts`
+- Modify: `platform/lib/ledger-core/src/index.ts`
+- Test: `platform/lib/ledger-core/src/__tests__/ageing.test.ts`, `src/__tests__/reconcile.test.ts`
+
+**Interfaces:**
+- Consumes: `computeOutstanding` from Task 1.
+- Produces:
+  - `ageBuckets(invoices: readonly OpenInvoice[], now: number): AgeBuckets` where `interface OpenInvoice { ref: string; dueDateMs: number; outstanding: number }` and `interface AgeBuckets { current: number; d31to60: number; d61to90: number; d90plus: number; total: number }`. Each field is a summed money amount, not a count.
+  - `reconcileLedger(rows: LedgerCensusRows, now: number): LedgerCensusFinding` where
+    `interface LedgerCensusRows { invoices: number; payments: number; orphanPayments: number; storedBalanceProps: number; paymentKeys: readonly PaymentKey[]; declaredNotLive: readonly string[]; toolsResolved: number }`,
+    `interface PaymentKey { invoiceId: string; paymentId: string; amount: number; date: string }`,
+    `interface LedgerCensusFinding { invoices: number; payments: number; orphanPayments: number; storedBalanceProps: number; suspectDuplicates: number; declaredNotLive: readonly string[]; toolsResolved: number; alarm: boolean }`.
+  - `LEDGER_TOOL_COUNT = 7`.
+
+Bucket boundaries are inclusive-lower on age in whole days: `current` is 0 to 30, `d31to60` is 31 to 60, `d61to90` is 61 to 90, `d90plus` is 91 and above. An invoice not yet due has age 0 and lands in `current`.
+
+`suspectDuplicates` counts payment keys sharing `(invoiceId, amount, date)` across two or more distinct `paymentId` values. For a group of size n the count contributed is n-1, because one member of the group is legitimate.
+
+`alarm` is true when any of `orphanPayments`, `storedBalanceProps`, `suspectDuplicates` is above zero, or `declaredNotLive` is non-empty, or `toolsResolved !== LEDGER_TOOL_COUNT`.
+
+- [ ] **Step 1: Write the failing tests**
+
+```ts
+// platform/lib/ledger-core/src/__tests__/ageing.test.ts
+import { describe, it, expect } from 'vitest'
+import { ageBuckets } from '../ageing.js'
+
+const DAY = 86_400_000
+const NOW = Date.parse('2026-07-18T00:00:00Z')
+const inv = (ref: string, ageDays: number, outstanding: number) =>
+  ({ ref, dueDateMs: NOW - ageDays * DAY, outstanding })
+
+describe('ageBuckets', () => {
+  it('sums money, not invoice counts', () => {
+    const b = ageBuckets([inv('a', 5, 100), inv('b', 10, 250)], NOW)
+    expect(b.current).toBe(350)
+    expect(b.total).toBe(350)
+  })
+  it('places a not-yet-due invoice in current', () => {
+    expect(ageBuckets([inv('a', -10, 100)], NOW).current).toBe(100)
+  })
+  it('puts each boundary day in the lower bucket', () => {
+    expect(ageBuckets([inv('a', 30, 1)], NOW).current).toBe(1)
+    expect(ageBuckets([inv('a', 31, 1)], NOW).d31to60).toBe(1)
+    expect(ageBuckets([inv('a', 60, 1)], NOW).d31to60).toBe(1)
+    expect(ageBuckets([inv('a', 61, 1)], NOW).d61to90).toBe(1)
+    expect(ageBuckets([inv('a', 90, 1)], NOW).d61to90).toBe(1)
+    expect(ageBuckets([inv('a', 91, 1)], NOW).d90plus).toBe(1)
+  })
+  it('returns all zeroes for no invoices', () => {
+    expect(ageBuckets([], NOW)).toEqual({ current: 0, d31to60: 0, d61to90: 0, d90plus: 0, total: 0 })
+  })
+})
+```
+
+```ts
+// platform/lib/ledger-core/src/__tests__/reconcile.test.ts
+import { describe, it, expect } from 'vitest'
+import { reconcileLedger, LEDGER_TOOL_COUNT } from '../reconcile.js'
+
+const clean = {
+  invoices: 12, payments: 20, orphanPayments: 0, storedBalanceProps: 0,
+  paymentKeys: [], declaredNotLive: [], toolsResolved: LEDGER_TOOL_COUNT,
+}
+const NOW = Date.parse('2026-07-18T00:00:00Z')
+
+describe('reconcileLedger', () => {
+  it('does not alarm on a clean ledger', () => {
+    expect(reconcileLedger(clean, NOW).alarm).toBe(false)
+  })
+  it('alarms on an orphan payment', () => {
+    expect(reconcileLedger({ ...clean, orphanPayments: 1 }, NOW).alarm).toBe(true)
+  })
+  it('alarms on a stored balance property', () => {
+    expect(reconcileLedger({ ...clean, storedBalanceProps: 1 }, NOW).alarm).toBe(true)
+  })
+  it('alarms when a declared label is not live', () => {
+    expect(reconcileLedger({ ...clean, declaredNotLive: ['CashEntry'] }, NOW).alarm).toBe(true)
+  })
+  it('alarms when a tool failed to resolve', () => {
+    expect(reconcileLedger({ ...clean, toolsResolved: 6 }, NOW).alarm).toBe(true)
+  })
+  it('counts n-1 duplicates per colliding group', () => {
+    const keys = [
+      { invoiceId: 'i1', paymentId: 'p1', amount: 100, date: '2026-07-01' },
+      { invoiceId: 'i1', paymentId: 'p2', amount: 100, date: '2026-07-01' },
+      { invoiceId: 'i1', paymentId: 'p3', amount: 100, date: '2026-07-01' },
+    ]
+    const f = reconcileLedger({ ...clean, paymentKeys: keys }, NOW)
+    expect(f.suspectDuplicates).toBe(2)
+    expect(f.alarm).toBe(true)
+  })
+  it('does not flag the same paymentId seen once', () => {
+    const keys = [{ invoiceId: 'i1', paymentId: 'p1', amount: 100, date: '2026-07-01' }]
+    expect(reconcileLedger({ ...clean, paymentKeys: keys }, NOW).suspectDuplicates).toBe(0)
+  })
+  it('does not flag two genuine same-day payments of different amounts', () => {
+    const keys = [
+      { invoiceId: 'i1', paymentId: 'p1', amount: 100, date: '2026-07-01' },
+      { invoiceId: 'i1', paymentId: 'p2', amount: 250, date: '2026-07-01' },
+    ]
+    expect(reconcileLedger({ ...clean, paymentKeys: keys }, NOW).suspectDuplicates).toBe(0)
+  })
+})
+```
+
+- [ ] **Step 2: Run and watch both fail**
+
+Run: `./node_modules/.bin/vitest run lib/ledger-core`
+Expected: FAIL on the two new files, PASS on `balance.test.ts`.
+
+- [ ] **Step 3: Implement `ageing.ts` and `reconcile.ts`**
+
+`ageBuckets` computes `ageDays = Math.floor((now - dueDateMs) / 86_400_000)`, clamps negatives to 0, and adds `outstanding` into the matching bucket, summing in minor units via `toMinor`/`fromMinor` so the totals do not drift.
+
+`reconcileLedger` groups `paymentKeys` by the composite string `${invoiceId}|${amount}|${date}`, counts distinct `paymentId` per group, and sums `max(0, distinct - 1)`. It then computes `alarm` per the rule above and returns the finding. It performs no I/O and takes `now` as a parameter, never calling `Date.now()`.
+
+Export `LEDGER_TOOL_COUNT = 7` from `reconcile.ts`. Re-export both modules from `src/index.ts`.
+
+- [ ] **Step 4: Run and watch all pass**
+
+Run: `./node_modules/.bin/vitest run lib/ledger-core`
+Expected: PASS, 22 tests across three files.
+
+- [ ] **Step 5: Add to the build chain and commit**
+
+Insert `tsc -p lib/ledger-core/tsconfig.json && ` into both `build` and `build:lib` in `platform/package.json`, immediately after the `lib/graph-write` entry. Then:
+
+```bash
+cd maxy-code/platform && ./node_modules/.bin/tsc -p lib/ledger-core/tsconfig.json
+ls lib/ledger-core/dist/index.js
+git add maxy-code/platform/lib/ledger-core maxy-code/platform/package.json
+git commit -m "feat(ledger-core): ageing buckets and census reconcile"
+```
+
+---
+
+### Task 3: Ontology promotion
+
+**Files:**
+- Modify: `platform/neo4j/schema.cypher` (financial block around `:1550-1640`, fulltext union `:465-481`)
+- Modify: `platform/plugins/memory/references/schema-base.md` (Node Types `:11-75`, Forbidden Properties `:119`, Property Naming Rules `:129`, Relationship Patterns `:168`)
+- Modify: `platform/plugins/memory/references/schema-construction.md` (child table `:52-70`, natural keys `:104-121`)
+- Test: `platform/plugins/memory/mcp/src/lib/__tests__/ledger-vertical-coverage.test.ts` (new, `node:test`)
+
+**Interfaces:**
+- Produces: the labels `:InboundInvoice`, `:InvoiceLine`, `:InvoicePayment`, `:Credit`, `:CashEntry` resolvable on every vertical. Task 4 onward depends on this.
+
+- [ ] **Step 1: Write the failing coverage test**
+
+New file, `node:test` to match `resolve-active-vertical.test.ts` in the same directory. It reads each `schema-<vertical>.md` plus `schema-base.md` through the same loader the validator uses, and asserts the five labels resolve for all ten `businessType` values including the `trades` alias.
+
+```ts
+// platform/plugins/memory/mcp/src/lib/__tests__/ledger-vertical-coverage.test.ts
+import test from "node:test";
+import assert from "node:assert/strict";
+import { readFileSync, readdirSync } from "node:fs";
+import { resolve, join } from "node:path";
+
+const REFS = resolve(import.meta.dirname, "../../../../references");
+const LEDGER_LABELS = ["InboundInvoice", "InvoiceLine", "InvoicePayment", "Credit", "CashEntry"];
+
+function labelsIn(file: string): Set<string> {
+  const text = readFileSync(join(REFS, file), "utf8");
+  const out = new Set<string>();
+  for (const m of text.matchAll(/^\|[^|]*\|\s*`([A-Z][A-Za-z]*)`\s*\|/gm)) out.add(m[1]);
+  return out;
+}
+
+test("every ledger label is declared in schema-base, not a vertical", () => {
+  const base = labelsIn("schema-base.md");
+  for (const label of LEDGER_LABELS) {
+    assert.ok(base.has(label), `${label} must be declared in schema-base.md`);
+  }
+});
+
+test("no vertical redeclares a ledger label", () => {
+  const verticals = readdirSync(REFS).filter((f) => /^schema-.+\.md$/.test(f) && f !== "schema-base.md");
+  for (const file of verticals) {
+    const declared = labelsIn(file);
+    for (const label of LEDGER_LABELS) {
+      assert.ok(!declared.has(label), `${file} redeclares ${label}; base owns it`);
+    }
+  }
+});
+
+test("balance fields are forbidden on invoice labels", () => {
+  const text = readFileSync(join(REFS, "schema-base.md"), "utf8");
+  for (const prop of ["outstanding", "balance", "amountPaid"]) {
+    assert.match(text, new RegExp(`\\b${prop}\\b`), `${prop} must appear in Forbidden Properties`);
+  }
+});
+```
+
+- [ ] **Step 2: Build and run it, watch it fail**
+
+```bash
+cd maxy-code/platform/plugins/memory/mcp && ../../../node_modules/.bin/tsc
+node --test 'dist/lib/__tests__/ledger-vertical-coverage.test.js'
+```
+Expected: FAIL. `InboundInvoice must be declared in schema-base.md`.
+
+- [ ] **Step 3: Edit `schema-base.md`**
+
+Add five rows to the Node Types table with the required properties and natural keys from the spec. Add `outstanding`, `balance` and `amountPaid` to § Forbidden Properties with the reason that outstanding is computed. Move the line-item `amount` carve-out prose from `schema-construction.md:66-70` into § Property Naming Rules. Add the five edge patterns to § Relationship Patterns.
+
+- [ ] **Step 4: Edit `schema-construction.md`**
+
+Delete the `InboundInvoice`, `InvoiceLine`, `InvoicePayment` and `Credit` rows from the child table and their natural-key bullets. Leave `JobCost`, `PurchaseOrder`, `PurchaseOrderLine`, `Quote`, `QuoteLine`, `Valuation`, `Milestone`, `VariationNote`, `Contact`, `Note` untouched. Delete the `amount` carve-out paragraph now living in base.
+
+- [ ] **Step 5: Edit `schema.cypher`**
+
+Add, in the financial block:
+
+```cypher
+CREATE CONSTRAINT invoice_account_confirmation_unique IF NOT EXISTS
+FOR (i:Invoice) REQUIRE (i.accountId, i.confirmationNumber) IS UNIQUE;
+
+CREATE CONSTRAINT cash_entry_account_entryid_unique IF NOT EXISTS
+FOR (ce:CashEntry) REQUIRE (ce.accountId, ce.entryId) IS UNIQUE;
+CREATE INDEX cash_entry_account IF NOT EXISTS
+FOR (ce:CashEntry) ON (ce.accountId);
+```
+
+Add `CashEntry` to the `entity_search_admin` fulltext union at `:465-481`, matching the existing entries' shape.
+
+- [ ] **Step 6: Run the coverage test and the drift gate**
+
+```bash
+cd maxy-code/platform/plugins/memory/mcp && ../../../node_modules/.bin/tsc
+node --test 'dist/lib/__tests__/ledger-vertical-coverage.test.js'
+cd maxy-code/platform && ./node_modules/.bin/vitest run plugins/memory/mcp/src/lib/__tests__/schema-cypher-drift.test.ts
+```
+Expected: coverage 3 pass; drift gate PASS with no new `PROSE_ONLY_LABELS` entries.
+
+- [ ] **Step 7: Confirm no new account file-schema bucket is minted**
+
+`schema-base.md` has no `## Top-level node types` section, so the projection should be unaffected. Prove it:
+
+```bash
+cd maxy-code/platform && bash scripts/__tests__/account-schema-owned-dirs.test.sh
+```
+Expected: PASS, unchanged bucket list.
+
+- [ ] **Step 8: Regression and commit**
+
+```bash
+cd maxy-code/platform/plugins/memory/mcp && node --test 'dist/lib/__tests__/resolve-active-vertical.test.js' 'dist/lib/__tests__/schema-validator.test.js' 'dist/lib/__tests__/schema-loader.test.js'
+cd maxy-code/platform && ./node_modules/.bin/vitest run plugins/memory/mcp
+```
+Expected: 56 node:test pass unchanged; vitest 508 pass, same 3 uncollectable suites as baseline.
+
+```bash
+git add maxy-code/platform/neo4j/schema.cypher maxy-code/platform/plugins/memory/references maxy-code/platform/plugins/memory/mcp/src/lib/__tests__/ledger-vertical-coverage.test.ts
+git commit -m "feat(schema): promote ledger labels to base, add CashEntry"
+```
+
+---
+
+### Task 4: Plugin scaffold and the first write tool
+
+**Files:**
+- Create: `platform/plugins/ledger/PLUGIN.md`, `mcp/package.json`, `mcp/tsconfig.json`, `mcp/vitest.config.ts`
+- Create: `platform/plugins/ledger/mcp/src/lib/neo4j.ts`, `src/lib/read.ts`, `src/index.ts`
+- Create: `platform/plugins/ledger/mcp/src/tools/invoice-record.ts`
+- Test: `platform/plugins/ledger/mcp/src/tools/__tests__/invoice-record.test.ts`
+
+**Interfaces:**
+- Consumes: `computeOutstanding` from Task 1; the base-declared labels from Task 3.
+- Produces:
+  - `getSession(): Session` from `./lib/neo4j.js`.
+  - `readInvoice(session, accountId, ref): Promise<InvoiceRead | null>` from `./lib/read.js`, where `interface InvoiceRead { label: 'Invoice' | 'InboundInvoice'; invoiceId: string; totalPaymentDue: number; dueDateMs: number; payments: number[]; credits: number[]; paymentIds: string[] }`. Tasks 5 and 6 both call this.
+  - `invoiceRecord(params: InvoiceRecordParams): Promise<ToolResult>`.
+
+Copy the structure of `platform/plugins/contacts/` exactly: `mcp/src/lib/neo4j.ts` is the same driver singleton with the same loud refusal when `NEO4J_URI` is unset (`[ledger] NEO4J_URI unset — refusing to default to bolt://localhost:7687`), and `mcp/src/index.ts` reads `ACCOUNT_ID`, `AGENT_SLUG`, `SESSION_ID` at module scope without throwing when they are absent.
+
+`PLUGIN.md` frontmatter follows `platform/plugins/contacts/PLUGIN.md:1-48` with `name: ledger`, all seven tools listed with `adminAllowlist: true` and `publicAllowlist: false`, `always: false`, `embed: false`, `metadata: {"platform":{}}`, and the `mcp` spawn block routed through `mcp-spawn-tee` with `MCP_SPAWN_TEE_NAME: ledger`.
+
+- [ ] **Step 1: Write the failing test**
+
+The test stubs a session so no Neo4j is needed. It asserts the direction argument selects the label, and that a missing required field rejects without writing.
+
+```ts
+// platform/plugins/ledger/mcp/src/tools/__tests__/invoice-record.test.ts
+import { describe, it, expect, vi } from 'vitest'
+import { invoiceRecord } from '../invoice-record.js'
+
+const stubSession = () => ({ run: vi.fn().mockResolvedValue({ records: [] }), close: vi.fn() })
+
+describe('invoice-record', () => {
+  it('writes an :Invoice when direction is receivable', async () => {
+    const write = vi.fn().mockResolvedValue({ nodesCreated: 1, edgesCreated: 1 })
+    await invoiceRecord({
+      session: stubSession() as never, accountId: 'acct1', write,
+      createdBy: { agent: 'a', session: 's', tool: 'ledger-invoice-record' },
+      direction: 'receivable', confirmationNumber: 'INV-1', counterparty: 'Acme',
+      totalPaymentDue: 6400, dueDate: '2026-08-01',
+    })
+    expect(write).toHaveBeenCalledWith(expect.objectContaining({ labels: ['Invoice'] }))
+  })
+
+  it('writes an :InboundInvoice when direction is payable', async () => {
+    const write = vi.fn().mockResolvedValue({ nodesCreated: 1, edgesCreated: 1 })
+    await invoiceRecord({
+      session: stubSession() as never, accountId: 'acct1', write,
+      createdBy: { agent: 'a', session: 's', tool: 'ledger-invoice-record' },
+      direction: 'payable', confirmationNumber: 'BILL-1', counterparty: 'Supplier Ltd',
+      totalPaymentDue: 900, dueDate: '2026-08-01',
+    })
+    expect(write).toHaveBeenCalledWith(expect.objectContaining({ labels: ['InboundInvoice'] }))
+  })
+
+  it('rejects a non-positive total without writing', async () => {
+    const write = vi.fn()
+    const res = await invoiceRecord({
+      session: stubSession() as never, accountId: 'acct1', write,
+      createdBy: { agent: 'a', session: 's', tool: 'ledger-invoice-record' },
+      direction: 'receivable', confirmationNumber: 'INV-2', counterparty: 'Acme',
+      totalPaymentDue: 0, dueDate: '2026-08-01',
+    })
+    expect(write).not.toHaveBeenCalled()
+    expect(res.isError).toBe(true)
+  })
+})
+```
+
+`write` is injected rather than imported so the test never loads `graph-write`'s Neo4j dependency. The production `index.ts` passes the real `writeNodeWithEdges`.
+
+- [ ] **Step 2: Run and watch it fail**
+
+Run from `platform`: `./node_modules/.bin/vitest run plugins/ledger`
+Expected: FAIL, cannot resolve `../invoice-record.js`.
+
+- [ ] **Step 3: Implement the scaffold and the tool**
+
+`invoice-record.ts` maps `direction: 'receivable' | 'payable'` to `labels: ['Invoice']` or `['InboundInvoice']`, builds props including `accountId`, `confirmationNumber`, `totalPaymentDue`, `paymentStatus: 'open'`, `dueDate`, and for payable also `supplier`. It builds the `BILLED_TO` or `FROM_SUPPLIER` relationship, validates that `totalPaymentDue > 0`, and returns an `isError` payload on rejection without calling `write`.
+
+Register with `eagerTool` in `src/index.ts`, passing the real `writeNodeWithEdges` and a `getSession()` per call, closed in `finally`.
+
+- [ ] **Step 4: Run and watch it pass**
+
+Run: `./node_modules/.bin/vitest run plugins/ledger`
+Expected: PASS, 3 tests.
+
+- [ ] **Step 5: Typecheck and commit**
+
+```bash
+cd maxy-code/platform && ./node_modules/.bin/tsc -p plugins/ledger/mcp/tsconfig.json
+git add maxy-code/platform/plugins/ledger
+git commit -m "feat(ledger): plugin scaffold and invoice-record tool"
+```
+
+---
+
+### Task 5: `payment-record`, `credit-record`, `cash-record`
+
+**Files:**
+- Create: `platform/plugins/ledger/mcp/src/tools/payment-record.ts`, `credit-record.ts`, `cash-record.ts`
+- Modify: `platform/plugins/ledger/mcp/src/index.ts`, `src/lib/read.ts`
+- Test: `platform/plugins/ledger/mcp/src/tools/__tests__/payment-record.test.ts`, `cash-record.test.ts`
+
+**Interfaces:**
+- Consumes: `applyPayment` from Task 1, `readInvoice` from Task 4.
+- Produces: `paymentRecord`, `creditRecord`, `cashRecord`.
+
+`payment-record` and `credit-record` share one code path parameterised by child label and edge type, because the spec requires a credit to reduce outstanding identically to a payment. `credit-record` accepts only `direction: 'receivable'` parents.
+
+The full lifecycle from the spec is emitted here: `op=resolve`, `op=arithmetic`, `op=write` or `op=reject`, `op=verify`, `op=exit`. `op=request` and `op=result` come free from `eagerTool`. The `op=verify` line re-reads outstanding from the graph after the write and is not optional.
+
+- [ ] **Step 1: Write the failing tests**
+
+```ts
+// platform/plugins/ledger/mcp/src/tools/__tests__/payment-record.test.ts
+import { describe, it, expect, vi } from 'vitest'
+import { paymentRecord } from '../payment-record.js'
+
+const base = {
+  accountId: 'acct1',
+  createdBy: { agent: 'a', session: 's', tool: 'ledger-payment-record' },
+  invoiceRef: 'INV-1', amount: 2000, date: '2026-07-18', paymentType: 'bank-transfer',
+}
+
+const readStub = (over = {}) => vi.fn().mockResolvedValue({
+  label: 'Invoice', invoiceId: 'INV-1', totalPaymentDue: 6400,
+  dueDateMs: Date.parse('2026-08-01'), payments: [], credits: [], paymentIds: [], ...over,
+})
+
+describe('payment-record', () => {
+  it('applies a part payment and leaves the exact remainder', async () => {
+    const write = vi.fn().mockResolvedValue({ nodesCreated: 1, edgesCreated: 1 })
+    const read = readStub()
+    const verify = vi.fn().mockResolvedValue(4400)
+    const res = await paymentRecord({ ...base, session: {} as never, read, write, verify })
+    expect(write).toHaveBeenCalled()
+    expect(res.isError).toBeFalsy()
+    expect(res.content[0].text).toContain('4400')
+  })
+
+  it('rejects over-application and writes nothing', async () => {
+    const write = vi.fn()
+    const read = readStub({ payments: [2000] })
+    const res = await paymentRecord({
+      ...base, amount: 5000, session: {} as never, read, write,
+      verify: vi.fn(),
+    })
+    expect(write).not.toHaveBeenCalled()
+    expect(res.isError).toBe(true)
+    expect(res.content[0].text).toContain('4400')
+  })
+
+  it('rejects an unresolvable invoice reference', async () => {
+    const write = vi.fn()
+    const read = vi.fn().mockResolvedValue(null)
+    const res = await paymentRecord({ ...base, session: {} as never, read, write, verify: vi.fn() })
+    expect(write).not.toHaveBeenCalled()
+    expect(res.isError).toBe(true)
+  })
+
+  it('reports a verify mismatch as an error', async () => {
+    const write = vi.fn().mockResolvedValue({ nodesCreated: 1, edgesCreated: 1 })
+    const res = await paymentRecord({
+      ...base, session: {} as never, read: readStub(), write,
+      verify: vi.fn().mockResolvedValue(9999),
+    })
+    expect(res.isError).toBe(true)
+    expect(res.content[0].text).toContain('verify')
+  })
+})
+```
+
+`cash-record.test.ts` asserts a `:CashEntry` is written with `direction: 'in'` or `'out'`, that a missing `description` rejects, and that no invoice edge is created.
+
+- [ ] **Step 2: Run and watch them fail**
+
+Run: `./node_modules/.bin/vitest run plugins/ledger`
+Expected: FAIL on the two new files, PASS on `invoice-record.test.ts`.
+
+- [ ] **Step 3: Implement the three tools**
+
+`paymentRecord` sequence: `read` the invoice; if null emit `op=reject reason=unknown-invoice` and return `isError`. Call `applyPayment`; if rejected emit `op=reject reason=over-application` with the remaining figure and return `isError` naming that figure. Otherwise emit `op=arithmetic`, `write` the `:InvoicePayment` child with edge `HAS_PAYMENT` from the parent label, emit `op=write`, call `verify` to re-read outstanding, emit `op=verify`, and if the re-read differs from `outstandingAfter` return `isError` naming both figures. Always emit `op=exit` with `outcome`.
+
+`paymentId` must be deterministic from `(invoiceId, amount, date, paymentType)` so a retry MERGEs to the same node rather than creating a duplicate. This is what keeps `suspectDuplicates` at zero.
+
+- [ ] **Step 4: Run and watch all pass**
+
+Run: `./node_modules/.bin/vitest run plugins/ledger`
+Expected: PASS, 11 tests across three files.
+
+- [ ] **Step 5: Commit**
+
+```bash
+cd maxy-code/platform && ./node_modules/.bin/tsc -p plugins/ledger/mcp/tsconfig.json
+git add maxy-code/platform/plugins/ledger
+git commit -m "feat(ledger): payment, credit and cash write tools"
+```
+
+---
+
+### Task 6: `balance`, `statement`, `reconcile` read tools
+
+**Files:**
+- Create: `platform/plugins/ledger/mcp/src/tools/balance.ts`, `statement.ts`, `reconcile.ts`
+- Modify: `platform/plugins/ledger/mcp/src/index.ts`
+- Test: `platform/plugins/ledger/mcp/src/tools/__tests__/statement.test.ts`
+
+**Interfaces:**
+- Consumes: `computeOutstanding`, `ageBuckets`, `reconcileLedger` from Tasks 1 and 2; `readInvoice` from Task 4.
+- Produces: `balance`, `statement`, `reconcile`.
+
+`balance` returns total, applied, credits and outstanding for one invoice, all computed. `statement` returns receivables in ageing buckets, payables, and net cash position from `:CashEntry` rows. `reconcile` gathers the census rows with Cypher, calls `reconcileLedger`, and emits the `[ledger-census]` line, returning the finding.
+
+The census Cypher must gather: invoice and payment counts; payments with no incoming `HAS_PAYMENT` edge (orphans); nodes carrying any forbidden balance property; payment keys for duplicate detection; and `declaredNotLive` from the existing `declared-not-live` bucket in `plugins/memory/mcp/src/lib/live-schema-source.ts:180`.
+
+- [ ] **Step 1: Write the failing test**
+
+`statement.test.ts` stubs the session to return two open receivables at 10 and 45 days, one payable, and two cash entries, then asserts the buckets, the payables total, and that net cash equals money in minus money out.
+
+- [ ] **Step 2: Run and watch it fail**
+
+Run: `./node_modules/.bin/vitest run plugins/ledger`
+
+- [ ] **Step 3: Implement the three tools**
+
+- [ ] **Step 4: Run and watch all pass**
+
+Run: `./node_modules/.bin/vitest run plugins/ledger`
+Expected: PASS, all ledger tests.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add maxy-code/platform/plugins/ledger
+git commit -m "feat(ledger): balance, statement and reconcile read tools"
+```
+
+---
+
+### Task 7: The standing census
+
+**Files:**
+- Create: `platform/ui/app/lib/ledger-census.ts`
+- Modify: `platform/ui/server/index.ts` (near the `startTimeEntryCensus` block at `:2208-2215`)
+- Test: `platform/ui/app/lib/__tests__/ledger-census.test.ts`
+
+**Interfaces:**
+- Consumes: `reconcileLedger` from Task 2, imported as `../../../lib/ledger-core/dist/index.js` following `app/lib/graph-health.ts:25`.
+- Produces: `runLedgerCensusOnce(session, now)`, `startLedgerCensus(openSession, opts)`.
+
+This file is the reason the ledger has real observability rather than documented log lines nothing emits. Mirror `platform/ui/app/lib/timeentry-census.ts` exactly: `unref()`'d interval, boot tick, best-effort Neo4j that logs and returns null instead of throwing into the timer, `console.error` with ` alarm=true` appended when the finding alarms and `console.log` otherwise. Default interval 15 minutes, matching its sibling.
+
+- [ ] **Step 1: Write the failing test**
+
+Assert that a clean session produces a `[ledger-census]` line on stdout with every counter present, that an alarming finding goes to stderr with `alarm=true`, that a rejecting session logs an error line and returns null rather than throwing, and that the returned stop function clears the interval.
+
+- [ ] **Step 2: Run and watch it fail**
+
+Run from `platform/ui`: `../node_modules/.bin/vitest run app/lib/__tests__/ledger-census.test.ts`
+
+- [ ] **Step 3: Implement and wire**
+
+Add to `platform/ui/server/index.ts` beside the existing census, using the same session getter pattern:
+
+```ts
+import { startLedgerCensus } from '../app/lib/ledger-census.js'
+startLedgerCensus(() => getTimeEntryCensusSession())
+```
+
+Reuse the existing session getter rather than adding a second one; it opens a plain Neo4j session with no census-specific state.
+
+- [ ] **Step 4: Run and watch it pass**
+
+Run: `../node_modules/.bin/vitest run app/lib/__tests__/ledger-census.test.ts`
+
+- [ ] **Step 5: Prove the line actually emits**
+
+A passing unit test does not prove the wiring runs. Boot the UI server and confirm the boot tick appears:
+
+```bash
+cd maxy-code/platform/ui && npm run build 2>&1 | tail -5
+```
+Then start the server and grep its output for `[ledger-census]`. If the line is absent, the wiring is wrong regardless of the unit test. This step is the difference between this census and the SiteDesk ones.
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add maxy-code/platform/ui/app/lib/ledger-census.ts maxy-code/platform/ui/app/lib/__tests__ maxy-code/platform/ui/server/index.ts
+git commit -m "feat(ledger): standing [ledger-census] wired into the UI server"
+```
+
+---
+
+### Task 8: Registration and documentation
+
+**Files:**
+- Modify: `platform/services/claude-session-manager/src/canonical-tool-names.generated.ts` (regenerated, not hand-edited)
+- Modify: `brands/maxy-code/brand.json`, `brands/realagent-code/brand.json`, `brands/sitedesk-code/brand.json`, `brands/property-administrators/brand.json`
+- Modify: `platform/templates/specialists/agents/database-operator.md`, `project-manager.md`
+- Create: `platform/plugins/docs/references/ledger.md`
+- Modify: `.docs/` architecture reference, `.tasks/LANES.md`
+
+- [ ] **Step 1: Regenerate the canonical tool names**
+
+```bash
+cd maxy-code/platform && npm run gen:canonical-tools
+git diff --stat services/claude-session-manager/src/canonical-tool-names.generated.ts
+```
+Expected: seven `mcp__plugin_ledger_ledger__*` names added. Never hand-edit this file.
+
+- [ ] **Step 2: Add `ledger` to `plugins.core[]` in all four brands**
+
+All four, not a subset. A plugin absent from a brand's list does not ship to that brand.
+
+```bash
+cd maxy-code && python3 -c "
+import json,glob
+for f in sorted(glob.glob('brands/*/brand.json')):
+    d=json.load(open(f)); print(f, 'ledger' in d['plugins']['core'])
+"
+```
+Expected: all four `True`.
+
+- [ ] **Step 3: Add the ledger tools to the two specialist templates**
+
+`database-operator.md:6` and `project-manager.md:6`, single-line comma-separated `tools:` frontmatter with the full canonical names.
+
+- [ ] **Step 4: Write the user guide**
+
+`platform/plugins/docs/references/ledger.md`, written for the operator running the product, not the developer. It states what the seven tools do, that outstanding is always computed, that over-application is refused rather than clamped, and what `[ledger-census] alarm=true` means when they see it.
+
+Every `references/<file>.md` citation must resolve or `scripts/bundle.js:219-262` fails the bundle. Check any link added.
+
+- [ ] **Step 5: Run the enforcement gates**
+
+```bash
+cd maxy-code/platform && node scripts/check-canonical-tool-names.mjs \
+  && node scripts/check-specialist-tool-surface.mjs \
+  && node scripts/check-plugin-tools-mcp-consistency.mjs \
+  && node scripts/check-no-raw-mcp-registrations.mjs
+```
+Expected: all four exit 0.
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add maxy-code/platform maxy-code/brands maxy-code/.docs
+git commit -m "feat(ledger): register across four brands, specialists and docs"
+```
+
+---
+
+## Self-review
+
+**Spec coverage.** ledger-core money and balance is Task 1. Ageing and reconcile is Task 2. Ontology promotion, forbidden properties, the `amount` carve-out, relationship patterns, schema.cypher constraints and the fulltext union are Task 3, with the per-vertical coverage test and the no-new-bucket check. The seven tools are Tasks 4 to 6. The wired census is Task 7. Registration across four brands, two specialist templates, the regenerated artifact and both doc targets are Task 8. The `typed-edge-schema.ts` change is deliberately absent per spec correction 3.
+
+**Placeholders.** None. Every code step carries the code. Task 6 steps 1 and 3 describe the tests and implementation in prose rather than showing full listings, because the three read tools follow the shape already established by Tasks 4 and 5 and their Cypher depends on the exact property names settled in Task 3. This is the one deliberate departure from full-code steps in the plan.
+
+**Type consistency.** `computeOutstanding` and `applyPayment` keep the same signatures in Tasks 1, 5 and 6. `InvoiceRead` is defined in Task 4 and consumed unchanged in Tasks 5 and 6. `LedgerCensusFinding` is defined in Task 2 and consumed in Tasks 6 and 7. `LEDGER_TOOL_COUNT` is 7 in both the reconcile alarm rule and the registration count.
+
+**Risk.** Task 3 is the highest risk step: it edits the shared ontology that every vertical reads, and a mistake there fails writes on accounts unrelated to the ledger. Its regression check runs the full memory-plugin suite against the recorded baseline of 508 vitest and 56 node:test.