@happyvertical/smrt-sales 0.39.2

package/dist/chunks/commissions-BCxqOKVM.js

@@ -0,0 +1,2181 @@
+import { SmrtCollection, SmrtObject, crossPackageRef, field, foreignKey, smrt } from "@happyvertical/smrt-core";
+import { TenantScoped, tenantId } from "@happyvertical/smrt-tenancy";
+//#region src/commissions/models/CommissionAdjustment.ts
+var __defProp$5 = Object.defineProperty;
+var __getOwnPropDesc$5 = Object.getOwnPropertyDescriptor;
+var __decorateClass$5 = (decorators, target, key, kind) => {
+	var result = kind > 1 ? void 0 : kind ? __getOwnPropDesc$5(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$5(target, key, result);
+	return result;
+};
+var frozenAdjustmentSnapshot = /* @__PURE__ */ new WeakMap();
+var CommissionAdjustment = class extends SmrtObject {
+	tenantId = null;
+	commissionId = "";
+	earnerId = "";
+	/** What kind of correction this is. */
+	adjustmentKind = "correction";
+	/**
+	* SIGNED amount in integer cents. Negative claws earnings back (refund,
+	* chargeback); positive credits extra.
+	*/
+	amountCents = 0;
+	/** ISO 4217 currency — must match the parent commission's. */
+	currency = "USD";
+	reason = "";
+	createdByProfileId = "";
+	payoutId = "";
+	/** Additional metadata as a JSON string. Frozen once persisted. */
+	metadata = "{}";
+	constructor(options = {}) {
+		super(options);
+		if (options.tenantId !== void 0) this.tenantId = options.tenantId;
+		if (options.commissionId !== void 0) this.commissionId = options.commissionId;
+		if (options.earnerId !== void 0) this.earnerId = options.earnerId;
+		if (options.adjustmentKind !== void 0) this.adjustmentKind = options.adjustmentKind;
+		if (options.amountCents !== void 0) this.amountCents = options.amountCents;
+		if (options.currency !== void 0) this.currency = options.currency;
+		if (options.reason !== void 0) this.reason = options.reason;
+		if (options.createdByProfileId !== void 0) this.createdByProfileId = options.createdByProfileId;
+		if (options.payoutId !== void 0) this.payoutId = options.payoutId;
+		if (options.metadata !== void 0) this.metadata = options.metadata;
+	}
+	/**
+	* Capture the frozen-fields snapshot when the row was loaded from the
+	* database — from that moment on, only {@link payoutId} may change.
+	*/
+	async initialize() {
+		await super.initialize();
+		if (await this.isSaved()) frozenAdjustmentSnapshot.set(this, this.serializeFrozenSnapshot());
+		return this;
+	}
+	/** `true` once a payout batch has stamped {@link payoutId}. */
+	isSettled() {
+		return !!this.payoutId;
+	}
+	/** Parse {@link metadata}; returns `{}` on empty/invalid JSON. */
+	getMetadata() {
+		if (!this.metadata) return {};
+		try {
+			const parsed = JSON.parse(this.metadata);
+			return parsed && typeof parsed === "object" && !Array.isArray(parsed) ? parsed : {};
+		} catch {
+			return {};
+		}
+	}
+	/** Serialize and store {@link metadata}. */
+	setMetadata(data) {
+		this.metadata = JSON.stringify(data ?? {});
+	}
+	/**
+	* Save with the append-only guard: once the row has been persisted, every
+	* field except `payoutId` must match the captured snapshot. Corrections
+	* to a wrong adjustment are new counter-adjustments, never edits.
+	*/
+	async save() {
+		this.assertImmutableOncePersisted();
+		const result = await super.save();
+		if (!frozenAdjustmentSnapshot.has(this)) frozenAdjustmentSnapshot.set(this, this.serializeFrozenSnapshot());
+		return result;
+	}
+	assertImmutableOncePersisted() {
+		const captured = frozenAdjustmentSnapshot.get(this);
+		if (!captured) return;
+		if (captured !== this.serializeFrozenSnapshot()) throw new Error(`CommissionAdjustment ${this.id ?? "<new>"}: adjustments are append-only \u2014 only payoutId may change after creation. Append a counter-adjustment instead of editing this one.`);
+	}
+	/**
+	* Serialize every field EXCEPT `payoutId` (the sole post-create mutable
+	* field) with stable key ordering.
+	*/
+	serializeFrozenSnapshot() {
+		return JSON.stringify({
+			tenantId: this.tenantId,
+			commissionId: this.commissionId,
+			earnerId: this.earnerId,
+			adjustmentKind: this.adjustmentKind,
+			amountCents: this.amountCents,
+			currency: this.currency,
+			reason: this.reason,
+			createdByProfileId: this.createdByProfileId,
+			metadata: this.metadata
+		});
+	}
+};
+__decorateClass$5([tenantId({ nullable: true })], CommissionAdjustment.prototype, "tenantId", 2);
+__decorateClass$5([foreignKey("Commission", { required: true })], CommissionAdjustment.prototype, "commissionId", 2);
+__decorateClass$5([foreignKey("Earner", { required: true })], CommissionAdjustment.prototype, "earnerId", 2);
+__decorateClass$5([field({ required: true })], CommissionAdjustment.prototype, "reason", 2);
+__decorateClass$5([crossPackageRef("@happyvertical/smrt-profiles:Profile")], CommissionAdjustment.prototype, "createdByProfileId", 2);
+__decorateClass$5([foreignKey("CommissionPayout")], CommissionAdjustment.prototype, "payoutId", 2);
+CommissionAdjustment = __decorateClass$5([TenantScoped({ mode: "optional" }), smrt({
+	api: { include: [
+		"create",
+		"list",
+		"get"
+	] },
+	mcp: { include: ["list", "create"] },
+	cli: false
+})], CommissionAdjustment);
+//#endregion
+//#region src/commissions/collections/CommissionAdjustmentCollection.ts
+var CommissionAdjustmentCollection = class extends SmrtCollection {
+	static _itemClass = CommissionAdjustment;
+	/** All adjustments appended to one commission, oldest first. */
+	async findByCommission(commissionId) {
+		return await this.list({
+			where: { commissionId },
+			orderBy: "created_at ASC"
+		});
+	}
+	/** Unsettled adjustments for an earner+currency, oldest first. */
+	async findUnsettledByEarner(earnerId, currency) {
+		return (await this.list({
+			where: {
+				earnerId,
+				currency
+			},
+			orderBy: "created_at ASC"
+		})).filter((a) => !a.payoutId);
+	}
+	/**
+	* Σ signed amountCents of {@link findUnsettledByEarner} rows (integer
+	* cents; clawbacks make it negative).
+	*/
+	async sumUnsettledByEarner(earnerId, currency) {
+		return (await this.findUnsettledByEarner(earnerId, currency)).reduce((sum, a) => sum + a.amountCents, 0);
+	}
+	/** Adjustments settled by one payout batch. */
+	async findByPayout(payoutId) {
+		return await this.list({
+			where: { payoutId },
+			orderBy: "created_at ASC"
+		});
+	}
+	/**
+	* Conditionally claim adjustment rows for a payout batch — the
+	* adjustment twin of `CommissionCollection.claimForPayout`. Rows already
+	* claimed by a DIFFERENT payout are skipped; rows already claimed by THIS
+	* payout pass through (idempotent retry / repair); every claim is
+	* verified by a post-save re-read. Returns the claimed rows.
+	*/
+	async claimForPayout(adjustmentIds, payoutId) {
+		const claimed = [];
+		for (const id of adjustmentIds) {
+			const row = await this.get({ id });
+			if (!row) continue;
+			if (row.payoutId && row.payoutId !== payoutId) continue;
+			if (!row.payoutId) {
+				row.payoutId = payoutId;
+				await row.save();
+			}
+			const verified = await this.get({ id });
+			if (verified && verified.payoutId === payoutId) claimed.push(verified);
+		}
+		return claimed;
+	}
+};
+//#endregion
+//#region src/commissions/models/Commission.ts
+var __defProp$4 = Object.defineProperty;
+var __getOwnPropDesc$4 = Object.getOwnPropertyDescriptor;
+var __decorateClass$4 = (decorators, target, key, kind) => {
+	var result = kind > 1 ? void 0 : kind ? __getOwnPropDesc$4(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$4(target, key, result);
+	return result;
+};
+var COMMISSION_STATUS_TRANSITIONS = {
+	pending: ["earned"],
+	earned: ["approved"],
+	approved: ["payable"],
+	payable: ["paid"],
+	paid: []
+};
+var loadedCommissionStatus = /* @__PURE__ */ new WeakMap();
+var Commission = class extends SmrtObject {
+	tenantId = null;
+	earnerId = "";
+	earningEventId = "";
+	/** Snapshot reference: plan key at calculation time. */
+	planKey = "";
+	/** Snapshot reference: plan version at calculation time. */
+	planVersion = 0;
+	/** Which plan component produced this commission. */
+	componentKey = "";
+	/**
+	* Generic polymorphic reference to the terms snapshot that governed the
+	* calculation (e.g. the referrals module sets
+	* `('referral_term_snapshot', <id>)`). Free-form; this module attaches no
+	* semantics beyond recording it in the dedupe key and trace.
+	*/
+	termsSnapshotKind = "";
+	/** Id of the terms snapshot named by {@link termsSnapshotKind}. */
+	termsSnapshotId = "";
+	/** How {@link baseAmountCents} was resolved from the event. */
+	basis = "gross";
+	/** Base amount the rate was applied to, in integer cents. */
+	baseAmountCents = 0;
+	/** Rate applied (0–1). Recorded as `0` for `fixed`-basis commissions. */
+	rate = 0;
+	/** Split share applied (0–1). `1.0` for unsplit commissions. */
+	shareFraction = 1;
+	/**
+	* Groups the sibling commissions of one split — every earner sharing an
+	* event/component carries the same `splitGroupId`. Empty for unsplit rows.
+	*/
+	splitGroupId = "";
+	/** The earned amount in integer cents. */
+	amountCents = 0;
+	/** ISO 4217 currency (copied from the earning event). */
+	currency = "USD";
+	/**
+	* Lifecycle status — strict chain `pending → earned → approved → payable
+	* → paid`. Mutate via the transition methods; the save-time guard rejects
+	* illegal edges.
+	*/
+	status = "pending";
+	/**
+	* End of the clearing window (refund/chargeback holdback). `null` means
+	* no clearing applies — the commission is immediately sweepable to
+	* `earned` (see `CommissionSettlementService.sweepClearing`).
+	*/
+	clearingEndsAt = null;
+	/** When the commission transitioned to `earned`. */
+	earnedAt = null;
+	/** When the commission transitioned to `approved`. */
+	approvedAt = null;
+	/** When the commission transitioned to `payable`. */
+	payableAt = null;
+	/** When the commission transitioned to `paid`. */
+	paidAt = null;
+	payoutId = "";
+	/** Copied from the earning event for reporting (generic source pair). */
+	sourceKind = "";
+	/** Copied from the earning event for reporting. */
+	sourceId = "";
+	/**
+	* JSON-string {@link CommissionCalculationTrace} — everything needed to
+	* reproduce {@link amountCents}. Use {@link getCalculationTrace} /
+	* {@link setCalculationTrace}.
+	*/
+	calculationTrace = "{}";
+	dedupeKey = "";
+	/** Additional metadata as a JSON string. */
+	metadata = "{}";
+	constructor(options = {}) {
+		super(options);
+		if (options.tenantId !== void 0) this.tenantId = options.tenantId;
+		if (options.earnerId !== void 0) this.earnerId = options.earnerId;
+		if (options.earningEventId !== void 0) this.earningEventId = options.earningEventId;
+		if (options.planKey !== void 0) this.planKey = options.planKey;
+		if (options.planVersion !== void 0) this.planVersion = options.planVersion;
+		if (options.componentKey !== void 0) this.componentKey = options.componentKey;
+		if (options.termsSnapshotKind !== void 0) this.termsSnapshotKind = options.termsSnapshotKind;
+		if (options.termsSnapshotId !== void 0) this.termsSnapshotId = options.termsSnapshotId;
+		if (options.basis !== void 0) this.basis = options.basis;
+		if (options.baseAmountCents !== void 0) this.baseAmountCents = options.baseAmountCents;
+		if (options.rate !== void 0) this.rate = options.rate;
+		if (options.shareFraction !== void 0) this.shareFraction = options.shareFraction;
+		if (options.splitGroupId !== void 0) this.splitGroupId = options.splitGroupId;
+		if (options.amountCents !== void 0) this.amountCents = options.amountCents;
+		if (options.currency !== void 0) this.currency = options.currency;
+		if (options.status !== void 0) this.status = options.status;
+		if (options.clearingEndsAt !== void 0) this.clearingEndsAt = Commission.coerceDate(options.clearingEndsAt);
+		if (options.earnedAt !== void 0) this.earnedAt = Commission.coerceDate(options.earnedAt);
+		if (options.approvedAt !== void 0) this.approvedAt = Commission.coerceDate(options.approvedAt);
+		if (options.payableAt !== void 0) this.payableAt = Commission.coerceDate(options.payableAt);
+		if (options.paidAt !== void 0) this.paidAt = Commission.coerceDate(options.paidAt);
+		if (options.payoutId !== void 0) this.payoutId = options.payoutId;
+		if (options.sourceKind !== void 0) this.sourceKind = options.sourceKind;
+		if (options.sourceId !== void 0) this.sourceId = options.sourceId;
+		if (options.calculationTrace !== void 0) this.calculationTrace = options.calculationTrace;
+		if (options.dedupeKey !== void 0) this.dedupeKey = options.dedupeKey;
+		if (options.metadata !== void 0) this.metadata = options.metadata;
+	}
+	/**
+	* Re-coerce timestamp fields after the framework reapplies raw option /
+	* hydrated row values, and record the loaded status for the save guard.
+	*/
+	async initialize() {
+		await super.initialize();
+		this.clearingEndsAt = Commission.coerceDate(this.clearingEndsAt);
+		this.earnedAt = Commission.coerceDate(this.earnedAt);
+		this.approvedAt = Commission.coerceDate(this.approvedAt);
+		this.payableAt = Commission.coerceDate(this.payableAt);
+		this.paidAt = Commission.coerceDate(this.paidAt);
+		if (await this.isSaved()) loadedCommissionStatus.set(this, this.status);
+		return this;
+	}
+	isPending() {
+		return this.status === "pending";
+	}
+	isEarned() {
+		return this.status === "earned";
+	}
+	isApproved() {
+		return this.status === "approved";
+	}
+	isPayable() {
+		return this.status === "payable";
+	}
+	isPaid() {
+		return this.status === "paid";
+	}
+	/** `true` once a payout batch has stamped {@link payoutId}. */
+	isSettled() {
+		return !!this.payoutId;
+	}
+	/**
+	* `pending → earned` (clearing window passed). Stamps {@link earnedAt}.
+	* Does NOT save — the caller saves.
+	*/
+	markEarned(now = /* @__PURE__ */ new Date()) {
+		this.assertTransitionFrom("pending", "earned");
+		this.status = "earned";
+		this.earnedAt = now;
+	}
+	/**
+	* `earned → approved` (operator/automation approved the earning).
+	* Stamps {@link approvedAt}. Does NOT save — the caller saves.
+	*/
+	approve(now = /* @__PURE__ */ new Date()) {
+		this.assertTransitionFrom("earned", "approved");
+		this.status = "approved";
+		this.approvedAt = now;
+	}
+	/**
+	* `approved → payable` (released for the next payout batch).
+	* Stamps {@link payableAt}. Does NOT save — the caller saves.
+	*/
+	markPayable(now = /* @__PURE__ */ new Date()) {
+		this.assertTransitionFrom("approved", "payable");
+		this.status = "payable";
+		this.payableAt = now;
+	}
+	/**
+	* `payable → paid` (its payout batch completed). Stamps {@link paidAt}.
+	* Does NOT save — the caller saves.
+	*/
+	markPaid(now = /* @__PURE__ */ new Date()) {
+		this.assertTransitionFrom("payable", "paid");
+		this.status = "paid";
+		this.paidAt = now;
+	}
+	assertTransitionFrom(expected, next) {
+		if (this.status !== expected) throw new Error(`Commission ${this.id ?? "<new>"}: cannot transition to '${next}' from status '${this.status}' (chain is pending \u2192 earned \u2192 approved \u2192 payable \u2192 paid)`);
+	}
+	/** Parse {@link calculationTrace}; returns `null` on empty/invalid JSON. */
+	getCalculationTrace() {
+		if (!this.calculationTrace) return null;
+		try {
+			const parsed = JSON.parse(this.calculationTrace);
+			if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) return null;
+			const trace = parsed;
+			return typeof trace.componentKey === "string" && typeof trace.baseAmountCents === "number" ? trace : null;
+		} catch {
+			return null;
+		}
+	}
+	/** Serialize and store {@link calculationTrace}. */
+	setCalculationTrace(trace) {
+		this.calculationTrace = JSON.stringify(trace);
+	}
+	/** Parse {@link metadata}; returns `{}` on empty/invalid JSON. */
+	getMetadata() {
+		if (!this.metadata) return {};
+		try {
+			const parsed = JSON.parse(this.metadata);
+			return parsed && typeof parsed === "object" && !Array.isArray(parsed) ? parsed : {};
+		} catch {
+			return {};
+		}
+	}
+	/** Serialize and store {@link metadata}. */
+	setMetadata(data) {
+		this.metadata = JSON.stringify(data ?? {});
+	}
+	/**
+	* Save-time state-machine guard (commerce pattern). Validates the status
+	* transition against the AUTHORITATIVE prior persisted status — re-read
+	* from the database so a `create({ id: <existing>, _skipLoad: true })`
+	* upsert is correctly treated as an update rather than a guard-free new
+	* row. Brand-new rows may start in any status (fixtures/imports); a
+	* persisted row may only advance one legal step.
+	*/
+	async save() {
+		const prior = await this.resolvePriorStatus();
+		this.assertStatusTransition(prior);
+		await this.assertDedupeKeyNotTaken();
+		const result = await super.save();
+		loadedCommissionStatus.set(this, this.status);
+		return result;
+	}
+	/**
+	* Refuse a save whose `dedupeKey` already belongs to a DIFFERENT row —
+	* commissions are audit rows, and the natural-key upsert would let a
+	* fresh instance (generated `create`, or the loser of a calculation
+	* race) overwrite the persisted amount/status and rotate the row id.
+	* `CommissionCalculationService` treats this refusal as "someone else
+	* already earned it" and returns the existing row.
+	*/
+	async assertDedupeKeyNotTaken() {
+		if (!this.dedupeKey) return;
+		try {
+			const res = await this.db.query(`SELECT id FROM ${this.tableName} WHERE dedupe_key = $1`, this.dedupeKey);
+			if ((Array.isArray(res) ? res : res.rows ?? []).find((row) => row.id !== this.id)) throw new Error(`Commission (dedupeKey '${this.dedupeKey}'): a commission with this dedupe key already exists \u2014 commissions are immutable audit rows; corrections append CommissionAdjustments.`);
+		} catch (error) {
+			if (error instanceof Error && error.message.includes("immutable")) throw error;
+		}
+	}
+	async resolvePriorStatus() {
+		if (this.id) try {
+			const row = await this.db.get(this.tableName, { id: this.id });
+			if (row && row.status != null) return row.status;
+		} catch {}
+		return loadedCommissionStatus.get(this);
+	}
+	assertStatusTransition(prior) {
+		if (prior === void 0) return;
+		if (prior === this.status) return;
+		if (!(COMMISSION_STATUS_TRANSITIONS[prior] ?? []).includes(this.status)) throw new Error(`Commission ${this.id}: illegal status transition '${prior}' \u2192 '${this.status}'. Use markEarned() / approve() / markPayable() / markPaid().`);
+	}
+	static coerceDate(value) {
+		if (value == null) return null;
+		if (value instanceof Date) return value;
+		if (typeof value === "number" || typeof value === "string") {
+			const d = new Date(value);
+			return Number.isNaN(d.getTime()) ? null : d;
+		}
+		return null;
+	}
+};
+__decorateClass$4([tenantId({ nullable: true })], Commission.prototype, "tenantId", 2);
+__decorateClass$4([foreignKey("Earner", { required: true })], Commission.prototype, "earnerId", 2);
+__decorateClass$4([foreignKey("EarningEvent")], Commission.prototype, "earningEventId", 2);
+__decorateClass$4([foreignKey("CommissionPayout")], Commission.prototype, "payoutId", 2);
+__decorateClass$4([field({ required: true })], Commission.prototype, "dedupeKey", 2);
+Commission = __decorateClass$4([TenantScoped({ mode: "optional" }), smrt({
+	conflictColumns: ["dedupe_key"],
+	api: { include: [
+		"list",
+		"get",
+		"create"
+	] },
+	mcp: { include: ["list", "get"] },
+	cli: false
+})], Commission);
+//#endregion
+//#region src/commissions/collections/CommissionCollection.ts
+var CommissionCollection = class extends SmrtCollection {
+	static _itemClass = Commission;
+	/** All commissions for an earner, newest first. */
+	async findByEarner(earnerId) {
+		return await this.list({
+			where: { earnerId },
+			orderBy: "created_at DESC"
+		});
+	}
+	/** All commissions derived from one earning event. */
+	async findByEvent(earningEventId) {
+		return await this.list({
+			where: { earningEventId },
+			orderBy: "created_at DESC"
+		});
+	}
+	/** Commissions by lifecycle status, newest first. */
+	async findByStatus(status) {
+		return await this.list({
+			where: { status },
+			orderBy: "created_at DESC"
+		});
+	}
+	/** Look up a commission by its idempotency natural key. */
+	async findByDedupeKey(dedupeKey) {
+		if (!dedupeKey) return null;
+		return (await this.list({
+			where: { dedupeKey },
+			limit: 1
+		}))[0] ?? null;
+	}
+	/**
+	* Payable commissions for an earner+currency that no payout batch has
+	* settled yet — the rows `CommissionPayoutService.createPayoutBatch`
+	* gathers.
+	*/
+	async findPayableUnsettled(earnerId, currency) {
+		return (await this.list({
+			where: {
+				earnerId,
+				currency,
+				status: "payable"
+			},
+			orderBy: "created_at ASC"
+		})).filter((c) => !c.payoutId);
+	}
+	/** Σ amountCents of {@link findPayableUnsettled} rows (integer cents). */
+	async sumPayableByEarner(earnerId, currency) {
+		return (await this.findPayableUnsettled(earnerId, currency)).reduce((sum, c) => sum + c.amountCents, 0);
+	}
+	/** Commissions settled by one payout batch. */
+	async findByPayout(payoutId) {
+		return await this.list({
+			where: { payoutId },
+			orderBy: "created_at ASC"
+		});
+	}
+	/**
+	* Conditionally claim rows for a payout batch: each row is re-loaded
+	* fresh and stamped with `payoutId` only when it is still payable and
+	* unclaimed (or already claimed by THIS payout — the idempotent-retry /
+	* repair case). Rows claimed by a DIFFERENT payout are skipped, and every
+	* claim is verified by a post-save re-read so a lost race never counts
+	* toward the caller's totals.
+	*
+	* This is the single place claim semantics live. It narrows the
+	* concurrent-batch window to the re-read granularity; true compare-and-set
+	* needs DB transactions the collection layer doesn't expose (settlement
+	* runs are expected to be single-writer per earner — see
+	* `CommissionPayoutService`).
+	*
+	* Returns the claimed rows (freshly loaded, `payoutId` verified).
+	*/
+	async claimForPayout(commissionIds, payoutId) {
+		const claimed = [];
+		for (const id of commissionIds) {
+			const row = await this.get({ id });
+			if (!row) continue;
+			if (row.payoutId && row.payoutId !== payoutId) continue;
+			if (!row.payoutId) {
+				if (!row.isPayable()) continue;
+				row.payoutId = payoutId;
+				await row.save();
+			}
+			const verified = await this.get({ id });
+			if (verified && verified.payoutId === payoutId) claimed.push(verified);
+		}
+		return claimed;
+	}
+};
+//#endregion
+//#region src/commissions/models/CommissionPayout.ts
+var __defProp$3 = Object.defineProperty;
+var __getOwnPropDesc$3 = Object.getOwnPropertyDescriptor;
+var __decorateClass$3 = (decorators, target, key, kind) => {
+	var result = kind > 1 ? void 0 : kind ? __getOwnPropDesc$3(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$3(target, key, result);
+	return result;
+};
+var PAYOUT_STATUS_TRANSITIONS = {
+	pending: ["approved"],
+	approved: ["processing", "failed"],
+	processing: ["completed", "failed"],
+	completed: [],
+	failed: ["pending"]
+};
+var loadedPayoutStatus = /* @__PURE__ */ new WeakMap();
+var CommissionPayout = class extends SmrtObject {
+	tenantId = null;
+	earnerId = "";
+	/** Start of the settlement period this batch covers (informational). */
+	periodStart = null;
+	/** End of the settlement period this batch covers (informational). */
+	periodEnd = null;
+	/** Σ amountCents of the Commissions this batch settled (integer cents). */
+	commissionTotalCents = 0;
+	/**
+	* Σ signed amountCents of the Adjustments this batch settled (integer
+	* cents; clawbacks make it negative).
+	*/
+	adjustmentTotalCents = 0;
+	/**
+	* Net amount remitted — must equal
+	* `commissionTotalCents + adjustmentTotalCents` (enforced on save).
+	*/
+	totalAmountCents = 0;
+	/** ISO 4217 currency of the batch. */
+	currency = "USD";
+	/** Delivery method for this batch (defaulted from the Earner). */
+	payoutMethod = "bank_transfer";
+	/**
+	* Lifecycle status — see the class doc. Mutate via {@link approve} /
+	* {@link markProcessing} / {@link complete} / {@link fail} /
+	* {@link resetFromFailed}.
+	*/
+	status = "pending";
+	/**
+	* Payment reference recorded at completion (check number, transfer id,
+	* …). Cleared by {@link resetFromFailed}.
+	*/
+	paymentReference = "";
+	/**
+	* Opaque payout-provider reference (processor batch id, remittance file
+	* id, …). Retained across failure/reset for audit.
+	*/
+	providerRef = "";
+	/** When the payout completed. */
+	paidAt = null;
+	invoiceId = "";
+	/** Operator notes — approval memos, failure reasons (append-only). */
+	notes = "";
+	idempotencyKey = "";
+	/** Additional metadata as a JSON string. */
+	metadata = "{}";
+	constructor(options = {}) {
+		super(options);
+		if (options.tenantId !== void 0) this.tenantId = options.tenantId;
+		if (options.earnerId !== void 0) this.earnerId = options.earnerId;
+		if (options.periodStart !== void 0) this.periodStart = CommissionPayout.coerceDate(options.periodStart);
+		if (options.periodEnd !== void 0) this.periodEnd = CommissionPayout.coerceDate(options.periodEnd);
+		if (options.commissionTotalCents !== void 0) this.commissionTotalCents = options.commissionTotalCents;
+		if (options.adjustmentTotalCents !== void 0) this.adjustmentTotalCents = options.adjustmentTotalCents;
+		if (options.totalAmountCents !== void 0) this.totalAmountCents = options.totalAmountCents;
+		if (options.currency !== void 0) this.currency = options.currency;
+		if (options.payoutMethod !== void 0) this.payoutMethod = options.payoutMethod;
+		if (options.status !== void 0) this.status = options.status;
+		if (options.paymentReference !== void 0) this.paymentReference = options.paymentReference;
+		if (options.providerRef !== void 0) this.providerRef = options.providerRef;
+		if (options.paidAt !== void 0) this.paidAt = CommissionPayout.coerceDate(options.paidAt);
+		if (options.invoiceId !== void 0) this.invoiceId = options.invoiceId;
+		if (options.notes !== void 0) this.notes = options.notes;
+		if (options.idempotencyKey !== void 0) this.idempotencyKey = options.idempotencyKey;
+		if (options.metadata !== void 0) this.metadata = options.metadata;
+	}
+	/**
+	* Re-coerce timestamp fields after the framework reapplies raw option /
+	* hydrated row values, and record the loaded status for the save guard.
+	*/
+	async initialize() {
+		await super.initialize();
+		this.periodStart = CommissionPayout.coerceDate(this.periodStart);
+		this.periodEnd = CommissionPayout.coerceDate(this.periodEnd);
+		this.paidAt = CommissionPayout.coerceDate(this.paidAt);
+		if (await this.isSaved()) loadedPayoutStatus.set(this, this.status);
+		return this;
+	}
+	isPending() {
+		return this.status === "pending";
+	}
+	isApproved() {
+		return this.status === "approved";
+	}
+	isProcessing() {
+		return this.status === "processing";
+	}
+	isCompleted() {
+		return this.status === "completed";
+	}
+	isFailed() {
+		return this.status === "failed";
+	}
+	/** `pending → approved`. Does NOT save — the caller saves. */
+	approve() {
+		if (this.status !== "pending") throw new Error(`CommissionPayout ${this.id ?? "<new>"}: cannot approve from status '${this.status}'`);
+		if (this.totalAmountCents <= 0) throw new Error(`CommissionPayout ${this.id ?? "<new>"}: cannot approve a batch with non-positive total (${this.totalAmountCents} cents)`);
+		this.status = "approved";
+	}
+	/** `approved → processing`. Does NOT save — the caller saves. */
+	markProcessing() {
+		if (this.status !== "approved") throw new Error(`CommissionPayout ${this.id ?? "<new>"}: cannot mark processing from status '${this.status}'`);
+		this.status = "processing";
+	}
+	/**
+	* `processing → completed`. Requires a payment reference — a completed
+	* payout with no reference is untraceable. Stamps {@link paidAt}.
+	* Does NOT save — the caller saves.
+	*/
+	complete(paymentReference, now = /* @__PURE__ */ new Date()) {
+		if (this.status !== "processing") throw new Error(`CommissionPayout ${this.id ?? "<new>"}: cannot complete from status '${this.status}'`);
+		if (!paymentReference) throw new Error(`CommissionPayout ${this.id ?? "<new>"}: complete() requires a paymentReference`);
+		this.status = "completed";
+		this.paymentReference = paymentReference;
+		this.paidAt = now;
+	}
+	/**
+	* `approved | processing → failed`. Appends the reason to {@link notes}.
+	* Does NOT save — the caller saves.
+	*/
+	fail(reason) {
+		if (this.status !== "approved" && this.status !== "processing") throw new Error(`CommissionPayout ${this.id ?? "<new>"}: cannot fail from status '${this.status}'`);
+		this.status = "failed";
+		const memo = `Failed: ${reason ?? ""}`;
+		this.notes = this.notes ? `${this.notes}
+${memo}` : memo;
+	}
+	/**
+	* Operator-driven reset: `failed → pending` after fixing whatever broke.
+	* Clears {@link paymentReference} and {@link paidAt} (the next attempt
+	* gets fresh ones) but RETAINS {@link providerRef} and {@link notes} for
+	* audit. The only path out of `failed`. Does NOT save — the caller saves.
+	*/
+	resetFromFailed() {
+		if (this.status !== "failed") throw new Error(`CommissionPayout ${this.id ?? "<new>"}: cannot reset from status '${this.status}' \u2014 only failed payouts are resettable`);
+		this.status = "pending";
+		this.paymentReference = "";
+		this.paidAt = null;
+	}
+	/** Parse {@link metadata}; returns `{}` on empty/invalid JSON. */
+	getMetadata() {
+		if (!this.metadata) return {};
+		try {
+			const parsed = JSON.parse(this.metadata);
+			return parsed && typeof parsed === "object" && !Array.isArray(parsed) ? parsed : {};
+		} catch {
+			return {};
+		}
+	}
+	/** Serialize and store {@link metadata}. */
+	setMetadata(data) {
+		this.metadata = JSON.stringify(data ?? {});
+	}
+	/**
+	* Save with two guards (commerce pattern):
+	*
+	* 1. **Totals invariant** — `totalAmountCents` must equal
+	*    `commissionTotalCents + adjustmentTotalCents` (exact integer
+	*    arithmetic, no epsilon).
+	* 2. **Status transition** — validated against the AUTHORITATIVE prior
+	*    persisted status (re-read from the database so a
+	*    `create({ id, _skipLoad: true })` upsert can't sidestep the guard).
+	*    A `completed` payout additionally requires a payment reference,
+	*    matching {@link complete}'s invariant, regardless of how the status
+	*    was set.
+	*/
+	async save() {
+		this.validateTotals();
+		const prior = await this.resolvePriorStatus();
+		this.assertStatusTransition(prior);
+		if (this.status === "completed" && !this.paymentReference) throw new Error(`CommissionPayout ${this.id ?? "<new>"}: a completed payout requires a paymentReference (use complete()).`);
+		const result = await super.save();
+		loadedPayoutStatus.set(this, this.status);
+		return result;
+	}
+	/** Throws when the totals invariant doesn't hold. */
+	validateTotals() {
+		for (const [name, value] of [
+			["commissionTotalCents", this.commissionTotalCents],
+			["adjustmentTotalCents", this.adjustmentTotalCents],
+			["totalAmountCents", this.totalAmountCents]
+		]) if (!Number.isInteger(value)) throw new Error(`CommissionPayout ${this.id ?? "<new>"}: ${name} must be integer cents (got ${value}).`);
+		const expected = this.commissionTotalCents + this.adjustmentTotalCents;
+		if (this.totalAmountCents !== expected) throw new Error(`CommissionPayout ${this.id ?? "<new>"}: totals invariant violated \u2014 commission=${this.commissionTotalCents} adjustment=${this.adjustmentTotalCents} total=${this.totalAmountCents} (expected total=${expected}).`);
+	}
+	async resolvePriorStatus() {
+		if (this.id) try {
+			const row = await this.db.get(this.tableName, { id: this.id });
+			if (row && row.status != null) return row.status;
+		} catch {}
+		return loadedPayoutStatus.get(this);
+	}
+	assertStatusTransition(prior) {
+		if (prior === void 0) return;
+		if (prior === this.status) return;
+		if (!(PAYOUT_STATUS_TRANSITIONS[prior] ?? []).includes(this.status)) throw new Error(`CommissionPayout ${this.id}: illegal status transition '${prior}' \u2192 '${this.status}'. Use approve() / markProcessing() / complete() / fail() / resetFromFailed().`);
+	}
+	static coerceDate(value) {
+		if (value == null) return null;
+		if (value instanceof Date) return value;
+		if (typeof value === "number" || typeof value === "string") {
+			const d = new Date(value);
+			return Number.isNaN(d.getTime()) ? null : d;
+		}
+		return null;
+	}
+};
+__decorateClass$3([tenantId({ nullable: true })], CommissionPayout.prototype, "tenantId", 2);
+__decorateClass$3([foreignKey("Earner", { required: true })], CommissionPayout.prototype, "earnerId", 2);
+__decorateClass$3([crossPackageRef("@happyvertical/smrt-commerce:Invoice")], CommissionPayout.prototype, "invoiceId", 2);
+__decorateClass$3([field({ required: true })], CommissionPayout.prototype, "idempotencyKey", 2);
+CommissionPayout = __decorateClass$3([TenantScoped({ mode: "optional" }), smrt({
+	conflictColumns: ["idempotency_key"],
+	api: { include: ["list", "get"] },
+	mcp: { include: ["list", "get"] },
+	cli: { include: ["list", "get"] }
+})], CommissionPayout);
+//#endregion
+//#region src/commissions/collections/CommissionPayoutCollection.ts
+var CommissionPayoutCollection = class extends SmrtCollection {
+	static _itemClass = CommissionPayout;
+	/** All payout batches for an earner, newest first. */
+	async findByEarner(earnerId) {
+		return await this.list({
+			where: { earnerId },
+			orderBy: "created_at DESC"
+		});
+	}
+	/** Payout batches by status, newest first. */
+	async findByStatus(status) {
+		return await this.list({
+			where: { status },
+			orderBy: "created_at DESC"
+		});
+	}
+	/** Look up a payout by its idempotency natural key. */
+	async findByIdempotencyKey(idempotencyKey) {
+		if (!idempotencyKey) return null;
+		return (await this.list({
+			where: { idempotencyKey },
+			limit: 1
+		}))[0] ?? null;
+	}
+	/**
+	* Σ totalAmountCents of COMPLETED payouts for an earner+currency —
+	* lifetime settled earnings (integer cents).
+	*/
+	async sumPaidByEarner(earnerId, currency) {
+		return (await this.list({ where: {
+			earnerId,
+			currency,
+			status: "completed"
+		} })).reduce((sum, p) => sum + p.totalAmountCents, 0);
+	}
+};
+//#endregion
+//#region src/commissions/types.ts
+var EARNER_STATUSES = [
+	"pending",
+	"active",
+	"suspended"
+];
+var PAYOUT_METHODS = [
+	"bank_transfer",
+	"check",
+	"paypal",
+	"credit",
+	"other"
+];
+var COMMISSION_PLAN_STATUSES = [
+	"draft",
+	"active",
+	"superseded",
+	"retired"
+];
+var COMMISSION_STATUSES = [
+	"pending",
+	"earned",
+	"approved",
+	"payable",
+	"paid"
+];
+var COMMISSION_BASES = [
+	"fixed",
+	"gross",
+	"net",
+	"margin",
+	"custom"
+];
+var COMMISSION_ADJUSTMENT_KINDS = [
+	"refund",
+	"credit",
+	"chargeback",
+	"dispute",
+	"correction"
+];
+var COMMISSION_PAYOUT_STATUSES = [
+	"pending",
+	"approved",
+	"processing",
+	"completed",
+	"failed"
+];
+var EARNING_EVENT_KINDS = [
+	"conversion",
+	"agreement_execution",
+	"invoice_payment",
+	"collected_revenue",
+	"recognized_margin",
+	"milestone"
+];
+var ADJUSTMENT_SETTLEABLE_COMMISSION_STATUSES = [
+	"earned",
+	"approved",
+	"payable",
+	"paid"
+];
+//#endregion
+//#region src/commissions/models/CommissionPlan.ts
+var __defProp$2 = Object.defineProperty;
+var __getOwnPropDesc$2 = Object.getOwnPropertyDescriptor;
+var __decorateClass$2 = (decorators, target, key, kind) => {
+	var result = kind > 1 ? void 0 : kind ? __getOwnPropDesc$2(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$2(target, key, result);
+	return result;
+};
+var PLAN_STATUS_TRANSITIONS = {
+	draft: ["active", "retired"],
+	active: ["superseded", "retired"],
+	superseded: [],
+	retired: []
+};
+var loadedPlanStatus = /* @__PURE__ */ new WeakMap();
+var frozenPlanSnapshot = /* @__PURE__ */ new WeakMap();
+function validateCommissionPlanComponents(components) {
+	if (!Array.isArray(components)) throw new Error("CommissionPlan components must be an array");
+	const seen = /* @__PURE__ */ new Set();
+	for (const component of components) {
+		const label = component?.key || "<missing key>";
+		if (!component || typeof component !== "object") throw new Error("CommissionPlan component must be an object");
+		if (!component.key || typeof component.key !== "string") throw new Error("CommissionPlan component requires a non-empty key");
+		if (seen.has(component.key)) throw new Error(`CommissionPlan component keys must be unique \u2014 duplicate '${component.key}'`);
+		seen.add(component.key);
+		if (!component.trigger || typeof component.trigger !== "string") throw new Error(`CommissionPlan component '${label}' requires a non-empty trigger ('*' matches all kinds)`);
+		if (!COMMISSION_BASES.includes(component.basis)) throw new Error(`CommissionPlan component '${label}' has invalid basis '${component.basis}'`);
+		if (component.basis === "fixed") {
+			if (typeof component.fixedAmountCents !== "number" || !Number.isInteger(component.fixedAmountCents)) throw new Error(`CommissionPlan component '${label}' with basis 'fixed' requires an integer fixedAmountCents`);
+		} else if (typeof component.rate !== "number" || !Number.isFinite(component.rate) || component.rate < 0 || component.rate > 1) throw new Error(`CommissionPlan component '${label}' with basis '${component.basis}' requires a rate in [0, 1]`);
+		if (component.basis === "custom" && !component.customBasisKey) throw new Error(`CommissionPlan component '${label}' with basis 'custom' requires a customBasisKey`);
+		const recurrence = component.recurrence;
+		if (recurrence !== void 0) {
+			if (recurrence.kind !== "one_time" && recurrence.kind !== "recurring") throw new Error(`CommissionPlan component '${label}' recurrence.kind must be 'one_time' or 'recurring'`);
+			for (const [name, value] of [["maxOccurrences", recurrence.maxOccurrences], ["windowMonths", recurrence.windowMonths]]) if (value !== void 0 && (!Number.isInteger(value) || value <= 0)) throw new Error(`CommissionPlan component '${label}' recurrence.${name} must be a positive integer`);
+		}
+	}
+}
+var CommissionPlan = class extends SmrtObject {
+	tenantId = null;
+	planKey = "";
+	/** Monotonic version within `planKey`. Amendments insert `max + 1`. */
+	version = 1;
+	/** Human-readable plan name. */
+	name = "";
+	/** Longer human-readable description of the terms. */
+	description = "";
+	/**
+	* Lifecycle status — see {@link PLAN_STATUS_TRANSITIONS}. Mutate via
+	* {@link activate} / {@link supersede} / {@link retire} (or a legal
+	* single-step assignment; the save-time guard rejects illegal edges).
+	*/
+	status = "draft";
+	/** When this version takes effect. Frozen once the plan activates. */
+	effectiveFrom = null;
+	/** ISO 4217 currency the plan's terms are denominated in. */
+	currency = "USD";
+	/**
+	* Calculation components as a JSON-string array — see
+	* {@link CommissionPlanComponent}. Use {@link getComponents} /
+	* {@link setComponents} (the setter validates).
+	*/
+	components = "[]";
+	/** Additional metadata as a JSON string. */
+	metadata = "{}";
+	constructor(options = {}) {
+		super(options);
+		if (options.tenantId !== void 0) this.tenantId = options.tenantId;
+		if (options.planKey !== void 0) this.planKey = options.planKey;
+		if (options.version !== void 0) this.version = options.version;
+		if (options.name !== void 0) this.name = options.name;
+		if (options.description !== void 0) this.description = options.description;
+		if (options.status !== void 0) this.status = options.status;
+		if (options.effectiveFrom !== void 0) this.effectiveFrom = CommissionPlan.coerceDate(options.effectiveFrom);
+		if (options.currency !== void 0) this.currency = options.currency;
+		if (options.components !== void 0) this.components = options.components;
+		if (options.metadata !== void 0) this.metadata = options.metadata;
+	}
+	/**
+	* Re-coerce date fields after the framework reapplies raw option values,
+	* record the loaded status for the transition guard, and capture the
+	* frozen snapshot when the row arrived already activated. The snapshot is
+	* captured for every non-draft status (not just `active`) so a superseded
+	* or retired version — history — can't be rewritten either.
+	*/
+	async initialize() {
+		await super.initialize();
+		this.effectiveFrom = CommissionPlan.coerceDate(this.effectiveFrom);
+		if (await this.isSaved()) {
+			loadedPlanStatus.set(this, this.status);
+			if (this.status !== "draft") frozenPlanSnapshot.set(this, this.serializeFrozenSnapshot());
+		}
+		return this;
+	}
+	isDraft() {
+		return this.status === "draft";
+	}
+	isActive() {
+		return this.status === "active";
+	}
+	/** Parse {@link components}; returns `[]` on empty/invalid JSON. */
+	getComponents() {
+		if (!this.components) return [];
+		try {
+			const parsed = JSON.parse(this.components);
+			return Array.isArray(parsed) ? parsed : [];
+		} catch {
+			return [];
+		}
+	}
+	/**
+	* Validate and store the components array. Throws on invalid components —
+	* see {@link validateCommissionPlanComponents} for the rules.
+	*/
+	setComponents(components) {
+		validateCommissionPlanComponents(components);
+		this.components = JSON.stringify(components);
+	}
+	/** Parse {@link metadata}; returns `{}` on empty/invalid JSON. */
+	getMetadata() {
+		if (!this.metadata) return {};
+		try {
+			const parsed = JSON.parse(this.metadata);
+			return parsed && typeof parsed === "object" && !Array.isArray(parsed) ? parsed : {};
+		} catch {
+			return {};
+		}
+	}
+	/** Serialize and store {@link metadata}. */
+	setMetadata(data) {
+		this.metadata = JSON.stringify(data ?? {});
+	}
+	/**
+	* Transition `draft → active`. Validates components first so no active
+	* plan can carry malformed terms.
+	*/
+	activate() {
+		if (this.status !== "draft") throw new Error(`CommissionPlan ${this.planKey}@${this.version}: cannot activate from status '${this.status}'`);
+		validateCommissionPlanComponents(this.getComponents());
+		this.status = "active";
+	}
+	/** Transition `active → superseded` (a newer version took over). */
+	supersede() {
+		if (this.status !== "active") throw new Error(`CommissionPlan ${this.planKey}@${this.version}: cannot supersede from status '${this.status}'`);
+		this.status = "superseded";
+	}
+	/** Transition `draft | active → retired` (terminal). */
+	retire() {
+		if (this.status !== "draft" && this.status !== "active") throw new Error(`CommissionPlan ${this.planKey}@${this.version}: cannot retire from status '${this.status}'`);
+		this.status = "retired";
+	}
+	/**
+	* Save with two guards:
+	*
+	* 1. **Status transition** — the about-to-be-written status must be a
+	*    legal edge from the authoritative prior persisted status (re-read
+	*    from the DB so a `create({ id: <existing>, _skipLoad: true })` upsert
+	*    can't sidestep the guard — commerce pattern).
+	* 2. **Frozen calculation identity** — once the row has been saved
+	*    non-draft, `components` / `currency` / `planKey` / `version` /
+	*    `effectiveFrom` must match the captured snapshot. Amend by inserting
+	*    a new version instead.
+	*
+	* Activating saves also re-validate components, so an `active` row always
+	* carries well-formed terms regardless of which write path set them.
+	*/
+	async save() {
+		const prior = await this.resolvePriorStatus();
+		this.assertStatusTransition(prior);
+		this.assertFrozenIdentityUnchanged();
+		await this.assertNaturalKeyNotTaken();
+		if (this.status === "active") validateCommissionPlanComponents(this.getComponents());
+		const result = await super.save();
+		loadedPlanStatus.set(this, this.status);
+		if (this.status !== "draft" && !frozenPlanSnapshot.has(this)) frozenPlanSnapshot.set(this, this.serializeFrozenSnapshot());
+		return result;
+	}
+	/**
+	* Refuse a save whose `(tenantId, planKey, version)` natural key already
+	* belongs to a DIFFERENT row. The frozen-identity guard above is
+	* instance-local (WeakMap), so a FRESH instance carrying an existing
+	* natural key would otherwise sail through and the conflict-column
+	* upsert would rewrite the persisted terms (and rotate the row id).
+	* Edit drafts by hydrating them; change terms with
+	* `CommissionPlanCollection.createAmendment()`.
+	*/
+	async assertNaturalKeyNotTaken() {
+		if (!this.planKey) return;
+		try {
+			const res = await this.db.query(`SELECT id, tenant_id FROM ${this.tableName} WHERE plan_key = $1 AND version = $2`, this.planKey, this.version);
+			if ((Array.isArray(res) ? res : res.rows ?? []).find((row) => (row.tenant_id ?? null) === (this.tenantId ?? null) && row.id !== this.id)) throw new Error(`CommissionPlan ${this.planKey}@${this.version}: this version already exists for the tenant \u2014 plan versions are immutable records. Hydrate the existing row to edit a draft, or create new terms with CommissionPlanCollection.createAmendment().`);
+		} catch (error) {
+			if (error instanceof Error && error.message.includes("immutable")) throw error;
+		}
+	}
+	/**
+	* Resolve the AUTHORITATIVE prior status from the database; fall back to
+	* the loaded-status WeakMap only when the DB is unavailable. `undefined`
+	* means no persisted row exists (genuinely new).
+	*/
+	async resolvePriorStatus() {
+		if (this.id) try {
+			const row = await this.db.get(this.tableName, { id: this.id });
+			if (row && row.status != null) return row.status;
+		} catch {}
+		return loadedPlanStatus.get(this);
+	}
+	assertStatusTransition(prior) {
+		if (prior === void 0) return;
+		if (prior === this.status) return;
+		if (!(PLAN_STATUS_TRANSITIONS[prior] ?? []).includes(this.status)) throw new Error(`CommissionPlan ${this.planKey}@${this.version}: illegal status transition '${prior}' \u2192 '${this.status}'. Use activate() / supersede() / retire().`);
+	}
+	assertFrozenIdentityUnchanged() {
+		const captured = frozenPlanSnapshot.get(this);
+		if (!captured) return;
+		if (captured !== this.serializeFrozenSnapshot()) throw new Error(`CommissionPlan ${this.planKey}@${this.version}: components, currency, planKey, version, and effectiveFrom are immutable once the plan has been active. Create an amendment (CommissionPlanCollection.createAmendment) instead of editing this version.`);
+	}
+	serializeFrozenSnapshot() {
+		return JSON.stringify({
+			planKey: this.planKey,
+			version: this.version,
+			currency: this.currency,
+			components: this.components,
+			effectiveFrom: this.effectiveFrom ? this.effectiveFrom.toISOString() : null
+		});
+	}
+	static coerceDate(value) {
+		if (value == null) return null;
+		if (value instanceof Date) return value;
+		if (typeof value === "number" || typeof value === "string") {
+			const d = new Date(value);
+			return Number.isNaN(d.getTime()) ? null : d;
+		}
+		return null;
+	}
+};
+__decorateClass$2([tenantId({ nullable: true })], CommissionPlan.prototype, "tenantId", 2);
+__decorateClass$2([field({ required: true })], CommissionPlan.prototype, "planKey", 2);
+CommissionPlan = __decorateClass$2([TenantScoped({ mode: "optional" }), smrt({
+	conflictColumns: [
+		"tenant_id",
+		"plan_key",
+		"version"
+	],
+	api: { include: [
+		"list",
+		"get",
+		"create"
+	] },
+	mcp: { include: ["list", "get"] },
+	cli: true
+})], CommissionPlan);
+//#endregion
+//#region src/commissions/collections/CommissionPlanCollection.ts
+var CommissionPlanCollection = class extends SmrtCollection {
+	static _itemClass = CommissionPlan;
+	/** Every version of a plan, newest version first. */
+	async findByPlanKey(planKey) {
+		return await this.list({
+			where: { planKey },
+			orderBy: "version DESC"
+		});
+	}
+	/** Plans by status. */
+	async findByStatus(status) {
+		return await this.list({
+			where: { status },
+			orderBy: "created_at DESC"
+		});
+	}
+	/**
+	* The highest ACTIVE version of a plan already IN EFFECT at `at`, or
+	* `null` when none is. This is what calculation callers resolve terms
+	* from when no frozen snapshot pins a specific version. A future-dated
+	* amendment can be activated ahead of its effective date without
+	* governing earlier qualifications (`effectiveFrom: null` = effective
+	* immediately).
+	*/
+	async latestActiveByKey(planKey, at = /* @__PURE__ */ new Date(), tenantId) {
+		const inEffect = (await this.list({
+			where: {
+				planKey,
+				status: "active"
+			},
+			orderBy: "version DESC"
+		})).filter((plan) => plan.effectiveFrom === null || plan.effectiveFrom <= at);
+		if (tenantId === void 0) return inEffect[0] ?? null;
+		return inEffect.find((plan) => plan.tenantId === tenantId) ?? inEffect.find((plan) => plan.tenantId === null) ?? null;
+	}
+	/**
+	* Create an amendment: insert a new DRAFT row with
+	* `version = max(existing versions) + 1`, copying the latest existing
+	* version's fields and then applying `changes`. The source version is not
+	* touched — activate the draft (and supersede the prior active version)
+	* as a separate, explicit step.
+	*
+	* Throws when no version of `planKey` exists (nothing to amend — use
+	* `create` for a brand-new plan).
+	*/
+	async createAmendment(planKey, changes = {}) {
+		const latest = (await this.findByPlanKey(planKey))[0];
+		if (!latest) throw new Error(`CommissionPlanCollection.createAmendment: no versions exist for plan key '${planKey}' \u2014 create the plan first`);
+		if (changes.components !== void 0) validateCommissionPlanComponents(changes.components);
+		return await this.create({
+			tenantId: latest.tenantId,
+			planKey,
+			version: latest.version + 1,
+			status: "draft",
+			name: changes.name ?? latest.name,
+			description: changes.description ?? latest.description,
+			currency: changes.currency ?? latest.currency,
+			effectiveFrom: changes.effectiveFrom !== void 0 ? changes.effectiveFrom : latest.effectiveFrom,
+			components: changes.components !== void 0 ? JSON.stringify(changes.components) : latest.components,
+			metadata: changes.metadata !== void 0 ? JSON.stringify(changes.metadata) : latest.metadata
+		});
+	}
+};
+//#endregion
+//#region src/commissions/models/Earner.ts
+var __defProp$1 = Object.defineProperty;
+var __getOwnPropDesc$1 = Object.getOwnPropertyDescriptor;
+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 Earner = class extends SmrtObject {
+	tenantId = null;
+	profileId = "";
+	/** Human-readable display name for portals and operator views. */
+	displayName = "";
+	/** Account lifecycle: `pending` (default) → `active` / `suspended`. */
+	status = "pending";
+	/** Preferred payout delivery method. */
+	payoutMethod = "bank_transfer";
+	/**
+	* Minimum unsettled balance (integer cents) before a payout batch is
+	* created. Default $50.00 = 5000 cents.
+	*/
+	payoutThresholdCents = 5e3;
+	/**
+	* Payout cadence key. Open string so applications can define their own
+	* schedules (`manual`, `monthly`, `weekly`, `net_30`, …); `manual` means
+	* an operator triggers batches explicitly.
+	*/
+	payoutScheduleKey = "manual";
+	/** ISO 4217 currency all of this earner's balances settle in. */
+	currency = "USD";
+	/**
+	* Additional metadata as a JSON string (tax info, payout-rail details,
+	* …). Use {@link getMetadata}/{@link setMetadata}.
+	*/
+	metadata = "{}";
+	constructor(options = {}) {
+		super(options);
+		if (options.tenantId !== void 0) this.tenantId = options.tenantId;
+		if (options.profileId !== void 0) this.profileId = options.profileId;
+		if (options.displayName !== void 0) this.displayName = options.displayName;
+		if (options.status !== void 0) this.status = options.status;
+		if (options.payoutMethod !== void 0) this.payoutMethod = options.payoutMethod;
+		if (options.payoutThresholdCents !== void 0) this.payoutThresholdCents = options.payoutThresholdCents;
+		if (options.payoutScheduleKey !== void 0) this.payoutScheduleKey = options.payoutScheduleKey;
+		if (options.currency !== void 0) this.currency = options.currency;
+		if (options.metadata !== void 0) this.metadata = options.metadata;
+	}
+	isActive() {
+		return this.status === "active";
+	}
+	isPending() {
+		return this.status === "pending";
+	}
+	isSuspended() {
+		return this.status === "suspended";
+	}
+	/** Parse {@link metadata}; returns `{}` on empty/invalid JSON. */
+	getMetadata() {
+		if (!this.metadata) return {};
+		try {
+			const parsed = JSON.parse(this.metadata);
+			return parsed && typeof parsed === "object" && !Array.isArray(parsed) ? parsed : {};
+		} catch {
+			return {};
+		}
+	}
+	/** Serialize and store {@link metadata}. */
+	setMetadata(data) {
+		this.metadata = JSON.stringify(data ?? {});
+	}
+};
+__decorateClass$1([tenantId({ nullable: true })], Earner.prototype, "tenantId", 2);
+__decorateClass$1([crossPackageRef("@happyvertical/smrt-profiles:Profile")], Earner.prototype, "profileId", 2);
+Earner = __decorateClass$1([TenantScoped({ mode: "optional" }), smrt({
+	api: { include: [
+		"list",
+		"get",
+		"create",
+		"update"
+	] },
+	mcp: { include: [
+		"list",
+		"get",
+		"create"
+	] },
+	cli: true
+})], Earner);
+//#endregion
+//#region src/commissions/collections/EarnerCollection.ts
+var EarnerCollection = class extends SmrtCollection {
+	static _itemClass = Earner;
+	/** Earners linked to a smrt-profiles Profile. */
+	async findByProfile(profileId) {
+		return await this.list({
+			where: { profileId },
+			orderBy: "created_at DESC"
+		});
+	}
+	/** Earners by status. */
+	async findByStatus(status) {
+		return await this.list({
+			where: { status },
+			orderBy: "created_at DESC"
+		});
+	}
+	/** All active earners. */
+	async findActive() {
+		return await this.findByStatus("active");
+	}
+};
+//#endregion
+//#region src/commissions/models/EarningEvent.ts
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+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 persistedEventState = /* @__PURE__ */ new WeakMap();
+var EarningEvent = class extends SmrtObject {
+	tenantId = null;
+	eventKind = "";
+	/** When the commercial event occurred (not when it was ingested). */
+	occurredAt = /* @__PURE__ */ new Date();
+	/**
+	* Generic earning-source discriminator (`referral`, `opportunity`,
+	* `subscription`, `ad_event`, …). Free-form; this module attaches no
+	* semantics to it.
+	*/
+	sourceKind = "";
+	/** Id of the source record named by {@link sourceKind}. */
+	sourceId = "";
+	/** Gross amount of the event in integer cents. */
+	grossAmountCents = 0;
+	netAmountCents = null;
+	marginCents = null;
+	/** ISO 4217 currency of the event's amounts. */
+	currency = "USD";
+	/**
+	* JSON map of `basisKey → integer cents` for `custom`-basis plan
+	* components. Use {@link getCustomBases}/{@link setCustomBases}.
+	*/
+	customBases = "{}";
+	dedupeKey = "";
+	/** Additional metadata as a JSON string. */
+	metadata = "{}";
+	constructor(options = {}) {
+		super(options);
+		if (options.tenantId !== void 0) this.tenantId = options.tenantId;
+		if (options.eventKind !== void 0) this.eventKind = options.eventKind;
+		if (options.occurredAt !== void 0) this.occurredAt = EarningEvent.coerceDate(options.occurredAt) ?? /* @__PURE__ */ new Date();
+		if (options.sourceKind !== void 0) this.sourceKind = options.sourceKind;
+		if (options.sourceId !== void 0) this.sourceId = options.sourceId;
+		if (options.grossAmountCents !== void 0) this.grossAmountCents = options.grossAmountCents;
+		if (options.netAmountCents !== void 0) this.netAmountCents = options.netAmountCents;
+		if (options.marginCents !== void 0) this.marginCents = options.marginCents;
+		if (options.currency !== void 0) this.currency = options.currency;
+		if (options.customBases !== void 0) this.customBases = options.customBases;
+		if (options.dedupeKey !== void 0) this.dedupeKey = options.dedupeKey;
+		if (options.metadata !== void 0) this.metadata = options.metadata;
+	}
+	/**
+	* Re-coerce {@link occurredAt} after the framework reapplies raw option /
+	* hydrated row values (SQLite hands back ISO strings), and capture the
+	* persisted state for the immutability guard when this instance hydrated
+	* an existing row.
+	*/
+	async initialize() {
+		await super.initialize();
+		this.occurredAt = EarningEvent.coerceDate(this.occurredAt) ?? /* @__PURE__ */ new Date();
+		if (await this.isSaved()) persistedEventState.set(this, this.serializeState());
+		return this;
+	}
+	/**
+	* Save with the evidence-immutability guard. EarningEvents are immutable
+	* commercial evidence; three write vectors are closed:
+	*
+	* - a HYDRATED persisted row must serialize identically to its captured
+	*   state (no-op re-saves pass, any change throws);
+	* - an instance carrying an existing id WITHOUT having hydrated it
+	*   (`create({ id, _skipLoad: true })`) is rejected outright;
+	* - a NEW instance whose `dedupeKey` already belongs to another row is
+	*   refused outright: the natural-key upsert would not only rewrite the
+	*   evidence values but ROTATE the row's id (orphaning any Commission
+	*   whose `earningEventId` points at it). Idempotent ingestion goes
+	*   through `EarningEventCollection.getOrCreateByDedupeKey()`, which
+	*   finds first and never upserts.
+	*/
+	async save() {
+		const captured = persistedEventState.get(this);
+		if (captured !== void 0) {
+			if (captured !== this.serializeState()) throw new Error(`EarningEvent ${this.id ?? "<new>"}: earning events are immutable evidence \u2014 record a correcting event (or a CommissionAdjustment downstream) instead of editing this row.`);
+		} else if (this.id && await this.isSaved()) throw new Error(`EarningEvent ${this.id}: refusing to overwrite an existing event row from a non-hydrated instance \u2014 earning events are immutable evidence.`);
+		else if (this.dedupeKey) try {
+			const row = await this.db.get(this.tableName, { dedupe_key: this.dedupeKey });
+			if (row && row.id !== this.id) throw new Error(`EarningEvent (dedupeKey '${this.dedupeKey}'): an event with this dedupe key already exists \u2014 earning events are immutable evidence, and the natural-key upsert would rotate the existing row's id (orphaning commissions that reference it). Use EarningEventCollection.getOrCreateByDedupeKey() for idempotent ingestion, or record a new event under its own dedupe key.`);
+		} catch (error) {
+			if (error instanceof Error && error.message.includes("immutable evidence")) throw error;
+		}
+		const result = await super.save();
+		persistedEventState.set(this, this.serializeState());
+		return result;
+	}
+	serializeState() {
+		return JSON.stringify({
+			tenantId: this.tenantId,
+			eventKind: this.eventKind,
+			occurredAt: this.occurredAt.toISOString(),
+			sourceKind: this.sourceKind,
+			sourceId: this.sourceId,
+			grossAmountCents: this.grossAmountCents,
+			netAmountCents: this.netAmountCents,
+			marginCents: this.marginCents,
+			currency: this.currency,
+			customBases: this.customBases,
+			dedupeKey: this.dedupeKey,
+			metadata: this.metadata
+		});
+	}
+	/**
+	* Parse {@link customBases} into a `basisKey → cents` map; non-numeric
+	* values are dropped. Returns `{}` on empty/invalid JSON.
+	*/
+	getCustomBases() {
+		if (!this.customBases) return {};
+		try {
+			const parsed = JSON.parse(this.customBases);
+			if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) return {};
+			const out = {};
+			for (const [key, value] of Object.entries(parsed)) if (typeof value === "number" && Number.isFinite(value)) out[key] = value;
+			return out;
+		} catch {
+			return {};
+		}
+	}
+	/** Serialize and store {@link customBases}. */
+	setCustomBases(bases) {
+		this.customBases = JSON.stringify(bases ?? {});
+	}
+	/** Parse {@link metadata}; returns `{}` on empty/invalid JSON. */
+	getMetadata() {
+		if (!this.metadata) return {};
+		try {
+			const parsed = JSON.parse(this.metadata);
+			return parsed && typeof parsed === "object" && !Array.isArray(parsed) ? parsed : {};
+		} catch {
+			return {};
+		}
+	}
+	/** Serialize and store {@link metadata}. */
+	setMetadata(data) {
+		this.metadata = JSON.stringify(data ?? {});
+	}
+	static coerceDate(value) {
+		if (value == null) return null;
+		if (value instanceof Date) return value;
+		if (typeof value === "number" || typeof value === "string") {
+			const d = new Date(value);
+			return Number.isNaN(d.getTime()) ? null : d;
+		}
+		return null;
+	}
+};
+__decorateClass([tenantId({ nullable: true })], EarningEvent.prototype, "tenantId", 2);
+__decorateClass([field({ required: true })], EarningEvent.prototype, "eventKind", 2);
+__decorateClass([field({
+	type: "integer",
+	nullable: true
+})], EarningEvent.prototype, "netAmountCents", 2);
+__decorateClass([field({
+	type: "integer",
+	nullable: true
+})], EarningEvent.prototype, "marginCents", 2);
+__decorateClass([field({ required: true })], EarningEvent.prototype, "dedupeKey", 2);
+EarningEvent = __decorateClass([TenantScoped({ mode: "optional" }), smrt({
+	conflictColumns: ["dedupe_key"],
+	api: { include: [
+		"create",
+		"list",
+		"get"
+	] },
+	mcp: { include: ["list", "create"] },
+	cli: false
+})], EarningEvent);
+//#endregion
+//#region src/commissions/collections/EarningEventCollection.ts
+var EarningEventCollection = class extends SmrtCollection {
+	static _itemClass = EarningEvent;
+	/** Look up an event by its idempotency natural key. */
+	async findByDedupeKey(dedupeKey) {
+		if (!dedupeKey) return null;
+		return (await this.list({
+			where: { dedupeKey },
+			limit: 1
+		}))[0] ?? null;
+	}
+	/**
+	* Idempotent ingestion: if an event with `options.dedupeKey` already
+	* exists, return it untouched (`created: false`) — evidence is immutable,
+	* so a replay never updates the stored row. Otherwise create the event.
+	*
+	* `dedupeKey` is required — callers embed tenant/source identity in it
+	* (e.g. `` `${tenantId}:${sourceKind}:${sourceId}:${eventKind}` ``);
+	* an empty key would silently disable idempotency, so it throws instead.
+	*/
+	async getOrCreateByDedupeKey(options) {
+		const dedupeKey = options.dedupeKey ?? "";
+		if (!dedupeKey) throw new Error("EarningEventCollection.getOrCreateByDedupeKey requires a dedupeKey");
+		const existing = await this.findByDedupeKey(dedupeKey);
+		if (existing) return {
+			event: existing,
+			created: false
+		};
+		const { occurredAt, ...rest } = options;
+		return {
+			event: await this.create({
+				...rest,
+				...occurredAt !== void 0 ? { occurredAt: new Date(occurredAt) } : {}
+			}),
+			created: true
+		};
+	}
+	/** Events for one generic earning source, newest occurrence first. */
+	async findBySource(sourceKind, sourceId) {
+		return await this.list({
+			where: {
+				sourceKind,
+				sourceId
+			},
+			orderBy: "occurred_at DESC"
+		});
+	}
+	/** Events by kind, newest occurrence first. */
+	async findByKind(eventKind) {
+		return await this.list({
+			where: { eventKind },
+			orderBy: "occurred_at DESC"
+		});
+	}
+};
+//#endregion
+//#region src/commissions/money.ts
+function roundCents(value) {
+	const rounded = Math.sign(value) * Math.round(Math.abs(value));
+	return rounded === 0 ? 0 : rounded;
+}
+function centsToAmount(cents) {
+	return cents / 100;
+}
+function amountToCents(amount) {
+	return roundCents(amount * 100);
+}
+function calculateCommissionAmountCents(baseCents, rate, shareFraction) {
+	return roundCents(baseCents * rate * (shareFraction ?? 1));
+}
+//#endregion
+//#region src/commissions/services/CommissionBalanceService.ts
+var CommissionBalanceService = class CommissionBalanceService {
+	constructor(commissions, adjustments) {
+		this.commissions = commissions;
+		this.adjustments = adjustments;
+	}
+	commissions;
+	adjustments;
+	static async create(classOptions = {}) {
+		return new CommissionBalanceService(await CommissionCollection.create(classOptions), await CommissionAdjustmentCollection.create(classOptions));
+	}
+	/** Compute the {@link EarnerBalance} for one earner in one currency. */
+	async getBalance(earnerId, currency) {
+		const rows = await this.commissions.list({ where: {
+			earnerId,
+			currency
+		} });
+		const sumByStatus = (status) => rows.filter((c) => c.status === status).reduce((sum, c) => sum + c.amountCents, 0);
+		const pendingCents = sumByStatus("pending");
+		const earnedCents = sumByStatus("earned");
+		const approvedCents = sumByStatus("approved");
+		const payableCents = rows.filter((c) => c.status === "payable" && !c.payoutId).reduce((sum, c) => sum + c.amountCents, 0);
+		const statusById = /* @__PURE__ */ new Map();
+		for (const c of rows) if (c.id) statusById.set(c.id, c.status);
+		const unsettled = await this.adjustments.findUnsettledByEarner(earnerId, currency);
+		let unsettledAdjustmentCents = 0;
+		for (const adjustment of unsettled) {
+			const parentStatus = statusById.get(adjustment.commissionId);
+			if (parentStatus !== void 0 && ADJUSTMENT_SETTLEABLE_COMMISSION_STATUSES.includes(parentStatus)) unsettledAdjustmentCents += adjustment.amountCents;
+		}
+		return {
+			earnerId,
+			currency,
+			payableCents,
+			pendingCents,
+			earnedCents,
+			approvedCents,
+			unsettledAdjustmentCents,
+			netPayableCents: payableCents + unsettledAdjustmentCents
+		};
+	}
+};
+//#endregion
+//#region src/commissions/services/CommissionCalculationService.ts
+var MS_PER_DAY = 1440 * 60 * 1e3;
+var CommissionCalculationService = class CommissionCalculationService {
+	constructor(commissions, earners) {
+		this.commissions = commissions;
+		this.earners = earners;
+	}
+	commissions;
+	earners;
+	static async create(classOptions = {}) {
+		return new CommissionCalculationService(await CommissionCollection.create(classOptions), await EarnerCollection.create(classOptions));
+	}
+	/**
+	* Calculate commissions for one event × one earner × a component set.
+	*
+	* For each component whose `trigger` matches `event.eventKind` (or `'*'`
+	* — non-matching components are silently filtered, not "skipped"):
+	*
+	* 1. **Idempotency** — if a Commission already exists for this
+	*    (event, terms, component, earner) tuple, it is returned in
+	*    `existing` and nothing else runs for the component.
+	* 2. **Currency** — `input.currency` (when given) must equal the event's;
+	*    otherwise skip `'currency_mismatch'`.
+	* 3. **Recurrence** — `one_time` components skip
+	*    `'occurrence_limit_reached'` once the resolver reports ≥ 1 prior
+	*    occurrence; `recurring` components honor `maxOccurrences` and
+	*    `windowMonths` (events after `anchorAt + windowMonths` skip
+	*    `'outside_recurrence_window'`).
+	* 4. **Basis** — gross → `grossAmountCents`; net → `netAmountCents`
+	*    (skip `'net_basis_undefined'` when null — net is explicit, NEVER
+	*    derived from gross); margin → `marginCents` (skip
+	*    `'margin_basis_undefined'` when null); fixed → `fixedAmountCents`;
+	*    custom → `getCustomBases()[customBasisKey]` (skip
+	*    `'custom_basis_missing'`).
+	* 5. **Amount** — `roundCents(base * rate * shareFraction)`; for `fixed`,
+	*    `roundCents(fixedAmountCents * shareFraction)` with `rate` recorded
+	*    as `0`. Rounding happens exactly once, on the final product.
+	*
+	* Every created Commission is persisted `pending`, carries the event's
+	* tenant/currency/source, a complete {@link CommissionCalculationTrace},
+	* `clearingEndsAt` when `clearingDays` was given, and the dedupe key
+	* `` `${event.dedupeKey}:${termsSnapshotId || planKey + '@' + planVersion}:${componentKey}:${earnerId}:${occurrenceIndex}` ``.
+	*/
+	async calculateForEvent(input) {
+		const { event } = input;
+		if (!event.id) throw new Error("CommissionCalculationService.calculateForEvent requires a persisted event (missing id)");
+		if (!input.earnerId) throw new Error("CommissionCalculationService.calculateForEvent requires an earnerId");
+		const shareFraction = input.shareFraction ?? 1;
+		if (!Number.isFinite(shareFraction) || shareFraction < 0 || shareFraction > 1) throw new Error(`CommissionCalculationService.calculateForEvent: shareFraction must be a finite number in [0, 1], got ${String(shareFraction)}`);
+		validateCommissionPlanComponents(input.components);
+		if (this.earners) {
+			const earner = await this.earners.get({ id: input.earnerId });
+			if (earner && earner.tenantId !== null && (event.tenantId ?? null) !== null && earner.tenantId !== event.tenantId) throw new Error(`CommissionCalculationService.calculateForEvent: earner '${input.earnerId}' belongs to tenant '${earner.tenantId}' but the event belongs to tenant '${event.tenantId}' \u2014 cross-tenant commissions are refused.`);
+		}
+		const termsRef = input.termsSnapshotId || `${input.planKey}@${input.planVersion}`;
+		const created = [];
+		const skipped = [];
+		const existing = [];
+		for (const component of input.components) {
+			if (component.trigger !== "*" && component.trigger !== event.eventKind) continue;
+			const priorForEvent = await this.commissions.list({
+				where: {
+					earningEventId: event.id,
+					earnerId: input.earnerId,
+					componentKey: component.key,
+					planKey: input.planKey,
+					planVersion: input.planVersion,
+					termsSnapshotId: input.termsSnapshotId ?? ""
+				},
+				limit: 1
+			});
+			if (priorForEvent[0]) {
+				existing.push(priorForEvent[0]);
+				continue;
+			}
+			if (input.currency !== void 0 && input.currency !== event.currency) {
+				skipped.push({
+					componentKey: component.key,
+					reason: "currency_mismatch"
+				});
+				continue;
+			}
+			const occurrenceCount = input.occurrenceCountResolver ? await input.occurrenceCountResolver(component.key) : 0;
+			const recurrence = component.recurrence;
+			if (recurrence) {
+				if (recurrence.kind === "one_time" && occurrenceCount >= 1) {
+					skipped.push({
+						componentKey: component.key,
+						reason: "occurrence_limit_reached"
+					});
+					continue;
+				}
+				if (recurrence.kind === "recurring" && recurrence.maxOccurrences !== void 0 && occurrenceCount >= recurrence.maxOccurrences) {
+					skipped.push({
+						componentKey: component.key,
+						reason: "occurrence_limit_reached"
+					});
+					continue;
+				}
+				if (recurrence.windowMonths !== void 0 && input.anchorAt !== void 0 && event.occurredAt.getTime() > CommissionCalculationService.addMonths(input.anchorAt, recurrence.windowMonths).getTime()) {
+					skipped.push({
+						componentKey: component.key,
+						reason: "outside_recurrence_window"
+					});
+					continue;
+				}
+			}
+			let baseAmountCents;
+			switch (component.basis) {
+				case "gross":
+					baseAmountCents = event.grossAmountCents;
+					break;
+				case "net":
+					if (event.netAmountCents === null) {
+						skipped.push({
+							componentKey: component.key,
+							reason: "net_basis_undefined"
+						});
+						continue;
+					}
+					baseAmountCents = event.netAmountCents;
+					break;
+				case "margin":
+					if (event.marginCents === null) {
+						skipped.push({
+							componentKey: component.key,
+							reason: "margin_basis_undefined"
+						});
+						continue;
+					}
+					baseAmountCents = event.marginCents;
+					break;
+				case "fixed":
+					if (typeof component.fixedAmountCents !== "number") {
+						skipped.push({
+							componentKey: component.key,
+							reason: "fixed_amount_missing"
+						});
+						continue;
+					}
+					baseAmountCents = component.fixedAmountCents;
+					break;
+				case "custom": {
+					const bases = event.getCustomBases();
+					const key = component.customBasisKey ?? "";
+					const value = key ? bases[key] : void 0;
+					if (typeof value !== "number") {
+						skipped.push({
+							componentKey: component.key,
+							reason: "custom_basis_missing"
+						});
+						continue;
+					}
+					baseAmountCents = value;
+					break;
+				}
+			}
+			let rate;
+			let amountCents;
+			if (component.basis === "fixed") {
+				rate = 0;
+				amountCents = roundCents(baseAmountCents * shareFraction);
+			} else {
+				if (typeof component.rate !== "number") {
+					skipped.push({
+						componentKey: component.key,
+						reason: "rate_missing"
+					});
+					continue;
+				}
+				rate = component.rate;
+				amountCents = calculateCommissionAmountCents(baseAmountCents, rate, shareFraction);
+			}
+			const occurrenceIndex = occurrenceCount;
+			const dedupeKey = `${event.dedupeKey}:${termsRef}:${component.key}:${input.earnerId}:${occurrenceIndex}`;
+			const priorByKey = await this.commissions.findByDedupeKey(dedupeKey);
+			if (priorByKey) {
+				existing.push(priorByKey);
+				continue;
+			}
+			const trace = {
+				planKey: input.planKey,
+				planVersion: input.planVersion,
+				componentKey: component.key,
+				basis: component.basis,
+				baseAmountCents,
+				rate,
+				shareFraction,
+				occurrenceIndex,
+				earningEventId: event.id,
+				roundingMode: "half_away_from_zero"
+			};
+			let commission;
+			try {
+				commission = await this.commissions.create({
+					tenantId: event.tenantId,
+					earnerId: input.earnerId,
+					earningEventId: event.id,
+					planKey: input.planKey,
+					planVersion: input.planVersion,
+					componentKey: component.key,
+					termsSnapshotKind: input.termsSnapshotKind ?? "",
+					termsSnapshotId: input.termsSnapshotId ?? "",
+					basis: component.basis,
+					baseAmountCents,
+					rate,
+					shareFraction,
+					splitGroupId: input.splitGroupId ?? "",
+					amountCents,
+					currency: event.currency,
+					status: "pending",
+					clearingEndsAt: input.clearingDays !== void 0 ? new Date(event.occurredAt.getTime() + input.clearingDays * MS_PER_DAY) : null,
+					sourceKind: event.sourceKind,
+					sourceId: event.sourceId,
+					calculationTrace: JSON.stringify(trace),
+					dedupeKey
+				});
+			} catch (error) {
+				if (error instanceof Error && error.message.includes("immutable audit rows")) {
+					const winner = await this.commissions.list({
+						where: { dedupeKey },
+						limit: 1
+					});
+					if (winner[0]) {
+						existing.push(winner[0]);
+						continue;
+					}
+				}
+				throw error;
+			}
+			created.push(commission);
+		}
+		return {
+			created,
+			skipped,
+			existing
+		};
+	}
+	/**
+	* Calendar-month addition (UTC). JS `setUTCMonth` semantics: day-of-month
+	* overflow rolls into the next month (Jan 31 + 1 month → Mar 2/3), which
+	* is acceptable for coarse recurrence windows.
+	*/
+	static addMonths(date, months) {
+		const result = new Date(date.getTime());
+		result.setUTCMonth(result.getUTCMonth() + months);
+		return result;
+	}
+};
+//#endregion
+//#region src/commissions/services/CommissionPayoutService.ts
+var CommissionPayoutService = class CommissionPayoutService {
+	constructor(deps) {
+		this.deps = deps;
+	}
+	deps;
+	static async create(classOptions = {}) {
+		return new CommissionPayoutService({
+			earners: await EarnerCollection.create(classOptions),
+			commissions: await CommissionCollection.create(classOptions),
+			adjustments: await CommissionAdjustmentCollection.create(classOptions),
+			payouts: await CommissionPayoutCollection.create(classOptions)
+		});
+	}
+	/**
+	* Create a settlement batch for one earner in one currency.
+	*
+	* Flow:
+	* 1. **Idempotency + repair** — an existing payout with the (defaulted)
+	*    key is returned as `{ payout, created: false }`. A clean replay
+	*    touches nothing (new payable work is never swept into an existing
+	*    batch). A PENDING payout whose stored totals disagree with the rows
+	*    stamped with its id — the signature of an interrupted claim pass —
+	*    is repaired: the claim pass re-runs and the totals are reconciled
+	*    from the verified membership. Past `pending` the batch is frozen.
+	* 2. **Gather** — payable unsettled commissions for the earner/currency,
+	*    plus unsettled adjustments whose parent commission is
+	*    earned/approved/payable/paid (same eligibility as the balance
+	*    service, so the batch settles exactly what the balance reports).
+	* 3. **Refuse** — `netTotal <= 0` → `'nothing_payable'`;
+	*    `netTotal < threshold` (earner default, overridable) →
+	*    `'below_threshold'`. Nothing is minted or stamped on refusal.
+	* 4. **Mint, claim, reconcile** — create the `pending` payout, then
+	*    CLAIM the gathered rows through the collections' conditional
+	*    `claimForPayout` (rows grabbed by another batch in the interim are
+	*    skipped, never double-claimed), and finally store totals computed
+	*    from the rows that were VERIFIABLY claimed — the payout's totals
+	*    are always reproducible from its member rows.
+	*
+	* Concurrency: claims are conditional with post-save verification, which
+	* narrows but does not eliminate races between batches with different
+	* keys (the collection layer exposes no cross-row transaction — the same
+	* stance as commerce/ledgers compensation). Settlement runs are expected
+	* to be single-writer per earner; totals are correct-by-construction from
+	* claimed rows either way.
+	*/
+	async createPayoutBatch(input) {
+		const now = input.now ?? /* @__PURE__ */ new Date();
+		const earner = await this.deps.earners.get({ id: input.earnerId });
+		if (!earner) throw new Error(`CommissionPayoutService: earner '${input.earnerId}' not found`);
+		const idempotencyKey = input.idempotencyKey ?? CommissionPayoutService.defaultIdempotencyKey(input.earnerId, input.currency, input.periodEnd ?? now);
+		const existingPayout = await this.deps.payouts.findByIdempotencyKey(idempotencyKey);
+		if (existingPayout) {
+			if (existingPayout.isPending() && !await this.membershipConsistent(existingPayout)) return {
+				...await this.claimAndReconcile(existingPayout, input),
+				created: false
+			};
+			return {
+				payout: existingPayout,
+				created: false,
+				settledCommissionIds: [],
+				settledAdjustmentIds: []
+			};
+		}
+		const commissions = await this.deps.commissions.findPayableUnsettled(input.earnerId, input.currency);
+		const eligibleAdjustments = await this.findEligibleUnsettledAdjustments(input.earnerId, input.currency);
+		const commissionTotalCents = commissions.reduce((sum, c) => sum + c.amountCents, 0);
+		const adjustmentTotalCents = eligibleAdjustments.reduce((sum, a) => sum + a.amountCents, 0);
+		const netTotalCents = commissionTotalCents + adjustmentTotalCents;
+		if (netTotalCents <= 0) return {
+			payout: null,
+			created: false,
+			reason: "nothing_payable",
+			settledCommissionIds: [],
+			settledAdjustmentIds: []
+		};
+		if (netTotalCents < (input.minimumThresholdCents ?? earner.payoutThresholdCents)) return {
+			payout: null,
+			created: false,
+			reason: "below_threshold",
+			settledCommissionIds: [],
+			settledAdjustmentIds: []
+		};
+		const minted = await this.deps.payouts.create({
+			tenantId: earner.tenantId,
+			earnerId: input.earnerId,
+			currency: input.currency,
+			periodStart: input.periodStart ?? null,
+			periodEnd: input.periodEnd ?? null,
+			payoutMethod: input.payoutMethod ?? earner.payoutMethod,
+			status: "pending",
+			commissionTotalCents,
+			adjustmentTotalCents,
+			totalAmountCents: netTotalCents,
+			idempotencyKey
+		});
+		const payout = await this.deps.payouts.findByIdempotencyKey(idempotencyKey) ?? minted;
+		return {
+			...await this.claimAndReconcile(payout, input),
+			created: true
+		};
+	}
+	/**
+	* Whether a payout's stored totals are reproducible from the rows
+	* actually stamped with its id — the invariant an interrupted claim pass
+	* breaks. Clean replays short-circuit on this; repair runs only when it
+	* fails.
+	*/
+	async membershipConsistent(payout) {
+		const payoutId = payout.id ?? "";
+		const members = await this.deps.commissions.findByPayout(payoutId);
+		const memberAdjustments = await this.deps.adjustments.findByPayout(payoutId);
+		const commissionTotalCents = members.reduce((sum, c) => sum + c.amountCents, 0);
+		const adjustmentTotalCents = memberAdjustments.reduce((sum, a) => sum + a.amountCents, 0);
+		return payout.commissionTotalCents === commissionTotalCents && payout.adjustmentTotalCents === adjustmentTotalCents && payout.totalAmountCents === commissionTotalCents + adjustmentTotalCents;
+	}
+	/**
+	* Claim pass + totals reconciliation for a PENDING payout.
+	*
+	* The claim set is the union of rows already stamped with this payout
+	* (an interrupted earlier pass) and the currently gathered eligible
+	* rows. Claims go through the collections' conditional `claimForPayout`
+	* (rows owned by another batch are skipped); totals are then recomputed
+	* from the claimed rows and saved when they drift from what the payout
+	* carries. In the pathological all-rows-raced-away case the payout keeps
+	* zero totals and a note — auditable, never double-paid.
+	*/
+	async claimAndReconcile(payout, input) {
+		const payoutId = payout.id ?? "";
+		const previouslyClaimed = await this.deps.commissions.findByPayout(payoutId);
+		const gathered = await this.deps.commissions.findPayableUnsettled(input.earnerId, input.currency);
+		const commissionIds = [...new Set([...previouslyClaimed, ...gathered].map((c) => c.id).filter((id) => !!id))];
+		const claimedCommissions = await this.deps.commissions.claimForPayout(commissionIds, payoutId);
+		const previouslyClaimedAdjustments = await this.deps.adjustments.findByPayout(payoutId);
+		const gatheredAdjustments = await this.findEligibleUnsettledAdjustments(input.earnerId, input.currency);
+		const adjustmentIds = [...new Set([...previouslyClaimedAdjustments, ...gatheredAdjustments].map((a) => a.id).filter((id) => !!id))];
+		const claimedAdjustments = await this.deps.adjustments.claimForPayout(adjustmentIds, payoutId);
+		const commissionTotalCents = claimedCommissions.reduce((sum, c) => sum + c.amountCents, 0);
+		const adjustmentTotalCents = claimedAdjustments.reduce((sum, a) => sum + a.amountCents, 0);
+		const totalAmountCents = commissionTotalCents + adjustmentTotalCents;
+		if (payout.commissionTotalCents !== commissionTotalCents || payout.adjustmentTotalCents !== adjustmentTotalCents || payout.totalAmountCents !== totalAmountCents) {
+			payout.commissionTotalCents = commissionTotalCents;
+			payout.adjustmentTotalCents = adjustmentTotalCents;
+			payout.totalAmountCents = totalAmountCents;
+			if (claimedCommissions.length === 0 && claimedAdjustments.length === 0) payout.notes = "no rows claimed (raced by a concurrent batch); nothing will be paid";
+			await payout.save();
+		}
+		return {
+			payout,
+			settledCommissionIds: claimedCommissions.map((c) => c.id).filter((id) => !!id),
+			settledAdjustmentIds: claimedAdjustments.map((a) => a.id).filter((id) => !!id)
+		};
+	}
+	/**
+	* Complete a payout: flip the batch's settled commissions
+	* `payable → paid` FIRST, then `payout.complete(paymentReference)`
+	* (requires status `processing`). Ordering matters for recoverability —
+	* if a member save fails mid-loop the payout is still `processing`, so a
+	* retry finishes the remaining members (already-paid ones are skipped)
+	* and then finalizes; the terminal transition never strands `payable`
+	* members behind a `completed` payout. Adjustments carry no status —
+	* stamping `payoutId` at batch time already settled them.
+	*/
+	async completePayout(payoutId, paymentReference, now = /* @__PURE__ */ new Date()) {
+		const payout = await this.requirePayout(payoutId);
+		if (!payout.isProcessing()) throw new Error(`CommissionPayout ${payout.id ?? "<new>"}: cannot complete from status '${payout.status}'`);
+		if (!paymentReference) throw new Error(`CommissionPayout ${payout.id ?? "<new>"}: complete() requires a paymentReference`);
+		const members = await this.deps.commissions.findByPayout(payoutId);
+		for (const commission of members) if (commission.isPayable()) {
+			commission.markPaid(now);
+			await commission.save();
+		}
+		payout.complete(paymentReference, now);
+		await payout.save();
+		return payout;
+	}
+	/**
+	* Fail a payout (`approved | processing → failed`). The batch's rows stay
+	* stamped — after `resetFromFailed()` the SAME payout retries the SAME
+	* rows; releasing the rows to a different batch would double-pay them if
+	* the failed remittance later settled.
+	*/
+	async failPayout(payoutId, reason) {
+		const payout = await this.requirePayout(payoutId);
+		payout.fail(reason);
+		await payout.save();
+		return payout;
+	}
+	/**
+	* Unsettled adjustments for the earner/currency whose parent commission
+	* is earned/approved/payable/paid — the same eligibility rule the balance
+	* service applies, so batches settle exactly what balances report.
+	*/
+	async findEligibleUnsettledAdjustments(earnerId, currency) {
+		const unsettled = await this.deps.adjustments.findUnsettledByEarner(earnerId, currency);
+		if (unsettled.length === 0) return unsettled;
+		const parentIds = [...new Set(unsettled.map((a) => a.commissionId).filter(Boolean))];
+		const parents = await this.deps.commissions.listByIds(parentIds);
+		const parentStatusById = /* @__PURE__ */ new Map();
+		for (const parent of parents) if (parent.id) parentStatusById.set(parent.id, parent.status);
+		return unsettled.filter((adjustment) => {
+			const parentStatus = parentStatusById.get(adjustment.commissionId);
+			return parentStatus !== void 0 && ADJUSTMENT_SETTLEABLE_COMMISSION_STATUSES.includes(parentStatus);
+		});
+	}
+	async requirePayout(payoutId) {
+		const payout = await this.deps.payouts.get({ id: payoutId });
+		if (!payout) throw new Error(`CommissionPayoutService: payout '${payoutId}' not found`);
+		return payout;
+	}
+	/** `${earnerId}:${currency}:${YYYY-MM-DD of periodEnd}` — see the input doc. */
+	static defaultIdempotencyKey(earnerId, currency, periodEnd) {
+		return `${earnerId}:${currency}:${periodEnd.toISOString().slice(0, 10)}`;
+	}
+};
+//#endregion
+//#region src/commissions/services/CommissionSettlementService.ts
+var CommissionSettlementService = class CommissionSettlementService {
+	constructor(commissions) {
+		this.commissions = commissions;
+	}
+	commissions;
+	static async create(classOptions = {}) {
+		return new CommissionSettlementService(await CommissionCollection.create(classOptions));
+	}
+	/**
+	* Sweep the clearing window: every `pending` commission whose
+	* `clearingEndsAt` is `<= now` — or whose `clearingEndsAt` is `null`
+	* (null means NO clearing window applies, so the row is immediately
+	* sweepable) — transitions to `earned` and is saved.
+	*
+	* @returns The commissions that were marked earned by this sweep.
+	*/
+	async sweepClearing(now = /* @__PURE__ */ new Date()) {
+		const pending = await this.commissions.findByStatus("pending");
+		const swept = [];
+		for (const commission of pending) {
+			const clearingEndsAt = commission.clearingEndsAt;
+			if (clearingEndsAt !== null && clearingEndsAt.getTime() > now.getTime()) continue;
+			commission.markEarned(now);
+			await commission.save();
+			swept.push(commission);
+		}
+		return swept;
+	}
+	/**
+	* Approve `earned` commissions by id (`earned → approved`). Strict: a
+	* missing id or a commission in any other status throws — the caller
+	* names exact rows, so a mismatch is a bug worth surfacing, not skipping.
+	*/
+	async approveCommissions(ids, now = /* @__PURE__ */ new Date()) {
+		return await this.transitionByIds(ids, (commission) => {
+			commission.approve(now);
+		});
+	}
+	/**
+	* Release `approved` commissions to `payable` by id. Strict — see
+	* {@link approveCommissions}.
+	*/
+	async markPayable(ids, now = /* @__PURE__ */ new Date()) {
+		return await this.transitionByIds(ids, (commission) => {
+			commission.markPayable(now);
+		});
+	}
+	/**
+	* Convenience chain: advance each commission from wherever it currently
+	* sits up to `payable` (`pending → earned → approved → payable`), saving
+	* after EACH step — the save-time guard only admits single-step edges, so
+	* every intermediate state is persisted (each with its timestamp). Rows
+	* already `payable` or `paid` are returned untouched (idempotent). Note
+	* this deliberately bypasses the clearing window — it's the "operator
+	* says pay these now" path.
+	*/
+	async settleUpToPayable(ids, now = /* @__PURE__ */ new Date()) {
+		const updated = [];
+		for (const id of ids) {
+			const commission = await this.requireCommission(id);
+			if (commission.isPending()) {
+				commission.markEarned(now);
+				await commission.save();
+			}
+			if (commission.isEarned()) {
+				commission.approve(now);
+				await commission.save();
+			}
+			if (commission.isApproved()) {
+				commission.markPayable(now);
+				await commission.save();
+			}
+			updated.push(commission);
+		}
+		return updated;
+	}
+	async transitionByIds(ids, transition) {
+		const updated = [];
+		for (const id of ids) {
+			const commission = await this.requireCommission(id);
+			const statusBefore = commission.status;
+			transition(commission);
+			if (commission.status !== statusBefore) await commission.save();
+			updated.push(commission);
+		}
+		return updated;
+	}
+	async requireCommission(id) {
+		const commission = await this.commissions.get({ id });
+		if (!commission) throw new Error(`CommissionSettlementService: commission '${id}' not found`);
+		return commission;
+	}
+};
+//#endregion
+export { CommissionAdjustment as A, EARNING_EVENT_KINDS as C, CommissionCollection as D, CommissionPayout as E, Commission as O, EARNER_STATUSES as S, CommissionPayoutCollection as T, COMMISSION_ADJUSTMENT_KINDS as _, amountToCents as a, COMMISSION_PLAN_STATUSES as b, roundCents as c, EarnerCollection as d, Earner as f, ADJUSTMENT_SETTLEABLE_COMMISSION_STATUSES as g, validateCommissionPlanComponents as h, CommissionBalanceService as i, CommissionAdjustmentCollection as k, EarningEventCollection as l, CommissionPlan as m, CommissionPayoutService as n, calculateCommissionAmountCents as o, CommissionPlanCollection as p, CommissionCalculationService as r, centsToAmount as s, CommissionSettlementService as t, EarningEvent as u, COMMISSION_BASES as v, PAYOUT_METHODS as w, COMMISSION_STATUSES as x, COMMISSION_PAYOUT_STATUSES as y };
+
+//# sourceMappingURL=commissions-BCxqOKVM.js.map