@rubytech/create-maxy-code 0.1.470 → 0.1.471

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

@@ -0,0 +1,241 @@
+# Graph-native cash book + AR/AP ledger — design
+
+Spec for [Task 1771](../../../../.tasks/1771-graph-native-cash-book-ledger.md). Written 2026-07-18.
+
+## Why
+
+On 2026-07-18 an admin asked the agent to record a £2,000 payment. The agent began inventing `Invoice`
+properties (`total`, `amountPaid`, `balance`, `status:"part-paid"`), then reported that no ledger exists
+and offered QuickBooks, a bespoke design, or a reminder task.
+
+The report was partly wrong. `:Invoice` is in the base ontology (`schema-base.md:20`). But
+`:InvoicePayment`, `:Credit`, `:InvoiceLine` and `:InboundInvoice` are declared only for the construction
+vertical (`schema-construction.md:63-64`), so on the other nine `businessType` values an invoice can be
+raised and a payment against it has nowhere to land. `paymentStatus` is free text. No arithmetic anywhere
+relates an invoice total to what has been paid. The QuickBooks plugin performs zero graph writes. Write
+Cypher is specialist-only (`platform/plugins/graph/PLUGIN.md:42`), so the admin agent has no deterministic
+path even where the labels exist.
+
+## Corrections to the task file
+
+Three statements in Task 1771 were checked against the tree and do not hold. The implementation follows
+the tree, not the task file.
+
+1. **`ADMIN_CORE_TOOLS` does not exist.** `grep -rn "ADMIN_CORE_TOOLS\s*[=:]"` returns zero hits. It is
+   named in `CLAUDE.md:35` but `.docs/superpowers/plans/2026-06-26-email-body-extraction.md:15` records it
+   as stale. The live mechanism is `eagerTool` (`platform/lib/mcp-eager/src/index.ts:63`), which sets
+   `_meta["anthropic/alwaysLoad"]`, plus the generated canonical-tool-names artifact.
+2. **`packages/create-maxy-code/payload/` must not be hand-edited.** It is gitignored and
+   `scripts/bundle.js:276-280` wipes it on every run.
+3. **The ledger edges do not belong in `TYPED_EDGE_ALLOWLIST`.** See § Ontology below. The task file's
+   list of eight triples is dropped; five patterns go to `schema-base.md` § Relationship Patterns instead,
+   and `typed-edge-schema.ts` is not touched.
+4. **A tool alone is not a standing check.** There is no plugin-level API for recurring jobs. The two real
+   homes are a `setInterval` module wired into `platform/ui/server/index.ts`, or code called from
+   `platform/plugins/scheduling/mcp/src/scripts/check-due-events.ts`. The SiteDesk censuses cited as
+   precedent in the task file (`quote-generation.md:241-243`, `issue-flow.md:103-115`) have **no emitter in
+   code**; they are documented log lines nothing produces. Shipping `ledger-reconcile` as only a tool would
+   reproduce that defect.
+
+## Architecture
+
+Three units. The arithmetic invariant is needed by two processes, so it lives in neither of them.
+
+### 1. `platform/lib/ledger-core/` — pure
+
+No Neo4j, no filesystem, no environment reads. Exports:
+
+- `computeOutstanding(totalPaymentDue, payments, credits)` — the invariant
+  `outstanding = totalPaymentDue - Σpayments - Σcredits`.
+- `applyPayment(invoice, existing, candidate)` — returns `{accepted}` or
+  `{rejected, reason: 'over-application', remaining}`. Never clamps.
+- `ageBuckets(openInvoices, now)` — 0-30 / 31-60 / 61-90 / 90+ days.
+- `reconcileLedger(rows, now)` — returns the census finding, including `alarm`.
+
+`platform/ui` already imports `platform/lib/*/dist` (`server/index.ts:45`,
+`app/lib/graph-health.ts:25`), so one shared lib serves both consumers and the invariant is defined once.
+ledger-core computes in integer minor units so the equality is exact and never subject to float drift.
+Graph storage is unchanged: `amount` and `totalPaymentDue` stay decimal numbers, matching the existing
+JobLogic-exact construction rows. The tools convert on the way in and on the way out, so no stored value
+changes shape and existing construction data stays readable.
+
+### 2. `platform/plugins/ledger/` — the MCP
+
+Seven tools, registered with `eagerTool`, which wraps each handler in `wrapWithLifeline` and therefore
+emits `op=request` and `op=result` with a correlation token and a handle census for free. This also
+satisfies `platform/scripts/check-no-raw-mcp-registrations.mjs`.
+
+| Tool | Purpose |
+|---|---|
+| `ledger-invoice-record` | Raise an AR `:Invoice` or record an AP `:InboundInvoice`, selected by a required `direction` |
+| `ledger-payment-record` | Apply a payment to either invoice label |
+| `ledger-credit-record` | Apply a credit to an `:Invoice` |
+| `ledger-cash-record` | A `:CashEntry` not attached to any invoice |
+| `ledger-balance` | One invoice: total, applied, outstanding |
+| `ledger-statement` | Open receivables in ageing buckets, open payables, net cash position |
+| `ledger-reconcile` | On-demand form of the census |
+
+Structure copies `platform/plugins/contacts/`: own `mcp/src/lib/neo4j.ts`, per-tool files under
+`mcp/src/tools/`, writes through `writeNodeWithEdges` from `platform/lib/graph-write/dist/index.js`.
+`accountId` is read once from `process.env.ACCOUNT_ID` at `index.ts` and passed in, never derived inside a
+tool. `createdBy` is `{agent: AGENT_SLUG, session: SESSION_ID, tool: <name>}`. Every arithmetic decision
+delegates to ledger-core; the plugin contains no money arithmetic of its own.
+
+### 3. `platform/ui/app/lib/ledger-census.ts` — the standing check
+
+Mirrors `platform/ui/app/lib/timeentry-census.ts`: pure reconcile imported from ledger-core, impure
+`runLedgerCensusOnce(session, now)`, and `startLedgerCensus(openSession, opts)` returning a stop function.
+The interval is `unref()`'d so it never holds the process open, defaults to 15 minutes matching its
+sibling, and takes a boot tick. A Neo4j error logs and returns null rather than throwing into the timer.
+Wired at `platform/ui/server/index.ts` alongside `startTimeEntryCensus` (`:2208-2215`).
+
+`ledger-reconcile` and the interval both call the same `reconcileLedger`, so the on-demand and standing
+forms cannot drift apart.
+
+## Ontology
+
+Promote to `schema-base.md` so all ten verticals are covered by one definition:
+
+| Label | Natural key |
+|---|---|
+| `:InboundInvoice` | `(accountId, supplier, confirmationNumber)` |
+| `:InvoiceLine` | `(accountId, invoiceId, lineId)` |
+| `:InvoicePayment` | `(accountId, invoiceId, paymentId)` |
+| `:Credit` | `(accountId, creditId)` |
+| `:CashEntry` | `(accountId, entryId)` — new |
+
+`:CashEntry` requires `accountId`, `entryId`, `direction` (`'in'|'out'`), `amount`, `date`, `description`.
+
+Two derivations, not stored fields:
+
+- **Direction of a payment comes from the parent label.** An `:InvoicePayment` under `:Invoice` is money
+  received; under `:InboundInvoice` it is money paid. No `direction` property on `:InvoicePayment`.
+- **Outstanding is computed on read.** `outstanding`, `balance` and `amountPaid` join § Forbidden
+  Properties (`schema-base.md:119`) for `:Invoice` and `:InboundInvoice`.
+
+`schema.cypher` additionally gains the `:Invoice` `(accountId, confirmationNumber)` uniqueness constraint
+that base already claims as its natural key but never declared, the `:CashEntry` constraint and index, and
+entries in the `entity_search_admin` fulltext union (`:465-481`).
+
+`schema-construction.md` drops the rows now owned by base. Construction-only labels stay.
+
+The line-item `amount` carve-out against the base `totalPaymentDue` synonym ban
+(`schema-construction.md:66-70`) moves to `schema-base.md` § Property Naming Rules with the labels.
+
+Five edge patterns join `schema-base.md` § Relationship Patterns (`:168`), beside the
+`(:Invoice)-[:BILLED_TO]->` pattern already there:
+
+```
+(:Invoice|:InboundInvoice)-[:HAS_LINE]->(:InvoiceLine)
+(:Invoice|:InboundInvoice)-[:HAS_PAYMENT]->(:InvoicePayment)
+(:Invoice)-[:HAS_CREDIT]->(:Credit)
+(:InboundInvoice)-[:FROM_SUPPLIER]->(:Organization)
+(:CashEntry)-[:COUNTERPARTY]->(:Person|Organization)
+```
+
+**Not `TYPED_EDGE_ALLOWLIST`.** That constant is imported by exactly two consumers,
+`plugins/memory/mcp/src/tools/memory-ingest.ts:25` and `scripts/generate-edge-docs.ts:20`. It governs what
+the typed-edge classifier may propose from free-text document ingest. `lib/graph-write/src/index.ts` never
+references it and `lib/schema-validator.ts` performs no edge-type validation, so the ledger tools' writes
+are not checked against it. Adding ledger triples there would make the classifier extract ledger edges out
+of ingested documents, which is not intended. The allowlist header states the rule directly: edge types
+outside it "are governed by schema-base.md / vertical-schema rules".
+
+## Data flow — one payment
+
+1. Resolve the invoice by reference; capture its label and `totalPaymentDue`.
+2. Fetch existing `:InvoicePayment` and `:Credit` children.
+3. ledger-core validates the candidate.
+4. Write through `writeNodeWithEdges`, or reject.
+5. Re-read outstanding from the graph.
+6. Emit `op=verify`.
+
+Step 5 is the point of the design. `op=write` proves intention; only the re-read proves outcome.
+
+## Errors
+
+Over-application rejects, is logged, and is reported to the user verbatim. It is never clamped and never
+silently recorded. An unresolvable invoice reference rejects. Neo4j failures surface as `isError` payloads,
+which `wrapWithLifeline` logs as `outcome=error` (`mcp-lifeline/src/index.ts:20-26`). The census swallows
+nothing but never throws into the interval.
+
+## Observability
+
+Failure modes and the signal for each. Four are no-event failures owned by the census, not by a log line.
+
+| # | Failure | Event? | Signal |
+|---|---|---|---|
+| 1 | Narrated as recorded, nothing written | No | `[ledger-census]` counts flat across a window containing `op=request` lines |
+| 2 | Payment with no parent-invoice edge | No | `[ledger-census] orphanPayments=<N>` |
+| 3 | A stored balance field reappears and drifts | No | `[ledger-census] storedBalanceProps=<N>` |
+| 4 | Duplicate payment via non-deterministic `paymentId` | No | `[ledger-census] suspectDuplicates=<N>` |
+| 5 | Over-application | Yes | `op=reject reason=over-application` |
+| 6 | Write rejected, resolved vertical lacks the label | Yes | `op=reject reason=unknown-label vertical=<file>` |
+| 7 | `schema.cypher` edited, `seed-neo4j.sh` not re-run | No | `[ledger-census] declaredNotLive=<labels>` from `live-schema-source.ts:180` |
+| 8 | Tool in one registry, absent from the other | No | `[ledger-census] toolsResolved=7/7` |
+
+Lifecycle for `ledger-payment-record`, correlated by `paymentId`. Lines 1 and 6 come free from
+`wrapWithLifeline`; the rest are domain lines the tool emits.
+
+```
+[ledger] op=request  paymentId=… invoiceRef=… direction=… amount=… date=…
+[ledger] op=resolve  paymentId=… found=<bool> label=<Invoice|InboundInvoice> vertical=… totalPaymentDue=…
+[ledger] op=arithmetic paymentId=… priorApplied=… priorCredits=… amount=… outstandingBefore=… outstandingAfter=…
+[ledger] op=write    paymentId=… nodesCreated=… edgesCreated=…
+[ledger] op=reject   paymentId=… reason=<over-application|unknown-label|no-parent> detail=…
+[ledger] op=verify   paymentId=… outstandingReRead=…
+[ledger] op=exit     paymentId=… ranMs=… outcome=<applied|rejected|error>
+[ledger-census] invoices=… payments=… orphanPayments=… storedBalanceProps=… suspectDuplicates=… declaredNotLive=… toolsResolved=…/7
+```
+
+**Success:** `op=verify` present, `outstandingReRead` equal to `op=arithmetic`'s `outstandingAfter`; census
+with every counter zero and `toolsResolved=7/7`.
+
+**Failure:** `op=request` with no matching `op=exit`; `op=write` with no `op=verify`; any non-zero census
+counter; **absence of a census line** in the expected window; `op=resolve found=false` on a reference the
+user just supplied.
+
+**Diagnostic path:** the plugin MCP tee log, `grep -E '\[ledger\]|\[ledger-census\]'`, then filter by one
+`paymentId` for that operation's full lifeline.
+
+## Registration
+
+- `platform/plugins/ledger/PLUGIN.md` frontmatter is the source of truth for tool names.
+- `cd platform && npm run gen:canonical-tools` regenerates
+  `services/claude-session-manager/src/canonical-tool-names.generated.ts`.
+  `platform/scripts/check-canonical-tool-names.mjs` fails the build on drift.
+- `plugins.core[]` in all four brand JSONs: `maxy-code`, `realagent-code`, `sitedesk-code`,
+  `property-administrators`. A plugin absent from a brand's list does not ship to that brand.
+- Specialist templates `database-operator.md` and `project-manager.md`.
+- `platform/package.json` build chain gains `lib/ledger-core`. The `plugins/*/mcp` glob picks the plugin up
+  automatically.
+
+## Testing
+
+- **ledger-core** — pure unit tests, no infrastructure. Part payment leaves the exact remainder; two
+  payments summing to the total leave zero; a credit reduces outstanding identically to a payment; an
+  over-application is rejected with the remaining figure; a zero-total invoice accepts no payment; the same
+  `paymentId` twice does not double-count; ageing buckets at the 30/60/90 boundaries.
+- **Tools** — stubbed session; asserts the reject branch writes nothing and that `op=verify` re-reads.
+- **Per-vertical coverage** — iterates all ten `businessType` values resolved by
+  `resolve-active-vertical.ts:38,67-81` including the `trades → schema-construction` alias, validating an
+  `:Invoice` + `:InvoicePayment` + `:CashEntry` write against each. Fails before the promotion, passes
+  after. This is the test that would have caught the reported defect.
+- **Census** — pure `reconcileLedger` cases for each non-zero counter.
+- **Drift gate** — `schema-cypher-drift.test.ts:60` green with no new `PROSE_ONLY_LABELS` entries.
+
+Baseline in this worktree before any change: 508 vitest tests pass across the memory plugin, 56 node:test
+tests pass. Three suites report as failed under vitest because they are `node:test` files vitest cannot
+collect. That is pre-existing and unrelated.
+
+## Regression boundary
+
+Existing construction-vertical tests unchanged. `resolve-active-vertical.test.ts` cases at `:69,:82,:95,:108`
+unchanged. `account-schema-owned-dirs.test.sh` confirms no new account file-schema bucket is minted, since
+`schema-base.md` has no `## Top-level node types` section. The SiteDesk `:Job -> :Quote -> :QuoteLine`
+reification is untouched.
+
+## Out of scope
+
+Double-entry. QuickBooks-to-graph mirroring. VAT, tax and multi-currency. Bank feed import. Any UI.
+SiteDesk quoting figures. Backfill of existing construction accounts.

