@classytic/ledger 0.12.2 → 0.12.3

package/README.md

@@ -121,6 +121,38 @@ const engine = createAccountingEngine({
 });
 ```
 
+### Source provenance — `JournalEntry.sourceRef` (0.13.0+)
+
+Every JE carries a typed `sourceRef: { sourceModel, sourceId, label?, kind? }`
+slot for "what produced this whole JE". Per-line back-references live on
+`journalItems[].sourceRef` (settles which document) and
+`journalItems[].linkedRefs[]` (additional docs touched).
+
+Add the index for fast source → JEs drill-down:
+
+```ts
+import { createAccountingEngine, ENTRY_SOURCE_INDEX } from '@classytic/ledger';
+
+createAccountingEngine({
+  schemaOptions: {
+    journalEntry: { extraIndexes: [ENTRY_SOURCE_INDEX] },
+  },
+});
+
+// After import — stamp the back-reference, then query by it.
+await JE.updateMany({ _importRunId: docId }, { $set: { sourceRef: {
+  sourceModel: 'SourceDocument', sourceId: docId,
+  label: 'INV-2026-001 — Acme Corp', kind: 'xero-invoice',
+}}});
+
+// Drill-down. Include `sourceModel` in the predicate so the query
+// planner reliably picks `sourceRef_idx` (the partial index only
+// contains stamped docs; the planner prefers it when both fields are
+// constrained). The sourceId-only form returns identical results but
+// may COLLSCAN on small collections.
+await JE.find({ 'sourceRef.sourceModel': 'SourceDocument', 'sourceRef.sourceId': docId });
+```
+
 ## Plugins
 
 ```ts

package/dist/bridges/index.d.mts

@@ -1,2 +1,3 @@
-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-DygMrab0.mjs";
+import { a as PeriodLockedNotification, i as NotificationBridgeContext, n as EntryReversedNotification, o as ReconciliationMismatchNotification, r as NotificationBridge, s as ExchangeRateBridge, t as LedgerBridges } from "../index-Dq3Kt1IG.mjs";
+import { n as SourceBridgeContext, r as SourceRef, t as SourceBridge } from "../source.bridge-CqqsPWfn.mjs";
 export { EntryReversedNotification, ExchangeRateBridge, LedgerBridges, NotificationBridge, NotificationBridgeContext, PeriodLockedNotification, ReconciliationMismatchNotification, SourceBridge, SourceBridgeContext, SourceRef };

package/dist/constants/index.d.mts

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

package/dist/country/index.d.mts

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

package/dist/events/index.d.mts

@@ -1,3 +1,3 @@
-import { $ as ReconciliationUnmatchedPayload, A as LedgerEventDefinition, B as InProcessLedgerBusOptions, C as EntryPostedPayloadSchema, D as EntryUnpostedPayloadSchema, E as EntryUnposted, F as ReconciliationUnmatched, G as EntryArchivedPayload, H as createEvent, I as ReconciliationUnmatchedPayloadSchema, J as EntryPostedPayload, K as EntryCreatedPayload, L as ledgerEventDefinitions, M as LedgerEventSchema, N as ReconciliationMatched, O as JournalSeeded, P as ReconciliationMatchedPayloadSchema, Q as ReconciliationMatchedPayload, R as EventLogger, S as EntryPosted, T as EntryReversedPayloadSchema, U as AccountBulkCreatedPayload, V as EventContext, W as AccountSeededPayload, X as EntryUnpostedPayload, Y as EntryReversedPayload, Z as JournalSeededPayload, _ as EntryArchivedPayloadSchema, a as OutboxFailOptions, b as EntryDuplicated, c as OutboxFailurePolicy, d as OutboxWriteOptions, et as LEDGER_EVENTS, f as AccountBulkCreated, g as EntryArchived, h as AccountSeededPayloadSchema, i as OutboxErrorInfo, j as LedgerEventPayloadOf, k as JournalSeededPayloadSchema, l as OutboxOwnershipError, m as AccountSeeded, n as OutboxAcknowledgeOptions, o as OutboxFailureContext, p as AccountBulkCreatedPayloadSchema, q as EntryDuplicatedPayload, r as OutboxClaimOptions, s as OutboxFailureDecision, t as InvalidOutboxEventError, tt as LedgerEventName, u as OutboxStore, v as EntryCreated, w as EntryReversed, x as EntryDuplicatedPayloadSchema, y as EntryCreatedPayloadSchema, z as InProcessLedgerBus } from "../outbox-store-CPLeocPg.mjs";
+import { $ as ReconciliationUnmatchedPayload, A as LedgerEventDefinition, B as InProcessLedgerBusOptions, C as EntryPostedPayloadSchema, D as EntryUnpostedPayloadSchema, E as EntryUnposted, F as ReconciliationUnmatched, G as EntryArchivedPayload, H as createEvent, I as ReconciliationUnmatchedPayloadSchema, J as EntryPostedPayload, K as EntryCreatedPayload, L as ledgerEventDefinitions, M as LedgerEventSchema, N as ReconciliationMatched, O as JournalSeeded, P as ReconciliationMatchedPayloadSchema, Q as ReconciliationMatchedPayload, R as EventLogger, S as EntryPosted, T as EntryReversedPayloadSchema, U as AccountBulkCreatedPayload, V as EventContext, W as AccountSeededPayload, X as EntryUnpostedPayload, Y as EntryReversedPayload, Z as JournalSeededPayload, _ as EntryArchivedPayloadSchema, a as OutboxFailOptions, b as EntryDuplicated, c as OutboxFailurePolicy, d as OutboxWriteOptions, et as LEDGER_EVENTS, f as AccountBulkCreated, g as EntryArchived, h as AccountSeededPayloadSchema, i as OutboxErrorInfo, j as LedgerEventPayloadOf, k as JournalSeededPayloadSchema, l as OutboxOwnershipError, m as AccountSeeded, n as OutboxAcknowledgeOptions, o as OutboxFailureContext, p as AccountBulkCreatedPayloadSchema, q as EntryDuplicatedPayload, r as OutboxClaimOptions, s as OutboxFailureDecision, t as InvalidOutboxEventError, tt as LedgerEventName, u as OutboxStore, v as EntryCreated, w as EntryReversed, x as EntryDuplicatedPayloadSchema, y as EntryCreatedPayloadSchema, z as InProcessLedgerBus } from "../outbox-store-BcCiHMPw.mjs";
 import { DomainEvent, EventHandler, EventTransport, PublishManyResult } from "@classytic/primitives/events";
 export { AccountBulkCreated, type AccountBulkCreatedPayload, type AccountBulkCreatedPayloadSchema, AccountSeeded, type AccountSeededPayload, type AccountSeededPayloadSchema, type DomainEvent, EntryArchived, type EntryArchivedPayload, type EntryArchivedPayloadSchema, EntryCreated, type EntryCreatedPayload, type EntryCreatedPayloadSchema, EntryDuplicated, type EntryDuplicatedPayload, type EntryDuplicatedPayloadSchema, EntryPosted, type EntryPostedPayload, type EntryPostedPayloadSchema, EntryReversed, type EntryReversedPayload, type EntryReversedPayloadSchema, EntryUnposted, type EntryUnpostedPayload, type EntryUnpostedPayloadSchema, type EventContext, type EventHandler, type EventLogger, type EventTransport, InProcessLedgerBus, type InProcessLedgerBusOptions, InvalidOutboxEventError, JournalSeeded, type JournalSeededPayload, type JournalSeededPayloadSchema, LEDGER_EVENTS, type LedgerEventDefinition, type LedgerEventName, type LedgerEventPayloadOf, type LedgerEventSchema, type OutboxAcknowledgeOptions, type OutboxClaimOptions, type OutboxErrorInfo, type OutboxFailOptions, type OutboxFailureContext, type OutboxFailureDecision, type OutboxFailurePolicy, OutboxOwnershipError, type OutboxStore, type OutboxWriteOptions, type PublishManyResult, ReconciliationMatched, type ReconciliationMatchedPayload, type ReconciliationMatchedPayloadSchema, ReconciliationUnmatched, type ReconciliationUnmatchedPayload, type ReconciliationUnmatchedPayloadSchema, createEvent, ledgerEventDefinitions };

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-pRW5cZhF.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-CMyOuKd3.mjs";
 export { CsvOptions, ExportField, ExportFieldMap, FlatJournalRow, PopulatedAccount, PopulatedJournalEntry, PopulatedJournalItem, buildCsv, escapeCell, exportToCsv, extractAllRows, extractRow, flattenJournalEntries, flattenJournalEntry, getHeaders, quickbooksFieldMap, serializeCsv, universalFieldMap };

