@classytic/ledger 0.6.0 → 0.8.0

package/dist/{trial-balance-s92GEvRR.d.mts → trial-balance-DTj-c21f.d.mts}

@@ -1,5 +1,5 @@
-import { c as DateRange } from "./core-BkGjuVZj.mjs";
-import { t as CountryPack } from "./index-BthGypsI.mjs";
+import { c as DateRange } from "./core-MpgjCqK0.mjs";
+import { t as CountryPack } from "./index-RNZsX0Yo.mjs";
 import { ClientSession, Model } from "mongoose";
 
 //#region src/utils/logger.d.ts
@@ -178,37 +178,6 @@ interface CashFlowReport {
   financing: CashFlowSection;
   netCashFlow: number;
 }
-interface TaxAccountBalance {
-  code: string;
-  name: string;
-  balance: number;
-  taxMetadata?: unknown;
-}
-interface TaxReturnSummary {
-  totalSales: number;
-  gstHstCollected: number;
-  inputTaxCredits: number;
-  netTax: number;
-  finalAmount: number;
-  isRefund: boolean;
-  refundAmount: number;
-  paymentAmount: number;
-}
-interface TaxReport {
-  period: {
-    startDate: string;
-    endDate: string;
-    province: string;
-  };
-  accountBalances: {
-    collected: Record<string, TaxAccountBalance>;
-    itc: Record<string, TaxAccountBalance>;
-    instalments: Record<string, TaxAccountBalance>;
-  };
-  craLines: Record<string | number, number>;
-  summary: TaxReturnSummary;
-  calculatedAt: string;
-}
 //#endregion
 //#region src/reports/balance-sheet.d.ts
 interface BalanceSheetOptions {
@@ -612,4 +581,4 @@ declare function generateTrialBalance(opts: TrialBalanceOptions, params: {
   filters?: Record<string, unknown>;
 }): Promise<TrialBalanceReport>;
 //#endregion
-export { TrialBalanceRow as $, generateDimensionBreakdown as A, BalanceSheetReport as B, FiscalReopenResult as C, DimensionBreakdownParams as D, DimensionBreakdownOptions as E, BudgetVsActualReport as F, IncomeStatementReport as G, CashFlowSection as H, BudgetVsActualRow as I, ReportCategory as J, LedgerEntry as K, generateBudgetVsActual as L, generateCashFlow as M, BudgetVsActualOptions as N, DimensionBreakdownReport as O, BudgetVsActualParams as P, TrialBalanceReport as Q, BalanceSheetOptions as R, FiscalCloseResult as S, reopenFiscalPeriod as T, GeneralLedgerAccount as U, CashFlowReport as V, GeneralLedgerReport as W, TaxReport as X, ReportGroup as Y, TaxReturnSummary as Z, IncomeStatementOptions as _, RevaluationReport as a, DEFAULT_BUCKETS as at, generateGeneralLedger as b, RevaluationRate as c, defaultLogger as ct, computeRevaluation as d, AgedBalanceOptions as et, PartnerLedgerLine as f, generatePartnerLedger as g, PartnerLedgerReport as h, RevaluationParams as i, AgedBucketConfig as it, CashFlowOptions as j, DimensionBreakdownRow as k, RevaluationResult as l, PartnerLedgerParams as m, generateTrialBalance as n, AgedBalanceReport as nt, generateRevaluation as o, generateAgedBalance as ot, PartnerLedgerOptions as p, ReportAccount as q, RevaluationOptions as r, AgedBalanceRow as rt, AccountForeignBalance as s, Logger as st, TrialBalanceOptions as t, AgedBalanceParams as tt, buildRevaluationEntry as u, generateIncomeStatement as v, closeFiscalPeriod as w, FiscalCloseOptions as x, GeneralLedgerOptions as y, generateBalanceSheet as z };
+export { AgedBalanceParams as $, generateDimensionBreakdown as A, BalanceSheetReport as B, FiscalReopenResult as C, DimensionBreakdownParams as D, DimensionBreakdownOptions as E, BudgetVsActualReport as F, IncomeStatementReport as G, CashFlowSection as H, BudgetVsActualRow as I, ReportCategory as J, LedgerEntry as K, generateBudgetVsActual as L, generateCashFlow as M, BudgetVsActualOptions as N, DimensionBreakdownReport as O, BudgetVsActualParams as P, AgedBalanceOptions as Q, BalanceSheetOptions as R, FiscalCloseResult as S, reopenFiscalPeriod as T, GeneralLedgerAccount as U, CashFlowReport as V, GeneralLedgerReport as W, TrialBalanceReport as X, ReportGroup as Y, TrialBalanceRow as Z, IncomeStatementOptions as _, RevaluationReport as a, Logger as at, generateGeneralLedger as b, RevaluationRate as c, computeRevaluation as d, AgedBalanceReport as et, PartnerLedgerLine as f, generatePartnerLedger as g, PartnerLedgerReport as h, RevaluationParams as i, generateAgedBalance as it, CashFlowOptions as j, DimensionBreakdownRow as k, RevaluationResult as l, PartnerLedgerParams as m, generateTrialBalance as n, AgedBucketConfig as nt, generateRevaluation as o, defaultLogger as ot, PartnerLedgerOptions as p, ReportAccount as q, RevaluationOptions as r, DEFAULT_BUCKETS as rt, AccountForeignBalance as s, TrialBalanceOptions as t, AgedBalanceRow as tt, buildRevaluationEntry as u, generateIncomeStatement as v, closeFiscalPeriod as w, FiscalCloseOptions as x, GeneralLedgerOptions as y, generateBalanceSheet as z };

package/docs/country-packs.md

@@ -1,6 +1,6 @@
 # Country Packs
 
-A country pack provides everything country-specific: chart of accounts template, tax codes, tax report templates, and region definitions.
+A country pack provides the **chart of accounts** + accounting conventions for a jurisdiction (retained-earnings code, COGS group, journal templates, fiscal year start month, report labels). Country packs are intentionally **tax-agnostic** in 0.7+ — tax computation, return templates, and tax code tables live in dedicated tax packages (`@classytic/bd-tax`, the planned `@classytic/ca-tax`, or your own).
 
 ## Using a Country Pack
 
@@ -9,6 +9,7 @@ import { createAccountingEngine } from '@classytic/ledger';
 import { canadaPack } from '@classytic/ledger-ca';
 
 const accounting = createAccountingEngine({
+  mongoose: mongoose.connection,
   country: canadaPack,
   currency: 'CAD',
 });
@@ -16,46 +17,44 @@ const accounting = createAccountingEngine({
 
 ## Available Packs
 
-| Package | Country | Account Types | Tax Codes |
+| Package | Country | Account Types | Notes |
 |---|---|---|---|
-| `@classytic/ledger-ca` | Canada | GIFI (CRA) | GST/HST/PST/QST |
+| `@classytic/ledger-ca` | Canada | GIFI (CRA-aligned) | Re-exports `TAX_CODES`, `TAX_CODES_BY_REGION`, `craReturnTemplate` as raw constants for tax engines to lift |
+| `@classytic/ledger-bd` | Bangladesh | BFRS (~600 accounts) | Re-exports `TAX_CODES`, `TAX_CODES_BY_DIVISION`, `mushakReturnTemplate` as raw constants for tax engines to lift |
 
 ## Creating a Custom Country Pack
 
 ```typescript
 import { defineCountryPack } from '@classytic/ledger';
-import type { AccountType, TaxCode } from '@classytic/ledger';
+import type { AccountType } from '@classytic/ledger';
 
 const myPack = defineCountryPack({
   code: 'US',
   name: 'United States',
   defaultCurrency: 'USD',
+  retainedEarningsAccountCode: '3200',
+  cogsGroupCode: 'Cost of Sales',
   accountTypes: [
     {
       code: '1000',
       name: 'Cash',
-      category: 'Balance Sheet-Assets',
-      mainType: 'Assets',
-      normalBalance: 'debit',
+      category: 'Balance Sheet-Asset',
+      description: 'Cash and equivalents',
+      parentCode: null,
       isGroup: false,
       isTotal: false,
+      cashFlowCategory: 'Operating',
     },
     // ... more account types
   ],
-  taxCodes: {
-    STATE_TAX: {
-      code: 'STATE_TAX',
-      name: 'State Sales Tax',
-      taxType: 'sales',
-      rate: 0.06,
-      direction: 'collected',
-      description: 'State sales tax',
-      active: true,
-    },
-  },
-  taxCodesByRegion: { CA: ['STATE_TAX'] },
-  regions: ['CA', 'NY', 'TX'],
-  taxReport: undefined, // optional tax return template
+  // Optional: declarative journal templates seeded per organization
+  journalTemplates: [
+    { code: 'SALES', name: 'Sales', journalType: 'SALES', kind: 'sale', sequencePrefix: 'INV' },
+    { code: 'PURCHASE', name: 'Purchases', journalType: 'PURCHASES', kind: 'purchase', sequencePrefix: 'BILL' },
+    { code: 'BANK', name: 'Bank', journalType: 'CASH_RECEIPTS', kind: 'bank', sequencePrefix: 'BNK' },
+    { code: 'CASH', name: 'Cash', journalType: 'CASH_PAYMENTS', kind: 'cash', sequencePrefix: 'CSH' },
+    { code: 'MISC', name: 'Miscellaneous', journalType: 'MISC', kind: 'general', sequencePrefix: 'JE' },
+  ],
 });
 ```
 
@@ -66,19 +65,30 @@ interface CountryPack {
   code: string;              // ISO 3166-1 alpha-2
   name: string;
   defaultCurrency: string;
-  accountTypes: AccountType[];
-  taxCodes: Record<string, TaxCode>;
-  taxCodesByRegion: Record<string, string[]>;
-  regions: string[];
-  taxReport?: TaxReportTemplate;
+  accountTypes: readonly AccountType[];
+
+  // Optional declarative journal templates for engine.repositories.journals.seedDefaults()
+  journalTemplates?: readonly JournalTemplate[];
+
+  // Country-specific report defaults
+  retainedEarningsAccountCode?: string;
+  retainedEarningsDisplayCode?: string;
+  currentYearEarningsCode?: string;
+  cogsGroupCode?: string;
+  reportLabels?: {
+    assets?: string;
+    liabilities?: string;
+    equity?: string;
+    revenue?: string;
+    expenses?: string;
+  };
 
   // Auto-generated helpers:
-  getPostingAccountTypes(): AccountType[];
+  getPostingAccountTypes(): readonly AccountType[];
   getAccountType(code: string): AccountType | undefined;
   isValidAccountType(code: string): boolean;
   isPostingAccount(code: string): boolean;
-  getTaxCodesForRegion(region: string): TaxCode[];
-  flattenAccountTypes(): AccountType[];
+  flattenAccountTypes(): readonly AccountType[];
 }
 ```
 
@@ -88,30 +98,44 @@ interface CountryPack {
 interface AccountType {
   code: string;
   name: string;
-  category: CategoryKey;        // e.g. 'Balance Sheet-Assets', 'Income Statement-Income'
-  mainType: MainType;           // 'Assets', 'Liabilities', 'Equity', etc.
-  normalBalance: 'debit' | 'credit';
-  isGroup: boolean;             // structural grouping header (not postable)
-  isTotal: boolean;             // calculated total row (not postable)
-  cashFlowCategory?: string;    // 'Operating', 'Investing', 'Financing'
-  taxMetadata?: TaxMetadata;    // for virtual tax sub-accounts
+  category: CategoryKey;        // e.g. 'Balance Sheet-Asset', 'Income Statement-Income'
+  description: string;
+  parentCode: string | null;    // grouping hierarchy
+  isGroup?: boolean;            // structural grouping header (not postable)
+  isTotal?: boolean;            // calculated total row (not postable)
+  cashFlowCategory?: 'Operating' | 'Investing' | 'Financing' | null;
+  taxMetadata?: TaxMetadata;    // opaque metadata pass-through (no logic)
+  deprecated?: boolean;
+  replacedBy?: string;
+  notes?: string;
 }
 ```
 
-Only accounts where `isGroup === false && isTotal === false` are posting accounts.
+Only accounts where `isGroup !== true && isTotal !== true` are posting accounts.
 
-## TaxCode Structure
+## JournalTemplate Structure
 
 ```typescript
-interface TaxCode {
-  code: string;
+interface JournalTemplate {
+  code: string;                 // 'SALES', 'PURCHASE', 'BANK', ...
   name: string;
-  taxType: string;                    // e.g. 'GST', 'HST', 'PST'
-  rate: number;                       // e.g. 0.05 for 5%
-  direction: 'collected' | 'recoverable' | 'paid';
-  province?: string;
-  reportLines?: number[];             // lines on the tax return
-  description: string;
-  active: boolean;
+  journalType: string;          // one of the registered JOURNAL_TYPES codes
+  sequencePrefix?: string;      // defaults to `code`
+  sequenceStartNum?: number;    // defaults to 1
+  kind?: 'general' | 'sale' | 'purchase' | 'bank' | 'cash' | string;
+  defaultDebitAccountRole?: string;
+  defaultCreditAccountRole?: string;
 }
 ```
+
+When the consumer calls `engine.repositories.journals.seedDefaults(orgId)`, the engine creates one Journal document per template with an isolated sequence counter.
+
+## Tax — out of scope
+
+Country packs in 0.7+ do **not** carry tax code tables, tax return templates, or tax repartition mappings. That work belongs in tax engine packages:
+
+- `@classytic/bd-tax` — Bangladesh income tax slabs, IT-11GA forms, VAT/TDS/VDS computation, Mushak 9.1 return generator, deduction optimizer
+- `@classytic/ca-tax` (planned) — Canadian GST/HST/PST/QST computation, CRA GST34 form, ITC tracking
+- Or roll your own — a tax engine just calls `engine.repositories.journalEntries.create()` with the tax line items it wants posted
+
+Country packs that previously bundled tax data (`ledger-bd`, `ledger-ca`) still re-export it as named constants — `TAX_CODES`, `TAX_CODES_BY_REGION` / `TAX_CODES_BY_DIVISION`, `mushakReturnTemplate`, `craReturnTemplate` — so tax engines can lift it directly without re-typing.

package/docs/engine.md

@@ -21,7 +21,7 @@ const accounting = createAccountingEngine({
 
 | Option | Type | Required | Description |
 |---|---|---|---|
-| `country` | `CountryPack` | Yes | Country pack (account types, tax codes) |
+| `country` | `CountryPack` | Yes | Country pack (chart of accounts + journal templates) |
 | `currency` | `string` | Yes | ISO 4217 currency code |
 | `multiTenant` | `{ orgField, orgRef }` | No | Multi-tenant configuration |
 | `fiscalYearStartMonth` | `number` | No | 1-12, default 1 (January) |
@@ -129,9 +129,10 @@ See [Reports](reports.md) for details.
 accounting.getPostingAccountTypes()   // → AccountType[]
 accounting.isValidAccountType('1000') // → boolean
 accounting.getAccountType('1000')     // → AccountType | undefined
-accounting.getTaxCodesForRegion('ON') // → TaxCode[]
 ```
 
+> Tax code lookups have moved out of the ledger in 0.7+ — they live in dedicated tax engine packages (`@classytic/bd-tax`, etc.). See [Country Packs](country-packs.md#tax--out-of-scope).
+
 ## Logger Interface
 
 The engine accepts a logger that implements:

package/docs/subledger-integration.md

@@ -1,6 +1,20 @@
 # Subledger Integration
 
-This guide explains how to integrate external subledgers (billing, inventory, payroll, etc.) with `@classytic/ledger`. The ledger provides **type-only posting contracts** — your application code is responsible for wiring subledgers to the journal entry repository.
+This guide explains how to integrate external subledgers (billing, inventory, payroll, etc.) with `@classytic/ledger`.
+
+## Which pattern should I use?
+
+| Subledger | Recommended approach |
+|---|---|
+| `@classytic/invoice` | Use `createLedgerBridge()` from `@classytic/ledger/sync` — see [sync.md](sync.md) |
+| Custom invoicing, billing, or any system with the `LedgerBridge` interface | Use `createLedgerBridge()` — same bridge, no `@classytic/invoice` dependency needed |
+| Inventory, payroll, or other custom subledgers | Use the `PostingContract` pattern described below |
+
+If you're integrating with `@classytic/invoice`, **start with [sync.md](sync.md)** — the bridge handles all the wiring for you. This document covers the manual `PostingContract` pattern for custom subledgers that don't use the invoice engine.
+
+---
+
+The ledger provides **type-only posting contracts** — your application code is responsible for wiring subledgers to the journal entry repository.
 
 ## Responsibility Boundaries
 
@@ -13,7 +27,7 @@ This guide explains how to integrate external subledgers (billing, inventory, pa
 | Idempotency (duplicate guard) | Yes — plugin checks `idempotencyKey` uniqueness | Must generate deterministic keys |
 | Posted-entry protection | Yes — plugin blocks field changes on posted entries; fully immutable when `strictness.immutable` enabled | Use `reverse()` for corrections; `unpost()` available when immutable mode is off |
 | Account code → ObjectId resolution | No | Yes — look up account by `accountType` code |
-| Tax calculation | No — country packs define tax codes, not tax logic | Yes — compute tax amounts before posting |
+| Tax calculation | No — tax engines are separate packages (`@classytic/bd-tax`, `@classytic/ca-tax`, etc.) | Yes — compute tax amounts before posting via your tax engine of choice |
 | Source document validation | No | Yes — implement `validate()` on the contract |
 | Creating the journal entry | No — provides `repo.post()` | Yes — call `repo.create()` then `repo.post()` |
 | Transaction coordination | No | Yes — wrap subledger + ledger writes in a session |
@@ -268,18 +282,25 @@ The ledger's `reverse()` creates a new journal entry with debits and credits swa
 
 ## Tax Handling
 
-The ledger's country packs define **tax code metadata** (names, rates, regions) but do **not** compute tax amounts. Tax calculation is the application's responsibility:
+`@classytic/ledger@0.7+` is intentionally tax-agnostic. Country packs ship the chart of accounts and journal templates only — tax computation, return generation, and tax-period filing locks all live in dedicated tax engine packages:
+
+- **`@classytic/bd-tax`** — Bangladesh income tax (IT-11GA), VAT/TDS/VDS computation, Mushak 9.1 returns
+- **`@classytic/ca-tax`** *(planned)* — Canadian GST/HST/PST/QST computation, CRA GST34 form
+- **Or roll your own** — a tax engine just computes amounts and posts the resulting tax line items via `engine.repositories.journalEntries.create()`
+
+The country packs `@classytic/ledger-bd` and `@classytic/ledger-ca` still re-export the raw tax data tables (`TAX_CODES`, `TAX_CODES_BY_DIVISION` / `TAX_CODES_BY_REGION`, `mushakReturnTemplate`, `craReturnTemplate`) as named constants so tax engines can lift them.
+
+The integration pattern:
 
-1. Look up applicable tax codes from the country pack (`accounting.getTaxCodesForRegion('ON')`)
-2. Compute tax amounts in your subledger / business logic
-3. Include tax lines as separate `SubledgerJournalItem` entries with the appropriate tax liability account code
-4. The ledger stores and reports on whatever you post — it does not validate tax arithmetic
+1. Compute tax amounts in your tax engine (input: invoice line items + jurisdiction; output: tax line items with account codes)
+2. Include those tax line items in the same `journalEntries.create()` call as the rest of the entry
+3. The ledger stores and reports on whatever you post — it does not validate tax arithmetic
 
 ## What the Ledger Does Not Do
 
 To set clear expectations, the ledger intentionally does **not**:
 
-- **Compute taxes** — country packs provide tax code catalogs, not calculation engines
+- **Compute taxes** — that lives in dedicated tax engine packages (see above)
 - **Manage invoices, bills, or payments** — these are subledger concerns
 - **Orchestrate multi-step workflows** — approval routing, email notifications, etc. are app-level
 - **Resolve account codes to ObjectIds** — the app must map country-pack codes to tenant accounts

package/docs/sync.md

@@ -0,0 +1,330 @@
+# Sync — Invoice Bridge, Import & Export
+
+`@classytic/ledger/sync` is the integration subpath for connecting external systems to the ledger.
+
+```typescript
+import {
+  // Invoice engine bridge (recommended)
+  createLedgerBridge,
+
+  // Import/export pipeline
+  wireImport,
+  wireExport,
+
+  // Mapper factories (fin-io canonical shapes → JournalEntry)
+  bankStatementMapper,
+  invoiceMapper,
+  journalEntryMapper,
+  openingBalanceMapper,
+} from '@classytic/ledger/sync';
+```
+
+---
+
+## Invoice Engine Integration
+
+### Recommended: `createLedgerBridge()`
+
+Wire `@classytic/invoice` to `@classytic/ledger` with one call. The bridge handles account mapping, tax lines, credit notes, payments, and reversals — no manual journal wiring needed.
+
+```typescript
+import { createAccountingEngine } from '@classytic/ledger';
+import { createLedgerBridge } from '@classytic/ledger/sync';
+import { createInvoiceEngine } from '@classytic/invoice';
+import { canadaPack } from '@classytic/ledger-ca';
+
+// 1. Create the accounting engine
+const accounting = createAccountingEngine({
+  mongoose: connection,
+  country: canadaPack,
+  currency: 'CAD',
+  multiTenant: { orgField: 'organizationId', orgRef: 'Organization' },
+  idempotency: true,
+});
+
+// 2. Create the bridge — map your chart of accounts once
+const bridge = createLedgerBridge(accounting, {
+  accounts: {
+    receivable: '1200',     // Accounts Receivable
+    payable: '2000',        // Accounts Payable
+    revenue: '4000',        // Revenue
+    expense: '5000',        // Cost of Goods Sold / Expenses
+    taxPayable: '2100',     // HST/GST/VAT Payable
+    taxReceivable: '1150',  // HST/GST/VAT Receivable (Input Tax Credit)
+    cash: '1000',           // Cash / Bank
+  },
+});
+
+// 3. Pass the bridge to the invoice engine — done
+const invoicing = createInvoiceEngine({
+  mongoose: connection,
+  ledger: bridge,
+  // ... other invoice config
+});
+```
+
+From this point, every invoice lifecycle operation automatically posts to the ledger:
+
+- **`invoicing.services.posting.post(id)`** → creates a balanced journal entry
+- **`invoicing.services.payment.recordPayment(input)`** → posts a payment entry (DR Cash, CR AR)
+- **`invoicing.services.posting.cancel(id, reason)`** → reverses the journal entry
+- **`invoicing.services.posting.void(id, reason)`** → reverses the journal entry (even if partially paid)
+
+### How the bridge maps each move type
+
+| Invoice Move Type | Journal Lines | Journal Type |
+|---|---|---|
+| `out_invoice` (Customer Invoice) | DR Receivable (total), CR Revenue (per line), CR Tax Payable | `SALES` |
+| `in_invoice` (Vendor Bill) | DR Expense (per line), DR Tax Receivable, CR Payable (total) | `PURCHASES` |
+| `out_refund` (Customer Credit Note) | CR Receivable, DR Revenue (per line), DR Tax Payable | `SALES` |
+| `in_refund` (Vendor Credit Note) | DR Payable, CR Expense (per line), CR Tax Receivable | `PURCHASES` |
+| `receipt` (POS Receipt) | DR Receivable/Cash, CR Revenue (per line), CR Tax Payable | `CASH_RECEIPTS` |
+
+All amounts are integer cents. Tax lines are only added when `taxAmount > 0`.
+
+### Payment recording
+
+When the invoice engine records a payment, the bridge calls `engine.record.payment()`:
+
+```
+DR Cash (1000)        $500.00
+CR Receivable (1200)  $500.00
+```
+
+An idempotency key is automatically derived from the payment ID (`payment:{paymentId}`), preventing duplicate journal entries on retry.
+
+### Reversal
+
+When an invoice is cancelled or voided, the bridge calls `engine.repositories.journalEntries.reverse()`, which creates a mirror entry with debits and credits swapped and links both entries bidirectionally.
+
+### Bridge configuration options
+
+#### `receiptAccount`
+
+Override the debit account for POS receipts. By default, receipts debit the `receivable` account. If your receipts are immediately paid (no A/R), point this at cash:
+
+```typescript
+createLedgerBridge(accounting, {
+  accounts: { ... },
+  receiptAccount: '1000',  // Receipts debit Cash directly
+});
+```
+
+#### `resolvePaymentAccounts`
+
+Custom resolver for payment accounts. Use when you need to determine AR vs AP based on context (e.g., vendor bill payments should clear AP, not AR):
+
+```typescript
+createLedgerBridge(accounting, {
+  accounts: { ... },
+  resolvePaymentAccounts: (input) => {
+    const isVendor = vendorInvoiceIds.has(input.invoiceId);
+    return {
+      receivableOrPayable: isVendor ? '2000' : '1200',
+      cash: '1000',
+    };
+  },
+});
+```
+
+### Double-entry guarantee
+
+The bridge uses `engine.record.adjustment()` internally. This routes through the ledger's double-entry plugin, which validates `sum(debits) === sum(credits)` before persisting. If the invoice engine sends unbalanced data, the ledger rejects it with a structured validation error.
+
+---
+
+### Alternative: Manual wiring (without `createLedgerBridge`)
+
+If you need full control over the journal entry shape — for example, to add dimension fields, use different accounts per line, or handle complex tax scenarios — you can implement the `LedgerBridge` interface yourself:
+
+```typescript
+import type { LedgerBridge } from '@classytic/ledger/sync';
+
+const ledgerBridge: LedgerBridge = {
+  async createJournalEntry(input) {
+    // Use record.adjustment() for multi-line entries with tax
+    const entry = await accounting.record.adjustment(input.organizationId, {
+      date: input.date,
+      label: `Invoice ${input.invoiceId}`,
+      journalType: 'SALES',
+      lines: [
+        { account: '1200', debit: input.totalAmount },
+        ...input.lines.map(line => ({
+          account: '4000',
+          credit: line.amount,
+          label: line.description,
+        })),
+        ...(input.taxAmount > 0
+          ? [{ account: '2100', credit: input.taxAmount, label: 'Tax' }]
+          : []),
+      ],
+    }, {
+      idempotencyKey: input.idempotencyKey,
+    });
+    return String((entry as any)._id);
+  },
+
+  async reverseJournalEntry(journalEntryId, reason) {
+    const { reversal } = await accounting.repositories.journalEntries
+      .reverse(journalEntryId);
+    return String((reversal as any)._id);
+  },
+
+  async recordPayment(input) {
+    const entry = await accounting.record.payment(input.organizationId, {
+      date: input.date,
+      amount: input.amount,
+      fromReceivableAccount: '1200',
+      toCashAccount: '1000',
+      label: `Payment ${input.paymentId} for ${input.invoiceId}`,
+    }, {
+      idempotencyKey: `payment:${input.paymentId}`,
+    });
+    return String((entry as any)._id);
+  },
+};
+
+// Then pass to the invoice engine
+const invoicing = createInvoiceEngine({
+  mongoose: connection,
+  ledger: ledgerBridge,
+});
+```
+
+This gives you the same integration but with full control over account resolution, dimension fields, and tax line construction.
+
+### Using `LedgerBridge` without `@classytic/invoice`
+
+The bridge types are generic — any invoicing system that calls these 3 methods works:
+
+```typescript
+import type { LedgerBridge, LedgerPostInput, LedgerPaymentInput } from '@classytic/ledger/sync';
+
+// Use createLedgerBridge() for standard mapping
+const bridge: LedgerBridge = createLedgerBridge(accounting, { accounts: { ... } });
+
+// Post an invoice
+const jeId = await bridge.createJournalEntry({
+  organizationId: 'org_1',
+  invoiceId: 'INV-001',
+  moveType: 'out_invoice',
+  partnerId: 'customer-123',
+  date: new Date(),
+  currency: 'USD',
+  lines: [
+    { description: 'Consulting', amount: 100000, taxAmount: 13000, taxCode: 'HST' },
+  ],
+  totalAmount: 113000,
+  taxAmount: 13000,
+});
+
+// Record a payment
+await bridge.recordPayment({
+  organizationId: 'org_1',
+  invoiceId: 'INV-001',
+  paymentId: 'PAY-001',
+  amount: 113000,
+  currency: 'USD',
+  date: new Date(),
+  method: 'bank_transfer',
+});
+
+// Reverse (cancel/void)
+await bridge.reverseJournalEntry(jeId, 'Invoice cancelled');
+```
+
+---
+
+## Bank Statement Import
+
+Import bank transactions from any format supported by `@classytic/fin-io`:
+
+```typescript
+import { parseOfx } from '@classytic/fin-io/ofx';
+import { wireImport, bankStatementMapper } from '@classytic/ledger/sync';
+
+const parsed = parseOfx(buffer);
+if (!parsed.ok) throw new Error(parsed.error);
+
+const report = await wireImport({
+  source: parsed.data.flatMap(s => s.transactions),
+  mapper: bankStatementMapper({
+    bankAccountId: bankAccount._id,
+    suspenseAccountId: suspenseAccount._id,
+    categorize: (txn) => knownVendors[txn.counterparty?.name]?.accountId,
+  }),
+  journalEntries: engine.repositories.journalEntries,
+  context: { organizationId },
+}).run();
+
+console.log(`Imported ${report.inserted}, skipped ${report.skipped} duplicates`);
+```
+
+### Available mappers
+
+| Mapper | Source | Output |
+|---|---|---|
+| `bankStatementMapper` | `CanonicalTransaction` (OFX, CAMT, MT940, CSV, Plaid) | 2-line JE: Cash ↔ Suspense |
+| `invoiceMapper` | `CanonicalInvoice` (QBO, Xero JSON) | Multi-line JE: AR/AP ↔ Revenue/Expense ↔ Tax |
+| `journalEntryMapper` | `CanonicalJournalEntry` (QBO, Xero manual journals) | 1:1 mapping |
+| `openingBalanceMapper` | `TrialBalanceInput` | Multi-line opening balance entry |
+
+### Idempotency
+
+Re-running an import on the same file produces zero duplicates. Each mapper extracts a stable `externalId` from the source record (e.g., OFX `FITID`, CAMT `NtryRef`). The `wireImport` pipeline checks for existing entries before creating.
+
+For best performance, provide a `findExisting` callback and add a partial index on `{ organizationId: 1, _externalId: 1 }`.
+
+---
+
+## Export
+
+Stream ledger data to external formats:
+
+```typescript
+import { wireExport } from '@classytic/ledger/sync';
+
+const report = await wireExport({
+  query: { organizationId: 'org_1', state: 'posted' },
+  sink: {
+    fromJournalEntry: (entry) => transformToCSVRow(entry),
+    emit: async (rows) => csvStream.write(rows),
+    flush: async () => csvStream.end(),
+  },
+  journalEntries: engine.repositories.journalEntries,
+  options: { batchSize: 500 },
+}).run();
+```
+
+---
+
+## Writing Custom Mappers
+
+Implement `ImportMapper<TRaw>` for any data source:
+
+```typescript
+import type { ImportMapper } from '@classytic/ledger/sync';
+
+interface MyPayrollRecord {
+  id: string;
+  employeeName: string;
+  grossPay: number;
+  taxWithheld: number;
+  netPay: number;
+  date: Date;
+}
+
+const payrollMapper: ImportMapper<MyPayrollRecord> = {
+  externalId: (record) => `payroll:${record.id}`,
+
+  toJournalEntry: (record, ctx) => ({
+    date: record.date,
+    label: `Payroll — ${record.employeeName}`,
+    journalItems: [
+      { account: salaryExpenseId, debit: record.grossPay, credit: 0 },
+      { account: taxPayableId, debit: 0, credit: record.taxWithheld },
+      { account: cashId, debit: 0, credit: record.netPay },
+    ],
+  }),
+};
+```