@classytic/ledger 0.7.0 → 0.9.0

package/dist/index.mjs

@@ -1,13 +1,42 @@
-import { a as JOURNAL_CODES, c as getCustomJournalTypes, d as isValidJournalType, f as registerJournalType, i as isValidCurrency, l as getJournalType, n as getCurrency, o as JOURNAL_TYPES, r as getMinorUnit, s as _freezeJournalTypes, t as CURRENCIES, u as getJournalTypeCodes } from "./currencies-CsuBGfgs.mjs";
+import { i as LEDGER_EVENTS, n as InProcessLedgerBus, r as createEvent, t as OutboxOwnershipError } from "./outbox-store-DQbL-KYT.mjs";
+import { a as IdempotencyConflictError, i as Errors, n as ConcurrencyError, o as ImmutableViolationError, r as DuplicateReferenceError, s as classifyDuplicateKey, t as AccountingError } from "./errors-BI5k4iak.mjs";
+import { a as JOURNAL_CODES, c as getCustomJournalTypes, d as isValidJournalType, f as registerJournalType, i as isValidCurrency, l as getJournalType, n as getCurrency, o as JOURNAL_TYPES, r as getMinorUnit, s as _freezeJournalTypes, t as CURRENCIES, u as getJournalTypeCodes } from "./currencies-Jo5oaM_4.mjs";
 import { Money, add, allocate, format, formatPlain, fromDecimal, multiply, parseCents, percentage, splitTaxExclusive, splitTaxInclusive, subtract, toDecimal } from "./money.mjs";
-import { n as Errors, t as AccountingError } from "./errors-CSDQPNyt.mjs";
-import { C as isVirtualTaxAccount, E as requireOrgScope, S as computeEndingBalance, T as generateAgedBalance, _ as buildItemFilters, a as finalizeSession, b as buildAccountTypeMap, c as generateRevaluation, d as generateIncomeStatement, f as generateGeneralLedger, g as generateBalanceSheet, h as generateBudgetVsActual, i as acquireSession, l as buildRevaluationEntry, m as generateCashFlow, n as closeFiscalPeriod, o as defaultLogger, p as generateDimensionBreakdown, r as reopenFiscalPeriod, s as generateTrialBalance, t as generatePartnerLedger, u as computeRevaluation, v as getDateRange, w as DEFAULT_BUCKETS, x as calculateTotal, y as getFiscalYearStart } from "./partner-ledger-D9H5hegI.mjs";
-import { c as getNormalBalance, d as isValidCategory, l as isBalanceSheet, n as CATEGORY_KEYS, t as CATEGORIES, u as isIncomeStatement } from "./categories-BkKdv16V.mjs";
-import { a as watermarkResolver, c as idempotencyPlugin, i as fiscalLockPlugin, l as doubleEntryPlugin, n as creditLimitPlugin, o as periodResolver, r as dailyLockPlugin, s as createLockPlugin, t as fxRealizationPlugin } from "./fx-realization.plugin-CfYy1tB6.mjs";
+import { C as isVirtualTaxAccount, E as requireOrgScope, S as computeEndingBalance, T as generateAgedBalance, _ as buildItemFilters, a as finalizeSession, b as buildAccountTypeMap, c as generateRevaluation, d as generateIncomeStatement, f as generateGeneralLedger, g as generateBalanceSheet, h as generateBudgetVsActual, i as acquireSession, l as buildRevaluationEntry, m as generateCashFlow, n as closeFiscalPeriod, o as defaultLogger, p as generateDimensionBreakdown, r as reopenFiscalPeriod, s as generateTrialBalance, t as generatePartnerLedger, u as computeRevaluation, v as getDateRange, w as DEFAULT_BUCKETS, x as calculateTotal, y as getFiscalYearStart } from "./partner-ledger-BoebloHk.mjs";
+import { c as getNormalBalance, d as isValidCategory, l as isBalanceSheet, n as CATEGORY_KEYS, t as CATEGORIES, u as isIncomeStatement } from "./categories-FJlrvzcl.mjs";
+import { a as watermarkResolver, c as idempotencyPlugin, i as fiscalLockPlugin, l as doubleEntryPlugin, n as creditLimitPlugin, o as periodResolver, r as dailyLockPlugin, s as createLockPlugin, t as fxRealizationPlugin } from "./fx-realization.plugin-Bxlb8cIx.mjs";
+import { t as buildOpeningBalanceEntry } from "./opening-balance-1cixYh6Y.mjs";
 import { defineCountryPack } from "./country/index.mjs";
-import { a as exportToCsv, i as quickbooksFieldMap, r as universalFieldMap, t as flattenJournalEntries } from "./exports-BP-0Ni5W.mjs";
+import { a as exportToCsv, i as quickbooksFieldMap, r as universalFieldMap, t as flattenJournalEntries } from "./exports-C30yRapf.mjs";
+import { QueryParser, Repository, getNextSequence, multiTenantPlugin } from "@classytic/mongokit";
 import mongoose, { Schema } from "mongoose";