package/dist/{index-pRW5cZhF.d.mts → index-CMyOuKd3.d.mts}

@@ -1,12 +1,6 @@
+import { r as SourceRef } from "./source.bridge-CqqsPWfn.mjs";
+
 //#region src/exports/types.d.ts
-/**
- * Export Types — Field maps, flat rows, and CSV builder configuration.
- *
- * All monetary values are in integer minor units (cents). For example,
- * 10050 represents $100.50. Field maps convert to dollar strings at CSV output.
- *
- * @module @classytic/ledger/exports
- */
 /**
  * A populated account object (the shape after .populate('journalItems.account')).
  * Only the fields the export module reads. Extra fields are ignored.
@@ -31,6 +25,12 @@ interface PopulatedJournalItem {
     taxCode?: string;
     taxName?: string;
   }>;
+  /** Per-line source back-ref (0.13.0). Null defaults when unstamped. */
+  sourceRef?: SourceRef;
+  /** Additional docs this line touches (QBO `LinkedTxn[]` shape). */
+  linkedRefs?: SourceRef[];
+  /** Free-form per-line provenance. */
+  meta?: Record<string, unknown> | null;
   /** Extra dimension fields from extraItemFields */
   [key: string]: unknown;
 }
@@ -49,6 +49,8 @@ interface PopulatedJournalEntry {
   totalCredit: number;
   state: 'draft' | 'posted' | 'archived';
   reversed?: boolean;
+  /** Entry-level source back-ref (0.13.0). Null defaults when unstamped. */
+  sourceRef?: SourceRef;
   createdAt?: Date | string;
   updatedAt?: Date | string;
   [key: string]: unknown;

package/dist/{index-Cr57UKD-.d.mts → index-DmRItmfZ.d.mts}

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

package/dist/{index-DygMrab0.d.mts → index-Dq3Kt1IG.d.mts}

@@ -1,3 +1,5 @@
+import { t as SourceBridge } from "./source.bridge-CqqsPWfn.mjs";
+
 //#region src/bridges/exchange-rate.bridge.d.ts
 /**
  * Exchange Rate Bridge — host-injected rate sourcing.
@@ -114,50 +116,6 @@ interface NotificationBridge {
   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 {
@@ -166,4 +124,4 @@ interface LedgerBridges {
   exchangeRate?: ExchangeRateBridge | undefined;
 }
 //#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 };
+export { PeriodLockedNotification as a, NotificationBridgeContext as i, EntryReversedNotification as n, ReconciliationMismatchNotification as o, NotificationBridge as r, ExchangeRateBridge as s, LedgerBridges as t };

package/dist/index.d.mts

@@ -1,12 +1,13 @@
-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-DygMrab0.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-B90x0Abq.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-B1CePayM.mjs";
-import { i as defineCountryPack, n as CountryPackInput, r as JournalTemplate, t as CountryPack } from "./index-Cr57UKD-.mjs";
-import { $ as ReconciliationUnmatchedPayload, A as LedgerEventDefinition, B as InProcessLedgerBusOptions, E as EntryUnposted, F as ReconciliationUnmatched, G as EntryArchivedPayload, H as createEvent, J as EntryPostedPayload, K as EntryCreatedPayload, L as ledgerEventDefinitions, M as LedgerEventSchema, N as ReconciliationMatched, O as JournalSeeded, Q as ReconciliationMatchedPayload, R as EventLogger, S as EntryPosted, U as AccountBulkCreatedPayload, V as EventContext, W as AccountSeededPayload, X as EntryUnpostedPayload, Y as EntryReversedPayload, Z as JournalSeededPayload, a as OutboxFailOptions, b as EntryDuplicated, c as OutboxFailurePolicy, d as OutboxWriteOptions, et as LEDGER_EVENTS, f as AccountBulkCreated, g as EntryArchived, i as OutboxErrorInfo, j as LedgerEventPayloadOf, l as OutboxOwnershipError, m as AccountSeeded, n as OutboxAcknowledgeOptions, o as OutboxFailureContext, q as EntryDuplicatedPayload, r as OutboxClaimOptions, s as OutboxFailureDecision, t as InvalidOutboxEventError, tt as LedgerEventName, u as OutboxStore, v as EntryCreated, w as EntryReversed, z as InProcessLedgerBus } from "./outbox-store-CPLeocPg.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-pRW5cZhF.mjs";
+import { a as PeriodLockedNotification, i as NotificationBridgeContext, n as EntryReversedNotification, o as ReconciliationMismatchNotification, r as NotificationBridge, s as ExchangeRateBridge, t as LedgerBridges } from "./index-Dq3Kt1IG.mjs";
+import { n as SourceBridgeContext, r as SourceRef, t as SourceBridge } from "./source.bridge-CqqsPWfn.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-D-2qfAJF.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-DCsI2nFX.mjs";
+import { i as defineCountryPack, n as CountryPackInput, r as JournalTemplate, t as CountryPack } from "./index-DmRItmfZ.mjs";
+import { $ as ReconciliationUnmatchedPayload, A as LedgerEventDefinition, B as InProcessLedgerBusOptions, E as EntryUnposted, F as ReconciliationUnmatched, G as EntryArchivedPayload, H as createEvent, J as EntryPostedPayload, K as EntryCreatedPayload, L as ledgerEventDefinitions, M as LedgerEventSchema, N as ReconciliationMatched, O as JournalSeeded, Q as ReconciliationMatchedPayload, R as EventLogger, S as EntryPosted, U as AccountBulkCreatedPayload, V as EventContext, W as AccountSeededPayload, X as EntryUnpostedPayload, Y as EntryReversedPayload, Z as JournalSeededPayload, a as OutboxFailOptions, b as EntryDuplicated, c as OutboxFailurePolicy, d as OutboxWriteOptions, et as LEDGER_EVENTS, f as AccountBulkCreated, g as EntryArchived, i as OutboxErrorInfo, j as LedgerEventPayloadOf, l as OutboxOwnershipError, m as AccountSeeded, n as OutboxAcknowledgeOptions, o as OutboxFailureContext, q as EntryDuplicatedPayload, r as OutboxClaimOptions, s as OutboxFailureDecision, t as InvalidOutboxEventError, tt as LedgerEventName, u as OutboxStore, v as EntryCreated, w as EntryReversed, z as InProcessLedgerBus } from "./outbox-store-BcCiHMPw.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-CMyOuKd3.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 GeneralLedgerAccount, A as generateDimensionBreakdown, B as AgedBalanceOptions, D as DimensionBreakdownParams, E as DimensionBreakdownOptions, F as BudgetVsActualReport, G as DEFAULT_BUCKETS, H as AgedBalanceReport, I as BudgetVsActualRow, J as BalanceSheetReport, K as generateAgedBalance, L as generateBudgetVsActual, M as generateCashFlow, N as BudgetVsActualOptions, O as DimensionBreakdownReport, P as BudgetVsActualParams, Q as ComparativeMode, T as reopenFiscalPeriod, U as AgedBalanceRow, V as AgedBalanceParams, W as AgedBucketConfig, X as CashFlowReport, Y as BalanceSheetSection, Z as CashFlowSection, a as RevaluationReport, at as PeriodColumn, b as generateGeneralLedger, c as RevaluationRate, ct as ReportGroup, d as computeRevaluation, dt as TrialBalanceColumnRow, et as GeneralLedgerReport, f as PartnerLedgerLine, ft as TrialBalanceReport, g as generatePartnerLedger, h as PartnerLedgerReport, ht as defaultLogger, i as RevaluationParams, it as LedgerEntry, k as DimensionBreakdownRow, l as RevaluationResult, lt as ReportLine, m as PartnerLedgerParams, mt as Logger, n as generateTrialBalance, nt as IncomeStatementReport, o as generateRevaluation, ot as ReportAccount, p as PartnerLedgerOptions, pt as TrialBalanceRow, q as BalanceSheetLineSource, r as RevaluationOptions, rt as IncomeStatementSection, s as AccountForeignBalance, st as ReportCategory, tt as IncomeStatementLineSource, u as buildRevaluationEntry, ut as ReportSection, v as generateIncomeStatement, vt as DaybookParams, w as closeFiscalPeriod, yt as DaybookReport, z as generateBalanceSheet } from "./trial-balance-Dy_fAeJV.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-BFPFihTF.mjs";
+import { $ as GeneralLedgerAccount, A as generateDimensionBreakdown, B as AgedBalanceOptions, D as DimensionBreakdownParams, E as DimensionBreakdownOptions, F as BudgetVsActualReport, G as DEFAULT_BUCKETS, H as AgedBalanceReport, I as BudgetVsActualRow, J as BalanceSheetReport, K as generateAgedBalance, L as generateBudgetVsActual, M as generateCashFlow, N as BudgetVsActualOptions, O as DimensionBreakdownReport, P as BudgetVsActualParams, Q as ComparativeMode, T as reopenFiscalPeriod, U as AgedBalanceRow, V as AgedBalanceParams, W as AgedBucketConfig, X as CashFlowReport, Y as BalanceSheetSection, Z as CashFlowSection, a as RevaluationReport, at as PeriodColumn, b as generateGeneralLedger, c as RevaluationRate, ct as ReportGroup, d as computeRevaluation, dt as TrialBalanceColumnRow, et as GeneralLedgerReport, f as PartnerLedgerLine, ft as TrialBalanceReport, g as generatePartnerLedger, h as PartnerLedgerReport, ht as defaultLogger, i as RevaluationParams, it as LedgerEntry, k as DimensionBreakdownRow, l as RevaluationResult, lt as ReportLine, m as PartnerLedgerParams, mt as Logger, n as generateTrialBalance, nt as IncomeStatementReport, o as generateRevaluation, ot as ReportAccount, p as PartnerLedgerOptions, pt as TrialBalanceRow, q as BalanceSheetLineSource, r as RevaluationOptions, rt as IncomeStatementSection, s as AccountForeignBalance, st as ReportCategory, tt as IncomeStatementLineSource, u as buildRevaluationEntry, ut as ReportSection, v as generateIncomeStatement, vt as DaybookParams, w as closeFiscalPeriod, yt as DaybookReport, z as generateBalanceSheet } from "./trial-balance-BS7F7-Xe.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-DkM0S1kQ.mjs";
 import { DomainEvent, EventHandler, EventTransport, EventTransport as EventTransport$1, PublishManyResult } from "@classytic/primitives/events";
 import { PaginationConfig, PluginFunction, PluginType, QueryParser, QueryParserOptions, Repository } from "@classytic/mongokit";
 import mongoose, { ClientSession, Connection, Model } from "mongoose";
@@ -887,6 +888,16 @@ interface JournalEntryInput {
   label?: string;
   date: Date;
   journalItems: JournalItemInput[];
+  /**
+   * Entry-level source back-reference (0.13.0+). Set at create time to stamp
+   * "what produced this whole JE". Most ingestion paths set this *after*
+   * insert via `repo.updateMany({ _importRunId }, { $set: { sourceRef } })`
+   * (because the source doc id is known only after the batch lands), but
+   * single-shot creators can pass it inline here. Drill-down: query
+   * `find({ 'sourceRef.sourceId': id })` — add `ENTRY_SOURCE_INDEX` to
+   * `schemaOptions.journalEntry.extraIndexes` for the index.
+   */
+  sourceRef?: SourceRef;
   /** Extra fields injected into the entry doc (dimension fields, tags, etc.). */
   extra?: Record<string, unknown>;
 }
