@classytic/ledger 0.7.0 → 0.9.0

package/README.md

@@ -2,14 +2,14 @@
 
 Embeddable double-entry accounting engine for MongoDB. Integer-cents arithmetic, plugin-based, country-agnostic, multi-tenant at every layer. Framework-agnostic — works with Express, Fastify, Nest, Arc, or any plain Mongoose app.
 
-> **0.5.1** — Critical plugin-pipeline fixes. `post()`, `unpost()`, `archive()`, and the `reverse()` mark-as-reversed step now route through `repository.update()` so `before:update` / `after:update` hooks fire on every state transition (period locks, audit, observability are no longer silently bypassed). `reverse()` and `duplicate()` propagate every consumer-defined top-level field (`departmentId`, `projectId`, `sourceRef`, `branchTag`, `organizationId`, …). New typed `_ledgerInternal` flag on `RepositoryContext` lets plugin authors observe internal transitions without casts. See [CHANGELOG.md](CHANGELOG.md).
+> **0.7.0 (BREAKING)** — `@classytic/ledger` is now a **pure double-entry accounting engine**. Tax computation, return templates, repartition, and exigibility have been removed from the core and country-pack contracts and now live in dedicated tax packages (`@classytic/bd-tax` is the existing reference; `@classytic/ca-tax` will follow). Country packs `@classytic/ledger-bd@0.2.0` and `@classytic/ledger-ca@0.2.0` ship the chart of accounts + journal templates only — they re-export the raw tax data tables as named constants for tax engines to lift. The 0.6.x A/P + A/R primitives (item-level matching, partner ledger, credit limit, FX realization, journal resource, open-item queries) are unchanged. See [CHANGELOG.md](CHANGELOG.md).
 
 ## Install
 
 ```bash
 npm install @classytic/ledger @classytic/mongokit mongoose
-npm install @classytic/ledger-ca   # Canada (GIFI, GST/HST, CRA)
-npm install @classytic/ledger-bd   # Bangladesh (BFRS, VAT/TDS, Mushak)
+npm install @classytic/ledger-ca   # Canada (GIFI chart of accounts)
+npm install @classytic/ledger-bd   # Bangladesh (BFRS chart of accounts)
 ```
 
 ## Quick Start
@@ -30,10 +30,9 @@ await engine.repositories.accounts.seedAccounts(orgId);
 
 await engine.record.sale(orgId, {
   date: new Date("2025-04-01"),
-  amount: 10000,                 // $100.00 in cents (tax-exclusive)
+  amount: 11300,                 // $113.00 in cents (caller pre-computes any tax)
   receivableAccount: "1200",     // AR
   revenueAccount:    "4010",     // Service Revenue
-  tax: { code: "HST", account: "2300" },
   label: "INV-001",
 });
 
@@ -48,32 +47,29 @@ The engine owns the models. After `createAccountingEngine` you have:
 
 | Property | What it gives you |
 | --- | --- |
-| `engine.models.{Account,JournalEntry,FiscalPeriod,Budget,Reconciliation}` | Mongoose models |
+| `engine.models.{Account,JournalEntry,FiscalPeriod,Budget,Reconciliation,Journal}` | Mongoose models |
 | `engine.repositories.accounts` | `seedAccounts()`, `bulkCreate()` + plugins |
 | `engine.repositories.journalEntries` | `post()`, `unpost()`, `reverse()`, `duplicate()` + double-entry, fiscal-lock, idempotency |
+| `engine.repositories.journals` | First-class posting channels — `seedDefaults()`, `nextSequenceNumber()` |
+| `engine.repositories.reconciliations` | Item-level matching — `match()`, `unmatch()`, `getOpenItems()` |
 | `engine.repositories.{fiscalPeriods,budgets}` | Plain CRUD |
-| `engine.repositories.reconciliations` | `reconcile()`, `unreconcile()`, `getUnreconciled()` |
 | `engine.record.*` | Domain verbs (`sale`, `expense`, `transfer`, `payment`, `adjustment`) |
-| `engine.introspect.*` | Runtime catalog of accounts, tax codes, reports |
-| `engine.reports.*` | All 10 reports, bound to owned models |
+| `engine.introspect.*` | Runtime catalog of accounts, journal types, reports, fiscal periods |
+| `engine.reports.*` | All 12 reports, bound to owned models |
 
 ## Semantic Record API
 
-Record business operations as domain verbs. The engine resolves account codes, splits tax, and produces a balanced journal entry — you never touch debits/credits.
+Record business operations as domain verbs. The engine resolves account codes and produces a balanced journal entry — you never touch debits/credits.
 
 ```ts
-// Cash sale with 13% HST
 await engine.record.sale(orgId, {
   date, amount: 10000,
   receivableAccount: "1001", revenueAccount: "4010",
-  tax: { code: "HST", account: "2300" },
 });
 
-// Expense with recoverable input tax credit
 await engine.record.expense(orgId, {
   date, amount: 3000,
   expenseAccount: "6010", paidFromAccount: "2001",
-  tax: { code: "HST_ITC", account: "2400" },
 });
 
 await engine.record.transfer(orgId, { date, amount: 5000, fromAccount: "1001", toAccount: "1002" });
@@ -93,16 +89,97 @@ await engine.record.adjustment(orgId, {
 });
 ```
 