-import { Repository } from "@classytic/mongokit";
+//#region src/plugins/immutable-guard.plugin.ts
+/**
+* Returns a mongokit plugin function. Install only when
+* `config.strictness.immutable === true`.
+*/
+function immutableGuardPlugin(options) {
+	const { JournalEntryModel, orgField } = options;
+	return (repo) => {
+		repo.on("before:update", async (ctx) => {
+			if (ctx._ledgerInternal) return;
+			const id = ctx.id;
+			if (!id) return;
+			const query = { _id: id };
+			if (orgField && ctx.query && orgField in ctx.query) query[orgField] = ctx.query[orgField];
+			if ((await JournalEntryModel.findOne(query).select({ state: 1 }).lean())?.state === "posted") throw new ImmutableViolationError(id);
+		});
+		repo.on("before:delete", async (ctx) => {
+			if (ctx._ledgerInternal) return;
+			const id = ctx.id;
+			if (!id) return;
+			const query = { _id: id };
+			if (orgField && ctx.query && orgField in ctx.query) query[orgField] = ctx.query[orgField];
+			if ((await JournalEntryModel.findOne(query).select({ state: 1 }).lean())?.state === "posted") throw new ImmutableViolationError(id);
+		});
+	};
+}
+//#endregion
 //#region src/schemas/currency-field.ts
 /**
 * Build the Mongoose currency field definition.
@@ -579,7 +608,10 @@ function createJournalEntrySchema(config, accountModelName, options = {}) {
 		ref: multiTenant.orgRef,
 		required: true
 	};
-	const schema = new mongoose.Schema(fields, { timestamps: true });
+	const schema = new mongoose.Schema(fields, {
+		timestamps: true,
+		optimisticConcurrency: true
+	});
 	schema.pre("validate", function() {
 		for (const item of this.journalItems) if (!item.date) item.date = this.date;
 		for (let i = 0; i < this.journalItems.length; i++) {
@@ -597,56 +629,25 @@ function createJournalEntrySchema(config, accountModelName, options = {}) {
 		this.totalDebit = totalDebit;
 		this.totalCredit = totalCredit;
 	});
-	if (autoReference) {
-		const generateReferenceNumber = async (doc, Model, session) => {
-			const jt = doc.journalType || "MISC";
-			const d = new Date(doc.date);
-			const prefix = `${jt}/${d.getFullYear()}/${String(d.getMonth() + 1).padStart(2, "0")}/`;
-			const matchFilter = { referenceNumber: { $regex: `^${prefix.replace(/\//g, "\\/")}` } };
-			if (multiTenant) matchFilter[multiTenant.orgField] = doc[multiTenant.orgField];
-			const pipeline = [
-				{ $match: matchFilter },
-				{ $addFields: { _refSeq: { $toInt: { $arrayElemAt: [{ $split: ["$referenceNumber", "/"] }, -1] } } } },
-				{ $sort: { _refSeq: -1 } },
-				{ $limit: 1 },
-				{ $project: { _refSeq: 1 } }
-			];
-			const results = await Model.aggregate(pipeline).session(session);
-			let seq = 1;
-			if (results.length > 0 && typeof results[0]._refSeq === "number") seq = results[0]._refSeq + 1;
-			return `${prefix}${String(seq).padStart(4, "0")}`;
-		};
-		schema.pre("save", async function() {
-			if (this.isModified("journalType")) this.referenceNumber = void 0;
-			if (!this.referenceNumber) {
-				const session = this.$session?.() ?? null;
-				const Model = this.constructor;
-				this.referenceNumber = await generateReferenceNumber(this, Model, session);
+	if (autoReference) schema.pre("save", async function() {
+		if (this.isModified("journalType")) this.referenceNumber = void 0;
+		if (!this.referenceNumber) {
+			const session = this.$session?.() ?? null;
+			const connection = this.constructor.db;
+			const journalType = this.journalType || "MISC";
+			const date = this.date ? new Date(this.date) : /* @__PURE__ */ new Date();
+			const year = date.getFullYear();
+			const month = String(date.getMonth() + 1).padStart(2, "0");
+			let orgScope = "global";
+			if (multiTenant) {
+				const raw = this.get(multiTenant.orgField);
+				if (raw != null) orgScope = typeof raw.toHexString === "function" ? raw.toHexString() : String(raw);
+				else orgScope = "unscoped";
 			}
