@classytic/ledger 0.6.0 → 0.8.0

package/dist/{tax-hooks-BnVenul5.d.mts → index-BSsvrf3m.d.mts}

@@ -1,6 +1,6 @@
-import { ClientSession, Model } from "mongoose";
 import * as _classytic_mongokit0 from "@classytic/mongokit";
 import { Repository, RepositoryContext, RepositoryInstance } from "@classytic/mongokit";
+import { ClientSession, Model } from "mongoose";
 
 //#region src/types/repositories.d.ts
 interface PostOptions {
@@ -213,7 +213,22 @@ declare function creditLimitPlugin(options: CreditLimitPluginOptions): {
  * This file is side-effect only — importing it anywhere in the package is
  * enough to activate the augmentation. `src/types/index.ts` re-exports it.
  */
-type LedgerInternalOp = 'post' | 'unpost' | 'archive' | 'reverseMark' | 'fxRealize' | 'cashBasisRealize';
+/**
+ * Internal op tags attached to `repository.update()` / `repository.create()`
+ * calls that the ledger itself initiates. Plugins observing the
+ * `before:update` / `before:create` hooks can read `context._ledgerInternal`
+ * to identify legitimate engine operations and skip guards accordingly.
+ *
+ * - `post` / `unpost` / `archive`  — state transitions on an entry
+ * - `reverseMark`                  — marking an original as reversed
+ *                                    (exempt from fiscal/daily locks)
+ * - `fxRealize`                    — FX realization plugin balancing entry
+ *                                    (exempt from all locks and credit-limit)
+ *
+ * Tax-specific internal ops (e.g. cash-basis exigibility realization) live
+ * in their respective tax packages and are not part of the ledger core.
+ */
+type LedgerInternalOp = 'post' | 'unpost' | 'archive' | 'reverseMark' | 'fxRealize';
 declare module '@classytic/mongokit' {
   interface RepositoryContext {
     /**
@@ -414,48 +429,6 @@ declare function fiscalLockPlugin(options: FiscalLockPluginOptions): {
   name: string;
   apply(repo: _classytic_mongokit0.RepositoryInstance): void;
 };
-interface TaxLockPluginOptions {
-  /**
-   * Tax-period model. Expected shape (fields are overridable via the
-   * lower-level `createLockPlugin` if your schema differs):
-   *
-   *   {
-   *     periodStart: Date,
-   *     periodEnd: Date,
-   *     status: 'open' | 'filed' | 'amended',
-   *     jurisdiction?: string,
-   *     taxType?: string,
-   *     returnRef?: string,
-   *     [orgField]?: unknown,
-   *   }
-   *
-   * `status !== 'open'` counts as locked.
-   */
-  TaxPeriodModel: Model<unknown>;
-  AccountModel: Model<unknown>;
-  JournalEntryModel?: Model<unknown>;
-  orgField?: string;
-  /**
-   * Predicate deciding which accounts participate in tax returns.
-   * Defaults to `acc => acc.taxMetadata != null` — matches the
-   * convention used by country packs that populate `taxMetadata` on
-   * tax-payable / tax-recoverable account types.
-   */
-  isTaxAffecting?: LockAccountSelector;
-  /**
-   * Derive `{ jurisdiction, taxType }` from the entry payload so each
-   * post can look up the right row. Default: use `data.jurisdiction`
-   * and `data.taxType` directly when present.
-   */
-  deriveFilter?: (data: Record<string, unknown>) => {
-    jurisdiction?: string;
-    taxType?: string;
-  } | undefined;
-}
-declare function taxLockPlugin(options: TaxLockPluginOptions): {
-  name: string;
-  apply(repo: _classytic_mongokit0.RepositoryInstance): void;
-};
 interface DailyLockPluginOptions {
   /**
    * Return the `lastClosedDate` for the given org/branch — everything
@@ -488,26 +461,4 @@ interface WatermarkResolverOptions {
 }
 declare function watermarkResolver(options: WatermarkResolverOptions): LockResolver;
 //#endregion
-//#region src/utils/tax-hooks.d.ts
-interface TaxLineInput {
-  account: unknown;
-  amount: number;
-  side: 'debit' | 'credit';
-  taxCode?: string;
-  extraFields?: Record<string, unknown>;
-}
-interface GeneratedTaxLine {
-  account: unknown;
-  debit: number;
-  credit: number;
-  label?: string;
-  taxDetails?: Array<{
-    taxCode: string;
-    taxName?: string;
-  }>;
-}
-interface TaxLineGenerator {
-  generateTaxLines(input: TaxLineInput): GeneratedTaxLine[];
-}
-//#endregion
-export { JournalEntryRepository as A, SeedResult as B, DoubleEntryPluginOptions as C, AccountRepository as D, creditLimitPlugin as E, PostOptions as F, ReconciliationRepository as I, ReverseOptions as L, JournalRepository as M, MatchInput as N, BulkCreateInput as O, OpenItem as P, ReverseResult as R, fxRealizationPlugin as S, CreditLimitPluginOptions as T, LockResolver as _, DailyLockPluginOptions as a, idempotencyPlugin as b, dailyLockPlugin as c, PeriodResolverOptions as d, periodResolver as f, LockHit as g, LockAccountSelector as h, watermarkResolver as i, JournalItemRef as j, BulkCreateResult as k, fiscalLockPlugin as l, CreateLockPluginOptions as m, TaxLineInput as n, FiscalLockPluginOptions as o, createLockPlugin as p, WatermarkResolverOptions as r, TaxLockPluginOptions as s, TaxLineGenerator as t, taxLockPlugin as u, LockResolverContext as v, doubleEntryPlugin as w, FxRealizationPluginOptions as x, IdempotencyPluginOptions as y, SeedOptions as z };
+export { OpenItem as A, AccountRepository as C, JournalItemRef as D, JournalEntryRepository as E, SeedOptions as F, SeedResult as I, ReconciliationRepository as M, ReverseOptions as N, JournalRepository as O, ReverseResult as P, creditLimitPlugin as S, BulkCreateResult as T, FxRealizationPluginOptions as _, dailyLockPlugin as a, doubleEntryPlugin as b, periodResolver as c, LockAccountSelector as d, LockHit as f, idempotencyPlugin as g, IdempotencyPluginOptions as h, FiscalLockPluginOptions as i, PostOptions as j, MatchInput as k, createLockPlugin as l, LockResolverContext as m, watermarkResolver as n, fiscalLockPlugin as o, LockResolver as p, DailyLockPluginOptions as r, PeriodResolverOptions as s, WatermarkResolverOptions as t, CreateLockPluginOptions as u, fxRealizationPlugin as v, BulkCreateInput as w, CreditLimitPluginOptions as x, DoubleEntryPluginOptions as y };

package/dist/index-RNZsX0Yo.d.mts

@@ -0,0 +1,130 @@
+import { t as AccountType } from "./core-MpgjCqK0.mjs";
+
+//#region src/country/index.d.ts
+/**
+ * Declarative template that tells the engine which journals to seed for a
+ * new organization. Consumers call
+ * `engine.repositories.journals.seedDefaults(orgId)` which reads these from
+ * the country pack and creates one Journal document per template.
+ *
+ * Journals are *optional* — if a consumer never seeds journals, the legacy
+ * `journalType` enum on a journal entry still works. Consumers opting in
+ * get per-journal sequence prefixes, restricted payment methods, bank
+ * statement sources, etc.
+ */
+interface JournalTemplate {
+  /** Short stable identifier — e.g. `'SALES'`, `'PURCHASE'`, `'BANK'`. */
+  readonly code: string;
+  /** Display name. */
+  readonly name: string;
+  /**
+   * One of the registered `JOURNAL_TYPES` codes — connects this journal to
+   * the engine's reference-number generator and posting-contract system.
+   */
+  readonly journalType: string;
+  /** Reference-number prefix — defaults to `code` when omitted. */
+  readonly sequencePrefix?: string;
+  /** First sequence number — defaults to `1`. */
+  readonly sequenceStartNum?: number;
+  /**
+   * Logical source — pure ledgering (`'general'`), sale-side docs (`'sale'`),
+   * purchase-side docs (`'purchase'`), cash/bank movement (`'bank'`, `'cash'`).
+   * Drives default locks (sale-lock, purchase-lock) when they're wired.
+   */
+  readonly kind?: 'general' | 'sale' | 'purchase' | 'bank' | 'cash' | string;
+  /** Optional default debit/credit account roles for quick data entry. */
+  readonly defaultDebitAccountRole?: string;
+  readonly defaultCreditAccountRole?: string;
+}
+interface CountryPack {
+  /** ISO 3166-1 alpha-2 code (e.g., 'CA', 'US', 'GB') */
+  readonly code: string;
+  /** Country name */
+  readonly name: string;
+  /** Default currency code */
+  readonly defaultCurrency: string;
+  /**
+   * Full chart of accounts template — flat array of account type definitions.
+   * Includes both posting accounts and grouping / total rows.
+   */
+  readonly accountTypes: readonly AccountType[];
+  /**
+   * Optional journal templates seeded per organization. When a consumer
+   * calls `engine.repositories.journals.seedDefaults(orgId)`, the engine
+   * creates one Journal document per template. See `JournalTemplate`.
+   */
+  readonly journalTemplates?: readonly JournalTemplate[];
+  /**
+   * The retained earnings account code — the account that holds accumulated
+   * retained earnings (e.g. '3600' CA, '3310' BD).
+   *
+   * On the balance sheet, this account is excluded from normal equity grouping
+   * and its balance is folded into the computed "Retained Earnings" section
+   * (opening RE = RE account balance + prior-year unclosed P&L).
+   *
+   * Inspired by Odoo's `equity_unaffected` account type.
+   */
+  readonly retainedEarningsAccountCode?: string;
+  /**
+   * Display code for the "Previous Years Retained Earnings" line on the
+   * balance sheet (e.g. '3660' for CA GIFI). Defaults to retainedEarningsAccountCode.
+   */
+  readonly retainedEarningsDisplayCode?: string;
+  /** Display code for current year net income line (e.g. '3680' CA, '3311' BD) */
+  readonly currentYearEarningsCode?: string;
+  /**
+   * Account code used as the equity contra for opening balance entries.
+   * Defaults to `retainedEarningsAccountCode` when not set.
+   *
+   * Following Odoo convention, this is typically the retained earnings
+   * account itself (not a temporary "Opening Balance Equity" account).
+   * Country packs that prefer a separate temporary account (like ERPNext)
+   * can override this.
+   */
+  readonly openingBalanceEquityCode?: string;
+  /** Group label code used to identify Cost of Sales in the income statement */
+  readonly cogsGroupCode?: string;
+  /** Override default English report section names */
+  readonly reportLabels?: {
+    readonly assets?: string;
+    readonly liabilities?: string;
+    readonly equity?: string;
+    readonly revenue?: string;
+    readonly expenses?: string;
+  };
+  /** Get all account types that can be posted to (not groups, not totals) */
+  getPostingAccountTypes(): readonly AccountType[];
+  /** Get account type by code */
+  getAccountType(code: string): AccountType | undefined;
+  /** Validate an account type code exists */
+  isValidAccountType(code: string): boolean;
+  /** Check if an account type can receive postings */
+  isPostingAccount(code: string): boolean;
+  /** Flatten hierarchical accounts (if needed) */
+  flattenAccountTypes(): readonly AccountType[];
+}
+interface CountryPackInput {
+  code: string;
+  name: string;
+  defaultCurrency: string;
+  accountTypes: readonly AccountType[];
+  journalTemplates?: readonly JournalTemplate[];
+  retainedEarningsAccountCode?: string;
+  retainedEarningsDisplayCode?: string;
+  currentYearEarningsCode?: string;
+  openingBalanceEquityCode?: string;
+  cogsGroupCode?: string;
+  reportLabels?: {
+    readonly assets?: string;
+    readonly liabilities?: string;
+    readonly equity?: string;
+    readonly revenue?: string;
+    readonly expenses?: string;
+  };
+}
+/**
+ * Factory to create a CountryPack with auto-generated helper methods.
+ */
+declare function defineCountryPack(input: CountryPackInput): CountryPack;
+//#endregion
+export { defineCountryPack as i, CountryPackInput as n, JournalTemplate as r, CountryPack as t };

package/dist/index.d.mts

@@ -1,12 +1,12 @@
-import { _ as TaxMetadata, a as Cents, c as DateRange, d as JournalType, f as MainType, g as TaxDetail, h as StatementType, i as CategoryKey, l as EntryState, m as ObjectId, n as CashFlowCategory, o as Currency, p as NormalBalance, s as DateOption, t as AccountType, u as JournalItem, v as TotalAccountOp } from "./core-BkGjuVZj.mjs";
-import { S as isValidCategory, a as getJournalTypeCodes, b as isBalanceSheet, c as CURRENCIES, d as isValidCurrency, f as CATEGORIES, i as getJournalType, l as getCurrency, n as JOURNAL_TYPES, o as isValidJournalType, p as CATEGORY_KEYS, r as getCustomJournalTypes, s as registerJournalType, t as JOURNAL_CODES, u as getMinorUnit, x as isIncomeStatement, y as getNormalBalance } from "./journals-C50E9mpo.mjs";
-import { a as TaxCodesByRegion, c as TaxReportLine, i as TaxCode, l as TaxReportTemplate, n as CountryPackInput, o as TaxExigibility, r as JournalTemplate, s as TaxRepartitionLine, t as CountryPack, u as defineCountryPack } from "./index-BthGypsI.mjs";
-import { _ as PopulatedJournalEntry, a as exportToCsv, h as FlatJournalRow, i as quickbooksFieldMap, m as ExportFieldMap, p as ExportField, r as universalFieldMap, t as flattenJournalEntries } from "./index-D1ZjgVxn.mjs";
+import { _ as TaxMetadata, a as Cents, c as DateRange, d as JournalType, f as MainType, g as TaxDetail, h as StatementType, i as CategoryKey, l as EntryState, m as ObjectId, n as CashFlowCategory, o as Currency, p as NormalBalance, s as DateOption, t as AccountType, u as JournalItem, v as TotalAccountOp } from "./core-MpgjCqK0.mjs";
+import { S as isValidCategory, a as getJournalTypeCodes, b as isBalanceSheet, c as CURRENCIES, d as isValidCurrency, f as CATEGORIES, i as getJournalType, l as getCurrency, n as JOURNAL_TYPES, o as isValidJournalType, p as CATEGORY_KEYS, r as getCustomJournalTypes, s as registerJournalType, t as JOURNAL_CODES, u as getMinorUnit, x as isIncomeStatement, y as getNormalBalance } from "./journals-Dd4A9TN3.mjs";
+import { i as defineCountryPack, n as CountryPackInput, r as JournalTemplate, t as CountryPack } from "./index-RNZsX0Yo.mjs";
+import { _ as PopulatedJournalEntry, a as exportToCsv, h as FlatJournalRow, i as quickbooksFieldMap, m as ExportFieldMap, p as ExportField, r as universalFieldMap, t as flattenJournalEntries } from "./index-bCEeSzdO.mjs";
 import { Money, abs, add, allocate, equals, format, formatPlain, fromDecimal, isNegative, isPositive, isValid, isZero, max, min, multiply, negate, parseCents, percentage, round, splitTaxExclusive, splitTaxInclusive, subtract, toDecimal } from "./money.mjs";
-import { $ as TrialBalanceRow, A as generateDimensionBreakdown, B as BalanceSheetReport, D as DimensionBreakdownParams, E as DimensionBreakdownOptions, F as BudgetVsActualReport, G as IncomeStatementReport, H as CashFlowSection, I as BudgetVsActualRow, J as ReportCategory, K as LedgerEntry, L as generateBudgetVsActual, M as generateCashFlow, N as BudgetVsActualOptions, O as DimensionBreakdownReport, P as BudgetVsActualParams, Q as TrialBalanceReport, T as reopenFiscalPeriod, U as GeneralLedgerAccount, V as CashFlowReport, W as GeneralLedgerReport, X as TaxReport, Y as ReportGroup, Z as TaxReturnSummary, a as RevaluationReport, at as DEFAULT_BUCKETS, b as generateGeneralLedger, c as RevaluationRate, ct as defaultLogger, d as computeRevaluation, et as AgedBalanceOptions, f as PartnerLedgerLine, g as generatePartnerLedger, h as PartnerLedgerReport, i as RevaluationParams, it as AgedBucketConfig, k as DimensionBreakdownRow, l as RevaluationResult, m as PartnerLedgerParams, n as generateTrialBalance, nt as AgedBalanceReport, o as generateRevaluation, ot as generateAgedBalance, p as PartnerLedgerOptions, q as ReportAccount, r as RevaluationOptions, rt as AgedBalanceRow, s as AccountForeignBalance, st as Logger, tt as AgedBalanceParams, u as buildRevaluationEntry, v as generateIncomeStatement, w as closeFiscalPeriod, z as generateBalanceSheet } from "./trial-balance-s92GEvRR.mjs";
-import { A as JournalEntryRepository, B as SeedResult, D as AccountRepository, E as creditLimitPlugin, F as PostOptions, I as ReconciliationRepository, L as ReverseOptions, M as JournalRepository, N as MatchInput, O as BulkCreateInput, P as OpenItem, R as ReverseResult, S as fxRealizationPlugin, T as CreditLimitPluginOptions, _ as LockResolver, a as DailyLockPluginOptions, b as idempotencyPlugin, c as dailyLockPlugin, d as PeriodResolverOptions, f as periodResolver, g as LockHit, h as LockAccountSelector, i as watermarkResolver, j as JournalItemRef, k as BulkCreateResult, l as fiscalLockPlugin, m as CreateLockPluginOptions, n as TaxLineInput, o as FiscalLockPluginOptions, p as createLockPlugin, r as WatermarkResolverOptions, s as TaxLockPluginOptions, t as TaxLineGenerator, u as taxLockPlugin, v as LockResolverContext, w as doubleEntryPlugin, x as FxRealizationPluginOptions, z as SeedOptions } from "./tax-hooks-BnVenul5.mjs";
+import { $ as AgedBalanceParams, A as generateDimensionBreakdown, B as BalanceSheetReport, D as DimensionBreakdownParams, E as DimensionBreakdownOptions, F as BudgetVsActualReport, G as IncomeStatementReport, H as CashFlowSection, I as BudgetVsActualRow, J as ReportCategory, K as LedgerEntry, L as generateBudgetVsActual, M as generateCashFlow, N as BudgetVsActualOptions, O as DimensionBreakdownReport, P as BudgetVsActualParams, Q as AgedBalanceOptions, T as reopenFiscalPeriod, U as GeneralLedgerAccount, V as CashFlowReport, W as GeneralLedgerReport, X as TrialBalanceReport, Y as ReportGroup, Z as TrialBalanceRow, a as RevaluationReport, at as Logger, b as generateGeneralLedger, c as RevaluationRate, d as computeRevaluation, et as AgedBalanceReport, f as PartnerLedgerLine, g as generatePartnerLedger, h as PartnerLedgerReport, i as RevaluationParams, it as generateAgedBalance, k as DimensionBreakdownRow, l as RevaluationResult, m as PartnerLedgerParams, n as generateTrialBalance, nt as AgedBucketConfig, o as generateRevaluation, ot as defaultLogger, p as PartnerLedgerOptions, q as ReportAccount, r as RevaluationOptions, rt as DEFAULT_BUCKETS, s as AccountForeignBalance, tt as AgedBalanceRow, u as buildRevaluationEntry, v as generateIncomeStatement, w as closeFiscalPeriod, z as generateBalanceSheet } from "./trial-balance-DTj-c21f.mjs";
+import { A as OpenItem, C as AccountRepository, D as JournalItemRef, E as JournalEntryRepository, F as SeedOptions, I as SeedResult, M as ReconciliationRepository, N as ReverseOptions, O as JournalRepository, P as ReverseResult, S as creditLimitPlugin, T as BulkCreateResult, _ as FxRealizationPluginOptions, a as dailyLockPlugin, b as doubleEntryPlugin, c as periodResolver, d as LockAccountSelector, f as LockHit, g as idempotencyPlugin, i as FiscalLockPluginOptions, j as PostOptions, k as MatchInput, l as createLockPlugin, m as LockResolverContext, n as watermarkResolver, o as fiscalLockPlugin, p as LockResolver, r as DailyLockPluginOptions, s as PeriodResolverOptions, t as WatermarkResolverOptions, u as CreateLockPluginOptions, v as fxRealizationPlugin, w as BulkCreateInput, x as CreditLimitPluginOptions } from "./index-BSsvrf3m.mjs";
+import { PaginationConfig, PluginType, QueryParser, QueryParserOptions, Repository } from "@classytic/mongokit";
 import { ClientSession, Connection, Model } from "mongoose";
-import { PaginationConfig, PluginType, Repository } from "@classytic/mongokit";
 
 //#region src/types/engine.d.ts
 /** Mongokit plugins to install per repository (composes with engine built-ins). */
@@ -256,23 +256,18 @@ interface IntrospectAPI {
    * Agents use this to discover what analytics they can run.
    */
   reports(): ReadonlyArray<ReportDescriptor>;
-  /**
-   * List tax codes — all of them, or filtered by region.
-   */
-  taxCodes(region?: string): ReadonlyArray<TaxCode>;
   /**
    * List fiscal periods for an organization.
    */
   fiscalPeriods(organizationId?: unknown, session?: ClientSession | null): Promise<FiscalPeriodSummary[]>;
   /**
    * A one-shot snapshot of everything an agent needs to start working:
-   * accounts, journal types, reports, tax codes, fiscal periods.
+   * accounts, journal types, reports, fiscal periods.
    */
   catalog(organizationId?: unknown): Promise<{
     accounts: AccountSummary[];
     journalTypes: ReadonlyArray<JournalType>;
     reports: ReadonlyArray<ReportDescriptor>;
-    taxCodes: ReadonlyArray<TaxCode>;
     fiscalPeriods: FiscalPeriodSummary[];
   }>;
 }
@@ -292,21 +287,6 @@ interface ActorContext {
 type AccountCode = string;
 /** Integer-cents amount. */
 type Cents$1 = number;
-interface TaxInput {
-  /** Tax code from the country pack (e.g. 'HST', 'GST', 'VAT') */
-  readonly code: string;
-  /**
-   * Account type code where the tax amount posts.
-   * For sales: the tax-payable account (e.g. '2300' HST Collected).
-   * For expenses: the tax-recoverable (ITC) account (e.g. '2400' HST Paid).
-   */
-  readonly account: AccountCode;
-  /**
-   * If true, `amount` is tax-inclusive and will be split into base + tax.
-   * If false (default), `amount` is the tax-exclusive base and tax is added.
-   */
-  readonly inclusive?: boolean;
-}
 /**
  * Options passed to every record.* operation. Matches mongokit's
  * RepositoryContext shape so audit/observability plugins pick them up
@@ -331,14 +311,16 @@ interface RecordOptions {
 interface RecordSaleInput {
   /** Transaction date */
   readonly date: Date;
-  /** Tax-exclusive sale amount in integer cents (unless `tax.inclusive` is true) */
+  /** Sale amount in integer cents. Tax, if any, is the caller's responsibility
+   *  — compute it with your tax engine (e.g. `@classytic/bd-tax`,
+   *  `@classytic/ca-tax`) and either pre-add it to `amount` + include a
+   *  tax journal item via `record.adjustment`, or post the entry directly
+   *  via `engine.repositories.journalEntries.create`. */
   readonly amount: Cents$1;
   /** Account that receives the money — either Cash or Accounts Receivable */
   readonly receivableAccount: AccountCode;
   /** Revenue account */
   readonly revenueAccount: AccountCode;
-  /** Tax info — optional */
-  readonly tax?: TaxInput;
   /** Free-text label / memo */
   readonly label?: string;
   /** Optional reference number override (otherwise auto-generated) */
@@ -350,14 +332,13 @@ interface RecordSaleInput {
 }
 interface RecordExpenseInput {
   readonly date: Date;
-  /** Tax-exclusive expense amount in cents (unless `tax.inclusive` is true) */
+  /** Expense amount in integer cents. Tax is caller's responsibility — see
+   *  `RecordSaleInput.amount` comment. */
   readonly amount: Cents$1;
   /** Expense category account (e.g. '6010' Rent) */
   readonly expenseAccount: AccountCode;
   /** Where the money came from — either Cash or Accounts Payable */
   readonly paidFromAccount: AccountCode;
-  /** Tax info (recoverable input tax credit) */
-  readonly tax?: TaxInput;
   readonly label?: string;
   readonly reference?: string;
   readonly dimensions?: Record<string, unknown>;
@@ -400,25 +381,49 @@ interface RecordAdjustmentInput {
   readonly dimensions?: Record<string, unknown>;
   readonly journalType?: string;
 }
+interface RecordOpeningBalanceInput {
+  /** Cutover date — typically start of fiscal year. */
+  readonly cutoverDate: Date;
+  /**
+   * Account balances in integer cents, signed:
+   *   - Positive = normal debit balance (assets)
+   *   - Negative = normal credit balance (liabilities, equity)
+   *
+   * Should only contain balance sheet accounts. P&L cumulative effect
+   * belongs in retained earnings (the equity account).
+   */
+  readonly balances: ReadonlyArray<{
+    readonly account: AccountCode;
+    readonly balance: Cents$1;
+  }>;
+  /**
+   * Equity contra account code. Defaults to the country pack's
+   * `retainedEarningsAccountCode` (e.g. '3600' for CA, '3310' for BD).
+   */
+  readonly equityAccount?: AccountCode;
+  readonly label?: string;
+}
 interface RecordAPI {
   /**
-   * Record a sale. Debits cash/AR, credits revenue, splits tax if provided.
+   * Record a sale. Debits cash/AR, credits revenue. Tax lines — if needed —
+   * are the consumer's responsibility (compute via your tax engine and
+   * either add to `amount` or use `record.adjustment`).
    *
    * @example
    * ```typescript
    * await engine.record.sale(orgId, {
    *   date: new Date('2025-04-01'),
-   *   amount: 10000,                    // $100.00 base
+   *   amount: 10000,                    // $100.00 total
    *   receivableAccount: '1001',        // Cash
    *   revenueAccount: '4010',           // Service Revenue
-   *   tax: { code: 'HST', account: '2300' },  // 13% HST Collected
    *   label: 'Invoice #INV-001',
    * });
    * ```
    */
   sale(organizationId: unknown, input: RecordSaleInput, options?: RecordOptions): Promise<unknown>;
   /**
-   * Record an expense. Debits expense, credits cash/AP, splits input tax credit if provided.
+   * Record an expense. Debits expense, credits cash/AP. Tax is caller's
+   * responsibility — see `sale()`.
    */
   expense(organizationId: unknown, input: RecordExpenseInput, options?: RecordOptions): Promise<unknown>;
   /**
@@ -435,6 +440,31 @@ interface RecordAPI {
    * the other verbs. Amounts must balance (debits = credits).
    */
   adjustment(organizationId: unknown, input: RecordAdjustmentInput, options?: RecordOptions): Promise<unknown>;
+  /**
+   * Record opening balances for a cutover migration. Creates a single
+   * multi-line journal entry with each account's balance, contra'd against
+   * an equity account (retained earnings by default).
+   *
+   * Follows the Odoo convention: regular JE, not a special type. Only
+   * balance sheet accounts should be passed — P&L cumulative effect belongs
+   * in the equity contra account.
+   *
+   * Idempotent: uses `_externalId: 'opening-balance:{date}'` so re-calling
+   * with the same cutover date fails cleanly (duplicate key error).
+   *
+   * @example
+   * ```typescript
+   * await engine.record.openingBalance(orgId, {
+   *   cutoverDate: new Date('2025-01-01'),
+   *   balances: [
+   *     { account: '1000', balance: 5000000 },   // $50k cash
+   *     { account: '2620', balance: -1875000 },   // $18.75k AP
+   *     { account: '3600', balance: -3125000 },   // $31.25k RE
+   *   ],
+   * });
+   * ```
+   */
+  openingBalance(organizationId: unknown, input: RecordOpeningBalanceInput, options?: RecordOptions): Promise<unknown>;
 }
 //#endregion
 //#region src/engine.d.ts
@@ -557,44 +587,79 @@ declare class AccountingEngine {
   isValidAccountType(code: string): boolean;
   /** Get account type definition by code */
   getAccountType(code: string): AccountType | undefined;
-  /** Get tax codes for a region */
-  getTaxCodesForRegion(region: string): TaxCode[];
+  /**
+   * Create a pre-configured QueryParser for URL-driven queries against
+   * ledger repositories. Returns a mongokit QueryParser with the correct
+   * schema and pagination limits for the specified model.
+   *
+   * @param model - Which ledger model to parse queries for
+   * @param overrides - Additional QueryParserOptions to merge
+   *
+   * @example
+   * ```typescript
+   * const parser = engine.createQueryParser('journalEntry');
+   * const parsed = parser.parse(req.query);
+   * const result = await engine.repositories.journalEntries.getAll({
+   *   ...parsed,
+   *   filters: { ...parsed.filters, organizationId },
+   * });
+   * ```
+   */
+  createQueryParser(model: 'account' | 'journalEntry' | 'fiscalPeriod' | 'budget' | 'reconciliation' | 'journal', overrides?: Partial<QueryParserOptions>): QueryParser;
   private _buildReports;
 }
 declare function createAccountingEngine(config: AccountingEngineConfig): AccountingEngine;
 //#endregion
-//#region src/utils/repartition-tax.d.ts
-/**
- * Resolves an `accountRole` (e.g. `'collected'`, `'recoverable'`,
- * `'transition'`) into the actual account ObjectId for the consumer's
- * chart of accounts. Implementations typically close over an account
- * cache loaded per organization at engine start.
- */
-type RepartitionAccountResolver = (role: string, taxCode: TaxCode, input: TaxLineInput) => unknown;
-interface RepartitionGeneratorOptions {
-  /** Country pack — provides tax codes and optional resolver. */
-  country: CountryPack;
-  /** Required: resolve role → account id in the consumer's chart. */
-  resolveAccount: RepartitionAccountResolver;
-  /**
-   * Document type — determines which repartition lines apply. A line
-   * with `documentTypes: ['invoice']` is skipped when this is `'refund'`.
-   * Defaults to `'invoice'`.
-   */
-  documentType?: 'invoice' | 'refund' | 'payment';
+//#region src/repositories/reconciliation.repository.d.ts
+interface MatchHookItem {
+  entry: unknown;
+  itemIndex: number;
+  debit: number;
+  credit: number;
+  amountCurrency: number | null;
+  exchangeRate: number | null;
 }
 /**
- * Build a `TaxLineGenerator` that expands each hit `taxCode` into one
- * journal item per repartition line. Taxes without `repartition` fall
- * back to a single-line generator using the direction-implied account.
+ * Context passed to `before:match` and `after:match` hooks.
+ *
+ * - `before:match`: fired after validation but before the matchingNumber is
+ *   stamped and the reconciliation doc is created. Throw to abort.
+ * - `after:match`: fired after the reconciliation doc is persisted. Used by
+ *   fxRealizationPlugin, and can be used by invoice packages to update
+ *   payment state.
  */
-declare function createRepartitionTaxGenerator(options: RepartitionGeneratorOptions): TaxLineGenerator;
+interface MatchHookContext {
+  /** The input that was passed to match(). */
+  input: MatchInput;
+  /** Validated + enriched item snapshots with debit/credit/currency info. */
+  items: MatchHookItem[];
+  /** Shared currency across all items, or null if mixed. */
+  sharedCurrency: string | null;
+  /** The matching number (auto-generated or caller-provided). */
+  matchingNumber: string;
+  /** Totals for the matched set. */
+  debitTotal: number;
+  creditTotal: number;
+  isFullReconcile: boolean;
+  /** The created reconciliation document (only in after:match). */
+  reconciliation?: unknown;
+  session: ClientSession | null;
+}
 /**
- * Helper for packs that want the standard "role → account-type code"
- * mapping without writing their own resolver. Returns the function you
- * stuff into `CountryPackInput.resolveTaxRepartitionAccountCode`.
+ * Context passed to `before:unmatch` and `after:unmatch` hooks.
  */
-declare function defaultResolveTaxRepartitionAccountCode(country: CountryPack): (role: string, tax: TaxCode) => string | undefined;
+interface UnmatchHookContext {
+  matchingNumber: string;
+  /** The reconciliation document being removed. */
+  reconciliation: Record<string, unknown>;
+  /** The items that will be / were unmatched. */
+  items: Array<{
+    entry: unknown;
+    itemIndex: number;
+  }>;
+  organizationId?: unknown;
+  session: ClientSession | null;
+}
 //#endregion
 //#region src/utils/account-helpers.d.ts
 /**
@@ -816,4 +881,4 @@ interface PostingResult {
   idempotencyKeys?: string[];
 }
 //#endregion
-export { type AccountCode, type AccountForeignBalance, type AccountRepository, type AccountSummary, type AccountType, AccountingEngine, type AccountingEngineConfig, AccountingError, type ActorContext, type AgedBalanceOptions, type AgedBalanceParams, type AgedBalanceReport, type AgedBalanceRow, type AgedBucketConfig, type AuditConfig, type BalanceSheetReport, type BudgetVsActualOptions, type BudgetVsActualParams, type BudgetVsActualReport, type BudgetVsActualRow, type BulkCreateInput, type BulkCreateResult, CATEGORIES, CATEGORY_KEYS, CURRENCIES, type CashFlowCategory, type CashFlowReport, type CashFlowSection, type CategoryKey, type Cents, type CountryPack, type CountryPackInput, type CreateLockPluginOptions, type CreditLimitPluginOptions, type Currency, DEFAULT_BUCKETS, type DailyLockPluginOptions, type DateOption, type DateRange, type DimensionBreakdownOptions, type DimensionBreakdownParams, type DimensionBreakdownReport, type DimensionBreakdownRow, type DimensionDefinition, type EntryState, Errors, type ExportField, type ExportFieldMap, type FieldError, type FiscalLockPluginOptions, type FiscalPeriodSummary, type FlatJournalRow, type FxRealizationPluginOptions, type GeneralLedgerAccount, type GeneralLedgerReport, type IncomeStatementReport, type IntrospectAPI, JOURNAL_CODES, JOURNAL_TYPES, type JournalEntryRepository, type JournalItem, type JournalItemRef, type JournalRepository, type JournalSchemaOptions, type JournalTemplate, type JournalType, type LedgerEntry, type LedgerModels, type LedgerPaginationConfig, type LedgerRepositories, type LedgerRepositoryPlugins, type LockAccountSelector, type LockHit, type LockResolver, type LockResolverContext, type Logger, type MainType, type MatchInput, type ModelNames, Money, type MultiCurrencyConfig, type MultiTenantConfig, type NormalBalance, type OpenItem, type PartnerLedgerLine, type PartnerLedgerOptions, type PartnerLedgerParams, type PartnerLedgerReport, type PeriodResolverOptions, type PopulatedJournalEntry, type PostOptions, type PostingContract, type PostingResult, type ReconciliationRepository, type RecordAPI, type RecordAdjustmentInput, type RecordAdjustmentLine, type RecordExpenseInput, type RecordOptions, type RecordPaymentInput, type RecordSaleInput, type RecordTransferInput, type RepartitionAccountResolver, type RepartitionGeneratorOptions, type ReportAccount, type ReportCategory, type ReportDescriptor, type ReportGroup, type ResolvedModelNames, type RevaluationOptions, type RevaluationParams, type RevaluationRate, type RevaluationReport, type RevaluationResult, type ReverseOptions, type ReverseResult, type SchemaOptions, type SeedOptions, type SeedResult, type Cents$1 as SemanticCents, type SessionResult, type StatementType, type StrictnessConfig, type SubledgerJournalItem, type SubledgerPostingInput, type TaxCode, type TaxCodesByRegion, type TaxDetail, type TaxExigibility, type TaxInput, type TaxLockPluginOptions, type TaxMetadata, type TaxRepartitionLine, type TaxReport, type TaxReportLine, type TaxReportTemplate, type TaxReturnSummary, type TotalAccountOp, type TrialBalanceReport, type TrialBalanceRow, type WatermarkResolverOptions, acquireSession, add, allocate, buildAccountTypeMap, buildDimensionFields, buildDimensionIndexes, buildItemFilters, buildRevaluationEntry, calculateTotal, closeFiscalPeriod, computeEndingBalance, computeRevaluation, createAccountingEngine, createLockPlugin, createModels, createRepartitionTaxGenerator, createRepositories, creditLimitPlugin, dailyLockPlugin, defaultLogger, defaultResolveTaxRepartitionAccountCode, defineCountryPack, doubleEntryPlugin, exportToCsv, finalizeSession, fiscalLockPlugin, flattenJournalEntries, format, formatPlain, fromDecimal, fxRealizationPlugin, generateAgedBalance, generateBalanceSheet, generateBudgetVsActual, generateCashFlow, generateDimensionBreakdown, generateGeneralLedger, generateIncomeStatement, generatePartnerLedger, generateRevaluation, generateTrialBalance, getCurrency, getCustomJournalTypes, getDateRange, getFiscalYearStart, getJournalType, getJournalTypeCodes, getMinorUnit, getNormalBalance, idempotencyPlugin, isBalanceSheet, isIncomeStatement, isValidCategory, isValidCurrency, isValidJournalType, isVirtualTaxAccount, multiply, parseCents, percentage, periodResolver, quickbooksFieldMap, registerJournalType, reopenFiscalPeriod, resolveModelNames, splitTaxExclusive, splitTaxInclusive, subtract, taxLockPlugin, toDecimal, universalFieldMap, watermarkResolver };
+export { type AccountCode, type AccountForeignBalance, type AccountRepository, type AccountSummary, type AccountType, AccountingEngine, type AccountingEngineConfig, AccountingError, type ActorContext, type AgedBalanceOptions, type AgedBalanceParams, type AgedBalanceReport, type AgedBalanceRow, type AgedBucketConfig, type AuditConfig, type BalanceSheetReport, type BudgetVsActualOptions, type BudgetVsActualParams, type BudgetVsActualReport, type BudgetVsActualRow, type BulkCreateInput, type BulkCreateResult, CATEGORIES, CATEGORY_KEYS, CURRENCIES, type CashFlowCategory, type CashFlowReport, type CashFlowSection, type CategoryKey, type Cents, type CountryPack, type CountryPackInput, type CreateLockPluginOptions, type CreditLimitPluginOptions, type Currency, DEFAULT_BUCKETS, type DailyLockPluginOptions, type DateOption, type DateRange, type DimensionBreakdownOptions, type DimensionBreakdownParams, type DimensionBreakdownReport, type DimensionBreakdownRow, type DimensionDefinition, type EntryState, Errors, type ExportField, type ExportFieldMap, type FieldError, type FiscalLockPluginOptions, type FiscalPeriodSummary, type FlatJournalRow, type FxRealizationPluginOptions, type GeneralLedgerAccount, type GeneralLedgerReport, type IncomeStatementReport, type IntrospectAPI, JOURNAL_CODES, JOURNAL_TYPES, type JournalEntryRepository, type JournalItem, type JournalItemRef, type JournalRepository, type JournalSchemaOptions, type JournalTemplate, type JournalType, type LedgerEntry, type LedgerModels, type LedgerPaginationConfig, type LedgerRepositories, type LedgerRepositoryPlugins, type LockAccountSelector, type LockHit, type LockResolver, type LockResolverContext, type Logger, type MainType, type MatchHookContext, type MatchHookItem, type MatchInput, type ModelNames, Money, type MultiCurrencyConfig, type MultiTenantConfig, type NormalBalance, type OpenItem, type PartnerLedgerLine, type PartnerLedgerOptions, type PartnerLedgerParams, type PartnerLedgerReport, type PeriodResolverOptions, type PopulatedJournalEntry, type PostOptions, type PostingContract, type PostingResult, type ReconciliationRepository, type RecordAPI, type RecordAdjustmentInput, type RecordAdjustmentLine, type RecordExpenseInput, type RecordOptions, type RecordPaymentInput, type RecordSaleInput, type RecordTransferInput, type ReportAccount, type ReportCategory, type ReportDescriptor, type ReportGroup, type ResolvedModelNames, type RevaluationOptions, type RevaluationParams, type RevaluationRate, type RevaluationReport, type RevaluationResult, type ReverseOptions, type ReverseResult, type SchemaOptions, type SeedOptions, type SeedResult, type Cents$1 as SemanticCents, type SessionResult, type StatementType, type StrictnessConfig, type SubledgerJournalItem, type SubledgerPostingInput, type TaxDetail, type TaxMetadata, type TotalAccountOp, type TrialBalanceReport, type TrialBalanceRow, type UnmatchHookContext, type WatermarkResolverOptions, acquireSession, add, allocate, buildAccountTypeMap, buildDimensionFields, buildDimensionIndexes, buildItemFilters, buildRevaluationEntry, calculateTotal, closeFiscalPeriod, computeEndingBalance, computeRevaluation, createAccountingEngine, createLockPlugin, createModels, createRepositories, creditLimitPlugin, dailyLockPlugin, defaultLogger, defineCountryPack, doubleEntryPlugin, exportToCsv, finalizeSession, fiscalLockPlugin, flattenJournalEntries, format, formatPlain, fromDecimal, fxRealizationPlugin, generateAgedBalance, generateBalanceSheet, generateBudgetVsActual, generateCashFlow, generateDimensionBreakdown, generateGeneralLedger, generateIncomeStatement, generatePartnerLedger, generateRevaluation, generateTrialBalance, getCurrency, getCustomJournalTypes, getDateRange, getFiscalYearStart, getJournalType, getJournalTypeCodes, getMinorUnit, getNormalBalance, idempotencyPlugin, isBalanceSheet, isIncomeStatement, isValidCategory, isValidCurrency, isValidJournalType, isVirtualTaxAccount, multiply, parseCents, percentage, periodResolver, quickbooksFieldMap, registerJournalType, reopenFiscalPeriod, resolveModelNames, splitTaxExclusive, splitTaxInclusive, subtract, toDecimal, universalFieldMap, watermarkResolver };