+> **Tax lines:** the semantic verbs are tax-agnostic in 0.7+. Compute VAT/GST/HST via your tax engine of choice (`@classytic/bd-tax`, the forthcoming `@classytic/ca-tax`, or your own) and either pre-add the tax to `amount` and post the tax line via `record.adjustment`, or post the full entry directly via `engine.repositories.journalEntries.create()`.
+
 All verbs accept `options.user`, `options.session`, `options.idempotencyKey`, plus any custom field — they all flow into mongokit's `RepositoryContext` so audit/observability plugins (and your hooks) pick them up automatically.
 
+## Accounts Payable & Receivable
+
+The 0.6.x A/P + A/R primitives are the foundation for any ERP workflow on top of the ledger.
+
+```ts
+// Tag every journal item with a partnerId via extraItemFields (one-time setup)
+const engine = createAccountingEngine({
+  // ...
+  schemaOptions: {
+    journalEntry: {
+      extraItemFields: {
+        partnerId: { type: String, index: true },
+      },
+    },
+  },
+});
+
+// Post a credit sale on 30-day terms
+const invoice = await engine.repositories.journalEntries.create({
+  state: "posted",
+  date: new Date("2026-01-15"),
+  journalItems: [
+    { account: arId, debit: 100_000, partnerId: "wholesale-1", maturityDate: new Date("2026-02-14") },
+    { account: revenueId, credit: 100_000 },
+  ],
+});
+
+// Customer pays $400 of the $1000 invoice
+const payment = await engine.repositories.journalEntries.create({
+  state: "posted",
+  date: new Date("2026-01-25"),
+  journalItems: [
+    { account: cashId, debit: 40_000 },
+    { account: arId, credit: 40_000, partnerId: "wholesale-1" },
+  ],
+});
+
+// Match the AR sides — partial settlement
+await engine.repositories.reconciliations.match({
+  account: arId,
+  items: [
+    { entry: invoice._id, itemIndex: 0 },
+    { entry: payment._id, itemIndex: 1 },
+  ],
+});
+
+// Open items for this partner (subsidiary ledger)
+await engine.repositories.reconciliations.getOpenItems({
+  accountId: arId,
+  filter: { partnerId: "wholesale-1" },
+});
+
+// Customer statement with running balance + aged buckets
+import { generatePartnerLedger } from "@classytic/ledger";
+await generatePartnerLedger(
+  { AccountModel: engine.models.Account, JournalEntryModel: engine.models.JournalEntry },
+  {
+    controlAccountId: arId,
+    partnerId: "wholesale-1",
+    startDate: new Date("2026-01-01"),
+    endDate: new Date("2026-03-31"),
+  },
+);
+
+// Cross-partner aged A/R buckets
+import { generateAgedBalance } from "@classytic/ledger";
+await generateAgedBalance(
+  { AccountModel, JournalEntryModel, country: canadaPack },
+  { type: "receivable", contactField: "journalItems.partnerId" },
+);
+
+// Enforce per-customer credit limits
+import { creditLimitPlugin } from "@classytic/ledger/plugins";
+creditLimitPlugin({
+  arControlAccountId: arId,
+  JournalEntryModel: engine.models.JournalEntry,
+  getCreditLimit: async (partnerId) => Customer.findById(partnerId).then(c => c?.creditLimit ?? null),
+}).apply(engine.repositories.journalEntries);
+```
+
 ## Introspection
 
 ```ts
 const catalog = await engine.introspect.catalog(orgId);
-// { accounts, journalTypes, reports, taxCodes, fiscalPeriods }
+// { accounts, journalTypes, reports, fiscalPeriods }
 
 engine.introspect.accounts(orgId);
-engine.introspect.taxCodes("ON");
 engine.introspect.reports();   // sync — static catalog
 ```
 
