@happyvertical/smrt-expenses 0.57.3 → 0.57.4

package/dist/chunks/Expense-C_WC5VLF.js

@@ -0,0 +1,1364 @@
+import { ExpenseError } from "../types.js";
+import { ObjectRegistry, SmrtObject, crossPackageRef, field, foreignKey, isPostgresDatabase, isUniqueViolationError, smrt } from "@happyvertical/smrt-core";
+import { TenantScoped, getTenantId, tenantId } from "@happyvertical/smrt-tenancy";
+import { ContractLineItemCollection, PurchaseContractCollection, VendorCollection } from "@happyvertical/smrt-commerce";
+import { createHash, randomUUID } from "node:crypto";
+//#region src/validation.ts
+var CATEGORY_PATTERN = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+var ISO_CURRENCY = /^[A-Z]{3}$/;
+var ISO_DATE = /^(\d{4})-(\d{2})-(\d{2})$/;
+var QUALIFIED_CLASS = /^[^\s:]+:[A-Za-z_$][\w$]*$/;
+var SHA256_HEX = /^[0-9a-f]{64}$/;
+function assertMinorUnits(model, label, fieldName, value, code = "EXPENSE_INVALID") {
+	if (!Number.isSafeInteger(value) || value < 0) throw new ExpenseError(code, `${model} ${label}: ${fieldName} must be a non-negative integer number of minor units (cents) \u2014 got ${value}. $19.99 is 1999.`);
+}
+function assertIsoCurrency(model, label, value) {
+	if (!ISO_CURRENCY.test(value)) throw new ExpenseError("EXPENSE_INVALID", `${model} ${label}: currency must be a three-letter ISO 4217 code (for example 'USD'), got '${value}'.`);
+}
+function assertIsoDate(model, label, fieldName, value) {
+	const match = ISO_DATE.exec(value);
+	if (!(match !== null && (() => {
+		const [year, month, day] = match.slice(1).map(Number);
+		const date = new Date(Date.UTC(year, month - 1, day));
+		return date.getUTCFullYear() === year && date.getUTCMonth() === month - 1 && date.getUTCDate() === day;
+	})())) throw new ExpenseError("EXPENSE_INVALID", `${model} ${label}: ${fieldName} must be a calendar date written YYYY-MM-DD, got '${value}'.`);
+}
+function assertQualifiedClassName(model, label, value) {
+	if (!QUALIFIED_CLASS.test(value)) throw new ExpenseError("EXPENSE_INVALID", `${model} ${label}: costObjectType must be a qualified class name such as '@happyvertical/smrt-projects:Project', got '${value}'.`);
+}
+function normalizeSha256(model, label, value) {
+	const digest = String(value ?? "").trim().toLowerCase();
+	if (!SHA256_HEX.test(digest)) throw new ExpenseError("EXPENSE_RECEIPT_INVALID", `${model} ${label}: contentSha256 must be a 64-character hex SHA-256 digest of the file bytes.`);
+	return digest;
+}
+function computeContentSha256(data) {
+	return createHash("sha256").update(data).digest("hex");
+}
+function instantMs(value) {
+	if (value === null || value === void 0 || value === "") return null;
+	const ms = value instanceof Date ? value.getTime() : new Date(String(value)).getTime();
+	return Number.isNaN(ms) ? null : ms;
+}
+async function pinNaturalKey(model, object, persisted) {
+	await object.getSlug();
+	if (!object.isPersisted) {
+		if (persisted) throw new ExpenseError("EXPENSE_IDENTITY_CONFLICT", `${model} ${object.id} already exists; load it and save the loaded instance instead of creating one with its id.`);
+		object.requireInsertOnSave();
+		return true;
+	}
+	if (persisted && (String(persisted.slug ?? "") !== String(object.slug ?? "") || String(persisted.context ?? "") !== String(object.context ?? ""))) throw new ExpenseError("EXPENSE_IDENTITY_CONFLICT", `${model} ${object.id}: slug and context cannot change; they would point the save at a different row.`);
+	return false;
+}
+function identityConflict(model, object, cause) {
+	return new ExpenseError("EXPENSE_IDENTITY_CONFLICT", `${model} ${object.id}: another row already uses slug '${object.slug}' in this tenant; a new ${model} cannot take it over.`, { cause });
+}
+function effectiveTenant(tenantId) {
+	return tenantId || getTenantId() || null;
+}
+function normalizeTenantId(tenantId) {
+	return tenantId || null;
+}
+//#endregion
+//#region src/financial-facts.ts
+function invalid$2(message) {
+	throw new ExpenseError("EXPENSE_INVALID", `Expense financial breakdown: ${message}`);
+}
+function record(value, keys) {
+	if (!value || typeof value !== "object" || Array.isArray(value)) return invalid$2("expected an object.");
+	const object = value;
+	if (Object.keys(object).length !== keys.length || keys.some((key) => !Object.hasOwn(object, key))) return invalid$2("missing or unknown fields.");
+	return object;
+}
+function minor$1(value) {
+	if (typeof value !== "number" || !Number.isSafeInteger(value)) return invalid$2("amounts must be safe integer minor units.");
+	return BigInt(value);
+}
+function safe$1(value) {
+	const result = Number(value);
+	if (!Number.isSafeInteger(result)) return invalid$2("unsafe calculated amount.");
+	return result;
+}
+function expenseCostBasis(value, amount, currency) {
+	const facts = record(value, [
+		"currency",
+		"subtotal",
+		"taxes",
+		"total"
+	]);
+	if (typeof facts.currency !== "string" || facts.currency !== currency) return invalid$2("currency must match the expense.");
+	assertIsoCurrency("Expense", "<financial-breakdown>", facts.currency);
+	const total = minor$1(facts.total);
+	const subtotal = minor$1(facts.subtotal);
+	if (total !== minor$1(amount)) return invalid$2("total must match the expense amount.");
+	const consistent = (part) => part === 0n || (total > 0n ? part > 0n : total < 0n && part < 0n);
+	if (!consistent(subtotal)) return invalid$2("subtotal sign must match total.");
+	if (!Array.isArray(facts.taxes)) return invalid$2("taxes must be an explicit array.");
+	let tax = 0n;
+	let recoverable = 0n;
+	const codes = /* @__PURE__ */ new Set();
+	for (const item of facts.taxes) {
+		const component = record(item, [
+			"code",
+			"amount",
+			"recoverableAmount"
+		]);
+		if (typeof component.code !== "string" || !/^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/.test(component.code) || component.code.length > 64 || codes.has(component.code)) return invalid$2("tax codes must be unique lower-case kebab-case identifiers.");
+		codes.add(component.code);
+		const charged = minor$1(component.amount);
+		const recovered = minor$1(component.recoverableAmount);
+		const chargedMagnitude = charged < 0n ? -charged : charged;
+		const recoveredMagnitude = recovered < 0n ? -recovered : recovered;
+		if (!consistent(charged) || !consistent(recovered) || recoveredMagnitude > chargedMagnitude) return invalid$2("tax and recovery must share the total sign, with recovery bounded by tax.");
+		tax += charged;
+		recoverable += recovered;
+	}
+	if (subtotal + tax !== total) return invalid$2("subtotal plus taxes must equal total.");
+	return {
+		currency,
+		subtotal: safe$1(subtotal),
+		taxTotal: safe$1(tax),
+		recoverableTax: safe$1(recoverable),
+		nonRecoverableTax: safe$1(tax - recoverable),
+		total: safe$1(total),
+		costBasis: safe$1(total - recoverable)
+	};
+}
+function parseExpenseFinancialBreakdown(stored, amount, currency) {
+	if (stored === "" || stored === null || stored === void 0) return null;
+	if (typeof stored !== "string") return invalid$2("storage must be JSON text.");
+	let parsed;
+	try {
+		parsed = JSON.parse(stored);
+	} catch {
+		return invalid$2("invalid JSON.");
+	}
+	expenseCostBasis(parsed, amount, currency);
+	return parsed;
+}
+//#endregion
+//#region src/refund-position.ts
+function invalid$1(message) {
+	throw new ExpenseError("EXPENSE_INVALID", `Expense refund: ${message}`);
+}
+function safe(value) {
+	const result = Number(value);
+	if (!Number.isSafeInteger(result)) invalid$1("unsafe calculated amount.");
+	return result;
+}
+function calculateRefundPosition(source, refunds) {
+	if (!Number.isSafeInteger(source.amount) || source.amount <= 0) invalid$1("source must remain positive.");
+	const sourceFacts = source.getFinancialBreakdown();
+	let refunded = 0n;
+	let subtotal = 0n;
+	let complete = sourceFacts !== null;
+	const components = new Map(sourceFacts?.taxes.map((tax) => [tax.code, {
+		charged: 0n,
+		recovered: 0n
+	}]));
+	const ids = /* @__PURE__ */ new Set();
+	for (const refund of refunds) {
+		if (ids.has(refund.id)) invalid$1("duplicate refund identity.");
+		ids.add(refund.id);
+		if (!Number.isSafeInteger(refund.amount) || refund.amount >= 0 || refund.currency !== source.currency) invalid$1("linked refunds must be negative and share source currency.");
+		refunded -= BigInt(refund.amount);
+		const facts = refund.getFinancialBreakdown();
+		if (!facts) {
+			complete = false;
+			continue;
+		}
+		expenseCostBasis(facts, refund.amount, source.currency);
+		if (!sourceFacts) continue;
+		subtotal -= BigInt(facts.subtotal);
+		for (const tax of facts.taxes) {
+			const sum = components.get(tax.code);
+			if (!sum) invalid$1(`tax component ${tax.code} does not identify a source component.`);
+			sum.charged -= BigInt(tax.amount);
+			sum.recovered -= BigInt(tax.recoverableAmount);
+		}
+	}
+	if (refunded > BigInt(source.amount)) invalid$1("cumulative cash exceeds source gross.");
+	if (sourceFacts) {
+		expenseCostBasis(sourceFacts, source.amount, source.currency);
+		if (subtotal > BigInt(sourceFacts.subtotal)) invalid$1("subtotal reversal exceeds source subtotal.");
+		for (const tax of sourceFacts.taxes) {
+			const sum = components.get(tax.code);
+			if (!sum) invalid$1("missing source component.");
+			if (sum.charged > BigInt(tax.amount) || sum.recovered > BigInt(tax.recoverableAmount) || sum.charged - sum.recovered > BigInt(tax.amount - tax.recoverableAmount)) invalid$1(`tax component ${tax.code} reversal exceeds its source component.`);
+		}
+	}
+	const position = {
+		sourceId: source.id,
+		currency: source.currency,
+		sourceAmount: source.amount,
+		refundedAmount: safe(refunded),
+		remainingAmount: safe(BigInt(source.amount) - refunded),
+		refundIds: [...ids].sort(),
+		financialPosition: null
+	};
+	if (complete && sourceFacts) {
+		const reversal = {
+			currency: source.currency,
+			subtotal: safe(-subtotal),
+			taxes: sourceFacts.taxes.map((tax) => {
+				const sum = components.get(tax.code);
+				if (!sum) invalid$1("missing source component.");
+				return {
+					code: tax.code,
+					amount: safe(-sum.charged),
+					recoverableAmount: safe(-sum.recovered)
+				};
+			}),
+			total: safe(-refunded)
+		};
+		const remaining = {
+			currency: source.currency,
+			subtotal: safe(BigInt(sourceFacts.subtotal) - subtotal),
+			taxes: sourceFacts.taxes.map((tax, index) => ({
+				code: tax.code,
+				amount: tax.amount + reversal.taxes[index].amount,
+				recoverableAmount: tax.recoverableAmount + reversal.taxes[index].recoverableAmount
+			})),
+			total: position.remainingAmount
+		};
+		expenseCostBasis(remaining, remaining.total, source.currency);
+		position.financialPosition = {
+			source: sourceFacts,
+			refunded: reversal,
+			remaining
+		};
+	}
+	return position;
+}
+//#endregion
+//#region src/reimbursement-position.ts
+function invalid(message) {
+	throw new ExpenseError("EXPENSE_INVALID", `Expense reimbursement: ${message}`);
+}
+function parseRefundRecipient(stored) {
+	if (stored === null || stored === "") return null;
+	let value;
+	try {
+		value = JSON.parse(stored);
+	} catch {
+		return invalid("invalid recipient JSON.");
+	}
+	if (!value || typeof value !== "object" || Array.isArray(value)) invalid("recipient must be an object.");
+	const object = value;
+	if (object.kind === "company" && Object.keys(object).length === 1) return { kind: "company" };
+	if (object.kind === "person" && Object.keys(object).length === 2 && typeof object.profileId === "string" && /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(object.profileId)) return {
+		kind: "person",
+		profileId: object.profileId
+	};
+	if (object.kind === "third-party" && Object.keys(object).length === 2 && typeof object.name === "string" && object.name.trim().length > 0 && object.name.length <= 200) return {
+		kind: "third-party",
+		name: object.name
+	};
+	return invalid("recipient must explicitly identify company, person profile or a third-party name (1–200 characters).");
+}
+function calculateReimbursementPosition(source, refunds) {
+	if (!Number.isSafeInteger(source.amount) || source.amount <= 0 || source.paidBy !== "person" || !source.paidByProfileId || !source.reimbursable) invalid("requires a positive person-paid reimbursable source.");
+	let person = 0n;
+	let company = 0n;
+	let reason = null;
+	for (const refund of refunds) {
+		const recipient = refund.getRefundRecipient();
+		if (!recipient) reason ??= "unknown-refund-recipient";
+		else if (recipient.kind === "company") company -= BigInt(refund.amount);
+		else if (recipient.kind === "third-party") reason ??= "unknown-third-party-recipient";
+		else if (recipient.profileId === source.paidByProfileId) person -= BigInt(refund.amount);
+		else reason ??= "recipient-is-another-person";
+	}
+	if (source.reimbursedAmount !== null && (!source.reimbursedAt || !Number.isSafeInteger(source.reimbursedAmount) || source.reimbursedAmount <= 0 || source.reimbursedAmount > source.amount)) invalid("retained paid amount is inconsistent with original gross claim.");
+	const paid = source.reimbursedAt ? source.reimbursedAmount : 0;
+	if (paid === null) reason = "legacy-reimbursement-amount";
+	const net = reason || paid === null ? null : BigInt(source.amount) - person - BigInt(paid);
+	const safe = (amount) => {
+		const value = Number(amount);
+		if (!Number.isSafeInteger(value)) invalid("unsafe cash position.");
+		return value;
+	};
+	return {
+		sourceId: source.id,
+		currency: source.currency,
+		sourceAmount: source.amount,
+		personRefundAmount: reason ? null : safe(person),
+		companyRefundAmount: reason ? null : safe(company),
+		reimbursedAmount: paid,
+		remainingAmount: net === null ? null : safe(net > 0n ? net : 0n),
+		owedToCompany: net === null ? null : safe(net < 0n ? -net : 0n),
+		unknownReason: reason
+	};
+}
+//#endregion
+//#region src/supplier-payable.ts
+function payableInvalid(message) {
+	throw new ExpenseError("EXPENSE_INVALID", `Supplier payable: ${message}`);
+}
+function text(value, label) {
+	if (typeof value !== "string" || !value.trim() || value.length > 2e3) payableInvalid(`${label} must be explicit bounded evidence.`);
+}
+function minor(value) {
+	if (typeof value !== "number" || !Number.isSafeInteger(value) || value < 0) payableInvalid("amounts must be nonnegative safe minor units.");
+}
+function source(value) {
+	if (!value || typeof value !== "object") payableInvalid("original source is required.");
+	for (const key of [
+		"namespace",
+		"key",
+		"version"
+	]) text(value[key], key);
+	if (value.author !== null) text(value.author, "original author");
+}
+function review(value, expense) {
+	text(value.requestId, "requestId");
+	text(value.evidenceRef, "review evidence");
+	if (!/^[\da-f]{8}-[\da-f]{4}-[\da-f]{4}-[\da-f]{4}-[\da-f]{12}$/i.test(value.recordedByProfileId)) payableInvalid("current recorder must be an explicit profile UUID.");
+	if (value.currency !== expense.currency) payableInvalid("currency must equal the Expense currency.");
+}
+function payableDigest(value) {
+	const canonical = (item) => {
+		if (item === null || typeof item === "string" || typeof item === "boolean") return JSON.stringify(item);
+		if (typeof item === "number" && Number.isSafeInteger(item)) return JSON.stringify(item);
+		if (Array.isArray(item)) return `[${item.map(canonical).join(",")}]`;
+		if (item && typeof item === "object" && Object.getPrototypeOf(item) === Object.prototype) return `{${Object.keys(item).sort().map((key) => `${JSON.stringify(key)}:${canonical(item[key])}`).join(",")}}`;
+		return payableInvalid("evidence must be exact JSON values.");
+	};
+	return createHash("sha256").update(canonical(value)).digest("hex");
+}
+function payableExpenseFingerprint(expense) {
+	return payableDigest({
+		id: expense.id,
+		tenantId: expense.tenantId,
+		amount: expense.amount,
+		currency: expense.currency,
+		incurredOn: expense.incurredOn,
+		refundOfId: expense.refundOfId,
+		financialBreakdown: expense.financialBreakdown,
+		refundRecipient: expense.refundRecipient,
+		vendorId: expense.vendorId,
+		costObjectType: expense.costObjectType,
+		costObjectId: expense.costObjectId,
+		paidBy: expense.paidBy,
+		paidByProfileId: expense.paidByProfileId,
+		paidByName: expense.paidByName
+	});
+}
+function parseSupplierPayable(stored) {
+	if (stored === null || stored === "") return null;
+	let value;
+	try {
+		value = JSON.parse(stored);
+	} catch {
+		return payableInvalid("invalid retained JSON.");
+	}
+	if (!value || value.version !== 1 || !value.original || !Array.isArray(value.events) || !value.expenseId || !value.expenseFingerprint) payableInvalid("invalid retained authority.");
+	return value;
+}
+function validateEvent(event, expense, original) {
+	if (!event || typeof event !== "object") payableInvalid("event is required.");
+	assertIsoDate("Expense", String(expense.id), "supplier payable event date", event.effectiveOn);
+	if (event.effectiveOn < expense.incurredOn) payableInvalid("event precedes the original expense date.");
+	if (!Number.isSafeInteger(event.sequence) || event.sequence < 0) payableInvalid("explicit event sequence is required.");
+	text(event.evidenceRef, "event evidence");
+	if (original || event.source) source(event.source);
+	if ([
+		"hold",
+		"release",
+		"settlement"
+	].includes(event.kind)) {
+		minor(event.amountMinor);
+		if (!event.amountMinor) payableInvalid("event amount must be positive.");
+	} else if (event.kind === "refund") {
+		text(event.refundExpenseId, "refund Expense identity");
+		minor(event.payableReductionMinor);
+		minor(event.retainedReductionMinor);
+		minor(event.cashReturnedMinor);
+		if (event.retainedReductionMinor > event.payableReductionMinor) payableInvalid("retained reduction exceeds the explicit payable reduction.");
+	} else payableInvalid("unsupported event kind.");
+}
+function bindEvent(event, expense, refunds, original, input, fingerprint) {
+	validateEvent(event, expense, original);
+	let refundFingerprint;
+	if (event.kind === "refund") {
+		const refund = refunds.find((row) => row.id === event.refundExpenseId);
+		if (!refund || refund.refundOfId !== expense.id || refund.tenantId !== expense.tenantId || refund.currency !== expense.currency || refund.amount >= 0) payableInvalid("refund must be an actual same-owner linked negative Expense.");
+		if (event.effectiveOn !== refund.incurredOn) payableInvalid("refund interpretation must preserve its actual effective date.");
+		if (event.payableReductionMinor > -refund.amount || event.cashReturnedMinor > -refund.amount) payableInvalid("refund interpretation exceeds its actual gross magnitude.");
+		refundFingerprint = payableExpenseFingerprint(refund);
+	}
+	return {
+		...event,
+		id: randomUUID(),
+		authority: original ? "original" : "current",
+		requestId: input.requestId,
+		requestFingerprint: fingerprint,
+		recordedByProfileId: input.recordedByProfileId,
+		recordedAt: (/* @__PURE__ */ new Date()).toISOString(),
+		...refundFingerprint ? { refundFingerprint } : {}
+	};
+}
+function createSupplierPayable(expense, input, refunds) {
+	if (!expense.id || expense.amount <= 0 || expense.refundOfId) payableInvalid("requires a persisted positive non-refund Expense.");
+	review(input, expense);
+	source(input.source);
+	if (input.payableBasisMinor !== null) {
+		minor(input.payableBasisMinor);
+		if (input.payableBasisMinor > expense.amount) payableInvalid("basis exceeds original gross.");
+	}
+	if (!Array.isArray(input.events)) payableInvalid("original events must be explicit.");
+	const fingerprint = payableDigest(input);
+	const state = {
+		version: 1,
+		expenseId: expense.id,
+		currency: expense.currency,
+		expenseFingerprint: payableExpenseFingerprint(expense),
+		original: {
+			id: randomUUID(),
+			requestId: input.requestId,
+			requestFingerprint: fingerprint,
+			source: input.source,
+			payableBasisMinor: input.payableBasisMinor,
+			recordedByProfileId: input.recordedByProfileId,
+			evidenceRef: input.evidenceRef,
+			recordedAt: (/* @__PURE__ */ new Date()).toISOString()
+		},
+		completion: null,
+		events: input.events.map((event) => bindEvent(event, expense, refunds, true, input, fingerprint))
+	};
+	supplierPayablePosition(expense, state, refunds);
+	return state;
+}
+function appendSupplierPayableEvent(expense, state, input, refunds) {
+	review(input, expense);
+	const fingerprint = payableDigest(input);
+	const existing = state.events.find((event) => event.requestId === input.requestId);
+	if (existing || state.original.requestId === input.requestId || state.completion?.requestId === input.requestId) {
+		if (existing?.authority === "current" && existing.requestFingerprint === fingerprint) return state;
+		return payableInvalid("request identity conflicts with retained authority.");
+	}
+	const before = supplierPayablePosition(expense, state, refunds);
+	if (input.event?.kind === "release" && before.unresolvedRefundExpenseIds.length) payableInvalid("release requires every linked refund interpretation.");
+	if (input.event?.kind === "settlement" && before.unknownReasons.length) payableInvalid("settlement requires known basis and every linked refund interpretation.");
+	const next = {
+		...state,
+		events: [...state.events, bindEvent(input.event, expense, refunds, false, input, fingerprint)]
+	};
+	supplierPayablePosition(expense, next, refunds);
+	return next;
+}
+function completeSupplierPayable(expense, state, input, refunds) {
+	review(input, expense);
+	minor(input.payableBasisMinor);
+	const fingerprint = payableDigest(input);
+	if (state.completion?.requestId === input.requestId && state.completion.requestFingerprint === fingerprint) return state;
+	if (state.original.payableBasisMinor !== null || state.completion || state.original.requestId === input.requestId || state.events.some((event) => event.requestId === input.requestId)) payableInvalid("original basis or its explicit completion is immutable.");
+	if (input.payableBasisMinor > expense.amount) payableInvalid("basis exceeds original gross.");
+	const next = {
+		...state,
+		completion: {
+			...input,
+			id: randomUUID(),
+			requestFingerprint: fingerprint,
+			recordedAt: (/* @__PURE__ */ new Date()).toISOString()
+		}
+	};
+	supplierPayablePosition(expense, next, refunds);
+	return next;
+}
+function supplierPayablePosition(expense, state, refunds, asOfDate) {
+	if (asOfDate) assertIsoDate("Expense", String(expense.id), "supplier payable as-of date", asOfDate);
+	if (state.expenseId !== expense.id || state.currency !== expense.currency || state.expenseFingerprint !== payableExpenseFingerprint(expense)) payableInvalid("canonical Expense authority changed.");
+	const basis = state.completion?.payableBasisMinor ?? state.original.payableBasisMinor;
+	if (basis !== null) {
+		minor(basis);
+		if (basis > expense.amount) payableInvalid("basis exceeds original gross.");
+	}
+	const tuples = /* @__PURE__ */ new Set(), originalKeys = /* @__PURE__ */ new Set(), refundIds = /* @__PURE__ */ new Set();
+	let held = 0n, released = 0n, retainedReduction = 0n, settled = 0n, cashReturned = 0n, reduction = 0n;
+	let projected = {
+		held,
+		released,
+		retainedReduction,
+		settled,
+		cashReturned,
+		reduction
+	};
+	for (const event of [...state.events].sort((a, b) => a.effectiveOn.localeCompare(b.effectiveOn) || a.sequence - b.sequence)) {
+		validateEvent(event, expense, event.authority === "original");
+		const tuple = `${event.effectiveOn}:${event.sequence}`;
+		if (tuples.has(tuple)) payableInvalid("same-day chronology requires unique explicit sequence.");
+		tuples.add(tuple);
+		if (event.source) {
+			const key = payableDigest([event.source.namespace, event.source.key]);
+			if (originalKeys.has(key)) payableInvalid("duplicate original event identity.");
+			originalKeys.add(key);
+		}
+		if (event.kind === "hold") held += BigInt(event.amountMinor);
+		else if (event.kind === "release") released += BigInt(event.amountMinor);
+		else if (event.kind === "settlement") settled += BigInt(event.amountMinor);
+		else if (event.kind === "refund") {
+			if (refundIds.has(event.refundExpenseId)) payableInvalid("refund already has a retained interpretation.");
+			refundIds.add(event.refundExpenseId);
+			const refund = refunds.find((row) => row.id === event.refundExpenseId);
+			if (!refund || event.refundFingerprint !== payableExpenseFingerprint(refund)) payableInvalid("interpreted refund authority changed or disappeared.");
+			if (event.payableReductionMinor > -refund.amount || event.cashReturnedMinor > -refund.amount) payableInvalid("refund interpretation exceeds source magnitude.");
+			reduction += BigInt(event.payableReductionMinor);
+			retainedReduction += BigInt(event.retainedReductionMinor);
+			cashReturned += BigInt(event.cashReturnedMinor);
+		}
+		const retained2 = held - released - retainedReduction, paid2 = settled - cashReturned, obligation = BigInt(basis ?? expense.amount) - reduction;
+		if (retained2 < 0n || paid2 < 0n || obligation < 0n || obligation - paid2 - retained2 < 0n) payableInvalid("dated event exceeds retained, paid or payable capacity.");
+		for (const value of [
+			held,
+			released,
+			retainedReduction,
+			settled,
+			cashReturned,
+			reduction
+		]) if (value > BigInt(Number.MAX_SAFE_INTEGER)) payableInvalid("unsafe aggregate money.");
+		if (!asOfDate || event.effectiveOn <= asOfDate) projected = {
+			held,
+			released,
+			retainedReduction,
+			settled,
+			cashReturned,
+			reduction
+		};
+	}
+	const unresolved = refunds.filter((row) => (!asOfDate || row.incurredOn <= asOfDate) && !refundIds.has(String(row.id))).map((row) => String(row.id));
+	const unknownReasons = [];
+	if (basis === null) unknownReasons.push("payable-basis-unknown");
+	if (unresolved.length) unknownReasons.push("refund-interpretation-required");
+	const p = projected, retained = p.held - p.released - p.retainedReduction, paid = p.settled - p.cashReturned;
+	return {
+		expenseId: state.expenseId,
+		currency: state.currency,
+		asOfDate: asOfDate ?? null,
+		payableBasisMinor: basis,
+		heldMinor: Number(p.held),
+		releasedMinor: Number(p.released),
+		retainedReductionMinor: Number(p.retainedReduction),
+		recordedRetainedMinor: Number(retained),
+		retainedMinor: unresolved.length ? null : Number(retained),
+		settledMinor: Number(p.settled),
+		cashReturnedMinor: Number(p.cashReturned),
+		netPaidMinor: unresolved.length ? null : Number(paid),
+		payableReductionMinor: Number(p.reduction),
+		remainingPayableMinor: unknownReasons.length ? null : Number(BigInt(basis) - p.reduction - paid - retained),
+		unknownReasons,
+		unresolvedRefundExpenseIds: unresolved,
+		authority: state
+	};
+}
+//#endregion
+//#region src/models/Expense.ts
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __defNormalProp = (obj, key, value) => key in obj ? __defProp(obj, key, {
+	enumerable: true,
+	configurable: true,
+	writable: true,
+	value
+}) : obj[key] = value;
+var __decorateClass = (decorators, target, key, kind) => {
+	var result = kind > 1 ? void 0 : kind ? __getOwnPropDesc(target, key) : target;
+	for (var i = decorators.length - 1, decorator; i >= 0; i--) if (decorator = decorators[i]) result = (kind ? decorator(target, key, result) : decorator(result)) || result;
+	if (kind && result) __defProp(target, key, result);
+	return result;
+};
+var __publicField = (obj, key, value) => __defNormalProp(obj, typeof key !== "symbol" ? key + "" : key, value);
+var authorizedPayable = /* @__PURE__ */ new WeakMap();
+var PROFILE = "@happyvertical/smrt-profiles:Profile";
+var REVIEW_TRANSITIONS = {
+	review: {
+		from: ["unreviewed"],
+		to: "reviewed"
+	},
+	reject: {
+		from: ["unreviewed", "reviewed"],
+		to: "rejected"
+	},
+	markDuplicate: {
+		from: ["unreviewed", "reviewed"],
+		to: "rejected"
+	},
+	reopen: {
+		from: ["reviewed", "rejected"],
+		to: "unreviewed"
+	}
+};
+var LOCKED_WHEN_REVIEWED = [
+	["amount", "amount"],
+	["financialBreakdown", "financial_breakdown"],
+	["paidByName", "paid_by_name"],
+	["refundOfId", "refund_of_id"],
+	["refundRecipient", "refund_recipient"],
+	["currency", "currency"],
+	["incurredOn", "incurred_on"],
+	["recordedAt", "recorded_at"],
+	["category", "category"],
+	["costObjectType", "cost_object_type"],
+	["costObjectId", "cost_object_id"],
+	["vendorId", "vendor_id"],
+	["commitmentId", "commitment_id"],
+	["commitmentLineId", "commitment_line_id"],
+	["paidBy", "paid_by"],
+	["paidByProfileId", "paid_by_profile_id"]
+];
+var authorizedTransition = /* @__PURE__ */ new WeakMap();
+var authorizedReimbursement = /* @__PURE__ */ new WeakMap();
+function sameReviewState(a, b) {
+	return a.status === b.status && a.reviewer === b.reviewer && a.reviewedAtMs === b.reviewedAtMs && a.note === b.note && a.duplicateOf === b.duplicateOf;
+}
+function asNullableString(value) {
+	return value === null || value === void 0 || value === "" ? null : String(value);
+}
+var Expense = class extends SmrtObject {
+	tenantId = null;
+	costObjectType = "";
+	costObjectId = "";
+	category = "other";
+	description = "";
+	amount = 0;
+	currency = "";
+	financialBreakdown = null;
+	supplierPayableJson = null;
+	paidByName = null;
+	refundOfId = null;
+	refundRecipient = null;
+	incurredOn = "";
+	recordedAt = null;
+	recordedByProfileId = null;
+	paidBy = "company";
+	paidByProfileId = null;
+	vendorId = null;
+	commitmentId = null;
+	commitmentLineId = null;
+	reviewStatus = "unreviewed";
+	reviewedByProfileId = null;
+	reviewedAt = null;
+	reviewNote = "";
+	duplicateOfId = null;
+	reimbursable = false;
+	reimbursedAmount = null;
+	reimbursedAt = null;
+	reimbursementReference = "";
+	constructor(options = {}) {
+		super(options);
+		if (options.tenantId !== void 0) this.tenantId = options.tenantId;
+		if (options.costObjectType !== void 0) this.costObjectType = options.costObjectType;
+		if (options.costObjectId !== void 0) this.costObjectId = options.costObjectId;
+		if (options.category !== void 0) this.category = options.category;
+		if (options.description !== void 0) this.description = options.description;
+		if (options.amount !== void 0) this.amount = options.amount;
+		if (options.currency !== void 0) this.currency = options.currency;
+		if (options.financialBreakdown !== void 0) this.financialBreakdown = options.financialBreakdown;
+		if (options.paidByName !== void 0) this.paidByName = options.paidByName;
+		if (options.supplierPayableJson !== void 0) this.supplierPayableJson = options.supplierPayableJson;
+		if (options.refundOfId !== void 0) this.refundOfId = options.refundOfId;
+		if (options.incurredOn !== void 0) this.incurredOn = options.incurredOn;
+		if (options.recordedAt !== void 0) this.recordedAt = options.recordedAt;
+		if (options.recordedByProfileId !== void 0) this.recordedByProfileId = options.recordedByProfileId;
+		if (options.paidBy !== void 0) this.paidBy = options.paidBy;
+		if (options.paidByProfileId !== void 0) this.paidByProfileId = options.paidByProfileId;
+		if (options.vendorId !== void 0) this.vendorId = options.vendorId;
+		if (options.commitmentId !== void 0) this.commitmentId = options.commitmentId;
+		if (options.commitmentLineId !== void 0) this.commitmentLineId = options.commitmentLineId;
+		if (options.reimbursable !== void 0) this.reimbursable = options.reimbursable;
+		if (options.refundRecipient !== void 0) this.refundRecipient = options.refundRecipient;
+		if (options.reimbursedAmount !== void 0) this.reimbursedAmount = options.reimbursedAmount;
+		if (options.reimbursedAt !== void 0) this.reimbursedAt = options.reimbursedAt;
+		if (options.reimbursementReference !== void 0) this.reimbursementReference = options.reimbursementReference;
+	}
+	/** Read validated supplier facts, or null when none were recorded. */
+	getFinancialBreakdown() {
+		return parseExpenseFinancialBreakdown(this.financialBreakdown, this.amount, this.currency);
+	}
+	/** Set complete supplier facts; null explicitly clears facts on an unreviewed row. */
+	setFinancialBreakdown(value) {
+		if (value === null) {
+			this.financialBreakdown = null;
+			return;
+		}
+		expenseCostBasis(value, this.amount, this.currency);
+		this.financialBreakdown = JSON.stringify(value);
+	}
+	/** Explicit recipient, independent of this expense's payer facts. */
+	getRefundRecipient() {
+		return parseRefundRecipient(this.refundRecipient);
+	}
+	setRefundRecipient(value) {
+		const stored = value === null ? null : JSON.stringify(value);
+		parseRefundRecipient(stored);
+		this.refundRecipient = stored;
+	}
+	/** Return exact retained purchase cost; legacy unknown tax facts return null. */
+	getCostBasis() {
+		const facts = this.getFinancialBreakdown();
+		return facts === null ? null : expenseCostBasis(facts, this.amount, this.currency);
+	}
+	/** True when the person who paid has been paid back. */
+	isReimbursed() {
+		return this.reimbursedAt !== null && this.reimbursedAt !== void 0;
+	}
+	/** True when this expense counts toward reviewed totals and drawdown. */
+	isCountable() {
+		return this.reviewStatus === "reviewed" && !this.duplicateOfId;
+	}
+	/**
+	* Accept the expense as a real cost: `unreviewed → reviewed`.
+	*
+	* This is the separately authorizable review action: gate it in your route
+	* or service (for example on `expenses.review`). The expense must already
+	* be saved and must not be marked a duplicate.
+	*
+	* @throws {ExpenseError} `EXPENSE_REVIEW_TRANSITION` from any other state.
+	*/
+	async review(input) {
+		const reviewer = requireReviewer(input?.reviewerProfileId);
+		return this.transition("review", () => {
+			this.reviewStatus = "reviewed";
+			this.reviewedByProfileId = reviewer;
+			this.reviewedAt = input.at ?? /* @__PURE__ */ new Date();
+			this.reviewNote = input.note ?? "";
+			this.duplicateOfId = null;
+		});
+	}
+	/**
+	* Refuse the expense: `unreviewed | reviewed → rejected`. A rejected
+	* expense is kept and shown, and never counted.
+	*
+	* @throws {ExpenseError} `EXPENSE_REVIEW_TRANSITION` from `rejected`, or
+	*   `EXPENSE_INVALID` without a reason.
+	*/
+	async reject(input) {
+		const reviewer = requireReviewer(input?.reviewerProfileId);
+		const reason = (input.reason ?? "").trim();
+		if (!reason) throw new ExpenseError("EXPENSE_INVALID", "A rejection needs a reason.");
+		return this.transition("reject", () => {
+			this.reviewStatus = "rejected";
+			this.reviewedByProfileId = reviewer;
+			this.reviewedAt = input.at ?? /* @__PURE__ */ new Date();
+			this.reviewNote = reason;
+			this.duplicateOfId = null;
+		});
+	}
+	/**
+	* Mark this expense a duplicate of another expense in the same tenant:
+	* `unreviewed | reviewed → rejected` with {@link Expense.duplicateOfId}
+	* set. A duplicate never counts toward any total.
+	*
+	* @throws {ExpenseError} `EXPENSE_INVALID` when the target is this expense
+	*   or is not visible in this expense's tenant.
+	*/
+	async markDuplicate(input) {
+		const reviewer = requireReviewer(input?.reviewerProfileId);
+		const targetId = String(input.duplicateOfId ?? "").trim();
+		if (!targetId || targetId === this.id) throw new ExpenseError("EXPENSE_INVALID", "An expense can only be a duplicate of a different expense.");
+		const { ExpenseCollection } = await import("../index.js").then((n) => n.t);
+		const target = await (await ExpenseCollection.create({ db: this.db })).get({ id: targetId });
+		if (!target || (target.tenantId ?? null) !== (this.tenantId ?? null)) throw new ExpenseError("EXPENSE_INVALID", `Expense ${targetId} was not found in this expense's tenant.`);
+		return this.transition("markDuplicate", () => {
+			this.reviewStatus = "rejected";
+			this.reviewedByProfileId = reviewer;
+			this.reviewedAt = input.at ?? /* @__PURE__ */ new Date();
+			this.reviewNote = `Duplicate of expense ${targetId}`;
+			this.duplicateOfId = targetId;
+		});
+	}
+	/**
+	* Send the expense back for review: `reviewed | rejected → unreviewed`.
+	* Clears the reviewer, the review time and any duplicate marker.
+	*
+	* @throws {ExpenseError} `EXPENSE_REVIEW_TRANSITION` from `unreviewed`.
+	*/
+	async reopen(input) {
+		requireReviewer(input?.reviewerProfileId);
+		return this.transition("reopen", () => {
+			this.reviewStatus = "unreviewed";
+			this.reviewedByProfileId = null;
+			this.reviewedAt = null;
+			this.reviewNote = input.note ?? "";
+			this.duplicateOfId = null;
+		});
+	}
+	/**
+	* Record that the person who paid has been paid back. Recording only:
+	* paying happens in payroll or payables, and this never changes the review
+	* state.
+	*
+	* @throws {ExpenseError} `EXPENSE_INVALID` unless the expense is
+	*   `reimbursable`.
+	*/
+	async markReimbursed(input = {}) {
+		return this.withTransaction(async () => {
+			await this.lockRefundRows();
+			const persisted = await this.readPersisted();
+			if (!persisted || persisted.reimbursed_at || this.reimbursedAt) throw new ExpenseError("EXPENSE_INVALID", "Reimbursement requires a persisted source without an existing payment marker.");
+			for (const [field2, column] of [
+				["amount", "amount"],
+				["currency", "currency"],
+				["paidBy", "paid_by"],
+				["paidByProfileId", "paid_by_profile_id"],
+				["reimbursable", "reimbursable"],
+				["refundOfId", "refund_of_id"]
+			]) if (field2 === "reimbursable" ? Boolean(this[field2]) !== Boolean(persisted[column]) : String(this[field2] ?? "") !== String(persisted[column] ?? "")) throw new ExpenseError("EXPENSE_INVALID", "Save source corrections separately before recording reimbursement.");
+			const position = await this.getReimbursementPosition();
+			if (position.remainingAmount === null || position.remainingAmount <= 0 || position.owedToCompany !== 0 || input.amount !== void 0 && input.amount !== position.remainingAmount) throw new ExpenseError("EXPENSE_INVALID", "Record only the exact full known remaining reimbursement; unknown, partial, or settled claims require explicit resolution.");
+			const at = input.at ?? /* @__PURE__ */ new Date();
+			if (!(at instanceof Date) || !Number.isFinite(at.getTime())) throw new ExpenseError("EXPENSE_INVALID", "Reimbursement date must be valid.");
+			const previous = {
+				at: this.reimbursedAt,
+				amount: this.reimbursedAmount,
+				reference: this.reimbursementReference
+			};
+			this.reimbursedAt = at;
+			this.reimbursedAmount = position.remainingAmount;
+			this.reimbursementReference = input.reference ?? "";
+			authorizedReimbursement.set(this, {
+				at: at.getTime(),
+				amount: position.remainingAmount,
+				reference: this.reimbursementReference
+			});
+			try {
+				return await this.save();
+			} catch (error) {
+				this.reimbursedAt = previous.at;
+				this.reimbursedAmount = previous.amount;
+				this.reimbursementReference = previous.reference;
+				throw error;
+			} finally {
+				authorizedReimbursement.delete(this);
+			}
+		});
+	}
+	/**
+	* Load the cost object this expense is charged to, through its registered
+	* collection (so tenant interceptors apply). Returns `null` when unset,
+	* when the type is not registered, when the row is gone, or when the row
+	* belongs to a different tenant than this expense.
+	*/
+	async getCostObject() {
+		if (!this.costObjectType || !this.costObjectId) return null;
+		let registered = ObjectRegistry.getClassByQualifiedName(this.costObjectType);
+		if (!registered) {
+			if (!await ObjectRegistry.tryLoadFromExternalPackage(this.costObjectType)) return null;
+			registered = ObjectRegistry.getClassByQualifiedName(this.costObjectType);
+		}
+		if (!registered) return null;
+		const target = await (await ObjectRegistry.getCollection(registered.qualifiedName ?? this.costObjectType, { db: this.db })).get({ id: this.costObjectId });
+		if (!target) return null;
+		const targetTenant = target.tenantId;
+		if (targetTenant !== void 0 && targetTenant !== null && this.tenantId !== null && targetTenant !== this.tenantId) return null;
+		return target;
+	}
+	/**
+	* Validate, enforce the review and reviewed-field locks, check the
+	* commitment, then persist.
+	*/
+	async save() {
+		this.normalize();
+		this.validateShape();
+		return this.withTransaction(() => this.saveValidated());
+	}
+	/** Keep both directions of refund validation and the write on one executor. */
+	async saveValidated() {
+		await this.lockRefundRows();
+		const persisted = await this.readPersisted();
+		const inserting = await pinNaturalKey("Expense", this, persisted);
+		if (persisted && String(persisted.tenant_id ?? "") !== String(effectiveTenant(this.tenantId) ?? "")) throw new ExpenseError("EXPENSE_INVALID", `Expense ${this.id}: its tenant cannot change after it is recorded.`);
+		await this.assertSupplierPayable(persisted);
+		this.assertReviewFields(persisted);
+		this.assertReviewedLock(persisted);
+		await this.assertCommitment(persisted);
+		await this.assertVendor(persisted);
+		this.assertReimbursementFields(persisted);
+		await this.assertInboundRefunds(persisted);
+		await this.assertRefund(persisted);
+		if (!this.recordedAt) this.recordedAt = /* @__PURE__ */ new Date();
+		try {
+			return await super.save();
+		} catch (error) {
+			if (inserting && isUniqueViolationError(error)) throw identityConflict("Expense", this, error);
+			throw error;
+		}
+	}
+	/** Record original supplier authority without creating approval, cash or journals. */
+	async recordSupplierPayable(input) {
+		return this.mutateSupplierPayable((source, state, refunds) => {
+			if (state) {
+				if (state.original.requestId === input.requestId && state.original.requestFingerprint === payableDigest(input)) return state;
+				return payableInvalid("original supplier authority is immutable.");
+			}
+			return createSupplierPayable(source, input, refunds);
+		});
+	}
+	/** Append explicit dated hold, release, supplier settlement or refund interpretation. */
+	async recordSupplierPayableEvent(input) {
+		return this.mutateSupplierPayable((source, state, refunds) => {
+			if (!state) return payableInvalid("original supplier authority is required.");
+			return appendSupplierPayableEvent(source, state, input, refunds);
+		});
+	}
+	/** Complete a previously unknown basis once with independent current review evidence. */
+	async completeSupplierPayableBasis(input) {
+		return this.mutateSupplierPayable((source, state, refunds) => {
+			if (!state) return payableInvalid("original supplier authority is required.");
+			return completeSupplierPayable(source, state, input, refunds);
+		});
+	}
+	/** Read exact dated supplier position; null means no authority exists or the source is not yet effective. */
+	async getSupplierPayablePosition(input = {}) {
+		return this.withTransaction(async () => {
+			this.assertSupplierPayableContext();
+			await this.lockRefundRows();
+			const source = await this.loadSupplierPayableSource();
+			const state = parseSupplierPayable(source.supplierPayableJson);
+			if (!state) return null;
+			const position = supplierPayablePosition(source, state, await source.supplierRefunds(), input.asOfDate);
+			return input.asOfDate && input.asOfDate < source.incurredOn ? null : position;
+		});
+	}
+	assertSupplierPayableContext() {
+		const active = getTenantId();
+		if (active && this.tenantId && active !== this.tenantId) payableInvalid("active tenant must own the supplier source.");
+	}
+	async loadSupplierPayableSource() {
+		const { ExpenseCollection } = await import("../index.js").then((n) => n.t);
+		const source = await (await ExpenseCollection.create({ db: this.db })).get({
+			id: this.id,
+			tenantId: effectiveTenant(this.tenantId)
+		}, { cache: false });
+		if (!source || source.amount <= 0 || source.refundOfId) return payableInvalid("requires an owned persisted positive source.");
+		return source;
+	}
+	async supplierRefunds() {
+		const { ExpenseCollection } = await import("../index.js").then((n) => n.t);
+		const collection = await ExpenseCollection.create({ db: this.db });
+		const all = [];
+		for (let offset = 0;; offset += 200) {
+			const rows = await collection.list({
+				where: {
+					refundOfId: this.id,
+					tenantId: effectiveTenant(this.tenantId)
+				},
+				orderBy: ["id ASC"],
+				limit: 200,
+				offset,
+				cache: false
+			});
+			all.push(...rows);
+			if (rows.length < 200) return all;
+		}
+	}
+	async mutateSupplierPayable(change) {
+		return this.withTransaction(async () => {
+			this.assertSupplierPayableContext();
+			await this.lockRefundRows();
+			const source = await this.loadSupplierPayableSource(), refunds = await source.supplierRefunds();
+			const state = change(source, parseSupplierPayable(source.supplierPayableJson), refunds);
+			const position = supplierPayablePosition(source, state, refunds), stored = JSON.stringify(state);
+			if (stored !== source.supplierPayableJson) {
+				source.supplierPayableJson = stored;
+				authorizedPayable.set(source, stored);
+				try {
+					await source.save();
+				} finally {
+					authorizedPayable.delete(source);
+				}
+			}
+			return position;
+		});
+	}
+	async assertSupplierPayable(persisted) {
+		const prior = asNullableString(persisted?.supplier_payable_json), next = asNullableString(this.supplierPayableJson);
+		if (prior !== next && (!next || authorizedPayable.get(this) !== next)) payableInvalid("supplier authority is command-owned.");
+		const state = parseSupplierPayable(next);
+		if (state) supplierPayablePosition(this, state, await this.supplierRefunds());
+		const oldParent = asNullableString(persisted?.refund_of_id);
+		if (oldParent) {
+			const { ExpenseCollection } = await import("../index.js").then((n) => n.t);
+			if ((await (await ExpenseCollection.create({ db: this.db })).get({
+				id: oldParent,
+				tenantId: effectiveTenant(this.tenantId)
+			}, { cache: false }))?.supplierPayableJson) for (const [field2, column] of LOCKED_WHEN_REVIEWED) {
+				const old = persisted?.[column], current = this[field2];
+				if (!(field2 === "recordedAt" ? instantMs(old) === instantMs(current) : String(old ?? "") === String(current ?? ""))) payableInvalid("linked supplier refund source facts are immutable; reconcile with new evidence.");
+			}
+		}
+	}
+	/** Managed supplier evidence cannot be erased through ordinary model/collection deletion. */
+	async delete(options = {}) {
+		return this.withTransaction(async () => {
+			this.assertSupplierPayableContext();
+			await this.lockRefundRows();
+			const row = await this.readPersisted();
+			if (row && String(row.tenant_id ?? "") !== String(effectiveTenant(this.tenantId) ?? "")) payableInvalid("owned source is required.");
+			if (row?.supplier_payable_json) payableInvalid("supplier authority cannot be deleted.");
+			const parentId = asNullableString(row?.refund_of_id);
+			if (parentId) {
+				const { ExpenseCollection } = await import("../index.js").then((n) => n.t);
+				if ((await (await ExpenseCollection.create({ db: this.db })).get({
+					id: parentId,
+					tenantId: effectiveTenant(this.tenantId)
+				}, { cache: false }))?.supplierPayableJson) payableInvalid("supplier refund evidence cannot be deleted.");
+			}
+			await super.delete(options);
+		});
+	}
+	normalize() {
+		this.tenantId = normalizeTenantId(this.tenantId);
+		this.currency = String(this.currency ?? "").trim().toUpperCase();
+		this.category = String(this.category ?? "").trim();
+		this.costObjectType = String(this.costObjectType ?? "").trim();
+		this.costObjectId = String(this.costObjectId ?? "").trim();
+		this.incurredOn = String(this.incurredOn ?? "").trim();
+		this.vendorId = asNullableString(this.vendorId);
+		this.commitmentId = asNullableString(this.commitmentId);
+		this.commitmentLineId = asNullableString(this.commitmentLineId);
+		this.paidByProfileId = asNullableString(this.paidByProfileId);
+		this.recordedByProfileId = asNullableString(this.recordedByProfileId);
+	}
+	validateShape() {
+		const label = this.id || "<new>";
+		assertMinorUnits("Expense", label, "amount", this.refundOfId && typeof this.amount === "number" ? Math.abs(this.amount) : this.amount);
+		assertIsoCurrency("Expense", label, this.currency);
+		assertIsoDate("Expense", label, "incurredOn", this.incurredOn);
+		if (!CATEGORY_PATTERN.test(this.category) || this.category.length > 64) throw new ExpenseError("EXPENSE_INVALID", `Expense ${label}: category must be lowercase kebab-case (for example 'outside-service'), got '${this.category}'.`);
+		if (Boolean(this.costObjectType) !== Boolean(this.costObjectId)) throw new ExpenseError("EXPENSE_INVALID", `Expense ${label}: costObjectType and costObjectId are set together or not at all.`);
+		if (this.costObjectType) assertQualifiedClassName("Expense", label, this.costObjectType);
+		this.getFinancialBreakdown();
+		if (this.getRefundRecipient() && !this.refundOfId) throw new ExpenseError("EXPENSE_INVALID", "Only linked refunds may name a cash recipient.");
+		if (this.reimbursedAmount !== null && (!Number.isSafeInteger(this.reimbursedAmount) || this.reimbursedAmount <= 0 || !this.reimbursedAt)) throw new ExpenseError("EXPENSE_INVALID", "Retained reimbursement needs a positive exact amount and payment date.");
+		if (this.paidBy === "third-party" ? typeof this.paidByName !== "string" || !this.paidByName.trim() : this.paidByName !== null && this.paidByName !== "") throw new ExpenseError("EXPENSE_INVALID", "Only a third-party payer requires paidByName.");
+		if (this.refundOfId !== null && (typeof this.refundOfId !== "string" || !this.refundOfId.trim())) throw new ExpenseError("EXPENSE_INVALID", "refundOfId must name a source expense or be null.");
+		if (this.paidBy !== "company" && this.paidBy !== "person" && this.paidBy !== "third-party") throw new ExpenseError("EXPENSE_INVALID", `Expense ${label}: paidBy must be 'company', 'person' or 'third-party'.`);
+		if (this.paidBy === "person" && !this.paidByProfileId) throw new ExpenseError("EXPENSE_INVALID", `Expense ${label}: an expense paid by a person names that person (paidByProfileId).`);
+		if (this.paidBy !== "person" && this.paidByProfileId) throw new ExpenseError("EXPENSE_INVALID", `Expense ${label}: paidByProfileId is only set when paidBy is 'person'.`);
+		if (this.reimbursable && this.paidBy !== "person") throw new ExpenseError("EXPENSE_INVALID", `Expense ${label}: only an expense a person paid can be owed back.`);
+		if (this.reimbursedAt && instantMs(this.reimbursedAt) === null) throw new ExpenseError("EXPENSE_INVALID", "Retained reimbursement date must be valid.");
+		if (this.reimbursedAt && !this.reimbursable) throw new ExpenseError("EXPENSE_INVALID", `Expense ${label}: reimbursedAt needs reimbursable.`);
+		if (this.reviewStatus === "reviewed" && this.duplicateOfId) throw new ExpenseError("EXPENSE_INVALID", `Expense ${label}: a reviewed expense cannot be marked a duplicate.`);
+		if (this.commitmentLineId && !this.commitmentId) throw new ExpenseError("EXPENSE_INVALID", `Expense ${label}: a commitment line needs its commitment (commitmentId).`);
+	}
+	/**
+	* Read the stored row directly. The authoritative prior state for the
+	* review and lock guards: the in-memory copy may have been mass-assigned.
+	*/
+	async readPersisted() {
+		if (!this.id) return null;
+		return await this.db.get(this.tableName, { id: this.id }) ?? null;
+	}
+	reviewState() {
+		return {
+			status: this.reviewStatus,
+			reviewer: asNullableString(this.reviewedByProfileId),
+			reviewedAtMs: instantMs(this.reviewedAt),
+			note: this.reviewNote ?? "",
+			duplicateOf: asNullableString(this.duplicateOfId)
+		};
+	}
+	/**
+	* Refuse any review-field change a transition did not authorize. The token
+	* binds the transition's complete resulting state — status, reviewer,
+	* time, note and duplicate marker — so a field set directly beside a
+	* legitimate `review()` / `reject()` cannot ride along with it.
+	*/
+	assertReviewFields(persisted) {
+		const token = authorizedTransition.get(this);
+		const prior = {
+			status: persisted?.review_status ?? "unreviewed",
+			reviewer: asNullableString(persisted?.reviewed_by_profile_id),
+			reviewedAtMs: instantMs(persisted?.reviewed_at),
+			note: String(persisted?.review_note ?? ""),
+			duplicateOf: asNullableString(persisted?.duplicate_of_id)
+		};
+		const current = this.reviewState();
+		if (sameReviewState(current, prior)) return;
+		if (!token || token.from !== prior.status || !sameReviewState(current, token.expected)) throw new ExpenseError("EXPENSE_REVIEW_FIELDS_LOCKED", `Expense ${this.id || "<new>"}: review state changes only through review(), reject(), markDuplicate() or reopen().`);
+	}
+	assertReviewedLock(persisted) {
+		if (persisted?.review_status !== "reviewed") return;
+		const self = this;
+		for (const [fieldName, column] of LOCKED_WHEN_REVIEWED) {
+			const before = persisted[column];
+			const after = self[fieldName];
+			if (!(fieldName === "amount" ? Number(before) === Number(after) : fieldName === "recordedAt" ? instantMs(before) === instantMs(after) : asNullableString(before) === asNullableString(after))) throw new ExpenseError("EXPENSE_REVIEW_FIELDS_LOCKED", `Expense ${this.id}: ${fieldName} of a reviewed expense cannot change; reopen() it first.`);
+		}
+	}
+	/**
+	* A matched commitment must be visible in this expense's tenant, owned by
+	* the same tenant, and in the same currency; a matched line must belong to
+	* it. Mixed currencies are refused here rather than summed later.
+	*
+	* Checked when the match is made or changed, not on every save: a later
+	* change to the commitment (its currency, or its deletion) must not stop
+	* an unrelated save such as recording a reimbursement.
+	*/
+	async assertCommitment(persisted) {
+		if (!this.commitmentId) return;
+		if (persisted && asNullableString(persisted.commitment_id) === this.commitmentId && asNullableString(persisted.commitment_line_id) === this.commitmentLineId && String(persisted.currency ?? "") === this.currency) return;
+		const commitment = await (await PurchaseContractCollection.create({ db: this.db })).get({ id: this.commitmentId });
+		const owner = effectiveTenant(this.tenantId);
+		if (!commitment || !sameTenant(commitment.tenantId, owner)) throw new ExpenseError("EXPENSE_COMMITMENT_MISMATCH", `Expense ${this.id || "<new>"}: commitment ${this.commitmentId} was not found in this expense's tenant.`);
+		if (String(commitment.currency).toUpperCase() !== this.currency) throw new ExpenseError("EXPENSE_COMMITMENT_MISMATCH", `Expense ${this.id || "<new>"}: currency ${this.currency} does not match commitment ${this.commitmentId} (${commitment.currency}). Amounts in different currencies are never summed.`);
+		if (this.commitmentLineId) {
+			const line = await (await ContractLineItemCollection.create({ db: this.db })).get({ id: this.commitmentLineId });
+			if (!line || line.contractId !== this.commitmentId) throw new ExpenseError("EXPENSE_COMMITMENT_MISMATCH", `Expense ${this.id || "<new>"}: line ${this.commitmentLineId} is not a line of commitment ${this.commitmentId}.`);
+		}
+	}
+	/**
+	* A vendor must be visible in, and owned by, the expense's tenant. A
+	* `crossPackageRef` neither validates its target nor creates a foreign
+	* key, so without this an expense in one tenant could name another
+	* tenant's vendor. Checked when the vendor is set or changed.
+	*/
+	async assertVendor(persisted) {
+		if (!this.vendorId) return;
+		if (persisted && asNullableString(persisted.vendor_id) === this.vendorId) return;
+		const vendor = await (await VendorCollection.create({ db: this.db })).get({ id: this.vendorId });
+		const owner = effectiveTenant(this.tenantId);
+		if (!vendor || !sameTenant(vendor.tenantId, owner)) throw new ExpenseError("EXPENSE_VENDOR_MISMATCH", `Expense ${this.id || "<new>"}: vendor ${this.vendorId} was not found in this expense's tenant.`);
+	}
+	/**
+	* Source edits and refund writes contend on the same source row. Acquire
+	* rows in deterministic order before either relationship check, and hold
+	* them through commit. SQLite's write transaction supplies serialization.
+	*/
+	async lockRefundRows() {
+		if (!isPostgresDatabase(this.db)) return;
+		const oldRow = await this.readPersisted();
+		const oldParent = oldRow && String(oldRow.tenant_id ?? "") === String(effectiveTenant(this.tenantId) ?? "") ? asNullableString(oldRow.refund_of_id) : null;
+		const ids = [...new Set([
+			this.id,
+			this.refundOfId,
+			oldParent
+		].filter((id) => Boolean(id)))].sort();
+		if (ids.length === 0) return;
+		const table = `"${this.tableName.replace(/"/g, "\"\"")}"`;
+		await this.db.query(`SELECT id FROM ${table} WHERE id IN (${ids.map(() => "?").join(", ")}) AND tenant_id IS NOT DISTINCT FROM ? ORDER BY id FOR UPDATE`, ...ids, effectiveTenant(this.tenantId));
+	}
+	/** Refuse source corrections that invalidate any same-owner refund. */
+	async assertInboundRefunds(persisted) {
+		if (!persisted || Number(persisted.amount) === this.amount && String(persisted.currency ?? "") === this.currency && asNullableString(persisted.refund_of_id) === this.refundOfId && asNullableString(persisted.financial_breakdown) === this.financialBreakdown) return;
+		const { ExpenseCollection } = await import("../index.js").then((n) => n.t);
+		const refunds = await (await ExpenseCollection.create({ db: this.db })).list({
+			where: {
+				refundOfId: this.id,
+				tenantId: effectiveTenant(this.tenantId)
+			},
+			cache: false
+		});
+		if (refunds.length === 0) return;
+		if (this.amount <= 0 || this.refundOfId) throw new ExpenseError("EXPENSE_INVALID", "A referenced refund source must remain positive and non-refund.");
+		if (persisted.financial_breakdown && !this.getFinancialBreakdown()) throw new ExpenseError("EXPENSE_INVALID", "Financial facts of a linked refund source cannot be cleared.");
+		calculateRefundPosition(this, refunds);
+	}
+	async assertRefund(persisted) {
+		if (!this.refundOfId) return;
+		if (this.refundOfId === this.id || this.amount >= 0) throw new ExpenseError("EXPENSE_INVALID", "A refund must be negative and name a different positive source expense.");
+		const { ExpenseCollection } = await import("../index.js").then((n) => n.t);
+		const expenses = await ExpenseCollection.create({ db: this.db });
+		const source = await expenses.get({ id: this.refundOfId }, { cache: false });
+		if (!source || !sameTenant(source.tenantId, effectiveTenant(this.tenantId)) || source.currency !== this.currency || source.amount <= 0 || source.refundOfId) throw new ExpenseError("EXPENSE_INVALID", "Refund source must be a positive non-refund expense in the same tenant and currency.");
+		if (persisted?.financial_breakdown && !this.getFinancialBreakdown()) throw new ExpenseError("EXPENSE_INVALID", "Financial facts of a linked refund cannot be cleared.");
+		calculateRefundPosition(source, [...(await expenses.list({
+			where: {
+				refundOfId: source.id,
+				tenantId: effectiveTenant(this.tenantId)
+			},
+			cache: false
+		})).filter((refund) => refund.id !== this.id), this]);
+		if (!persisted || persisted.refund_of_id !== this.refundOfId || Number(persisted.amount) !== this.amount || asNullableString(persisted.financial_breakdown) !== this.financialBreakdown || asNullableString(persisted.refund_recipient) !== this.refundRecipient) {
+			if (!source.updated_at) throw new ExpenseError("EXPENSE_INVALID", "Refund source has no revision.");
+			await source.claimRevision(source.updated_at);
+		}
+	}
+	assertReimbursementFields(persisted) {
+		const token = authorizedReimbursement.get(this);
+		const at = instantMs(this.reimbursedAt);
+		const priorAt = instantMs(persisted?.reimbursed_at);
+		const priorAmount = persisted?.reimbursed_amount == null ? null : Number(persisted.reimbursed_amount);
+		if ((at !== priorAt || this.reimbursedAmount !== priorAmount || String(this.reimbursementReference ?? "") !== String(persisted?.reimbursement_reference ?? "")) && (!token || priorAt !== null || at !== token.at || this.reimbursedAmount !== token.amount || this.reimbursementReference !== token.reference)) throw new ExpenseError("EXPENSE_INVALID", "Retained reimbursement payment fields change only through markReimbursed and cannot be overwritten.");
+		if (priorAt !== null && persisted) {
+			for (const [field2, column] of [
+				["amount", "amount"],
+				["currency", "currency"],
+				["paidBy", "paid_by"],
+				["paidByProfileId", "paid_by_profile_id"],
+				["reimbursable", "reimbursable"],
+				["refundOfId", "refund_of_id"]
+			]) if (field2 === "reimbursable" ? Boolean(this[field2]) !== Boolean(persisted[column]) : String(this[field2] ?? "") !== String(persisted[column] ?? "")) throw new ExpenseError("EXPENSE_INVALID", "A paid reimbursement preserves its original cash claim and payer.");
+		}
+	}
+	/** Remaining person cash claim and separate company receivable; null is unknown. */
+	async getReimbursementPosition() {
+		return this.withTransaction(async () => {
+			await this.lockRefundRows();
+			const { ExpenseCollection } = await import("../index.js").then((n) => n.t);
+			const expenses = await ExpenseCollection.create({ db: this.db });
+			const source = this.id ? await expenses.get({ id: this.id }, { cache: false }) : null;
+			if (!source || source.refundOfId) throw new ExpenseError("EXPENSE_INVALID", "Reimbursement position requires a persisted positive source.");
+			const refunds = await expenses.list({
+				where: {
+					refundOfId: source.id,
+					tenantId: effectiveTenant(source.tenantId)
+				},
+				cache: false
+			});
+			calculateRefundPosition(source, refunds);
+			return calculateReimbursementPosition(source, refunds);
+		});
+	}
+	/** Exact source cash capacity and optional complete signed financial position. */
+	async getRefundPosition() {
+		return this.withTransaction(async () => {
+			await this.lockRefundRows();
+			const { ExpenseCollection } = await import("../index.js").then((n) => n.t);
+			const expenses = await ExpenseCollection.create({ db: this.db });
+			const source = this.id ? await expenses.get({ id: this.id }, { cache: false }) : null;
+			if (!source || source.refundOfId) throw new ExpenseError("EXPENSE_INVALID", "Refund position requires a persisted positive non-refund source.");
+			return calculateRefundPosition(source, await expenses.list({
+				where: {
+					refundOfId: source.id,
+					tenantId: effectiveTenant(source.tenantId)
+				},
+				cache: false
+			}));
+		});
+	}
+	async transition(action, apply) {
+		const rule = REVIEW_TRANSITIONS[action];
+		const persisted = await this.readPersisted();
+		if (!persisted) throw new ExpenseError("EXPENSE_REVIEW_TRANSITION", `Expense ${this.id || "<new>"}: save the expense before ${action}().`);
+		const from = String(persisted.review_status);
+		if (!rule.from.includes(from)) throw new ExpenseError("EXPENSE_REVIEW_TRANSITION", `Expense ${this.id}: cannot ${action}() an expense that is ${from}.`);
+		if (action === "review" && persisted.duplicate_of_id) throw new ExpenseError("EXPENSE_REVIEW_TRANSITION", `Expense ${this.id}: a duplicate cannot be reviewed; reopen() it first.`);
+		const snapshot = {
+			reviewStatus: this.reviewStatus,
+			reviewedByProfileId: this.reviewedByProfileId,
+			reviewedAt: this.reviewedAt,
+			reviewNote: this.reviewNote,
+			duplicateOfId: this.duplicateOfId
+		};
+		apply();
+		authorizedTransition.set(this, {
+			from,
+			expected: this.reviewState()
+		});
+		try {
+			return await this.save();
+		} catch (error) {
+			Object.assign(this, snapshot);
+			throw error;
+		} finally {
+			authorizedTransition.delete(this);
+		}
+	}
+};
+__publicField(Expense, "__smrtPackage__", "@happyvertical/smrt-expenses");
+__decorateClass([tenantId({ nullable: true })], Expense.prototype, "tenantId", 2);
+__decorateClass([field({ type: "text" })], Expense.prototype, "costObjectType", 2);
+__decorateClass([field({ type: "text" })], Expense.prototype, "costObjectId", 2);
+__decorateClass([field({ type: "text" })], Expense.prototype, "category", 2);
+__decorateClass([field({ type: "text" })], Expense.prototype, "description", 2);
+__decorateClass([field({ type: "integer" })], Expense.prototype, "amount", 2);
+__decorateClass([field({ type: "text" })], Expense.prototype, "currency", 2);
+__decorateClass([field({ type: "text" })], Expense.prototype, "financialBreakdown", 2);
+__decorateClass([field({
+	type: "text",
+	nullable: true,
+	readonly: true
+})], Expense.prototype, "supplierPayableJson", 2);
+__decorateClass([field({ type: "text" })], Expense.prototype, "paidByName", 2);
+__decorateClass([foreignKey("Expense", { onDelete: "RESTRICT" })], Expense.prototype, "refundOfId", 2);
+__decorateClass([field({ type: "text" })], Expense.prototype, "refundRecipient", 2);
+__decorateClass([field({ type: "text" })], Expense.prototype, "incurredOn", 2);
+__decorateClass([field({ type: "datetime" })], Expense.prototype, "recordedAt", 2);
+__decorateClass([crossPackageRef(PROFILE)], Expense.prototype, "recordedByProfileId", 2);
+__decorateClass([field({ type: "text" })], Expense.prototype, "paidBy", 2);
+__decorateClass([crossPackageRef(PROFILE)], Expense.prototype, "paidByProfileId", 2);
+__decorateClass([crossPackageRef("@happyvertical/smrt-commerce:Vendor")], Expense.prototype, "vendorId", 2);
+__decorateClass([crossPackageRef("@happyvertical/smrt-commerce:PurchaseContract", { validateSubtype: true })], Expense.prototype, "commitmentId", 2);
+__decorateClass([crossPackageRef("@happyvertical/smrt-commerce:ContractLineItem")], Expense.prototype, "commitmentLineId", 2);
+__decorateClass([field({
+	type: "text",
+	readonly: true
+})], Expense.prototype, "reviewStatus", 2);
+__decorateClass([crossPackageRef(PROFILE, { readonly: true })], Expense.prototype, "reviewedByProfileId", 2);
+__decorateClass([field({
+	type: "datetime",
+	readonly: true
+})], Expense.prototype, "reviewedAt", 2);
+__decorateClass([field({
+	type: "text",
+	readonly: true
+})], Expense.prototype, "reviewNote", 2);
+__decorateClass([foreignKey("Expense", {
+	readonly: true,
+	onDelete: "SET NULL"
+})], Expense.prototype, "duplicateOfId", 2);
+__decorateClass([field({ type: "boolean" })], Expense.prototype, "reimbursable", 2);
+__decorateClass([field({
+	type: "integer",
+	nullable: true,
+	readonly: true
+})], Expense.prototype, "reimbursedAmount", 2);
+__decorateClass([field({
+	type: "datetime",
+	readonly: true
+})], Expense.prototype, "reimbursedAt", 2);
+__decorateClass([field({
+	type: "text",
+	readonly: true
+})], Expense.prototype, "reimbursementReference", 2);
+Expense = __decorateClass([TenantScoped({ mode: "optional" }), smrt({
+	tableName: "expenses",
+	api: { include: [
+		"record",
+		"attachReceipt",
+		"recordReview",
+		"recordReimbursement"
+	] },
+	mcp: { include: [] },
+	cli: false,
+	indexes: [
+		{
+			name: "expenses_cost_object_idx",
+			columns: [
+				"tenantId",
+				"costObjectType",
+				"costObjectId",
+				"incurredOn"
+			]
+		},
+		{
+			name: "expenses_commitment_review_idx",
+			columns: [
+				"tenantId",
+				"commitmentId",
+				"reviewStatus"
+			]
+		},
+		{
+			name: "expenses_review_status_idx",
+			columns: [
+				"tenantId",
+				"reviewStatus",
+				"incurredOn"
+			]
+		}
+	]
+})], Expense);
+function requireReviewer(reviewerProfileId) {
+	const reviewer = String(reviewerProfileId ?? "").trim();
+	if (!reviewer) throw new ExpenseError("EXPENSE_INVALID", "A review decision names its reviewer (reviewerProfileId).");
+	return reviewer;
+}
+function sameTenant(a, b) {
+	return (a ?? null) === (b ?? null);
+}
+//#endregion
+export { identityConflict as a, pinNaturalKey as c, effectiveTenant as i, assertMinorUnits as n, normalizeSha256 as o, computeContentSha256 as r, normalizeTenantId as s, Expense as t };
+
+//# sourceMappingURL=Expense-C_WC5VLF.js.map