@classytic/ledger 0.8.0 → 0.9.1

package/dist/events/index.d.mts

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

package/dist/events/index.mjs

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

package/dist/exports/index.d.mts

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

package/dist/exports/index.mjs

@@ -1,2 +1,2 @@
-import { a as exportToCsv, c as getHeaders, d as serializeCsv, i as quickbooksFieldMap, l as buildCsv, n as flattenJournalEntry, o as extractAllRows, r as universalFieldMap, s as extractRow, t as flattenJournalEntries, u as escapeCell } from "../exports-B3whucXe.mjs";
+import { a as exportToCsv, c as getHeaders, d as serializeCsv, i as quickbooksFieldMap, l as buildCsv, n as flattenJournalEntry, o as extractAllRows, r as universalFieldMap, s as extractRow, t as flattenJournalEntries, u as escapeCell } from "../exports-C30yRapf.mjs";
 export { buildCsv, escapeCell, exportToCsv, extractAllRows, extractRow, flattenJournalEntries, flattenJournalEntry, getHeaders, quickbooksFieldMap, serializeCsv, universalFieldMap };

package/dist/{fx-realization.plugin-DDVK-oYO.mjs → fx-realization.plugin-Bxlb8cIx.mjs}

@@ -1,4 +1,4 @@
-import { n as Errors, t as AccountingError } from "./errors-CSDQPNyt.mjs";
+import { a as IdempotencyConflictError, i as Errors, t as AccountingError } from "./errors-BI5k4iak.mjs";
 //#region src/plugins/double-entry.plugin.ts
 function doubleEntryPlugin(options = {}) {
 	const { onlyOnPost = true, JournalEntryModel, AccountModel, orgField } = options;
@@ -166,7 +166,7 @@ function idempotencyPlugin(options) {
 				const query = { idempotencyKey: data.idempotencyKey };
 				if (orgField && data[orgField]) query[orgField] = data[orgField];
 				const existing = await JournalEntryModel.findOne(query).select("_id").session(context.session ?? null).lean();
-				if (existing) throw Errors.conflict(`Duplicate idempotency key: "${data.idempotencyKey}". Existing entry: ${existing._id}`);
+				if (existing) throw new IdempotencyConflictError(data.idempotencyKey, existing._id);
 			});
 			repo.on("before:createMany", async (context) => {
 				const docs = context.dataArray;

package/dist/{index-RNZsX0Yo.d.mts → index-08IpHhrU.d.mts}

@@ -1,4 +1,4 @@
-import { t as AccountType } from "./core-MpgjCqK0.mjs";
+import { t as AccountType } from "./core-DwjkrRkJ.mjs";
 
 //#region src/country/index.d.ts
 /**

package/dist/{index-BSsvrf3m.d.mts → index-ClLwzNRF.d.mts}

@@ -1,4 +1,4 @@
-import * as _classytic_mongokit0 from "@classytic/mongokit";
+import * as _$_classytic_mongokit0 from "@classytic/mongokit";
 import { Repository, RepositoryContext, RepositoryInstance } from "@classytic/mongokit";
 import { ClientSession, Model } from "mongoose";
 
@@ -427,7 +427,7 @@ interface FiscalLockPluginOptions {
 }
 declare function fiscalLockPlugin(options: FiscalLockPluginOptions): {
   name: string;
-  apply(repo: _classytic_mongokit0.RepositoryInstance): void;
+  apply(repo: _$_classytic_mongokit0.RepositoryInstance): void;
 };
 interface DailyLockPluginOptions {
   /**
@@ -441,7 +441,7 @@ interface DailyLockPluginOptions {
 }
 declare function dailyLockPlugin(options: DailyLockPluginOptions): {
   name: string;
-  apply(repo: _classytic_mongokit0.RepositoryInstance): void;
+  apply(repo: _$_classytic_mongokit0.RepositoryInstance): void;
 };
 //#endregion
 //#region src/plugins/lock/watermark-resolver.d.ts

package/dist/index-Dih0lM65.d.mts

@@ -0,0 +1,169 @@
+//#region src/bridges/exchange-rate.bridge.d.ts
+/**
+ * Exchange Rate Bridge — host-injected rate sourcing.
+ *
+ * The ledger never hardcodes where exchange rates come from. The host
+ * provides an implementation at engine init time:
+ *
+ *   - ManualRateBridge:        user-entered Currency Exchange records
+ *   - BangladeshBankRateBridge: BB daily rate API
+ *   - FixedRateBridge:         hardcoded for testing
+ *   - ProviderRateBridge:      third-party rate API (Wise, Open Exchange Rates)
+ *
+ * When no bridge is provided, the caller must supply the exchange rate
+ * explicitly on every journal item (the existing behavior). The bridge
+ * is a convenience for hosts that want automatic rate lookup.
+ *
+ * @example
+ * ```ts
+ * const engine = createAccountingEngine({
+ *   country: bdPack,
+ *   currency: 'BDT',
+ *   multiCurrency: { enabled: true, currencies: ['USD', 'EUR'] },
+ *   bridges: {
+ *     exchangeRate: {
+ *       async getRate(from, to, date) {
+ *         const row = await CurrencyExchange.findOne({ from, to, date });
+ *         if (!row) throw new Error(`No rate for ${from}→${to} on ${date}`);
+ *         return row.rate;
+ *       },
+ *     },
+ *   },
+ * });
+ * ```
+ */
+interface ExchangeRateBridge {
+  /**
+   * Get the exchange rate for converting `fromCurrency` to `toCurrency`
+   * on a given date.
+   *
+   * @param fromCurrency ISO 4217 code (e.g., 'USD')
+   * @param toCurrency   ISO 4217 code (e.g., 'BDT')
+   * @param date         Transaction date (rate as of this date)
+   * @param purpose      Optional: 'buying' or 'selling' rate (some central
+   *                     banks publish separate rates)
+   * @returns The rate as a positive decimal. Example: 120.50 means
+   *          1 USD = 120.50 BDT.
+   * @throws When no rate is available for the requested pair + date.
+   */
+  getRate(fromCurrency: string, toCurrency: string, date: Date, purpose?: 'buying' | 'selling'): Promise<number>;
+  /**
+   * Optional batch lookup — avoids N+1 when posting multi-line entries
+   * with different currencies. Host implementations that cache rates
+   * benefit from a single DB round-trip.
+   *
+   * When absent, the engine falls back to calling `getRate()` per item.
+   */
+  getRates?(requests: Array<{
+    fromCurrency: string;
+    toCurrency: string;
+    date: Date;
+    purpose?: 'buying' | 'selling';
+  }>): Promise<Map<string, number>>;
+}
+//#endregion
+//#region src/bridges/notification.bridge.d.ts
+/**
+ * NotificationBridge — host-implemented delivery for ledger-originated alerts.
+ *
+ * The ledger generates operational alerts that hosts may want to route to
+ * email, Slack, in-app notifications, or an audit/compliance system:
+ *
+ *   - `periodLocked` — a fiscal period was locked (audit sign-off)
+ *   - `periodUnlocked` — a locked period was re-opened (requires elevated role)
+ *   - `entryReversed` — a posted entry was reversed (accounting correction)
+ *   - `reconciliationMismatch` — match debit/credit totals differ (FX gain/loss)
+ *
+ * This is deliberately thin — richer integrations should subscribe to the
+ * EventTransport (§11-14) and route via their own notification stack.
+ * NotificationBridge exists for hosts that want a direct callback without
+ * owning an event bus.
+ *
+ * All methods are optional. Skip the bridge entirely if the host uses events.
+ */
+interface NotificationBridgeContext {
+  organizationId?: unknown;
+  actorId?: unknown;
+  correlationId?: string;
+}
+interface PeriodLockedNotification {
+  periodId: unknown;
+  startDate: Date;
+  endDate: Date;
+  lockedBy?: unknown;
+}
+interface EntryReversedNotification {
+  originalEntryId: unknown;
+  reversalEntryId: unknown;
+  reversalDate: Date;
+  reversedBy?: unknown;
+  reason?: string;
+}
+interface ReconciliationMismatchNotification {
+  matchingNumber: string;
+  account: unknown;
+  debitTotal: number;
+  creditTotal: number;
+  difference: number;
+  currency: string | null;
+}
+interface NotificationBridge {
+  onPeriodLocked?(payload: PeriodLockedNotification, ctx: NotificationBridgeContext): Promise<void>;
+  onPeriodUnlocked?(payload: PeriodLockedNotification, ctx: NotificationBridgeContext): Promise<void>;
+  onEntryReversed?(payload: EntryReversedNotification, ctx: NotificationBridgeContext): Promise<void>;
+  onReconciliationMismatch?(payload: ReconciliationMismatchNotification, ctx: NotificationBridgeContext): Promise<void>;
+}
+//#endregion
+//#region src/bridges/source.bridge.d.ts
+/**
+ * SourceBridge — host-implemented resolver for polymorphic external references.
+ *
+ * Ledger journal entries commonly carry a `reference`/`externalRef` pointing
+ * at a source document that lives outside the ledger package — an Invoice,
+ * Payment, Payroll Run, Stripe Charge, ERP voucher, etc. Storing these as
+ * opaque `String + sourceModel` (per PACKAGE_RULES §7) keeps the ledger
+ * transport-agnostic: the same schema works whether the source lives in the
+ * same Mongo, a different Mongo, Postgres, or an external REST API.
+ *
+ * Hosts implement `SourceBridge` to hydrate those refs when building
+ * enriched views (partner ledger with invoice details, audit trail with
+ * payment metadata, reconciliation UI with source documents, etc.).
+ *
+ * All methods are optional. Features that need resolution degrade gracefully
+ * when a bridge is not provided.
+ */
+interface SourceRef {
+  sourceId: string;
+  sourceModel: string;
+}
+interface SourceBridgeContext {
+  organizationId?: unknown;
+  actorId?: unknown;
+  [key: string]: unknown;
+}
+interface SourceBridge {
+  /**
+   * Resolve a single external reference.
+   *
+   * Return `null` when the source cannot be found (deleted, permission
+   * denied, wrong model). Do not throw for missing sources — callers
+   * expect `null` for graceful degradation.
+   */
+  resolve?(sourceId: string, sourceModel: string, ctx: SourceBridgeContext): Promise<unknown | null>;
+  /**
+   * Batch resolver — avoids N+1 round-trips when enriching a list.
+   * Key the returned map by `sourceId`. Missing sources may be omitted or
+   * mapped to `null` at the implementer's discretion.
+   */
+  resolveMany?(refs: ReadonlyArray<SourceRef>, ctx: SourceBridgeContext): Promise<Map<string, unknown>>;
+}
+//#endregion
+//#region src/bridges/index.d.ts
+/** Collected bridges exposed as `engine.bridges`. All optional per PACKAGE_RULES §23. */
+interface LedgerBridges {
+  source?: SourceBridge;
+  notification?: NotificationBridge;
+  exchangeRate?: ExchangeRateBridge;
+}
+//#endregion
+export { EntryReversedNotification as a, PeriodLockedNotification as c, SourceRef as i, ReconciliationMismatchNotification as l, SourceBridge as n, NotificationBridge as o, SourceBridgeContext as r, NotificationBridgeContext as s, LedgerBridges as t, ExchangeRateBridge as u };

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-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 { 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, u as ExchangeRateBridge } from "./index-Dih0lM65.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-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 { $ 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-ClLwzNRF.mjs";
+import { PaginationConfig, PluginFunction, PluginType, QueryParser, QueryParserOptions, Repository } from "@classytic/mongokit";
 import { ClientSession, Connection, Model } from "mongoose";
 
+//#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 {
@@ -500,8 +693,33 @@ 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);
+  /**
+   * Explicitly sync indexes on all managed models.
+   * Call this in deploy-time scripts — NOT on every boot.
+   * See PACKAGE_RULES section 32.
+   */
+  syncIndexes(): Promise<void>;
   /**
    * Pre-built reports bound to the engine's owned models.
    * Lazy-initialized on first access.
@@ -752,56 +970,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.
@@ -881,4 +1049,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 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 };
+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 ExchangeRateBridge, 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 };