@happyvertical/smrt-ledgers 0.57.1 → 0.57.3

package/dist/smrt-knowledge.json

@@ -3,13 +3,13 @@
   "sensitiveFieldsExcluded": true,
   "generatedAt": "1970-01-01T00:00:00.000Z",
   "packageName": "@happyvertical/smrt-ledgers",
-  "packageVersion": "0.57.1",
+  "packageVersion": "0.57.3",
   "sourceManifestPath": "dist/manifest.json",
   "agentDocPath": "AGENTS.md",
   "sourceHashes": {
-    "manifest": "a53c901842be696daf66607dcd30aa3b05ad591dccb95697fc8b4844d478d011",
-    "packageJson": "45e64e181feb9199c9c5fb35a11ae9a42700b4937e717a80a8b1db9059f2ce2a",
-    "agents": "a1bece3d7fcf3112b2b5193fdc51cf4438ba8446af146d1c8ac1c95c8ed2f0c8"
+    "manifest": "57d87e11095c7b1fd6375eb2732225e7c376b4cf3c22b855f9f9ca9c0e44b062",
+    "packageJson": "dd2f5d9d1e5011ceff990ca1c5dcba0a60cced637aa8b0d3ffe7dfb4bbbb594f",
+    "agents": "d6890f0ff56feedb3cb850c32492d202b151e612e87873347fc99f0535ca1d44"
   },
   "exports": [
     ".",
@@ -338,6 +338,8 @@
         "findWithGlobals",
         "getAccountBalance",
         "getAccountLedger",
+        "getCounterpartyAging",
+        "getCounterpartyBalances",
         "getTotalsForDateRange",
         "getTrialBalance",
         "listPostedMovements"
@@ -405,6 +407,23 @@
           ],
           "returns": "Promise<Array<object>>"
         },
+        {
+          "name": "getCounterpartyAging",
+          "async": true,
+          "params": [
+            "options: PostedJournalMovementOptions",
+            "asOf: Date"
+          ],
+          "returns": "Promise<CounterpartyAgingRow[]>"
+        },
+        {
+          "name": "getCounterpartyBalances",
+          "async": true,
+          "params": [
+            "options: PostedJournalMovementOptions"
+          ],
+          "returns": "Promise<CounterpartyBalance[]>"
+        },
         {
           "name": "getTotalsForDateRange",
           "async": true,
@@ -444,6 +463,18 @@
           "operation": "findByAccount",
           "objectName": "@happyvertical/smrt-ledgers:JournalEntryCollection"
         },
+        {
+          "kind": "cli",
+          "name": "journalentrycollection_getCounterpartyBalances",
+          "operation": "getCounterpartyBalances",
+          "objectName": "@happyvertical/smrt-ledgers:JournalEntryCollection"
+        },
+        {
+          "kind": "cli",
+          "name": "journalentrycollection_getCounterpartyAging",
+          "operation": "getCounterpartyAging",
+          "objectName": "@happyvertical/smrt-ledgers:JournalEntryCollection"
+        },
         {
           "kind": "cli",
           "name": "journalentrycollection_getAccountBalance",
@@ -556,6 +587,20 @@
           "reason": "not listed in api.include",
           "objectName": "@happyvertical/smrt-ledgers:JournalEntryCollection"
         },
+        {
+          "kind": "api",
+          "operation": "getCounterpartyAging",
+          "code": "not-included",
+          "reason": "not listed in api.include",
+          "objectName": "@happyvertical/smrt-ledgers:JournalEntryCollection"
+        },
+        {
+          "kind": "api",
+          "operation": "getCounterpartyBalances",
+          "code": "not-included",
+          "reason": "not listed in api.include",
+          "objectName": "@happyvertical/smrt-ledgers:JournalEntryCollection"
+        },
         {
           "kind": "api",
           "operation": "getTotalsForDateRange",
@@ -909,6 +954,23 @@
       "tags": [],
       "risks": []
     },
