@classytic/ledger 0.10.3 → 0.12.0

package/dist/index.mjs

@@ -1,16 +1,15 @@
 import { _ as LEDGER_EVENTS, a as EntryArchived, c as EntryPosted, d as JournalSeeded, f as ReconciliationMatched, g as createEvent, h as InProcessLedgerBus, i as AccountSeeded, l as EntryReversed, m as ledgerEventDefinitions, n as OutboxOwnershipError, o as EntryCreated, p as ReconciliationUnmatched, r as AccountBulkCreated, s as EntryDuplicated, t as InvalidOutboxEventError, u as EntryUnposted } from "./outbox-store-BbKdQ2eT.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-vXd932rB.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 { 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, u as isReverseMarkClaim } from "./fx-realization.plugin-DY3pPxIi.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-OuPHPyS2.mjs";
 import { Money, add, allocate, format, formatPlain, fromDecimal, multiply, parseCents, percentage, splitTaxExclusive, splitTaxInclusive, subtract, toDecimal } from "./money.mjs";
-import { C as computeEndingBalance, D as requireOrgScope, E as generateAgedBalance, S as calculateTotal, T as DEFAULT_BUCKETS, _ as generateBalanceSheet, a as finalizeSession, b as getFiscalYearStart, c as generateRevaluation, d as generateIncomeStatement, f as generateGeneralLedger, g as generateBudgetVsActual, h as generateCashFlow, i as acquireSession, l as buildRevaluationEntry, m as generateDaybook, n as closeFiscalPeriod, o as defaultLogger, p as generateDimensionBreakdown, r as reopenFiscalPeriod, s as generateTrialBalance, t as generatePartnerLedger, u as computeRevaluation, v as buildItemFilters, w as isVirtualTaxAccount, x as buildAccountTypeMap, y as getDateRange } from "./partner-ledger-BIkmQsAc.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-Dzqzi3u0.mjs";
-import { t as buildOpeningBalanceEntry } from "./opening-balance-1cixYh6Y.mjs";
+import { C as computeEndingBalance, D as requireOrgScope, E as generateAgedBalance, S as calculateTotal, T as DEFAULT_BUCKETS, _ as generateBalanceSheet, a as finalizeSession, b as getFiscalYearStart, c as generateRevaluation, d as generateIncomeStatement, f as generateGeneralLedger, g as generateBudgetVsActual, h as generateCashFlow, i as acquireSession, l as buildRevaluationEntry, m as generateDaybook, n as closeFiscalPeriod, o as defaultLogger, p as generateDimensionBreakdown, r as reopenFiscalPeriod, s as generateTrialBalance, t as generatePartnerLedger, u as computeRevaluation, v as buildItemFilters, w as isVirtualTaxAccount, x as buildAccountTypeMap, y as getDateRange } from "./partner-ledger-B0eym6Ss.mjs";
+import { c as getNormalBalance, d as isValidCategory, l as isBalanceSheet, n as CATEGORY_KEYS, t as CATEGORIES, u as isIncomeStatement } from "./categories-CclX7Q94.mjs";
 import { defineCountryPack } from "./country/index.mjs";
-import { a as exportToCsv, i as quickbooksFieldMap, r as universalFieldMap, t as flattenJournalEntries } from "./exports-C30yRapf.mjs";
+import { a as exportToCsv, i as quickbooksFieldMap, r as universalFieldMap, t as flattenJournalEntries } from "./exports-B3whucXe.mjs";
 import { QueryParser, Repository, getNextSequence, multiTenantPlugin, withTransaction } from "@classytic/mongokit";
 import mongoose, { Schema } from "mongoose";
