@happyvertical/smrt-sales 0.57.23 → 0.57.24

package/dist/chunks/{commissions-D5x24d4o.js → commissions-nMBMa0DT.js}

@@ -534,7 +534,7 @@ var Commission = class extends SmrtObject {
 	async assertDedupeKeyNotTaken() {
 		if (!this.dedupeKey) return;
 		try {
-			const res = await this.db.query(`SELECT id FROM ${this.tableName} WHERE dedupe_key = $1`, this.dedupeKey);
+			const res = await this.db.query(`SELECT CAST(id AS VARCHAR) AS 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;
@@ -702,7 +702,81 @@ var CommissionCollection = class extends SmrtCollection {
 	}
 };
 //#endregion
-//#region src/commissions/models/CommissionPayout.ts
+//#region src/commissions/types.ts
+var EARNER_STATUSES = [
+	"pending",
+	"active",
+	"suspended"
+];
+var EARNER_SOURCE_ATTRIBUTION_STATUSES = ["active", "inactive"];
+var EARNER_KINDS = [
+	"person",
+	"organisation",
+	"treasury"
+];
+var PAYOUT_METHODS = [
+	"bank_transfer",
+	"check",
+	"paypal",
+	"credit",
+	"other",
+	"stripe_connect",
+	"crypto"
+];
+var PAYOUT_METHODS_REQUIRING_DESTINATION = ["stripe_connect", "crypto"];
+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",
+	"rejected"
+];
+var EARNING_EVENT_KINDS = [
+	"conversion",
+	"agreement_execution",
+	"invoice_payment",
+	"collected_revenue",
+	"recognized_margin",
+	"milestone"
+];
+var ADJUSTMENT_SETTLEABLE_COMMISSION_STATUSES = [
+	"earned",
+	"approved",
+	"payable",
+	"paid"
+];
+var WATERFALL_POOL_RESIDUAL_RULES = ["remainder_sink", "largest_remainder"];
+var WATERFALL_POOL_ZERO_WEIGHT_RULES = ["remainder_sink", "equal"];
+//#endregion
+//#region src/commissions/models/Earner.ts
 var __defProp$4 = Object.defineProperty;
 var __getOwnPropDesc$4 = Object.getOwnPropertyDescriptor;
 var __defNormalProp$4 = (obj, key, value) => key in obj ? __defProp$4(obj, key, {
@@ -718,6 +792,197 @@ var __decorateClass$4 = (decorators, target, key, kind) => {
 	return result;
 };
 var __publicField$4 = (obj, key, value) => __defNormalProp$4(obj, typeof key !== "symbol" ? key + "" : key, value);
+function validatePayoutDestination(destination) {
+	const value = destination;
+	if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error("Earner payoutDestination must be an object");
+	const requireText = (key) => {
+		if (typeof value[key] !== "string" || !value[key].trim()) throw new Error(`Earner payoutDestination.${key} is required`);
+	};
+	let allowed;
+	if (value.method === "stripe_connect") {
+		allowed = ["method", "connectedAccountId"];
+		requireText("connectedAccountId");
+		if (!/^acct_[A-Za-z0-9]+$/.test(value.connectedAccountId)) throw new Error("Earner payoutDestination.connectedAccountId must be a Stripe connected account id ('acct_…')");
+	} else if (value.method === "crypto") {
+		allowed = [
+			"method",
+			"network",
+			"asset",
+			"address",
+			"memo"
+		];
+		requireText("network");
+		requireText("asset");
+		requireText("address");
+		if (value.memo !== void 0 && typeof value.memo !== "string") throw new Error("Earner payoutDestination.memo must be a string");
+	} else throw new Error(`Earner payoutDestination.method must be one of ${PAYOUT_METHODS_REQUIRING_DESTINATION.join(", ")}`);
+	for (const key of Object.keys(value)) if (!allowed.includes(key)) throw new Error(`Earner payoutDestination has an unexpected field '${key}'`);
+}
+var Earner = class extends SmrtObject {
+	tenantId = null;
+	/**
+	* Party kind: `person` (default), `organisation`, or `treasury`.
+	* Organisation and treasury earners need no person Profile.
+	*/
+	kind = "person";
+	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";
+	/**
+	* Typed payout-rail descriptor as a JSON string (`{}` when none). Required
+	* for an active earner whose method is `stripe_connect` or `crypto`, and
+	* its `method` must match {@link payoutMethod}. Use
+	* {@link getPayoutDestination}/{@link setPayoutDestination}.
+	*/
+	payoutDestination = "{}";
+	/**
+	* 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.kind !== void 0) this.kind = options.kind;
+		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.payoutDestination !== void 0) this.payoutDestination = options.payoutDestination;
+		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 ?? {});
+	}
+	isOrganisation() {
+		return this.kind === "organisation";
+	}
+	isTreasury() {
+		return this.kind === "treasury";
+	}
+	/** Parse {@link payoutDestination}; `null` when none or unparseable. */
+	getPayoutDestination() {
+		try {
+			const parsed = JSON.parse(this.payoutDestination || "{}");
+			return parsed && typeof parsed === "object" && !Array.isArray(parsed) && Object.keys(parsed).length > 0 ? parsed : null;
+		} catch {
+			return null;
+		}
+	}
+	/**
+	* Validate and store a payout destination, and set {@link payoutMethod}
+	* to its method. `null` clears it (the method is left unchanged).
+	*/
+	setPayoutDestination(destination) {
+		if (destination === null) {
+			this.payoutDestination = "{}";
+			return;
+		}
+		validatePayoutDestination(destination);
+		this.payoutDestination = JSON.stringify(destination);
+		this.payoutMethod = destination.method;
+	}
+	/**
+	* Save with field guards: `kind` and `payoutMethod` must be known values,
+	* a stored destination must be valid and match `payoutMethod`, and an
+	* active Stripe Connect / crypto earner must have a destination.
+	*/
+	async save() {
+		this.assertPayoutTerms();
+		return await super.save();
+	}
+	assertPayoutTerms() {
+		const label = `Earner ${this.id ?? "<new>"}`;
+		if (!EARNER_KINDS.includes(this.kind)) throw new Error(`${label}: unknown kind '${this.kind}'`);
+		if (!PAYOUT_METHODS.includes(this.payoutMethod)) throw new Error(`${label}: unknown payoutMethod '${this.payoutMethod}'`);
+		let parsed;
+		try {
+			parsed = JSON.parse(this.payoutDestination || "{}");
+		} catch {
+			throw new Error(`${label}: payoutDestination must be valid JSON`);
+		}
+		const hasDestination = !!parsed && typeof parsed === "object" && !Array.isArray(parsed) && Object.keys(parsed).length > 0;
+		if (hasDestination) {
+			validatePayoutDestination(parsed);
+			if (parsed.method !== this.payoutMethod) throw new Error(`${label}: payoutDestination method '${parsed.method}' does not match payoutMethod '${this.payoutMethod}'`);
+		} else if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) throw new Error(`${label}: payoutDestination must be a JSON object`);
+		if (this.status === "active" && !hasDestination && PAYOUT_METHODS_REQUIRING_DESTINATION.includes(this.payoutMethod)) throw new Error(`${label}: an active ${this.payoutMethod} earner requires a payoutDestination`);
+	}
+};
+__publicField$4(Earner, "__smrtPackage__", "@happyvertical/smrt-sales");
+__decorateClass$4([tenantId({ nullable: true })], Earner.prototype, "tenantId", 2);
+__decorateClass$4([crossPackageRef("@happyvertical/smrt-profiles:Profile")], Earner.prototype, "profileId", 2);
+Earner = __decorateClass$4([TenantScoped({ mode: "optional" }), smrt({
+	api: { include: [
+		"list",
+		"get",
+		"create",
+		"update"
+	] },
+	mcp: { include: [
+		"list",
+		"get",
+		"create"
+	] },
+	cli: { skipApiCheck: true }
+})], Earner);
+//#endregion
+//#region src/commissions/models/CommissionPayout.ts
+var __defProp$3 = Object.defineProperty;
+var __getOwnPropDesc$3 = Object.getOwnPropertyDescriptor;
+var __defNormalProp$3 = (obj, key, value) => key in obj ? __defProp$3(obj, key, {
+	enumerable: true,
+	configurable: true,
+	writable: true,
+	value
+}) : obj[key] = value;
+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 __publicField$3 = (obj, key, value) => __defNormalProp$3(obj, typeof key !== "symbol" ? key + "" : key, value);
 var PAYOUT_STATUS_TRANSITIONS = {
 	pending: ["approved", "rejected"],
 	approved: [
@@ -755,6 +1020,13 @@ var CommissionPayout = class extends SmrtObject {
 	/** Delivery method for this batch (defaulted from the Earner). */
 	payoutMethod = "bank_transfer";
 	/**
+	* Routing descriptor captured at batch creation, never the live Earner's
+	* preference. Routing is immutable after the first save, including pending
+	* and failed/reset batches; reject and create a new batch to change it.
+	* Legacy/manual methods have no typed descriptor (`{}`).
+	*/
+	payoutDestination = "{}";
+	/**
 	* Lifecycle status — see the class doc. Mutate via {@link approve} /
 	* {@link markProcessing} / {@link complete} / {@link fail} /
 	* {@link resetFromFailed}.
@@ -802,6 +1074,7 @@ var CommissionPayout = class extends SmrtObject {
 		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.payoutDestination !== void 0) this.payoutDestination = options.payoutDestination;
 		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;
@@ -847,6 +1120,7 @@ var CommissionPayout = class extends SmrtObject {
 	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.validateRouting(true);
 		this.status = "approved";
 	}
 	/** `approved → processing`. Does NOT save — the caller saves. */
@@ -908,6 +1182,16 @@ ${memo}` : memo;
 		this.paymentReference = "";
 		this.paidAt = null;
 	}
+	/** Read the batch's validated routing snapshot, never a live Earner. */
+	getPayoutDestination() {
+		return this.validateRouting(false);
+	}
+	/** Set a descriptor before first persistence; save enforces routing freeze. */
+	setPayoutDestination(destination) {
+		if (destination) validatePayoutDestination(destination);
+		this.payoutDestination = JSON.stringify(destination ?? {});
+		if (destination) this.payoutMethod = destination.method;
+	}
 	/** Parse {@link metadata}; returns `{}` on empty/invalid JSON. */
 	getMetadata() {
 		if (!this.metadata) return {};
@@ -937,13 +1221,51 @@ ${memo}` : memo;
 	*/
 	async save() {
 		this.validateTotals();
+		await this.assertRoutingUnchanged();
 		const prior = await this.resolvePriorStatus();
+		this.validateRouting(prior !== this.status && [
+			"approved",
+			"processing",
+			"completed"
+		].includes(this.status));
 		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;
 	}
+	validateRouting(requireDestination) {
+		const label = `CommissionPayout ${this.id ?? "<new>"}`;
+		if (!PAYOUT_METHODS.includes(this.payoutMethod)) throw new Error(`${label}: unknown payoutMethod '${this.payoutMethod}'`);
+		let parsed;
+		try {
+			parsed = JSON.parse(this.payoutDestination);
+		} catch {
+			throw new Error(`${label}: payoutDestination must be valid JSON`);
+		}
+		if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) throw new Error(`${label}: payoutDestination must be a JSON object`);
+		if (Object.keys(parsed).length > 0) {
+			validatePayoutDestination(parsed);
+			const destination = parsed;
+			if (destination.method !== this.payoutMethod) throw new Error(`${label}: payoutDestination method does not match payoutMethod`);
+			return destination;
+		}
+		if (requireDestination && PAYOUT_METHODS_REQUIRING_DESTINATION.includes(this.payoutMethod)) throw new Error(`${label}: ${this.payoutMethod} requires a payoutDestination snapshot; reject and recreate the batch`);
+		return null;
+	}
+	/** Authoritative read also closes blind-id and natural-key upsert doors. */
+	async assertRoutingUnchanged() {
+		const { rows } = await this.db.query(`SELECT CAST(id AS VARCHAR) AS id, payout_method, payout_destination FROM ${this.tableName} WHERE id = ? OR idempotency_key = ?`, this.id ?? null, this.idempotencyKey || null);
+		for (const row of rows) {
+			if (row.id !== this.id) throw new Error("CommissionPayout: existing batch routing is immutable; reuse its idempotency key through the payout service");
+			const priorDestination = String(row.payout_destination ?? "{}");
+			const canonical = (raw) => {
+				const parsed = JSON.parse(raw);
+				return JSON.stringify(Object.entries(parsed).sort(([a], [b]) => a.localeCompare(b)));
+			};
+			if (row.payout_method !== this.payoutMethod || canonical(priorDestination) !== canonical(this.payoutDestination)) throw new Error("CommissionPayout: routing is immutable; reject and recreate the batch");
+		}
+	}
 	/** Throws when the totals invariant doesn't hold. */
 	validateTotals() {
 		for (const [name, value] of [
@@ -976,13 +1298,13 @@ ${memo}` : memo;
 		return null;
 	}
 };
-__publicField$4(CommissionPayout, "__smrtPackage__", "@happyvertical/smrt-sales");
-__decorateClass$4([tenantId({ nullable: true })], CommissionPayout.prototype, "tenantId", 2);
-__decorateClass$4([foreignKey("Earner", { required: true })], CommissionPayout.prototype, "earnerId", 2);
-__decorateClass$4([crossPackageRef("@happyvertical/smrt-commerce:Invoice")], CommissionPayout.prototype, "invoiceId", 2);
-__decorateClass$4([field({ required: true })], CommissionPayout.prototype, "idempotencyKey", 2);
-__decorateClass$4([field({ indexed: true })], CommissionPayout.prototype, "sourceId", 2);
-CommissionPayout = __decorateClass$4([TenantScoped({ mode: "optional" }), smrt({
+__publicField$3(CommissionPayout, "__smrtPackage__", "@happyvertical/smrt-sales");
+__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);
+__decorateClass$3([field({ indexed: true })], CommissionPayout.prototype, "sourceId", 2);
+CommissionPayout = __decorateClass$3([TenantScoped({ mode: "optional" }), smrt({
 	conflictColumns: ["idempotency_key"],
 	api: { include: ["list", "get"] },
 	mcp: { include: ["list", "get"] },
@@ -992,135 +1314,68 @@ CommissionPayout = __decorateClass$4([TenantScoped({ mode: "optional" }), smrt({
 //#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;
-	}
-	/**
-	* One page of payouts carrying the derived single-source stamp for
-	* `(sourceKind, sourceId)`, newest first with a deterministic id
-	* tiebreak. This is the RAW indexed page — stamped rows only, membership
-	* unverified. Consumers want
-	* `CommissionPayoutService.getSourcePayoutHistory`, which re-verifies
-	* each page's membership and fails closed on rows the stamp alone cannot
-	* prove.
-	*/
-	async findBySource(sourceKind, sourceId, page) {
-		if (!sourceKind || !sourceId) return [];
-		return await this.list({
-			where: {
-				sourceKind,
-				sourceId
-			},
-			orderBy: ["created_at DESC", "id DESC"],
-			limit: page.limit,
-			offset: page.offset
-		});
-	}
-	/**
-	* Σ 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);
+	/** Persist the first routing snapshot atomically; a duplicate key must not upsert it. */
+	async create(options, context) {
+		return super.create({
+			...options,
+			_insertOnly: true
+		}, context);
 	}
-};
-//#endregion
-//#region src/commissions/types.ts
-var EARNER_STATUSES = [
-	"pending",
-	"active",
-	"suspended"
-];
-var EARNER_SOURCE_ATTRIBUTION_STATUSES = ["active", "inactive"];
-var EARNER_KINDS = [
-	"person",
-	"organisation",
-	"treasury"
-];
-var PAYOUT_METHODS = [
-	"bank_transfer",
-	"check",
-	"paypal",
-	"credit",
-	"other",
-	"stripe_connect",
-	"crypto"
-];
-var PAYOUT_METHODS_REQUIRING_DESTINATION = ["stripe_connect", "crypto"];
-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",
-	"rejected"
-];
-var EARNING_EVENT_KINDS = [
-	"conversion",
-	"agreement_execution",
-	"invoice_payment",
-	"collected_revenue",
-	"recognized_margin",
-	"milestone"
-];
-var ADJUSTMENT_SETTLEABLE_COMMISSION_STATUSES = [
-	"earned",
-	"approved",
-	"payable",
-	"paid"
-];
-var WATERFALL_POOL_RESIDUAL_RULES = ["remainder_sink", "largest_remainder"];
-var WATERFALL_POOL_ZERO_WEIGHT_RULES = ["remainder_sink", "equal"];
+	/** 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;
+	}
+	/**
+	* One page of payouts carrying the derived single-source stamp for
+	* `(sourceKind, sourceId)`, newest first with a deterministic id
+	* tiebreak. This is the RAW indexed page — stamped rows only, membership
+	* unverified. Consumers want
+	* `CommissionPayoutService.getSourcePayoutHistory`, which re-verifies
+	* each page's membership and fails closed on rows the stamp alone cannot
+	* prove.
+	*/
+	async findBySource(sourceKind, sourceId, page) {
+		if (!sourceKind || !sourceId) return [];
+		return await this.list({
+			where: {
+				sourceKind,
+				sourceId
+			},
+			orderBy: ["created_at DESC", "id DESC"],
+			limit: page.limit,
+			offset: page.offset
+		});
+	}
+	/**
+	* Σ 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/services/WaterfallCalculationService.ts
 var WaterfallRecipientResolverRegistry = class {
@@ -1616,21 +1871,21 @@ function assertWholeNonNegative(value, label) {
 }
 //#endregion
 //#region src/commissions/models/CommissionPlan.ts
-var __defProp$3 = Object.defineProperty;
-var __getOwnPropDesc$3 = Object.getOwnPropertyDescriptor;
-var __defNormalProp$3 = (obj, key, value) => key in obj ? __defProp$3(obj, key, {
+var __defProp$2 = Object.defineProperty;
+var __getOwnPropDesc$2 = Object.getOwnPropertyDescriptor;
+var __defNormalProp$2 = (obj, key, value) => key in obj ? __defProp$2(obj, key, {
 	enumerable: true,
 	configurable: true,
 	writable: true,
 	value
 }) : obj[key] = value;
-var __decorateClass$3 = (decorators, target, key, kind) => {
-	var result = kind > 1 ? void 0 : kind ? __getOwnPropDesc$3(target, key) : target;
+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$3(target, key, result);
+	if (kind && result) __defProp$2(target, key, result);
 	return result;
 };
-var __publicField$3 = (obj, key, value) => __defNormalProp$3(obj, typeof key !== "symbol" ? key + "" : key, value);
+var __publicField$2 = (obj, key, value) => __defNormalProp$2(obj, typeof key !== "symbol" ? key + "" : key, value);
 var PLAN_STATUS_TRANSITIONS = {
 	draft: ["active", "retired"],
 	active: ["superseded", "retired"],
@@ -1971,10 +2226,10 @@ var CommissionPlan = class extends SmrtObject {
 		return null;
 	}
 };
-__publicField$3(CommissionPlan, "__smrtPackage__", "@happyvertical/smrt-sales");
-__decorateClass$3([tenantId({ nullable: true })], CommissionPlan.prototype, "tenantId", 2);
-__decorateClass$3([field({ required: true })], CommissionPlan.prototype, "planKey", 2);
-CommissionPlan = __decorateClass$3([TenantScoped({ mode: "optional" }), smrt({
+__publicField$2(CommissionPlan, "__smrtPackage__", "@happyvertical/smrt-sales");
+__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",
@@ -2086,197 +2341,6 @@ var CommissionPlanCollection = class extends SmrtCollection {
 	}
 };
 //#endregion
-//#region src/commissions/models/Earner.ts
-var __defProp$2 = Object.defineProperty;
-var __getOwnPropDesc$2 = Object.getOwnPropertyDescriptor;
-var __defNormalProp$2 = (obj, key, value) => key in obj ? __defProp$2(obj, key, {
-	enumerable: true,
-	configurable: true,
-	writable: true,
-	value
-}) : obj[key] = value;
-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 __publicField$2 = (obj, key, value) => __defNormalProp$2(obj, typeof key !== "symbol" ? key + "" : key, value);
-function validatePayoutDestination(destination) {
-	const value = destination;
-	if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error("Earner payoutDestination must be an object");
-	const requireText = (key) => {
-		if (typeof value[key] !== "string" || !value[key].trim()) throw new Error(`Earner payoutDestination.${key} is required`);
-	};
-	let allowed;
-	if (value.method === "stripe_connect") {
-		allowed = ["method", "connectedAccountId"];
-		requireText("connectedAccountId");
-		if (!/^acct_[A-Za-z0-9]+$/.test(value.connectedAccountId)) throw new Error("Earner payoutDestination.connectedAccountId must be a Stripe connected account id ('acct_…')");
-	} else if (value.method === "crypto") {
-		allowed = [
-			"method",
-			"network",
-			"asset",
-			"address",
-			"memo"
-		];
-		requireText("network");
-		requireText("asset");
-		requireText("address");
-		if (value.memo !== void 0 && typeof value.memo !== "string") throw new Error("Earner payoutDestination.memo must be a string");
-	} else throw new Error(`Earner payoutDestination.method must be one of ${PAYOUT_METHODS_REQUIRING_DESTINATION.join(", ")}`);
-	for (const key of Object.keys(value)) if (!allowed.includes(key)) throw new Error(`Earner payoutDestination has an unexpected field '${key}'`);
-}
-var Earner = class extends SmrtObject {
-	tenantId = null;
-	/**
-	* Party kind: `person` (default), `organisation`, or `treasury`.
-	* Organisation and treasury earners need no person Profile.
-	*/
-	kind = "person";
-	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";
-	/**
-	* Typed payout-rail descriptor as a JSON string (`{}` when none). Required
-	* for an active earner whose method is `stripe_connect` or `crypto`, and
-	* its `method` must match {@link payoutMethod}. Use
-	* {@link getPayoutDestination}/{@link setPayoutDestination}.
-	*/
-	payoutDestination = "{}";
-	/**
-	* 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.kind !== void 0) this.kind = options.kind;
-		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.payoutDestination !== void 0) this.payoutDestination = options.payoutDestination;
-		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 ?? {});
-	}
-	isOrganisation() {
-		return this.kind === "organisation";
-	}
-	isTreasury() {
-		return this.kind === "treasury";
-	}
-	/** Parse {@link payoutDestination}; `null` when none or unparseable. */
-	getPayoutDestination() {
-		try {
-			const parsed = JSON.parse(this.payoutDestination || "{}");
-			return parsed && typeof parsed === "object" && !Array.isArray(parsed) && Object.keys(parsed).length > 0 ? parsed : null;
-		} catch {
-			return null;
-		}
-	}
-	/**
-	* Validate and store a payout destination, and set {@link payoutMethod}
-	* to its method. `null` clears it (the method is left unchanged).
-	*/
-	setPayoutDestination(destination) {
-		if (destination === null) {
-			this.payoutDestination = "{}";
-			return;
-		}
-		validatePayoutDestination(destination);
-		this.payoutDestination = JSON.stringify(destination);
-		this.payoutMethod = destination.method;
-	}
-	/**
-	* Save with field guards: `kind` and `payoutMethod` must be known values,
-	* a stored destination must be valid and match `payoutMethod`, and an
-	* active Stripe Connect / crypto earner must have a destination.
-	*/
-	async save() {
-		this.assertPayoutTerms();
-		return await super.save();
-	}
-	assertPayoutTerms() {
-		const label = `Earner ${this.id ?? "<new>"}`;
-		if (!EARNER_KINDS.includes(this.kind)) throw new Error(`${label}: unknown kind '${this.kind}'`);
-		if (!PAYOUT_METHODS.includes(this.payoutMethod)) throw new Error(`${label}: unknown payoutMethod '${this.payoutMethod}'`);
-		let parsed;
-		try {
-			parsed = JSON.parse(this.payoutDestination || "{}");
-		} catch {
-			throw new Error(`${label}: payoutDestination must be valid JSON`);
-		}
-		const hasDestination = !!parsed && typeof parsed === "object" && !Array.isArray(parsed) && Object.keys(parsed).length > 0;
-		if (hasDestination) {
-			validatePayoutDestination(parsed);
-			if (parsed.method !== this.payoutMethod) throw new Error(`${label}: payoutDestination method '${parsed.method}' does not match payoutMethod '${this.payoutMethod}'`);
-		} else if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) throw new Error(`${label}: payoutDestination must be a JSON object`);
-		if (this.status === "active" && !hasDestination && PAYOUT_METHODS_REQUIRING_DESTINATION.includes(this.payoutMethod)) throw new Error(`${label}: an active ${this.payoutMethod} earner requires a payoutDestination`);
-	}
-};
-__publicField$2(Earner, "__smrtPackage__", "@happyvertical/smrt-sales");
-__decorateClass$2([tenantId({ nullable: true })], Earner.prototype, "tenantId", 2);
-__decorateClass$2([crossPackageRef("@happyvertical/smrt-profiles:Profile")], Earner.prototype, "profileId", 2);
-Earner = __decorateClass$2([TenantScoped({ mode: "optional" }), smrt({
-	api: { include: [
-		"list",
-		"get",
-		"create",
-		"update"
-	] },
-	mcp: { include: [
-		"list",
-		"get",
-		"create"
-	] },
-	cli: { skipApiCheck: true }
-})], Earner);
-//#endregion
 //#region src/commissions/collections/EarnerCollection.ts
 var EarnerCollection = class extends SmrtCollection {
 	static _itemClass = Earner;
@@ -3322,20 +3386,20 @@ var CommissionPayoutService = class CommissionPayoutService {
 			settledCommissionIds: [],
 			settledAdjustmentIds: []
 		};
-		const minted = await this.deps.payouts.create({
+		const payout = await this.deps.payouts.create({
 			tenantId: earner.tenantId,
 			earnerId: input.earnerId,
 			currency: input.currency,
 			periodStart: input.periodStart ?? null,
 			periodEnd: input.periodEnd ?? null,
 			payoutMethod,
+			payoutDestination: JSON.stringify(earner.getPayoutDestination()?.method === payoutMethod ? earner.getPayoutDestination() : {}),
 			status: "pending",
 			commissionTotalCents,
 			adjustmentTotalCents,
 			totalAmountCents: netTotalCents,
 			idempotencyKey
 		});
-		const payout = await this.deps.payouts.findByIdempotencyKey(idempotencyKey) ?? minted;
 		return {
 			...await this.claimAndReconcile(payout, input),
 			created: true
@@ -3429,6 +3493,8 @@ var CommissionPayoutService = class CommissionPayoutService {
 		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 destination = payout.getPayoutDestination();
+		if (PAYOUT_METHODS_REQUIRING_DESTINATION.includes(payout.payoutMethod) && !destination) throw new Error(`CommissionPayout ${payout.id ?? "<new>"}: ${payout.payoutMethod} requires a payoutDestination snapshot; reject and recreate the batch`);
 		const members = await this.deps.commissions.findByPayout(payoutId);
 		for (const commission of members) if (commission.isPayable()) {
 			commission.markPaid(now);
@@ -3817,7 +3883,7 @@ var CommissionPayoutService = class CommissionPayoutService {
 		const ids = payoutIds.filter((id) => CommissionPayoutService.UUID_RE.test(id));
 		if (ids.length === 0) return counts;
 		const placeholders = ids.map((_, i) => `$${i + 1}`).join(", ");
-		const res = await db.query(`SELECT payout_id, COUNT(*) AS row_count FROM ${table} WHERE payout_id IN (${placeholders}) GROUP BY payout_id`, ...ids);
+		const res = await db.query(`SELECT CAST(payout_id AS VARCHAR) AS payout_id, COUNT(*) AS row_count FROM ${table} WHERE payout_id IN (${placeholders}) GROUP BY payout_id`, ...ids);
 		const rows = Array.isArray(res) ? res : res.rows ?? [];
 		for (const row of rows) counts.set(String(row.payout_id), Number(row.row_count));
 		return counts;
@@ -4336,6 +4402,6 @@ var EarnerAttributionService = class EarnerAttributionService {
 	}
 };
 //#endregion
-export { COMMISSION_BASES as A, WATERFALL_POOL_RESIDUAL_RULES as B, WaterfallRecipientResolverRegistry as C, validateWaterfallPlan as D, prepareWaterfallPools as E, EARNER_SOURCE_ATTRIBUTION_STATUSES as F, Commission as G, CommissionPayoutCollection as H, EARNER_STATUSES as I, CommissionAdjustmentCollection as J, CommissionAdjustmentOperationCollection as K, EARNING_EVENT_KINDS as L, COMMISSION_PLAN_STATUSES as M, COMMISSION_STATUSES as N, ADJUSTMENT_SETTLEABLE_COMMISSION_STATUSES as O, EARNER_KINDS as P, PAYOUT_METHODS as R, validateCommissionPlanComponents as S, calculateWaterfallWithPools as T, CommissionPayout as U, WATERFALL_POOL_ZERO_WEIGHT_RULES as V, CommissionCollection as W, CommissionAdjustment as Y, EarnerCollection as _, CommissionBalanceService as a, CommissionPlanCollection as b, CommissionAdjustmentValidationError as c, centsToAmount as d, roundCents as f, EarnerSourceAttribution as g, EarnerSourceAttributionCollection as h, CommissionCalculationService as i, COMMISSION_PAYOUT_STATUSES as j, COMMISSION_ADJUSTMENT_KINDS as k, amountToCents as l, EarningEvent as m, CommissionSettlementService as n, CommissionAdjustmentReplayConflictError as o, EarningEventCollection as p, CommissionAdjustmentOperation as q, CommissionPayoutService as r, CommissionAdjustmentService as s, EarnerAttributionService as t, calculateCommissionAmountCents as u, Earner as v, calculateWaterfall as w, CommissionPlan as x, validatePayoutDestination as y, PAYOUT_METHODS_REQUIRING_DESTINATION as z };
+export { ADJUSTMENT_SETTLEABLE_COMMISSION_STATUSES as A, PAYOUT_METHODS as B, calculateWaterfallWithPools as C, CommissionPayout as D, CommissionPayoutCollection as E, COMMISSION_STATUSES as F, Commission as G, WATERFALL_POOL_RESIDUAL_RULES as H, EARNER_KINDS as I, CommissionAdjustmentCollection as J, CommissionAdjustmentOperationCollection as K, EARNER_SOURCE_ATTRIBUTION_STATUSES as L, COMMISSION_BASES as M, COMMISSION_PAYOUT_STATUSES as N, Earner as O, COMMISSION_PLAN_STATUSES as P, EARNER_STATUSES as R, calculateWaterfall as S, validateWaterfallPlan as T, WATERFALL_POOL_ZERO_WEIGHT_RULES as U, PAYOUT_METHODS_REQUIRING_DESTINATION as V, CommissionCollection as W, CommissionAdjustment as Y, EarnerCollection as _, CommissionBalanceService as a, validateCommissionPlanComponents as b, CommissionAdjustmentValidationError as c, centsToAmount as d, roundCents as f, EarnerSourceAttribution as g, EarnerSourceAttributionCollection as h, CommissionCalculationService as i, COMMISSION_ADJUSTMENT_KINDS as j, validatePayoutDestination as k, amountToCents as l, EarningEvent as m, CommissionSettlementService as n, CommissionAdjustmentReplayConflictError as o, EarningEventCollection as p, CommissionAdjustmentOperation as q, CommissionPayoutService as r, CommissionAdjustmentService as s, EarnerAttributionService as t, calculateCommissionAmountCents as u, CommissionPlanCollection as v, prepareWaterfallPools as w, WaterfallRecipientResolverRegistry as x, CommissionPlan as y, EARNING_EVENT_KINDS as z };
 
-//# sourceMappingURL=commissions-D5x24d4o.js.map
+//# sourceMappingURL=commissions-nMBMa0DT.js.map