@@ -901,6 +912,12 @@ interface JournalItemInput {
   originalCredit?: Cents;
   matchingNumber?: string;
   maturityDate?: Date;
+  /** "The document this line settles" — primary per-line back-reference. */
+  sourceRef?: SourceRef;
+  /** Additional docs this line touches (QBO `LinkedTxn[]` shape). */
+  linkedRefs?: SourceRef[];
+  /** Free-form per-line provenance (cost-center, project code, etc). */
+  meta?: Record<string, unknown> | null;
 }
 //#endregion
 //#region src/builders/opening-balance.d.ts
@@ -972,6 +989,30 @@ declare function buildOpeningBalanceEntry(input: OpeningBalanceInput): OpeningBa
  *     },
  *   });
  */
+/**
+ * Recommended opt-in index for the entry-level `sourceRef` field (0.13.0+).
+ *
+ * Spread into `schemaOptions.journalEntry.extraIndexes` to enable fast
+ * "list every JE produced by source document X" lookups — the canonical
+ * bookkeeping-UI drill-down from a source document (invoice, bill, bank
+ * statement) into its derived journal entries.
+ *
+ * Sparse + partial: only JEs where `sourceRef.sourceModel` is a string get
+ * indexed. Unstamped JEs (the default `{ sourceModel: null, sourceId: null }`)
+ * cost zero index storage.
+ *
+ * @example
+ *   import { createAccountingEngine, ENTRY_SOURCE_INDEX } from '@classytic/ledger';
+ *   createAccountingEngine({
+ *     schemaOptions: {
+ *       journalEntry: { extraIndexes: [ENTRY_SOURCE_INDEX] },
+ *     },
+ *   });
+ */
+declare const ENTRY_SOURCE_INDEX: {
+  fields: Record<string, 1 | -1>;
+  options: Record<string, unknown>;
+};
 declare const LINE_SOURCE_INDEXES: ReadonlyArray<{
   fields: Record<string, 1 | -1>;
   options: Record<string, unknown>;
@@ -1198,4 +1239,4 @@ interface PostingResult {
   idempotencyKeys?: string[];
 }
 //#endregion
-export { AccountBulkCreated, type AccountBulkCreatedPayload, type AccountCode, type AccountForeignBalance, type AccountRepository, AccountSeeded, 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 BalanceSheetLineSource, type BalanceSheetReport, type BalanceSheetSection, 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 ComparativeMode, 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, EntryArchived, type EntryArchivedPayload, EntryCreated, type EntryCreatedPayload, EntryDuplicated, type EntryDuplicatedPayload, EntryPosted, type EntryPostedPayload, EntryReversed, type EntryReversedNotification, type EntryReversedPayload, type EntryState, EntryUnposted, 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 IncomeStatementLineSource, type IncomeStatementReport, type IncomeStatementSection, type IntrospectAPI, InvalidOutboxEventError, JOURNAL_CODES, JOURNAL_TYPES, type JournalEntryInput, type JournalEntryRepository, type JournalItem, type JournalItemInput, type JournalItemRef, type JournalRepository, type JournalSchemaOptions, JournalSeeded, type JournalSeededPayload, type JournalTemplate, type JournalType, LEDGER_EVENTS, LINE_SOURCE_INDEXES, type LedgerBridges, type LedgerEntry, type LedgerEventDefinition, type LedgerEventName, type LedgerEventPayloadOf, type LedgerEventSchema, 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 OpeningBalanceInput, type OpeningBalanceResult, type OutboxAcknowledgeOptions, type OutboxClaimOptions, type OutboxErrorInfo, type OutboxFailOptions, type OutboxFailureContext, type OutboxFailureDecision, type OutboxFailurePolicy, OutboxOwnershipError, type OutboxStore, type OutboxWriteOptions, type PartnerLedgerLine, type PartnerLedgerOptions, type PartnerLedgerParams, type PartnerLedgerReport, type PeriodColumn, type PeriodLockedNotification, type PeriodResolverOptions, type PopulatedJournalEntry, type PostOptions, type PostingContract, type PostingResult, type PublishManyResult, ReconciliationMatched, type ReconciliationMatchedPayload, type ReconciliationMismatchNotification, type ReconciliationRepository, ReconciliationUnmatched, 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 ReportLine, type ReportSection, 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 TrialBalanceColumnRow, type TrialBalanceReport, type TrialBalanceRow, type UnmatchHookContext, type WatermarkResolverOptions, acquireSession, add, allocate, buildAccountTypeMap, buildDimensionFields, buildDimensionIndexes, buildItemFilters, buildOpeningBalanceEntry, 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, ledgerEventDefinitions, multiply, parseCents, percentage, periodResolver, quickbooksFieldMap, registerJournalType, reopenFiscalPeriod, resolveModelNames, splitTaxExclusive, splitTaxInclusive, subtract, toDecimal, universalFieldMap, watermarkResolver };
+export { AccountBulkCreated, type AccountBulkCreatedPayload, type AccountCode, type AccountForeignBalance, type AccountRepository, AccountSeeded, 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 BalanceSheetLineSource, type BalanceSheetReport, type BalanceSheetSection, 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 ComparativeMode, 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, ENTRY_SOURCE_INDEX, EntryArchived, type EntryArchivedPayload, EntryCreated, type EntryCreatedPayload, EntryDuplicated, type EntryDuplicatedPayload, EntryPosted, type EntryPostedPayload, EntryReversed, type EntryReversedNotification, type EntryReversedPayload, type EntryState, EntryUnposted, 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 IncomeStatementLineSource, type IncomeStatementReport, type IncomeStatementSection, type IntrospectAPI, InvalidOutboxEventError, JOURNAL_CODES, JOURNAL_TYPES, type JournalEntryInput, type JournalEntryRepository, type JournalItem, type JournalItemInput, type JournalItemRef, type JournalRepository, type JournalSchemaOptions, JournalSeeded, type JournalSeededPayload, type JournalTemplate, type JournalType, LEDGER_EVENTS, LINE_SOURCE_INDEXES, type LedgerBridges, type LedgerEntry, type LedgerEventDefinition, type LedgerEventName, type LedgerEventPayloadOf, type LedgerEventSchema, 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 OpeningBalanceInput, type OpeningBalanceResult, type OutboxAcknowledgeOptions, type OutboxClaimOptions, type OutboxErrorInfo, type OutboxFailOptions, type OutboxFailureContext, type OutboxFailureDecision, type OutboxFailurePolicy, OutboxOwnershipError, type OutboxStore, type OutboxWriteOptions, type PartnerLedgerLine, type PartnerLedgerOptions, type PartnerLedgerParams, type PartnerLedgerReport, type PeriodColumn, type PeriodLockedNotification, type PeriodResolverOptions, type PopulatedJournalEntry, type PostOptions, type PostingContract, type PostingResult, type PublishManyResult, ReconciliationMatched, type ReconciliationMatchedPayload, type ReconciliationMismatchNotification, type ReconciliationRepository, ReconciliationUnmatched, 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 ReportLine, type ReportSection, 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 TrialBalanceColumnRow, type TrialBalanceReport, type TrialBalanceRow, type UnmatchHookContext, type WatermarkResolverOptions, acquireSession, add, allocate, buildAccountTypeMap, buildDimensionFields, buildDimensionIndexes, buildItemFilters, buildOpeningBalanceEntry, 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, ledgerEventDefinitions, multiply, parseCents, percentage, periodResolver, quickbooksFieldMap, registerJournalType, reopenFiscalPeriod, resolveModelNames, splitTaxExclusive, splitTaxInclusive, subtract, toDecimal, universalFieldMap, watermarkResolver };

package/dist/index.mjs

@@ -497,13 +497,42 @@ function createJournalSchema(config, accountModelName, options = {}) {
 *     },
 *   });
 */