package/payload/platform/lib/ledger-core/dist/ageing.d.ts

@@ -0,0 +1,14 @@
+export interface OpenInvoice {
+    ref: string;
+    dueDateMs: number;
+    outstanding: number;
+}
+export interface AgeBuckets {
+    current: number;
+    d31to60: number;
+    d61to90: number;
+    d90plus: number;
+    total: number;
+}
+export declare function ageBuckets(invoices: readonly OpenInvoice[], now: number): AgeBuckets;
+//# sourceMappingURL=ageing.d.ts.map

package/payload/platform/lib/ledger-core/dist/ageing.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ageing.d.ts","sourceRoot":"","sources":["../src/ageing.ts"],"names":[],"mappings":"AAcA,MAAM,WAAW,WAAW;IAC1B,GAAG,EAAE,MAAM,CAAA;IACX,SAAS,EAAE,MAAM,CAAA;IACjB,WAAW,EAAE,MAAM,CAAA;CACpB;AAED,MAAM,WAAW,UAAU;IACzB,OAAO,EAAE,MAAM,CAAA;IACf,OAAO,EAAE,MAAM,CAAA;IACf,OAAO,EAAE,MAAM,CAAA;IACf,OAAO,EAAE,MAAM,CAAA;IACf,KAAK,EAAE,MAAM,CAAA;CACd;AAED,wBAAgB,UAAU,CAAC,QAAQ,EAAE,SAAS,WAAW,EAAE,EAAE,GAAG,EAAE,MAAM,GAAG,UAAU,CAsBpF"}

