@classytic/ledger 0.7.0 → 0.9.0

package/dist/index.d.mts

@@ -1,13 +1,128 @@
-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 { i as defineCountryPack, n as CountryPackInput, r as JournalTemplate, t as CountryPack } from "./index-BX8miYdu.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 { 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";
+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-DwjkrRkJ.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-DUpWwFt1.mjs";
+import { i as defineCountryPack, n as CountryPackInput, r as JournalTemplate, t as CountryPack } from "./index-08IpHhrU.mjs";
+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";
+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-J-XIbXH-.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 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-DTc8kzTD.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-Bl0_ak5w.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-DyNm5bFu.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-Db0n_6Z8.mjs";
+import { PaginationConfig, PluginFunction, PluginType, QueryParser, QueryParserOptions, Repository } from "@classytic/mongokit";
 import { ClientSession, Connection, Model } from "mongoose";
-import { PaginationConfig, PluginType, Repository } from "@classytic/mongokit";
 
+//#region src/plugins/immutable-guard.plugin.d.ts
+interface ImmutableGuardOptions {
+  /** The JournalEntry Mongoose model, for looking up current state on update. */
+  JournalEntryModel: Model<unknown>;
+  /** Multi-tenant org field name (if enabled). */
+  orgField?: string;
+}
+/**
+ * Returns a mongokit plugin function. Install only when
+ * `config.strictness.immutable === true`.
+ */
+declare function immutableGuardPlugin(options: ImmutableGuardOptions): PluginFunction;
+//#endregion
+//#region src/utils/errors.d.ts
+/**
+ * Typed error for the accounting package.
+ * Carries HTTP status + machine-readable code + structured field errors.
+ *
+ * The `fields` array lets AI agents and API clients pinpoint exactly
+ * what failed in a multi-field validation:
+ *
+ *   throw Errors.validationWithFields('Journal entry invalid', [
+ *     { path: 'journalItems.2.account', issue: 'account does not exist', value: '...' },
+ *     { path: 'journalItems', issue: 'debits must equal credits', value: { debit: 500, credit: 450 } },
+ *   ]);
+ */
+/** A single field-level validation error. */
+interface FieldError {
+  /** Dot-notation path to the invalid field (e.g. `journalItems.2.account`) */
+  readonly path: string;
+  /** Human-readable description of what's wrong */
+  readonly issue: string;
+  /** The offending value (optional — omit for sensitive data) */
+  readonly value?: unknown;
+}
+declare class AccountingError extends Error {
+  readonly status: number;
+  readonly code: string;
+  readonly fields?: ReadonlyArray<FieldError>;
+  constructor(message: string, status?: number, code?: string, fields?: ReadonlyArray<FieldError>);
+  /** Serialize to a plain object for API responses and logs. */
+  toJSON(): {
+    name: string;
+    message: string;
+    status: number;
+    code: string;
+    fields?: ReadonlyArray<FieldError>;
+  };
+}
+interface ErrorsFactories {
+  validation: (msg: string, fields?: ReadonlyArray<FieldError>) => AccountingError;
+  notFound: (msg: string, fields?: ReadonlyArray<FieldError>) => AccountingError;
+  conflict: (msg: string, fields?: ReadonlyArray<FieldError>) => AccountingError;
+  immutable: (msg: string, fields?: ReadonlyArray<FieldError>) => AccountingError;
+  locked: (scope: string, msg: string, fields?: ReadonlyArray<FieldError>) => AccountingError;
+}
+declare const Errors: ErrorsFactories;
+/**
+ * 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.
+ */
+declare class IdempotencyConflictError extends AccountingError {
+  readonly idempotencyKey: string;
+  readonly existingId: unknown;
+  constructor(idempotencyKey: string, existingId: unknown, message?: string);
+}
+/**
+ * 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.
+ */
+declare class DuplicateReferenceError extends AccountingError {
+  readonly referenceNumber: string;
+  constructor(referenceNumber: string, message?: string);
+}
+/**
+ * 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.
+ */
+declare class ConcurrencyError extends AccountingError {
+  readonly resource: string;
+  readonly resourceId: unknown;
+  constructor(resource: string, resourceId: unknown, message?: string);
+}
+/**
+ * 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.
+ */
+declare class ImmutableViolationError extends AccountingError {
+  readonly entryId: unknown;
+  constructor(entryId: unknown, message?: string, fields?: ReadonlyArray<FieldError>);
+}
+/**
+ * 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.
+ */
+declare function classifyDuplicateKey(err: unknown): {
+  indexName: string;
+  keyPattern?: Record<string, unknown>;
+} | null;
+//#endregion
 //#region src/types/engine.d.ts
 /** Mongokit plugins to install per repository (composes with engine built-ins). */
 interface LedgerRepositoryPlugins {
@@ -33,6 +148,22 @@ interface MultiTenantConfig {
   orgField: string;
   /** Mongoose model name the org field references (e.g., 'Business', 'Organization') */
   orgRef: string;
+  /**
+   * Enable mongokit's `multiTenantPlugin` on every ledger repository. The plugin
+   * injects the tenant filter at POLICY priority (before cache/audit) whenever
+   * `ctx.organizationId` is present on a call. When `false` (default), only
+   * manual `orgField` filters inside domain verbs enforce scoping.
+   *
+   * Recommended: `true` for new hosts. Keep `false` if your app has not yet
+   * migrated to context-based scoping.
+   */
+  plugin?: boolean;
+  /**
+   * Fail closed when `ctx.organizationId` is missing on a plugin-scoped call.
+   * Only applies when `plugin: true`. Default: `false` (skip injection when
+   * context is empty — matches historical ledger behavior).
+   */
+  required?: boolean;
 }
 /** Options passed to schema factory functions */
 interface SchemaOptions {
@@ -148,12 +279,70 @@ interface AccountingEngineConfig {
   audit?: AuditConfig;
   /** Enable built-in idempotency key field on journal entries */
   idempotency?: boolean;
+  /**
+   * TTL in seconds for idempotency records — stale replay keys auto-expire
+   * via a partial TTL index so they don't collide with legitimate reuse
+   * after the window closes. Default: 86400 (24h). Matches Stripe / Saleor
+   * convention. Only applies when `idempotency: true`.
+   */
+  idempotencyTtlSeconds?: number;
+  /**
+   * Automatically call `Model.syncIndexes()` on every managed model right
+   * after the engine boots. Ensures new partial/TTL indexes (0.9.0+) are
+   * present in MongoDB before the first write. Default: `false` — hosts
+   * that run migrations themselves should leave this off.
+   */
+  syncIndexes?: boolean;
   /** Strictness rules for the ledger */
   strictness?: StrictnessConfig;
   /** Mongokit plugins to install per repository. */
   plugins?: LedgerRepositoryPlugins;
   /** Pagination caps per repository. */
   pagination?: LedgerPaginationConfig;
+  /**
+   * Mongoose type for the multi-tenant field on all ledger schemas.
+   *
+   * - `'string'` (default, back-compat): stores tenant IDs as strings.
+   *   Accepts any external auth system (UUIDs, slugs, external identifiers).
+   * - `'objectId'`: stores tenant IDs as native MongoDB ObjectId with a
+   *   Mongoose ref to the organization collection. Enables `$lookup` and
+   *   `.populate()` against Better Auth's `organization` collection.
+   *
+   * New hosts wiring Better Auth should pass `'objectId'`. See
+   * PACKAGE_RULES §9.1 and §9.2.
+   *
+   * Note: this field is plumbed into `multiTenantPlugin` when
+   * `multiTenant.plugin: true`. Schema-level type switching is applied
+   * by the models factory when it supports dynamic type declaration.
+   */
+  tenantFieldType?: 'objectId' | 'string';
+  /**
+   * Optional event transport — structurally identical to `@classytic/arc`'s
+   * `EventTransport`. Drop in any arc transport (Memory, Redis, Kafka, BullMQ)
+   * or provide a custom one. When omitted, the engine uses an in-process bus
+   * (`InProcessLedgerBus`) that is NOT suitable for multi-instance deployments.
+   */
+  eventTransport?: EventTransport;
+  /**
+   * Optional host-owned outbox store — structurally identical to
+   * `@classytic/arc`'s `OutboxStore`. When provided, domain events are
+   * persisted via `outbox.save(event, { session })` inside the same
+   * mongoose session as the ledger write, giving at-least-once delivery
+   * guarantees. A host-side relay worker calls `store.claimPending` +
+   * `transport.publish` + `store.acknowledge` independently.
+   *
+   * Package-owned durable outbox storage is an anti-pattern per
+   * PACKAGE_RULES §5.5. Ledger does NOT ship a concrete store — the
+   * host picks `MongoOutboxStore` (arc), a SQL store, a Redis store,
+   * etc. See `src/events/outbox-store.ts` for the interface contract.
+   */
+  outboxStore?: OutboxStore;
+  /**
+   * Host-provided bridges for external integrations (source resolution,
+   * notifications). All bridges and all methods are optional — features
+   * degrade gracefully when a bridge is missing.
+   */
+  bridges?: LedgerBridges;
 }
 //#endregion
 //#region src/models/factory.d.ts
@@ -185,16 +374,20 @@ interface LedgerRepositories {
   reconciliations: ReconciliationRepository<unknown>;
   journals: JournalRepository<unknown>;
 }
+/**
+ * Extra wiring context passed into wireXxxMethods so domain verbs can emit
+ * events and reach out through host-provided bridges. Always optional so
+ * consumers without events/bridges see no behavioral change.
+ */
+interface LedgerRepositoryIntegrations {
+  events?: EventTransport;
+  bridges?: LedgerBridges;
+  outboxStore?: OutboxStore;
+}
 /**
  * Build all ledger repositories with plugins + domain methods pre-wired.
- *
- * - `accounts` — has seedAccounts(), bulkCreate()
- * - `journalEntries` — has post(), unpost(), reverse(), duplicate() + double-entry + fiscal-lock (+ idempotency if enabled)
- * - `fiscalPeriods` — plain CRUD
- * - `budgets` — plain CRUD
- * - `reconciliations` — has reconcile(), unreconcile(), getUnreconciled()
  */
-declare function createRepositories(models: LedgerModels, config: AccountingEngineConfig, plugins?: LedgerRepositoryPlugins, pagination?: LedgerPaginationConfig): LedgerRepositories;
+declare function createRepositories(models: LedgerModels, config: AccountingEngineConfig, plugins?: LedgerRepositoryPlugins, pagination?: LedgerPaginationConfig, integrations?: LedgerRepositoryIntegrations): LedgerRepositories;
 //#endregion
 //#region src/semantic/introspect.d.ts
 interface AccountSummary {
@@ -381,6 +574,28 @@ 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. Tax lines — if needed —
@@ -418,6 +633,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
@@ -453,6 +693,25 @@ declare class AccountingEngine {
   readonly repositories: LedgerRepositories;
   readonly record: RecordAPI;
   readonly introspect: IntrospectAPI;
+  /**
+   * Event transport — structurally matches `@classytic/arc`'s `EventTransport`.
+   * When the host does not inject one, the engine instantiates
+   * `InProcessLedgerBus` (suitable for single-instance deployments only).
+   * Subscribe with glob patterns: `ledger:entry.*`, `ledger:reconciliation.*`, `*`.
+   */
+  readonly events: EventTransport;
+  /**
+   * Host-provided bridges. Empty object when none supplied. Callers should
+   * optional-chain every method (`engine.bridges.source?.resolve?.(...)`).
+   */
+  readonly bridges: LedgerBridges;
+  /**
+   * Host-provided outbox store for durable event delivery (0.9.0). When
+   * present, every domain event is persisted to the outbox in the same
+   * mongoose session as the ledger write before the transport publish.
+   * Undefined when the host opts out of durable delivery.
+   */
+  readonly outboxStore: OutboxStore | undefined;
   private _reports?;
   constructor(config: AccountingEngineConfig);
   /**
@@ -540,10 +799,80 @@ declare class AccountingEngine {
   isValidAccountType(code: string): boolean;
   /** Get account type definition by code */
   getAccountType(code: string): AccountType | undefined;
+  /**
+   * 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/repositories/reconciliation.repository.d.ts
+interface MatchHookItem {
+  entry: unknown;
+  itemIndex: number;
+  debit: number;
+  credit: number;
+  amountCurrency: number | null;
+  exchangeRate: number | null;
+}
+/**
+ * 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.
+ */
+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;
+}
+/**
+ * Context passed to `before:unmatch` and `after:unmatch` hooks.
+ */
+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
 /**
  * Check if an account type is a virtual tax sub-account.
@@ -635,56 +964,6 @@ declare function buildDimensionIndexes(dimensions: DimensionDefinition[], orgFie
   options?: Record<string, unknown>;
 }>;
 //#endregion
-//#region src/utils/errors.d.ts
-/**
- * Typed error for the accounting package.
- * Carries HTTP status + machine-readable code + structured field errors.
- *
- * The `fields` array lets AI agents and API clients pinpoint exactly
- * what failed in a multi-field validation:
- *
- *   throw Errors.validationWithFields('Journal entry invalid', [
- *     { path: 'journalItems.2.account', issue: 'account does not exist', value: '...' },
- *     { path: 'journalItems', issue: 'debits must equal credits', value: { debit: 500, credit: 450 } },
- *   ]);
- */
-/** A single field-level validation error. */
-interface FieldError {
-  /** Dot-notation path to the invalid field (e.g. `journalItems.2.account`) */
-  readonly path: string;
-  /** Human-readable description of what's wrong */
-  readonly issue: string;
-  /** The offending value (optional — omit for sensitive data) */
-  readonly value?: unknown;
-}
-declare class AccountingError extends Error {
-  readonly status: number;
-  readonly code: string;
-  readonly fields?: ReadonlyArray<FieldError>;
-  constructor(message: string, status?: number, code?: string, fields?: ReadonlyArray<FieldError>);
-  /** Serialize to a plain object for API responses and logs. */
-  toJSON(): {
-    name: string;
-    message: string;
-    status: number;
-    code: string;
-    fields?: ReadonlyArray<FieldError>;
-  };
-}
-/** Convenience factory functions. */
-declare const Errors: {
-  readonly validation: (msg: string, fields?: ReadonlyArray<FieldError>) => AccountingError;
-  readonly notFound: (msg: string, fields?: ReadonlyArray<FieldError>) => AccountingError;
-  readonly conflict: (msg: string, fields?: ReadonlyArray<FieldError>) => AccountingError;
-  readonly immutable: (msg: string, fields?: ReadonlyArray<FieldError>) => AccountingError;
-  /**
-   * Period/scope lock violation. Replaces the old `fiscal` factory — use the
-   * `scope` argument to distinguish fiscal / tax / daily / bank / etc. The
-   * resulting error code is `PERIOD_LOCKED_{SCOPE}` (e.g. `PERIOD_LOCKED_FISCAL`).
-   */
-  readonly locked: (scope: string, msg: string, fields?: ReadonlyArray<FieldError>) => AccountingError;
-};
-//#endregion
 //#region src/utils/filter-builder.d.ts
 /**
  * Filter Builder — Sanitizes user-supplied dimension filters for aggregation pipelines.
@@ -764,4 +1043,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 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 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 };
+export { type AccountBulkCreatedPayload, type AccountCode, type AccountForeignBalance, type AccountRepository, type AccountSeededPayload, 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, ConcurrencyError, 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 DomainEvent, DuplicateReferenceError, type EntryArchivedPayload, type EntryCreatedPayload, type EntryDuplicatedPayload, type EntryPostedPayload, type EntryReversedNotification, type EntryReversedPayload, type EntryState, type EntryUnpostedPayload, Errors, type EventContext, type EventHandler, type EventLogger, type EventTransport, type ExportField, type ExportFieldMap, type FieldError, type FiscalLockPluginOptions, type FiscalPeriodSummary, type FlatJournalRow, type FxRealizationPluginOptions, type GeneralLedgerAccount, type GeneralLedgerReport, IdempotencyConflictError, type ImmutableGuardOptions, ImmutableViolationError, InProcessLedgerBus, type InProcessLedgerBusOptions, type IncomeStatementReport, type IntrospectAPI, JOURNAL_CODES, JOURNAL_TYPES, type JournalEntryRepository, type JournalItem, type JournalItemRef, type JournalRepository, type JournalSchemaOptions, type JournalSeededPayload, type JournalTemplate, type JournalType, LEDGER_EVENTS, type LedgerBridges, type LedgerEntry, type LedgerEventName, 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 NotificationBridge, type NotificationBridgeContext, type OpenItem, type OutboxAcknowledgeOptions, type OutboxClaimOptions, type OutboxErrorInfo, type OutboxFailOptions, OutboxOwnershipError, type OutboxStore, type OutboxWriteOptions, type PartnerLedgerLine, type PartnerLedgerOptions, type PartnerLedgerParams, type PartnerLedgerReport, type PeriodLockedNotification, type PeriodResolverOptions, type PopulatedJournalEntry, type PostOptions, type PostingContract, type PostingResult, type PublishManyResult, type ReconciliationMatchedPayload, type ReconciliationMismatchNotification, type ReconciliationRepository, type ReconciliationUnmatchedPayload, 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 SourceBridge, type SourceBridgeContext, type SourceRef, 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, classifyDuplicateKey, closeFiscalPeriod, computeEndingBalance, computeRevaluation, createAccountingEngine, createEvent, 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, immutableGuardPlugin, isBalanceSheet, isIncomeStatement, isValidCategory, isValidCurrency, isValidJournalType, isVirtualTaxAccount, multiply, parseCents, percentage, periodResolver, quickbooksFieldMap, registerJournalType, reopenFiscalPeriod, resolveModelNames, splitTaxExclusive, splitTaxInclusive, subtract, toDecimal, universalFieldMap, watermarkResolver };