+    {
+      "name": "LedgerCollection",
+      "qualifiedName": "@happyvertical/smrt-ledgers:LedgerCollection",
+      "collection": "ledgers",
+      "tableName": "ledgers",
+      "packageName": "@happyvertical/smrt-ledgers",
+      "extends": "SmrtCollection",
+      "fields": [],
+      "relationships": [],
+      "methods": [],
+      "surfaces": [],
+      "relationshipFeatures": [
+        "uuidColumns"
+      ],
+      "tags": [],
+      "risks": []
+    },
     {
       "name": "Account",
       "qualifiedName": "@happyvertical/smrt-ledgers:Account",
@@ -963,6 +1025,14 @@
           "default": "asset",
           "description": "asset, liability, equity, revenue or expense."
         },
+        {
+          "name": "ledgerId",
+          "type": "foreignKey",
+          "required": false,
+          "related": "Ledger",
+          "columnType": "UUID",
+          "description": "The ledger policy this account belongs to."
+        },
         {
           "name": "active",
           "type": "boolean",
@@ -986,10 +1056,18 @@
           "required": false,
           "related": "Account",
           "columnType": "UUID"
+        },
+        {
+          "name": "ledgerId",
+          "type": "foreignKey",
+          "required": false,
+          "related": "Ledger",
+          "columnType": "UUID"
         }
       ],
       "methods": [
         "createChild",
+        "delete",
         "getAncestors",
         "getBalance",
         "getChildren",
@@ -1012,6 +1090,14 @@
           ],
           "returns": "Promise<Account>"
         },
+        {
+          "name": "delete",
+          "async": true,
+          "params": [
+            "options?: any"
+          ],
+          "returns": "Promise<void>"
+        },
         {
           "name": "getAncestors",
           "async": true,
@@ -1405,6 +1491,26 @@
           "required": false,
           "columnType": "TEXT"
         },
+        {
+          "name": "ledgerId",
+          "type": "foreignKey",
+          "required": false,
+          "related": "Ledger",
+          "columnType": "UUID",
+          "description": "The ledger policy that governs this journal."
+        },
+        {
+          "name": "idempotencyKey",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT"
+        },
+        {
+          "name": "requestDigest",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT"
+        },
         {
           "name": "status",
           "type": "text",
@@ -1440,10 +1546,20 @@
           "default": {}
         }
       ],
-      "relationships": [],
+      "relationships": [
+        {
+          "name": "ledgerId",
+          "type": "foreignKey",
+          "required": false,
+          "related": "Ledger",
+          "columnType": "UUID"
+        }
+      ],
       "methods": [
         "addEntry",
+        "delete",
         "getEntries",
+        "getLedger",
         "getTotalCredits",
         "getTotalDebits",
         "isBalanced",
@@ -1452,6 +1568,7 @@
         "isPosted",
         "isVoided",
         "post",
+        "save",
         "summarize",
         "void"
       ],
@@ -1464,11 +1581,24 @@
           ],
           "returns": "Promise<void>"
         },
+        {
+          "name": "delete",
+          "async": true,
+          "params": [
+            "options?: any"
+          ],
+          "returns": "Promise<void>"
+        },
         {
           "name": "getEntries",
           "async": true,
           "returns": "any"
         },
+        {
+          "name": "getLedger",
+          "async": true,
+          "returns": "any"
+        },
         {
           "name": "getTotalCredits",
           "async": true,
@@ -1505,6 +1635,14 @@
           "async": true,
           "returns": "Promise<void>"
         },
+        {
+          "name": "save",
+          "async": true,
+          "params": [
+            "options?: any"
+          ],
+          "returns": "Promise<this>"
+        },
         {
           "name": "summarize",
           "async": true,
@@ -1632,6 +1770,12 @@
           "operation": "isBalanced",
           "objectName": "@happyvertical/smrt-ledgers:Journal"
         },
+        {
+          "kind": "cli",
+          "name": "journal_getLedger",
+          "operation": "getLedger",
+          "objectName": "@happyvertical/smrt-ledgers:Journal"
+        },
         {
           "kind": "cli",
           "name": "journal_addEntry",
@@ -1690,6 +1834,13 @@
           "reason": "not listed in api.include",
           "objectName": "@happyvertical/smrt-ledgers:Journal"
         },
+        {
+          "kind": "api",
+          "operation": "getLedger",
+          "code": "not-included",
+          "reason": "not listed in api.include",
+          "objectName": "@happyvertical/smrt-ledgers:Journal"
+        },
         {
           "kind": "api",
           "operation": "getTotalCredits",
@@ -1746,6 +1897,13 @@
           "reason": "not listed in api.include",
           "objectName": "@happyvertical/smrt-ledgers:Journal"
         },