-		});
-		const MAX_REF_RETRIES = 3;
-		schema.post("save", async (error, doc, next) => {
-			const mongoError = error;
-			if (mongoError.code === 11e3 && mongoError.keyPattern?.referenceNumber) {
-				const entry = doc;
-				const retryCount = entry.__refRetries ?? 0;
-				if (retryCount >= MAX_REF_RETRIES) {
-					next(/* @__PURE__ */ new Error(`Failed to generate unique reference number after ${MAX_REF_RETRIES} retries. Too many concurrent inserts for this period.`));
-					return;
-				}
-				entry.__refRetries = retryCount + 1;
-				const session = entry.$session?.() ?? null;
-				const Model = entry.constructor;
-				entry.referenceNumber = await generateReferenceNumber(entry, Model, session);
-				try {
-					await entry.save({ session });
-					next();
-				} catch (retryError) {
-					next(retryError);
-				}
-			} else next(error);
-		});
-	}
+			const seq = await getNextSequence(`ledger:${orgScope}:${journalType}:${year}-${month}`, 1, connection, session ?? void 0);
+			this.referenceNumber = `${journalType}/${year}/${month}/${String(seq).padStart(4, "0")}`;
+		}
+	});
 	if (indexes) {
 		const org = multiTenant?.orgField;
 		const refPartial = { partialFilterExpression: { referenceNumber: {
@@ -712,10 +713,13 @@ function createJournalEntrySchema(config, accountModelName, options = {}) {
 			idempotencyIdx.idempotencyKey = 1;
 			schema.index(idempotencyIdx, {
 				unique: true,
-				partialFilterExpression: { idempotencyKey: {
-					$exists: true,
-					$ne: null
-				} }
+				partialFilterExpression: { idempotencyKey: { $type: "string" } }
+			});
+			const ttlSeconds = typeof config.idempotencyTtlSeconds === "number" && config.idempotencyTtlSeconds > 0 ? config.idempotencyTtlSeconds : 86400;
+			schema.index({ createdAt: 1 }, {
+				name: "idempotency_ttl_idx",
+				expireAfterSeconds: ttlSeconds,
+				partialFilterExpression: { idempotencyKey: { $type: "string" } }
 			});
 		}
 	}
@@ -914,16 +918,26 @@ function createModels(connection, config) {
 }
 //#endregion
 //#region src/repositories/account.repository.ts
+async function safePublish$3(events, outboxStore, type, payload, ctx) {
+	const event = createEvent(type, payload, ctx);
+	if (outboxStore) try {
+		await outboxStore.save(event, { session: ctx?.session ?? void 0 });
+	} catch {}
+	if (events) try {
+		await events.publish(event);
+	} catch {}
+}
 /**
 * Wire seedAccounts, bulkCreate and posting-account validation
 * onto an existing mongokit Repository.
 *
 * @param repository - A mongokit Repository instance (already created)
-* @param AccountModel - The Mongoose model for accounts
 * @param country - The CountryPack for account type lookups
 * @param orgField - The multi-tenant field name (e.g. 'business')
 */
-function wireAccountMethods(repository, AccountModel, country, orgField) {
+function wireAccountMethods(repository, country, orgField, integrations = {}) {
+	const events = integrations.events;
+	const outboxStore = integrations.outboxStore;
 	repository.on("before:create", (ctx) => {
 		const code = ctx.data?.accountTypeCode;
 		if (code && !country.isPostingAccount(code)) throw Errors.validation(`Cannot create account with type "${code}" — it is a structural group or calculated total, not a posting account.`);
@@ -936,7 +950,10 @@ function wireAccountMethods(repository, AccountModel, country, orgField) {
 		const postingTypes = country.getPostingAccountTypes();
 		const filter = {};
 		if (orgField && orgId != null) filter[orgField] = orgId;
-		const existing = await AccountModel.find(filter).select("accountNumber").lean();
+		const existing = await repository.findAll(filter, {
+			select: { accountNumber: 1 },
+			lean: true
+		});
 		const existingNumbers = new Set(existing.map((a) => a.accountNumber));
 		const toCreate = postingTypes.filter((at) => !existingNumbers.has(at.code)).map((at) => {
 			const doc = {
@@ -951,9 +968,10 @@ function wireAccountMethods(repository, AccountModel, country, orgField) {
 			created: 0,
 			skipped: existingNumbers.size
 		};
+		let result;
 		try {
-			return {
-				created: (await AccountModel.insertMany(toCreate, {
+			result = {
+				created: (await repository.createMany(toCreate, {
 					session: options.session ?? void 0,
 					ordered: false
 				})).length,
@@ -963,13 +981,21 @@ function wireAccountMethods(repository, AccountModel, country, orgField) {
 			const bulkError = err;
 			if (bulkError.code === 11e3 || bulkError.writeErrors) {
 				const insertedDocs = bulkError.insertedDocs ?? [];
-				return {
+				result = {
 					created: insertedDocs.length,
 					skipped: existingNumbers.size + (toCreate.length - insertedDocs.length)
 				};
-			}
-			throw err;
+			} else throw err;
 		}
+		await safePublish$3(events, outboxStore, LEDGER_EVENTS.ACCOUNT_SEEDED, {
+			created: result.created,
+			skipped: result.skipped,
+			organizationId: orgId
+		}, {
+			organizationId: orgId,
+			session: options.session ?? null
+		});
+		return result;
 	};
 	/**
 	* Bulk create accounts with validation and skip-if-exists logic.
@@ -1034,7 +1060,10 @@ function wireAccountMethods(repository, AccountModel, country, orgField) {
 		};
 		const existsFilter = { accountNumber: { $in: validAccounts.map((a) => a.accountNumber) } };
 		if (orgField && orgId != null) existsFilter[orgField] = orgId;
-		const existingDocs = await AccountModel.find(existsFilter).select("accountNumber").lean();
+		const existingDocs = await repository.findAll(existsFilter, {
+			select: { accountNumber: 1 },
+			lean: true
+		});
 		const existingNumbers = new Set(existingDocs.map((d) => d.accountNumber));
 		const toCreate = [];
 		for (const item of validAccounts) if (existingNumbers.has(item.accountNumber)) results.skipped.push({
@@ -1056,7 +1085,7 @@ function wireAccountMethods(repository, AccountModel, country, orgField) {
 				return doc;
 			});
 			try {
-				const inserted = await AccountModel.insertMany(docs, { ordered: false });
+				const inserted = await repository.createMany(docs, { ordered: false });
 				results.created = toCreate.map((item, idx) => ({
 					accountTypeCode: item.accountTypeCode,
 					active: item.active,
@@ -1084,13 +1113,20 @@ function wireAccountMethods(repository, AccountModel, country, orgField) {
 				} else throw err;
 			}
 		}
+		const summary = {
+			total: accounts.length,
+			created: results.created.length,
+			skipped: results.skipped.length,
+			errors: results.errors.length
+		};
+		await safePublish$3(events, outboxStore, LEDGER_EVENTS.ACCOUNT_BULK_CREATED, {
+			created: summary.created,
+			skipped: summary.skipped,
+			errors: summary.errors,
+			organizationId: orgId
+		}, { organizationId: orgId });
 		return {
-			summary: {
-				total: accounts.length,
-				created: results.created.length,
-				skipped: results.skipped.length,
-				errors: results.errors.length
-			},
+			summary,
 			...results
 		};
 	};
@@ -1107,6 +1143,15 @@ function wireAccountMethods(repository, AccountModel, country, orgField) {
 }
 //#endregion
 //#region src/repositories/journal.repository.ts
+async function safePublish$2(events, outboxStore, type, payload, ctx) {
+	const event = createEvent(type, payload, ctx);
+	if (outboxStore) try {
+		await outboxStore.save(event);
+	} catch {}
+	if (events) try {
+		await events.publish(event);
+	} catch {}
+}
 /**
 * Lean default set used when a country pack doesn't provide
 * `journalTemplates`. Covers the Stripe/QuickBooks/Xero baseline.
@@ -1148,9 +1193,11 @@ const DEFAULT_TEMPLATES = [
 		sequencePrefix: "JE"
 	}
 ];
-function wireJournalMethods(repository, country, orgField) {
+function wireJournalMethods(repository, country, orgField, integrations = {}) {
 	const create = repository.create.bind(repository);
 	const exists = repository.exists.bind(repository);
+	const events = integrations.events;
+	const outboxStore = integrations.outboxStore;
 	repository.seedDefaults = async (orgId) => {
 		requireOrgScope(orgField, orgId);
 		const templates = country.journalTemplates ?? DEFAULT_TEMPLATES;
@@ -1176,6 +1223,11 @@ function wireJournalMethods(repository, country, orgField) {
 			await create(data);
 			created += 1;
 		}
+		await safePublish$2(events, outboxStore, LEDGER_EVENTS.JOURNAL_SEEDED, {
+			created,
+			skipped,
+			organizationId: orgId
+		}, { organizationId: orgId });
 		return {
 			created,
 			skipped
@@ -1205,6 +1257,25 @@ function wireJournalMethods(repository, country, orgField) {
 }
 //#endregion
 //#region src/repositories/journal-entry.repository.ts
+/**
+* Publish a domain event. When an outbox store is provided, first persist
+* the event inside the caller's session (so outbox + ledger write commit
+* atomically), then fire-and-forget publish to the transport. Without an
+* outbox, publish-only, still fire-and-forget — transport errors never
+* propagate into ledger mutations.
+*
+* Tracks PACKAGE_RULES §16 (host-composed transactional outbox) and §14
+* (domain verbs publish via injected transport).
+*/
+async function safePublish$1(events, outboxStore, type, payload, ctx, meta) {
+	const event = createEvent(type, payload, ctx, meta);
+	if (outboxStore) try {
+		await outboxStore.save(event, { session: ctx?.session ?? void 0 });
+	} catch {}
+	if (events) try {
+		await events.publish(event);
+	} catch {}
+}
 /** Keys that are either handled explicitly or must not be copied */
 const ITEM_CORE_KEYS = new Set([
 	"account",
@@ -1227,11 +1298,58 @@ const ITEM_CORE_KEYS = new Set([
 * @param orgField - The multi-tenant field name (e.g. 'business')
 * @param strictness - Strictness rules (immutable, requireActor, requireApproval)
 */
-function wireJournalEntryMethods(repository, _JournalEntryModel, orgField, strictness) {
+function wireJournalEntryMethods(repository, _JournalEntryModel, orgField, strictness, integrations = {}) {
+	const events = integrations.events;
+	const outboxStore = integrations.outboxStore;
 	const getByQuery = repository.getByQuery.bind(repository);
-	const create = repository.create.bind(repository);
+	const baseCreate = repository.create.bind(repository);
 	const update = repository.update.bind(repository);
 	const withTransaction = repository.withTransaction.bind(repository);
+	const raceSafeCreate = async (data, options) => {
+		const input = data;
+		const idempotencyKey = typeof input.idempotencyKey === "string" && input.idempotencyKey.length > 0 ? input.idempotencyKey : void 0;
+		const orgValue = orgField ? input[orgField] : void 0;
+		if (idempotencyKey) {
+			const prequery = { idempotencyKey };
+			if (orgField && orgValue != null) prequery[orgField] = orgValue;
+			const existing = await getByQuery(prequery, {
+				lean: false,
+				throwOnNotFound: false,
+				...options?.session ? { session: options.session } : {}
+			});
+			if (existing) return existing;
+		}
+		try {
+			return await baseCreate(data, options);
+		} catch (err) {
+			if (err instanceof IdempotencyConflictError && err.existingId) {
+				const winner = await getByQuery({ _id: err.existingId }, {
+					lean: false,
+					throwOnNotFound: false,
+					...options?.session ? { session: options.session } : {}
+				});
+				if (winner) return winner;
+				throw err;
+			}
+			const dup = classifyDuplicateKey(err);
+			if (!dup) throw err;
+			if (dup.keyPattern?.referenceNumber) throw new DuplicateReferenceError(String(input.referenceNumber ?? ""));
+			if (dup.keyPattern?.idempotencyKey && idempotencyKey) {
+				const winnerQuery = { idempotencyKey };
+				if (orgField && orgValue != null) winnerQuery[orgField] = orgValue;
+				const winner = await getByQuery(winnerQuery, {
+					lean: false,
+					throwOnNotFound: false,
+					...options?.session ? { session: options.session } : {}
+				});
+				if (winner) return winner;
+				throw new IdempotencyConflictError(idempotencyKey, null);
+			}
+			throw Errors.conflict(`Journal entry write violated unique index ${dup.indexName}.`);
+		}
+	};
+	repository.create = raceSafeCreate.bind(repository);
+	const create = raceSafeCreate;
 	const RESERVED_TOPLEVEL = new Set([
 		"_id",
 		"__v",
@@ -1341,7 +1459,23 @@ function wireJournalEntryMethods(repository, _JournalEntryModel, orgField, stric
 			_ledgerInternal: "post",
 			...options.session ? { session: options.session } : {}
 		};
-		return await update(entry._id, patch, updateOptions) ?? entry;
+		const final = await update(entry._id, patch, updateOptions) ?? entry;
+		await safePublish$1(events, outboxStore, LEDGER_EVENTS.ENTRY_POSTED, {
+			entryId: final._id,
+			referenceNumber: final.referenceNumber,
+			postedBy: options.actorId,
+			totalDebit,
+			totalCredit,
+			organizationId: orgId
+		}, {
+			actorId: options.actorId,
+			organizationId: orgId,
+			session: options.session ?? null
+		}, {
+			resource: "journal-entry",
+			resourceId: String(final._id)
+		});
+		return final;
 	};
 	/**
 	* Unpost an entry (posted → draft).
@@ -1360,10 +1494,23 @@ function wireJournalEntryMethods(repository, _JournalEntryModel, orgField, stric
 			_ledgerInternal: "unpost",
 			...options.session ? { session: options.session } : {}
 		};
-		return await update(entry._id, {
+		const final = await update(entry._id, {
 			state: "draft",
 			stateChangedAt: /* @__PURE__ */ new Date()
 		}, updateOptions) ?? entry;
+		await safePublish$1(events, outboxStore, LEDGER_EVENTS.ENTRY_UNPOSTED, {
+			entryId: final._id,
+			unpostedBy: options.actorId,
+			organizationId: orgId
+		}, {
+			actorId: options.actorId,
+			organizationId: orgId,
+			session: options.session ?? null
+		}, {
+			resource: "journal-entry",
+			resourceId: String(final._id)
+		});
+		return final;
 	};
 	/**
 	* Archive a draft entry (draft → archived).
@@ -1380,10 +1527,23 @@ function wireJournalEntryMethods(repository, _JournalEntryModel, orgField, stric
 			_ledgerInternal: "archive",
 			...options.session ? { session: options.session } : {}
 		};
-		return await update(entry._id, {
+		const final = await update(entry._id, {
 			state: "archived",
 			stateChangedAt: /* @__PURE__ */ new Date()
 		}, updateOptions) ?? entry;
+		await safePublish$1(events, outboxStore, LEDGER_EVENTS.ENTRY_ARCHIVED, {
+			entryId: final._id,
+			archivedBy: options.actorId,
+			organizationId: orgId
+		}, {
+			actorId: options.actorId,
+			organizationId: orgId,
+			session: options.session ?? null
+		}, {
+			resource: "journal-entry",
+			resourceId: String(final._id)
+		});
+		return final;
 	};
 	/**
 	* Duplicate an entry as a new draft.
@@ -1414,7 +1574,21 @@ function wireJournalEntryMethods(repository, _JournalEntryModel, orgField, stric
 			})
 		};
 		copyExtraTopLevel(entry, duplicateData);
-		return await create(duplicateData, options.session ? { session: options.session } : {});
+		const duplicated = await create(duplicateData, options.session ? { session: options.session } : {});
+		const dup = duplicated;
+		await safePublish$1(events, outboxStore, LEDGER_EVENTS.ENTRY_DUPLICATED, {
+			sourceEntryId: entry._id,
+			duplicateEntryId: dup._id,
+			organizationId: orgId
+		}, {
+			actorId: void 0,
+			organizationId: orgId,
+			session: options.session ?? null
+		}, {
+			resource: "journal-entry",
+			resourceId: String(dup._id)
+		});
+		return duplicated;
 	};
 	/**
 	* Reverse a posted entry by creating a mirror entry with flipped debits/credits.
@@ -1477,8 +1651,23 @@ function wireJournalEntryMethods(repository, _JournalEntryModel, orgField, stric
 				_ledgerInternal: "reverseMark",
 				...session ? { session } : {}
 			};
+			const original = await update(entry._id, markPatch, markOptions) ?? entry;
+			await safePublish$1(events, outboxStore, LEDGER_EVENTS.ENTRY_REVERSED, {
+				originalEntryId: original._id,
+				reversalEntryId: reversalEntry._id,
+				reversalDate: reversalData.date ?? /* @__PURE__ */ new Date(),
+				reversedBy: options.actorId,
+				organizationId: orgId
+			}, {
+				actorId: options.actorId,
+				organizationId: orgId,
+				session: session ?? null
+			}, {
+				resource: "journal-entry",
+				resourceId: String(original._id)
+			});
 			return {
-				original: await update(entry._id, markPatch, markOptions) ?? entry,
+				original,
 				reversal: reversalEntry
 			};
 		};
@@ -1506,6 +1695,15 @@ function wireJournalEntryMethods(repository, _JournalEntryModel, orgField, stric
 }
 //#endregion
 //#region src/repositories/reconciliation.repository.ts
+async function safePublish(events, outboxStore, type, payload, ctx) {
+	const event = createEvent(type, payload, ctx);
+	if (outboxStore) try {
+		await outboxStore.save(event, { session: ctx?.session ?? void 0 });
+	} catch {}
+	if (events) try {
+		await events.publish(event);
+	} catch {}
+}
 /**
 * Default matching-number generator — atomic counter stored in the
 * reconciliation collection. Uses a dedicated sentinel document keyed
@@ -1537,10 +1735,14 @@ async function nextMatchingNumber(ReconciliationModel, orgField, orgId, session)
 	}).lean())?.seq ?? 1;
 	return `RECN-${String(seq).padStart(6, "0")}`;
 }
-function wireReconciliationMethods(repository, ReconciliationModel, JournalEntryModel, orgField) {
+function wireReconciliationMethods(repository, ReconciliationModel, JournalEntryModel, orgField, integrations = {}) {
 	const create = repository.create.bind(repository);
 	const deleteById = repository.delete.bind(repository);
 	const repoInstance = repository;
+	const events = integrations.events;
+	const outboxStore = integrations.outboxStore;
+	const notification = integrations.bridges?.notification;
+	const emitHook = repoInstance.emitAsync.bind(repoInstance);
 	repository.match = async (input) => {
 		const { account, items, note, reconciledBy, organizationId, session = null } = input;
 		let { matchingNumber } = input;
@@ -1585,6 +1787,17 @@ function wireReconciliationMethods(repository, ReconciliationModel, JournalEntry
 		const isFullReconcile = difference === 0;
 		const sharedCurrency = currencies.size === 1 ? Array.from(currencies)[0] : null;
 		if (!matchingNumber) matchingNumber = await nextMatchingNumber(ReconciliationModel, orgField, organizationId, session);
+		const hookCtx = {
+			input,
+			items: itemSnapshots,
+			sharedCurrency,
+			matchingNumber,
+			debitTotal,
+			creditTotal,
+			isFullReconcile,
+			session
+		};
+		await emitHook("before:match", hookCtx);
 		const bulkOps = itemSnapshots.map((snap) => ({ updateOne: {
 			filter: { _id: snap.entry },
 			update: { $set: { [`journalItems.${snap.itemIndex}.matchingNumber`]: matchingNumber } }
@@ -1612,13 +1825,33 @@ function wireReconciliationMethods(repository, ReconciliationModel, JournalEntry
 		};
 		if (orgField && organizationId != null) reconciliationData[orgField] = organizationId;
 		const record = await create(reconciliationData);
-		const emit = repoInstance._emitHook;
-		if (emit) await emit.call(repoInstance, "after:match", {
-			reconciliation: record,
-			items: itemSnapshots,
-			sharedCurrency,
+		await emitHook("after:match", {
+			...hookCtx,
+			reconciliation: record
+		});
+		await safePublish(events, outboxStore, LEDGER_EVENTS.RECONCILIATION_MATCHED, {
+			matchingNumber,
+			account,
+			itemCount: itemSnapshots.length,
+			debitTotal,
+			creditTotal,
+			isFullReconcile,
+			currency: sharedCurrency,
+			organizationId
+		}, {
+			organizationId,
 			session
 		});
+		if (!isFullReconcile && notification?.onReconciliationMismatch) try {
+			await notification.onReconciliationMismatch({
+				matchingNumber,
+				account,
+				debitTotal,
+				creditTotal,
+				difference,
+				currency: sharedCurrency
+			}, { organizationId });
+		} catch {}
 		return record;
 	};
 	repository.unmatch = async (input) => {
@@ -1628,13 +1861,31 @@ function wireReconciliationMethods(repository, ReconciliationModel, JournalEntry
 		if (orgField && organizationId != null) query[orgField] = organizationId;
 		const existing = await ReconciliationModel.findOne(query).session(session).lean();
 		if (!existing) throw Errors.notFound(`Reconciliation ${matchingNumber} not found`);
-		const bulkOps = (existing.items ?? []).map((it) => ({ updateOne: {
+		const items = existing.items ?? [];
+		const unmatchCtx = {
+			matchingNumber,
+			reconciliation: existing,
+			items,
+			organizationId,
+			session
+		};
+		await emitHook("before:unmatch", unmatchCtx);
+		const bulkOps = items.map((it) => ({ updateOne: {
 			filter: { _id: it.entry },
 			update: { $set: { [`journalItems.${it.itemIndex}.matchingNumber`]: null } }
 		} }));
 		if (bulkOps.length > 0) await JournalEntryModel.bulkWrite(bulkOps, { session: session ?? void 0 });
 		const result = await deleteById(String(existing._id));
 		if (!result.success) throw Errors.notFound("Failed to delete reconciliation record");
+		await emitHook("after:unmatch", unmatchCtx);
+		await safePublish(events, outboxStore, LEDGER_EVENTS.RECONCILIATION_UNMATCHED, {
+			matchingNumber,
+			itemCount: items.length,
+			organizationId
+		}, {
+			organizationId,
+			session
+		});
 		return result;
 	};
 	repository.getOpenItems = async (params) => {
@@ -1706,29 +1957,39 @@ function wireReconciliationMethods(repository, ReconciliationModel, JournalEntry
 * Matches the flow/promo pattern: engine owns the repositories with all
 * plugins (double-entry, fiscal-lock, idempotency) pre-wired.
 *
-* Consumer never constructs Repository, never calls wireXxx methods.
-* Just uses `engine.repositories.accounts.seedAccounts(orgId)`.
+* 0.9.0 additions:
+*   - Optional `multiTenantPlugin` adoption (config.multiTenant.plugin)
+*   - Optional `EventTransport` threaded to every wireXxxMethods call
+*   - Optional `LedgerBridges` threaded through so domain verbs can resolve
+*     external sources or send notifications without importing siblings.
 */
 /**
 * 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()
 */
-function createRepositories(models, config, plugins = {}, pagination = {}) {
+function createRepositories(models, config, plugins = {}, pagination = {}, integrations = {}) {
 	const orgField = config.multiTenant?.orgField;
 	const strictness = config.strictness;
 	const country = config.country;
+	const { events, bridges, outboxStore } = integrations;
+	const tenantPlugins = [];
+	if (orgField && config.multiTenant?.plugin) tenantPlugins.push(multiTenantPlugin({
+		tenantField: orgField,
+		contextKey: "organizationId",
+		required: config.multiTenant.required ?? false,
+		fieldType: config.tenantFieldType ?? "string"
+	}));
 	const accountPagination = pagination.account ?? {};
 	const jePagination = pagination.journalEntry ?? {};
 	const fpPagination = pagination.fiscalPeriod ?? {};
 	const budgetPagination = pagination.budget ?? {};
 	const reconPagination = pagination.reconciliation ?? {};
-	const accounts = wireAccountMethods(new Repository(models.Account, plugins.account ?? [], accountPagination), models.Account, country, orgField);
+	const accounts = wireAccountMethods(new Repository(models.Account, [...tenantPlugins, ...plugins.account ?? []], accountPagination), country, orgField, {
+		events,
+		bridges,
+		outboxStore
+	});
 	const jePlugins = [
+		...tenantPlugins,
 		...plugins.journalEntry ?? [],
 		doubleEntryPlugin({
 			JournalEntryModel: models.JournalEntry,
@@ -1745,10 +2006,22 @@ function createRepositories(models, config, plugins = {}, pagination = {}) {
 		JournalEntryModel: models.JournalEntry,
 		orgField
 	}));
-	const journalEntries = wireJournalEntryMethods(new Repository(models.JournalEntry, jePlugins, jePagination), models.JournalEntry, orgField, strictness);
-	const fiscalPeriods = new Repository(models.FiscalPeriod, plugins.fiscalPeriod ?? [], fpPagination);
-	const budgets = new Repository(models.Budget, plugins.budget ?? [], budgetPagination);
-	const reconciliations = wireReconciliationMethods(new Repository(models.Reconciliation, plugins.reconciliation ?? [], reconPagination), models.Reconciliation, models.JournalEntry, orgField);
+	if (strictness?.immutable) jePlugins.push(immutableGuardPlugin({
+		JournalEntryModel: models.JournalEntry,
+		orgField
+	}));
+	const journalEntries = wireJournalEntryMethods(new Repository(models.JournalEntry, jePlugins, jePagination), models.JournalEntry, orgField, strictness, {
+		events,
+		bridges,
+		outboxStore
+	});
+	const fiscalPeriods = new Repository(models.FiscalPeriod, [...tenantPlugins, ...plugins.fiscalPeriod ?? []], fpPagination);
+	const budgets = new Repository(models.Budget, [...tenantPlugins, ...plugins.budget ?? []], budgetPagination);
+	const reconciliations = wireReconciliationMethods(new Repository(models.Reconciliation, [...tenantPlugins, ...plugins.reconciliation ?? []], reconPagination), models.Reconciliation, models.JournalEntry, orgField, {
+		events,
+		bridges,
+		outboxStore
+	});
 	const journalPagination = pagination.journal ?? {};
 	return {
 		accounts,
@@ -1756,7 +2029,11 @@ function createRepositories(models, config, plugins = {}, pagination = {}) {
 		fiscalPeriods,
 		budgets,
 		reconciliations,
-		journals: wireJournalMethods(new Repository(models.Journal, plugins.journal ?? [], journalPagination), country, orgField)
+		journals: wireJournalMethods(new Repository(models.Journal, [...tenantPlugins, ...plugins.journal ?? []], journalPagination), country, orgField, {
+			events,
+			bridges,
+			outboxStore
+		})
 	};
 }
 //#endregion
@@ -2255,16 +2532,80 @@ function buildRecordAPI({ models, repositories, config }) {
 			journalItems: items
 		}, options);
 	};
+	const openingBalance = async (organizationId, input, options) => {
+		if (!input.balances || input.balances.length === 0) throw Errors.validation("Opening balance requires at least one account balance.", [{
+			path: "balances",
+			issue: "must contain at least 1 entry",
+			value: 0
+		}]);
+		const equityCode = input.equityAccount ?? config.country?.retainedEarningsAccountCode;
+		if (!equityCode) throw Errors.validation("Equity contra account code is required. Pass equityAccount or configure retainedEarningsAccountCode in the country pack.", [{
+			path: "equityAccount",
+			issue: "required",
+			value: void 0
+		}]);
+		const result = buildOpeningBalanceEntry({
+			cutoverDate: input.cutoverDate,
+			balances: input.balances.map((b) => ({
+				accountCode: b.account,
+				balance: b.balance
+			})),
+			equityAccountCode: equityCode,
+			label: input.label
+		});
+		const acctMap = await resolveAccounts(organizationId, result.entry.journalItems.map((item) => item.account), "balances", options?.session ?? null);
+		const items = result.entry.journalItems.map((item) => buildItem(acctMap.get(item.account), item.debit, item.credit, item.label));
+		return postEntry(organizationId, {
+			journalType: result.entry.journalType ?? "GENERAL",
+			date: result.entry.date,
+			label: result.entry.label,
+			journalItems: items,
+			...result.entry.extra
+		}, options);
+	};
 	return {
 		sale,
 		expense,
 		transfer,
 		payment,
-		adjustment
+		adjustment,
+		openingBalance
 	};
 }
 //#endregion
 //#region src/engine.ts
+/**
+* AccountingEngine — The main entry point for @classytic/ledger.
+*
+* The engine owns all models, repositories, and reports. Matches the
+* @classytic/flow and @classytic/promo pattern: pass a mongoose connection
+* in config, and everything is auto-wired.
+*
+* @example
+* ```typescript
+* import mongoose from 'mongoose';
+* import { createAccountingEngine } from '@classytic/ledger';
+* import { canadaPack } from '@classytic/ledger-ca';
+*
+* const engine = createAccountingEngine({
+*   mongoose: mongoose.connection,
+*   country: canadaPack,
+*   currency: 'CAD',
+*   multiTenant: { orgField: 'organizationId', orgRef: 'Organization' },
+* });
+*
+* // Models — auto-created Mongoose models
+* engine.models.Account
+* engine.models.JournalEntry
+*
+* // Repositories — plugins + domain methods pre-wired
+* await engine.repositories.accounts.seedAccounts(orgId);
+* await engine.repositories.journalEntries.post(entryId, orgId);
+*
+* // Reports — bound to owned models
+* const bs = await engine.reports.balanceSheet({ organizationId: orgId, dateOption: 'year', dateValue: 2025 });
+* ```
+*/
 var AccountingEngine = class {
 	config;
 	country;
@@ -2274,14 +2615,48 @@ var AccountingEngine = class {
 	repositories;
 	record;
 	introspect;
+	/**
+	* 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.*`, `*`.
+	*/
+	events;
+	/**
+	* Host-provided bridges. Empty object when none supplied. Callers should
+	* optional-chain every method (`engine.bridges.source?.resolve?.(...)`).
+	*/
+	bridges;
+	/**
+	* 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.
+	*/
+	outboxStore;
 	_reports;
 	constructor(config) {
 		if (!config.mongoose) throw new Error("createAccountingEngine: `mongoose` connection is required. Pass `mongoose: mongoose.connection` in config.");
 		this.config = config;
 		this.country = config.country;
 		this.currency = config.currency;
+		this.events = config.eventTransport ?? new InProcessLedgerBus();
+		this.bridges = config.bridges ?? {};
+		this.outboxStore = config.outboxStore;
 		this.models = createModels(config.mongoose, config);
-		this.repositories = createRepositories(this.models, config, config.plugins ?? {}, config.pagination ?? {});
+		this.repositories = createRepositories(this.models, config, config.plugins ?? {}, config.pagination ?? {}, {
+			events: this.events,
+			bridges: this.bridges,
+			outboxStore: this.outboxStore
+		});
+		if (config.syncIndexes) Promise.all([
+			this.models.Account.syncIndexes().catch(() => void 0),
+			this.models.JournalEntry.syncIndexes().catch(() => void 0),
+			this.models.FiscalPeriod.syncIndexes().catch(() => void 0),
+			this.models.Budget.syncIndexes().catch(() => void 0),
+			this.models.Reconciliation.syncIndexes().catch(() => void 0),
+			this.models.Journal.syncIndexes().catch(() => void 0)
+		]);
 		this.record = buildRecordAPI({
 			models: this.models,
 			repositories: this.repositories,
@@ -2313,6 +2688,60 @@ var AccountingEngine = class {
 	getAccountType(code) {
 		return this.country.getAccountType(code);
 	}
+	/**
+	* Create a pre-configured QueryParser for URL-driven queries against
+	* ledger repositories. Returns a mongokit QueryParser with the correct
+	* schema and pagination limits for the specified model.
+	*
+	* @param model - Which ledger model to parse queries for
+	* @param overrides - Additional QueryParserOptions to merge
+	*
+	* @example
+	* ```typescript
+	* const parser = engine.createQueryParser('journalEntry');
+	* const parsed = parser.parse(req.query);
+	* const result = await engine.repositories.journalEntries.getAll({
+	*   ...parsed,
+	*   filters: { ...parsed.filters, organizationId },
+	* });
+	* ```
+	*/
+	createQueryParser(model, overrides) {
+		const paginationConfig = this.config.pagination ?? {};
+		const entry = {
+			account: {
+				model: this.models.Account,
+				pagination: paginationConfig.account
+			},
+			journalEntry: {
+				model: this.models.JournalEntry,
+				pagination: paginationConfig.journalEntry
+			},
+			fiscalPeriod: {
+				model: this.models.FiscalPeriod,
+				pagination: paginationConfig.fiscalPeriod
+			},
+			budget: {
+				model: this.models.Budget,
+				pagination: paginationConfig.budget
+			},
+			reconciliation: {
+				model: this.models.Reconciliation,
+				pagination: paginationConfig.reconciliation
+			},
+			journal: {
+				model: this.models.Journal,
+				pagination: paginationConfig.journal
+			}
+		}[model];
+		if (!entry) throw new Error(`createQueryParser: unknown model "${model}"`);
+		return new QueryParser({
+			schema: entry.model.schema,
+			maxLimit: entry.pagination?.maxLimit ?? 100,
+			searchMode: "regex",
+			...overrides
+		});
+	}
 	_buildReports() {
 		const AccountModel = this.models.Account;
 		const JournalEntryModel = this.models.JournalEntry;
@@ -2452,4 +2881,4 @@ function buildDimensionIndexes(dimensions, orgField) {
 	});
 }
 //#endregion
-export { AccountingEngine, AccountingError, CATEGORIES, CATEGORY_KEYS, CURRENCIES, DEFAULT_BUCKETS, Errors, JOURNAL_CODES, JOURNAL_TYPES, Money, 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 { AccountingEngine, AccountingError, CATEGORIES, CATEGORY_KEYS, CURRENCIES, ConcurrencyError, DEFAULT_BUCKETS, DuplicateReferenceError, Errors, IdempotencyConflictError, ImmutableViolationError, InProcessLedgerBus, JOURNAL_CODES, JOURNAL_TYPES, LEDGER_EVENTS, Money, OutboxOwnershipError, 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 };