@rubytech/create-maxy-code 0.1.470 → 0.1.471

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

@@ -0,0 +1,48 @@
+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)
+  })
+})

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

@@ -0,0 +1,87 @@
+import { describe, it, expect } from 'vitest'
+import { reconcileLedger, formatCensusLine, LEDGER_INDEX_NAMES } from '../reconcile.js'
+
+const clean = {
+  invoices: 12,
+  payments: 20,
+  orphanPayments: 0,
+  storedBalanceProps: 0,
+  paymentKeys: [],
+  declaredNotLive: [],
+}
+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('counts n-1 duplicates per colliding group', () => {
+    const paymentKeys = [
+      { 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 }, NOW)
+    expect(f.suspectDuplicates).toBe(2)
+    expect(f.alarm).toBe(true)
+  })
+  it('does not flag the same paymentId seen once', () => {
+    const paymentKeys = [{ invoiceId: 'i1', paymentId: 'p1', amount: 100, date: '2026-07-01' }]
+    expect(reconcileLedger({ ...clean, paymentKeys }, NOW).suspectDuplicates).toBe(0)
+  })
+  it('does not flag two genuine same-day payments of different amounts', () => {
+    const paymentKeys = [
+      { invoiceId: 'i1', paymentId: 'p1', amount: 100, date: '2026-07-01' },
+      { invoiceId: 'i1', paymentId: 'p2', amount: 250, date: '2026-07-01' },
+    ]
+    expect(reconcileLedger({ ...clean, paymentKeys }, NOW).suspectDuplicates).toBe(0)
+  })
+  it('does not flag the same key repeated under one paymentId', () => {
+    const paymentKeys = [
+      { invoiceId: 'i1', paymentId: 'p1', amount: 100, date: '2026-07-01' },
+      { invoiceId: 'i1', paymentId: 'p1', amount: 100, date: '2026-07-01' },
+    ]
+    expect(reconcileLedger({ ...clean, paymentKeys }, NOW).suspectDuplicates).toBe(0)
+  })
+  it('separates groups by invoice', () => {
+    const paymentKeys = [
+      { invoiceId: 'i1', paymentId: 'p1', amount: 100, date: '2026-07-01' },
+      { invoiceId: 'i2', paymentId: 'p2', amount: 100, date: '2026-07-01' },
+    ]
+    expect(reconcileLedger({ ...clean, paymentKeys }, NOW).suspectDuplicates).toBe(0)
+  })
+
+  it('formats one census line carrying every counter', () => {
+    const line = formatCensusLine(reconcileLedger(clean, NOW))
+    for (const field of [
+      '[ledger-census]',
+      'invoices=12',
+      'payments=20',
+      'orphanPayments=0',
+      'storedBalanceProps=0',
+      'suspectDuplicates=0',
+      'declaredNotLive=none',
+    ]) {
+      expect(line).toContain(field)
+    }
+  })
+
+  it('names the missing indexes in the line when some are absent', () => {
+    const f = reconcileLedger({ ...clean, declaredNotLive: ['cash_entry_account'] }, NOW)
+    expect(formatCensusLine(f)).toContain('declaredNotLive=cash_entry_account')
+  })
+
+  it('declares the six ledger index names schema.cypher creates', () => {
+    expect(LEDGER_INDEX_NAMES).toHaveLength(6)
+    expect(LEDGER_INDEX_NAMES).toContain('cash_entry_account_entryid_unique')
+  })
+})

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

@@ -0,0 +1,51 @@
+/**
+ * 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 interface OpenInvoice {
+  ref: string
+  dueDateMs: number
+  outstanding: number
+}
+
+export interface AgeBuckets {
+  current: number
+  d31to60: number
+  d61to90: number
+  d90plus: number
+  total: number
+}
+
+export function ageBuckets(invoices: readonly OpenInvoice[], now: number): AgeBuckets {
+  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),
+  }
+}

package/payload/platform/lib/ledger-core/src/balance.ts

@@ -0,0 +1,52 @@
+/**
+ * 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'
+
+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 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 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: 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/payload/platform/lib/ledger-core/src/index.ts

@@ -0,0 +1,4 @@
+export * from './money.js'
+export * from './balance.js'
+export * from './ageing.js'
+export * from './reconcile.js'

package/payload/platform/lib/ledger-core/src/money.ts

@@ -0,0 +1,17 @@
+/**
+ * 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: number): number {
+  return Math.round(n * 100)
+}
+
+/** Integer minor units back to decimal major units. */
+export function fromMinor(n: number): number {
+  return n / 100
+}