package/payload/platform/lib/ledger-core/dist/ageing.js

@@ -0,0 +1,38 @@
+/**
+ * Task 1771 — receivables and payables ageing.
+ *
+ * Buckets are inclusive-lower on whole days past the due date: 0-30 is
+ * `current`, 31-60, 61-90, and 91 and above is `d90plus`. An invoice not yet
+ * due has a negative age, which clamps to 0 and lands in `current`.
+ *
+ * Every bucket is a summed money amount, not a count of invoices. Summing is
+ * done in minor units so a statement of many decimal amounts does not drift.
+ */
+import { toMinor, fromMinor } from './money.js';
+const DAY_MS = 86_400_000;
+export function ageBuckets(invoices, now) {
+    let current = 0;
+    let d31to60 = 0;
+    let d61to90 = 0;
+    let d90plus = 0;
+    for (const inv of invoices) {
+        const ageDays = Math.max(0, Math.floor((now - inv.dueDateMs) / DAY_MS));
+        const minor = toMinor(inv.outstanding);
+        if (ageDays <= 30)
+            current += minor;
+        else if (ageDays <= 60)
+            d31to60 += minor;
+        else if (ageDays <= 90)
+            d61to90 += minor;
+        else
+            d90plus += minor;
+    }
+    return {
+        current: fromMinor(current),
+        d31to60: fromMinor(d31to60),
+        d61to90: fromMinor(d61to90),
+        d90plus: fromMinor(d90plus),
+        total: fromMinor(current + d31to60 + d61to90 + d90plus),
+    };
+}
+//# sourceMappingURL=ageing.js.map