+/**
+* Recommended opt-in index for the entry-level `sourceRef` field (0.13.0+).
+*
+* Spread into `schemaOptions.journalEntry.extraIndexes` to enable fast
+* "list every JE produced by source document X" lookups — the canonical
+* bookkeeping-UI drill-down from a source document (invoice, bill, bank
+* statement) into its derived journal entries.
+*
+* Sparse + partial: only JEs where `sourceRef.sourceModel` is a string get
+* indexed. Unstamped JEs (the default `{ sourceModel: null, sourceId: null }`)
+* cost zero index storage.
+*
+* @example
+*   import { createAccountingEngine, ENTRY_SOURCE_INDEX } from '@classytic/ledger';
+*   createAccountingEngine({
+*     schemaOptions: {
+*       journalEntry: { extraIndexes: [ENTRY_SOURCE_INDEX] },
+*     },
+*   });
+*/
+const ENTRY_SOURCE_INDEX = {
+	fields: {
+		"sourceRef.sourceModel": 1,
+		"sourceRef.sourceId": 1
+	},
+	options: {
+		partialFilterExpression: { "sourceRef.sourceModel": { $type: "string" } },
+		name: "sourceRef_idx"
+	}
+};
 const LINE_SOURCE_INDEXES = [{
 	fields: {
 		"journalItems.sourceRef.sourceModel": 1,
 		"journalItems.sourceRef.sourceId": 1
 	},
 	options: {
-		sparse: true,
 		partialFilterExpression: { "journalItems.sourceRef.sourceModel": { $type: "string" } },
 		name: "journalItems_sourceRef_idx"
 	}
@@ -525,7 +554,7 @@ function createJournalEntrySchema(config, accountModelName, options = {}) {
 		taxCode: { type: String },
 		taxName: { type: String }
 	}, { _id: false });
-	const ItemSourceRefSchema = new mongoose.Schema({
+	const SourceRefSchema = new mongoose.Schema({
 		sourceModel: {
 			type: String,
 			default: null
@@ -533,6 +562,14 @@ function createJournalEntrySchema(config, accountModelName, options = {}) {
 		sourceId: {
 			type: String,
 			default: null
+		},
+		label: {
+			type: String,
+			default: null
+		},
+		kind: {
+			type: String,
+			default: null
 		}
 	}, { _id: false });
 	const amountValidator = {
@@ -603,11 +640,11 @@ function createJournalEntrySchema(config, accountModelName, options = {}) {
 			default: null
 		},
 		sourceRef: {
-			type: ItemSourceRefSchema,
+			type: SourceRefSchema,
 			default: () => ({})
 		},
 		linkedRefs: {
-			type: [ItemSourceRefSchema],
+			type: [SourceRefSchema],
 			default: void 0
 		},
 		...currencyItemFields,
@@ -688,6 +725,10 @@ function createJournalEntrySchema(config, accountModelName, options = {}) {
 			type: mongoose.Schema.Types.Mixed,
 			default: null
 		},
+		sourceRef: {
+			type: SourceRefSchema,
+			default: () => ({})
+		},
 		...extraFields
 	};
 	if (config.audit?.trackActor) {
@@ -783,6 +824,7 @@ function createJournalEntrySchema(config, accountModelName, options = {}) {
 			partialFilterExpression: { idempotencyKey: { $type: "string" } }
 		});
 	}
+	for (const idx of extraIndexes) schema.index(idx.fields, idx.options);
 	injectTenantField(schema, scope);
 	if (indexes) {
 		schema.index({
@@ -801,7 +843,6 @@ function createJournalEntrySchema(config, accountModelName, options = {}) {
 		},
 		name: "journal_text_idx"
 	});
-	for (const idx of extraIndexes) schema.index(idx.fields, idx.options);
 	return schema;
 }
 //#endregion
@@ -3129,4 +3170,4 @@ function buildDimensionIndexes(dimensions, orgField) {
 	});
 }
 //#endregion
-export { AccountBulkCreated, AccountSeeded, AccountingEngine, AccountingError, CATEGORIES, CATEGORY_KEYS, CURRENCIES, ConcurrencyError, DEFAULT_BUCKETS, DuplicateReferenceError, EntryArchived, EntryCreated, EntryDuplicated, EntryPosted, EntryReversed, EntryUnposted, Errors, IdempotencyConflictError, ImmutableViolationError, InProcessLedgerBus, InvalidOutboxEventError, JOURNAL_CODES, JOURNAL_TYPES, JournalSeeded, LEDGER_EVENTS, LINE_SOURCE_INDEXES, Money, OutboxOwnershipError, ReconciliationMatched, ReconciliationUnmatched, acquireSession, add, allocate, buildAccountTypeMap, buildDimensionFields, buildDimensionIndexes, buildItemFilters, buildOpeningBalanceEntry, 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, ledgerEventDefinitions, multiply, parseCents, percentage, periodResolver, quickbooksFieldMap, registerJournalType, reopenFiscalPeriod, resolveModelNames, splitTaxExclusive, splitTaxInclusive, subtract, toDecimal, universalFieldMap, watermarkResolver };
+export { AccountBulkCreated, AccountSeeded, AccountingEngine, AccountingError, CATEGORIES, CATEGORY_KEYS, CURRENCIES, ConcurrencyError, DEFAULT_BUCKETS, DuplicateReferenceError, ENTRY_SOURCE_INDEX, EntryArchived, EntryCreated, EntryDuplicated, EntryPosted, EntryReversed, EntryUnposted, Errors, IdempotencyConflictError, ImmutableViolationError, InProcessLedgerBus, InvalidOutboxEventError, JOURNAL_CODES, JOURNAL_TYPES, JournalSeeded, LEDGER_EVENTS, LINE_SOURCE_INDEXES, Money, OutboxOwnershipError, ReconciliationMatched, ReconciliationUnmatched, acquireSession, add, allocate, buildAccountTypeMap, buildDimensionFields, buildDimensionIndexes, buildItemFilters, buildOpeningBalanceEntry, 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, ledgerEventDefinitions, multiply, parseCents, percentage, periodResolver, quickbooksFieldMap, registerJournalType, reopenFiscalPeriod, resolveModelNames, splitTaxExclusive, splitTaxInclusive, subtract, toDecimal, universalFieldMap, watermarkResolver };

package/dist/{journals-B1CePayM.d.mts → journals-DCsI2nFX.d.mts}

@@ -1,4 +1,4 @@
-import { d as JournalType, f as MainType, h as StatementType, i as CategoryKey, o as Currency, r as Category } from "./core-B90x0Abq.mjs";
+import { d as JournalType, f as MainType, h as StatementType, i as CategoryKey, o as Currency, r as Category } from "./core-D-2qfAJF.mjs";
 
 //#region src/constants/categories.d.ts
 /** All valid categories */

package/dist/plugins/index.d.mts

@@ -1,2 +1,2 @@
-import { S as creditLimitPlugin, _ as FxRealizationPluginOptions, a as dailyLockPlugin, b as doubleEntryPlugin, c as periodResolver, d as LockAccountSelector, f as LockHit, g as idempotencyPlugin, h as IdempotencyPluginOptions, i as FiscalLockPluginOptions, 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, x as CreditLimitPluginOptions, y as DoubleEntryPluginOptions } from "../index-BFPFihTF.mjs";
+import { S as creditLimitPlugin, _ as FxRealizationPluginOptions, a as dailyLockPlugin, b as doubleEntryPlugin, c as periodResolver, d as LockAccountSelector, f as LockHit, g as idempotencyPlugin, h as IdempotencyPluginOptions, i as FiscalLockPluginOptions, 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, x as CreditLimitPluginOptions, y as DoubleEntryPluginOptions } from "../index-DkM0S1kQ.mjs";
 export { type CreateLockPluginOptions, type CreditLimitPluginOptions, type DailyLockPluginOptions, type DoubleEntryPluginOptions, type FiscalLockPluginOptions, type FxRealizationPluginOptions, type IdempotencyPluginOptions, type LockAccountSelector, type LockHit, type LockResolver, type LockResolverContext, type PeriodResolverOptions, type WatermarkResolverOptions, createLockPlugin, creditLimitPlugin, dailyLockPlugin, doubleEntryPlugin, fiscalLockPlugin, fxRealizationPlugin, idempotencyPlugin, periodResolver, watermarkResolver };

package/dist/reports/index.d.mts

@@ -1,2 +1,2 @@
-import { A as generateDimensionBreakdown, B as AgedBalanceOptions, C as FiscalReopenResult, D as DimensionBreakdownParams, E as DimensionBreakdownOptions, F as BudgetVsActualReport, G as DEFAULT_BUCKETS, H as AgedBalanceReport, I as BudgetVsActualRow, K as generateAgedBalance, L as generateBudgetVsActual, M as generateCashFlow, N as BudgetVsActualOptions, O as DimensionBreakdownReport, P as BudgetVsActualParams, R as BalanceSheetOptions, S as FiscalCloseResult, T as reopenFiscalPeriod, U as AgedBalanceRow, V as AgedBalanceParams, W as AgedBucketConfig, _ as IncomeStatementOptions, _t as DaybookOptions, a as RevaluationReport, b as generateGeneralLedger, bt as generateDaybook, f as PartnerLedgerLine, g as generatePartnerLedger, gt as DaybookLine, h as PartnerLedgerReport, i as RevaluationParams, j as CashFlowOptions, k as DimensionBreakdownRow, m as PartnerLedgerParams, n as generateTrialBalance, o as generateRevaluation, p as PartnerLedgerOptions, r as RevaluationOptions, t as TrialBalanceOptions, v as generateIncomeStatement, vt as DaybookParams, w as closeFiscalPeriod, x as FiscalCloseOptions, y as GeneralLedgerOptions, yt as DaybookReport, z as generateBalanceSheet } from "../trial-balance-Dy_fAeJV.mjs";
+import { A as generateDimensionBreakdown, B as AgedBalanceOptions, C as FiscalReopenResult, D as DimensionBreakdownParams, E as DimensionBreakdownOptions, F as BudgetVsActualReport, G as DEFAULT_BUCKETS, H as AgedBalanceReport, I as BudgetVsActualRow, K as generateAgedBalance, L as generateBudgetVsActual, M as generateCashFlow, N as BudgetVsActualOptions, O as DimensionBreakdownReport, P as BudgetVsActualParams, R as BalanceSheetOptions, S as FiscalCloseResult, T as reopenFiscalPeriod, U as AgedBalanceRow, V as AgedBalanceParams, W as AgedBucketConfig, _ as IncomeStatementOptions, _t as DaybookOptions, a as RevaluationReport, b as generateGeneralLedger, bt as generateDaybook, f as PartnerLedgerLine, g as generatePartnerLedger, gt as DaybookLine, h as PartnerLedgerReport, i as RevaluationParams, j as CashFlowOptions, k as DimensionBreakdownRow, m as PartnerLedgerParams, n as generateTrialBalance, o as generateRevaluation, p as PartnerLedgerOptions, r as RevaluationOptions, t as TrialBalanceOptions, v as generateIncomeStatement, vt as DaybookParams, w as closeFiscalPeriod, x as FiscalCloseOptions, y as GeneralLedgerOptions, yt as DaybookReport, z as generateBalanceSheet } from "../trial-balance-BS7F7-Xe.mjs";
 export { type AgedBalanceOptions, type AgedBalanceParams, type AgedBalanceReport, type AgedBalanceRow, type AgedBucketConfig, type BalanceSheetOptions, type BudgetVsActualOptions, type BudgetVsActualParams, type BudgetVsActualReport, type BudgetVsActualRow, type CashFlowOptions, DEFAULT_BUCKETS, type DaybookLine, type DaybookOptions, type DaybookParams, type DaybookReport, type DimensionBreakdownOptions, type DimensionBreakdownParams, type DimensionBreakdownReport, type DimensionBreakdownRow, type FiscalCloseOptions, type FiscalCloseResult, type FiscalReopenResult, type GeneralLedgerOptions, type IncomeStatementOptions, type PartnerLedgerLine, type PartnerLedgerOptions, type PartnerLedgerParams, type PartnerLedgerReport, type RevaluationOptions, type RevaluationParams, type RevaluationReport, type TrialBalanceOptions, closeFiscalPeriod, generateAgedBalance, generateBalanceSheet, generateBudgetVsActual, generateCashFlow, generateDaybook, generateDimensionBreakdown, generateGeneralLedger, generateIncomeStatement, generatePartnerLedger, generateRevaluation, generateTrialBalance, reopenFiscalPeriod };

package/dist/source.bridge-CqqsPWfn.d.mts

@@ -0,0 +1,74 @@
+//#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.
+ */
+/**
+ * Polymorphic back-reference to a host source document — the universal
+ * "what produced this entry" pointer used by both the entry-level
+ * `JournalEntry.sourceRef` slot and the line-level
+ * `JournalEntry.journalItems[].sourceRef` slot.
+ *
+ * Required:
+ *   - `sourceModel` — host model namespace (`"SourceDocument"`,
+ *     `"BankStatement"`, `"Invoice"`, `"PayrollRun"`, …).
+ *   - `sourceId` — opaque string identifier (ObjectId hex, ULID, or a
+ *     human-readable number like `INV-2026-04-001`). String — not ObjectId —
+ *     because the ledger has no knowledge of consumer model namespaces.
+ *
+ * Optional denormalization (0.13.0+):
+ *   - `label` — human-readable name of the source (statement label,
+ *     invoice number with party). Renders "From: <label>" in audit / drill-down
+ *     UIs without a follow-up `SourceBridge.resolve()` call.
+ *   - `kind` — sub-classifier of `sourceModel` (e.g. `"xero-invoice"`,
+ *     `"qbo-bill"`, `"bank-statement"`). Lets the UI route to the correct
+ *     detail page without re-querying the source.
+ *
+ * Both optional fields are denormalized — labels rarely change, and if they
+ * do, a one-shot `updateMany({ 'sourceRef.sourceId': id }, { $set: ... })`
+ * refreshes stale copies. The tradeoff buys the bookkeeping UI a fast path
+ * for "show me every JE produced by this document" without N+1 source-doc
+ * fetches.
+ */
+interface SourceRef {
+  sourceId: string;
+  sourceModel: string;
+  label?: string | null;
+  kind?: string | null;
+}
+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
+export { SourceBridgeContext as n, SourceRef as r, SourceBridge as t };

package/dist/{trial-balance-Dy_fAeJV.d.mts → trial-balance-BS7F7-Xe.d.mts}

@@ -1,5 +1,5 @@
-import { c as DateRange } from "./core-B90x0Abq.mjs";
-import { t as CountryPack } from "./index-Cr57UKD-.mjs";
+import { c as DateRange } from "./core-D-2qfAJF.mjs";
+import { t as CountryPack } from "./index-DmRItmfZ.mjs";
 import { ClientSession, Model } from "mongoose";
 
 //#region src/reports/daybook.d.ts

package/docs/sync.md

@@ -1,330 +1,84 @@
-# Sync — Invoice Bridge, Import & Export
+# Sync — Removed in 0.11.0
 
-`@classytic/ledger/sync` is the integration subpath for connecting external systems to the ledger.
+> **The `@classytic/ledger/sync` subpath was removed in `@classytic/ledger@0.11.0`.**
+> Sync orchestration is now host responsibility. This doc page is preserved
+> so links from older releases still resolve to a useful migration pointer
+> instead of a 404.
 
-```typescript
-import {
-  // Invoice engine bridge (recommended)
-  createLedgerBridge,
+## What used to live here
 
-  // Import/export pipeline
-  wireImport,
-  wireExport,
+The `/sync` subpath shipped with three concerns bundled together:
 
-  // Mapper factories (fin-io canonical shapes → JournalEntry)
-  bankStatementMapper,
-  invoiceMapper,
-  journalEntryMapper,
-  openingBalanceMapper,
-} from '@classytic/ledger/sync';
-```
-
----
-
-## Invoice Engine Integration
-
-### Recommended: `createLedgerBridge()`
-
-Wire `@classytic/invoice` to `@classytic/ledger` with one call. The bridge handles account mapping, tax lines, credit notes, payments, and reversals — no manual journal wiring needed.
-
-```typescript
-import { createAccountingEngine } from '@classytic/ledger';
-import { createLedgerBridge } from '@classytic/ledger/sync';
-import { createInvoiceEngine } from '@classytic/invoice';
-import { canadaPack } from '@classytic/ledger-ca';
-
-// 1. Create the accounting engine
-const accounting = createAccountingEngine({
-  mongoose: connection,
-  country: canadaPack,
-  currency: 'CAD',
-  multiTenant: { orgField: 'organizationId', orgRef: 'Organization' },
-  idempotency: true,
-});
-
-// 2. Create the bridge — map your chart of accounts once
-const bridge = createLedgerBridge(accounting, {
-  accounts: {
-    receivable: '1200',     // Accounts Receivable
-    payable: '2000',        // Accounts Payable
-    revenue: '4000',        // Revenue
-    expense: '5000',        // Cost of Goods Sold / Expenses
-    taxPayable: '2100',     // HST/GST/VAT Payable
-    taxReceivable: '1150',  // HST/GST/VAT Receivable (Input Tax Credit)
-    cash: '1000',           // Cash / Bank
-  },
-});
-
-// 3. Pass the bridge to the invoice engine — done
-const invoicing = createInvoiceEngine({
-  mongoose: connection,
-  ledger: bridge,
-  // ... other invoice config
-});
-```
-
-From this point, every invoice lifecycle operation automatically posts to the ledger:
-
-- **`invoicing.services.posting.post(id)`** → creates a balanced journal entry
-- **`invoicing.services.payment.recordPayment(input)`** → posts a payment entry (DR Cash, CR AR)
-- **`invoicing.services.posting.cancel(id, reason)`** → reverses the journal entry
-- **`invoicing.services.posting.void(id, reason)`** → reverses the journal entry (even if partially paid)
-
-### How the bridge maps each move type
-
-| Invoice Move Type | Journal Lines | Journal Type |
-|---|---|---|
-| `out_invoice` (Customer Invoice) | DR Receivable (total), CR Revenue (per line), CR Tax Payable | `SALES` |
-| `in_invoice` (Vendor Bill) | DR Expense (per line), DR Tax Receivable, CR Payable (total) | `PURCHASES` |
-| `out_refund` (Customer Credit Note) | CR Receivable, DR Revenue (per line), DR Tax Payable | `SALES` |
-| `in_refund` (Vendor Credit Note) | DR Payable, CR Expense (per line), CR Tax Receivable | `PURCHASES` |
-| `receipt` (POS Receipt) | DR Receivable/Cash, CR Revenue (per line), CR Tax Payable | `CASH_RECEIPTS` |
-
-All amounts are integer cents. Tax lines are only added when `taxAmount > 0`.
-
-### Payment recording
-
-When the invoice engine records a payment, the bridge calls `engine.record.payment()`:
-
-```
-DR Cash (1000)        $500.00
-CR Receivable (1200)  $500.00
-```
-
-An idempotency key is automatically derived from the payment ID (`payment:{paymentId}`), preventing duplicate journal entries on retry.
-
-### Reversal
-
-When an invoice is cancelled or voided, the bridge calls `engine.repositories.journalEntries.reverse()`, which creates a mirror entry with debits and credits swapped and links both entries bidirectionally.
-
-### Bridge configuration options
-
-#### `receiptAccount`
-
-Override the debit account for POS receipts. By default, receipts debit the `receivable` account. If your receipts are immediately paid (no A/R), point this at cash:
-
-```typescript
-createLedgerBridge(accounting, {
-  accounts: { ... },
-  receiptAccount: '1000',  // Receipts debit Cash directly
-});
-```
-
-#### `resolvePaymentAccounts`
-
-Custom resolver for payment accounts. Use when you need to determine AR vs AP based on context (e.g., vendor bill payments should clear AP, not AR):
+1. **`createLedgerBridge(accounting, config)`** — `@classytic/invoice` `LedgerBridge` adapter.
+2. **`wireImport` / `wireExport`** — generic batch importer/exporter pipeline.
+3. **Mapper factories** — `bankStatementMapper`, `invoiceMapper`, `journalEntryMapper`, `openingBalanceMapper` (fin-io canonical shapes → `JournalEntryInput`).
 
-```typescript
-createLedgerBridge(accounting, {
-  accounts: { ... },
-  resolvePaymentAccounts: (input) => {
-    const isVendor = vendorInvoiceIds.has(input.invoiceId);
-    return {
-      receivableOrPayable: isVendor ? '2000' : '1200',
-      cash: '1000',
-    };
-  },
-});
-```
-
-### Double-entry guarantee
-
-The bridge uses `engine.record.adjustment()` internally. This routes through the ledger's double-entry plugin, which validates `sum(debits) === sum(credits)` before persisting. If the invoice engine sends unbalanced data, the ledger rejects it with a structured validation error.
-
----
-
-### Alternative: Manual wiring (without `createLedgerBridge`)
+All three were moved out of `@classytic/ledger` because:
 
-If you need full control over the journal entry shape — for example, to add dimension fields, use different accounts per line, or handle complex tax scenarios — you can implement the `LedgerBridge` interface yourself:
+- They forced **`@classytic/fin-io`** as an optional peer on every consumer, even when no fin-io shape was ever read.
+- The invoice-bridge adapter imported `@classytic/invoice` types — a cross-package import that violates [`PACKAGE_RULES` P1](../PACKAGE_RULES.md) (no inter-package imports beyond `mongokit` + `primitives`).
+- Only one host ever consumed the subpath, so the cost wasn't worth keeping in a shared library.
 
-```typescript
-import type { LedgerBridge } from '@classytic/ledger/sync';
+## What stayed (still on the main entry)
 
-const ledgerBridge: LedgerBridge = {
-  async createJournalEntry(input) {
-    // Use record.adjustment() for multi-line entries with tax
-    const entry = await accounting.record.adjustment(input.organizationId, {
-      date: input.date,
-      label: `Invoice ${input.invoiceId}`,
-      journalType: 'SALES',
-      lines: [
-        { account: '1200', debit: input.totalAmount },
-        ...input.lines.map(line => ({
-          account: '4000',
-          credit: line.amount,
-          label: line.description,
-        })),
-        ...(input.taxAmount > 0
-          ? [{ account: '2100', credit: input.taxAmount, label: 'Tax' }]
-          : []),
-      ],
-    }, {
-      idempotencyKey: input.idempotencyKey,
-    });
-    return String((entry as any)._id);
-  },
+The pure ledger-side primitives that don't pull in fin-io OR invoice types are kept:
 
-  async reverseJournalEntry(journalEntryId, reason) {
-    const { reversal } = await accounting.repositories.journalEntries
-      .reverse(journalEntryId);
-    return String((reversal as any)._id);
-  },
+- `buildOpeningBalanceEntry(input)` — pure helper, re-exported from `@classytic/ledger`.
+- `OpeningBalanceInput`, `OpeningBalanceResult` — re-exported from `@classytic/ledger`.
+- `JournalEntryInput`, `JournalItemInput` — describe the `journalEntries.create()` input; inherent to the engine, not a sync concern.
 
-  async recordPayment(input) {
-    const entry = await accounting.record.payment(input.organizationId, {
-      date: input.date,
-      amount: input.amount,
-      fromReceivableAccount: '1200',
-      toCashAccount: '1000',
-      label: `Payment ${input.paymentId} for ${input.invoiceId}`,
-    }, {
-      idempotencyKey: `payment:${input.paymentId}`,
-    });
-    return String((entry as any)._id);
-  },
-};
-
-// Then pass to the invoice engine
-const invoicing = createInvoiceEngine({
-  mongoose: connection,
-  ledger: ledgerBridge,
-});
+```ts
+import { buildOpeningBalanceEntry } from '@classytic/ledger';
+import type { JournalEntryInput, JournalItemInput } from '@classytic/ledger';
 ```
 
-This gives you the same integration but with full control over account resolution, dimension fields, and tax line construction.
-
-### Using `LedgerBridge` without `@classytic/invoice`
+## How to wire an invoice engine today
 
-The bridge types are generic — any invoicing system that calls these 3 methods works:
+Pick one of two paths:
 
-```typescript
-import type { LedgerBridge, LedgerPostInput, LedgerPaymentInput } from '@classytic/ledger/sync';
+### Option A — Copy the canonical reference implementation
 
-// Use createLedgerBridge() for standard mapping
-const bridge: LedgerBridge = createLedgerBridge(accounting, { accounts: { ... } });
+`fajr-be-arc` carries the production-grade implementation at
+`src/shared/ledger-sync/`. The relevant files are:
 
-// Post an invoice
-const jeId = await bridge.createJournalEntry({
-  organizationId: 'org_1',
-  invoiceId: 'INV-001',
-  moveType: 'out_invoice',
-  partnerId: 'customer-123',
-  date: new Date(),
-  currency: 'USD',
-  lines: [
-    { description: 'Consulting', amount: 100000, taxAmount: 13000, taxCode: 'HST' },
-  ],
-  totalAmount: 113000,
-  taxAmount: 13000,
-});
+- `ledger-bridge.ts` — implements `@classytic/invoice`'s `LedgerBridge`
+  contract on top of an `AccountingEngine`. Includes multi-tenant scope,
+  multi-currency, withholding tax, refunds, and an opt-in
+  `resolvePaymentAccounts({ debit, credit })` callback for AR/AP-aware
+  hosts (clears AR-shape for `out_invoice`, AP-shape for `in_invoice`).
 
-// Record a payment
-await bridge.recordPayment({
-  organizationId: 'org_1',
-  invoiceId: 'INV-001',
-  paymentId: 'PAY-001',
-  amount: 113000,
-  currency: 'USD',
-  date: new Date(),
-  method: 'bank_transfer',
-});
+Drop the files into your repo, adjust the import paths, done. The
+implementation is < 600 lines total and stable.
 
-// Reverse (cancel/void)
-await bridge.reverseJournalEntry(jeId, 'Invoice cancelled');
-```
-
----
-
-## Bank Statement Import
+### Option B — Implement `LedgerBridge` yourself
 
-Import bank transactions from any format supported by `@classytic/fin-io`:
+Implement the three-method interface against your accounting engine
+directly. The contract lives in `@classytic/invoice/dist/domain/contracts/ledger-bridge.d.ts`:
 
-```typescript
-import { parseOfx } from '@classytic/fin-io/ofx';
-import { wireImport, bankStatementMapper } from '@classytic/ledger/sync';
-
-const parsed = parseOfx(buffer);
-if (!parsed.ok) throw new Error(parsed.error);
-
-const report = await wireImport({
-  source: parsed.data.flatMap(s => s.transactions),
-  mapper: bankStatementMapper({
-    bankAccountId: bankAccount._id,
-    suspenseAccountId: suspenseAccount._id,
-    categorize: (txn) => knownVendors[txn.counterparty?.name]?.accountId,
-  }),
-  journalEntries: engine.repositories.journalEntries,
-  context: { organizationId },
-}).run();
-
-console.log(`Imported ${report.inserted}, skipped ${report.skipped} duplicates`);
+```ts
+export interface LedgerBridge {
+  createJournalEntry(input: LedgerPostInput): Promise<string>;
+  reverseJournalEntry(jeId: string, reason: string, ctx: LedgerReverseContext): Promise<string>;
+  recordPayment(input: LedgerPaymentInput): Promise<string>;
+}
 ```
 
-### Available mappers
+A bare-minimum implementation is ~80 lines (one tax line, no withholding,
+no FX). Useful when your COA is small and stable enough that the
+`createLedgerBridge` config map's flexibility is overkill.
 
-| Mapper | Source | Output |
-|---|---|---|
-| `bankStatementMapper` | `CanonicalTransaction` (OFX, CAMT, MT940, CSV, Plaid) | 2-line JE: Cash ↔ Suspense |
-| `invoiceMapper` | `CanonicalInvoice` (QBO, Xero JSON) | Multi-line JE: AR/AP ↔ Revenue/Expense ↔ Tax |
-| `journalEntryMapper` | `CanonicalJournalEntry` (QBO, Xero manual journals) | 1:1 mapping |
-| `openingBalanceMapper` | `TrialBalanceInput` | Multi-line opening balance entry |
+## How to wire fin-io imports today
 
-### Idempotency
+The mapper helpers (`bankStatementMapper`, `invoiceMapper`, etc.) and the
+`wireImport`/`wireExport` pipeline moved to host code along with the
+bridge. The canonical implementation lives in `fajr-be-arc` under
+`src/workflows/ai-bank-import.workflow.ts` (for AI-extracted bank
+statements) and `src/resources/integrations/` (for QBO / Xero sync).
 
-Re-running an import on the same file produces zero duplicates. Each mapper extracts a stable `externalId` from the source record (e.g., OFX `FITID`, CAMT `NtryRef`). The `wireImport` pipeline checks for existing entries before creating.
-
-For best performance, provide a `findExisting` callback and add a partial index on `{ organizationId: 1, _externalId: 1 }`.
-
----
-
-## Export
-
-Stream ledger data to external formats:
-
-```typescript
-import { wireExport } from '@classytic/ledger/sync';
-
-const report = await wireExport({
-  query: { organizationId: 'org_1', state: 'posted' },
-  sink: {
-    fromJournalEntry: (entry) => transformToCSVRow(entry),
-    emit: async (rows) => csvStream.write(rows),
-    flush: async () => csvStream.end(),
-  },
-  journalEntries: engine.repositories.journalEntries,
-  options: { batchSize: 500 },
-}).run();
-```
+`@classytic/fin-io` is a normal direct dependency in fajr — not a peer
+of ledger. Hosts that don't need fin-io shapes don't pull it in.
 
 ---
 
-## Writing Custom Mappers
-
-Implement `ImportMapper<TRaw>` for any data source:
-
-```typescript
-import type { ImportMapper } from '@classytic/ledger/sync';
-
-interface MyPayrollRecord {
-  id: string;
-  employeeName: string;
-  grossPay: number;
-  taxWithheld: number;
-  netPay: number;
-  date: Date;
-}
-
-const payrollMapper: ImportMapper<MyPayrollRecord> = {
-  externalId: (record) => `payroll:${record.id}`,
-
-  toJournalEntry: (record, ctx) => ({
-    date: record.date,
-    label: `Payroll — ${record.employeeName}`,
-    journalItems: [
-      { account: salaryExpenseId, debit: record.grossPay, credit: 0 },
-      { account: taxPayableId, debit: 0, credit: record.taxWithheld },
-      { account: cashId, debit: 0, credit: record.netPay },
-    ],
-  }),
-};
-```
+For the architectural rationale + full migration list, see
+[`CHANGELOG.md` → 0.11.0](../CHANGELOG.md).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@classytic/ledger",
-  "version": "0.12.2",
+  "version": "0.12.3",
   "description": "Production-grade double-entry accounting engine for MongoDB — schemas, reports, tax, multi-tenant",
   "type": "module",
   "sideEffects": false,
@@ -88,23 +88,23 @@
     "url": "git+https://github.com/classytic/ledger.git"
   },
   "peerDependencies": {
-    "@classytic/mongokit": ">=3.13.0",
-    "@classytic/primitives": ">=0.5.0",
-    "@classytic/repo-core": ">=0.4.0",
-    "mongoose": ">=9.4.1",
+    "@classytic/mongokit": ">=3.14.0",
+    "@classytic/primitives": ">=0.6.0",
+    "@classytic/repo-core": ">=0.5.0",
+    "mongoose": ">=9.6.2",
     "zod": ">=4.0.0"
   },
   "devDependencies": {
     "@biomejs/biome": "^2.4.12",
     "@classytic/dev-tools": "^0.2.0",
-    "@classytic/mongokit": ">=3.13.0",
-    "@classytic/primitives": ">=0.5.0",
-    "@classytic/repo-core": ">=0.4.0",
+    "@classytic/mongokit": "^3.14.0",
+    "@classytic/primitives": "^0.6.0",
+    "@classytic/repo-core": "^0.5.0",
     "@types/node": "^25.5.0",
     "@vitest/coverage-v8": "^4.1.4",
     "knip": "^6.4.1",
     "mongodb-memory-server": "^11.0.1",
-    "mongoose": "^9.4.1",
+    "mongoose": "^9.6.2",
     "tsdown": "^0.21.8",
     "typescript": "^5.7.0",
     "vitest": "^4.1.4",