@@ -113,124 +190,74 @@ try {
   await engine.record.sale(orgId, { ... });
 } catch (err) {
   if (err instanceof AccountingError) {
-    err.status   // 400 | 403 | 404 | 409
-    err.code     // 'VALIDATION_ERROR' | 'NOT_FOUND' | ...
+    err.status   // 400 | 402 | 403 | 404 | 409
+    err.code     // 'VALIDATION_ERROR' | 'NOT_FOUND' | 'CREDIT_LIMIT_EXCEEDED' | 'PERIOD_LOCKED_FISCAL' | ...
     err.fields   // [{ path, issue, value }, ...]
     err.toJSON();
   }
 }
 ```
 
-Field errors come straight from plugins (double-entry, fiscal-lock) and the semantic layer.
-
 ## Audit, Observability & Framework Integration
 
-The ledger is **framework-agnostic** and operates at the model layer — Express, Fastify, Nest, Hono, and Arc all work the same way. Three places you can hook in, composable:
-
-1. **Any mongokit plugin** via `config.plugins` — see the `@classytic/mongokit` docs for `auditTrailPlugin`, `observabilityPlugin`, and others.
-   ```ts
-   const engine = createAccountingEngine({
-     mongoose: mongoose.connection, country: canadaPack, currency: "CAD",
-     plugins: {
-       journalEntry: [/* your mongokit plugins */],
-       account:      [/* your mongokit plugins */],
-     },
-   });
-   ```
-2. **Runtime listeners** — no plugin needed:
-   ```ts
-   engine.repositories.journalEntries.on("after:create", ({ context, result }) => {
-     auditLog.write({ userId: context.user?._id, orgId: context.organizationId, entryId: result._id });
-   });
-   ```
-3. **Your framework's own audit (HTTP-level)** — e.g. `@classytic/arc`'s `auditPlugin` records resource CRUD with request context. Use it alone, or combine with a model-layer plugin.
-
-| Layer | What it sees | What it misses |
-| --- | --- | --- |
-| HTTP middleware (Arc / Express / Nest) | Request → user, IP, route, payload | Background jobs, CLI scripts, anything bypassing HTTP |
-| Model-layer mongokit plugin | Every collection write, regardless of caller | HTTP context unless the caller forwards it |
-
-For accounting compliance most teams want **both** — HTTP audit for traffic, model audit on `journalEntry` for an immutable trail. Forward request context on the call so both layers see it:
+Every operation flows through mongokit's `RepositoryContext`. Custom plugins can hook `before:create` / `after:create` / `before:update` / `after:update` / `after:match` to add audit trails, metrics, webhooks, or business rules — none of it is hardcoded into the core.
 
-```ts
-// Express
-app.post("/sales", async (req, res) => {
-  await engine.record.sale(req.body.orgId, req.body, {
-    user: req.user, ip: req.ip, userAgent: req.headers["user-agent"],
-  });
-});
-```
+The `_ledgerInternal` context flag (`'post' | 'unpost' | 'archive' | 'reverseMark' | 'fxRealize'`) tells plugins which engine operation is in flight, so guards (locks, credit limit, immutability) can exempt legitimate engine writes without affecting consumer code.
 
 ## Reports
 
-```ts
-await engine.reports.trialBalance({ organizationId, dateOption: "year",  dateValue: 2025 });
-await engine.reports.balanceSheet({ organizationId, dateOption: "year",  dateValue: 2025 });
-await engine.reports.incomeStatement({ organizationId, dateOption: "quarter", dateValue: { year: 2025, quarter: 2 } });
-await engine.reports.generalLedger({ organizationId, dateOption: "month", dateValue: { year: 2025, month: 4 } });
-await engine.reports.cashFlow({ organizationId, dateOption: "year", dateValue: 2025 });
-await engine.reports.agedBalance({ organizationId, type: "receivable", asOfDate: new Date() });
-await engine.reports.budgetVsActual({ organizationId, dateOption: "year", dateValue: 2025 });
-await engine.reports.dimensionBreakdown({ organizationId, dimension: "departmentId", dateOption: "year", dateValue: 2025 });
-await engine.reports.revaluation({ organizationId, asOfDate: new Date(), rates: [{ currency: "USD", rate: 1.40 }], unrealizedGainLossAccountId });
-```
-
-All values are integer cents. Use `Money.toDecimal()` at your API boundary.
+12 typed reports, all multi-tenant scoped, all returning structured JSON ready for any UI:
 
-The 10 reports:
-
-- **Trial Balance** (3-column: opening + period + ending)
-- **Balance Sheet** (with computed retained earnings, multi-year aware)
-- **Income Statement** (revenue, COGS, gross profit, operating expenses, net income)
-- **General Ledger** (per-account with running balances)
-- **Cash Flow** (operating / investing / financing)
-- **Aged Receivable / Payable** (configurable buckets)
-- **Budget vs Actual** (variance analysis)
-- **Dimension Breakdown** (by department, project, cost center)
-- **FX Revaluation** (unrealized gain/loss)
-- **Fiscal Year Close / Reopen** (automatic closing entries)
+| Report | Purpose |
+| --- | --- |
+| `trialBalance` | Debits/credits per account with running balances |
+| `balanceSheet` | Assets, liabilities, equity at a date with computed retained earnings |
+| `incomeStatement` | Revenue, COGS, expenses, net income for a period |
+| `generalLedger` | Per-account transaction detail with running balance |
+| `cashFlow` | Operating / investing / financing breakdown |
+| `agedBalance` | A/R or A/P bucketed by age, optionally per partner |
+| `partnerLedger` | Supplier/customer statement with opening + running balance + aged buckets |
+| `dimensionBreakdown` | Group by department/project/cost center |
+| `budgetVsActual` | Variance vs budget per account/period |
+| `revaluation` | Foreign-currency unrealized FX gain/loss at a date |
+| `closeFiscalPeriod` / `reopenFiscalPeriod` | Year-end close pipeline |
 
 ## Engine Configuration
 
 ```ts