package/payload/platform/lib/ledger-core/dist/ageing.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ageing.js","sourceRoot":"","sources":["../src/ageing.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,OAAO,EAAE,OAAO,EAAE,SAAS,EAAE,MAAM,YAAY,CAAA;AAE/C,MAAM,MAAM,GAAG,UAAU,CAAA;AAgBzB,MAAM,UAAU,UAAU,CAAC,QAAgC,EAAE,GAAW;IACtE,IAAI,OAAO,GAAG,CAAC,CAAA;IACf,IAAI,OAAO,GAAG,CAAC,CAAA;IACf,IAAI,OAAO,GAAG,CAAC,CAAA;IACf,IAAI,OAAO,GAAG,CAAC,CAAA;IAEf,KAAK,MAAM,GAAG,IAAI,QAAQ,EAAE,CAAC;QAC3B,MAAM,OAAO,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC,GAAG,GAAG,GAAG,CAAC,SAAS,CAAC,GAAG,MAAM,CAAC,CAAC,CAAA;QACvE,MAAM,KAAK,GAAG,OAAO,CAAC,GAAG,CAAC,WAAW,CAAC,CAAA;QACtC,IAAI,OAAO,IAAI,EAAE;YAAE,OAAO,IAAI,KAAK,CAAA;aAC9B,IAAI,OAAO,IAAI,EAAE;YAAE,OAAO,IAAI,KAAK,CAAA;aACnC,IAAI,OAAO,IAAI,EAAE;YAAE,OAAO,IAAI,KAAK,CAAA;;YACnC,OAAO,IAAI,KAAK,CAAA;IACvB,CAAC;IAED,OAAO;QACL,OAAO,EAAE,SAAS,CAAC,OAAO,CAAC;QAC3B,OAAO,EAAE,SAAS,CAAC,OAAO,CAAC;QAC3B,OAAO,EAAE,SAAS,CAAC,OAAO,CAAC;QAC3B,OAAO,EAAE,SAAS,CAAC,OAAO,CAAC;QAC3B,KAAK,EAAE,SAAS,CAAC,OAAO,GAAG,OAAO,GAAG,OAAO,GAAG,OAAO,CAAC;KACxD,CAAA;AACH,CAAC"}

