@happyvertical/smrt-commerce 0.57.2 → 0.57.4

package/dist/chunks/retention-accounting-Brdj9x-V.js

@@ -0,0 +1,2323 @@
+import { t as __exportAll } from "./rolldown-runtime-D7D4PA-g.js";
+import { Y as InvoiceLineItemCollection, t as DocumentTaxCollection, x as lockAndReloadInvoice } from "./DocumentTaxCollection-C42x0YLW.js";
+import { d as PaymentStatus, s as InvoiceStatus, u as PaymentMethod } from "./types-Bbm0Xflc.js";
+import { o as minorToMajorUnits } from "./units-8ElbjVZK.js";
+import { n as withRetentionAccountingAuthority, t as hasRetentionAccountingAuthority } from "./retention-accounting-internal-CBQRvd74.js";
+import { i as claimAllocationParent, n as allocationTotal, r as assertAllocationParent, t as allocationOwner } from "./allocation-integrity-DJ7-LY1j.js";
+import { n as customerFundsState, t as assertCustomerFundsWrite } from "./customer-funds-internal-BQzoJXK5.js";
+import { MoneyValidationError, assertIntegerMinorUnits, calculateMoneyDocument } from "../money.js";
+import { t as HistoricalCustomerFundsAllocationCollection } from "./HistoricalCustomerFundsCollections-B5x8gTW3.js";
+import { n as calculateAvailableRefund } from "./credit-allocation-yspz0Lab.js";
+import { _ as withDocumentMoneyTransaction, m as isMoneyTransaction, p as DOCUMENT_MONEY_WRITE } from "./detect-DAE-_NAk.js";
+import { c as validateRetentionEvidence, o as calculateInvoicePayable, s as parseInvoiceRetention, t as InvoiceCollection } from "./InvoiceCollection-BIcge9Wl.js";
+import { t as lockTenantMoneyRuntime } from "./tenant-money-barrier-DoF6lR8h.js";
+import { SmrtCollection, SmrtObject, crossPackageRef, field, foreignKey, isPostgresDatabase, smrt } from "@happyvertical/smrt-core";
+import { TenantScoped, getTenantId, queryGlobal, queryWithGlobals, tenantId } from "@happyvertical/smrt-tenancy";
+import { createHash, randomUUID } from "node:crypto";
+import { prepareQuickBooksCreditMemoRequest, prepareQuickBooksInvoiceRequest, prepareQuickBooksReceivableRequest, requireCreditMemoOperations } from "@happyvertical/accounting";
+//#region src/models/Payment.ts
+var __defProp$1 = Object.defineProperty;
+var __getOwnPropDesc$1 = Object.getOwnPropertyDescriptor;
+var __defNormalProp$1 = (obj, key, value) => key in obj ? __defProp$1(obj, key, {
+	enumerable: true,
+	configurable: true,
+	writable: true,
+	value
+}) : obj[key] = value;
+var __decorateClass$1 = (decorators, target, key, kind) => {
+	var result = kind > 1 ? void 0 : kind ? __getOwnPropDesc$1(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$1(target, key, result);
+	return result;
+};
+var __publicField$1 = (obj, key, value) => __defNormalProp$1(obj, typeof key !== "symbol" ? key + "" : key, value);
+var PAYMENT_STATUS_TRANSITIONS = {
+	[PaymentStatus.PENDING]: [
+		PaymentStatus.COMPLETED,
+		PaymentStatus.FAILED,
+		PaymentStatus.CANCELLED
+	],
+	[PaymentStatus.COMPLETED]: [PaymentStatus.REFUNDED],
+	[PaymentStatus.FAILED]: [],
+	[PaymentStatus.REFUNDED]: [],
+	[PaymentStatus.CANCELLED]: []
+};
+var loadedPaymentStatus = /* @__PURE__ */ new WeakMap();
+var settlementInProgress = /* @__PURE__ */ new WeakSet();
+var recordingInProgress = /* @__PURE__ */ new WeakSet();
+var Payment = class extends SmrtObject {
+	/** Incoming settlement or outgoing customer refund. Amount stays positive. */
+	kind = "payment";
+	customerFundsJson = "";
+	retentionAccountingBindingJson = "";
+	tenantId = null;
+	contractId = null;
+	customerId = null;
+	amount = 0;
+	currency = "USD";
+	method = PaymentMethod.BANK_TRANSFER;
+	status = PaymentStatus.PENDING;
+	/**
+	* External transaction ID (from payment processor)
+	*/
+	transactionId = "";
+	reference = "";
+	journalId = "";
+	paidAt = null;
+	notes = "";
+	/**
+	* External ID in accounting provider (e.g., QBO payment ID)
+	*/
+	externalId = "";
+	/**
+	* Accounting provider name ('quickbooks' | 'stripe' | 'paypal' | etc.)
+	*/
+	externalProvider = "";
+	/**
+	* When payment was last synced to provider
+	*/
+	syncedAt = null;
+	/**
+	* Stable identifier of the `PaymentBackend` adapter that served this
+	* payment — e.g. `base-usdc`, `solana-usdc`, `btc`, `stripe`, `paypal`.
+	*
+	* Distinct from {@link externalProvider}: `backendId` names the SMRT
+	* payment-rail adapter, while `externalProvider` names a downstream
+	* accounting destination (QuickBooks, Stripe-the-accounting-source).
+	* The same Stripe payment will have `backendId: 'stripe'` AND
+	* `externalProvider: 'stripe'`; a crypto payment synced to QBO will
+	* have `backendId: 'base-usdc'` and `externalProvider: 'quickbooks'`.
+	*/
+	backendId = "";
+	/**
+	* Chain transaction hash or backend aggregator's reference id. For
+	* on-chain payments this is the tx hash (`0x...` on EVM, base58 sig on
+	* Solana, txid on Bitcoin); for fiat-rail backends it's the gateway's
+	* own reference. Kept distinct from {@link transactionId} so consumers
+	* that already populate `transactionId` with a provider-internal id
+	* don't have to overload it.
+	*/
+	backendTxRef = "";
+	/**
+	* The amount the backend actually moved, in the native currency's own
+	* **integer minor units** — satoshis for BTC, cents for a fiat rail. For
+	* stablecoin rails this typically equals `amount`; for volatile-currency
+	* rails it's the satoshi/wei figure the chain recorded, independent of any
+	* USD valuation.
+	*
+	* Fresh PostgreSQL and DuckDB INTEGER columns materialize as BIGINT. SMRT
+	* rejects values outside JavaScript's safe-integer range during hydration;
+	* existing PostgreSQL `int4` columns require the explicit widening in #2424.
+	*/
+	nativeAmount = 0;
+	/**
+	* Code identifying the native currency `nativeAmount` is denominated
+	* in. Mirrors the `backendId` namespacing convention — `USDC-base`,
+	* `BTC`, `ETH`, `USD-stripe`. Empty string means "use {@link currency}"
+	* (i.e. the payment was already quoted and settled in the same
+	* currency).
+	*/
+	nativeCurrency = "";
+	/**
+	* USD valuation of the payment at the moment the price was quoted to
+	* the buyer (typically the moment a `PaymentIntent` was issued), in
+	* **integer minor units** (US cents). A default of `0` means no USD-quote
+	* snapshot was taken (the payment was already USD-denominated or the
+	* backend doesn't require drift accounting).
+	*
+	* This is money describing the same funds as {@link Payment.amount}, so it
+	* converts with it — a dollars-here / cents-there split would make
+	* {@link Payment.usdDrift} meaningless (#2401).
+	*/
+	usdAtQuote = 0;
+	/**
+	* USD valuation of the payment at the moment it was confirmed on the
+	* backend (chain confirmation, gateway settlement, etc.), in integer minor
+	* units (US cents). The delta between {@link usdAtQuote} and
+	* `usdAtConfirmation` is the USD drift the operator absorbs (positive or
+	* negative) when accepting payment in a volatile native currency (#2401).
+	*/
+	usdAtConfirmation = 0;
+	constructor(options = {}) {
+		super(options);
+		if (options.kind !== void 0) this.kind = options.kind;
+		if (options.tenantId !== void 0) this.tenantId = options.tenantId;
+		if (options.contractId !== void 0) this.contractId = options.contractId;
+		if (options.customerId !== void 0) this.customerId = options.customerId;
+		if (options.amount !== void 0) this.amount = options.amount;
+		if (options.currency !== void 0) this.currency = options.currency;
+		if (options.method !== void 0) this.method = options.method;
+		if (options.status !== void 0) this.status = options.status;
+		if (options.transactionId !== void 0) this.transactionId = options.transactionId;
+		if (options.reference !== void 0) this.reference = options.reference;
+		if (options.customerFundsJson !== void 0) this.customerFundsJson = options.customerFundsJson;
+		if (options.journalId !== void 0) this.journalId = options.journalId;
+		if (options.paidAt !== void 0) this.paidAt = options.paidAt;
+		if (options.notes !== void 0) this.notes = options.notes;
+		if (options.externalId !== void 0) this.externalId = options.externalId;
+		if (options.externalProvider !== void 0) this.externalProvider = options.externalProvider;
+		if (options.syncedAt !== void 0) this.syncedAt = options.syncedAt;
+		if (options.backendId !== void 0) this.backendId = options.backendId;
+		if (options.backendTxRef !== void 0) this.backendTxRef = options.backendTxRef;
+		if (options.nativeAmount !== void 0) this.nativeAmount = options.nativeAmount;
+		if (options.nativeCurrency !== void 0) this.nativeCurrency = options.nativeCurrency;
+		if (options.usdAtQuote !== void 0) this.usdAtQuote = options.usdAtQuote;
+		if (options.usdAtConfirmation !== void 0) this.usdAtConfirmation = options.usdAtConfirmation;
+	}
+	/**
+	* Capture the persisted status the row was loaded with, so the save-time
+	* transition guard can reject illegal status flips made via raw field
+	* assignment (mass-assignment on the generated update route, a stale caller,
+	* etc.). Freshly-constructed (not-yet-saved) payments have no prior status.
+	*/
+	async initialize() {
+		await super.initialize();
+		if (await this.isSaved()) loadedPaymentStatus.set(this, this.status);
+		return this;
+	}
+	/**
+	* Save-time state-machine guard (S5 audit #1390).
+	*
+	* `status` is mass-assignable on the generated update/create routes, and a
+	* COMPLETED Payment is treated as settlement proof downstream — e.g.
+	* {@link PaymentIntent}'s PAID verification trusts a COMPLETED Payment row.
+	* A forged `status: 'completed'` (with arbitrary amounts and no journal)
+	* would therefore satisfy that check without any money having moved.
+	*
+	* This guard enforces two things:
+	*  - **Transitions must be legal** per {@link PAYMENT_STATUS_TRANSITIONS}.
+	*  - **Reaching COMPLETED requires the verified settlement path — on
+	*    creation AND on update.** Only `recordPayment()` (which posts a
+	*    balanced journal and links `journalId`) may write a Payment into
+	*    COMPLETED; it announces itself via {@link settlementInProgress}. A raw
+	*    `status: 'completed'` is rejected whether the row is brand-new (a
+	*    GENESIS `create({ status: 'completed' })`) or already persisted — that
+	*    is the exact path a forged COMPLETED would take to satisfy
+	*    PaymentIntent's PAID verification without any money having moved (codex
+	*    HIGH#1, #1390 round 5). There is deliberately NO import/fixture
+	*    carve-out: a COMPLETED Payment is settlement proof downstream, so it is
+	*    only ever reachable through `recordPayment()`, on every surface
+	*    (REST/MCP/CLI/direct). Fixtures/migrations that need a completed payment
+	*    must drive it through `recordPayment()` (or start non-COMPLETED).
+	*/
+	async save() {
+		return this.withTransaction(async () => {
+			if (this.kind !== "payment" && this.kind !== "refund") throw new Error("Payment kind must be payment or refund");
+			await claimAllocationParent(this, "payment");
+			assertIntegerMinorUnits("Payment", this.id || "<new>", [
+				["amount", this.amount],
+				["nativeAmount", this.nativeAmount],
+				["usdAtQuote", this.usdAtQuote],
+				["usdAtConfirmation", this.usdAtConfirmation]
+			]);
+			const priorRow = await this.loadPersistedRow();
+			if (this.customerFundsJson || priorRow?.customer_funds_json) assertCustomerFundsWrite(this);
+			const retainedBinding = this.retentionAccountingBindingJson || String(priorRow?.retention_accounting_binding_json ?? "");
+			if (retainedBinding && !hasRetentionAccountingAuthority(this.tenantId, JSON.parse(retainedBinding).invoiceId)) throw new Error("Provider-recorded refund is immutable; use an explicit reversal workflow");
+			const prior = priorRow && priorRow.status != null ? priorRow.status : loadedPaymentStatus.get(this);
+			this.assertStatusTransition(prior);
+			if (this.status === PaymentStatus.COMPLETED && prior !== PaymentStatus.COMPLETED && !settlementInProgress.has(this)) throw new Error(`Payment ${this.id || "<new>"}: cannot set status to COMPLETED via raw assignment \u2014 a Payment is only completed through recordPayment(), which posts a balanced settlement journal. Use recordPayment() instead of setting status directly.`);
+			if (priorRow && (priorRow.status === PaymentStatus.COMPLETED || priorRow.status === PaymentStatus.REFUNDED)) this.assertSettledAmountsUnchanged(priorRow);
+			try {
+				await assertAllocationParent(this, "payment");
+				const result = await super.save();
+				loadedPaymentStatus.set(this, this.status);
+				return result;
+			} finally {
+				settlementInProgress.delete(this);
+			}
+		});
+	}
+	/** Managed receipts and refunds retain immutable cash provenance. */
+	async delete(options = {}) {
+		const persisted = await this.loadPersistedRow();
+		if (this.retentionAccountingBindingJson || persisted?.retention_accounting_binding_json) throw new Error("Provider-recorded refund history cannot be deleted");
+		if (this.customerFundsJson || persisted?.customer_funds_json) throw new Error("Customer funds cash history cannot be deleted");
+		return super.delete(options);
+	}
+	/**
+	* Reject an illegal status flip. Compares the about-to-be-written status
+	* against the status the row was loaded with. No-op transitions (status
+	* unchanged) and brand-new rows (no prior) are always allowed — the
+	* COMPLETED-specific settlement requirement is enforced separately in
+	* {@link save}.
+	*/
+	assertStatusTransition(prior) {
+		if (prior === void 0) return;
+		if (prior === this.status) return;
+		if (!(PAYMENT_STATUS_TRANSITIONS[prior] ?? []).includes(this.status)) throw new Error(`Payment ${this.id}: illegal status transition '${prior}' \u2192 '${this.status}'. Use the guarded helpers (recordPayment / markFailed / cancel).`);
+	}
+	/**
+	* Load the AUTHORITATIVE persisted row (S5 audit #1390 round 4, codex HIGH#1;
+	* extended round 6 to carry the full row, not just `status`). The WeakMap is
+	* only populated when {@link initialize} loaded the row from the DB; it is
+	* empty for an instance built via
+	* `collection.create({ id: <existing>, _skipLoad: true })` — the upsert path
+	* that lets a caller write onto an existing row without hydrating it. Trusting
+	* an empty WeakMap there would treat the write as a brand-new row and skip the
+	* transition guard entirely (a poisonable prior-state).
+	*
+	* So when this instance carries an `id`, read the persisted row straight from
+	* the database and use it as the prior — a create-onto-existing is an update.
+	* Returns `undefined` when no row exists (truly new), so callers fall back to
+	* the WeakMap (which is also empty then). Settled-amount columns are
+	* snake_case (`native_amount`, etc.); the `status` column is single-word.
+	*/
+	async loadPersistedRow() {
+		if (!this.id) return void 0;
+		try {
+			return await this.db.get(this.tableName, { id: this.id }) ?? void 0;
+		} catch {
+			return;
+		}
+	}
+	/**
+	* Reject any change to the settled monetary fields of an already-COMPLETED
+	* Payment (S5 audit #1390 round 6 — codex ROOT INSIGHT). Mirrors the
+	* PaymentIntent PAID backing-field freeze. A COMPLETED Payment's economic
+	* identity is settled: the `amount` was posted into a balanced journal and is
+	* the figure PaymentIntent's PAID verification reconciles against, so it (and
+	* the native/USD valuation fields that describe the same money) must not
+	* drift. The only legal status move out of COMPLETED is REFUNDED, which
+	* reverses the funds without rewriting how much they were. Compared against
+	* the AUTHORITATIVE persisted row so the freeze holds on every surface, even
+	* for an un-hydrated create-onto-existing upsert.
+	*/
+	assertSettledAmountsUnchanged(priorRow) {
+		const frozen = [
+			[
+				"journalId",
+				String(priorRow.journal_id ?? ""),
+				this.journalId ?? ""
+			],
+			[
+				"paidAt",
+				priorRow.paid_at == null ? "" : new Date(priorRow.paid_at).getTime(),
+				this.paidAt == null ? "" : new Date(this.paidAt).getTime()
+			],
+			[
+				"kind",
+				String(priorRow.kind ?? "payment"),
+				this.kind
+			],
+			[
+				"amount",
+				Number(priorRow.amount ?? 0),
+				Number(this.amount ?? 0)
+			],
+			[
+				"currency",
+				String(priorRow.currency ?? ""),
+				String(this.currency ?? "")
+			],
+			[
+				"nativeAmount",
+				Number(priorRow.native_amount ?? 0),
+				Number(this.nativeAmount ?? 0)
+			],
+			[
+				"nativeCurrency",
+				String(priorRow.native_currency ?? ""),
+				String(this.nativeCurrency ?? "")
+			],
+			[
+				"usdAtQuote",
+				Number(priorRow.usd_at_quote ?? 0),
+				Number(this.usdAtQuote ?? 0)
+			],
+			[
+				"usdAtConfirmation",
+				Number(priorRow.usd_at_confirmation ?? 0),
+				Number(this.usdAtConfirmation ?? 0)
+			]
+		];
+		for (const [field2, prior, next] of frozen) if (prior !== next) throw new Error(`Payment ${this.id}: '${field2}' is frozen once the payment is COMPLETED (was '${prior}', got '${next}'). A settled payment's monetary fields cannot be mutated \u2014 issue a refund instead.`);
+	}
+	/**
+	* USD drift between quote time and confirmation time — what the
+	* operator gained (positive) or lost (negative) by accepting a
+	* volatile-currency payment. Returns `0` when either side of the
+	* comparison is missing or zero, so callers don't have to special-case
+	* fiat-rail / stablecoin payments.
+	*/
+	usdDrift() {
+		if (!this.usdAtQuote || !this.usdAtConfirmation) return 0;
+		return this.usdAtConfirmation - this.usdAtQuote;
+	}
+	/**
+	* Check if payment is pending
+	*/
+	isPending() {
+		return this.status === PaymentStatus.PENDING;
+	}
+	/**
+	* Check if payment is completed
+	*/
+	isCompleted() {
+		return this.status === PaymentStatus.COMPLETED;
+	}
+	/**
+	* Check if payment is refunded
+	*/
+	isRefunded() {
+		return this.status === PaymentStatus.REFUNDED;
+	}
+	/**
+	* Record the payment and create a balanced journal entry.
+	*
+	* Creates a journal entry in smrt-ledgers:
+	* - Debit: Cash/Bank account (assets increase)
+	* - Credit: Accounts Receivable (receivables decrease)
+	*
+	* Both sides carry `this.amount`, so the journal posted from commerce is
+	* denominated in **integer minor units** like the rest of this package
+	* (#2401). smrt-ledgers is unit-agnostic — its `BALANCE_EPSILON` only checks
+	* that debits equal credits — and integer entries balance exactly, so this is
+	* strictly tighter than the major-unit journals commerce used to post.
+	*
+	* @param options - Ledger and account configuration
+	* @returns The created journal
+	*
+	* @example
+	* ```typescript
+	* const journal = await payment.recordPayment({
+	*   ledgerId: ledger.id,
+	*   receivablesAccountId: arAccount.id,
+	*   cashAccountId: bankAccount.id
+	* });
+	* console.log(`Created journal: ${journal.number}`);
+	* ```
+	*/
+	async recordPayment(options) {
+		if (recordingInProgress.has(this)) throw new Error("Payment recording is already in progress");
+		if (this.status === PaymentStatus.COMPLETED) throw new Error("Payment already recorded");
+		const previous = {
+			status: this.status,
+			journalId: this.journalId,
+			paidAt: this.paidAt,
+			loadedStatus: loadedPaymentStatus.get(this)
+		};
+		recordingInProgress.add(this);
+		try {
+			await this.withTransaction(async () => {
+				if (!this.isPersisted) await this.save();
+				if (!this.updated_at) throw new Error("Payment revision is missing; reload before recording");
+				await this.claimRevision(this.updated_at);
+				const persisted = await this.db.get(this.tableName, { id: this.id });
+				if (!persisted) throw new Error("Claimed payment could not be loaded");
+				if (persisted.status === PaymentStatus.COMPLETED) throw new Error("Payment already recorded");
+				await this.postPaymentInTransaction(options);
+			});
+		} catch (error) {
+			this.status = previous.status;
+			this.journalId = previous.journalId;
+			this.paidAt = previous.paidAt;
+			if (previous.loadedStatus === void 0) loadedPaymentStatus.delete(this);
+			else loadedPaymentStatus.set(this, previous.loadedStatus);
+			throw error;
+		} finally {
+			recordingInProgress.delete(this);
+			settlementInProgress.delete(this);
+		}
+		const { JournalCollection } = await import("@happyvertical/smrt-ledgers");
+		const journal = await (await JournalCollection.create({
+			...this.options,
+			db: this.db
+		})).get({ id: this.journalId });
+		if (!journal) throw new Error("Recorded payment journal could not be loaded");
+		return journal;
+	}
+	/** Settle an outgoing refund through the same guarded journal transaction. */
+	async recordRefund(options) {
+		if (this.kind !== "refund") throw new Error("recordRefund requires Payment.kind=refund");
+		return this.recordPayment(options);
+	}
+	/** Post and complete only inside recordPayment's claimed transaction. */
+	async postPaymentInTransaction(options) {
+		if (this.status === PaymentStatus.COMPLETED) throw new Error("Payment already recorded");
+		if (this.amount <= 0) throw new Error("Payment amount must be positive");
+		const funds = customerFundsState(this.customerFundsJson);
+		const explicitDate = options.effectiveOn;
+		if (explicitDate !== void 0 && (typeof explicitDate !== "string" || !/^\d{4}-\d{2}-\d{2}$/.test(explicitDate) || !Number.isFinite(Date.parse(explicitDate)) || new Date(explicitDate).toISOString().slice(0, 10) !== explicitDate)) throw new Error("Settlement effectiveOn must be a calendar date");
+		if (funds) {
+			if (explicitDate !== void 0 && explicitDate !== funds.effectiveOn) throw new Error("Settlement date differs from reviewed customer funds");
+			assertCustomerFundsWrite(this);
+			if (options.cashAccountId !== funds.policy.cashAccountId || options.receivablesAccountId !== funds.policy.receivablesAccountId) throw new Error("Customer funds settlement accounts differ from reviewed policy");
+		}
+		const creditAccountId = funds?.policy.mode === "deposit-liability" ? funds.policy.liabilityAccountId : options.receivablesAccountId;
+		const effectiveOn = funds?.effectiveOn ?? explicitDate;
+		const effectiveDate = effectiveOn ? /* @__PURE__ */ new Date(`${effectiveOn}T12:00:00Z`) : /* @__PURE__ */ new Date();
+		const { JournalCollection } = await import("@happyvertical/smrt-ledgers");
+		const journal = await (await JournalCollection.create(this.options)).create({
+			date: effectiveDate,
+			description: this.kind === "refund" ? `Customer refund for contract ${this.contractId}` : `Payment received for contract ${this.contractId}`,
+			sourceModule: "smrt-commerce",
+			sourceRef: this.id
+		});
+		await journal.save();
+		await journal.addEntry({
+			accountId: options.cashAccountId,
+			currency: this.currency,
+			debit: this.kind === "payment" ? this.amount : 0,
+			credit: this.kind === "refund" ? this.amount : 0,
+			memo: `${this.kind === "refund" ? "Refund" : "Payment"} ${this.reference || this.id}`
+		});
+		await journal.addEntry({
+			accountId: creditAccountId,
+			currency: this.currency,
+			debit: this.kind === "refund" ? this.amount : 0,
+			credit: this.kind === "payment" ? this.amount : 0,
+			memo: `${this.kind === "refund" ? "Refund" : "Payment"} ${this.reference || this.id}`
+		});
+		await journal.post();
+		if (!journal.id) throw new Error("Payment.recordPayment: journal was posted but has no id");
+		this.journalId = journal.id;
+		this.status = PaymentStatus.COMPLETED;
+		this.paidAt = effectiveDate;
+		settlementInProgress.add(this);
+		await this.save();
+		return journal;
+	}
+	/**
+	* Get the linked journal entry (if recorded)
+	*/
+	async getJournal() {
+		if (!this.journalId) return null;
+		try {
+			const { JournalCollection } = await import("@happyvertical/smrt-ledgers");
+			return await (await JournalCollection.create(this.options)).get({ id: this.journalId });
+		} catch {
+			return null;
+		}
+	}
+	/**
+	* Mark payment as failed
+	*/
+	markFailed(reason) {
+		this.status = PaymentStatus.FAILED;
+		if (reason) this.notes = `${this.notes ? `${this.notes}
+` : ""}Failed: ${reason}`;
+	}
+	/**
+	* Cancel the payment
+	*/
+	cancel() {
+		if (this.status === PaymentStatus.COMPLETED) throw new Error("Cannot cancel a completed payment. Use refund instead.");
+		this.status = PaymentStatus.CANCELLED;
+	}
+};
+__publicField$1(Payment, "__smrtPackage__", "@happyvertical/smrt-commerce");
+__decorateClass$1([field({ type: "text" })], Payment.prototype, "customerFundsJson", 2);
+__decorateClass$1([field({ sensitive: true })], Payment.prototype, "retentionAccountingBindingJson", 2);
+__decorateClass$1([tenantId({ nullable: true })], Payment.prototype, "tenantId", 2);
+__decorateClass$1([field({ description: "The order or agreement this payment is for, if any." }), foreignKey("SalesContract", { validateSubtype: true })], Payment.prototype, "contractId", 2);
+__decorateClass$1([field({ description: "The customer who paid." }), foreignKey("Customer")], Payment.prototype, "customerId", 2);
+__decorateClass$1([field({
+	description: "How much was paid.",
+	ui: { format: "money" }
+})], Payment.prototype, "amount", 2);
+__decorateClass$1([field({
+	description: "The currency of the payment.",
+	ui: { widget: "currency" }
+})], Payment.prototype, "currency", 2);
+__decorateClass$1([field({ description: "How it was paid: cash, check, card, bank transfer or other." })], Payment.prototype, "method", 2);
+__decorateClass$1([field({ description: "Whether the payment is pending, completed, failed or refunded." })], Payment.prototype, "status", 2);
+__decorateClass$1([field({ description: "A reference note, such as a check number." })], Payment.prototype, "reference", 2);
+__decorateClass$1([crossPackageRef("@happyvertical/smrt-ledgers:Journal")], Payment.prototype, "journalId", 2);
+__decorateClass$1([field({ description: "When the money was received." })], Payment.prototype, "paidAt", 2);
+__decorateClass$1([field({
+	description: "Anything worth remembering about this payment.",
+	ui: { widget: "textarea" }
+})], Payment.prototype, "notes", 2);
+Payment = __decorateClass$1([TenantScoped({ mode: "optional" }), smrt({
+	api: {
+		include: [
+			"list",
+			"get",
+			"create",
+			"update"
+		],
+		writable: [
+			"kind",
+			"contractId",
+			"customerId",
+			"amount",
+			"currency",
+			"method",
+			"transactionId",
+			"reference",
+			"notes",
+			"externalId",
+			"externalProvider",
+			"backendId",
+			"backendTxRef",
+			"nativeAmount",
+			"nativeCurrency",
+			"usdAtQuote",
+			"usdAtConfirmation"
+		]
+	},
+	mcp: { include: ["list", "get"] },
+	cli: { skipApiCheck: true }
+})], Payment);
+//#endregion
+//#region src/collections/PaymentCollection.ts
+var PaymentCollection_exports = /* @__PURE__ */ __exportAll({ PaymentCollection: () => PaymentCollection });
+var PaymentCollection = class extends SmrtCollection {
+	static _itemClass = Payment;
+	/**
+	* Find payments by contract
+	*
+	* @param contractId - Contract ID
+	* @returns Array of payments
+	*/
+	async findByContract(contractId) {
+		return await this.list({
+			where: { contractId },
+			orderBy: "created_at DESC"
+		});
+	}
+	/**
+	* Find payments by customer
+	*
+	* @param customerId - Customer ID
+	* @returns Array of payments
+	*/
+	async findByCustomer(customerId) {
+		return await this.list({
+			where: { customerId },
+			orderBy: "created_at DESC"
+		});
+	}
+	/**
+	* Find payments by status
+	*
+	* @param status - Payment status
+	* @returns Array of payments
+	*/
+	async findByStatus(status) {
+		return await this.list({
+			where: { status },
+			orderBy: "created_at DESC"
+		});
+	}
+	/**
+	* Find payments by method
+	*
+	* @param method - Payment method
+	* @returns Array of payments
+	*/
+	async findByMethod(method) {
+		return await this.list({
+			where: { method },
+			orderBy: "created_at DESC"
+		});
+	}
+	/**
+	* Find all pending payments
+	*
+	* @returns Array of pending payments
+	*/
+	async findPending() {
+		return await this.findByStatus(PaymentStatus.PENDING);
+	}
+	/**
+	* Find all completed payments
+	*
+	* @returns Array of completed payments
+	*/
+	async findCompleted() {
+		return await this.findByStatus(PaymentStatus.COMPLETED);
+	}
+	/**
+	* Find payment by transaction ID
+	*
+	* @param transactionId - External transaction ID
+	* @returns Payment or null
+	*/
+	async findByTransactionId(transactionId) {
+		return (await this.list({
+			where: { transactionId },
+			limit: 1
+		}))[0] || null;
+	}
+	/**
+	* Find payments in date range
+	*
+	* @param startDate - Start date
+	* @param endDate - End date
+	* @returns Array of payments
+	*/
+	async findByDateRange(startDate, endDate) {
+		return await this.list({
+			where: {
+				"paidAt >=": startDate.toISOString(),
+				"paidAt <=": endDate.toISOString()
+			},
+			orderBy: "paidAt DESC"
+		});
+	}
+	/**
+	* Calculate total payments for a contract
+	*
+	* @param contractId - Contract ID
+	* @returns Total amount paid
+	*/
+	async getTotalForContract(contractId) {
+		return (await this.list({ where: {
+			contractId,
+			status: PaymentStatus.COMPLETED
+		} })).reduce((sum, payment) => sum + payment.amount, 0);
+	}
+	/**
+	* Find payments linked to a ledger journal
+	*
+	* @param journalId - Journal ID from smrt-ledgers
+	* @returns Payment or null
+	*/
+	async findByJournal(journalId) {
+		return (await this.list({
+			where: { journalId },
+			limit: 1
+		}))[0] || null;
+	}
+	/**
+	* Find all payments belonging to a specific tenant
+	*
+	* @param tenantId - Tenant ID
+	* @returns Array of payments for the tenant
+	*/
+	async findByTenant(tenantId) {
+		return this.list({ where: { tenantId } });
+	}
+	/**
+	* Find all global payments (not associated with any tenant).
+	*
+	* Routes through the shared tenant-global helper so it does not throw under
+	* an active tenant context (an explicit `tenant_id IS NULL` filter would be
+	* flagged as an isolation violation). (#1600)
+	*
+	* @returns Array of global payments
+	*/
+	async findGlobal() {
+		return queryGlobal(this);
+	}
+	/**
+	* Find payments for a tenant including global payments.
+	*
+	* Fails closed if an active tenant context requests a different tenant's
+	* rows; the admin/system path keeps the cross-tenant capability. (#1600)
+	*
+	* @param tenantId - Tenant ID
+	* @returns Array of tenant-specific and global payments
+	*/
+	async findWithGlobals(tenantId) {
+		return queryWithGlobals(this, tenantId, "Payment.findWithGlobals");
+	}
+};
+//#endregion
+//#region src/historical-funds-internal.ts
+async function exists(db) {
+	return isPostgresDatabase(db) ? (await db.query("SELECT to_regclass(?) AS relation", ["historical_customer_funds_allocations"])).rows[0]?.relation != null : db.tableExists("historical_customer_funds_allocations");
+}
+async function historicalInvoiceAllocationTotal(db, invoiceId, effect) {
+	if (effect === "refund") return historicalCreditRefundCommittedTotal(db, invoiceId);
+	if (!await exists(db)) return historicalCreditRefundCommittedTotal(db, invoiceId);
+	const tenantId = getTenantId();
+	if (!tenantId) {
+		if ((await db.query("SELECT id FROM historical_customer_funds_allocations WHERE invoice_id=? LIMIT 1", invoiceId)).rows.length) throw new Error("Historical allocation capacity requires the explicit active tenant");
+		return historicalCreditRefundCommittedTotal(db, invoiceId);
+	}
+	const rows = await (await HistoricalCustomerFundsAllocationCollection.create({ db })).list({
+		where: {
+			tenantId,
+			invoiceId,
+			effect: "payment"
+		},
+		limit: 100001
+	});
+	if (rows.length > 1e5) throw new Error("Historical allocation capacity exceeds the bounded source scope");
+	const total = rows.filter((row) => row.effect === "payment").reduce((sum, row) => sum + BigInt(row.amountMinor), 0n);
+	if (total > BigInt(Number.MAX_SAFE_INTEGER)) throw new Error("Historical allocation capacity is unsafe");
+	const combined = total + BigInt(effect === "payment" ? 0 : await historicalCreditRefundCommittedTotal(db, invoiceId));
+	if (combined > BigInt(Number.MAX_SAFE_INTEGER)) throw new Error("Historical combined capacity is unsafe");
+	return Number(combined);
+}
+async function historicalCreditRefundCommittedTotal(db, creditNoteId) {
+	if (!(isPostgresDatabase(db) ? (await db.query("SELECT to_regclass(?) AS relation", ["historical_customer_funds"])).rows[0]?.relation != null : await db.tableExists("historical_customer_funds"))) return 0;
+	const tenantId = getTenantId();
+	if (!tenantId) {
+		if ((await db.query("SELECT id FROM historical_customer_funds WHERE source_credit_note_id=? LIMIT 1", creditNoteId)).rows.length) throw new Error("Historical refund capacity requires the explicit active tenant");
+		return 0;
+	}
+	const { HistoricalCustomerFundsCollection } = await import("./HistoricalCustomerFundsCollections-B5x8gTW3.js").then((n) => n.r);
+	const rows = await (await HistoricalCustomerFundsCollection.create({ db })).list({
+		where: {
+			tenantId,
+			sourceCreditNoteId: creditNoteId,
+			kind: "refund"
+		},
+		limit: 100001
+	});
+	if (rows.length > 1e5) throw new Error("Historical credit refund source scope exceeds its bounded limit");
+	const total = rows.reduce((sum, row) => sum + BigInt(row.amountMinor), 0n);
+	if (total > BigInt(Number.MAX_SAFE_INTEGER)) throw new Error("Historical refund source total is unsafe");
+	return Number(total);
+}
+//#endregion
+//#region src/models/PaymentAllocation.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 PaymentAllocation = class extends SmrtObject {
+	tenantId = null;
+	paymentId = "";
+	invoiceId = "";
+	amount = 0;
+	allocatedAt = /* @__PURE__ */ new Date();
+	/**
+	* User/agent who made the allocation
+	*/
+	allocatedBy = "";
+	notes = "";
+	constructor(options = {}) {
+		super(options);
+		if (options.tenantId !== void 0) this.tenantId = options.tenantId;
+		if (options.paymentId !== void 0) this.paymentId = options.paymentId;
+		if (options.invoiceId !== void 0) this.invoiceId = options.invoiceId;
+		if (options.amount !== void 0) this.amount = options.amount;
+		if (options.allocatedAt !== void 0) this.allocatedAt = options.allocatedAt;
+		if (options.allocatedBy !== void 0) this.allocatedBy = options.allocatedBy;
+		if (options.notes !== void 0) this.notes = options.notes;
+	}
+	/** Save and validate against both claimed parent rows in one transaction. */
+	async save() {
+		assertIntegerMinorUnits("PaymentAllocation", this.id ?? "<new>", [["amount", this.amount]]);
+		if (this.amount <= 0) throw new Error("PaymentAllocation amount must be a positive number");
+		if (!this.paymentId || !this.invoiceId) throw new Error("PaymentAllocation requires payment and invoice");
+		return this.withTransaction(async () => {
+			const { PaymentCollection } = await Promise.resolve().then(() => PaymentCollection_exports);
+			const { InvoiceCollection } = await import("./InvoiceCollection-BIcge9Wl.js").then((n) => n.n);
+			const { PaymentAllocationCollection } = await Promise.resolve().then(() => PaymentAllocationCollection_exports);
+			const payments = await PaymentCollection.create({ db: this.db });
+			const invoices = await InvoiceCollection.create({ db: this.db });
+			const allocations = await PaymentAllocationCollection.create({ db: this.db });
+			const prior = this.id ? await allocations.get({ id: this.id }, { cache: false }) : null;
+			if (prior && (prior.paymentId !== this.paymentId || prior.invoiceId !== this.invoiceId || prior.tenantId !== allocationOwner(this.tenantId))) throw new Error("PaymentAllocation parent identity is immutable");
+			const payment = await payments.get({ id: this.paymentId }, { cache: false });
+			if (!payment) throw new Error("PaymentAllocation referenced Payment does not exist");
+			if (payment.retentionAccountingBindingJson) throw new Error("Provider-recorded refund allocation is immutable");
+			if (customerFundsState(payment.customerFundsJson)) assertCustomerFundsWrite(this);
+			if (!payment.updated_at) throw new Error("Allocation parent has no persisted revision");
+			await payment.claimRevision(payment.updated_at);
+			const invoice = await invoices.get({ id: this.invoiceId }, { cache: false });
+			if (!invoice) throw new Error("PaymentAllocation referenced Invoice does not exist");
+			if (!invoice.updated_at) throw new Error("Allocation parent has no persisted revision");
+			await invoice.claimRevision(invoice.updated_at);
+			const owner = allocationOwner(this.tenantId);
+			if (payment.tenantId !== owner || invoice.tenantId !== owner || (payment.customerId || null) !== (invoice.customerId || null) || payment.currency !== invoice.currency) throw new Error("PaymentAllocation requires matching tenant, customer and currency");
+			if (payment.kind === "refund" && invoice.kind !== "credit_note" || payment.kind === "payment" && invoice.kind !== "invoice") throw new Error("PaymentAllocation requires payments on invoices and refunds on credit notes");
+			const paymentTotal = allocationTotal(await allocations.findByPayment(this.paymentId), this.id) + BigInt(this.amount);
+			const invoiceTotal = allocationTotal(await allocations.findByInvoice(this.invoiceId), this.id) + BigInt(this.amount) + BigInt(await historicalInvoiceAllocationTotal(this.db, this.invoiceId));
+			if (paymentTotal > BigInt(payment.amount)) throw new Error("PaymentAllocation would over-apply payment");
+			const invoiceCap = invoice.kind === "invoice" ? invoice.getPayableFacts().allocationCapMinor : invoice.totalAmount;
+			if (invoiceTotal > BigInt(Math.max(0, invoiceCap))) throw new Error("PaymentAllocation would over-pay invoice");
+			if (payment.kind === "refund") {
+				if (payment.status !== "completed") throw new Error("A refund must be settled before it is allocated");
+				if (!invoice.creditedInvoiceId) throw new Error("Refund credit note has no credited invoice");
+				const source = await invoices.get({ id: invoice.creditedInvoiceId }, { cache: false });
+				if (!source || source.tenantId !== owner) throw new Error("Refund source invoice does not exist in its tenant");
+				if (!source.updated_at) throw new Error("Refund source invoice has no persisted revision");
+				await source.claimRevision(source.updated_at);
+				const creditRows = await invoices.list({
+					where: {
+						tenantId: owner,
+						creditedInvoiceId: source.id
+					},
+					limit: 100001
+				});
+				if (creditRows.length > 1e5) throw new Error("Refund credit scope exceeds its bounded source limit");
+				const credits = creditRows.filter((credit) => credit.kind === "credit_note" && credit.status !== "draft" && credit.status !== "cancelled");
+				const issuedCredits = credits.reduce((sum, credit) => sum + credit.totalAmount, 0);
+				let settledRefunds = 0;
+				for (const credit of credits) {
+					if (!credit.id) continue;
+					settledRefunds += await historicalCreditRefundCommittedTotal(this.db, credit.id);
+					for (const allocation of await allocations.findByInvoice(credit.id)) {
+						if (allocation.id === this.id) continue;
+						const refund = await payments.get({ id: allocation.paymentId }, { cache: false });
+						if (refund?.kind === "refund" && refund.status === "completed") settledRefunds += allocation.amount;
+					}
+				}
+				const availableRefund = calculateAvailableRefund({
+					sourceTotalMinor: source.totalAmount,
+					sourcePaidMinor: source.amountPaid,
+					issuedCreditMinor: issuedCredits,
+					settledRefundMinor: settledRefunds
+				});
+				if (this.amount > availableRefund) throw new Error(`Refund allocation exceeds available unapplied credit (${availableRefund})`);
+			}
+			return await super.save();
+		});
+	}
+	/** Managed application reversal must also post its inverse journal and retain evidence. */
+	async delete(options = {}) {
+		return this.withTransaction(async () => {
+			const persisted = this.id ? await this.db.get(this.tableName, { id: this.id }) : null;
+			const { PaymentCollection } = await Promise.resolve().then(() => PaymentCollection_exports);
+			const payment = await (await PaymentCollection.create({ db: this.db })).get({ id: String(persisted?.payment_id ?? this.paymentId) }, { cache: false });
+			if (payment) {
+				if (!payment.updated_at) throw new Error("Allocation parent has no persisted revision");
+				await payment.claimRevision(payment.updated_at);
+			}
+			if (payment?.retentionAccountingBindingJson) throw new Error("Provider-recorded refund allocation cannot be deleted");
+			if (payment?.customerFundsJson) assertCustomerFundsWrite(this);
+			return super.delete(options);
+		});
+	}
+};
+__publicField(PaymentAllocation, "__smrtPackage__", "@happyvertical/smrt-commerce");
+__decorateClass([tenantId({ nullable: true })], PaymentAllocation.prototype, "tenantId", 2);
+__decorateClass([field({ description: "The payment being applied." }), foreignKey("Payment")], PaymentAllocation.prototype, "paymentId", 2);
+__decorateClass([field({ description: "The invoice it settles." }), foreignKey("Invoice")], PaymentAllocation.prototype, "invoiceId", 2);
+__decorateClass([field({
+	description: "How much of the payment goes to this invoice.",
+	ui: { format: "money" }
+})], PaymentAllocation.prototype, "amount", 2);
+__decorateClass([field({ description: "When it was applied." })], PaymentAllocation.prototype, "allocatedAt", 2);
+__decorateClass([field({ description: "Anything worth remembering about this allocation." })], PaymentAllocation.prototype, "notes", 2);
+PaymentAllocation = __decorateClass([TenantScoped({ mode: "optional" }), smrt({
+	api: { include: ["list", "get"] },
+	mcp: { include: ["list", "get"] },
+	cli: { include: ["list", "get"] }
+})], PaymentAllocation);
+//#endregion
+//#region src/collections/PaymentAllocationCollection.ts
+var PaymentAllocationCollection_exports = /* @__PURE__ */ __exportAll({ PaymentAllocationCollection: () => PaymentAllocationCollection });
+var PaymentAllocationCollection = class PaymentAllocationCollection extends SmrtCollection {
+	static _itemClass = PaymentAllocation;
+	/**
+	* Apply a payment to several invoices atomically. Callers supply stable UUID
+	* allocation ids: exact replays reuse rows; reusing an id with other money
+	* or parents fails. Actor authorization remains the application's job.
+	*/
+	async allocatePayment(input) {
+		if (!input.allocations.length || new Set(input.allocations.map((item) => item.id)).size !== input.allocations.length) throw new Error("Allocation batch requires distinct stable allocation ids");
+		const { PaymentCollection } = await Promise.resolve().then(() => PaymentCollection_exports);
+		const { InvoiceCollection } = await import("./InvoiceCollection-BIcge9Wl.js").then((n) => n.n);
+		const { InvoiceStatus } = await import("./types-Bbm0Xflc.js").then((n) => n.m);
+		const payment = await (await PaymentCollection.create({ db: this.db })).get({ id: input.paymentId }, { cache: false });
+		if (!payment) throw new Error("Payment does not exist");
+		const committed = await payment.withTransaction(async () => {
+			if (!payment.updated_at) throw new Error("Allocation parent has no persisted revision");
+			await payment.claimRevision(payment.updated_at);
+			const allocations = await PaymentAllocationCollection.create({ db: payment.db });
+			const invoices = await InvoiceCollection.create({ db: payment.db });
+			const result = [];
+			for (const item of [...input.allocations].sort((a, b) => a.invoiceId.localeCompare(b.invoiceId) || a.id.localeCompare(b.id))) {
+				if (!item.id) throw new Error("Allocation requires a stable id");
+				const existing = await allocations.get({ id: item.id }, { cache: false });
+				if (existing) {
+					if (existing.paymentId !== input.paymentId || existing.invoiceId !== item.invoiceId || existing.amount !== item.amount || existing.tenantId !== payment.tenantId) throw new Error("Allocation replay does not match existing allocation");
+					result.push(existing);
+				} else result.push(await allocations.create({
+					...item,
+					paymentId: input.paymentId,
+					tenantId: payment.tenantId,
+					allocatedBy: input.allocatedBy ?? "",
+					_insertOnly: true
+				}));
+			}
+			for (const invoiceId of [...new Set(input.allocations.map((item) => item.invoiceId))].sort()) {
+				const invoice = await invoices.get({ id: invoiceId }, { cache: false });
+				if (!invoice) throw new Error("Invoice does not exist");
+				if (invoice.status !== InvoiceStatus.WRITTEN_OFF) invoice.updatePaymentStatus(await allocations.getTotalAllocatedToInvoice(invoiceId));
+				await invoice.save();
+			}
+			return result;
+		});
+		return Promise.all(committed.map(async ({ id }) => {
+			const allocation = await this.get({ id: String(id) }, { cache: false });
+			if (!allocation) throw new Error("Committed allocation no longer exists");
+			return allocation;
+		}));
+	}
+	/** Remove one allocation atomically and rederive its invoice/credit status. */
+	async removeAllocation(id) {
+		const allocation = await this.get({ id }, { cache: false });
+		if (!allocation) return;
+		const { PaymentCollection } = await Promise.resolve().then(() => PaymentCollection_exports);
+		const { InvoiceCollection } = await import("./InvoiceCollection-BIcge9Wl.js").then((n) => n.n);
+		const payment = await (await PaymentCollection.create({ db: this.db })).get({ id: allocation.paymentId }, { cache: false });
+		if (!payment) throw new Error("Allocation payment does not exist");
+		await payment.withTransaction(async () => {
+			const rows = await PaymentAllocationCollection.create({ db: payment.db });
+			const current = await rows.get({ id }, { cache: false });
+			if (!current) return;
+			const invoice = await (await InvoiceCollection.create({ db: payment.db })).get({ id: current.invoiceId }, { cache: false });
+			if (!invoice) throw new Error("Allocation invoice does not exist");
+			await current.delete();
+			invoice.updatePaymentStatus(await rows.getTotalAllocatedToInvoice(current.invoiceId));
+			await invoice.save();
+		});
+	}
+	/**
+	* Find allocations by payment
+	*
+	* @param paymentId - Payment ID
+	* @returns Array of allocations
+	*/
+	async allFor(field, id) {
+		const rows = [];
+		for (let offset = 0;; offset += 1e3) {
+			const page = await this.list({
+				where: { [field]: id },
+				orderBy: ["allocatedAt DESC", "id ASC"],
+				offset,
+				limit: 1e3
+			});
+			rows.push(...page);
+			if (page.length < 1e3) return rows;
+		}
+	}
+	async findByPayment(paymentId) {
+		return this.allFor("paymentId", paymentId);
+	}
+	/** Every committed row participates in payment and historical combined capacity. */
+	async findByInvoice(invoiceId) {
+		return this.allFor("invoiceId", invoiceId);
+	}
+	/**
+	* Get total amount allocated to an invoice
+	*
+	* @param invoiceId - Invoice ID
+	* @returns Total allocated amount
+	*/
+	async getTotalAllocatedToInvoice(invoiceId) {
+		const total = (await this.findByInvoice(invoiceId)).reduce((sum, alloc) => sum + BigInt(alloc.amount), BigInt(await historicalInvoiceAllocationTotal(this.db, invoiceId)));
+		if (total > BigInt(Number.MAX_SAFE_INTEGER)) throw new Error("Combined invoice allocation total is unsafe");
+		return Number(total);
+	}
+	/**
+	* Get total amount allocated from a payment
+	*
+	* @param paymentId - Payment ID
+	* @returns Total allocated amount
+	*/
+	async getTotalAllocatedFromPayment(paymentId) {
+		return (await this.findByPayment(paymentId)).reduce((sum, alloc) => sum + alloc.amount, 0);
+	}
+	/**
+	* Get remaining unallocated amount from a payment.
+	*
+	* @param paymentId - Payment ID
+	* @param paymentAmount - Total payment amount
+	* @returns Unallocated amount
+	* @throws Error if payment is over-allocated (indicates data integrity issue)
+	*/
+	async getUnallocatedFromPayment(paymentId, paymentAmount) {
+		const allocated = await this.getTotalAllocatedFromPayment(paymentId);
+		const { PaymentCollection } = await Promise.resolve().then(() => PaymentCollection_exports);
+		const payment = await (await PaymentCollection.create({ db: this.db })).get({ id: paymentId }, { cache: false });
+		const managed = customerFundsState(payment?.customerFundsJson);
+		if (managed && (managed.kind !== "receipt" || payment?.amount !== paymentAmount)) throw new Error("Customer funds require their authoritative receipt amount");
+		const refunded = managed?.operations.filter((op) => op.kind === "refund").reduce((sum, op) => sum + BigInt(op.amountMinor), 0n) ?? 0n;
+		const remaining = Number(BigInt(paymentAmount) - BigInt(allocated) - refunded);
+		if (remaining < 0) throw new Error(`Over-allocated payment detected for paymentId=${paymentId}: allocated amount (${allocated}) exceeds payment amount (${paymentAmount})`);
+		return remaining;
+	}
+	/**
+	* Find allocation by payment and invoice
+	*
+	* @param paymentId - Payment ID
+	* @param invoiceId - Invoice ID
+	* @returns Allocation or null
+	*/
+	async findByPaymentAndInvoice(paymentId, invoiceId) {
+		return (await this.list({
+			where: {
+				paymentId,
+				invoiceId
+			},
+			limit: 1
+		}))[0] || null;
+	}
+	/**
+	* Find allocations by allocator
+	*
+	* @param allocatedBy - User/agent ID who made the allocation
+	* @returns Array of allocations
+	*/
+	async findByAllocator(allocatedBy) {
+		return await this.list({
+			where: { allocatedBy },
+			orderBy: "allocatedAt DESC"
+		});
+	}
+	/**
+	* Find allocations in date range
+	*
+	* @param startDate - Start date
+	* @param endDate - End date
+	* @returns Array of allocations
+	*/
+	async findByDateRange(startDate, endDate) {
+		return await this.list({
+			where: {
+				"allocatedAt >=": startDate.toISOString(),
+				"allocatedAt <=": endDate.toISOString()
+			},
+			orderBy: "allocatedAt DESC"
+		});
+	}
+	/**
+	* Find all payment allocations belonging to a specific tenant
+	*
+	* @param tenantId - Tenant ID
+	* @returns Array of payment allocations for the tenant
+	*/
+	async findByTenant(tenantId) {
+		return this.list({ where: { tenantId } });
+	}
+	/**
+	* Find all global payment allocations (not associated with any tenant).
+	*
+	* Routes through the shared tenant-global helper so it does not throw under
+	* an active tenant context (an explicit `tenant_id IS NULL` filter would be
+	* flagged as an isolation violation). (#1600)
+	*
+	* @returns Array of global payment allocations
+	*/
+	async findGlobal() {
+		return queryGlobal(this);
+	}
+	/**
+	* Find payment allocations for a tenant including global allocations.
+	*
+	* Fails closed if an active tenant context requests a different tenant's
+	* rows; the admin/system path keeps the cross-tenant capability. (#1600)
+	*
+	* @param tenantId - Tenant ID
+	* @returns Array of tenant-specific and global payment allocations
+	*/
+	async findWithGlobals(tenantId) {
+		return queryWithGlobals(this, tenantId, "PaymentAllocation.findWithGlobals");
+	}
+};
+//#endregion
+//#region src/accounting-snapshot.ts
+function requireText(value, label) {
+	if (!value || value.trim() !== value) throw new Error(`${label} must be a nonempty trimmed string`);
+	return value;
+}
+function requireSafeMinor(value, label) {
+	if (!Number.isSafeInteger(value) || value < 0) throw new Error(`${label} must be a nonnegative safe integer minor amount`);
+	return value;
+}
+function requirePositiveQuantity(quantity, lineId) {
+	if (!Number.isFinite(quantity) || quantity <= 0) throw new Error(`Line '${lineId}' quantity must be a positive finite number`);
+	return quantity;
+}
+function percentToFraction(percent, componentId) {
+	if (!/^(?:0|[1-9]\d{0,2})(?:\.\d{1,6})?$/.test(percent)) throw new Error(`Tax component '${componentId}' percent must be exact decimal text from 0 through 100`);
+	const [whole, fraction = ""] = percent.split(".");
+	const scale = 10n ** BigInt(fraction.length);
+	const numerator = BigInt(whole) * scale + BigInt(fraction || "0");
+	const denominator = 100n * scale;
+	if (numerator > denominator) throw new Error(`Tax component '${componentId}' percent exceeds 100`);
+	if (numerator === 0n) return "0";
+	if (numerator === denominator) return "1";
+	return `0.${numerator.toString().padStart(denominator.toString().length - 1, "0")}`.replace(/0+$/, "");
+}
+function globalTaxCalculation(lineAmountType) {
+	switch (lineAmountType) {
+		case "exclusive": return "TaxExcluded";
+		case "inclusive": return "TaxInclusive";
+		case "none": return "NotApplicable";
+	}
+}
+function mapLine(line, currency, lineAmountType, mapping) {
+	requireText(line.id, "Line ID");
+	const lineMapping = mapping.lines[line.id];
+	if (!lineMapping) throw new Error(`Missing explicit QuickBooks mapping for line '${line.id}'`);
+	requireText(lineMapping.itemRef, `QuickBooks item reference for line '${line.id}'`);
+	requireText(lineMapping.taxCodeRef, `QuickBooks tax-code reference for line '${line.id}'`);
+	const amountMinor = requireSafeMinor(line.amountMinor, `Line '${line.id}' amount`);
+	const taxMinor = requireSafeMinor(line.taxMinor, `Line '${line.id}' tax`);
+	const componentIds = /* @__PURE__ */ new Set();
+	let componentTotalMinor = 0;
+	const taxComponents = line.taxComponents.map((component) => {
+		if (component.compound !== void 0 && typeof component.compound !== "boolean") throw new MoneyValidationError("INVALID_MONEY_INPUT", "Frozen component compound flag must be boolean");
+		if (component.compound && !lineMapping.taxComponents) throw new MoneyValidationError("ACCOUNTING_SYNC_UNSUPPORTED", "Compound accounting sync requires caller-verified ordered realm tax-code mapping");
+		if (component.compound && component.taxableMinor === void 0) throw new MoneyValidationError("ACCOUNTING_SYNC_UNSUPPORTED", "Compound accounting sync requires the frozen component taxable basis");
+		const basisMinor = component.taxableMinor === void 0 ? void 0 : requireSafeMinor(component.taxableMinor, `Line '${line.id}' component taxable basis`);
+		if (basisMinor !== void 0 && basisMinor !== amountMinor + (component.compound ? componentTotalMinor : 0)) throw new MoneyValidationError("ACCOUNTING_SYNC_UNSUPPORTED", "Frozen component taxable basis does not match ordered source facts");
+		requireText(component.taxComponentId, `Line '${line.id}' tax component ID`);
+		if (componentIds.has(component.taxComponentId)) throw new Error(`Line '${line.id}' repeats tax component '${component.taxComponentId}'`);
+		componentIds.add(component.taxComponentId);
+		const taxAmountMinor = requireSafeMinor(component.taxMinor, `Line '${line.id}' component '${component.taxComponentId}' tax`);
+		componentTotalMinor += taxAmountMinor;
+		const componentMapping = mapping.components[component.taxComponentId];
+		if (!componentMapping) throw new Error(`Missing explicit QuickBooks tax-rate reference for component '${component.taxComponentId}'`);
+		requireText(componentMapping.quickbooksTaxRateRef, `QuickBooks tax-rate reference for component '${component.taxComponentId}'`);
+		return {
+			taxCode: component.taxComponentId,
+			rate: percentToFraction(component.percent, component.taxComponentId),
+			quickbooksTaxRateRef: componentMapping.quickbooksTaxRateRef,
+			taxAmount: minorToMajorUnits(taxAmountMinor, currency),
+			...component.compound ? { compound: true } : {},
+			...basisMinor !== void 0 ? { taxableAmount: minorToMajorUnits(basisMinor, currency) } : {}
+		};
+	});
+	if (lineMapping.taxComponents && (lineMapping.taxComponents.length !== taxComponents.length || lineMapping.taxComponents.some((part, index) => part.taxRateRef !== taxComponents[index].quickbooksTaxRateRef || typeof part.compound !== "boolean" || part.compound !== (taxComponents[index].compound ?? false)))) throw new MoneyValidationError("ACCOUNTING_SYNC_UNSUPPORTED", "Ordered realm tax-code mapping does not match frozen components");
+	if (componentTotalMinor !== taxMinor) throw new Error(`Line '${line.id}' frozen component tax ${componentTotalMinor} does not equal line tax ${taxMinor}`);
+	if (taxMinor > 0 && taxComponents.length === 0) throw new Error(`Line '${line.id}' tax requires frozen tax components`);
+	const discountMinor = requireSafeMinor(line.discountMinor, `Line '${line.id}' discount`);
+	const unitPriceMinor = requireSafeMinor(line.unitPriceMinor, `Line '${line.id}' unit price`);
+	const result = {
+		description: requireText(line.description, `Line '${line.id}' description`),
+		sku: line.sku || void 0,
+		quantity: requirePositiveQuantity(line.quantity, line.id),
+		unitPrice: minorToMajorUnits(unitPriceMinor, currency),
+		...discountMinor === 0 ? {} : { discount: minorToMajorUnits(discountMinor, currency) },
+		amount: minorToMajorUnits(amountMinor, currency),
+		taxAmount: minorToMajorUnits(taxMinor, currency),
+		taxComponents,
+		quickbooksMapping: {
+			itemRef: lineMapping.itemRef,
+			taxCodeRef: lineMapping.taxCodeRef,
+			...lineMapping.taxComponents ? { taxComponents: lineMapping.taxComponents.map((part) => ({ ...part })) } : {}
+		}
+	};
+	if (lineAmountType === "inclusive") return {
+		...result,
+		taxInclusiveAmount: minorToMajorUnits(amountMinor + taxMinor, currency)
+	};
+	return result;
+}
+function mapFrozenAccountingSnapshot(snapshot, mapping) {
+	const currency = requireText(snapshot.currency, "Currency");
+	requireText(snapshot.id, "Document ID");
+	requireText(snapshot.number, "Document number");
+	requireText(snapshot.customerId, "Customer ID");
+	if (!(snapshot.issueDate instanceof Date) || Number.isNaN(snapshot.issueDate.valueOf())) throw new Error("Issue date must be a valid Date");
+	if (!Array.isArray(snapshot.lineItems) || snapshot.lineItems.length === 0) throw new Error("Frozen document requires at least one line item");
+	const subtotalMinor = requireSafeMinor(snapshot.subtotalMinor, "Subtotal");
+	const taxAmountMinor = requireSafeMinor(snapshot.taxAmountMinor, "Tax amount");
+	const providerTaxMinor = requireSafeMinor(snapshot.providerTaxMinor, "Provider tax");
+	const totalAmountMinor = requireSafeMinor(snapshot.totalAmountMinor, "Total");
+	if (providerTaxMinor !== 0) throw new Error("Frozen provider tax cannot be mapped to QuickBooks without a stored component snapshot and explicit tax-rate reference");
+	if (subtotalMinor + taxAmountMinor !== totalAmountMinor) throw new Error("Frozen subtotal plus tax must equal frozen total");
+	const lineItems = snapshot.lineItems.map((line) => mapLine(line, currency, snapshot.lineAmountType, mapping));
+	const linesSubtotalMinor = snapshot.lineItems.reduce((sum, line) => sum + line.amountMinor, 0);
+	const linesTaxMinor = snapshot.lineItems.reduce((sum, line) => sum + line.taxMinor, 0);
+	if (linesSubtotalMinor !== subtotalMinor) throw new Error("Frozen line net amounts do not equal frozen subtotal");
+	if (linesTaxMinor !== taxAmountMinor) throw new Error("Frozen line tax amounts do not equal frozen tax total");
+	const base = {
+		id: snapshot.id,
+		externalId: snapshot.externalId,
+		customerId: snapshot.customerId,
+		customerExternalId: snapshot.customerExternalId,
+		issueDate: snapshot.issueDate,
+		currency,
+		subtotal: minorToMajorUnits(subtotalMinor, currency),
+		taxAmount: minorToMajorUnits(taxAmountMinor, currency),
+		totalAmount: minorToMajorUnits(totalAmountMinor, currency),
+		lineItems,
+		quickbooksMapping: { globalTaxCalculation: globalTaxCalculation(snapshot.lineAmountType) },
+		reference: snapshot.reference,
+		memo: snapshot.memo
+	};
+	if (snapshot.kind === "invoice") {
+		if (!(snapshot.dueDate instanceof Date) || Number.isNaN(snapshot.dueDate.valueOf())) throw new Error("Invoice due date must be a valid Date");
+		return {
+			...base,
+			invoiceNumber: snapshot.number,
+			dueDate: snapshot.dueDate
+		};
+	}
+	const creditedInvoiceExternalId = requireText(snapshot.creditedInvoiceExternalId, "Credited invoice external ID");
+	if (subtotalMinor === 0 || totalAmountMinor === 0) throw new Error("Credit memo amounts must be positive");
+	return {
+		...base,
+		creditMemoNumber: snapshot.number,
+		creditedInvoiceExternalId
+	};
+}
+//#endregion
+//#region src/invoice-accounting-sync.ts
+var invoice_accounting_sync_exports = /* @__PURE__ */ __exportAll({
+	loadFrozenInvoiceAccountingSnapshot: () => loadFrozenInvoiceAccountingSnapshot,
+	readFrozenAccountingSyncState: () => readFrozenAccountingSyncState,
+	reconcileFrozenInvoiceAccountingSync: () => reconcileFrozenInvoiceAccountingSync,
+	syncFrozenInvoiceToAccounting: () => syncFrozenInvoiceToAccounting,
+	toFrozenInvoiceAccountingInput: () => toFrozenInvoiceAccountingInput
+});
+function requiredText(value, label) {
+	if (!value || value.trim() !== value) throw new MoneyValidationError("INVALID_MONEY_INPUT", `${label} must be a nonempty trimmed string`);
+	return value;
+}
+function assertPrincipalTenant(tenantId) {
+	requiredText(tenantId, "Accounting tenant");
+	if (getTenantId() !== tenantId) throw new MoneyValidationError("INVALID_MONEY_INPUT", "Accounting sync requires its active principal tenant");
+}
+function unsupported(message) {
+	throw new MoneyValidationError("ACCOUNTING_SYNC_UNSUPPORTED", message);
+}
+function parseSyncState(value) {
+	if (!value) return null;
+	try {
+		const parsed = JSON.parse(value);
+		if (!parsed || typeof parsed !== "object") throw new Error("not object");
+		const state = parsed;
+		const identity = state.identity;
+		if (state.version !== 1 || ![
+			"in_flight",
+			"unknown",
+			"rejected",
+			"synced"
+		].includes(String(state.status)) || !identity || identity.provider !== "quickbooks" || typeof identity.realmId !== "string" || identity.environment !== "sandbox" && identity.environment !== "production" || typeof identity.invoiceId !== "string" || typeof identity.moneySnapshotId !== "string" || typeof identity.requestId !== "string" || typeof identity.payloadHash !== "string" || identity.documentKind !== void 0 && identity.documentKind !== "invoice" && identity.documentKind !== "creditMemo" || identity.creditedInvoiceExternalId !== void 0 && typeof identity.creditedInvoiceExternalId !== "string" || typeof state.attemptId !== "string" || typeof state.startedAt !== "string") throw new Error("invalid shape");
+		return {
+			...state,
+			identity: {
+				...identity,
+				documentKind: identity.documentKind ?? "invoice"
+			}
+		};
+	} catch {
+		throw new MoneyValidationError("ACCOUNTING_SYNC_RECONCILIATION_REQUIRED", "Stored accounting sync state is malformed and requires reconciliation");
+	}
+}
+function sameIdentity(left, right) {
+	return left.provider === right.provider && left.documentKind === right.documentKind && left.realmId === right.realmId && left.environment === right.environment && left.invoiceId === right.invoiceId && left.moneySnapshotId === right.moneySnapshotId && left.requestId === right.requestId && left.payloadHash === right.payloadHash && left.creditedInvoiceExternalId === right.creditedInvoiceExternalId;
+}
+function sameSyncScope(identity, snapshot, mapping) {
+	return identity.provider === "quickbooks" && identity.documentKind === snapshot.document.kind && identity.realmId === mapping.realmId && identity.environment === mapping.environment && identity.invoiceId === snapshot.document.id && identity.moneySnapshotId === snapshot.moneySnapshotId;
+}
+function sum(values) {
+	let result = 0n;
+	for (const value of values) {
+		if (!Number.isSafeInteger(value)) throw new MoneyValidationError("UNSAFE_MONEY", "Frozen accounting facts require safe integer minor units");
+		result += BigInt(value);
+	}
+	if (result > BigInt(Number.MAX_SAFE_INTEGER) || result < BigInt(Number.MIN_SAFE_INTEGER)) throw new MoneyValidationError("UNSAFE_MONEY", "Frozen accounting totals exceed safe integer minor units");
+	return Number(result);
+}
+function componentTotals(lines) {
+	const totals = /* @__PURE__ */ new Map();
+	for (const line of lines) for (const component of line.taxComponents) totals.set(component.taxComponentId, sum([totals.get(component.taxComponentId) ?? 0, component.taxMinor]));
+	return totals;
+}
+async function loadSnapshot(db, tenantId, invoice) {
+	if (invoice.moneyAuthority === "historical") throw new MoneyValidationError("ACCOUNTING_SYNC_UNSUPPORTED", "Historical sales source money requires an explicit reviewed provider representation; no quantities or tax breakdown will be invented");
+	if (invoice.tenantId !== tenantId) throw new MoneyValidationError("INVALID_MONEY_INPUT", "Accounting invoice cannot cross tenant boundaries");
+	if (invoice.status === InvoiceStatus.DRAFT || !invoice.moneySnapshotId) throw new MoneyValidationError("FROZEN_DOCUMENT", "Accounting sync requires an issued frozen invoice");
+	if ((invoice.getPayableFacts().retainedRemainingMinor > 0 || invoice.retentionAccountingStateJson) && !hasRetentionAccountingAuthority(invoice.tenantId, invoice.id)) unsupported("Unreleased retention requires a provider payable representation");
+	if (invoice.status === InvoiceStatus.CANCELLED) unsupported("Cancelled documents cannot be created by accounting sync");
+	const lines = await (await InvoiceLineItemCollection.create({ db })).findByInvoice(requiredText(invoice.id ?? "", "Accounting invoice ID"));
+	if (lines.length === 0) throw new MoneyValidationError("INVALID_MONEY_INPUT", "Frozen accounting invoice requires at least one line");
+	for (const line of lines) if (line.tenantId !== tenantId || line.moneySnapshotId !== invoice.moneySnapshotId) throw new MoneyValidationError("FROZEN_DOCUMENT", "Accounting line snapshot does not match its frozen invoice");
+	const taxes = await (await DocumentTaxCollection.create({ db })).findByDocument(tenantId, invoice.kind, invoice.id ?? "");
+	const lineTax = sum(lines.map((line) => line.taxAmount));
+	const storedTax = sum(taxes.map((row) => row.taxMinor));
+	if (lineTax + invoice.providerTaxAmount !== invoice.taxAmount || storedTax !== lineTax) throw new MoneyValidationError("INVALID_MONEY_INPUT", "Frozen line, DocumentTax, and invoice tax totals do not reconcile");
+	const lineComponents = componentTotals(lines);
+	const storedComponents = /* @__PURE__ */ new Map();
+	for (const row of taxes) {
+		if (!row.taxComponentId) continue;
+		storedComponents.set(row.taxComponentId, sum([storedComponents.get(row.taxComponentId) ?? 0, row.taxMinor]));
+	}
+	if ([.../* @__PURE__ */ new Set([...lineComponents.keys(), ...storedComponents.keys()])].some((id) => (lineComponents.get(id) ?? 0) !== (storedComponents.get(id) ?? 0))) throw new MoneyValidationError("INVALID_MONEY_INPUT", "Frozen line components do not reconcile to DocumentTax");
+	let creditedInvoiceExternalId;
+	let creditedInvoiceScope;
+	if (invoice.kind === "credit_note") {
+		if (!invoice.creditedInvoiceId) throw new MoneyValidationError("INVALID_MONEY_INPUT", "Frozen credit note requires its credited invoice");
+		const source = await (await InvoiceCollection.create({ db })).get({ id: invoice.creditedInvoiceId }, { cache: false });
+		if (!source || source.tenantId !== tenantId || !source.externalId) throw new MoneyValidationError("INVALID_MONEY_INPUT", "Frozen credit note requires the source invoice external ID");
+		if (source.retentionAccountingStateJson && !hasRetentionAccountingAuthority(source.tenantId, source.id)) unsupported("Provider-retained credit requires the retained-first accounting adjustment command");
+		const sourceState = parseSyncState(source.accountingSyncStateJson);
+		if (sourceState?.status !== "synced" || sourceState.externalId !== source.externalId) throw new MoneyValidationError("ACCOUNTING_SYNC_RECONCILIATION_REQUIRED", "Frozen credit note requires a reconciled source invoice accounting identity");
+		creditedInvoiceExternalId = source.externalId;
+		creditedInvoiceScope = {
+			provider: sourceState.identity.provider,
+			realmId: sourceState.identity.realmId,
+			environment: sourceState.identity.environment
+		};
+	}
+	return {
+		moneySnapshotId: invoice.moneySnapshotId,
+		creditedInvoiceScope,
+		document: {
+			kind: invoice.kind === "invoice" ? "invoice" : "creditMemo",
+			id: invoice.id ?? "",
+			number: invoice.invoiceNumber,
+			customerId: invoice.customerId,
+			customerExternalId: invoice.customerExternalId || void 0,
+			issueDate: invoice.issueDate,
+			dueDate: invoice.dueDate ?? void 0,
+			currency: invoice.currency,
+			lineAmountType: invoice.lineAmountType,
+			taxRoundingScope: invoice.taxRoundingScope,
+			subtotalMinor: invoice.subtotal,
+			taxAmountMinor: invoice.taxAmount,
+			providerTaxMinor: invoice.providerTaxAmount,
+			totalAmountMinor: invoice.totalAmount,
+			lineItems: lines.map((line) => ({
+				id: requiredText(line.id ?? "", "Accounting line ID"),
+				description: line.description,
+				sku: line.sku || void 0,
+				quantity: line.quantity,
+				unitPriceMinor: line.unitPrice,
+				discountMinor: line.discount,
+				amountMinor: invoice.lineAmountType === "inclusive" ? line.amount - line.taxAmount : line.amount,
+				taxMinor: line.taxAmount,
+				taxComponents: structuredClone(line.taxComponents)
+			})),
+			creditedInvoiceExternalId,
+			externalId: invoice.externalId || void 0,
+			reference: invoice.reference || void 0,
+			memo: invoice.customerNotes || void 0
+		}
+	};
+}
+function validateMapping(mapping) {
+	requiredText(mapping.realmId, "QuickBooks realm ID");
+	if (mapping.environment !== "sandbox" && mapping.environment !== "production") throw new MoneyValidationError("INVALID_MONEY_INPUT", "QuickBooks environment must be sandbox or production");
+	if (!mapping.lines || typeof mapping.lines !== "object") throw new MoneyValidationError("INVALID_MONEY_INPUT", "QuickBooks line mapping is required");
+	if (!mapping.components || typeof mapping.components !== "object") throw new MoneyValidationError("INVALID_MONEY_INPUT", "QuickBooks component mapping is required");
+}
+function toSdkInput(snapshot, mapping) {
+	validateMapping(mapping);
+	if (snapshot.document.kind === "creditMemo" && (snapshot.creditedInvoiceScope?.provider !== "quickbooks" || snapshot.creditedInvoiceScope.realmId !== mapping.realmId || snapshot.creditedInvoiceScope.environment !== mapping.environment)) throw new MoneyValidationError("ACCOUNTING_SYNC_RECONCILIATION_REQUIRED", "Credit note and credited invoice must use the same accounting provider, realm, and environment");
+	if (snapshot.document.lineItems.some((line) => line.quantity < 0 || line.amountMinor < 0 || line.unitPriceMinor < 0)) unsupported("Signed-line accounting sync requires a public accounting SDK signed-line representation");
+	return mapFrozenAccountingSnapshot(snapshot.document, mapping);
+}
+async function loadFrozenInvoiceAccountingSnapshot(input) {
+	assertPrincipalTenant(input.tenantId);
+	return withDocumentMoneyTransaction(input.db, async (tx) => {
+		await lockTenantMoneyRuntime(tx, input.tenantId);
+		const { invoice } = await lockAndReloadInvoice(tx, input.invoiceId, input.tenantId);
+		return loadSnapshot(tx, input.tenantId, invoice);
+	});
+}
+async function toFrozenInvoiceAccountingInput(input) {
+	return toSdkInput(await loadFrozenInvoiceAccountingSnapshot(input), input.mapping);
+}
+function prepareRequest(snapshot, mapping, sdkInput) {
+	const identity = {
+		requestId: requestIdFor(snapshot, mapping),
+		realmId: mapping.realmId,
+		environment: mapping.environment
+	};
+	if (snapshot.document.kind === "invoice") {
+		if (!("invoiceNumber" in sdkInput)) throw new MoneyValidationError("INVALID_MONEY_INPUT", "Frozen invoice mapping produced the wrong accounting document kind");
+		const request2 = prepareQuickBooksInvoiceRequest(sdkInput, identity);
+		return {
+			request: request2,
+			accountingInput: {
+				...sdkInput,
+				idempotencyKey: request2.requestId,
+				quickbooksRequest: request2
+			}
+		};
+	}
+	if (!("creditMemoNumber" in sdkInput)) throw new MoneyValidationError("INVALID_MONEY_INPUT", "Frozen credit-note mapping produced the wrong accounting document kind");
+	const request = prepareQuickBooksCreditMemoRequest(sdkInput, identity);
+	return {
+		request,
+		accountingInput: {
+			...sdkInput,
+			quickbooksCreditMemoRequest: request
+		}
+	};
+}
+function requestIdFor(snapshot, mapping) {
+	return `smrt_${createHash("sha256").update(JSON.stringify([
+		"quickbooks",
+		mapping.realmId,
+		mapping.environment,
+		snapshot.document.id,
+		snapshot.moneySnapshotId
+	])).digest("hex").slice(0, 40)}`;
+}
+async function prepareSync(input) {
+	if (input.provider.type !== "quickbooks") unsupported(`Frozen accounting sync does not support provider '${input.provider.type}'`);
+	return withDocumentMoneyTransaction(input.db, async (tx) => {
+		await lockTenantMoneyRuntime(tx, input.tenantId);
+		const { invoice } = await lockAndReloadInvoice(tx, input.invoiceId, input.tenantId);
+		const snapshot = await loadSnapshot(tx, input.tenantId, invoice);
+		const sdkInput = toSdkInput(snapshot, input.mapping);
+		const prior = parseSyncState(invoice.accountingSyncStateJson);
+		if (prior?.status === "synced" && sameSyncScope(prior.identity, snapshot, input.mapping)) {
+			if (!prior.externalId || !prior.syncedAt) throw new MoneyValidationError("ACCOUNTING_SYNC_RECONCILIATION_REQUIRED", "Completed accounting sync state is incomplete");
+			return {
+				kind: "unchanged",
+				result: {
+					status: "unchanged",
+					externalId: prior.externalId,
+					syncedAt: new Date(prior.syncedAt),
+					moneySnapshotId: prior.identity.moneySnapshotId
+				}
+			};
+		}
+		if (prior?.status === "in_flight") throw new MoneyValidationError("ACCOUNTING_SYNC_IN_PROGRESS", "Another accounting sync owns this invoice");
+		if (prior?.status === "unknown") throw new MoneyValidationError("ACCOUNTING_SYNC_RECONCILIATION_REQUIRED", "The prior accounting write outcome is unknown and must be reconciled");
+		if (prior?.status === "synced" || invoice.externalId) throw new MoneyValidationError("ACCOUNTING_SYNC_RECONCILIATION_REQUIRED", "Invoice accounting identity changed across provider, realm, environment, or snapshot");
+		if (snapshot.document.kind === "creditMemo") try {
+			requireCreditMemoOperations(input.provider);
+		} catch (error) {
+			unsupported(error instanceof Error ? error.message : String(error));
+		}
+		const { accountingInput, request } = prepareRequest(snapshot, input.mapping, sdkInput);
+		const identity = {
+			provider: "quickbooks",
+			documentKind: snapshot.document.kind,
+			realmId: request.realmId,
+			environment: request.environment,
+			invoiceId: snapshot.document.id,
+			moneySnapshotId: snapshot.moneySnapshotId,
+			requestId: request.requestId,
+			payloadHash: request.payloadHash,
+			creditedInvoiceExternalId: "creditedInvoiceExternalId" in request ? request.creditedInvoiceExternalId : void 0
+		};
+		if (prior && !sameIdentity(prior.identity, identity)) throw new MoneyValidationError("ACCOUNTING_SYNC_RECONCILIATION_REQUIRED", "Invoice accounting identity changed across provider, realm, environment, or snapshot");
+		const attemptId = randomUUID();
+		invoice.accountingSyncStateJson = JSON.stringify({
+			version: 1,
+			status: "in_flight",
+			identity,
+			attemptId,
+			startedAt: (/* @__PURE__ */ new Date()).toISOString()
+		});
+		await invoice.saveDerived(DOCUMENT_MONEY_WRITE);
+		return {
+			kind: "push",
+			documentKind: snapshot.document.kind,
+			accountingInput,
+			identity,
+			attemptId
+		};
+	});
+}
+async function recordFailure(input, prepared, error) {
+	const rejected = !!error && typeof error === "object" && error.code === "QBO_WRITE_ERROR" && error.outcome === "rejected";
+	await withDocumentMoneyTransaction(input.db, async (tx) => {
+		await lockTenantMoneyRuntime(tx, input.tenantId);
+		const { invoice } = await lockAndReloadInvoice(tx, input.invoiceId, input.tenantId);
+		const state = parseSyncState(invoice.accountingSyncStateJson);
+		if (!state || state.attemptId !== prepared.attemptId || !sameIdentity(state.identity, prepared.identity)) throw new MoneyValidationError("ACCOUNTING_SYNC_RECONCILIATION_REQUIRED", "Accounting sync ownership changed after provider failure");
+		invoice.accountingSyncStateJson = JSON.stringify({
+			...state,
+			status: rejected ? "rejected" : "unknown"
+		});
+		await invoice.saveDerived(DOCUMENT_MONEY_WRITE);
+	});
+}
+async function recordSuccess(input, prepared, result) {
+	requiredText(result.externalId, "Accounting external ID");
+	if (!(result.syncedAt instanceof Date) || Number.isNaN(result.syncedAt.valueOf())) throw new MoneyValidationError("INVALID_MONEY_INPUT", "Accounting provider returned an invalid sync timestamp");
+	return withDocumentMoneyTransaction(input.db, async (tx) => {
+		await lockTenantMoneyRuntime(tx, input.tenantId);
+		const { invoice } = await lockAndReloadInvoice(tx, input.invoiceId, input.tenantId);
+		const state = parseSyncState(invoice.accountingSyncStateJson);
+		if (state?.status !== "in_flight" || state.attemptId !== prepared.attemptId || !sameIdentity(state.identity, prepared.identity) || invoice.moneySnapshotId !== prepared.identity.moneySnapshotId) throw new MoneyValidationError("ACCOUNTING_SYNC_RECONCILIATION_REQUIRED", "Accounting sync ownership or frozen snapshot changed after provider write");
+		const syncedAt = result.syncedAt.toISOString();
+		invoice.externalId = result.externalId;
+		invoice.externalProvider = prepared.identity.provider;
+		invoice.syncedAt = result.syncedAt;
+		invoice.accountingSyncStateJson = JSON.stringify({
+			...state,
+			status: "synced",
+			externalId: result.externalId,
+			syncedAt
+		});
+		await invoice.saveDerived(DOCUMENT_MONEY_WRITE);
+		return {
+			status: "synced",
+			externalId: result.externalId,
+			syncedAt: result.syncedAt,
+			moneySnapshotId: prepared.identity.moneySnapshotId
+		};
+	});
+}
+async function syncFrozenInvoiceToAccounting(input) {
+	assertPrincipalTenant(input.tenantId);
+	const prepared = await prepareSync(input);
+	if (prepared.kind === "unchanged") return prepared.result;
+	let result;
+	try {
+		if (prepared.documentKind === "invoice") {
+			if (!("invoiceNumber" in prepared.accountingInput)) throw new MoneyValidationError("INVALID_MONEY_INPUT", "Prepared invoice has the wrong accounting document kind");
+			result = await input.provider.invoices.push(prepared.accountingInput);
+		} else {
+			if (!("creditMemoNumber" in prepared.accountingInput)) throw new MoneyValidationError("INVALID_MONEY_INPUT", "Prepared credit note has the wrong accounting document kind");
+			result = await requireCreditMemoOperations(input.provider).push(prepared.accountingInput);
+		}
+	} catch (error) {
+		await recordFailure(input, prepared, error);
+		throw error;
+	}
+	return recordSuccess(input, prepared, result);
+}
+async function reconcileFrozenInvoiceAccountingSync(input) {
+	assertPrincipalTenant(input.tenantId);
+	requiredText(input.requestId, "Accounting request ID");
+	requiredText(input.attemptId, "Accounting attempt ID");
+	return withDocumentMoneyTransaction(input.db, async (tx) => {
+		await lockTenantMoneyRuntime(tx, input.tenantId);
+		const { invoice } = await lockAndReloadInvoice(tx, input.invoiceId, input.tenantId);
+		const snapshot = await loadSnapshot(tx, input.tenantId, invoice);
+		const sdkInput = toSdkInput(snapshot, input.mapping);
+		const { request } = prepareRequest(snapshot, input.mapping, sdkInput);
+		const identity = {
+			provider: "quickbooks",
+			documentKind: snapshot.document.kind,
+			realmId: request.realmId,
+			environment: request.environment,
+			invoiceId: snapshot.document.id,
+			moneySnapshotId: snapshot.moneySnapshotId,
+			requestId: request.requestId,
+			payloadHash: request.payloadHash,
+			creditedInvoiceExternalId: "creditedInvoiceExternalId" in request ? request.creditedInvoiceExternalId : void 0
+		};
+		const state = parseSyncState(invoice.accountingSyncStateJson);
+		if (!state || state.status !== "unknown" && state.status !== "in_flight" || state.identity.requestId !== input.requestId || state.attemptId !== input.attemptId || !sameIdentity(state.identity, identity)) throw new MoneyValidationError("ACCOUNTING_SYNC_RECONCILIATION_REQUIRED", "Accounting reconciliation does not match the unresolved frozen request");
+		if (state.status === "in_flight" && input.confirmInterruptedOwnerStopped !== true) throw new MoneyValidationError("ACCOUNTING_SYNC_IN_PROGRESS", "Accounting reconciliation cannot release a live sync owner");
+		if (input.outcome.status === "absent") {
+			invoice.accountingSyncStateJson = JSON.stringify({
+				...state,
+				status: "rejected"
+			});
+			await invoice.saveDerived(DOCUMENT_MONEY_WRITE);
+			return {
+				status: "ready",
+				moneySnapshotId: identity.moneySnapshotId,
+				requestId: identity.requestId
+			};
+		}
+		const externalId = requiredText(input.outcome.externalId, "Accounting external ID");
+		if (!(input.outcome.syncedAt instanceof Date) || Number.isNaN(input.outcome.syncedAt.valueOf())) throw new MoneyValidationError("INVALID_MONEY_INPUT", "Accounting reconciliation requires a valid sync timestamp");
+		const syncedAt = input.outcome.syncedAt.toISOString();
+		invoice.externalId = externalId;
+		invoice.externalProvider = identity.provider;
+		invoice.syncedAt = input.outcome.syncedAt;
+		invoice.accountingSyncStateJson = JSON.stringify({
+			...state,
+			status: "synced",
+			externalId,
+			syncedAt
+		});
+		await invoice.saveDerived(DOCUMENT_MONEY_WRITE);
+		return {
+			status: "synced",
+			externalId,
+			syncedAt: input.outcome.syncedAt,
+			moneySnapshotId: identity.moneySnapshotId
+		};
+	});
+}
+function readFrozenAccountingSyncState(invoice) {
+	const state = parseSyncState(invoice.accountingSyncStateJson);
+	if (!state) return null;
+	return {
+		status: state.status,
+		provider: state.identity.provider,
+		realmId: state.identity.realmId,
+		environment: state.identity.environment,
+		documentKind: state.identity.documentKind,
+		moneySnapshotId: state.identity.moneySnapshotId,
+		requestId: state.identity.requestId,
+		attemptId: state.attemptId,
+		startedAt: state.startedAt,
+		request: {
+			requestId: state.identity.requestId,
+			realmId: state.identity.realmId,
+			environment: state.identity.environment,
+			payloadHash: state.identity.payloadHash,
+			...state.identity.documentKind === "creditMemo" ? { creditedInvoiceExternalId: requiredText(state.identity.creditedInvoiceExternalId ?? "", "Credited invoice external ID") } : {}
+		}
+	};
+}
+//#endregion
+//#region src/svelte/invoices/calculations.ts
+function numberDecimal(value, precision) {
+	if (!Number.isFinite(value) || value < 0 || value > Number.MAX_SAFE_INTEGER) throw new RangeError("Invoice rate or quantity is outside the supported range.");
+	const [mantissa, exponent = "0"] = value.toString().split("e");
+	const [whole, fraction = ""] = mantissa.split(".");
+	const places = fraction.length - Number(exponent);
+	if (places > precision) throw new RangeError("Invoice rate or quantity exceeds the supported decimal precision.");
+	const coefficient = BigInt(whole + fraction);
+	return places < 0 ? {
+		coefficient: coefficient * 10n ** BigInt(-places),
+		scale: 1n
+	} : {
+		coefficient,
+		scale: 10n ** BigInt(places)
+	};
+}
+function decimalText(value) {
+	if (value.scale === 1n) return value.coefficient.toString();
+	const places = value.scale.toString().length - 1;
+	const digits = value.coefficient.toString().padStart(places + 1, "0");
+	const split = digits.length - places;
+	return `${digits.slice(0, split)}.${digits.slice(split)}`.replace(/0+$/, "").replace(/\.$/, "");
+}
+function rateTaxCode(percent) {
+	const normalized = percent.replace(/^0+(?=\d)/, "").replace(/(\.\d*?)0+$/, "$1").replace(/\.$/, "") || "0";
+	return normalized === "0" ? {
+		id: "rate-zero",
+		kind: "zero-rated",
+		components: []
+	} : {
+		id: `rate-${normalized}`,
+		kind: "taxable",
+		components: [{
+			taxComponentId: `rate-${normalized}`,
+			percent: normalized,
+			compound: false
+		}]
+	};
+}
+function calculateInvoiceMinorLine(input) {
+	for (const amount of [input.unitPrice, input.discount]) if (!Number.isSafeInteger(amount)) throw new RangeError("Invoice money must be safe integer minor units.");
+	if (input.taxRate > 1) throw new RangeError("Invoice tax rate is outside the supported range.");
+	numberDecimal(input.quantity, 6);
+	const tax = numberDecimal(input.taxRate, 8);
+	const percent = decimalText({
+		coefficient: tax.coefficient * 100n,
+		scale: tax.scale
+	});
+	let result;
+	try {
+		result = calculateMoneyDocument({
+			currency: "USD",
+			lineAmountType: "exclusive",
+			roundingScope: "line",
+			lines: [{
+				id: "line",
+				quantity: input.quantity,
+				unitPrice: input.unitPrice,
+				discount: input.discount === 0 ? { kind: "none" } : {
+					kind: "amount",
+					minor: input.discount
+				},
+				taxCode: rateTaxCode(percent)
+			}]
+		}).lines[0];
+	} catch (cause) {
+		if (cause instanceof MoneyValidationError) throw new RangeError(cause.message, { cause });
+		throw cause;
+	}
+	return {
+		grossMinor: result.grossMinor,
+		discountMinor: result.discountMinor,
+		subtotalMinor: result.netMinor,
+		taxMinor: result.taxMinor,
+		totalMinor: result.netMinor + result.taxMinor
+	};
+}
+//#endregion
+//#region src/retention-accounting.ts
+var hash = (value) => createHash("sha256").update(JSON.stringify(value)).digest("hex");
+function reject(message) {
+	throw new MoneyValidationError("ACCOUNTING_SYNC_RECONCILIATION_REQUIRED", message);
+}
+function text(value, label) {
+	if (typeof value !== "string" || !value || value.trim() !== value) reject(`${label} is required`);
+}
+function date(value, label) {
+	if (!/^\d{4}-\d{2}-\d{2}$/.test(value) || !Number.isFinite(Date.parse(value)) || new Date(value).toISOString().slice(0, 10) !== value) reject(`${label} is invalid`);
+}
+function principal(input) {
+	if (!input.tenantId || getTenantId() !== input.tenantId) reject("Retention accounting requires its active tenant");
+	if (isMoneyTransaction(input.db)) reject("Provider writes cannot run inside a caller-owned money transaction");
+	if (input.provider.type !== "quickbooks" || !input.provider.receivableTransfers) reject("Provider lacks the reviewed receivable transfer capability");
+}
+function readRetainedInvoiceAccountingState(invoice) {
+	if (!invoice.retentionAccountingStateJson) return null;
+	let state;
+	try {
+		state = JSON.parse(invoice.retentionAccountingStateJson);
+	} catch {
+		return reject("Malformed retained accounting state");
+	}
+	if (state.version !== 1 || state.invoiceId !== invoice.id || state.moneySnapshotId !== invoice.moneySnapshotId || state.currency !== invoice.currency || state.grossMinor !== invoice.totalAmount || state.mapping.customerRef !== invoice.customerExternalId || !Array.isArray(state.steps) || !Array.isArray(state.releases) || !Array.isArray(state.credits) || !Array.isArray(state.refunds)) reject("Retention provider source identity changed");
+	const retention = parseInvoiceRetention(invoice.retentionStateJson);
+	if (!retention) reject("Provider retention agreement is missing");
+	const { releases: _releases, ...agreement } = retention;
+	if (state.retentionAgreementHash !== hash(agreement)) reject("Provider retention agreement changed");
+	return state;
+}
+async function loadRetainedInvoiceAccountingSnapshot(input) {
+	if (!input.tenantId || getTenantId() !== input.tenantId) reject("Retained accounting review requires its active tenant");
+	return withDocumentMoneyTransaction(input.db, async (tx) => {
+		await lockTenantMoneyRuntime(tx, input.tenantId);
+		const { invoice } = await lockAndReloadInvoice(tx, input.invoiceId, input.tenantId);
+		const retention = parseInvoiceRetention(invoice.retentionStateJson);
+		if (!retention || retention.retainedMinor <= 0 || invoice.kind !== "invoice" || invoice.moneyAuthority === "historical") reject("Retained accounting review requires a calculated retained invoice");
+		readRetainedInvoiceAccountingState(invoice);
+		return withRetentionAccountingAuthority(input.tenantId, input.invoiceId, () => loadFrozenInvoiceAccountingSnapshot({
+			...input,
+			db: tx
+		}));
+	});
+}
+async function toRetainedInvoiceAccountingInput(input) {
+	return mapFrozenAccountingSnapshot((await loadRetainedInvoiceAccountingSnapshot(input)).document, input.mapping);
+}
+async function reviewRetainedCredit(input, read) {
+	if (!input.tenantId || getTenantId() !== input.tenantId) reject("Retained credit review requires its active tenant");
+	return withDocumentMoneyTransaction(input.db, async (tx) => {
+		const original = await loadRetainedInvoiceAccountingSnapshot({
+			...input,
+			db: tx
+		});
+		const { invoice: credit } = await lockAndReloadInvoice(tx, input.creditInvoiceId, input.tenantId);
+		if (credit.kind !== "credit_note" || credit.creditedInvoiceId !== input.invoiceId || credit.customerId !== original.document.customerId || credit.currency !== original.document.currency || credit.moneyAuthority === "historical") reject("Retained credit review requires its exact calculated source lineage");
+		return withRetentionAccountingAuthority(input.tenantId, input.invoiceId, () => read({
+			db: tx,
+			tenantId: input.tenantId,
+			invoiceId: input.creditInvoiceId
+		}));
+	});
+}
+function loadRetainedCreditAccountingSnapshot(input) {
+	return reviewRetainedCredit(input, loadFrozenInvoiceAccountingSnapshot);
+}
+function toRetainedCreditAccountingInput(input) {
+	return reviewRetainedCredit(input, async (scope) => {
+		return await toFrozenInvoiceAccountingInput({
+			...scope,
+			mapping: input.mapping
+		});
+	});
+}
+async function locked(input, operation) {
+	return withDocumentMoneyTransaction(input.db, async (tx) => {
+		await lockTenantMoneyRuntime(tx, input.tenantId);
+		const { invoice } = await lockAndReloadInvoice(tx, input.invoiceId, input.tenantId);
+		return operation(invoice, readRetainedInvoiceAccountingState(invoice));
+	});
+}
+async function save(invoice, state) {
+	invoice.retentionAccountingStateJson = JSON.stringify(state);
+	await invoice.saveDerived(DOCUMENT_MONEY_WRITE);
+}
+function refreshStatus(state) {
+	state.status = state.steps.every((step) => step.status === "confirmed") && state.releases.every((event) => event.committed) && state.credits.every((event) => event.committed) && state.refunds.every((event) => event.committed) ? "ready" : "pending";
+}
+function requireReady(state) {
+	if (!state || state.status !== "ready" || state.steps.some((s) => s.status !== "confirmed")) reject("Retention provider bundle requires reconciliation before a new operation");
+	return state;
+}
+function requestId(state, key) {
+	return `smrt_ret_${hash([
+		state.invoiceId,
+		state.moneySnapshotId,
+		state.mapping.realmId,
+		state.mapping.environment,
+		key
+	]).slice(0, 40)}`;
+}
+function source(invoice, state) {
+	if (!invoice.externalId || invoice.externalProvider !== "quickbooks") reject("Retention needs a reconciled provider invoice");
+	return {
+		type: "Invoice",
+		id: invoice.externalId,
+		customerRef: state.mapping.customerRef,
+		evidenceRef: state.moneySnapshotId
+	};
+}
+async function executeStep(input, key, make) {
+	const prepared = await locked(input, async (invoice, state) => {
+		if (!state) reject("Retention provider contract is missing");
+		const expected = make(invoice, state), prior = state.steps.find((s) => s.key === key);
+		if (prior && prior.request.payloadHash !== expected.payloadHash) reject("Retention operation identity reused with changed facts");
+		if (prior?.status === "confirmed") {
+			if (!prior.result) reject("Confirmed retention step has no readback");
+			return { complete: prior.result };
+		}
+		if (prior && prior.status !== "rejected") reject("Retention operation has an unresolved remote owner");
+		if (state.steps.some((s) => s.key !== key && s.status !== "confirmed")) reject("Another retention operation requires reconciliation");
+		const step2 = {
+			key,
+			status: "in_flight",
+			attemptId: randomUUID(),
+			request: expected,
+			startedAt: (/* @__PURE__ */ new Date()).toISOString(),
+			priorAttempts: prior ? [...prior.priorAttempts ?? [], {
+				attemptId: prior.attemptId,
+				status: prior.status,
+				startedAt: prior.startedAt,
+				reconciliation: prior.reconciliation
+			}] : []
+		};
+		if (prior) state.steps[state.steps.indexOf(prior)] = step2;
+		else state.steps.push(step2);
+		await save(invoice, state);
+		return { step: step2 };
+	});
+	if ("complete" in prepared && prepared.complete) return prepared.complete;
+	if (!prepared.step) reject("Prepared retention step is missing");
+	const step = prepared.step;
+	let result;
+	try {
+		result = await input.provider.receivableTransfers.execute(step.request);
+	} catch (error) {
+		await locked(input, async (invoice, state) => {
+			const current = state?.steps.find((s) => s.key === key);
+			if (!state || current?.attemptId !== step.attemptId || current.status !== "in_flight") reject("Retention step ownership changed after remote failure");
+			current.status = error?.outcome === "rejected" ? "rejected" : "unknown";
+			await save(invoice, state);
+		});
+		throw error;
+	}
+	return locked(input, async (invoice, state) => {
+		const current = state?.steps.find((s) => s.key === key);
+		if (!state || current?.attemptId !== step.attemptId || current.status !== "in_flight" || result.payloadHash !== step.request.payloadHash) reject("Retention step ownership or readback changed after write");
+		current.status = "confirmed";
+		current.result = structuredClone(result);
+		await save(invoice, state);
+		return result;
+	});
+}
+async function syncRetainedInvoiceToAccounting(input) {
+	principal(input);
+	text(input.requestId, "Retention request");
+	text(input.evidenceRef, "Retention evidence");
+	date(input.effectiveOn, "Retention effective date");
+	await input.provider.receivableTransfers.verifyMapping(input.mapping);
+	await locked(input, async (invoice, state) => {
+		if (input.mapping.realmId !== input.invoiceMapping.realmId || input.mapping.environment !== input.invoiceMapping.environment || input.mapping.currency !== invoice.currency || input.mapping.customerRef !== invoice.customerExternalId) reject("Retention mapping differs from frozen invoice provider authority");
+		if (state) {
+			if (hash([
+				state.requestId,
+				state.evidenceRef,
+				state.effectiveOn,
+				state.mapping,
+				state.invoiceMapping
+			]) !== hash([
+				input.requestId,
+				input.evidenceRef,
+				input.effectiveOn,
+				input.mapping,
+				input.invoiceMapping
+			])) reject("Retention provider contract is immutable");
+			return;
+		}
+		if ("moneyAuthority" in invoice && invoice.moneyAuthority === "historical") reject("Historical source-owned invoices require an explicit reconciled provider authority contract; original journals cannot be duplicated");
+		const retention = parseInvoiceRetention(invoice.retentionStateJson);
+		if (!retention || retention.retainedMinor <= 0 || retention.releases.length || invoice.creditedAmount || invoice.amountPaid || !invoice.moneySnapshotId || invoice.kind !== "invoice" || [
+			InvoiceStatus.DRAFT,
+			InvoiceStatus.CANCELLED,
+			InvoiceStatus.WRITTEN_OFF
+		].includes(invoice.status) || invoice.externalId || invoice.externalProvider || invoice.accountingSyncStateJson || invoice.collectionMethod || invoice.providerTaxAmount) reject("Initial provider retention requires an issued, uncredited, unpaid, unreleased host-owned retained invoice");
+		const { releases: _releases, ...agreement } = retention;
+		state = {
+			version: 1,
+			invoiceId: input.invoiceId,
+			moneySnapshotId: invoice.moneySnapshotId,
+			requestId: input.requestId,
+			evidenceRef: input.evidenceRef,
+			effectiveOn: input.effectiveOn,
+			currency: invoice.currency,
+			grossMinor: invoice.totalAmount,
+			retainedMinor: retention.retainedMinor,
+			retentionAgreementHash: hash(agreement),
+			mapping: structuredClone(input.mapping),
+			invoiceMapping: structuredClone(input.invoiceMapping),
+			status: "pending",
+			steps: [],
+			releases: [],
+			credits: [],
+			refunds: []
+		};
+		await save(invoice, state);
+	});
+	await withRetentionAccountingAuthority(input.tenantId, input.invoiceId, () => syncFrozenInvoiceToAccounting({
+		...input,
+		mapping: input.invoiceMapping
+	}));
+	const withheld = await executeStep(input, "withhold", (invoice, state) => prepareQuickBooksReceivableRequest({
+		kind: "withhold",
+		mapping: state.mapping,
+		source: source(invoice, state),
+		requestId: requestId(state, "withhold"),
+		effectiveOn: state.effectiveOn,
+		evidenceRef: state.evidenceRef,
+		amountMinor: state.retainedMinor
+	}));
+	await executeStep(input, "withhold-application", (invoice, state) => prepareQuickBooksReceivableRequest({
+		kind: "application",
+		mapping: state.mapping,
+		source: source(invoice, state),
+		requestId: requestId(state, "withhold-application"),
+		effectiveOn: state.effectiveOn,
+		evidenceRef: state.evidenceRef,
+		amountMinor: state.retainedMinor,
+		debit: {
+			type: "Invoice",
+			id: invoice.externalId
+		},
+		credit: {
+			type: "JournalEntry",
+			id: withheld.externalId
+		}
+	}));
+	return locked(input, async (invoice, state) => {
+		if (!state) reject("Missing retained provider state");
+		if (state.steps.some((step) => step.status !== "confirmed") || state.releases.some((release) => !release.committed)) reject("Another retention operation is unfinished");
+		refreshStatus(state);
+		await save(invoice, state);
+		return state;
+	});
+}
+async function releaseRetainedInvoiceToAccounting(input) {
+	principal(input);
+	validateRetentionEvidence(input);
+	date(input.effectiveOn, "Release effective date");
+	date(input.dueOn, "Release due date");
+	if (!Number.isSafeInteger(input.amountMinor) || input.amountMinor <= 0) reject("Release amount or due date is invalid");
+	const key = `release:${input.requestId}`;
+	await locked(input, async (invoice, state) => {
+		if (!state) reject("Retention provider contract is missing");
+		const prior = state.releases.find((r) => r.requestId === input.requestId);
+		const release = {
+			requestId: input.requestId,
+			policyVersion: input.policyVersion,
+			evidenceRef: input.evidenceRef,
+			actorId: input.actorId,
+			reason: input.reason,
+			amountMinor: input.amountMinor,
+			effectiveOn: input.effectiveOn,
+			dueOn: input.dueOn,
+			stepKey: key,
+			committed: false
+		};
+		if (prior) {
+			if (hash({
+				...prior,
+				committed: false
+			}) !== hash(release)) reject("Release request identity reused with changed facts");
+			return;
+		}
+		requireReady(state);
+		if (!invoice.updated_at || new Date(invoice.updated_at).toISOString() !== new Date(input.expectedUpdatedAt).toISOString()) reject("Stale retention release revision");
+		if (invoice.creditedAmount !== state.credits.filter((c) => c.committed).reduce((sum, c) => sum + c.grossMinor, 0)) reject("Provider retention credit adjustment must reconcile before release");
+		if (input.amountMinor > calculateInvoicePayable(invoice).retainedRemainingMinor) reject("Release exceeds retained capacity");
+		state.releases.push(release);
+		state.status = "pending";
+		await save(invoice, state);
+	});
+	await executeStep(input, key, (invoice, state) => prepareQuickBooksReceivableRequest({
+		kind: "release",
+		mapping: state.mapping,
+		source: source(invoice, state),
+		requestId: requestId(state, key),
+		effectiveOn: input.effectiveOn,
+		evidenceRef: input.evidenceRef,
+		amountMinor: input.amountMinor
+	}));
+	return locked(input, async (invoice, state) => {
+		if (!state) reject("Retention provider contract is missing");
+		const release = state.releases.find((r) => r.requestId === input.requestId);
+		if (!release) reject("Release reservation disappeared");
+		if (!release.committed) {
+			if (invoice.creditedAmount !== state.credits.filter((c) => c.committed).reduce((sum, c) => sum + c.grossMinor, 0) || input.amountMinor > calculateInvoicePayable(invoice).retainedRemainingMinor) reject("Source capacity changed after provider release; reconciliation required");
+			const retention = parseInvoiceRetention(invoice.retentionStateJson);
+			retention.releases.push({
+				requestId: release.requestId,
+				policyVersion: release.policyVersion,
+				evidenceRef: release.evidenceRef,
+				actorId: release.actorId,
+				reason: release.reason,
+				amountMinor: release.amountMinor,
+				effectiveOn: release.effectiveOn,
+				recordedAt: (/* @__PURE__ */ new Date()).toISOString()
+			});
+			invoice.retentionStateJson = JSON.stringify(retention);
+			release.committed = true;
+		}
+		refreshStatus(state);
+		await save(invoice, state);
+		return state;
+	});
+}
+async function reconcileRetainedAccountingStep(input) {
+	principal(input);
+	const step = await locked(input, async (_invoice, state) => {
+		const found = state?.steps.find((s) => s.key === input.stepKey);
+		if (!found || found.request.requestId !== input.requestId || found.attemptId !== input.attemptId || !["in_flight", "unknown"].includes(found.status)) reject("Observed retention reconciliation owner differs");
+		if (found.status === "in_flight" && !input.confirmInterruptedOwnerStopped) reject("Interrupted retention owner must be proven stopped");
+		return structuredClone(found);
+	});
+	const result = input.outcome.status === "found" ? await input.provider.receivableTransfers.read(step.request, input.outcome.externalId) : null;
+	if (input.outcome.status === "absent") text(input.outcome.evidenceRef, "Authoritative provider absence evidence");
+	return locked(input, async (invoice, state) => {
+		const current = state?.steps.find((s) => s.key === input.stepKey);
+		if (!state || current?.attemptId !== step.attemptId || current.status !== step.status) reject("Retention reconciliation owner changed");
+		current.reconciliation = {
+			outcome: input.outcome.status,
+			recordedAt: (/* @__PURE__ */ new Date()).toISOString(),
+			interruptedOwnerStopped: input.confirmInterruptedOwnerStopped === true,
+			...input.outcome.status === "found" ? { externalId: input.outcome.externalId } : { evidenceRef: input.outcome.evidenceRef }
+		};
+		if (result) {
+			if (result.payloadHash !== step.request.payloadHash) reject("Retention reconciliation readback differs");
+			current.result = result;
+			current.status = "confirmed";
+		} else current.status = "rejected";
+		await save(invoice, state);
+		return state;
+	});
+}
+async function reconcileRetainedBaseInvoice(input) {
+	principal(input);
+	await locked(input, async (_invoice, state) => {
+		if (!state || hash(state.invoiceMapping) !== hash(input.mapping)) reject("Retention base mapping differs");
+	});
+	return withRetentionAccountingAuthority(input.tenantId, input.invoiceId, () => reconcileFrozenInvoiceAccountingSync(input));
+}
+async function syncRetainedCreditToAccounting(input) {
+	principal(input);
+	text(input.requestId, "Credit adjustment request");
+	text(input.evidenceRef, "Credit adjustment evidence");
+	date(input.effectiveOn, "Credit adjustment date");
+	const reserved = await locked(input, async (invoice, state) => {
+		if (!state) reject("Retention provider contract is missing");
+		const credit = await (await InvoiceCollection.create({ db: invoice.db })).get({ id: input.creditInvoiceId }, { cache: false });
+		if (!credit || credit.tenantId !== input.tenantId || credit.creditedInvoiceId !== invoice.id || credit.kind !== "credit_note" || !credit.moneySnapshotId || [InvoiceStatus.DRAFT, InvoiceStatus.CANCELLED].includes(credit.status) || credit.currency !== state.currency || credit.customerExternalId !== state.mapping.customerRef) reject("Credit adjustment requires its issued same-customer source credit");
+		if (input.creditMapping.realmId !== state.mapping.realmId || input.creditMapping.environment !== state.mapping.environment) reject("Credit adjustment provider scope differs");
+		const prior = state.credits.find((c) => c.creditId === input.creditInvoiceId || c.requestId === input.requestId);
+		if (prior) {
+			if (prior.creditId !== input.creditInvoiceId || prior.requestId !== input.requestId || prior.moneySnapshotId !== credit.moneySnapshotId || prior.grossMinor !== credit.totalAmount || prior.evidenceRef !== input.evidenceRef || prior.effectiveOn !== input.effectiveOn || hash(prior.mapping) !== hash(input.creditMapping)) reject("Credit adjustment identity reused with changed facts");
+			return structuredClone(prior);
+		}
+		requireReady(state);
+		if (state.credits.reduce((sum, c) => sum + c.grossMinor, 0) + credit.totalAmount > invoice.creditedAmount) reject("Provider credit exceeds issued source credit capacity");
+		const remainingRetained = state.retainedMinor - state.releases.filter((r) => r.committed).reduce((sum, r) => sum + r.amountMinor, 0) - state.credits.reduce((sum, c) => sum + c.retainedMinor, 0);
+		const retainedMinor = Math.min(remainingRetained, credit.totalAmount);
+		if (retainedMinor < 0 || retainedMinor > credit.creditedAmount) reject("Retained-first credit exceeds its approved source allocation");
+		const next = {
+			creditId: input.creditInvoiceId,
+			moneySnapshotId: credit.moneySnapshotId,
+			requestId: input.requestId,
+			evidenceRef: input.evidenceRef,
+			effectiveOn: input.effectiveOn,
+			grossMinor: credit.totalAmount,
+			retainedMinor,
+			appliedMinor: credit.creditedAmount - retainedMinor,
+			mapping: structuredClone(input.creditMapping),
+			committed: false
+		};
+		state.credits.push(next);
+		state.status = "pending";
+		await save(invoice, state);
+		return next;
+	});
+	const creditResult = await withRetentionAccountingAuthority(input.tenantId, input.invoiceId, () => syncFrozenInvoiceToAccounting({
+		db: input.db,
+		tenantId: input.tenantId,
+		invoiceId: input.creditInvoiceId,
+		provider: input.provider,
+		mapping: input.creditMapping
+	}));
+	const prefix = `credit:${input.requestId}`;
+	const creditSource = (state) => ({
+		type: "CreditMemo",
+		id: creditResult.externalId,
+		customerRef: state.mapping.customerRef,
+		evidenceRef: reserved.moneySnapshotId
+	});
+	if (reserved.retainedMinor > 0) {
+		const cancelled = await executeStep(input, `${prefix}:retention`, (_invoice, state) => prepareQuickBooksReceivableRequest({
+			kind: "release",
+			mapping: state.mapping,
+			source: creditSource(state),
+			requestId: requestId(state, `${prefix}:retention`),
+			effectiveOn: reserved.effectiveOn,
+			evidenceRef: reserved.evidenceRef,
+			amountMinor: reserved.retainedMinor
+		}));
+		await executeStep(input, `${prefix}:retention-application`, (_invoice, state) => prepareQuickBooksReceivableRequest({
+			kind: "application",
+			mapping: state.mapping,
+			source: creditSource(state),
+			requestId: requestId(state, `${prefix}:retention-application`),
+			effectiveOn: reserved.effectiveOn,
+			evidenceRef: reserved.evidenceRef,
+			amountMinor: reserved.retainedMinor,
+			debit: {
+				type: "JournalEntry",
+				id: cancelled.externalId
+			},
+			credit: {
+				type: "CreditMemo",
+				id: creditResult.externalId
+			}
+		}));
+	}
+	if (reserved.appliedMinor > 0) await executeStep(input, `${prefix}:due-application`, (invoice, state) => prepareQuickBooksReceivableRequest({
+		kind: "application",
+		mapping: state.mapping,
+		source: creditSource(state),
+		requestId: requestId(state, `${prefix}:due-application`),
+		effectiveOn: reserved.effectiveOn,
+		evidenceRef: reserved.evidenceRef,
+		amountMinor: reserved.appliedMinor,
+		debit: {
+			type: "Invoice",
+			id: invoice.externalId
+		},
+		credit: {
+			type: "CreditMemo",
+			id: creditResult.externalId
+		}
+	}));
+	return locked(input, async (invoice, state) => {
+		if (!state) reject("Retention provider state is missing");
+		const credit = state.credits.find((c) => c.creditId === input.creditInvoiceId);
+		if (!credit) reject("Credit reservation disappeared");
+		credit.committed = true;
+		refreshStatus(state);
+		await save(invoice, state);
+		return state;
+	});
+}
+async function syncRetainedRefundToAccounting(input) {
+	principal(input);
+	text(input.requestId, "Refund recording request");
+	text(input.evidenceRef, "Refund settlement evidence");
+	date(input.effectiveOn, "Refund effective date");
+	const reservation = await locked(input, async (invoice, state) => {
+		if (!state) reject("Retention provider contract is missing");
+		const credit = state.credits.find((c) => c.creditId === input.creditInvoiceId && c.committed);
+		if (!credit) reject("Refund requires its reconciled provider credit");
+		const payment = await (await PaymentCollection.create({ db: invoice.db })).get({ id: input.paymentId }, { cache: false });
+		const creditInvoice = await (await InvoiceCollection.create({ db: invoice.db })).get({ id: input.creditInvoiceId }, { cache: false });
+		if (!payment || !creditInvoice || payment.tenantId !== input.tenantId || payment.customerId !== invoice.customerId || payment.currency !== state.currency || payment.kind !== "refund" || payment.status !== "completed" || !payment.journalId || !payment.paidAt || !creditInvoice.externalId || creditInvoice.moneySnapshotId !== credit.moneySnapshotId) reject("Provider refund requires its completed same-customer local cash journal and source credit");
+		const allocations = await (await PaymentAllocationCollection.create({ db: invoice.db })).findByPayment(input.paymentId);
+		if (allocations.length !== 1 || allocations[0].invoiceId !== input.creditInvoiceId || allocations[0].amount !== payment.amount) reject("Refund recording requires one exact full source-credit allocation");
+		const fingerprint = hash([
+			payment.id,
+			payment.customerId,
+			payment.currency,
+			payment.amount,
+			payment.journalId,
+			new Date(payment.paidAt).toISOString(),
+			allocations[0].id,
+			allocations[0].amount,
+			credit.moneySnapshotId
+		]);
+		const next = {
+			paymentId: input.paymentId,
+			creditId: input.creditInvoiceId,
+			requestId: input.requestId,
+			evidenceRef: input.evidenceRef,
+			effectiveOn: input.effectiveOn,
+			amountMinor: payment.amount,
+			paymentFingerprint: fingerprint,
+			committed: false
+		};
+		const prior = state.refunds.find((r) => r.paymentId === input.paymentId || r.requestId === input.requestId);
+		if (prior) {
+			if (hash({
+				...prior,
+				committed: false
+			}) !== hash(next)) reject("Refund recording identity reused with changed facts");
+			return {
+				...prior,
+				externalCreditId: creditInvoice.externalId
+			};
+		}
+		requireReady(state);
+		if (!state.mapping.cashAccountRef) reject("Refund provider bank account must be explicitly reviewed");
+		if (state.refunds.filter((r) => r.creditId === input.creditInvoiceId).reduce((sum, r) => sum + r.amountMinor, 0) + payment.amount > credit.grossMinor - credit.retainedMinor - credit.appliedMinor) reject("Refund exceeds unapplied provider credit capacity");
+		if (payment.retentionAccountingBindingJson) reject("Refund is already bound to a provider operation");
+		payment.retentionAccountingBindingJson = JSON.stringify({
+			invoiceId: input.invoiceId,
+			tenantId: input.tenantId,
+			requestId: input.requestId,
+			paymentFingerprint: fingerprint
+		});
+		await withRetentionAccountingAuthority(input.tenantId, input.invoiceId, () => payment.save());
+		state.refunds.push(next);
+		state.status = "pending";
+		await save(invoice, state);
+		return {
+			...next,
+			externalCreditId: creditInvoice.externalId
+		};
+	});
+	const prefix = `refund:${input.requestId}`;
+	const creditSource = (state) => ({
+		type: "CreditMemo",
+		id: reservation.externalCreditId,
+		customerRef: state.mapping.customerRef,
+		evidenceRef: reservation.paymentFingerprint
+	});
+	const journal = await executeStep(input, prefix, (_invoice, state) => prepareQuickBooksReceivableRequest({
+		kind: "cash-refund",
+		mapping: state.mapping,
+		source: creditSource(state),
+		requestId: requestId(state, prefix),
+		effectiveOn: reservation.effectiveOn,
+		evidenceRef: reservation.evidenceRef,
+		amountMinor: reservation.amountMinor
+	}));
+	await executeStep(input, `${prefix}:application`, (_invoice, state) => prepareQuickBooksReceivableRequest({
+		kind: "application",
+		mapping: state.mapping,
+		source: creditSource(state),
+		requestId: requestId(state, `${prefix}:application`),
+		effectiveOn: reservation.effectiveOn,
+		evidenceRef: reservation.evidenceRef,
+		amountMinor: reservation.amountMinor,
+		debit: {
+			type: "JournalEntry",
+			id: journal.externalId
+		},
+		credit: {
+			type: "CreditMemo",
+			id: reservation.externalCreditId
+		}
+	}));
+	return locked(input, async (invoice, state) => {
+		if (!state) reject("Retention provider state disappeared");
+		const refund = state.refunds.find((r) => r.requestId === input.requestId);
+		if (!refund) reject("Refund reservation disappeared");
+		refund.committed = true;
+		refreshStatus(state);
+		await save(invoice, state);
+		return state;
+	});
+}
+async function reconcileRetainedCreditAccounting(input) {
+	principal(input);
+	const mapping = await locked(input, async (_invoice, state) => {
+		const reserved = state?.credits.find((credit) => credit.creditId === input.creditInvoiceId);
+		if (!reserved) reject("Retained credit has no approved provider reservation");
+		return structuredClone(reserved.mapping);
+	});
+	return withRetentionAccountingAuthority(input.tenantId, input.invoiceId, () => reconcileFrozenInvoiceAccountingSync({
+		...input,
+		invoiceId: input.creditInvoiceId,
+		mapping
+	}));
+}
+//#endregion
+export { historicalCreditRefundCommittedTotal as C, Payment as E, PaymentAllocation as S, PaymentCollection_exports as T, reconcileFrozenInvoiceAccountingSync as _, reconcileRetainedBaseInvoice as a, PaymentAllocationCollection as b, syncRetainedCreditToAccounting as c, toRetainedCreditAccountingInput as d, toRetainedInvoiceAccountingInput as f, readFrozenAccountingSyncState as g, loadFrozenInvoiceAccountingSnapshot as h, reconcileRetainedAccountingStep as i, syncRetainedInvoiceToAccounting as l, invoice_accounting_sync_exports as m, loadRetainedInvoiceAccountingSnapshot as n, reconcileRetainedCreditAccounting as o, calculateInvoiceMinorLine as p, readRetainedInvoiceAccountingState as r, releaseRetainedInvoiceToAccounting as s, loadRetainedCreditAccountingSnapshot as t, syncRetainedRefundToAccounting as u, syncFrozenInvoiceToAccounting as v, PaymentCollection as w, PaymentAllocationCollection_exports as x, toFrozenInvoiceAccountingInput as y };
+
+//# sourceMappingURL=retention-accounting-Brdj9x-V.js.map