package/payload/platform/lib/ledger-core/src/reconcile.ts

@@ -0,0 +1,109 @@
+/**
+ * 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: readonly string[] = [
+  "invoice_account_confirmation_unique",
+  "cash_entry_account_entryid_unique",
+  "cash_entry_account",
+  "invoice_line_account",
+  "invoice_payment_account",
+  "credit_account",
+]
+
+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
+}
+
+/**
+ * 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: readonly PaymentKey[]): number {
+  const groups = new Map<string, Set<string>>()
+  for (const k of keys) {
+    const composite = `${k.invoiceId}|${k.amount}|${k.date}`
+    const ids = groups.get(composite) ?? new Set<string>()
+    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: LedgerCensusRows, _now: number): LedgerCensusFinding {
+  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: LedgerCensusFinding): string {
+  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(",")}`
+  )
+}

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

@@ -0,0 +1,6 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": { "outDir": "dist", "rootDir": "src" },
+  "include": ["src"],
+  "exclude": ["src/__tests__"]
+}

package/payload/platform/neo4j/schema.cypher

@@ -467,6 +467,7 @@ FOR (n:LocalBusiness|Service|PriceSpecification|OpeningHoursSpecification|Organi
     |Listing|Property|Viewing|Offer|PostalAddress|Sale|Chain|ChainLink
     |Job|Quote|QuoteLine|Valuation|Milestone|VariationNote|Invoice|InboundInvoice|JobCost|WhatsAppGroup
     |Customer|Site|Asset|Visit|Part|PurchaseOrder|PpmContract|Contact|PurchaseOrderLine|InvoiceLine|InvoicePayment|Credit|Note
+    |CashEntry
     |Person|UserProfile|Preference|AdminUser|AccessGrant
     |KnowledgeDocument|ConversationArchive|Section|Chunk|DigitalDocument|CreativeWork|Question|FAQPage|DefinedTerm|Review|ImageObject
     |Conversation|AdminConversation|PublicConversation|Message|UserMessage|AssistantMessage|ToolCall
@@ -1563,9 +1564,24 @@ FOR (ii:InboundInvoice) REQUIRE (ii.accountId, ii.supplier, ii.confirmationNumbe
 CREATE INDEX inbound_invoice_account IF NOT EXISTS
 FOR (ii:InboundInvoice) ON (ii.accountId);
 
+// Task 1771 — :Invoice gained the uniqueness constraint schema-base.md already
+// claimed as its natural key but never declared, so a second write of the same
+// confirmationNumber merges rather than creating a rival invoice that would
+// split a payment history in two.
+CREATE CONSTRAINT invoice_account_confirmation_unique IF NOT EXISTS
+FOR (i:Invoice) REQUIRE (i.accountId, i.confirmationNumber) IS UNIQUE;
+
 CREATE INDEX invoice_account IF NOT EXISTS
 FOR (i:Invoice) ON (i.accountId);
 
+// :CashEntry (Task 1771) — one movement of money not attached to any invoice.
+// Direction lives on the node because there is no parent label to derive it
+// from, unlike :InvoicePayment.
+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);
+
 // :CheckIn -> :JobCost (Task 1084). A logged labour day is an incurred labour
 // cost (costType:'labour'); JobCost also carries material/travel/mileage/
 // expense/subcontractor/scheduleOfRates lines. Clean natural key (costId).

package/payload/platform/package.json

@@ -6,8 +6,8 @@
     "services/*"
   ],
   "scripts": {
-    "build": "tsc -p lib/models/tsconfig.json && tsc -p lib/mcp-spawn-tee/tsconfig.json && tsc -p lib/mcp-lifeline/tsconfig.json && tsc -p lib/mcp-eager/tsconfig.json && tsc -p lib/account-enumeration/tsconfig.json && tsc -p lib/account-scope/tsconfig.json && tsc -p lib/graph-write/tsconfig.json && tsc -p lib/embed-client/tsconfig.json && tsc -p lib/graph-mcp/tsconfig.json && tsc -p lib/graph-trash/tsconfig.json && tsc -p lib/active-rules/tsconfig.json && tsc -p lib/admin-conversation-purge/tsconfig.json && tsc -p lib/graph-search/tsconfig.json && tsc -p lib/graph-style/tsconfig.json && tsc -p lib/device-url/tsconfig.json && tsc -p lib/brand-templating/tsconfig.json && tsc -p lib/entitlement/tsconfig.json && tsc -p lib/task-secrets/tsconfig.json && tsc -p lib/admins-write/tsconfig.json && tsc -p lib/admin-access-password/tsconfig.json && tsc -p lib/persistent-components/tsconfig.json && tsc -p lib/require-port-env/tsconfig.json && tsc -p lib/aeo-llms-txt-writer/tsconfig.json && tsc -p lib/obsidian-parser/tsconfig.json && tsc -p lib/storage-broker/tsconfig.json && tsc -p services/claude-session-manager/tsconfig.json && tsc -p services/whatsapp-channel/tsconfig.json && tsc -p services/webchat-channel/tsconfig.json && tsc -p services/telegram-channel/tsconfig.json && NODE_OPTIONS='--max-old-space-size=8192' tsc -b plugins/*/mcp/tsconfig.json",
-    "build:lib": "tsc -p lib/models/tsconfig.json && tsc -p lib/mcp-spawn-tee/tsconfig.json && tsc -p lib/mcp-lifeline/tsconfig.json && tsc -p lib/mcp-eager/tsconfig.json && tsc -p lib/account-enumeration/tsconfig.json && tsc -p lib/account-scope/tsconfig.json && tsc -p lib/graph-write/tsconfig.json && tsc -p lib/embed-client/tsconfig.json && tsc -p lib/graph-mcp/tsconfig.json && tsc -p lib/graph-trash/tsconfig.json && tsc -p lib/active-rules/tsconfig.json && tsc -p lib/admin-conversation-purge/tsconfig.json && tsc -p lib/graph-search/tsconfig.json && tsc -p lib/graph-style/tsconfig.json && tsc -p lib/device-url/tsconfig.json && tsc -p lib/brand-templating/tsconfig.json && tsc -p lib/entitlement/tsconfig.json && tsc -p lib/task-secrets/tsconfig.json && tsc -p lib/admins-write/tsconfig.json && tsc -p lib/admin-access-password/tsconfig.json && tsc -p lib/persistent-components/tsconfig.json && tsc -p lib/require-port-env/tsconfig.json && tsc -p lib/aeo-llms-txt-writer/tsconfig.json && tsc -p lib/obsidian-parser/tsconfig.json && tsc -p lib/storage-broker/tsconfig.json",
+    "build": "tsc -p lib/models/tsconfig.json && tsc -p lib/mcp-spawn-tee/tsconfig.json && tsc -p lib/mcp-lifeline/tsconfig.json && tsc -p lib/mcp-eager/tsconfig.json && tsc -p lib/account-enumeration/tsconfig.json && tsc -p lib/account-scope/tsconfig.json && tsc -p lib/graph-write/tsconfig.json && tsc -p lib/ledger-core/tsconfig.json && tsc -p lib/embed-client/tsconfig.json && tsc -p lib/graph-mcp/tsconfig.json && tsc -p lib/graph-trash/tsconfig.json && tsc -p lib/active-rules/tsconfig.json && tsc -p lib/admin-conversation-purge/tsconfig.json && tsc -p lib/graph-search/tsconfig.json && tsc -p lib/graph-style/tsconfig.json && tsc -p lib/device-url/tsconfig.json && tsc -p lib/brand-templating/tsconfig.json && tsc -p lib/entitlement/tsconfig.json && tsc -p lib/task-secrets/tsconfig.json && tsc -p lib/admins-write/tsconfig.json && tsc -p lib/admin-access-password/tsconfig.json && tsc -p lib/persistent-components/tsconfig.json && tsc -p lib/require-port-env/tsconfig.json && tsc -p lib/aeo-llms-txt-writer/tsconfig.json && tsc -p lib/obsidian-parser/tsconfig.json && tsc -p lib/storage-broker/tsconfig.json && tsc -p services/claude-session-manager/tsconfig.json && tsc -p services/whatsapp-channel/tsconfig.json && tsc -p services/webchat-channel/tsconfig.json && tsc -p services/telegram-channel/tsconfig.json && NODE_OPTIONS='--max-old-space-size=8192' tsc -b plugins/*/mcp/tsconfig.json",
+    "build:lib": "tsc -p lib/models/tsconfig.json && tsc -p lib/mcp-spawn-tee/tsconfig.json && tsc -p lib/mcp-lifeline/tsconfig.json && tsc -p lib/mcp-eager/tsconfig.json && tsc -p lib/account-enumeration/tsconfig.json && tsc -p lib/account-scope/tsconfig.json && tsc -p lib/graph-write/tsconfig.json && tsc -p lib/ledger-core/tsconfig.json && tsc -p lib/embed-client/tsconfig.json && tsc -p lib/graph-mcp/tsconfig.json && tsc -p lib/graph-trash/tsconfig.json && tsc -p lib/active-rules/tsconfig.json && tsc -p lib/admin-conversation-purge/tsconfig.json && tsc -p lib/graph-search/tsconfig.json && tsc -p lib/graph-style/tsconfig.json && tsc -p lib/device-url/tsconfig.json && tsc -p lib/brand-templating/tsconfig.json && tsc -p lib/entitlement/tsconfig.json && tsc -p lib/task-secrets/tsconfig.json && tsc -p lib/admins-write/tsconfig.json && tsc -p lib/admin-access-password/tsconfig.json && tsc -p lib/persistent-components/tsconfig.json && tsc -p lib/require-port-env/tsconfig.json && tsc -p lib/aeo-llms-txt-writer/tsconfig.json && tsc -p lib/obsidian-parser/tsconfig.json && tsc -p lib/storage-broker/tsconfig.json",
     "gen:canonical-tools": "node scripts/generate-canonical-tool-names.mjs",
     "build:memory": "tsc -p plugins/memory/mcp/tsconfig.json",
     "build:contacts": "tsc -p plugins/contacts/mcp/tsconfig.json",