package/payload/platform/lib/ledger-core/dist/balance.d.ts

@@ -0,0 +1,25 @@
+export type ApplyResult = {
+    accepted: true;
+    outstandingAfter: number;
+} | {
+    accepted: false;
+    reason: 'over-application';
+    remaining: number;
+};
+/**
+ * outstanding = totalPaymentDue - sum(payments) - sum(credits).
+ *
+ * A credit reduces what is owed exactly as a payment does; the two differ in
+ * provenance, not arithmetic, which is why they are summed together here.
+ */
+export declare function computeOutstanding(totalPaymentDue: number, payments: readonly number[], credits: readonly number[]): number;
+/**
+ * Validates one candidate payment or credit against what is still outstanding.
+ *
+ * Never clamps. A candidate that would take applied-to-date above the invoice
+ * total is rejected outright and the caller reports it, rather than silently
+ * recording a figure that does not reconcile. A non-positive candidate is
+ * rejected for the same reason: it is not a payment.
+ */
+export declare function applyPayment(totalPaymentDue: number, payments: readonly number[], credits: readonly number[], candidate: number): ApplyResult;
+//# sourceMappingURL=balance.d.ts.map

package/payload/platform/lib/ledger-core/dist/balance.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"balance.d.ts","sourceRoot":"","sources":["../src/balance.ts"],"names":[],"mappings":"AAUA,MAAM,MAAM,WAAW,GACnB;IAAE,QAAQ,EAAE,IAAI,CAAC;IAAC,gBAAgB,EAAE,MAAM,CAAA;CAAE,GAC5C;IAAE,QAAQ,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,kBAAkB,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,CAAA;AAEtE;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAChC,eAAe,EAAE,MAAM,EACvB,QAAQ,EAAE,SAAS,MAAM,EAAE,EAC3B,OAAO,EAAE,SAAS,MAAM,EAAE,GACzB,MAAM,CAGR;AAED;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAC1B,eAAe,EAAE,MAAM,EACvB,QAAQ,EAAE,SAAS,MAAM,EAAE,EAC3B,OAAO,EAAE,SAAS,MAAM,EAAE,EAC1B,SAAS,EAAE,MAAM,GAChB,WAAW,CASb"}

package/payload/platform/lib/ledger-core/dist/balance.js

@@ -0,0 +1,38 @@
+/**
+ * Task 1771 — the outstanding invariant, defined exactly once.
+ *
+ * Nothing stores a balance. `outstanding`, `balance` and `amountPaid` are
+ * forbidden properties on :Invoice and :InboundInvoice (schema-base.md
+ * § Forbidden Properties), because a stored figure drifts silently the moment
+ * a payment lands by any other path. Every consumer computes from this module.
+ */
+import { toMinor, fromMinor } from './money.js';
+/**
+ * outstanding = totalPaymentDue - sum(payments) - sum(credits).
+ *
+ * A credit reduces what is owed exactly as a payment does; the two differ in
+ * provenance, not arithmetic, which is why they are summed together here.
+ */
+export function computeOutstanding(totalPaymentDue, payments, credits) {
+    const applied = [...payments, ...credits].reduce((acc, a) => acc + toMinor(a), 0);
+    return fromMinor(toMinor(totalPaymentDue) - applied);
+}
+/**
+ * Validates one candidate payment or credit against what is still outstanding.
+ *
+ * Never clamps. A candidate that would take applied-to-date above the invoice
+ * total is rejected outright and the caller reports it, rather than silently
+ * recording a figure that does not reconcile. A non-positive candidate is
+ * rejected for the same reason: it is not a payment.
+ */
+export function applyPayment(totalPaymentDue, payments, credits, candidate) {
+    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)) };
+}
+//# sourceMappingURL=balance.js.map

package/payload/platform/lib/ledger-core/dist/balance.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"balance.js","sourceRoot":"","sources":["../src/balance.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,EAAE,OAAO,EAAE,SAAS,EAAE,MAAM,YAAY,CAAA;AAM/C;;;;;GAKG;AACH,MAAM,UAAU,kBAAkB,CAChC,eAAuB,EACvB,QAA2B,EAC3B,OAA0B;IAE1B,MAAM,OAAO,GAAG,CAAC,GAAG,QAAQ,EAAE,GAAG,OAAO,CAAC,CAAC,MAAM,CAAC,CAAC,GAAG,EAAE,CAAC,EAAE,EAAE,CAAC,GAAG,GAAG,OAAO,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAA;IACjF,OAAO,SAAS,CAAC,OAAO,CAAC,eAAe,CAAC,GAAG,OAAO,CAAC,CAAA;AACtD,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,YAAY,CAC1B,eAAuB,EACvB,QAA2B,EAC3B,OAA0B,EAC1B,SAAiB;IAEjB,MAAM,SAAS,GAAG,kBAAkB,CAAC,eAAe,EAAE,QAAQ,EAAE,OAAO,CAAC,CAAA;IACxE,IAAI,OAAO,CAAC,SAAS,CAAC,IAAI,CAAC,EAAE,CAAC;QAC5B,OAAO,EAAE,QAAQ,EAAE,KAAK,EAAE,MAAM,EAAE,kBAAkB,EAAE,SAAS,EAAE,CAAA;IACnE,CAAC;IACD,IAAI,OAAO,CAAC,SAAS,CAAC,GAAG,OAAO,CAAC,SAAS,CAAC,EAAE,CAAC;QAC5C,OAAO,EAAE,QAAQ,EAAE,KAAK,EAAE,MAAM,EAAE,kBAAkB,EAAE,SAAS,EAAE,CAAA;IACnE,CAAC;IACD,OAAO,EAAE,QAAQ,EAAE,IAAI,EAAE,gBAAgB,EAAE,SAAS,CAAC,OAAO,CAAC,SAAS,CAAC,GAAG,OAAO,CAAC,SAAS,CAAC,CAAC,EAAE,CAAA;AACjG,CAAC"}