+        {
+          "kind": "api",
+          "operation": "save",
+          "code": "lifecycle-method",
+          "reason": "`save` is a framework lifecycle method, not a distinct operation",
+          "objectName": "@happyvertical/smrt-ledgers:Journal"
+        },
         {
           "kind": "api",
           "operation": "summarize",
@@ -1762,6 +1920,7 @@
         }
       ],
       "relationshipFeatures": [
+        "foreignKey",
         "uuidColumns"
       ],
       "tags": [],
@@ -1797,6 +1956,33 @@
           "columnType": "UUID",
           "description": "The account this entry changes."
         },
+        {
+          "name": "counterpartyKind",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT",
+          "description": "Generic counterparty type."
+        },
+        {
+          "name": "counterpartyId",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT",
+          "description": "Generic counterparty identifier."
+        },
+        {
+          "name": "dueDate",
+          "type": "datetime",
+          "required": false,
+          "columnType": "TIMESTAMP",
+          "description": "When this open receivable or payable is due."
+        },
+        {
+          "name": "settlesSourceRef",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT"
+        },
         {
           "name": "debit",
           "type": "decimal",
@@ -1861,15 +2047,25 @@
         }
       ],
       "methods": [
+        "delete",
         "getAccount",
         "getAmount",
         "getBaseAmount",
         "getDescription",
         "getJournal",
         "isCredit",
-        "isDebit"
+        "isDebit",
+        "save"
       ],
       "methodSignatures": [
+        {
+          "name": "delete",
+          "async": true,
+          "params": [
+            "options?: any"
+          ],
+          "returns": "Promise<void>"
+        },
         {
           "name": "getAccount",
           "async": true,
@@ -1900,6 +2096,14 @@
         {
           "name": "isDebit",
           "returns": "boolean"
+        },
+        {
+          "name": "save",
+          "async": true,
+          "params": [
+            "options?: any"
+          ],
+          "returns": "Promise<this>"
         }
       ],
       "tenant": {
@@ -2063,6 +2267,13 @@
           "code": "not-included",
           "reason": "not listed in api.include",
           "objectName": "@happyvertical/smrt-ledgers:JournalEntry"
+        },
+        {
+          "kind": "api",
+          "operation": "save",
+          "code": "lifecycle-method",
+          "reason": "`save` is a framework lifecycle method, not a distinct operation",
+          "objectName": "@happyvertical/smrt-ledgers:JournalEntry"
         }
       ],
       "relationshipFeatures": [
@@ -2071,6 +2282,154 @@
       ],
       "tags": [],
       "risks": []