package/payload/platform/plugins/.claude-plugin/marketplace.json

@@ -74,6 +74,11 @@
       "source": "./graph-viewer",
       "version": "0.1.0"
     },
+    {
+      "name": "ledger",
+      "source": "./ledger",
+      "version": "0.1.0"
+    },
     {
       "name": "linkedin-extension",
       "source": "./linkedin-extension",

package/payload/platform/plugins/admin/hooks/lib/maxy-mcp-plugins.txt

@@ -9,6 +9,7 @@ google
 graph
 graph-viewer
 joblogic
+ledger
 memory
 outlook
 quickbooks

package/payload/platform/plugins/admin/skills/platform-architecture/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: platform-architecture
 description: Use when grounding any documented-surface claim about what Maxy ships — plugins, skills, specialists, install/deploy flows, internals. This is the install catalogue, not evidence of what is enabled on the current account. For install state on this account, call `capabilities-here`; for documented surface, cite the `Source:` URL inline.
-content-hash: sha256:4f7717f06a4d87172809793ad9a02cfe57e3b4f6ec4b2f0f2dbff39792ef5456
+content-hash: sha256:46e07a18921b711849e53f63b8c29b72f3324f91bc682eb5be585ccd64c98971
 brand: maxy-code
 product-name: Maxy
 ---
@@ -606,6 +606,54 @@ Pausing keeps a workflow but stops it running. Editing replaces the steps or the
 
 A workflow can run on a schedule instead of on demand. Tell Maxy when you want it to run, for example "run the daily summary workflow every morning at eight," and it sets up the schedule. Scheduled runs happen with no one present, so a workflow that needs you to supply inputs is best run on demand rather than scheduled.
 
+---
+# Cash Book + AR/AP Ledger
+Source: https://docs.getmaxy.com/ledger.md
+
+# Ledger
+
+A cash book with receivables and payables. It records what you invoiced, what you were billed, what was paid, and money that moved without an invoice, then tells you what is still outstanding.
+
+## What it is not
+
+It is not double-entry bookkeeping. There is no chart of accounts, no journals, no trial balance. It computes no VAT and handles a single currency. It does not read bank feeds and it does not talk to QuickBooks.
+
+If you need statutory accounts, this is not that. It is the answer to "who owes me what, what do I owe, and where did the money go".
+
+## The seven things you can ask for
+
+**Record an invoice you raised.** A reference, who owes you, the amount, and when it is due.
+
+**Record a bill you received.** The same, in the other direction.
+
+**Record a payment.** Against either an invoice or a bill. You give the reference, the amount, the date and how it was paid.
+
+**Record a credit.** Against an invoice you raised. It reduces what is owed exactly as a payment does.
+
+**Record a cash movement.** Money in or out that belongs to no invoice: bank charges, a cash sale, drawings, a refund.
+
+**Ask what is outstanding on one document.** You get the total, what has been paid, what has been credited, and what remains.
+
+**Ask for a statement.** Everything owed to you and everything you owe, sorted into 0-30, 31-60, 61-90 and 90+ days overdue, plus net cash.
+
+## Three behaviours worth knowing about
+
+**What is outstanding is never stored.** It is worked out from the payments each time you ask. This means the figure cannot fall out of step with the payments behind it. If it were stored, a payment recorded by any route that forgot to update it would leave the invoice quietly reporting a wrong number, and nothing would fail.
+
+**Paying more than is owed is refused.** If an invoice has 4,400 left and you try to record 5,000, nothing is written and you are told the figure that would settle it. It is not rounded down to 4,400 and it is not recorded anyway. A ledger that quietly accepts an impossible payment is worse than one that says no.
+
+**Every payment is read back.** After a payment is written, the invoice is re-read from the graph and the outstanding figure is checked against what was expected. If they disagree you are told to stop recording against that invoice until it is sorted out. Writing something is not the same as it having landed.
+
+## The health check
+
+Some ways this can go wrong announce themselves. Others do not: a payment that ends up attached to no invoice, a stale balance field reappearing, or the same payment recorded twice under two different ids. None of those produce an error at the time, because nothing goes wrong at the moment they happen.
+
+So there is a check that runs by itself every fifteen minutes and writes one line to the log beginning `[ledger-census]`. When it is healthy the counters are all zero. When something is wrong the line ends with `alarm=true` and says which of the four it found.
+
+You can also ask for that check on demand at any time, and it reports the same thing in plain words.
+
+If you never see the line at all, that is itself the problem: it means the periodic check is not running.
+
 ---
 # Install Overview
 Source: https://docs.getmaxy.com/install.md
@@ -3138,6 +3186,54 @@ A 0.000 reading that persists across many polls while `top` shows load
 is the delta-cache regression signature (the single-flight promise was
 not released).
 
+## Activity view
+
+Source:
+[`server/routes/admin/activity.ts`](../../../ui/server/routes/admin/activity.ts)
+(house-gated proxy) and
+[`platform/ui/app/activity/page.tsx`](../../../ui/app/activity/page.tsx)
+(page). CSS lives under `.activity*` in
+[`platform/ui/app/globals.css`](../../../ui/app/globals.css).
+
+**What it shows.** `/activity` lists every live session across every account
+in the install, one row per session: account, title, model, status, age, idle,
+turn count, RSS, CPU %, cumulative tokens, and imputed GBP cost. Columns sort
+on click. The sidebar session list is scoped to the caller's own account, so
+this is the only surface that answers "where is the activity" install-wide.
+
+**House account only.** The manager binds loopback and gates nothing, so the
+scoping lives on the admin route. The house is resolved by the same three-arm
+predicate the spawn path uses (`resolveAccountDir`): exactly one `role:"house"`
+account, else a sole account declaring no role, else deny — two houses is
+corruption and denies rather than picking one. Both operands are null-checked,
+because `caller === house` alone is true for two nulls. A caller pinned
+elsewhere receives 403 and a logged `op=gate decision=deny` carrying its
+reason. The `HeaderMenu` item is admin-variant only for the same reason.
+
+Be precise about what this is. Under the install-wide access model every
+authenticated install admin can re-pin to any account via
+`POST /api/admin/session/switch-account`, so the gate is a scope selector, not
+an authority boundary between privilege levels.
+
+**Where the numbers come from.** The manager assembles them at its own
+`GET /activity`, joining the live PTY set, the watcher's per-row `accountId`,
+the JSONL enumerator (turns, model, tokens, last message), the PTY census
+(RSS and CPU), and a bounded metering fan-out. The admin route adds the one
+fact the manager cannot see: the `data/accounts` directory count, taken
+independently of `listValidAccounts()` so a rejected account shows as
+`onDisk > valid` rather than silently shortening the list.
+
+**Reading the cells.** A dash means unmeasured, never zero — an unmeasured CPU
+is not an idle session. Cost is the price arm matching the row's own model,
+because the metering core prices one token count under both Opus and Sonnet
+assumptions without knowing which ran; a model in neither family shows a dash.
+Every dashed cost carries its reason as a tooltip, so an unpriced model, a
+failed parse and a session with no transcript are distinguishable rather than
+three readings of the same glyph.
+A session whose sidecar carries no account shows `untagged` rather than being
+folded into the house. The census age is rendered because the snapshot is a 60s
+sample and a dead collector emits nothing.
+
 ## Sidebar surfaces
 
 The sidebar is the entire left column of the admin UI. Its full layout,
@@ -3973,7 +4069,7 @@ This tool is read-only and available to both public and admin agents.
 
 ### When conversations are created
 
-`:Conversation` nodes on webchat (admin login, "New conversation" in the burger, a new public visitor) are created lazily. Opening the chat or logging in does not write anything to the graph — Maxy only records the conversation once the user sends a second message. This keeps `conversation-search` and the Conversations modal free of one-turn abandoned threads. WhatsApp and Telegram take the opposite posture: every inbound — DM or group, allowed or activation-off, agent-invoked or gated — MERGEs the `:Conversation` and writes a forensic `:Message:WhatsAppMessage` row before any access-control decision. The graph is the durable record of every message the device received, not just the ones the agent replied to. See `.docs/web-chat.md` "Deferred conversation persistence" and `.docs/whatsapp.md` "Session continuity" for the full contract.
+`:Conversation` nodes on webchat (admin login, "New conversation" in the burger, a new public visitor) are created lazily. Opening the chat or logging in does not write anything to the graph — Maxy only records the conversation once the user sends a second message. This keeps `conversation-search` and the Conversations modal free of one-turn abandoned threads. WhatsApp and Telegram take the opposite posture: every inbound — DM or group, allowed or activation-off, agent-invoked or gated — MERGEs the `:Conversation` and writes a forensic `:Message:WhatsAppMessage` row before any access-control decision. The graph is the durable record of every message the device received, not just the ones the agent replied to. That forensic row is addressed by cacheKey (`default:<phone>`) on the socket-owning account and deliberately has no session behind it. A WhatsApp sender therefore carries a **second** `:Conversation`: the anchored row written at spawn on the account the session actually runs under, keyed by the session's own deterministic id, which is the row every `MATCH (c:Conversation {sessionId: $SESSION_ID})` resolves. Two rows, two jobs, not duplicates. See `.docs/web-chat.md` "Deferred conversation persistence", `.docs/whatsapp.md` "Session continuity", and `.docs/session-conversation-identity.md` for the per-channel identity contract.
 
 Each row in the Conversations modal exposes a `View logs` row-action that opens a popover with three links — **Stream**, **Errors**, **SSE** — each of which targets `/api/admin/logs?type={stream|error|sse}&sessionId={full-id}` in a new tab. The row's 8-char id chip is click-to-copy; hover reveals the full `sessionId` as a tooltip. See `.docs/web-chat.md` "In-chat retrieval" for the route contract and `console.debug` observability.