package/payload/platform/lib/ledger-core/dist/index.d.ts

@@ -0,0 +1,5 @@
+export * from './money.js';
+export * from './balance.js';
+export * from './ageing.js';
+export * from './reconcile.js';
+//# sourceMappingURL=index.d.ts.map

package/payload/platform/lib/ledger-core/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAA;AAC1B,cAAc,cAAc,CAAA;AAC5B,cAAc,aAAa,CAAA;AAC3B,cAAc,gBAAgB,CAAA"}

package/payload/platform/lib/ledger-core/dist/index.js

@@ -0,0 +1,5 @@
+export * from './money.js';
+export * from './balance.js';
+export * from './ageing.js';
+export * from './reconcile.js';
+//# sourceMappingURL=index.js.map

package/payload/platform/lib/ledger-core/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAA;AAC1B,cAAc,cAAc,CAAA;AAC5B,cAAc,aAAa,CAAA;AAC3B,cAAc,gBAAgB,CAAA"}

package/payload/platform/lib/ledger-core/dist/money.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Task 1771 — money is compared and summed in integer minor units so the
+ * outstanding invariant is exact and never subject to float drift. Graph
+ * storage is unchanged: `amount` and `totalPaymentDue` stay decimal numbers,
+ * matching the existing JobLogic-exact construction rows. Conversion happens
+ * here, at the boundary, so no stored value changes shape.
+ */
+/** Decimal major units to integer minor units. */
+export declare function toMinor(n: number): number;
+/** Integer minor units back to decimal major units. */
+export declare function fromMinor(n: number): number;
+//# sourceMappingURL=money.d.ts.map

package/payload/platform/lib/ledger-core/dist/money.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"money.d.ts","sourceRoot":"","sources":["../src/money.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,kDAAkD;AAClD,wBAAgB,OAAO,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAEzC;AAED,uDAAuD;AACvD,wBAAgB,SAAS,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAE3C"}

package/payload/platform/lib/ledger-core/dist/money.js

@@ -0,0 +1,16 @@
+/**
+ * Task 1771 — money is compared and summed in integer minor units so the
+ * outstanding invariant is exact and never subject to float drift. Graph
+ * storage is unchanged: `amount` and `totalPaymentDue` stay decimal numbers,
+ * matching the existing JobLogic-exact construction rows. Conversion happens
+ * here, at the boundary, so no stored value changes shape.
+ */
+/** Decimal major units to integer minor units. */
+export function toMinor(n) {
+    return Math.round(n * 100);
+}
+/** Integer minor units back to decimal major units. */
+export function fromMinor(n) {
+    return n / 100;
+}
+//# sourceMappingURL=money.js.map

package/payload/platform/lib/ledger-core/dist/money.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"money.js","sourceRoot":"","sources":["../src/money.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,kDAAkD;AAClD,MAAM,UAAU,OAAO,CAAC,CAAS;IAC/B,OAAO,IAAI,CAAC,KAAK,CAAC,CAAC,GAAG,GAAG,CAAC,CAAA;AAC5B,CAAC;AAED,uDAAuD;AACvD,MAAM,UAAU,SAAS,CAAC,CAAS;IACjC,OAAO,CAAC,GAAG,GAAG,CAAA;AAChB,CAAC"}

package/payload/platform/lib/ledger-core/dist/reconcile.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Task 1771 — the ledger census finding.
+ *
+ * Four of the ledger's failure modes emit no event of their own: a write that
+ * was narrated but never landed, a payment with no parent invoice, a stored
+ * balance property that has drifted, and a duplicate payment created by a
+ * non-deterministic paymentId. None of them can be caught by logging an
+ * action, because no action occurs. This reconcile is the substitute, and it
+ * is called from two places: the `ledger-reconcile` tool (on demand) and the
+ * standing interval in the UI server. Both share this function so the two
+ * forms cannot report different things.
+ *
+ * Pure: no I/O, and `now` is a parameter rather than a Date.now() call.
+ */
+/** The index names schema.cypher declares for the ledger. Their absence from a
+ *  live database means schema.cypher was edited but seed-neo4j.sh never re-ran
+ *  on that install, which emits nothing on its own. Defined here because both
+ *  the on-demand tool and the standing census check the same list; two copies
+ *  would let them disagree about whether the schema is applied. */
+export declare const LEDGER_INDEX_NAMES: readonly string[];
+export interface PaymentKey {
+    invoiceId: string;
+    paymentId: string;
+    amount: number;
+    date: string;
+}
+export interface LedgerCensusRows {
+    invoices: number;
+    payments: number;
+    orphanPayments: number;
+    storedBalanceProps: number;
+    paymentKeys: readonly PaymentKey[];
+    declaredNotLive: readonly string[];
+}
+export interface LedgerCensusFinding {
+    invoices: number;
+    payments: number;
+    orphanPayments: number;
+    storedBalanceProps: number;
+    suspectDuplicates: number;
+    declaredNotLive: readonly string[];
+    alarm: boolean;
+}
+export declare function reconcileLedger(rows: LedgerCensusRows, _now: number): LedgerCensusFinding;
+/**
+ * The one `[ledger-census]` line format. Shared by the on-demand tool and the
+ * standing interval so a log search finds both, and so a new counter cannot be
+ * added to one emission and missed by the other.
+ */
+export declare function formatCensusLine(f: LedgerCensusFinding): string;
+//# sourceMappingURL=reconcile.d.ts.map