+    },
+    {
+      "name": "Ledger",
+      "qualifiedName": "@happyvertical/smrt-ledgers:Ledger",
+      "displayLabelField": "name",
+      "collection": "ledgers",
+      "description": "A named accounting scope. Exact ledgers store one currency's minor units and reject fractional entries; legacy journals without a ledger retain the tolerant balance rule for backwards compatibility.",
+      "tableName": "ledgers",
+      "packageName": "@happyvertical/smrt-ledgers",
+      "extends": "SmrtObject",
+      "fields": [
+        {
+          "name": "tenantId",
+          "type": "text",
+          "required": false,
+          "columnType": "UUID"
+        },
+        {
+          "name": "name",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT",
+          "description": "The accounting scope name."
+        },
+        {
+          "name": "currency",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT",
+          "description": "ISO 4217 currency used by this ledger."
+        },
+        {
+          "name": "balanceMode",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT",
+          "default": "tolerant",
+          "description": "tolerant accepts decimal units; exact requires integer minor units."
+        }
+      ],
+      "relationships": [],
+      "methods": [
+        "delete"
+      ],
+      "methodSignatures": [
+        {
+          "name": "delete",
+          "async": true,
+          "returns": "Promise<void>"
+        }
+      ],
+      "tenant": {
+        "scoped": true,
+        "mode": "optional",
+        "field": "tenantId"
+      },
+      "conflictColumns": [
+        "tenant_id",
+        "slug",
+        "context"
+      ],
+      "surfaces": [
+        {
+          "kind": "api",
+          "name": "ledgers.list",
+          "operation": "list",
+          "objectName": "@happyvertical/smrt-ledgers:Ledger",
+          "path": "/ledgers",
+          "method": "GET"
+        },
+        {
+          "kind": "api",
+          "name": "ledgers.get",
+          "operation": "get",
+          "objectName": "@happyvertical/smrt-ledgers:Ledger",
+          "path": "/ledgers/[id]",
+          "method": "GET"
+        },
+        {
+          "kind": "api",
+          "name": "ledgers.create",
+          "operation": "create",
+          "objectName": "@happyvertical/smrt-ledgers:Ledger",
+          "path": "/ledgers",
+          "method": "POST"
+        },
+        {
+          "kind": "api",
+          "name": "ledgers.update",
+          "operation": "update",
+          "objectName": "@happyvertical/smrt-ledgers:Ledger",
+          "path": "/ledgers/[id]",
+          "method": "PATCH"
+        },
+        {
+          "kind": "cli",
+          "name": "ledger_list",
+          "operation": "list",
+          "objectName": "@happyvertical/smrt-ledgers:Ledger"
+        },
+        {
+          "kind": "cli",
+          "name": "ledger_get",
+          "operation": "get",
+          "objectName": "@happyvertical/smrt-ledgers:Ledger"
+        },
+        {
+          "kind": "cli",
+          "name": "ledger_create",
+          "operation": "create",
+          "objectName": "@happyvertical/smrt-ledgers:Ledger"
+        },
+        {
+          "kind": "cli",
+          "name": "ledger_update",
+          "operation": "update",
+          "objectName": "@happyvertical/smrt-ledgers:Ledger"
+        },
+        {
+          "kind": "cli",
+          "name": "ledger_delete",
+          "operation": "delete",
+          "objectName": "@happyvertical/smrt-ledgers:Ledger"
+        },
+        {
+          "kind": "mcp",
+          "name": "ledger_list",
+          "operation": "list",
+          "objectName": "@happyvertical/smrt-ledgers:Ledger"
+        },
+        {
+          "kind": "mcp",
+          "name": "ledger_get",
+          "operation": "get",
+          "objectName": "@happyvertical/smrt-ledgers:Ledger"
+        },
+        {
+          "kind": "mcp",
+          "name": "ledger_create",
+          "operation": "create",
+          "objectName": "@happyvertical/smrt-ledgers:Ledger"
+        }
+      ],
+      "relationshipFeatures": [
+        "uuidColumns"
+      ],
+      "tags": [],
+      "risks": []
     }
   ],
   "surfaces": [
@@ -2158,6 +2517,18 @@
       "operation": "findByAccount",
       "objectName": "@happyvertical/smrt-ledgers:JournalEntryCollection"
     },
+    {
+      "kind": "cli",
+      "name": "journalentrycollection_getCounterpartyBalances",
+      "operation": "getCounterpartyBalances",
+      "objectName": "@happyvertical/smrt-ledgers:JournalEntryCollection"
+    },
+    {
+      "kind": "cli",
+      "name": "journalentrycollection_getCounterpartyAging",
+      "operation": "getCounterpartyAging",
+      "objectName": "@happyvertical/smrt-ledgers:JournalEntryCollection"
+    },
     {
       "kind": "cli",
       "name": "journalentrycollection_getAccountBalance",
@@ -2564,6 +2935,12 @@
       "operation": "isBalanced",
       "objectName": "@happyvertical/smrt-ledgers:Journal"
     },