-import { resolveTenantConfig } from "@classytic/primitives/tenant";
+import { resolveTenantConfig } from "@classytic/repo-core/tenant";
 //#region src/plugins/immutable-guard.plugin.ts
 /**
 * Returns a mongokit plugin function. Install only when
@@ -35,13 +34,24 @@ function immutableGuardPlugin(options) {
 			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:claim", async (rawCtx) => {
+			const ctx = rawCtx;
+			if (ctx._ledgerInternal) return;
+			if (isReverseMarkClaim(ctx)) return;
+			const transition = ctx.transition;
+			if (!transition) return;
+			if ((transition.field ?? "state") !== "state") return;
+			const fromSpec = transition.from;
+			if (!(Array.isArray(fromSpec) ? fromSpec.includes("posted") : fromSpec === "posted")) return;
+			throw new ImmutableViolationError(ctx.id);
+		});
 	};
 }
 //#endregion
 //#region src/models/inject-tenant.ts
 /**
 * Mongoose-specific adapter around `resolveTenantConfig()` from
-* `@classytic/primitives/tenant`. The pure resolution lives in primitives
+* `@classytic/repo-core/tenant`. The pure resolution lives in primitives
 * (zero runtime deps) — this file only handles the Mongoose schema
 * mutations (add field, prepend tenant onto compound indexes) that
 * primitives can't own without a mongoose dependency.
@@ -134,22 +144,21 @@ function buildCurrencyField(config) {
 *
 * Creates a Mongoose schema for Chart of Accounts that is:
 * - Multi-tenant aware (adds org field + compound indexes when configured)
-* - Validates accountTypeCode against the country pack
 * - Supports accountNumber (unique per org) and name (user-facing display)
 * - Lean: no cached balances — always computed from journal entries
+*
+* Country-specific validation (accountTypeCode against the country pack) is
+* intentionally NOT done at the schema layer — schema validators are baked in
+* at model-registration time and would bleed across country engines that share
+* the same connection. Validation lives in wireAccountMethods.before:create.
 */
 function createAccountSchema(config, options = {}) {
-	const { country } = config;
 	const scope = resolveLedgerTenant(config);
 	const { indexes = true, extraFields = {}, extraIndexes = [] } = options;
 	const fields = {
 		accountTypeCode: {
 			type: String,
-			required: true,
-			validate: {
-				validator: (code) => country.isValidAccountType(code),
-				message: (props) => `"${props.value}" is not a valid account type code for ${country.name}.`
-			}
+			required: true
 		},
 		accountNumber: {
 			type: String,
@@ -166,6 +175,25 @@ function createAccountSchema(config, options = {}) {
 		isCashAccount: {
 			type: Boolean,
 			default: false
+		},
+		/**
+		* Optional per-account override for Cash Flow Statement classification.
+		* Wins over the country-pack `account_type` taxonomy. Use case: a
+		* "Long-term deferred revenue" account whose type would default to
+		* Financing but the business intent is Operating. Mirrors Xero's
+		* per-account Cash Flow category override; one of:
+		*   'operating' | 'investing' | 'financing' | 'excluded'
+		* `null` (default) → fall back to country-pack inference.
+		*/
+		cashflowSection: {
+			type: String,
+			enum: [
+				"operating",
+				"investing",
+				"financing",
+				"excluded"
+			],
+			default: null
 		}
 	};
 	const currencyField = buildCurrencyField(config);
@@ -174,10 +202,6 @@ function createAccountSchema(config, options = {}) {
 	const schema = new mongoose.Schema(fields, { timestamps: true });
 	schema.pre("validate", function() {
 		if (!this.accountNumber && this.accountTypeCode) this.accountNumber = this.accountTypeCode;
-		if (!this.name && this.accountTypeCode) {
-			const at = country.getAccountType(this.accountTypeCode);
-			this.name = at?.name ?? this.accountTypeCode;
-		}
 	});
 	if (indexes) {
 		schema.index({ active: 1 });
@@ -190,13 +214,6 @@ function createAccountSchema(config, options = {}) {
 }
 //#endregion
 //#region src/schemas/budget.schema.ts
-/**
-* Budget Schema Factory
-*
-* Creates a Mongoose schema for budget records.
-* Each record represents a budgeted amount for an account over a specific period.
-* All monetary amounts are in integer cents.
-*/
 function createBudgetSchema(config, options = {}) {
 	const scope = resolveLedgerTenant(config);
 	const { indexes = true, extraFields = {}, extraIndexes = [] } = options;
@@ -226,6 +243,10 @@ function createBudgetSchema(config, options = {}) {
 			type: String,
 			default: null
 		},
+		approvals: {
+			type: mongoose.Schema.Types.Mixed,
+			default: null
+		},
 		...extraFields
 	};
 	const schema = new mongoose.Schema(fields, { timestamps: true });
@@ -455,6 +476,47 @@ function createJournalSchema(config, accountModelName, options = {}) {
 * - Double-entry validation on post
 * - Optimized indexes for high-load reporting
 */
+/**
+* Recommended opt-in indexes for the line-level provenance fields
+* (`journalItems.sourceRef.*` + `journalItems.linkedRefs.*`).
+*
+* Schema fields ship in the core schema unconditionally. Index creation
+* costs writes on every JE insert, so the package ships them as opt-in:
+* spread this into `schemaOptions.journalEntry.extraIndexes` to enable
+* fast `/by-source` lookups against the line-level slots.
+*
+* Both indexes are sparse + partial — only lines that actually carry a
+* sourceModel are indexed. Hosts that never write line-level provenance
+* pay zero index storage / no insert overhead.
+*
+* @example
+*   import { createAccountingEngine, LINE_SOURCE_INDEXES } from '@classytic/ledger';
+*   createAccountingEngine({
+*     schemaOptions: {
+*       journalEntry: { extraIndexes: [...LINE_SOURCE_INDEXES] },
+*     },
+*   });
+*/
+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"
+	}
+}, {
+	fields: {
+		"journalItems.linkedRefs.sourceModel": 1,
+		"journalItems.linkedRefs.sourceId": 1
+	},
+	options: {
+		sparse: true,
+		name: "journalItems_linkedRefs_idx"
+	}
+}];
 function createJournalEntrySchema(config, accountModelName, options = {}) {
 	const { multiTenant } = config;
 	const scope = resolveLedgerTenant(config);
@@ -463,6 +525,16 @@ function createJournalEntrySchema(config, accountModelName, options = {}) {
 		taxCode: { type: String },
 		taxName: { type: String }
 	}, { _id: false });
+	const ItemSourceRefSchema = new mongoose.Schema({
+		sourceModel: {
+			type: String,
+			default: null
+		},
+		sourceId: {
+			type: String,
+			default: null
+		}
+	}, { _id: false });
 	const amountValidator = {
 		validator: (v) => Number.isInteger(v) && v >= 0,
 		message: "{PATH} must be a non-negative integer (cents), got {VALUE}"
@@ -526,6 +598,18 @@ function createJournalEntrySchema(config, accountModelName, options = {}) {
 			type: Date,
 			default: null
 		},
+		meta: {
+			type: mongoose.Schema.Types.Mixed,
+			default: null
+		},
+		sourceRef: {
+			type: ItemSourceRefSchema,
+			default: () => ({})
+		},
+		linkedRefs: {
+			type: [ItemSourceRefSchema],
+			default: void 0
+		},
 		...currencyItemFields,
 		...extraItemFields
 	}, { _id: false });
@@ -600,6 +684,10 @@ function createJournalEntrySchema(config, accountModelName, options = {}) {
 			ref: "JournalEntry",
 			default: null
 		},
+		approvals: {
+			type: mongoose.Schema.Types.Mixed,
+			default: null
+		},
 		...extraFields
 	};
 	if (config.audit?.trackActor) {
@@ -702,14 +790,6 @@ function createJournalEntrySchema(config, accountModelName, options = {}) {
 			state: 1
 		});
 		schema.index({ reversed: 1 });
-		if (config.idempotency) {
-			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" } }
-			});
-		}
 	}
 	if (textSearch) schema.index({
 		referenceNumber: "text",
@@ -897,9 +977,14 @@ 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);
+//#region src/utils/safe-publish.ts
+/**
+* Persist and publish a ledger domain event without letting delivery failures
+* break the write path. When an outbox is configured, the outbox row is saved
+* first and participates in the caller's mongoose session.
+*/
+async function safePublish(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 {}
@@ -907,6 +992,8 @@ async function safePublish$3(events, outboxStore, type, payload, ctx) {
 		await events.publish(event);
 	} catch {}
 }
+//#endregion
+//#region src/repositories/account.repository.ts
 function isDuplicateKeyBulkError(err) {
 	if (!err || typeof err !== "object") return false;
 	const e = err;
@@ -928,9 +1015,13 @@ function wireAccountMethods(repository, country, orgField, integrations = {}) {
 	const outboxStore = integrations.outboxStore;
 	const journalEntryModel = integrations.journalEntryModel;
 	repository.on("before:create", async (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.`);
 		const data = ctx.data;
+		const code = 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.`);
+		if (data && !data.name && code) {
+			const at = country.getAccountType(code);
+			if (at) data.name = at.name ?? code;
+		}
 		if (!data) return;
 		const accountNumber = data.accountNumber ?? code;
 		if (!accountNumber) return;
@@ -994,7 +1085,7 @@ function wireAccountMethods(repository, country, orgField, integrations = {}) {
 				};
 			} else throw err;
 		}
-		await safePublish$3(events, outboxStore, LEDGER_EVENTS.ACCOUNT_SEEDED, {
+		await safePublish(events, outboxStore, LEDGER_EVENTS.ACCOUNT_SEEDED, {
 			created: result.created,
 			skipped: result.skipped,
 			organizationId: orgId
@@ -1020,7 +1111,7 @@ function wireAccountMethods(repository, country, orgField, integrations = {}) {
 		};
 		const validAccounts = [];
 		for (let i = 0; i < accounts.length; i++) {
-			const { accountTypeCode, accountNumber, name, active = true, isCashAccount = false } = accounts[i];
+			const { accountTypeCode, accountNumber, name, active = true, isCashAccount } = accounts[i];
 			if (!accountTypeCode) {
 				results.errors.push({
 					index: i,
@@ -1047,13 +1138,14 @@ function wireAccountMethods(repository, country, orgField, integrations = {}) {
 			}
 			const resolvedNumber = accountNumber ?? accountTypeCode;
 			const resolvedName = name ?? at.name ?? accountTypeCode;
+			const resolvedIsCash = isCashAccount === void 0 ? Boolean(at.isCashAccount) : Boolean(isCashAccount);
 			validAccounts.push({
 				index: i,
 				accountTypeCode,
 				accountNumber: resolvedNumber,
 				name: resolvedName,
 				active: Boolean(active),
-				isCashAccount: Boolean(isCashAccount)
+				isCashAccount: resolvedIsCash
 			});
 		}
 		if (validAccounts.length === 0) return {
@@ -1144,7 +1236,7 @@ function wireAccountMethods(repository, country, orgField, integrations = {}) {
 			skipped: results.skipped.length,
 			errors: results.errors.length
 		};
-		await safePublish$3(events, outboxStore, LEDGER_EVENTS.ACCOUNT_BULK_CREATED, {
+		await safePublish(events, outboxStore, LEDGER_EVENTS.ACCOUNT_BULK_CREATED, {
 			created: summary.created,
 			skipped: summary.skipped,
 			errors: summary.errors,
@@ -1168,15 +1260,6 @@ function wireAccountMethods(repository, country, orgField, integrations = {}) {
 }
 //#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.
@@ -1248,7 +1331,7 @@ function wireJournalMethods(repository, country, orgField, integrations = {}) {
 			await create(data);
 			created += 1;
 		}
-		await safePublish$2(events, outboxStore, LEDGER_EVENTS.JOURNAL_SEEDED, {
+		await safePublish(events, outboxStore, LEDGER_EVENTS.JOURNAL_SEEDED, {
 			created,
 			skipped,
 			organizationId: orgId
@@ -1282,25 +1365,6 @@ function wireJournalMethods(repository, country, orgField, integrations = {}) {
 }
 //#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",
@@ -1328,7 +1392,8 @@ function wireJournalEntryMethods(repository, _JournalEntryModel, orgField, stric
 	const outboxStore = integrations.outboxStore;
 	const getByQuery = repository.getByQuery.bind(repository);
 	const baseCreate = repository.create.bind(repository);
-	const update = repository.update.bind(repository);
+	repository.update.bind(repository);
+	const claim = repository.claim.bind(repository);
 	const withTransaction$1 = (fn, opts) => withTransaction(repository.Model.db, fn, opts);
 	const raceSafeCreate = async (data, options) => {
 		const input = data;
@@ -1433,13 +1498,37 @@ function wireJournalEntryMethods(repository, _JournalEntryModel, orgField, stric
 		return await getByQuery(query, opts);
 	}
 	/**
+	* Build the options bag passed to `repo.claim()` from the call's
+	* org/actor/session context. mongokit's `multiTenantPlugin` reads
+	* `options.organizationId`, audit plugins read `options.userId`, and
+	* the transaction layer reads `options.session` — same shape we'd
+	* forward via `repoOptionsFromCtx(ctx)` from a host route.
+	*/
+	function buildClaimOptions(orgId, actorId, session) {
+		const opts = {};
+		if (session) opts.session = session;
+		if (orgField && orgId != null) opts.organizationId = orgId;
+		if (actorId !== void 0 && actorId !== null) opts.userId = actorId;
+		return opts;
+	}
+	/**
+	* Build the `where` predicate for a state-transition claim. Encodes the
+	* tenant-scope guard so the CAS only matches docs in the caller's org.
+	*/
+	function buildClaimWhere(orgId, extra) {
+		const where = { ...extra ?? {} };
+		if (orgField && orgId != null) where[orgField] = orgId;
+		return where;
+	}
+	/**
 	* Post an entry (draft → posted).
 	* Validates items, balance, and accounts before changing state.
 	*/
 	repository.post = async (id, orgId, options = {}) => {
 		if (strictness?.requireActor && !options.actorId) throw Errors.validation("actorId is required for post operations.");
 		requireOrgScope(orgField, orgId);
-		const entry = await findEntry(buildQuery(id, orgId), {
+		const query = buildQuery(id, orgId);
+		const entry = await findEntry(query, {
 			session: options.session,
 			populate: "journalItems.account"
 		});
@@ -1475,17 +1564,22 @@ function wireJournalEntryMethods(repository, _JournalEntryModel, orgField, stric
 		const totalDebit = entry.journalItems.reduce((s, i) => s + (i.debit || 0), 0);
 		const totalCredit = entry.journalItems.reduce((s, i) => s + (i.credit || 0), 0);
 		if (totalDebit !== totalCredit) throw Errors.validation(`Entry is not balanced. Debit: ${totalDebit}, Credit: ${totalCredit}`);
-		const patch = {
-			state: "posted",
-			stateChangedAt: /* @__PURE__ */ new Date()
-		};
-		if (options.actorId) patch.postedBy = options.actorId;
-		const updateOptions = {
-			_ledgerInternal: "post",
-			...options.session ? { session: options.session } : {}
-		};
-		const final = await update(entry._id, patch, updateOptions) ?? entry;
-		await safePublish$1(events, outboxStore, LEDGER_EVENTS.ENTRY_POSTED, {
+		const $set = { stateChangedAt: /* @__PURE__ */ new Date() };
+		if (options.actorId) $set.postedBy = options.actorId;
+		const claimed = await claim(entry._id, {
+			field: "state",
+			from: "draft",
+			to: "posted",
+			where: buildClaimWhere(orgId)
+		}, { $set }, buildClaimOptions(orgId, options.actorId, options.session ?? null));
+		let final;
+		if (!claimed) {
+			const reread = await findEntry(query, { session: options.session });
+			if (reread && reread.state === "posted") final = reread;
+			else if (reread) throw new ConcurrencyError("JournalEntry", String(entry._id));
+			else throw Errors.notFound("Entry not found");
+		} else final = claimed;
+		await safePublish(events, outboxStore, LEDGER_EVENTS.ENTRY_POSTED, {
 			entryId: final._id,
 			referenceNumber: final.referenceNumber,
 			postedBy: options.actorId,
@@ -1511,19 +1605,25 @@ function wireJournalEntryMethods(repository, _JournalEntryModel, orgField, stric
 		if (strictness?.immutable) throw Errors.immutable("Unpost is disabled in strict mode. Use reverse() to correct posted entries.");
 		if (strictness?.requireActor && !options.actorId) throw Errors.validation("actorId is required for unpost operations.");
 		requireOrgScope(orgField, orgId);
-		const entry = await findEntry(buildQuery(id, orgId), { session: options.session });
+		const query = buildQuery(id, orgId);
+		const entry = await findEntry(query, { session: options.session });
 		if (!entry) throw Errors.notFound("Entry not found");
 		if (entry.state !== "posted") throw Errors.validation("Only posted entries can be unposted");
 		if (entry.reversed) throw Errors.validation("Cannot unpost a reversed entry. The reversal entry is still posted and linked to this entry. Reverse the reversal entry first, or create a new correcting entry instead.");
-		const updateOptions = {
-			_ledgerInternal: "unpost",
-			...options.session ? { session: options.session } : {}
-		};
-		const final = await update(entry._id, {
-			state: "draft",
-			stateChangedAt: /* @__PURE__ */ new Date()
-		}, updateOptions) ?? entry;
-		await safePublish$1(events, outboxStore, LEDGER_EVENTS.ENTRY_UNPOSTED, {
+		const claimed = await claim(entry._id, {
+			field: "state",
+			from: "posted",
+			to: "draft",
+			where: buildClaimWhere(orgId, { reversed: { $ne: true } })
+		}, { $set: { stateChangedAt: /* @__PURE__ */ new Date() } }, buildClaimOptions(orgId, options.actorId, options.session ?? null));
+		let final;
+		if (!claimed) {
+			const reread = await findEntry(query, { session: options.session });
+			if (reread && reread.state === "draft") final = reread;
+			else if (reread) throw new ConcurrencyError("JournalEntry", String(entry._id));
+			else throw Errors.notFound("Entry not found");
+		} else final = claimed;
+		await safePublish(events, outboxStore, LEDGER_EVENTS.ENTRY_UNPOSTED, {
 			entryId: final._id,
 			unpostedBy: options.actorId,
 			organizationId: orgId
@@ -1545,18 +1645,24 @@ function wireJournalEntryMethods(repository, _JournalEntryModel, orgField, stric
 	repository.archive = async (id, orgId, options = {}) => {
 		if (strictness?.requireActor && !options.actorId) throw Errors.validation("actorId is required for archive operations.");
 		requireOrgScope(orgField, orgId);
-		const entry = await findEntry(buildQuery(id, orgId), { session: options.session });
+		const query = buildQuery(id, orgId);
+		const entry = await findEntry(query, { session: options.session });
 		if (!entry) throw Errors.notFound("Entry not found");
 		if (entry.state !== "draft") throw Errors.validation("Only draft entries can be archived");
-		const updateOptions = {
-			_ledgerInternal: "archive",
-			...options.session ? { session: options.session } : {}
-		};
-		const final = await update(entry._id, {
-			state: "archived",
-			stateChangedAt: /* @__PURE__ */ new Date()
-		}, updateOptions) ?? entry;
-		await safePublish$1(events, outboxStore, LEDGER_EVENTS.ENTRY_ARCHIVED, {
+		const claimed = await claim(entry._id, {
+			field: "state",
+			from: "draft",
+			to: "archived",
+			where: buildClaimWhere(orgId)
+		}, { $set: { stateChangedAt: /* @__PURE__ */ new Date() } }, buildClaimOptions(orgId, options.actorId, options.session ?? null));
+		let final;
+		if (!claimed) {
+			const reread = await findEntry(query, { session: options.session });
+			if (reread && reread.state === "archived") final = reread;
+			else if (reread) throw new ConcurrencyError("JournalEntry", String(entry._id));
+			else throw Errors.notFound("Entry not found");
+		} else final = claimed;
+		await safePublish(events, outboxStore, LEDGER_EVENTS.ENTRY_ARCHIVED, {
 			entryId: final._id,
 			archivedBy: options.actorId,
 			organizationId: orgId
@@ -1601,7 +1707,7 @@ function wireJournalEntryMethods(repository, _JournalEntryModel, orgField, stric
 		copyExtraTopLevel(entry, duplicateData);
 		const duplicated = await create(duplicateData, options.session ? { session: options.session } : {});
 		const dup = duplicated;
-		await safePublish$1(events, outboxStore, LEDGER_EVENTS.ENTRY_DUPLICATED, {
+		await safePublish(events, outboxStore, LEDGER_EVENTS.ENTRY_DUPLICATED, {
 			sourceEntryId: entry._id,
 			duplicateEntryId: dup._id,
 			organizationId: orgId
@@ -1655,29 +1761,39 @@ function wireJournalEntryMethods(repository, _JournalEntryModel, orgField, stric
 			const totalCredit = reversalItems.reduce((s, i) => s + i.credit, 0);
 			const reversalData = {
 				journalType: entry.journalType ?? "MISC",
-				state: "posted",
 				date: options.reversalDate ?? /* @__PURE__ */ new Date(),
 				label: `Reversal of ${entry.referenceNumber ?? entry._id}`,
 				journalItems: reversalItems,
 				totalDebit,
 				totalCredit,
-				reversalOf: entry._id,
-				stateChangedAt: /* @__PURE__ */ new Date()
+				reversalOf: entry._id
 			};
 			copyExtraTopLevel(entry, reversalData);
-			if (options.actorId) reversalData.postedBy = options.actorId;
-			const reversalEntry = await create(reversalData, session ? { session } : {});
-			const markPatch = {
+			let reversalEntry = await create(reversalData, session ? { session } : {});
+			const postFn = repository.post;
+			if (options.autoPost && postFn) {
+				const posted = await postFn(reversalEntry._id, orgId, {
+					actorId: options.actorId,
+					...session ? { session } : {}
+				});
+				if (posted) reversalEntry = posted;
+			}
+			const $set = {
 				reversed: true,
 				reversedBy: reversalEntry._id
 			};
-			if (options.actorId) markPatch.reversedByUser = options.actorId;
-			const markOptions = {
-				_ledgerInternal: "reverseMark",
-				...session ? { session } : {}
-			};
-			const original = await update(entry._id, markPatch, markOptions) ?? entry;
-			await safePublish$1(events, outboxStore, LEDGER_EVENTS.ENTRY_REVERSED, {
+			if (options.actorId) $set.reversedByUser = options.actorId;
+			const claimOpts = {};
+			if (session) claimOpts.session = session;
+			if (orgField && orgId != null) claimOpts.organizationId = orgId;
+			if (options.actorId) claimOpts.userId = options.actorId;
+			const original = await claim(entry._id, {
+				field: "state",
+				from: "posted",
+				to: "posted",
+				where: { reversed: { $ne: true } }
+			}, { $set }, claimOpts) ?? entry;
+			await safePublish(events, outboxStore, LEDGER_EVENTS.ENTRY_REVERSED, {
 				originalEntryId: original._id,
 				reversalEntryId: reversalEntry._id,
 				reversalDate: reversalData.date ?? /* @__PURE__ */ new Date(),
@@ -1720,44 +1836,54 @@ 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
-* `{ matchingNumber: '__counter__', [org]: orgId }` so each org has its
-* own counter, safe under concurrent match calls.
+* Reconciliation Repository Factory (0.6.0 — item-level open-item matching)
+*
+* Implements the three new primitives:
+*
+*   - `match({ account, items, ... })` stamps a shared matchingNumber onto
+*     every referenced item and creates a reconciliation document.
+*     Triggers `after:match` hook for downstream plugins (fxRealization,
+*     cash-basis exigibility).
+*
+*   - `unmatch({ matchingNumber })` clears the matching number from every
+*     referenced item and removes the reconciliation. If an FX realization
+*     entry was booked, it is reversed via journalEntries.reverse.
+*
+*   - `getOpenItems({ accountId })` returns posted journal items against
+*     the account that have no matchingNumber yet. Backed by the sparse
+*     index on `journalItems.matchingNumber`.
+*
+* Matching numbers auto-generate as `RECN-{n}` if the caller doesn't
+* supply one. Uniqueness is enforced by the org-scoped unique index on
+* the reconciliation collection.
 */
-async function nextMatchingNumber(ReconciliationModel, orgField, orgId, session) {
-	const counterQuery = { matchingNumber: "__counter__" };
-	if (orgField && orgId != null) counterQuery[orgField] = orgId;
-	const seq = (await ReconciliationModel.findOneAndUpdate(counterQuery, {
-		$inc: { seq: 1 },
-		$setOnInsert: {
-			account: null,
-			items: [{
-				entry: null,
-				itemIndex: 0
-			}, {
-				entry: null,
-				itemIndex: 1
-			}],
-			debitTotal: 0,
-			creditTotal: 0
-		}
-	}, {
-		new: true,
-		upsert: true,
-		session,
-		strict: false
-	}).lean())?.seq ?? 1;
+/**
+* Default matching-number generator — delegates to mongokit's
+* `getNextSequence(counterKey, 1, connection, session)` which atomically
+* bumps a counter row in the shared `_mongokit_counters` collection. Same
+* primitive that backs `journalEntries.referenceNumber` allocation in this
+* package (see `journal-entry.schema.ts:431`) and the per-package id
+* generators in `@classytic/invoice`, `order`, `cart`, `revenue`.
+*
+* Why this replaced the in-collection sentinel pattern (pre-0.10.4): the
+* sentinel approach stored the counter as a synthetic `matchingNumber:
+* '__counter__'` doc in the reconciliation collection itself, with the
+* counter slot as `seq`. After the 0.10.x refactor that routed the bump
+* through `repository.findOneAndUpdate(...)` (to flow through the plugin
+* pipeline), mongoose strict mode silently dropped `$inc: { seq: 1 }`
+* because `seq` was never declared in the schema — every call returned
+* `undefined`, fell back to `1`, and every match resolved to `RECN-000001`.
+* The first match per engine succeeded; the second collided on the unique
+* index. `getNextSequence` sidesteps this entirely: dedicated counter
+* collection, no schema pollution, session-aware (counter rolls back if
+* the calling transaction aborts), multi-tenant via key prefix.
+*/
+async function nextMatchingNumber(connection, orgField, orgId, session) {
+	let orgScope = "global";
+	if (orgField && orgId != null) orgScope = typeof orgId.toHexString === "function" ? orgId.toHexString() : String(orgId);
+	else if (orgField) orgScope = "unscoped";
+	const seq = await getNextSequence(`ledger:${orgScope}:matchingNumber`, 1, connection, session ?? void 0);
 	return `RECN-${String(seq).padStart(6, "0")}`;
 }
 function wireReconciliationMethods(repository, ReconciliationModel, JournalEntryModel, orgField, integrations = {}) {
@@ -1811,7 +1937,7 @@ function wireReconciliationMethods(repository, ReconciliationModel, JournalEntry
 		const difference = debitTotal - creditTotal;
 		const isFullReconcile = difference === 0;
 		const sharedCurrency = currencies.size === 1 ? Array.from(currencies)[0] : null;
-		if (!matchingNumber) matchingNumber = await nextMatchingNumber(ReconciliationModel, orgField, organizationId, session);
+		if (!matchingNumber) matchingNumber = await nextMatchingNumber(ReconciliationModel.db, orgField, organizationId, session);
 		const hookCtx = {
 			input,
 			items: itemSnapshots,
@@ -1901,7 +2027,7 @@ function wireReconciliationMethods(repository, ReconciliationModel, JournalEntry
 		} }));
 		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");
+		if (!result) throw Errors.notFound("Failed to delete reconciliation record");
 		await emitHook("after:unmatch", unmatchCtx);
 		await safePublish(events, outboxStore, LEDGER_EVENTS.RECONCILIATION_UNMATCHED, {
 			matchingNumber,
@@ -2390,6 +2516,65 @@ function buildIntrospectAPI({ models, country, config }) {
 	};
 }
 //#endregion
+//#region src/builders/opening-balance.ts
+function buildOpeningBalanceEntry(input) {
+	const { cutoverDate, balances, equityAccountCode } = input;
+	const dateStr = cutoverDate.toISOString().split("T")[0];
+	const label = input.label ?? `Opening Balance — Cutover ${dateStr}`;
+	const items = [];
+	let totalDebit = 0;
+	let totalCredit = 0;
+	for (const { accountCode, balance } of balances) {
+		if (balance === 0) continue;
+		if (balance > 0) {
+			items.push({
+				account: accountCode,
+				debit: balance,
+				credit: 0,
+				label: "Opening balance"
+			});
+			totalDebit += balance;
+		} else {
+			const absBalance = Math.abs(balance);
+			items.push({
+				account: accountCode,
+				debit: 0,
+				credit: absBalance,
+				label: "Opening balance"
+			});
+			totalCredit += absBalance;
+		}
+	}
+	const residual = totalDebit - totalCredit;
+	const lineCount = items.length;
+	if (residual > 0) items.push({
+		account: equityAccountCode,
+		debit: 0,
+		credit: residual,
+		label: "Opening balance equity (contra)"
+	});
+	else if (residual < 0) items.push({
+		account: equityAccountCode,
+		debit: Math.abs(residual),
+		credit: 0,
+		label: "Opening balance equity (contra)"
+	});
+	return {
+		entry: {
+			date: cutoverDate,
+			label,
+			journalType: "GENERAL",
+			journalItems: items,
+			extra: {
+				_externalId: `opening-balance:${dateStr}`,
+				_importSource: "opening-balance"
+			}
+		},
+		residual,
+		lineCount
+	};
+}
+//#endregion
 //#region src/semantic/record.ts
 function buildRecordAPI({ models, repositories, config }) {
 	const AccountModel = models.Account;
@@ -2931,4 +3116,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, Money, OutboxOwnershipError, ReconciliationMatched, ReconciliationUnmatched, 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, 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, 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 };