package/payload/platform/lib/ledger-core/dist/reconcile.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"reconcile.d.ts","sourceRoot":"","sources":["../src/reconcile.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH;;;;mEAImE;AACnE,eAAO,MAAM,kBAAkB,EAAE,SAAS,MAAM,EAO/C,CAAA;AAED,MAAM,WAAW,UAAU;IACzB,SAAS,EAAE,MAAM,CAAA;IACjB,SAAS,EAAE,MAAM,CAAA;IACjB,MAAM,EAAE,MAAM,CAAA;IACd,IAAI,EAAE,MAAM,CAAA;CACb;AAED,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,EAAE,MAAM,CAAA;IAChB,QAAQ,EAAE,MAAM,CAAA;IAChB,cAAc,EAAE,MAAM,CAAA;IACtB,kBAAkB,EAAE,MAAM,CAAA;IAC1B,WAAW,EAAE,SAAS,UAAU,EAAE,CAAA;IAClC,eAAe,EAAE,SAAS,MAAM,EAAE,CAAA;CACnC;AAED,MAAM,WAAW,mBAAmB;IAClC,QAAQ,EAAE,MAAM,CAAA;IAChB,QAAQ,EAAE,MAAM,CAAA;IAChB,cAAc,EAAE,MAAM,CAAA;IACtB,kBAAkB,EAAE,MAAM,CAAA;IAC1B,iBAAiB,EAAE,MAAM,CAAA;IACzB,eAAe,EAAE,SAAS,MAAM,EAAE,CAAA;IAClC,KAAK,EAAE,OAAO,CAAA;CACf;AAwBD,wBAAgB,eAAe,CAAC,IAAI,EAAE,gBAAgB,EAAE,IAAI,EAAE,MAAM,GAAG,mBAAmB,CAiBzF;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,CAAC,EAAE,mBAAmB,GAAG,MAAM,CAO/D"}

package/payload/platform/lib/ledger-core/dist/reconcile.js

@@ -0,0 +1,77 @@
+/**
+ * Task 1771 — the ledger census finding.
+ *
+ * Four of the ledger's failure modes emit no event of their own: a write that
+ * was narrated but never landed, a payment with no parent invoice, a stored
+ * balance property that has drifted, and a duplicate payment created by a
+ * non-deterministic paymentId. None of them can be caught by logging an
+ * action, because no action occurs. This reconcile is the substitute, and it
+ * is called from two places: the `ledger-reconcile` tool (on demand) and the
+ * standing interval in the UI server. Both share this function so the two
+ * forms cannot report different things.
+ *
+ * Pure: no I/O, and `now` is a parameter rather than a Date.now() call.
+ */
+/** The index names schema.cypher declares for the ledger. Their absence from a
+ *  live database means schema.cypher was edited but seed-neo4j.sh never re-ran
+ *  on that install, which emits nothing on its own. Defined here because both
+ *  the on-demand tool and the standing census check the same list; two copies
+ *  would let them disagree about whether the schema is applied. */
+export const LEDGER_INDEX_NAMES = [
+    "invoice_account_confirmation_unique",
+    "cash_entry_account_entryid_unique",
+    "cash_entry_account",
+    "invoice_line_account",
+    "invoice_payment_account",
+    "credit_account",
+];
+/**
+ * Counts payments that share (invoiceId, amount, date) across two or more
+ * distinct paymentId values. For a group of n distinct ids the contribution is
+ * n-1, because exactly one member of the group is the legitimate payment.
+ *
+ * Grouping on distinct ids, not on row count, is what keeps a genuine retry
+ * quiet: a retry that MERGEs onto the same deterministic paymentId appears
+ * twice in the rows but once in the id set, and is not a duplicate.
+ */
+function countSuspectDuplicates(keys) {
+    const groups = new Map();
+    for (const k of keys) {
+        const composite = `${k.invoiceId}|${k.amount}|${k.date}`;
+        const ids = groups.get(composite) ?? new Set();
+        ids.add(k.paymentId);
+        groups.set(composite, ids);
+    }
+    let total = 0;
+    for (const ids of groups.values())
+        total += Math.max(0, ids.size - 1);
+    return total;
+}
+export function reconcileLedger(rows, _now) {
+    const suspectDuplicates = countSuspectDuplicates(rows.paymentKeys);
+    const alarm = rows.orphanPayments > 0 ||
+        rows.storedBalanceProps > 0 ||
+        suspectDuplicates > 0 ||
+        rows.declaredNotLive.length > 0;
+    return {
+        invoices: rows.invoices,
+        payments: rows.payments,
+        orphanPayments: rows.orphanPayments,
+        storedBalanceProps: rows.storedBalanceProps,
+        suspectDuplicates,
+        declaredNotLive: rows.declaredNotLive,
+        alarm,
+    };
+}
+/**
+ * The one `[ledger-census]` line format. Shared by the on-demand tool and the
+ * standing interval so a log search finds both, and so a new counter cannot be
+ * added to one emission and missed by the other.
+ */
+export function formatCensusLine(f) {
+    return (`[ledger-census] invoices=${f.invoices} payments=${f.payments} ` +
+        `orphanPayments=${f.orphanPayments} storedBalanceProps=${f.storedBalanceProps} ` +
+        `suspectDuplicates=${f.suspectDuplicates} ` +
+        `declaredNotLive=${f.declaredNotLive.length === 0 ? "none" : f.declaredNotLive.join(",")}`);
+}
+//# sourceMappingURL=reconcile.js.map