+    {
+      "kind": "cli",
+      "name": "journal_getLedger",
+      "operation": "getLedger",
+      "objectName": "@happyvertical/smrt-ledgers:Journal"
+    },
     {
       "kind": "cli",
       "name": "journal_addEntry",
@@ -2705,6 +3082,86 @@
       "name": "journalentry_get",
       "operation": "get",
       "objectName": "@happyvertical/smrt-ledgers:JournalEntry"
+    },
+    {
+      "kind": "api",
+      "name": "ledgers.list",
+      "operation": "list",
+      "objectName": "@happyvertical/smrt-ledgers:Ledger",
+      "path": "/ledgers",
+      "method": "GET"
+    },
+    {
+      "kind": "api",
+      "name": "ledgers.get",
+      "operation": "get",
+      "objectName": "@happyvertical/smrt-ledgers:Ledger",
+      "path": "/ledgers/[id]",
+      "method": "GET"
+    },
+    {
+      "kind": "api",
+      "name": "ledgers.create",
+      "operation": "create",
+      "objectName": "@happyvertical/smrt-ledgers:Ledger",
+      "path": "/ledgers",
+      "method": "POST"
+    },
+    {
+      "kind": "api",
+      "name": "ledgers.update",
+      "operation": "update",
+      "objectName": "@happyvertical/smrt-ledgers:Ledger",
+      "path": "/ledgers/[id]",
+      "method": "PATCH"
+    },
+    {
+      "kind": "cli",
+      "name": "ledger_list",
+      "operation": "list",
+      "objectName": "@happyvertical/smrt-ledgers:Ledger"
+    },
+    {
+      "kind": "cli",
+      "name": "ledger_get",
+      "operation": "get",
+      "objectName": "@happyvertical/smrt-ledgers:Ledger"
+    },
+    {
+      "kind": "cli",
+      "name": "ledger_create",
+      "operation": "create",
+      "objectName": "@happyvertical/smrt-ledgers:Ledger"
+    },
+    {
+      "kind": "cli",
+      "name": "ledger_update",
+      "operation": "update",
+      "objectName": "@happyvertical/smrt-ledgers:Ledger"
+    },
+    {
+      "kind": "cli",
+      "name": "ledger_delete",
+      "operation": "delete",
+      "objectName": "@happyvertical/smrt-ledgers:Ledger"
+    },
+    {
+      "kind": "mcp",
+      "name": "ledger_list",
+      "operation": "list",
+      "objectName": "@happyvertical/smrt-ledgers:Ledger"
+    },
+    {
+      "kind": "mcp",
+      "name": "ledger_get",
+      "operation": "get",
+      "objectName": "@happyvertical/smrt-ledgers:Ledger"
+    },
+    {
+      "kind": "mcp",
+      "name": "ledger_create",
+      "operation": "create",
+      "objectName": "@happyvertical/smrt-ledgers:Ledger"
     }
   ],
   "prompts": [
@@ -2713,14 +3170,14 @@
     }
   ],
   "relationshipsV2": {
-    "foreignKeyFields": 3,
+    "foreignKeyFields": 5,
     "crossPackageRefFields": 0,
     "junctionCollections": 0,
     "hierarchicalObjects": 1,
     "polymorphicAssociations": 0,
-    "uuidColumns": 18
+    "uuidColumns": 26
   },
