@happyvertical/smrt-ledgers 0.57.15 → 0.57.17

package/dist/manifest.json

@@ -2,7 +2,7 @@
   "version": "1.0.0",
   "timestamp": 0,
   "packageName": "@happyvertical/smrt-ledgers",
-  "packageVersion": "0.57.15",
+  "packageVersion": "0.57.17",
   "objects": {
     "@happyvertical/smrt-ledgers:AccountCollection": {
       "name": "accountcollection",

package/dist/postings.d.ts

@@ -25,6 +25,9 @@ export interface LedgerPostingInput {
  * Atomically records an exact-minor-unit double entry. `runOnce` scopes the
  * key by tenant and ledger; its receipt binds the request digest so retries recover the
  * original journal and a changed replay refuses instead of double-posting.
+ * Idempotency is permanent: once the receipt is pruned, the journal's unique
+ * `(tenantId, ledgerId, idempotencyKey)` row and its `requestDigest` answer the
+ * same replay.
  */
 export declare function postLedgerEntry(input: LedgerPostingInput): Promise<Journal>;
 export declare const postReceivable: typeof postLedgerEntry;

package/dist/postings.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"postings.d.ts","sourceRoot":"","sources":["../src/postings.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,qCAAqC,CAAC;AAI7E,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,qBAAkB,CAAC;AAEhD,MAAM,MAAM,YAAY,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,EAAE,EAAE,MAAM,CAAA;CAAE,CAAC;AAExD,MAAM,WAAW,kBAAkB;IACjC,EAAE,EAAE,iBAAiB,CAAC;IACtB,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,cAAc,EAAE,MAAM,CAAC;IACvB,YAAY,EAAE,MAAM,CAAC;IACrB,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;IACpB,IAAI,CAAC,EAAE,IAAI,CAAC;IACZ,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,YAAY,CAAC;IAC3B,cAAc,EAAE,MAAM,CAAC;IACvB,eAAe,EAAE,MAAM,CAAC;IACxB,OAAO,CAAC,EAAE,IAAI,CAAC;IACf,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B;AA2BD;;;;GAIG;AACH,wBAAsB,eAAe,CACnC,KAAK,EAAE,kBAAkB,GACxB,OAAO,CAAC,OAAO,CAAC,CAyGlB;AAED,eAAO,MAAM,cAAc,wBAAkB,CAAC;AAC9C,eAAO,MAAM,WAAW,wBAAkB,CAAC;AAC3C,eAAO,MAAM,cAAc,wBAAkB,CAAC"}
+{"version":3,"file":"postings.d.ts","sourceRoot":"","sources":["../src/postings.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,qCAAqC,CAAC;AAI7E,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,qBAAkB,CAAC;AAEhD,MAAM,MAAM,YAAY,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,EAAE,EAAE,MAAM,CAAA;CAAE,CAAC;AAExD,MAAM,WAAW,kBAAkB;IACjC,EAAE,EAAE,iBAAiB,CAAC;IACtB,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,cAAc,EAAE,MAAM,CAAC;IACvB,YAAY,EAAE,MAAM,CAAC;IACrB,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;IACpB,IAAI,CAAC,EAAE,IAAI,CAAC;IACZ,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,YAAY,CAAC;IAC3B,cAAc,EAAE,MAAM,CAAC;IACvB,eAAe,EAAE,MAAM,CAAC;IACxB,OAAO,CAAC,EAAE,IAAI,CAAC;IACf,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B;AAiCD;;;;;;;GAOG;AACH,wBAAsB,eAAe,CACnC,KAAK,EAAE,kBAAkB,GACxB,OAAO,CAAC,OAAO,CAAC,CAuHlB;AAED,eAAO,MAAM,cAAc,wBAAkB,CAAC;AAC9C,eAAO,MAAM,WAAW,wBAAkB,CAAC;AAC3C,eAAO,MAAM,cAAc,wBAAkB,CAAC"}

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.15",
+  "packageVersion": "0.57.17",
   "sourceManifestPath": "dist/manifest.json",
   "agentDocPath": "AGENTS.md",
   "sourceHashes": {
-    "manifest": "2b83987470dd593a4c2e58d16af9ed4b185ce907347814a0934445cf4c262d93",
-    "packageJson": "a647697af8ff71497b216fd91e15473ac4b059456f5c34f2d015b7d309c5c2f4",
-    "agents": "d6890f0ff56feedb3cb850c32492d202b151e612e87873347fc99f0535ca1d44"
+    "manifest": "879800f99882f3d529b110511f9b9c09b63c70ee513474df27dcce2c10ee1879",
+    "packageJson": "c02424049d450192ea560d6c231243a92ad1512753f6545bfc987d15d706f41f",
+    "agents": "f981081420e5141313cd5d31b9ac9258b121484cfef783cf03e29b0f229e44eb"
   },
   "exports": [
     ".",
@@ -24,7 +24,7 @@
     "@types/node": "24.13.6",
     "fast-glob": "^3.3.3",
     "typescript": "6.0.3",
-    "vite": "8.1.4",
+    "vite": "8.1.6",
     "vitest": "4.1.10"
   },
   "smrtDependencies": [
@@ -3177,7 +3177,7 @@
     "polymorphicAssociations": 0,
     "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\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",
+  "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.\nThe journal's unique `(tenantId, ledgerId, idempotencyKey)` row is the permanent\nrecord: a retry after the `runOnce` claim is pruned (#4067) returns the original\nposted journal on a digest match, and refuses a mismatch or a non-posted row.\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",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@happyvertical/smrt-ledgers",
-  "version": "0.57.15",
+  "version": "0.57.17",
   "description": "Double-entry accounting ledger for the SMRT framework",
   "type": "module",
   "main": "./dist/index.js",
@@ -38,16 +38,16 @@
     "access": "public"
   },
   "dependencies": {
-    "@happyvertical/smrt-core": "0.57.15",
-    "@happyvertical/smrt-prompts": "0.57.15",
-    "@happyvertical/smrt-tenancy": "0.57.15"
+    "@happyvertical/smrt-core": "0.57.17",
+    "@happyvertical/smrt-prompts": "0.57.17",
+    "@happyvertical/smrt-tenancy": "0.57.17"
   },
   "devDependencies": {
-    "@happyvertical/smrt-vitest": "0.57.15",
+    "@happyvertical/smrt-vitest": "0.57.17",
     "@types/node": "24.13.6",
     "fast-glob": "^3.3.3",
     "typescript": "6.0.3",
-    "vite": "8.1.4",
+    "vite": "8.1.6",
     "vitest": "4.1.10"
   },
   "scripts": {