package/payload/platform/lib/ledger-core/dist/reconcile.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"reconcile.js","sourceRoot":"","sources":["../src/reconcile.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH;;;;mEAImE;AACnE,MAAM,CAAC,MAAM,kBAAkB,GAAsB;IACnD,qCAAqC;IACrC,mCAAmC;IACnC,oBAAoB;IACpB,sBAAsB;IACtB,yBAAyB;IACzB,gBAAgB;CACjB,CAAA;AA4BD;;;;;;;;GAQG;AACH,SAAS,sBAAsB,CAAC,IAA2B;IACzD,MAAM,MAAM,GAAG,IAAI,GAAG,EAAuB,CAAA;IAC7C,KAAK,MAAM,CAAC,IAAI,IAAI,EAAE,CAAC;QACrB,MAAM,SAAS,GAAG,GAAG,CAAC,CAAC,SAAS,IAAI,CAAC,CAAC,MAAM,IAAI,CAAC,CAAC,IAAI,EAAE,CAAA;QACxD,MAAM,GAAG,GAAG,MAAM,CAAC,GAAG,CAAC,SAAS,CAAC,IAAI,IAAI,GAAG,EAAU,CAAA;QACtD,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,SAAS,CAAC,CAAA;QACpB,MAAM,CAAC,GAAG,CAAC,SAAS,EAAE,GAAG,CAAC,CAAA;IAC5B,CAAC;IACD,IAAI,KAAK,GAAG,CAAC,CAAA;IACb,KAAK,MAAM,GAAG,IAAI,MAAM,CAAC,MAAM,EAAE;QAAE,KAAK,IAAI,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,GAAG,CAAC,IAAI,GAAG,CAAC,CAAC,CAAA;IACrE,OAAO,KAAK,CAAA;AACd,CAAC;AAED,MAAM,UAAU,eAAe,CAAC,IAAsB,EAAE,IAAY;IAClE,MAAM,iBAAiB,GAAG,sBAAsB,CAAC,IAAI,CAAC,WAAW,CAAC,CAAA;IAClE,MAAM,KAAK,GACT,IAAI,CAAC,cAAc,GAAG,CAAC;QACvB,IAAI,CAAC,kBAAkB,GAAG,CAAC;QAC3B,iBAAiB,GAAG,CAAC;QACrB,IAAI,CAAC,eAAe,CAAC,MAAM,GAAG,CAAC,CAAA;IAEjC,OAAO;QACL,QAAQ,EAAE,IAAI,CAAC,QAAQ;QACvB,QAAQ,EAAE,IAAI,CAAC,QAAQ;QACvB,cAAc,EAAE,IAAI,CAAC,cAAc;QACnC,kBAAkB,EAAE,IAAI,CAAC,kBAAkB;QAC3C,iBAAiB;QACjB,eAAe,EAAE,IAAI,CAAC,eAAe;QACrC,KAAK;KACN,CAAA;AACH,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,gBAAgB,CAAC,CAAsB;IACrD,OAAO,CACL,4BAA4B,CAAC,CAAC,QAAQ,aAAa,CAAC,CAAC,QAAQ,GAAG;QAChE,kBAAkB,CAAC,CAAC,cAAc,uBAAuB,CAAC,CAAC,kBAAkB,GAAG;QAChF,qBAAqB,CAAC,CAAC,iBAAiB,GAAG;QAC3C,mBAAmB,CAAC,CAAC,eAAe,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,eAAe,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAC3F,CAAA;AACH,CAAC"}

package/payload/platform/lib/ledger-core/package.json

@@ -0,0 +1,16 @@
+{
+  "name": "@maxy/ledger-core",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "main": "dist/index.js",
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.7.0",
+    "vitest": "^4.1.2"
+  }
+}

package/payload/platform/lib/ledger-core/src/__tests__/ageing.test.ts

@@ -0,0 +1,42 @@
+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,
+    })
+  })
+  it('does not drift when summing many decimal amounts', () => {
+    const rows = Array.from({ length: 3 }, (_, i) => inv(`r${i}`, 1, 33.33))
+    expect(ageBuckets(rows, NOW).total).toBe(99.99)
+  })
+})