-  "agentDoc": "# @happyvertical/smrt-ledgers\n\nDouble-entry accounting with chart of accounts, journal lifecycle, and balance enforcement.\n\n## Models\n\n- **Account**: 5 types (asset/liability/equity/revenue/expense). Hierarchical via `parentId`. Debit-normal (asset, expense) vs credit-normal (liability, equity, revenue). Methods: `getAncestors()`, `getFullPath()`, `toTreeNode()`, `getBalance(asOfDate?)`. Stored in `ledger_accounts` (explicit `tableName`), never the derived `accounts`: smrt-messages declares an unrelated `Account` on that table (#3098). `src/migrations/ledger-accounts-table.ts` (`smrt db:migrate-ledger-accounts`) moves pre-#3098 rows; the README has the operator sequence.\n- **Journal**: lifecycle `draft → posted → voided`. **Immutable after posting** (can only void, not edit). `sourceModule`/`sourceRef` for cross-package attribution. Auto-numbered (e.g., \"JNL-0001\"). `summarize()` is AI-powered via the smrt-prompts registry (see Prompt Registry below).\n- **JournalEntry**: debit XOR credit (not both, validated on save). Multi-currency via `exchangeRate`. Non-negative amounts required.\n\n## Key Methods\n\n- **`Journal.summarize()`**: Generates a natural-language summary via the registered `smrtLedgers.journal.summarize` prompt, resolved through `@happyvertical/smrt-prompts`. Tenants can override the template, model, temperature, or other params via `_smrt_prompt_overrides` without code changes. Only non-PII fields (number, date, description, status, aggregate total, entry count, balanced flag) reach the AI provider.\n\n## Prompt Registry\n\nRegistered at module-load time via `definePrompt()` in `src/prompts.ts`. Side-effect imported from `src/index.ts` so consumers automatically see the prompts after importing any export from this package.\n\n| Key | Method | Variables |\n|-----|--------|-----------|\n| `smrtLedgers.journal.summarize` | `Journal.summarize()` | `journalNumber`, `journalDate`, `journalDescription`, `journalStatus`, `journalTotal`, `entryCount`, `journalBalanced` |\n\nPII-conscious variable selection: `tenantId`, `sourceRef` (may reference customer/vendor identifiers), per-entry `accountId`/`id`, and the extensible `metadata` blob are intentionally NOT exposed as prompt variables. Tenants who need richer context should override the template via `PromptOverride` and supply their own variables through a custom call site.\n\n## Balance Enforcement\n\n`journal.post()` validates `Math.abs(totalDebits - totalCredits) < BALANCE_EPSILON` where `BALANCE_EPSILON = 0.01` (float rounding tolerance). Unbalanced journals cannot be posted.\n\n**This package is unit-agnostic** — `debit` / `credit` are plain DECIMAL numbers and the balance check only compares the two sides, so it holds for whatever unit the posting module uses. As of #2401, journals posted from `@happyvertical/smrt-commerce` (`Payment.recordPayment()`, `Invoice.recognizeRevenue()`) carry **integer minor units**, which balance exactly rather than merely within the epsilon. A consumer mixing modules that post in different units will get arithmetically balanced but semantically meaningless journals; pick one unit per ledger.\n\n`JournalEntryCollection.listPostedMovements({ tenantId, accountIds, from, to,\ncurrency })` is the bounded reporting input. It joins only rows whose entry and\njournal share the requested tenant, includes every posted source (including\nmanual journals), and excludes drafts and voids. Its debit, credit, and\n`creditMinusDebit` values are raw ledger units; commerce must verify its\nminor-unit convention before using them in an exact tax report. Each returned\nmovement retains the requested `tenantId` so consumers can reject a fact that\ncrosses the reporting boundary.\n\n## Gotchas\n\n- **Float tolerance**: 0.01 epsilon for balance check — not exact equality\n- **Entry requires journalId**: save Journal first, then add entries\n- **Posted journals cannot be modified**: only voided (`voidReason`, `voidedAt`)\n- **Account types inherited by children**: child cannot differ from parent type\n- **getBalance() is async**: requires JournalEntryCollection query (not stored on Account)\n- **Optional tenancy** on all models\n- **Same-named `Account`**: reference the ledger model by constructor (`@foreignKey(Account)`) or qualified name (`@happyvertical/smrt-ledgers:Account`), never the bare string. The PostgreSQL lanes are `pnpm test:postgres` here (ledgers alone) and in smrt-messages (both packages loaded)\n",
+  "agentDoc": "# @happyvertical/smrt-ledgers\n\nDouble-entry accounting with chart of accounts, journal lifecycle, and balance enforcement.\n\n## Models\n\n- **Account**: 5 types (asset/liability/equity/revenue/expense). Hierarchical via `parentId`. Debit-normal (asset, expense) vs credit-normal (liability, equity, revenue). Methods: `getAncestors()`, `getFullPath()`, `toTreeNode()`, `getBalance(asOfDate?)`. Stored in `ledger_accounts` (explicit `tableName`), never the derived `accounts`: smrt-messages declares an unrelated `Account` on that table (#3098). `src/migrations/ledger-accounts-table.ts` (`smrt db:migrate-ledger-accounts`) moves pre-#3098 rows; the README has the operator sequence.\n- **Journal**: lifecycle `draft → posted → voided`. **Immutable after posting** (can only void, not edit). `sourceModule`/`sourceRef` for cross-package attribution. Auto-numbered (e.g., \"JNL-0001\"). `summarize()` is AI-powered via the smrt-prompts registry (see Prompt Registry below).\n- **JournalEntry**: debit XOR credit (not both, validated on save). Multi-currency via `exchangeRate`. Non-negative amounts required.\n\n## Key Methods\n\n- **`Journal.summarize()`**: Generates a natural-language summary via the registered `smrtLedgers.journal.summarize` prompt, resolved through `@happyvertical/smrt-prompts`. Tenants can override the template, model, temperature, or other params via `_smrt_prompt_overrides` without code changes. Only non-PII fields (number, date, description, status, aggregate total, entry count, balanced flag) reach the AI provider.\n\n## Prompt Registry\n\nRegistered at module-load time via `definePrompt()` in `src/prompts.ts`. Side-effect imported from `src/index.ts` so consumers automatically see the prompts after importing any export from this package.\n\n| Key | Method | Variables |\n|-----|--------|-----------|\n| `smrtLedgers.journal.summarize` | `Journal.summarize()` | `journalNumber`, `journalDate`, `journalDescription`, `journalStatus`, `journalTotal`, `entryCount`, `journalBalanced` |\n\nPII-conscious variable selection: `tenantId`, `sourceRef` (may reference customer/vendor identifiers), per-entry `accountId`/`id`, and the extensible `metadata` blob are intentionally NOT exposed as prompt variables. Tenants who need richer context should override the template via `PromptOverride` and supply their own variables through a custom call site.\n\n## Balance Enforcement\n\nNamed `Ledger` scopes freeze owner, currency and balance mode at creation.\n`exact-integer` mode requires safe integer minor units and exact equality; assigned\naccounts freeze scope/owner/type and cannot be deleted. Posted scoped journals and\nlines are immutable, including void/delete; use compensating postings.\n`postReceivable`/`postPayable`/`postSettlement` require exact ledgers and use one\ntransactional claim per tenant/ledger/key with payload-digest replay validation.\nSee README for ownership, reversal, aging and dialect contracts.\n\n\n`journal.post()` validates `Math.abs(totalDebits - totalCredits) < BALANCE_EPSILON` where `BALANCE_EPSILON = 0.01` (float rounding tolerance). Unbalanced journals cannot be posted.\n\n**This package is unit-agnostic** — `debit` / `credit` are plain DECIMAL numbers and the balance check only compares the two sides, so it holds for whatever unit the posting module uses. As of #2401, journals posted from `@happyvertical/smrt-commerce` (`Payment.recordPayment()`, `Invoice.recognizeRevenue()`) carry **integer minor units**, which balance exactly rather than merely within the epsilon. A consumer mixing modules that post in different units will get arithmetically balanced but semantically meaningless journals; pick one unit per ledger.\n\n`JournalEntryCollection.listPostedMovements({ tenantId, accountIds, from, to,\ncurrency })` is the bounded reporting input. It joins only rows whose entry and\njournal share the requested tenant, includes every posted source (including\nmanual journals), and excludes drafts and voids. Its debit, credit, and\n`creditMinusDebit` values are raw ledger units; commerce must verify its\nminor-unit convention before using them in an exact tax report. Each returned\nmovement retains the requested `tenantId` so consumers can reject a fact that\ncrosses the reporting boundary.\n\n## Gotchas\n\n- **Float tolerance**: 0.01 epsilon for balance check — not exact equality\n- **Entry requires journalId**: save Journal first, then add entries\n- **Posted journals cannot be modified**: only voided (`voidReason`, `voidedAt`)\n- **Account types inherited by children**: child cannot differ from parent type\n- **getBalance() is async**: requires JournalEntryCollection query (not stored on Account)\n- **Optional tenancy** on all models\n- **Same-named `Account`**: reference the ledger model by constructor (`@foreignKey(Account)`) or qualified name (`@happyvertical/smrt-ledgers:Account`), never the bare string. The PostgreSQL lanes are `pnpm test:postgres` here (ledgers alone) and in smrt-messages (both packages loaded)\n",
   "recipes": [
     {
       "id": "ledgers.bookkeeping",
@@ -2779,6 +3236,12 @@
             "sourceRef": {
               "visibility": "hidden"
             },
+            "idempotencyKey": {
+              "visibility": "hidden"
+            },
+            "requestDigest": {
+              "visibility": "hidden"
+            },
             "voidedAt": {
               "visibility": "hidden"
             },
@@ -2795,6 +3258,9 @@
             "exchangeRate": {
               "visibility": "hidden"
             },
+            "settlesSourceRef": {
+              "visibility": "hidden"
+            },
             "metadata": {
               "visibility": "hidden"
             }