-createAccountingEngine({
-  mongoose: mongoose.connection,             // required
-  country:  canadaPack,                      // required
-  currency: "CAD",                           // required — base/functional currency
-  multiTenant: { orgField, orgRef },         // optional
+const engine = createAccountingEngine({
+  mongoose: mongoose.connection,
+  country: canadaPack,
+  currency: "CAD",
+  multiTenant: { orgField: "organizationId", orgRef: "Organization" },
   multiCurrency: { enabled: true, currencies: ["USD", "EUR"] },
-  fiscalYearStartMonth: 1,                   // 1=Jan (default), 4=Apr, 7=Jul
-  retainedEarningsAccountCode: "3600",       // overrides country pack
-  modelNames: { account: "GLAccount", ... }, // custom collection names
-  schemaOptions: {                           // extra fields/indexes per model
+  fiscalYearStartMonth: 1,
+  idempotency: true,
+  strictness: { immutable: true, requireActor: true },
+  schemaOptions: {
     journalEntry: {
-      extraFields: { aiJob: { status: String, generatedAt: Date } },
-      extraIndexes: [{ fields: { "aiJob.status": 1 }, options: { sparse: true } }],
+      extraItemFields: {
+        partnerId: { type: String, index: true },
+        departmentId: { type: mongoose.Schema.Types.ObjectId },
+      },
     },
   },
-  strictness: {
-    immutable:        true,   // disable unpost — corrections only via reverse
-    requireActor:     true,   // actorId required on post/reverse
-    requireApproval:  true,   // entries must be approved before posting
-  },
-  plugins:    { journalEntry: [...], account: [...] },  // any mongokit plugins
-  pagination: { account: { maxLimit: 5000 } },          // optional caps; no default cap
 });
 ```
 
-`pagination` has **no default cap** — large enterprise charts of accounts can be tens of thousands of rows. Pass `{ maxLimit: N }` per repository if you want to bound list queries.
-
 ## Built-in Plugins
 
 | Plugin | Purpose |
 | --- | --- |
-| `doubleEntryPlugin` | Validates debits = credits, account existence, tenant integrity |
-| `fiscalLockPlugin` | Prevents posting to closed fiscal periods |
-| `dateLockPlugin` | Blocks entries before a configurable lock date |
-| `taxHookPlugin` | Auto-generates tax lines via a `TaxLineGenerator` |
-| `idempotencyPlugin` | Prevents duplicate entries by key |
+| `doubleEntryPlugin` | Validates debits = credits, account existence, tenant integrity, posted-entry immutability |
+| `fiscalLockPlugin` | Prevents posting into closed fiscal periods (auto-wired) |
+| `dailyLockPlugin` | Per-branch `lastClosedDate` watermark for daily POS close |
+| `createLockPlugin` | Generic lock factory — compose your own scopes (bank recon, payroll, tax filings) |
+| `idempotencyPlugin` | Prevents duplicate entries by key (auto-wired when `idempotency: true`) |
+| `creditLimitPlugin` | Per-partner A/R credit limit enforcement |
+| `fxRealizationPlugin` | Books realized FX gain/loss when matched items have different exchange rates |
 
-`doubleEntryPlugin`, `fiscalLockPlugin` and `idempotencyPlugin` are wired automatically by the engine. The others are opt-in via the second `createAccountingEngine` argument.
+`doubleEntryPlugin`, `fiscalLockPlugin`, and `idempotencyPlugin` (when enabled) are wired automatically by the engine. The others are opt-in via `.apply(engine.repositories.journalEntries)` or `.apply(engine.repositories.reconciliations)`.
 
 ## Custom Journal Types
 
@@ -247,25 +274,99 @@ Reference numbers use the type prefix (`POS_SALES/2025/03/0001`). The registry f
 
 ## Country Packs
 
+A country pack ships the **chart of accounts** + accounting conventions for a jurisdiction. Tax (VAT/GST/HST/income-tax) lives in separate tax packages — see "Tax" below.
+
 ```ts
 import { defineCountryPack } from "@classytic/ledger";
 
 export const myPack = defineCountryPack({
-  code: "US", name: "United States", defaultCurrency: "USD",
+  code: "US",
+  name: "United States",
+  defaultCurrency: "USD",
   retainedEarningsAccountCode: "3200",
   accountTypes: [/* chart of accounts */],
-  taxCodes:     {/* tax codes */},
-  taxCodesByRegion: {}, regions: [],
+  journalTemplates: [
+    { code: "SALES", name: "Sales", journalType: "SALES", kind: "sale", sequencePrefix: "INV" },
+    // ...
+  ],
+});
+```
+
+Available: `@classytic/ledger-ca` (Canada GIFI), `@classytic/ledger-bd` (Bangladesh BFRS).
+
+## Tax
+
+`@classytic/ledger@0.7+` is intentionally tax-agnostic. The same separation Odoo (`account/` vs `l10n_*`), QuickBooks (Ledger vs TaxService), and Xero (accounting vs Xero Tax) all use.
+
+For tax computation, return generation, and repartition:
+
+- **`@classytic/bd-tax`** — Bangladesh income tax + VAT compute, IT-11GA forms, Mushak 9.1 returns, deduction optimizer, depreciation
+- **`@classytic/ca-tax`** *(planned)* — Canadian GST/HST/PST/QST compute, CRA GST34 form, ITC tracking
+- **Or your own** — tax engines just call `engine.repositories.journalEntries.create()` with the tax line items they want posted
+
+The country packs (`ledger-bd`, `ledger-ca`) still re-export their raw tax data tables (`TAX_CODES`, `TAX_CODES_BY_REGION`, `mushakReturnTemplate`, `craReturnTemplate`) as named exports so tax packages can lift them — they're just no longer wired into the `CountryPack` contract.
+
+## Invoice Engine Integration
+
+Wire `@classytic/invoice` to the ledger with one call — no manual journal wiring needed:
+
+```ts
+import { createAccountingEngine } from "@classytic/ledger";
+import { createLedgerBridge } from "@classytic/ledger/sync";
+import { createInvoiceEngine } from "@classytic/invoice";
+import { canadaPack } from "@classytic/ledger-ca";
+
+const accounting = createAccountingEngine({
+  mongoose: mongoose.connection,
+  country: canadaPack,
+  currency: "CAD",
+  multiTenant: { orgField: "organizationId", orgRef: "Organization" },
+  idempotency: true,
+});
+
+const invoicing = createInvoiceEngine({
+  mongoose: mongoose.connection,
+  ledger: createLedgerBridge(accounting, {
+    accounts: {
+      receivable: "1200",     // Accounts Receivable
+      payable: "2000",        // Accounts Payable
+      revenue: "4000",        // Revenue
+      expense: "5000",        // Expenses
+      taxPayable: "2100",     // Tax Payable
+      taxReceivable: "1150",  // Tax Receivable
+      cash: "1000",           // Cash / Bank
+    },
+  }),
+});
+```
+
+The bridge handles all 5 move types (`out_invoice`, `in_invoice`, `out_refund`, `in_refund`, `receipt`), payment recording, and reversal. See [docs/sync.md](docs/sync.md) for the full mapping table and configuration options.
+
+For custom subledgers (inventory, payroll, etc.) that don't use `@classytic/invoice`, see [docs/subledger-integration.md](docs/subledger-integration.md) for the manual `PostingContract` pattern.
+
+## URL-Driven Queries
+
+Parse URL query parameters directly into paginated repository queries via mongokit's `QueryParser`:
+
+```ts
+const parser = engine.createQueryParser("journalEntry");
+const parsed = parser.parse(req.query);
+// ?state=posted&date[gte]=2025-01-01&sort=-date&limit=25
+
+const result = await engine.repositories.journalEntries.getAll({
+  ...parsed,
+  filters: { ...parsed.filters, organizationId },
 });
 ```
 
-Available: `@classytic/ledger-ca` (Canada), `@classytic/ledger-bd` (Bangladesh).
+Available for all 6 models: `account`, `journalEntry`, `fiscalPeriod`, `budget`, `reconciliation`, `journal`.
 
 ## Subpath Exports
 
 | Path | Contents |
 | --- | --- |
 | `@classytic/ledger`           | Engine, Money, plugins, reports, types |
+| `@classytic/ledger/sync`      | `createLedgerBridge`, `wireImport`, `wireExport`, bank/invoice/JE mappers |
 | `@classytic/ledger/money`     | `Money` class |
 | `@classytic/ledger/reports`   | Standalone report generators |
 | `@classytic/ledger/plugins`   | All plugins |
@@ -276,9 +377,10 @@ Available: `@classytic/ledger-ca` (Canada), `@classytic/ledger-bd` (Bangladesh).
 ## Testing
 
 ```bash
-npm test                            # 1273 tests, 67 files
-npx vitest run tests/e2e/           # full-year scenarios
-npx vitest run tests/scenarios/     # integration scenarios
+npm test                            # 1327 tests, 77 files
+npm run smoke                       # full pipeline against published dist/
+npx vitest run tests/e2e/           # end-to-end scenarios
+npx vitest run tests/scenarios/     # multi-step business scenarios
 npx vitest run tests/hardening/     # edge cases & invariants
 ```
 
@@ -286,11 +388,15 @@ Coverage includes:
 
 - Canadian small-business full-year lifecycle (open → post → close → reopen)
 - Multi-year fiscal cycles with retained-earnings rollover
-- Multi-currency trading with FX revaluation
+- Multi-currency trading with realized + unrealized FX
 - Multi-tenant report isolation (org A cannot see org B)
-- All 10 reports with month / quarter / year / custom date ranges
+- All 12 reports with month / quarter / year / custom date ranges
 - Reversal and correction workflows
 - Custom journal type registry → schema → posting pipeline
+- Item-level matching: 1-to-1, 1-to-many, partial settlement, unmatch
+- Per-partner credit limit enforcement + reversal exemption
+- FX realization plugin auto-booking gain/loss on cross-rate match
+- Full ERP A/P + A/R cycle (bill receipt → match → supplier statement → aged balance)
 - Double-entry conservation across all entries
 - Money arithmetic hardening (overflow, penny-leak, float traps)
 - O-Level / A-Level / university textbook accounting problems
@@ -300,7 +406,7 @@ Coverage includes:
 - Node.js >= 22
 - MongoDB (replica set recommended for transactions)
 - Mongoose >= 9.4.1
-- @classytic/mongokit >= 3.5.3
+- @classytic/mongokit >= 3.5.6
 
 ## License
 

package/dist/bridges/index.d.mts

@@ -0,0 +1,2 @@
+import { a as EntryReversedNotification, c as PeriodLockedNotification, i as SourceRef, l as ReconciliationMismatchNotification, n as SourceBridge, o as NotificationBridge, r as SourceBridgeContext, s as NotificationBridgeContext, t as LedgerBridges } from "../index-dqkjgpII.mjs";
+export { EntryReversedNotification, LedgerBridges, NotificationBridge, NotificationBridgeContext, PeriodLockedNotification, ReconciliationMismatchNotification, SourceBridge, SourceBridgeContext, SourceRef };

package/dist/bridges/index.mjs

@@ -0,0 +1 @@
+export {};

package/dist/constants/index.d.mts

@@ -1,2 +1,2 @@
-import { S as isValidCategory, _ as getCategoryMainType, a as getJournalTypeCodes, b as isBalanceSheet, c as CURRENCIES, d as isValidCurrency, f as CATEGORIES, g as extractStatementType, h as extractMainType, i as getJournalType, l as getCurrency, m as categoryKey, n as JOURNAL_TYPES, o as isValidJournalType, p as CATEGORY_KEYS, r as getCustomJournalTypes, s as registerJournalType, t as JOURNAL_CODES, u as getMinorUnit, v as getCategoryStatementType, x as isIncomeStatement, y as getNormalBalance } from "../journals-C50E9mpo.mjs";
+import { S as isValidCategory, _ as getCategoryMainType, a as getJournalTypeCodes, b as isBalanceSheet, c as CURRENCIES, d as isValidCurrency, f as CATEGORIES, g as extractStatementType, h as extractMainType, i as getJournalType, l as getCurrency, m as categoryKey, n as JOURNAL_TYPES, o as isValidJournalType, p as CATEGORY_KEYS, r as getCustomJournalTypes, s as registerJournalType, t as JOURNAL_CODES, u as getMinorUnit, v as getCategoryStatementType, x as isIncomeStatement, y as getNormalBalance } from "../journals-DUpWwFt1.mjs";
 export { CATEGORIES, CATEGORY_KEYS, CURRENCIES, JOURNAL_CODES, JOURNAL_TYPES, categoryKey, extractMainType, extractStatementType, getCategoryMainType, getCategoryStatementType, getCurrency, getCustomJournalTypes, getJournalType, getJournalTypeCodes, getMinorUnit, getNormalBalance, isBalanceSheet, isIncomeStatement, isValidCategory, isValidCurrency, isValidJournalType, registerJournalType };

package/dist/constants/index.mjs

@@ -1,3 +1,3 @@
-import { a as JOURNAL_CODES, c as getCustomJournalTypes, d as isValidJournalType, f as registerJournalType, i as isValidCurrency, l as getJournalType, n as getCurrency, o as JOURNAL_TYPES, r as getMinorUnit, t as CURRENCIES, u as getJournalTypeCodes } from "../currencies-CsuBGfgs.mjs";
-import { a as extractStatementType, c as getNormalBalance, d as isValidCategory, i as extractMainType, l as isBalanceSheet, n as CATEGORY_KEYS, o as getCategoryMainType, r as categoryKey, s as getCategoryStatementType, t as CATEGORIES, u as isIncomeStatement } from "../categories-BkKdv16V.mjs";
+import { a as JOURNAL_CODES, c as getCustomJournalTypes, d as isValidJournalType, f as registerJournalType, i as isValidCurrency, l as getJournalType, n as getCurrency, o as JOURNAL_TYPES, r as getMinorUnit, t as CURRENCIES, u as getJournalTypeCodes } from "../currencies-Jo5oaM_4.mjs";
+import { a as extractStatementType, c as getNormalBalance, d as isValidCategory, i as extractMainType, l as isBalanceSheet, n as CATEGORY_KEYS, o as getCategoryMainType, r as categoryKey, s as getCategoryStatementType, t as CATEGORIES, u as isIncomeStatement } from "../categories-FJlrvzcl.mjs";
 export { CATEGORIES, CATEGORY_KEYS, CURRENCIES, JOURNAL_CODES, JOURNAL_TYPES, categoryKey, extractMainType, extractStatementType, getCategoryMainType, getCategoryStatementType, getCurrency, getCustomJournalTypes, getJournalType, getJournalTypeCodes, getMinorUnit, getNormalBalance, isBalanceSheet, isIncomeStatement, isValidCategory, isValidCurrency, isValidJournalType, registerJournalType };

package/dist/country/index.d.mts

@@ -1,2 +1,2 @@
-import { i as defineCountryPack, n as CountryPackInput, r as JournalTemplate, t as CountryPack } from "../index-BX8miYdu.mjs";
+import { i as defineCountryPack, n as CountryPackInput, r as JournalTemplate, t as CountryPack } from "../index-08IpHhrU.mjs";
 export { CountryPack, CountryPackInput, JournalTemplate, defineCountryPack };

package/dist/errors-BI5k4iak.mjs

@@ -0,0 +1,121 @@
+//#region src/utils/errors.ts
+var AccountingError = class extends Error {
+	status;
+	code;
+	fields;
+	constructor(message, status = 400, code = "ACCOUNTING_ERROR", fields) {
+		super(message);
+		this.name = "AccountingError";
+		this.status = status;
+		this.code = code;
+		if (fields && fields.length > 0) this.fields = Object.freeze([...fields]);
+	}
+	/** Serialize to a plain object for API responses and logs. */
+	toJSON() {
+		return {
+			name: this.name,
+			message: this.message,
+			status: this.status,
+			code: this.code,
+			...this.fields ? { fields: this.fields } : {}
+		};
+	}
+};
+const Errors = {
+	validation: (msg, fields) => new AccountingError(msg, 400, "VALIDATION_ERROR", fields),
+	notFound: (msg, fields) => new AccountingError(msg, 404, "NOT_FOUND", fields),
+	conflict: (msg, fields) => new AccountingError(msg, 409, "CONFLICT", fields),
+	immutable: (msg, _fields) => new AccountingError(msg, 403, "IMMUTABLE_ENTRY"),
+	locked: (scope, msg, fields) => new AccountingError(msg, 409, `PERIOD_LOCKED_${scope.toUpperCase()}`, fields)
+};
+/**
+* Thrown when an idempotent create was attempted with a key that already
+* resolved to a different winner (not the common "same winner, same payload"
+* replay — that returns the existing doc without throwing).
+*
+* Typically surfaces when the host supplies an `idempotencyKey` that collides
+* with a logically-different prior write.
+*/
+var IdempotencyConflictError = class extends AccountingError {
+	idempotencyKey;
+	existingId;
+	constructor(idempotencyKey, existingId, message) {
+		super(message ?? `Idempotency key "${idempotencyKey}" already resolved to entry ${String(existingId)}.`, 409, "IDEMPOTENCY_CONFLICT");
+		this.name = "IdempotencyConflictError";
+		this.idempotencyKey = idempotencyKey;
+		this.existingId = existingId;
+	}
+};
+/**
+* Thrown when the unique `referenceNumber` index fires. With the new atomic
+* counter this should be effectively impossible — if it ever throws, it
+* indicates either a pre-atomic-counter doc that was hand-inserted OR a bug
+* in the counter partitioning.
+*/
+var DuplicateReferenceError = class extends AccountingError {
+	referenceNumber;
+	constructor(referenceNumber, message) {
+		super(message ?? `Duplicate reference number "${referenceNumber}".`, 409, "DUPLICATE_REFERENCE_NUMBER");
+		this.name = "DuplicateReferenceError";
+		this.referenceNumber = referenceNumber;
+	}
+};
+/**
+* Thrown when an optimistic-concurrency FSM transition fails because another
+* writer advanced the state or version between our read and our write.
+*
+* Callers should re-fetch the doc and decide whether to retry or surface.
+*/
+var ConcurrencyError = class extends AccountingError {
+	resource;
+	resourceId;
+	constructor(resource, resourceId, message) {
+		super(message ?? `${resource} ${String(resourceId)} was modified by another writer — retry after re-fetch.`, 409, "CONCURRENCY_CONFLICT");
+		this.name = "ConcurrencyError";
+		this.resource = resource;
+		this.resourceId = resourceId;
+	}
+};
+/**
+* Thrown when a mutation targets an entry that is protected by immutability —
+* either `strictness.immutable` or the double-entry plugin's posted-entry
+* guard. Factory `Errors.immutable(msg)` returns this subclass so callers
+* can `instanceof`-match without sniffing the `code` field.
+*/
+var ImmutableViolationError = class extends AccountingError {
+	entryId;
+	constructor(entryId, message, fields) {
+		super(message ?? `Entry ${String(entryId)} is posted and immutable. Use reverse() to correct it.`, 403, "IMMUTABLE_ENTRY", fields);
+		this.name = "ImmutableViolationError";
+		this.entryId = entryId;
+	}
+};
+Errors.immutable = (msg, fields) => new ImmutableViolationError(null, msg, fields);
+/**
+* Detect a Mongo duplicate-key error (11000) and return the index name the
+* conflict hit on, so callers can switch on which unique key fired.
+*
+* Handles both driver-style and mongoose-style error shapes. Safe to call
+* with any `unknown` — returns `null` when the error is not a dup-key.
+*/
+function classifyDuplicateKey(err) {
+	if (!err || typeof err !== "object") return null;
+	const e = err;
+	const code = typeof e.code === "number" ? e.code : typeof e.code === "string" ? Number(e.code) : void 0;
+	const isDriverDup = code === 11e3 || e.name === "MongoServerError" && code === 11e3 || Array.isArray(e.writeErrors) && e.writeErrors.some((w) => w?.code === 11e3);
+	const wrappedMsgMatch = typeof e.message === "string" ? e.message.match(/^Duplicate value for ([a-zA-Z_.0-9,\s]+?)(?:\s*\(|$)/) : null;
+	const isMongokitDup = e.status === 409 && !!wrappedMsgMatch;
+	if (!isDriverDup && !isMongokitDup) return null;
+	let keyPattern = e.keyPattern;
+	if (!keyPattern && Array.isArray(e.writeErrors)) keyPattern = e.writeErrors.find((w) => w?.code === 11e3)?.keyPattern;
+	if (!keyPattern && wrappedMsgMatch) {
+		const fields = wrappedMsgMatch[1].split(",").map((f) => f.trim()).filter(Boolean);
+		keyPattern = Object.fromEntries(fields.map((f) => [f, 1]));
+	}
+	return {
+		indexName: keyPattern ? Object.keys(keyPattern).join("_") : typeof e.message === "string" && e.message.match(/index: ([^\s]+)/)?.[1] ? e.message.match(/index: ([^\s]+)/)[1] : "unknown",
+		keyPattern
+	};
+}
+//#endregion
+export { IdempotencyConflictError as a, Errors as i, ConcurrencyError as n, ImmutableViolationError as o, DuplicateReferenceError as r, classifyDuplicateKey as s, AccountingError as t };

package/dist/events/index.d.mts

@@ -0,0 +1,2 @@
+import { C as EntryReversedPayload, D as ReconciliationUnmatchedPayload, E as ReconciliationMatchedPayload, O as LEDGER_EVENTS, S as EntryPostedPayload, T as JournalSeededPayload, _ as AccountBulkCreatedPayload, a as OutboxOwnershipError, b as EntryCreatedPayload, c as InProcessLedgerBus, d as createEvent, f as DomainEvent, g as PublishManyResult, h as EventTransport, i as OutboxFailOptions, k as LedgerEventName, l as InProcessLedgerBusOptions, m as EventLogger, n as OutboxClaimOptions, o as OutboxStore, p as EventHandler, r as OutboxErrorInfo, s as OutboxWriteOptions, t as OutboxAcknowledgeOptions, u as EventContext, v as AccountSeededPayload, w as EntryUnpostedPayload, x as EntryDuplicatedPayload, y as EntryArchivedPayload } from "../outbox-store-UYC4eZpI.mjs";
+export { type AccountBulkCreatedPayload, type AccountSeededPayload, type DomainEvent, type EntryArchivedPayload, type EntryCreatedPayload, type EntryDuplicatedPayload, type EntryPostedPayload, type EntryReversedPayload, type EntryUnpostedPayload, type EventContext, type EventHandler, type EventLogger, type EventTransport, InProcessLedgerBus, type InProcessLedgerBusOptions, type JournalSeededPayload, LEDGER_EVENTS, type LedgerEventName, type OutboxAcknowledgeOptions, type OutboxClaimOptions, type OutboxErrorInfo, type OutboxFailOptions, OutboxOwnershipError, type OutboxStore, type OutboxWriteOptions, type PublishManyResult, type ReconciliationMatchedPayload, type ReconciliationUnmatchedPayload, createEvent };

package/dist/events/index.mjs

@@ -0,0 +1,2 @@
+import { i as LEDGER_EVENTS, n as InProcessLedgerBus, r as createEvent, t as OutboxOwnershipError } from "../outbox-store-DQbL-KYT.mjs";
+export { InProcessLedgerBus, LEDGER_EVENTS, OutboxOwnershipError, createEvent };

package/dist/exports/index.d.mts

@@ -1,2 +1,2 @@
-import { _ as PopulatedJournalEntry, a as exportToCsv, c as getHeaders, d as serializeCsv, f as CsvOptions, g as PopulatedAccount, h as FlatJournalRow, i as quickbooksFieldMap, l as buildCsv, m as ExportFieldMap, n as flattenJournalEntry, o as extractAllRows, p as ExportField, r as universalFieldMap, s as extractRow, t as flattenJournalEntries, u as escapeCell, v as PopulatedJournalItem } from "../index-D1ZjgVxn.mjs";
+import { _ as PopulatedJournalEntry, a as exportToCsv, c as getHeaders, d as serializeCsv, f as CsvOptions, g as PopulatedAccount, h as FlatJournalRow, i as quickbooksFieldMap, l as buildCsv, m as ExportFieldMap, n as flattenJournalEntry, o as extractAllRows, p as ExportField, r as universalFieldMap, s as extractRow, t as flattenJournalEntries, u as escapeCell, v as PopulatedJournalItem } from "../index-J-XIbXH-.mjs";
 export { CsvOptions, ExportField, ExportFieldMap, FlatJournalRow, PopulatedAccount, PopulatedJournalEntry, PopulatedJournalItem, buildCsv, escapeCell, exportToCsv, extractAllRows, extractRow, flattenJournalEntries, flattenJournalEntry, getHeaders, quickbooksFieldMap, serializeCsv, universalFieldMap };