@classytic/loyalty 0.7.0 → 0.10.0

package/dist/{repositories-DErtHQou.mjs → repositories-ER68JmUo.mjs}

@@ -1,9 +1,12 @@
-import { n as createEvent, t as LoyaltyEvents } from "./loyalty-events-DXirolM_.mjs";
+import { d as STAMP_PROGRAM_STATUSES, r as EARN_SOURCES, u as STAMP_EARN_UNITS } from "./constants-DfrENxFG.mjs";
+import { isRuleInSchedule } from "./domain/rule-schedule.mjs";
+import { n as createEvent, t as LoyaltyEvents } from "./loyalty-events-j29B66YW.mjs";
 import { Repository, appendOnlyPlugin, multiTenantPlugin } from "@classytic/mongokit";
-import { localTimeParts } from "@classytic/primitives/timezone";
+import { civilDateOf, localTimeParts } from "@classytic/primitives/timezone";
 import { addDays, isoWeekday } from "@classytic/primitives/calendar";
 import { randomBytes } from "node:crypto";
 import { throwIfAborted } from "@classytic/repo-core/repository";
+import { z } from "zod";
 //#region src/domain/errors/base.ts
 /**
 * Base for every loyalty throwable. Implements `HttpError` from
@@ -274,6 +277,7 @@ function validateOrderTotal(total) {
 var EarningRuleRepository = class extends Repository {
 	memberRepo;
 	txRepo;
+	tierRepo;
 	config;
 	constructor(model, plugins = []) {
 		super(model, plugins);
@@ -340,6 +344,7 @@ var EarningRuleRepository = class extends Repository {
 				memberId: input.memberId,
 				points,
 				description: `Earning rule: ${rule.name}`,
+				source: "order",
 				referenceType: "order",
 				referenceId: input.orderId,
 				earningRuleId: rule._id,
@@ -353,12 +358,58 @@ var EarningRuleRepository = class extends Repository {
 			});
 			transactions.push(tx);
 		}
+		const tierBonus = await this.tierMultiplierBonus(member, input.orderId, accumulatedPoints, ctx, tc);
+		if (tierBonus) {
+			accumulatedPoints += tierBonus.points;
+			breakdown.push(tierBonus.breakdown);
+			transactions.push(tierBonus.tx);
+		}
 		return {
 			totalPoints: accumulatedPoints,
 			breakdown,
 			transactions
 		};
 	}
+	/**
+	* The member's tier benefit `benefits.pointsMultiplier`: above 1, the order earns
+	* (m − 1) × what the rules awarded, as its own ledger row. Keyed on the order
+	* alone, so a retry after a tier change cannot award a second bonus.
+	*/
+	async tierMultiplierBonus(member, orderId, rulePoints, ctx, tc) {
+		const tierName = member.tierOverride ?? member.tier;
+		if (!tierName || rulePoints <= 0) return null;
+		const multiplier = (await this.tierRepo.getByQuery({
+			programId: member.programId,
+			name: tierName
+		}, {
+			throwOnNotFound: false,
+			...tc
+		}))?.benefits?.pointsMultiplier ?? 0;
+		const points = multiplier > 1 ? Math.floor(rulePoints * (multiplier - 1)) : 0;
+		if (points <= 0) return null;
+		const tx = await this.txRepo.earnPoints({
+			memberId: String(member._id),
+			points,
+			description: `Tier bonus: ${tierName} ×${multiplier}`,
+			source: "order",
+			referenceType: "order",
+			referenceId: orderId,
+			idempotencyKey: `${orderId}:tier-multiplier`,
+			metadata: {
+				tier: tierName,
+				multiplier
+			}
+		}, ctx);
+		return {
+			points,
+			breakdown: {
+				ruleId: `tier:${tierName}`,
+				ruleName: `Tier ${tierName} ×${multiplier}`,
+				points
+			},
+			tx
+		};
+	}
 	async evaluateAction(input, ctx) {
 		assertTenantContext(ctx, this.config.tenant);
 		const tenantId = getTenantValue(ctx, this.config.tenant);
@@ -382,6 +433,7 @@ var EarningRuleRepository = class extends Repository {
 				memberId: input.memberId,
 				points,
 				description: `Action: ${input.action} (${rule.name})`,
+				source: "action",
 				referenceType: "action",
 				earningRuleId: rule._id,
 				...input.referenceId !== void 0 ? {
@@ -415,10 +467,7 @@ var EarningRuleRepository = class extends Repository {
 			const memberTier = member.tierOverride ?? member.tier;
 			if (!memberTier || !conditions.tiers.includes(memberTier)) return false;
 		}
-		if (conditions.dateRange) {
-			if (conditions.dateRange.start && now < conditions.dateRange.start) return false;
-			if (conditions.dateRange.end && now > conditions.dateRange.end) return false;
-		}
+		if (!isRuleInSchedule(rule, now)) return false;
 		if (conditions.dayOfWeek && conditions.dayOfWeek.length > 0) {
 			if (!conditions.dayOfWeek.includes(this.weekday(now))) return false;
 		}
@@ -603,6 +652,7 @@ var MemberRepository = class extends Repository {
 	outbox;
 	notifications = null;
 	config;
+	tierRepo;
 	/** Session-bound outbox save + transport publish (PACKAGE_RULES §5.5 + P8). */
 	async _dispatch(event, ctx) {
 		await dispatchLoyaltyEvent({
@@ -672,14 +722,16 @@ var MemberRepository = class extends Repository {
 		})) throw new MemberAlreadyEnrolledError(input.externalId);
 		const referralCode = generateReferralCode(this.config.referral.codeLength);
 		const now = /* @__PURE__ */ new Date();
+		const programId = input.programId ?? this.config.programId;
+		const tier = input.tier ?? await this.tierRepo.qualifiedTierName(programId, 0, tc);
 		const data = {
-			programId: input.programId ?? this.config.programId,
+			programId,
 			externalId: input.externalId,
 			externalType: input.externalType,
 			status: "active",
 			cardId: input.cardId,
 			referralCode,
-			tier: input.tier ?? null,
+			tier,
 			tierOverride: null,
 			balance: {
 				current: 0,
@@ -790,7 +842,35 @@ var MemberRepository = class extends Repository {
 	}
 };
 //#endregion
+//#region src/utils/mongo-errors.ts
+/** E11000 across the raw driver + mongokit wrapper shapes. */
+function isDuplicateKey(err) {
+	if (typeof err !== "object" || err === null) return false;
+	const e = err;
+	if (e.code === 11e3) return true;
+	if (e.status === 409) return true;
+	if (e.cause !== void 0) return isDuplicateKey(e.cause);
+	return false;
+}
+/**
+* Transient MongoDB WriteConflict — surfaces under concurrent webhook
+* replay when two transactions try to update the same member balance.
+* With an idempotency key present, the winning insert is the source of
+* truth; losers are short-circuited to its doc rather than leaking the
+* raw driver error.
+*/
+function isWriteConflict(err) {
+	if (typeof err !== "object" || err === null) return false;
+	const e = err;
+	if (e.code === 112 || e.codeName === "WriteConflict") return true;
+	if (Array.isArray(e.errorLabels) && e.errorLabels.includes("TransientTransactionError")) return true;
+	if (typeof e.message === "string" && /write conflict/i.test(e.message)) return true;
+	if (e.cause !== void 0) return isWriteConflict(e.cause);
+	return false;
+}
+//#endregion
 //#region src/repositories/point-transaction.repository.ts
+const EXPIRY_PAGE = 100;
 var PointTransactionRepository = class extends Repository {
 	memberRepo;
 	events;
@@ -798,9 +878,15 @@ var PointTransactionRepository = class extends Repository {
 	notifications = null;
 	unitOfWork;
 	config;
+	program;
 	constructor(model, plugins = []) {
 		super(model, [...plugins, appendOnlyPlugin()]);
 	}
+	/** `now + expiry.defaultDays` when the program expires points, else none. */
+	defaultExpiry(program) {
+		const { enabled, defaultDays } = program.expiry;
+		return enabled && defaultDays ? new Date(Date.now() + defaultDays * 864e5) : void 0;
+	}
 	/** Session-bound outbox save + transport publish (PACKAGE_RULES §5.5 + P8). */
 	async _dispatch(event, ctx) {
 		await dispatchLoyaltyEvent({
@@ -829,6 +915,7 @@ var PointTransactionRepository = class extends Repository {
 	}
 	async earnPoints(input, ctx) {
 		validatePositivePoints(input.points);
+		if (!EARN_SOURCES.includes(input.source)) throw new ValidationError(`Unknown earn source '${String(input.source)}' — expected one of ${EARN_SOURCES.join(", ")}`);
 		assertTenantContext(ctx, this.config.tenant);
 		const tenantId = getTenantValue(ctx, this.config.tenant);
 		const tc = tenantCtx(this.config.tenant, tenantId);
@@ -840,6 +927,8 @@ var PointTransactionRepository = class extends Repository {
 			if (existing) return existing;
 		}
 		const member = await this.memberRepo.requireActiveMember(input.memberId, tc);
+		const program = await this.program();
+		const expiresAt = input.expiresAt ?? this.defaultExpiry(program);
 		try {
 			let payload;
 			const tx = await runLoyaltyUnit(this.unitOfWork, this._dispatchDeps, ctx, async (txCtx) => {
@@ -863,12 +952,14 @@ var PointTransactionRepository = class extends Repository {
 					programId: member.programId,
 					type: "earn",
 					points: input.points,
+					source: input.source,
+					pointValueMinor: program.pointValueMinor,
 					balanceAfter: updatedMember.balance.current,
 					description: input.description,
 					referenceType: input.referenceType,
 					referenceId: input.referenceId,
 					earningRuleId: input.earningRuleId,
-					expiresAt: input.expiresAt,
+					expiresAt,
 					actorId: ctx.actorId,
 					...input.metadata ? { metadata: input.metadata } : {}
 				};
@@ -882,6 +973,8 @@ var PointTransactionRepository = class extends Repository {
 					externalId: member.externalId,
 					externalType: member.externalType,
 					points: input.points,
+					source: input.source,
+					pointValueMinor: program.pointValueMinor,
 					balanceAfter: created.balanceAfter,
 					transactionId: created._id,
 					referenceType: input.referenceType,
@@ -942,6 +1035,7 @@ var PointTransactionRepository = class extends Repository {
 				const input = {
 					memberId: row.memberId,
 					points: row.points,
+					source: "campaign",
 					description: source.description,
 					idempotencyKey: `${source.eventId}:${row.memberId}`,
 					metadata: {
@@ -998,9 +1092,10 @@ var PointTransactionRepository = class extends Repository {
 				throwOnNotFound: false,
 				...tc
 			});
-			if (existing) return existing;
+			if (existing) return sameAdjustment(existing, input);
 		}
 		const member = await this.memberRepo.requireActiveMember(input.memberId, tc);
+		const { pointValueMinor } = await this.program();
 		if (input.points < 0 && member.balance.current < Math.abs(input.points)) throw new InsufficientPointsError(member.balance.current, Math.abs(input.points));
 		let payload;
 		const tx = await runLoyaltyUnit(this.unitOfWork, this._dispatchDeps, ctx, async (txCtx) => {
@@ -1010,7 +1105,7 @@ var PointTransactionRepository = class extends Repository {
 					throwOnNotFound: false,
 					...tc
 				});
-				if (dup) return dup;
+				if (dup) return sameAdjustment(dup, input);
 			}
 			const balanceUpdate = { current: input.points };
 			if (input.points > 0) balanceUpdate.lifetime = input.points;
@@ -1024,6 +1119,7 @@ var PointTransactionRepository = class extends Repository {
 				programId: member.programId,
 				type: "adjust",
 				points: input.points,
+				pointValueMinor,
 				balanceAfter: updatedMember.balance.current,
 				description: input.description,
 				referenceType: input.referenceType,
@@ -1043,6 +1139,7 @@ var PointTransactionRepository = class extends Repository {
 				memberId: member._id,
 				externalId: member.externalId,
 				points: input.points,
+				pointValueMinor,
 				balanceAfter: created.balanceAfter,
 				transactionId: created._id,
 				description: input.description
@@ -1056,65 +1153,244 @@ var PointTransactionRepository = class extends Repository {
 		if (payload) this.notifications?.notify(LoyaltyEvents.POINTS_ADJUSTED, { ...payload });
 		return tx;
 	}
-	async processExpirations(ctx) {
+	/**
+	* Take back points earned on a reference (an order) once it is refunded or canceled.
+	*
+	* CONVERGES BY STATE. The caller says how much of the purchase is undone
+	* (`fraction`, 1 = all); this reverses `floor(earned × fraction)` minus what earlier
+	* reversals already claimed. A replayed event reverses nothing extra, and the
+	* idempotency key is derived from the target so concurrent callers collide on the
+	* unique index instead of both debiting.
+	*
+	* A member cannot go below zero: points already spent are reported as `shortfall`
+	* on the row and the event. `lifetime` drops by the full claim — tier status must
+	* not keep credit for a sale that was undone.
+	*/
+	async reverseEarned(input, ctx) {
+		if (!(input.fraction >= 0 && input.fraction <= 1)) throw new ValidationError(`fraction must be between 0 and 1, got ${input.fraction}`);
+		if (!input.referenceId) throw new ValidationError("referenceId is required");
 		assertTenantContext(ctx, this.config.tenant);
-		const tenantId = getTenantValue(ctx, this.config.tenant);
-		const tc = tenantCtx(this.config.tenant, tenantId);
-		const now = /* @__PURE__ */ new Date();
-		const expiredTxs = await this.findAll({
-			expiresAt: { $lte: now },
-			expiredAt: { $exists: false }
-		}, {
-			sort: { createdAt: 1 },
-			limit: 100,
-			...tc
-		});
-		let totalExpired = 0;
-		let transactionCount = 0;
-		const affectedMemberIds = /* @__PURE__ */ new Set();
-		for (const tx of expiredTxs) {
-			throwIfAborted(ctx.signal);
-			const expiredAmount = await this.unitOfWork.withTransaction(async (session) => {
-				const member = await this.memberRepo.requireMember(tx.memberId, {
+		const tc = tenantCtx(this.config.tenant, getTenantValue(ctx, this.config.tenant));
+		const { pointValueMinor } = await this.program();
+		const results = [];
+		for (const [memberId, share] of await this.tallyReference(input, tc)) {
+			const target = Math.floor(share.earned * input.fraction);
+			const base = {
+				memberId,
+				earned: share.earned,
+				target,
+				alreadyClaimed: share.claimed
+			};
+			const delta = target - share.claimed;
+			results.push(delta > 0 ? {
+				...base,
+				...await this.claimBack({
+					...input,
+					memberId,
+					target,
+					delta,
+					pointValueMinor
+				}, ctx, tc)
+			} : {
+				...base,
+				claimed: 0,
+				collected: 0,
+				shortfall: 0,
+				transactionId: null
+			});
+		}
+		return results;
+	}
+	/** Per member: points earned on the reference, and points earlier reversals already claimed. */
+	async tallyReference(ref, tc) {
+		const rows = await this.findAll({
+			referenceType: ref.referenceType,
+			referenceId: ref.referenceId,
+			type: { $in: ["earn", "reverse"] }
+		}, tc);
+		const byMember = /* @__PURE__ */ new Map();
+		for (const row of rows) {
+			const acc = byMember.get(String(row.memberId)) ?? {
+				earned: 0,
+				claimed: 0
+			};
+			if (row.type === "earn") acc.earned += row.points;
+			else acc.claimed += Number(row.metadata?.claimed ?? 0);
+			byMember.set(String(row.memberId), acc);
+		}
+		return byMember;
+	}
+	/** Debit one member's `delta` in its own unit of work; a lost race on the target key has converged. */
+	async claimBack(input, ctx, tc) {
+		const { memberId, target, delta } = input;
+		const idempotencyKey = `reverse:${input.referenceType}:${input.referenceId}:${memberId}:${target}`;
+		try {
+			let payload;
+			await runLoyaltyUnit(this.unitOfWork, this._dispatchDeps, ctx, async (txCtx) => {
+				const session = txCtx.session;
+				const member = await this.memberRepo.requireMember(memberId, {
 					session,
 					...tc
 				});
-				const available = Math.max(0, member.balance.current);
-				const amount = Math.min(tx.points, available);
-				await this.update(tx._id, { expiredAt: now }, {
-					session,
-					...tc,
-					bypassAppendOnly: true
-				});
-				if (amount <= 0) return 0;
-				const updatedMember = await this.memberRepo.updateBalance(tx.memberId, {
-					current: -amount,
-					expired: amount
+				const collected = Math.min(delta, Math.max(0, member.balance.current));
+				const updated = await this.memberRepo.updateBalance(memberId, {
+					current: -collected,
+					lifetime: -delta
 				}, {
 					session,
 					...tc
 				});
-				if (updatedMember.balance.current < 0) throw new InsufficientPointsError(updatedMember.balance.current + amount, amount);
-				await this.create({
-					memberId: tx.memberId,
-					programId: tx.programId,
-					type: "expire",
-					points: -amount,
-					balanceAfter: updatedMember.balance.current,
-					description: `Points expired from transaction ${tx._id}`,
-					referenceType: "expiration",
-					referenceId: tx._id,
-					actorId: ctx.actorId
+				if (updated.balance.current < 0) throw new InsufficientPointsError(updated.balance.current + collected, collected);
+				const shortfall = delta - collected;
+				const created = await this.create({
+					memberId,
+					programId: member.programId,
+					type: "reverse",
+					points: -collected,
+					pointValueMinor: input.pointValueMinor,
+					balanceAfter: updated.balance.current,
+					description: `Reversed: ${input.reason}`,
+					referenceType: input.referenceType,
+					referenceId: input.referenceId,
+					idempotencyKey,
+					actorId: ctx.actorId,
+					metadata: {
+						claimed: delta,
+						collected,
+						shortfall,
+						target,
+						fraction: input.fraction,
+						reason: input.reason
+					}
 				}, {
 					session,
 					...tc
 				});
-				return amount;
+				payload = {
+					memberId,
+					externalId: member.externalId,
+					referenceType: input.referenceType,
+					referenceId: input.referenceId,
+					claimed: delta,
+					collected,
+					shortfall,
+					pointValueMinor: input.pointValueMinor,
+					balanceAfter: created.balanceAfter,
+					transactionId: String(created._id),
+					reason: input.reason
+				};
+				await this._dispatch(createEvent(LoyaltyEvents.POINTS_REVERSED, payload, txCtx, {
+					resource: "pointTransaction",
+					resourceId: created._id
+				}), txCtx);
 			});
-			if (expiredAmount > 0) {
-				affectedMemberIds.add(tx.memberId);
-				totalExpired += expiredAmount;
-				transactionCount++;
+			if (!payload) throw new ValidationError("reversal unit of work produced no transaction");
+			this.notifications?.notify(LoyaltyEvents.POINTS_REVERSED, { ...payload });
+			const { collected, shortfall, transactionId } = payload;
+			return {
+				claimed: delta,
+				collected,
+				shortfall,
+				transactionId
+			};
+		} catch (err) {
+			if (!(isDuplicateKey(err) || isWriteConflict(err))) throw err;
+			const winner = await this.getByQuery({ idempotencyKey }, {
+				throwOnNotFound: false,
+				...tc
+			});
+			if (!winner) throw err;
+			return {
+				claimed: 0,
+				collected: 0,
+				shortfall: 0,
+				transactionId: String(winner._id)
+			};
+		}
+	}
+	async processExpirations(ctx) {
+		assertTenantContext(ctx, this.config.tenant);
+		const tenantId = getTenantValue(ctx, this.config.tenant);
+		const tc = tenantCtx(this.config.tenant, tenantId);
+		const now = /* @__PURE__ */ new Date();
+		const { pointValueMinor } = await this.program();
+		let totalExpired = 0;
+		let transactionCount = 0;
+		const affectedMemberIds = /* @__PURE__ */ new Set();
+		for (;;) {
+			const page = await this.findAll({
+				expiresAt: { $lte: now },
+				expiredAt: { $exists: false }
+			}, {
+				sort: {
+					expiresAt: 1,
+					_id: 1
+				},
+				limit: EXPIRY_PAGE,
+				...tc
+			});
+			if (page.length === 0) break;
+			for (const tx of page) {
+				throwIfAborted(ctx.signal);
+				let lotPayload;
+				const expiredAmount = await runLoyaltyUnit(this.unitOfWork, this._dispatchDeps, ctx, async (txCtx) => {
+					const session = txCtx.session;
+					const member = await this.memberRepo.requireMember(tx.memberId, {
+						session,
+						...tc
+					});
+					const available = Math.max(0, member.balance.current);
+					const amount = Math.min(tx.points, available);
+					await this.update(tx._id, { expiredAt: now }, {
+						session,
+						...tc,
+						bypassAppendOnly: true
+					});
+					if (amount <= 0) return 0;
+					const updatedMember = await this.memberRepo.updateBalance(tx.memberId, {
+						current: -amount,
+						expired: amount
+					}, {
+						session,
+						...tc
+					});
+					if (updatedMember.balance.current < 0) throw new InsufficientPointsError(updatedMember.balance.current + amount, amount);
+					const expireRow = await this.create({
+						memberId: tx.memberId,
+						programId: tx.programId,
+						type: "expire",
+						points: -amount,
+						pointValueMinor,
+						balanceAfter: updatedMember.balance.current,
+						description: `Points expired from transaction ${tx._id}`,
+						referenceType: "expiration",
+						referenceId: tx._id,
+						actorId: ctx.actorId
+					}, {
+						session,
+						...tc
+					});
+					lotPayload = {
+						memberId: String(tx.memberId),
+						externalId: member.externalId,
+						transactionId: String(expireRow._id),
+						lotTransactionId: String(tx._id),
+						points: amount,
+						pointValueMinor,
+						balanceAfter: expireRow.balanceAfter
+					};
+					await this._dispatch(createEvent(LoyaltyEvents.POINTS_LOT_EXPIRED, lotPayload, txCtx, {
+						resource: "pointTransaction",
+						resourceId: expireRow._id
+					}), txCtx);
+					return amount;
+				});
+				if (lotPayload) this.notifications?.notify(LoyaltyEvents.POINTS_LOT_EXPIRED, { ...lotPayload });
+				if (expiredAmount > 0) {
+					affectedMemberIds.add(tx.memberId);
+					totalExpired += expiredAmount;
+					transactionCount++;
+				}
 			}
 		}
 		if (totalExpired > 0) await runLoyaltyUnit(this.unitOfWork, this._dispatchDeps, ctx, async (txCtx) => {
@@ -1131,30 +1407,16 @@ var PointTransactionRepository = class extends Repository {
 		};
 	}
 };
-/** E11000 across the raw driver + mongokit wrapper shapes. */
-function isDuplicateKey(err) {
-	if (typeof err !== "object" || err === null) return false;
-	const e = err;
-	if (e.code === 11e3) return true;
-	if (e.status === 409) return true;
-	if (e.cause !== void 0) return isDuplicateKey(e.cause);
-	return false;
-}
 /**
-* Transient MongoDB WriteConflict — surfaces under concurrent webhook
-* replay when two transactions try to update the same member balance.
-* With an idempotency key present, the winning insert is the source of
-* truth; losers are short-circuited to its doc rather than leaking the
-* raw driver error.
+* A replay of an adjustment returns the booked transaction — but only when it IS the same
+* adjustment. The same key on another member or another amount is two commands sharing one key.
 */
-function isWriteConflict(err) {
-	if (typeof err !== "object" || err === null) return false;
-	const e = err;
-	if (e.code === 112 || e.codeName === "WriteConflict") return true;
-	if (Array.isArray(e.errorLabels) && e.errorLabels.includes("TransientTransactionError")) return true;
-	if (typeof e.message === "string" && /write conflict/i.test(e.message)) return true;
-	if (e.cause !== void 0) return isWriteConflict(e.cause);
-	return false;
+function sameAdjustment(booked, input) {
+	if (String(booked.memberId) !== String(input.memberId) || booked.points !== input.points) throw Object.assign(/* @__PURE__ */ new Error(`idempotencyKey '${input.idempotencyKey}' was already used for a different adjustment`), {
+		code: "IDEMPOTENCY_KEY_REUSED",
+		status: 409
+	});
+	return booked;
 }
 //#endregion
 //#region src/repositories/redemption.repository.ts
@@ -1166,6 +1428,7 @@ var RedemptionRepository = class extends Repository {
 	notifications = null;
 	unitOfWork;
 	config;
+	program;
 	constructor(model, plugins = []) {
 		super(model, plugins);
 	}
@@ -1193,6 +1456,38 @@ var RedemptionRepository = class extends Repository {
 		};
 	}
 	/**
+	* The points the program owes right now: every member's spendable balance plus the points
+	* held by open reservations (a reservation has left the balance but not yet been used), at
+	* the program's current point value. The measure a ledger's liability reconciles against.
+	*/
+	async outstandingLiability(ctx) {
+		assertTenantContext(ctx, this.config.tenant);
+		const tc = tenantCtx(this.config.tenant, getTenantValue(ctx, this.config.tenant));
+		const sum = async (repo, pipeline) => {
+			const [row] = await repo.aggregatePipeline(pipeline, tc);
+			return row?.total ?? 0;
+		};
+		const [spendablePoints, reservedPoints, program] = await Promise.all([
+			sum(this.memberRepo, [{ $group: {
+				_id: null,
+				total: { $sum: "$balance.current" }
+			} }]),
+			sum(this, [{ $match: { status: "reserved" } }, { $group: {
+				_id: null,
+				total: { $sum: "$pointsReserved" }
+			} }]),
+			this.program()
+		]);
+		const outstandingPoints = spendablePoints + reservedPoints;
+		return {
+			spendablePoints,
+			reservedPoints,
+			outstandingPoints,
+			pointValueMinor: program.pointValueMinor,
+			valueMinor: outstandingPoints * program.pointValueMinor
+		};
+	}
+	/**
 	* Atomic compare-and-set status transition.
 	*
 	* `null` means ONE thing and one thing only: the guarded update matched
@@ -1211,10 +1506,13 @@ var RedemptionRepository = class extends Repository {
 	*
 	* Anything that throws in here is a real error and must propagate.
 	*/
-	async atomicStatusTransition(id, expectedStatus, data, ctx) {
+	async atomicStatusTransition(id, expectedStatus, data, ctx, guard) {
 		return this.update(id, data, {
 			lean: true,
-			query: { status: expectedStatus },
+			query: {
+				...guard,
+				status: expectedStatus
+			},
 			throwOnNotFound: false,
 			...ctx
 		});
@@ -1231,8 +1529,9 @@ var RedemptionRepository = class extends Repository {
 		const tenantId = getTenantValue(ctx, this.config.tenant);
 		const tc = tenantCtx(this.config.tenant, tenantId);
 		const member = await this.memberRepo.requireActiveMember(input.memberId, tc);
-		const { minPoints, minOrderAmount, maxRedeemPercent } = this.config.redemption;
-		const { pointValueMinor } = this.config;
+		const program = await this.program();
+		const { minPoints, minOrderAmount, maxRedeemPercent } = program.redemption;
+		const { pointValueMinor } = program;
 		if (input.pointsToRedeem < minPoints) return {
 			valid: false,
 			error: `Minimum ${minPoints} points required`,
@@ -1259,10 +1558,18 @@ var RedemptionRepository = class extends Repository {
 		const cappedDiscountMinor = Math.min(requestedDiscountMinor, maxDiscountMinor);
 		const maxAllowedPoints = Math.floor(maxDiscountMinor / pointValueMinor);
 		const actualPoints = cappedDiscountMinor < requestedDiscountMinor ? Math.floor(cappedDiscountMinor / pointValueMinor) : input.pointsToRedeem;
+		const discountAmount = actualPoints * pointValueMinor;
+		if (actualPoints === 0 || actualPoints < minPoints) return {
+			valid: false,
+			error: maxRedeemPercent === 0 ? "Points redemption is switched off" : `This order allows at most ${maxAllowedPoints} points; the minimum is ${minPoints}`,
+			pointsToRedeem: 0,
+			discountAmount: 0,
+			maxAllowedPoints
+		};
 		return {
 			valid: true,
 			pointsToRedeem: actualPoints,
-			discountAmount: actualPoints * pointValueMinor,
+			discountAmount,
 			maxAllowedPoints
 		};
 	}
@@ -1298,7 +1605,7 @@ var RedemptionRepository = class extends Repository {
 				pointsReserved: validation.pointsToRedeem,
 				pointsConfirmed: 0,
 				discountAmount: validation.discountAmount,
-				pointValueMinor: this.config.pointValueMinor,
+				pointValueMinor: validation.discountAmount / Math.max(1, validation.pointsToRedeem),
 				status: "reserved",
 				ownerType: input.ownerType,
 				ownerId: input.ownerId,
@@ -1326,7 +1633,17 @@ var RedemptionRepository = class extends Repository {
 		if (payload) this.notifications?.notify(LoyaltyEvents.REDEMPTION_RESERVED, { ...payload });
 		return redemption;
 	}
-	async confirm(redemptionId, ctx) {
+	/**
+	* `ownerExists: true` skips the reservation-expiry refusal — for a caller that
+	* knows the order was committed, where refusing would return points the customer
+	* already spent as a discount.
+	*
+	* `rebind` hands the hold to the document it paid for (a checkout reserves under its
+	* request key, the placed order owns it), inside the same CAS as the confirm; the CAS
+	* also matches `rebind.from`, so a caller holding only an id cannot re-home another
+	* owner's points. Absent ⇒ the reserve-time owner stays.
+	*/
+	async confirm(redemptionId, ctx, options) {
 		assertTenantContext(ctx, this.config.tenant);
 		const tenantId = getTenantValue(ctx, this.config.tenant);
 		const tc = tenantCtx(this.config.tenant, tenantId);
@@ -1335,18 +1652,30 @@ var RedemptionRepository = class extends Repository {
 			...tc
 		});
 		if (!redemption) throw new RedemptionNotFoundError(redemptionId);
-		if (redemption.expiresAt && redemption.expiresAt < /* @__PURE__ */ new Date()) throw new RedemptionExpiredError(redemptionId);
+		if (!options?.ownerExists && redemption.expiresAt && redemption.expiresAt < /* @__PURE__ */ new Date()) throw new RedemptionExpiredError(redemptionId);
+		const rebind = options?.rebind;
 		let payload;
 		const updated = await runLoyaltyUnit(this.unitOfWork, this._dispatchDeps, ctx, async (txCtx) => {
 			const session = txCtx.session;
-			if (!await this.atomicStatusTransition(redemptionId, "reserved", {
+			const transitioned = await this.atomicStatusTransition(redemptionId, "reserved", {
 				status: "confirmed",
 				pointsConfirmed: redemption.pointsReserved,
-				confirmedAt: /* @__PURE__ */ new Date()
+				confirmedAt: /* @__PURE__ */ new Date(),
+				...rebind ? {
+					ownerType: rebind.to.ownerType,
+					ownerId: rebind.to.ownerId
+				} : {}
 			}, {
 				session,
 				...tc
-			})) throw new ValidationError(`Redemption status must be 'reserved', got '${redemption.status}'`);
+			}, rebind ? {
+				ownerType: rebind.from.ownerType,
+				ownerId: rebind.from.ownerId
+			} : void 0);
+			if (!transitioned) {
+				if (rebind && redemption.status === "reserved" && redemption.ownerId !== rebind.from.ownerId) throw new ValidationError(`Redemption ${redemptionId} is held by ${redemption.ownerType} ${redemption.ownerId}, not ${rebind.from.ownerType} ${rebind.from.ownerId}`);
+				throw new ValidationError(`Redemption status must be 'reserved', got '${redemption.status}'`);
+			}
 			const member = await this.memberRepo.requireActiveMember(redemption.memberId, {
 				session,
 				...tc
@@ -1358,8 +1687,8 @@ var RedemptionRepository = class extends Repository {
 				points: -redemption.pointsReserved,
 				balanceAfter: member.balance.current,
 				description: `Redemption confirmed: ${redemptionId}`,
-				referenceType: redemption.ownerType,
-				referenceId: redemption.ownerId,
+				referenceType: transitioned.ownerType,
+				referenceId: transitioned.ownerId,
 				actorId: ctx.actorId
 			}, {
 				session,
@@ -1547,7 +1876,8 @@ var RedemptionRepository = class extends Repository {
 				pointsCredited: pointsToCredit,
 				originalPoints,
 				proportional: usedProportional,
-				transactionId: result.reversalTransactionId ?? ""
+				pointValueMinor: redemption.pointValueMinor,
+				...result.reversalTransactionId ? { transactionId: String(result.reversalTransactionId) } : {}
 			};
 			if (options?.reason) payload.reason = options.reason;
 			await this._dispatch(createEvent(LoyaltyEvents.REDEMPTION_REVERSED, payload, txCtx, {
@@ -1559,6 +1889,90 @@ var RedemptionRepository = class extends Repository {
 		if (payload) this.notifications?.notify(LoyaltyEvents.REDEMPTION_REVERSED, { ...payload });
 		return reversed;
 	}
+	/**
+	* Confirm every redemption still `reserved` against an owner that now exists.
+	*
+	* The convergence net for a checkout whose inline confirm failed after the order
+	* was committed: left `reserved`, the expiry sweep would RELEASE it and the
+	* member would keep both the discount and the points. Safe to repeat — a status
+	* CAS, and a redemption another caller already settled is skipped.
+	*/
+	async confirmForOwner(ownerIds, ctx, options) {
+		assertTenantContext(ctx, this.config.tenant);
+		const tc = tenantCtx(this.config.tenant, getTenantValue(ctx, this.config.tenant));
+		const ids = [...new Set(ownerIds.filter(Boolean))];
+		if (ids.length === 0) return { confirmed: 0 };
+		let confirmed = 0;
+		const filter = {
+			ownerType: "order",
+			ownerId: { $in: ids },
+			status: "reserved"
+		};
+		for (const redemption of await this.findAll(filter, tc)) try {
+			await this.confirm(redemption._id, ctx, {
+				ownerExists: true,
+				...options?.rebindTo && options.rebindTo.ownerId !== redemption.ownerId ? { rebind: {
+					from: {
+						ownerType: redemption.ownerType,
+						ownerId: redemption.ownerId
+					},
+					to: options.rebindTo
+				} } : {}
+			});
+			confirmed++;
+		} catch (err) {
+			const now = await this.getById(redemption._id, {
+				throwOnNotFound: false,
+				...tc
+			});
+			if (now && now.status !== "reserved") continue;
+			throw err;
+		}
+		return { confirmed };
+	}
+	/**
+	* Undo every redemption held against an owner that was refunded or canceled:
+	* confirmed ones credit their points back, reserved ones release their hold.
+	*
+	* `ownerIds` lists every identity the owner was reserved under (a till reserves
+	* against its idempotency key, not the order number). Safe to repeat: each step is
+	* a status CAS, and a redemption another caller already settled is skipped.
+	*/
+	async undoForOwner(ownerIds, ctx, options) {
+		assertTenantContext(ctx, this.config.tenant);
+		const tc = tenantCtx(this.config.tenant, getTenantValue(ctx, this.config.tenant));
+		const ids = [...new Set(ownerIds.filter(Boolean))];
+		const out = {
+			reversed: 0,
+			released: 0,
+			pointsReturned: 0
+		};
+		if (ids.length === 0) return out;
+		const open = await this.findAll({
+			ownerType: "order",
+			ownerId: { $in: ids },
+			status: { $in: ["reserved", "confirmed"] }
+		}, tc);
+		for (const redemption of open) try {
+			if (redemption.status === "confirmed") {
+				await this.reverseConfirmed(redemption._id, ctx, { reason: options.reason });
+				out.reversed++;
+				out.pointsReturned += redemption.pointsConfirmed;
+			} else {
+				await this.release(redemption._id, ctx);
+				out.released++;
+				out.pointsReturned += redemption.pointsReserved;
+			}
+		} catch (err) {
+			const now = await this.getById(redemption._id, {
+				throwOnNotFound: false,
+				...tc
+			});
+			if (now && now.status !== redemption.status) continue;
+			throw err;
+		}
+		return out;
+	}
 	async cleanupExpired(ctx) {
 		assertTenantContext(ctx, this.config.tenant);
 		const tenantId = getTenantValue(ctx, this.config.tenant);
@@ -1791,6 +2205,7 @@ var ReferralRepository = class extends Repository {
 				memberId: referrer._id,
 				points: referrerRewardPoints,
 				description: `Referral reward: referred ${referee.externalId}`,
+				source: "referral",
 				referenceType: "referral",
 				referenceId: referral._id,
 				idempotencyKey: `referral:${referral._id}:referrer`
@@ -1802,6 +2217,7 @@ var ReferralRepository = class extends Repository {
 				memberId: referee._id,
 				points: refereeRewardPoints,
 				description: `Referral welcome bonus from ${referrer.externalId}`,
+				source: "referral",
 				referenceType: "referral",
 				referenceId: referral._id,
 				idempotencyKey: `referral:${referral._id}:referee`
@@ -1842,6 +2258,7 @@ var ReferralRepository = class extends Repository {
 							memberId: ancestor._id,
 							points,
 							description: `Multi-tier referral reward (depth ${depth})`,
+							source: "referral",
 							referenceType: "referral",
 							referenceId: referral._id,
 							idempotencyKey: `referral:${referral._id}:ancestor:${depth}`,
@@ -1887,7 +2304,619 @@ var ReferralRepository = class extends Repository {
 	}
 };
 //#endregion
+//#region src/domain/stamp-program.ts
+/**
+* Stamp-card program rules — the wire schemas, the write-time invariants, and the stamp count for
+* one order. Pure: no I/O.
+*/
+/** An allow-list: omit it to mean "any". Empty is refused — it would otherwise read as "any". */
+const allowList = z.array(z.string().trim().min(1)).min(1, "an empty list is refused — omit the field to allow any");
+const positiveInt = z.number().int().min(1);
+const minorAmount = z.number().int().min(0);
+const instant = z.iso.datetime({ offset: true });
+const stampEarnSchema = z.strictObject({
+	unit: z.enum(STAMP_EARN_UNITS),
+	categoryIds: allowList.optional(),
+	productIds: allowList.optional(),
+	perMinor: positiveInt.optional(),
+	minOrderMinor: minorAmount.optional()
+}).superRefine((earn, ctx) => {
+	if (earn.unit === "spend" && earn.perMinor === void 0) ctx.addIssue({
+		code: "custom",
+		path: ["perMinor"],
+		message: "unit 'spend' requires perMinor (minor units per stamp)"
+	});
+	if (earn.unit !== "spend" && earn.perMinor !== void 0) ctx.addIssue({
+		code: "custom",
+		path: ["perMinor"],
+		message: "perMinor applies to unit 'spend' only"
+	});
+});
+const stampRewardSchema = z.discriminatedUnion("kind", [z.strictObject({
+	kind: z.literal("points"),
+	points: positiveInt
+}), z.strictObject({
+	kind: z.literal("voucher"),
+	voucherProgramId: z.string().trim().min(1)
+})]);
+const programFields = {
+	name: z.string().trim().min(1),
+	description: z.string().optional(),
+	status: z.enum(STAMP_PROGRAM_STATUSES).optional(),
+	earn: stampEarnSchema,
+	stampsRequired: positiveInt,
+	stampValidityDays: positiveInt.optional(),
+	startsAt: instant.optional(),
+	endsAt: instant.optional(),
+	reward: stampRewardSchema,
+	maxRewardsPerMember: positiveInt.optional(),
+	branchIds: allowList.optional(),
+	metadata: z.record(z.string(), z.unknown()).optional()
+};
+/** The create body — strict: an unknown key is a 400, never silently dropped. Dates are ISO strings. */
+const stampProgramInputSchema = z.strictObject(programFields);
+/** The patch body — strict, every field optional; nested `earn` / `reward` are replaced whole. */
+const stampProgramPatchSchema = z.strictObject(programFields).partial();
+/** Fields `assertStampProgram` judges; persistence and system keys pass through untouched. */
+const PROGRAM_KEYS = Object.keys(programFields);
+/**
+* Refuse a program that could never award correctly. Runs on the WHOLE document (a patch merged
+* over what is stored), so a partial update cannot produce an invalid program.
+*/
+function assertStampProgram(doc, opts) {
+	const fields = {};
+	for (const key of PROGRAM_KEYS) {
+		const value = doc[key];
+		if (value === void 0 || value === null) continue;
+		fields[key] = value instanceof Date ? value.toISOString() : value;
+	}
+	const parsed = stampProgramInputSchema.safeParse(stripNullish(fields));
+	if (!parsed.success) {
+		const issue = parsed.error.issues[0];
+		throw new ValidationError(`Invalid stamp program — ${issue?.path.length ? `${issue.path.join(".")}: ` : ""}${issue?.message ?? "malformed"}`);
+	}
+	const p = parsed.data;
+	if (p.startsAt && p.endsAt && Date.parse(p.startsAt) >= Date.parse(p.endsAt)) throw new ValidationError("Invalid stamp program — startsAt must be before endsAt");
+	if (p.reward.kind === "voucher" && !opts.rewardIssuerBound) throw new ValidationError("Invalid stamp program — a voucher reward needs a reward issuer, and this engine was bound without LoyaltyRuntime.rewardIssuer: the program would claim stamps and never issue anything");
+}
+/** Mongoose hands back `[]` for an unset array path and `{}`-ish subdocs; judge only what was set. */
+function stripNullish(value) {
+	const out = {};
+	for (const [k, v] of Object.entries(value)) {
+		if (v === void 0 || v === null) continue;
+		out[k] = v !== null && typeof v === "object" && !Array.isArray(v) ? stripNullish(plain(v)) : v;
+	}
+	return out;
+}
+function plain(v) {
+	const maybe = v;
+	return typeof maybe.toObject === "function" ? maybe.toObject() : v;
+}
+/** Whether the order falls inside the program's window, branch set and order minimum. */
+function programAppliesTo(program, order) {
+	const at = order.occurredAt.getTime();
+	if (program.startsAt && at < new Date(program.startsAt).getTime()) return false;
+	if (program.endsAt && at >= new Date(program.endsAt).getTime()) return false;
+	if (program.branchIds?.length) {
+		if (!order.branchId || !program.branchIds.includes(order.branchId)) return false;
+	}
+	if (program.earn.minOrderMinor !== void 0 && order.orderTotalMinor < program.earn.minOrderMinor) return false;
+	return true;
+}
+/**
+* Stamps one order earns on a program: `order` / `visit` → 1 when a line qualifies, `item` → the
+* qualifying units (a line sold by measure counts once, see {@link itemStampsOf}), `spend` →
+* floor(qualifying spend / perMinor). With no product/category filter every line qualifies and
+* `spend` counts the order total.
+*/
+function stampsForOrder(program, order) {
+	if (!programAppliesTo(program, order)) return 0;
+	const { earn } = program;
+	const filtered = Boolean(earn.categoryIds?.length || earn.productIds?.length);
+	const lines = filtered ? order.lines.filter((l) => l.categoryId !== void 0 && earn.categoryIds?.includes(l.categoryId) || l.productId !== void 0 && earn.productIds?.includes(l.productId)) : order.lines;
+	if (filtered && lines.length === 0) return 0;
+	switch (earn.unit) {
+		case "order":
+		case "visit": return 1;
+		case "item": return lines.reduce((n, l) => n + itemStampsOf(l), 0);
+		case "spend": {
+			const perMinor = earn.perMinor;
+			if (!perMinor) throw new ValidationError(`Stamp program ${program._id} has unit 'spend' without perMinor`);
+			const spend = filtered ? lines.reduce((n, l) => n + l.amountMinor, 0) : order.orderTotalMinor;
+			return Math.floor(spend / perMinor);
+		}
+		default: throw new ValidationError(`Stamp program ${program._id} has unknown earn unit '${String(earn.unit)}'`);
+	}
+}
+/** A line whose step is a whole number (absent = 1) is counted in units. */
+function isWholeUnitLine(line) {
+	return line.quantityStep === void 0 || Number.isInteger(line.quantityStep);
+}
+/**
+* `item` stamps for one line: its units when it sells in whole units, ONE when it sells by measure
+* (2.35 kg of rice is one item bought, never 2 or 2350 stamps).
+*/
+function itemStampsOf(line) {
+	if (isWholeUnitLine(line)) return line.quantity;
+	return line.quantity > 0 ? 1 : 0;
+}
+/** Refuse an order input a stamp count would silently mis-read. */
+function assertStampOrderInput(input) {
+	if (!input.memberId) throw new ValidationError("recordOrder: memberId is required");
+	if (!input.orderRef) throw new ValidationError("recordOrder: orderRef is required");
+	if (!(input.occurredAt instanceof Date) || Number.isNaN(input.occurredAt.getTime())) throw new ValidationError("recordOrder: occurredAt must be a valid Date");
+	if (!Number.isSafeInteger(input.orderTotalMinor) || input.orderTotalMinor < 0) throw new ValidationError("recordOrder: orderTotalMinor must be a non-negative integer (minor units)");
+	for (const line of input.lines) {
+		if (!Number.isSafeInteger(line.amountMinor) || line.amountMinor < 0) throw new ValidationError("recordOrder: line amountMinor must be a non-negative integer (minor units)");
+		if (!Number.isFinite(line.quantity) || line.quantity < 0) throw new ValidationError("recordOrder: line quantity must be a non-negative number");
+		if (line.quantityStep !== void 0 && !(Number.isFinite(line.quantityStep) && line.quantityStep > 0)) throw new ValidationError("recordOrder: line quantityStep must be a positive number when given");
+		if (isWholeUnitLine(line) && !Number.isInteger(line.quantity)) throw new ValidationError(`recordOrder: line quantity ${line.quantity} is fractional on a whole-unit line — send the line's quantityStep`);
+	}
+}
+//#endregion
+//#region src/repositories/stamp.repository.ts
+const DAY_MS = 864e5;
+/** Lost races a settle retries before failing — each one means another settle made progress. */
+const MAX_SETTLE_CONFLICTS = 5;
+/** An entry's `consumed` moved between the read and the claim — re-read and try again. */
+var StampClaimConflict = class extends Error {};
+/**
+* Stamp-card ledger: one entry per (program, member, order), consumed oldest-first into awards.
+*
+* Every guard is an index or a CAS filter, never an `if` above a write: the order entry, the visit
+* day, the award sequence and each entry's `consumed` count.
+*/
+var StampRepository = class extends Repository {
+	memberRepo;
+	txRepo;
+	programRepo;
+	awardRepo;
+	events;
+	outbox;
+	unitOfWork;
+	config;
+	rewardIssuer;
+	constructor(model, plugins = []) {
+		super(model, plugins);
+	}
+	get deps() {
+		return {
+			events: this.events,
+			outbox: this.outbox
+		};
+	}
+	tc(ctx) {
+		assertTenantContext(ctx, this.config.tenant);
+		return tenantCtx(this.config.tenant, getTenantValue(ctx, this.config.tenant));
+	}
+	async create(data, options) {
+		injectTenantIntoData(data, options, this.config.tenant);
+		return super.create(data, options);
+	}
+	/**
+	* Record one paid order against every active stamp program of the member's loyalty program,
+	* then settle each. Re-recording the same order is a no-op that still settles, so a redelivery
+	* after a crash finishes the award the first delivery started.
+	*/
+	async recordOrder(input, ctx) {
+		assertStampOrderInput(input);
+		const tc = this.tc(ctx);
+		const member = await this.memberRepo.requireActiveMember(input.memberId, tc);
+		const programs = await this.programRepo.findAll({
+			status: "active",
+			programId: member.programId
+		}, {
+			sort: { createdAt: 1 },
+			...tc
+		});
+		const businessDay = civilDateOf(input.occurredAt, this.config.timezone ?? "UTC");
+		const results = [];
+		for (const program of programs) {
+			const stamps = stampsForOrder(program, input);
+			if (stamps <= 0) continue;
+			const recorded = await this.insertEntry(program, member, input, stamps, businessDay, ctx, tc);
+			const awards = await this.settle(String(program._id), input.memberId, ctx);
+			results.push({
+				stampProgramId: String(program._id),
+				stamps: recorded ? stamps : 0,
+				duplicate: !recorded,
+				awards
+			});
+		}
+		return results;
+	}
+	/** Insert the order's entry; `false` when the unique index says it (or its visit day) exists. */
+	async insertEntry(program, member, input, stamps, businessDay, ctx, tc) {
+		const expiresAt = program.stampValidityDays ? new Date(input.occurredAt.getTime() + program.stampValidityDays * DAY_MS) : void 0;
+		const data = {
+			stampProgramId: program._id,
+			memberId: input.memberId,
+			orderRef: input.orderRef,
+			stamps,
+			consumed: 0,
+			earnedAt: input.occurredAt,
+			businessDay,
+			...expiresAt ? { expiresAt } : {},
+			...program.earn.unit === "visit" ? { visitKey: businessDay } : {},
+			...input.branchId ? { branchId: input.branchId } : {}
+		};
+		try {
+			await runLoyaltyUnit(this.unitOfWork, this.deps, ctx, async (txCtx) => {
+				const entry = await this.create(data, {
+					session: txCtx.session,
+					...tc
+				});
+				const payload = {
+					stampProgramId: String(program._id),
+					memberId: String(member._id),
+					externalId: member.externalId,
+					entryId: String(entry._id),
+					orderRef: input.orderRef,
+					stamps,
+					businessDay,
+					...expiresAt ? { expiresAt: expiresAt.toISOString() } : {}
+				};
+				await dispatchLoyaltyEvent(this.deps, createEvent(LoyaltyEvents.STAMP_EARNED, payload, txCtx, {
+					resource: "stampEntry",
+					resourceId: String(entry._id)
+				}), txCtx);
+			});
+			return true;
+		} catch (err) {
+			if (isDuplicateKey(err) && !ctx.session) return false;
+			throw err;
+		}
+	}
+	/**
+	* Exchange full cards for rewards until the member's stamps (or `maxRewardsPerMember`) run out.
+	* Voucher awards claimed earlier but not yet issued are resumed first.
+	*/
+	async settle(stampProgramId, memberId, ctx) {
+		const tc = this.tc(ctx);
+		const out = [];
+		const pending = await this.awardRepo.findAll({
+			stampProgramId,
+			memberId,
+			status: "pending"
+		}, {
+			sort: { sequence: 1 },
+			...tc
+		});
+		for (const award of pending) out.push(await this.issueVoucher(award, ctx, tc));
+		let conflicts = 0;
+		for (;;) {
+			let claimed;
+			try {
+				claimed = await this.claimAward(stampProgramId, memberId, ctx, tc);
+			} catch (err) {
+				if ((err instanceof StampClaimConflict || isDuplicateKey(err) || isWriteConflict(err)) && !ctx.session && ++conflicts <= MAX_SETTLE_CONFLICTS) continue;
+				throw err;
+			}
+			if (!claimed) return out;
+			out.push(claimed.status === "pending" ? await this.issueVoucher(claimed, ctx, tc) : claimed);
+		}
+	}
+	/**
+	* ONE award in ONE unit of work: consume the oldest stamps (CAS per entry), insert the award at
+	* the next sequence (unique — the race fence), and for points credit them in the same
+	* transaction. A voucher award commits as `pending`; its issuance happens after commit.
+	*/
+	async claimAward(stampProgramId, memberId, ctx, tc) {
+		return runLoyaltyUnit(this.unitOfWork, this.deps, ctx, async (txCtx) => {
+			const opts = {
+				session: txCtx.session,
+				...tc
+			};
+			const program = await this.programRepo.getById(stampProgramId, {
+				...opts,
+				throwOnNotFound: false
+			});
+			if (!program || program.status !== "active") return null;
+			const awarded = await this.awardRepo.count({
+				stampProgramId,
+				memberId
+			}, opts);
+			if (program.maxRewardsPerMember !== void 0 && awarded >= program.maxRewardsPerMember) return null;
+			const open = await this.openEntries(stampProgramId, memberId, /* @__PURE__ */ new Date(), opts);
+			if (open.reduce((n, e) => n + (e.stamps - e.consumed), 0) < program.stampsRequired) return null;
+			if (program.reward.kind === "voucher" && !this.rewardIssuer) throw new ValidationError(`Stamp program ${stampProgramId} rewards a voucher but the engine has no rewardIssuer — refusing to consume stamps`);
+			let remaining = program.stampsRequired;
+			const taken = [];
+			for (const entry of open) {
+				if (remaining === 0) break;
+				const take = Math.min(entry.stamps - entry.consumed, remaining);
+				if (!await this.claim(entry._id, {
+					field: "consumed",
+					from: entry.consumed,
+					to: entry.consumed + take,
+					where: { reversedAt: { $exists: false } }
+				}, {}, opts)) throw new StampClaimConflict();
+				taken.push({
+					entryId: String(entry._id),
+					stamps: take
+				});
+				remaining -= take;
+			}
+			const sequence = awarded + 1;
+			const awardKey = `stamp:${stampProgramId}:${memberId}:${sequence}`;
+			const now = /* @__PURE__ */ new Date();
+			const reward = program.reward;
+			const award = await this.awardRepo.create({
+				stampProgramId,
+				memberId,
+				sequence,
+				awardKey,
+				entries: taken,
+				stampsConsumed: program.stampsRequired,
+				status: reward.kind === "points" ? "issued" : "pending",
+				reward: reward.kind === "points" ? {
+					kind: "points",
+					points: reward.points
+				} : {
+					kind: "voucher",
+					voucherProgramId: reward.voucherProgramId
+				},
+				awardedAt: now,
+				...reward.kind === "points" ? { issuedAt: now } : {}
+			}, opts);
+			if (reward.kind !== "points") return award;
+			const tx = await this.txRepo.earnPoints({
+				memberId,
+				points: reward.points,
+				source: "campaign",
+				description: `Stamp card: ${program.name} (#${sequence})`,
+				referenceType: "stamp_award",
+				referenceId: awardKey,
+				idempotencyKey: awardKey,
+				metadata: {
+					stampProgramId,
+					awardId: String(award._id),
+					sequence
+				}
+			}, txCtx);
+			const issued = await this.awardRepo.update(award._id, { "reward.pointTransactionId": tx._id }, {
+				...opts,
+				throwOnNotFound: true
+			});
+			const member = await this.memberRepo.requireMember(memberId, opts);
+			await this.dispatchAwardIssued(award, member.externalId, {
+				kind: "points",
+				points: reward.points,
+				pointTransactionId: String(tx._id)
+			}, txCtx);
+			return issued ?? award;
+		});
+	}
+	/** Issue a claimed voucher award through the host port (idempotent on `awardKey`), then mark it. */
+	async issueVoucher(award, ctx, tc) {
+		if (award.status !== "pending") return award;
+		const issuer = this.rewardIssuer;
+		const voucherProgramId = award.reward.voucherProgramId;
+		if (!issuer || !voucherProgramId) throw new ValidationError(`Stamp award ${award.awardKey} is a pending voucher but the engine has no rewardIssuer (or the award names no voucher program)`);
+		const member = await this.memberRepo.requireMember(String(award.memberId), tc);
+		const issued = await issuer.issueVoucher({
+			voucherProgramId,
+			stampProgramId: String(award.stampProgramId),
+			memberId: String(award.memberId),
+			externalId: member.externalId,
+			externalType: member.externalType,
+			awardKey: award.awardKey
+		}, ctx);
+		if (!issued || typeof issued.voucherId !== "string" || !issued.voucherId || typeof issued.code !== "string" || !issued.code) throw new ValidationError(`rewardIssuer.issueVoucher returned no voucherId/code for award ${award.awardKey}`);
+		return runLoyaltyUnit(this.unitOfWork, this.deps, ctx, async (txCtx) => {
+			const opts = {
+				session: txCtx.session,
+				...tc
+			};
+			const marked = await this.awardRepo.claim(award._id, {
+				from: "pending",
+				to: "issued"
+			}, {
+				"reward.voucherId": issued.voucherId,
+				"reward.code": issued.code,
+				issuedAt: /* @__PURE__ */ new Date()
+			}, opts);
+			if (!marked) return await this.awardRepo.getById(award._id, {
+				...opts,
+				throwOnNotFound: true
+			}) ?? award;
+			await this.dispatchAwardIssued(award, member.externalId, {
+				kind: "voucher",
+				voucherProgramId,
+				voucherId: issued.voucherId,
+				code: issued.code
+			}, txCtx);
+			return marked;
+		});
+	}
+	async dispatchAwardIssued(award, externalId, reward, txCtx) {
+		const payload = {
+			stampProgramId: String(award.stampProgramId),
+			memberId: String(award.memberId),
+			externalId,
+			awardId: String(award._id),
+			sequence: award.sequence,
+			stampsConsumed: award.stampsConsumed,
+			reward
+		};
+		await dispatchLoyaltyEvent(this.deps, createEvent(LoyaltyEvents.STAMP_AWARD_ISSUED, payload, txCtx, {
+			resource: "stampAward",
+			resourceId: String(award._id)
+		}), txCtx);
+	}
+	/**
+	* Reverse an undone order's stamps. Policy: unconsumed stamps are removed; stamps already
+	* consumed into an award are kept (`retainedInAwards`, on the result and the event) — never clawed back.
+	*/
+	async reverseOrder(orderRef, ctx) {
+		if (!orderRef) throw new ValidationError("reverseOrder: orderRef is required");
+		const tc = this.tc(ctx);
+		const entries = await this.findAll({
+			orderRef,
+			reversedAt: { $exists: false }
+		}, tc);
+		const out = [];
+		for (const entry of entries) {
+			const reversal = await this.reverseEntry(entry, ctx, tc);
+			if (reversal) out.push(reversal);
+		}
+		return out;
+	}
+	async reverseEntry(entry, ctx, tc) {
+		for (let attempt = 0; attempt <= MAX_SETTLE_CONFLICTS; attempt++) {
+			const current = attempt === 0 ? entry : await this.getById(entry._id, {
+				...tc,
+				throwOnNotFound: false
+			});
+			if (!current || current.reversedAt) return null;
+			const reversal = {
+				stampProgramId: String(current.stampProgramId),
+				memberId: String(current.memberId),
+				entryId: String(current._id),
+				reversed: current.stamps - current.consumed,
+				retainedInAwards: current.consumed
+			};
+			if (await runLoyaltyUnit(this.unitOfWork, this.deps, ctx, async (txCtx) => {
+				if (!await this.claim(current._id, {
+					field: "consumed",
+					from: current.consumed,
+					to: current.consumed,
+					where: { reversedAt: { $exists: false } }
+				}, {
+					$set: {
+						reversedAt: /* @__PURE__ */ new Date(),
+						reversedStamps: reversal.reversed
+					},
+					$unset: { visitKey: "" }
+				}, {
+					session: txCtx.session,
+					...tc
+				})) return false;
+				const payload = {
+					...reversal,
+					orderRef: current.orderRef
+				};
+				await dispatchLoyaltyEvent(this.deps, createEvent(LoyaltyEvents.STAMP_REVERSED, payload, txCtx, {
+					resource: "stampEntry",
+					resourceId: String(current._id)
+				}), txCtx);
+				return true;
+			})) return reversal;
+		}
+		throw new StampClaimConflict(`reverseOrder: entry ${String(entry._id)} kept changing under the reversal`);
+	}
+	/** The member's card on every active program of their loyalty program. */
+	async progress(memberId, ctx) {
+		const tc = this.tc(ctx);
+		const member = await this.memberRepo.requireMember(memberId, tc);
+		const programs = await this.programRepo.findAll({
+			status: "active",
+			programId: member.programId
+		}, {
+			sort: { createdAt: 1 },
+			...tc
+		});
+		const now = /* @__PURE__ */ new Date();
+		const out = [];
+		for (const program of programs) {
+			const stampProgramId = String(program._id);
+			const open = await this.openEntries(stampProgramId, memberId, now, tc);
+			const expiries = open.flatMap((e) => e.expiresAt ? [new Date(e.expiresAt).getTime()] : []);
+			const rewardsEarned = await this.awardRepo.count({
+				stampProgramId,
+				memberId
+			}, tc);
+			out.push({
+				stampProgramId,
+				name: program.name,
+				stampsRequired: program.stampsRequired,
+				stamps: open.reduce((n, e) => n + (e.stamps - e.consumed), 0),
+				...expiries.length > 0 ? { nextExpiry: new Date(Math.min(...expiries)) } : {},
+				rewardsEarned,
+				...program.maxRewardsPerMember !== void 0 ? { maxRewardsPerMember: program.maxRewardsPerMember } : {},
+				reward: program.reward
+			});
+		}
+		return out;
+	}
+	/** Unreversed, unexpired entries with stamps left, oldest first. */
+	openEntries(stampProgramId, memberId, now, opts) {
+		return this.findAll({
+			stampProgramId,
+			memberId,
+			reversedAt: { $exists: false },
+			$expr: { $lt: ["$consumed", "$stamps"] },
+			$or: [{ expiresAt: { $exists: false } }, { expiresAt: { $gt: now } }]
+		}, {
+			sort: {
+				earnedAt: 1,
+				_id: 1
+			},
+			...opts
+		});
+	}
+};
+//#endregion
+//#region src/repositories/stamp-award.repository.ts
+/** Awards are written only by `stamps.settle`; this repository is their read surface. */
+var StampAwardRepository = class extends Repository {
+	config;
+	constructor(model, plugins = []) {
+		super(model, plugins);
+	}
+	async create(data, options) {
+		injectTenantIntoData(data, options, this.config.tenant);
+		return super.create(data, options);
+	}
+};
+//#endregion
+//#region src/repositories/stamp-program.repository.ts
+/**
+* Stamp-card programs. Every write is judged whole by `assertStampProgram` — a create, and a patch
+* merged over the stored program — so no path (HTTP or direct) stores a program that cannot award.
+*/
+var StampProgramRepository = class extends Repository {
+	config;
+	rewardIssuer;
+	constructor(model, plugins = []) {
+		super(model, plugins);
+	}
+	async create(data, options) {
+		const doc = data;
+		doc.programId ??= this.config.programId;
+		injectTenantIntoData(doc, options, this.config.tenant);
+		assertStampProgram(doc, { rewardIssuerBound: this.rewardIssuer !== void 0 });
+		return super.create(data, options);
+	}
+	async createMany(docs, options) {
+		for (const doc of docs) {
+			doc.programId ??= this.config.programId;
+			injectTenantIntoData(doc, options, this.config.tenant);
+			assertStampProgram(doc, { rewardIssuerBound: this.rewardIssuer !== void 0 });
+		}
+		return super.createMany(docs, options);
+	}
+	/** A flat patch only: nested `earn` / `reward` are replaced whole, then the result is judged. */
+	async update(id, data, options) {
+		if (Object.keys(data).some((k) => k.startsWith("$"))) throw new ValidationError("Stamp program updates take a flat patch, not update operators");
+		const current = await this.getById(id, {
+			...options,
+			lean: true,
+			throwOnNotFound: false
+		});
+		if (current) assertStampProgram({
+			...current,
+			...data
+		}, { rewardIssuerBound: this.rewardIssuer !== void 0 });
+		return super.update(id, data, options);
+	}
+};
+//#endregion
 //#region src/repositories/tier-definition.repository.ts
+/** The highest-ranked tier whose `minLifetimePoints` the lifetime reaches. */
+function qualifiedAmong(tiers, lifetime) {
+	return [...tiers].sort((a, b) => b.rank - a.rank).find((t) => t.qualificationCriteria.minLifetimePoints !== void 0 && lifetime >= t.qualificationCriteria.minLifetimePoints) ?? null;
+}
 var TierDefinitionRepository = class extends Repository {
 	memberRepo;
 	events;
@@ -1914,7 +2943,18 @@ var TierDefinitionRepository = class extends Repository {
 			outbox: this.outbox
 		}, event, ctx);
 	}
-	async evaluateMember(memberId, ctx) {
+	/** The highest tier `lifetime` points qualify for in a program, or null. */
+	async qualifiedTierName(programId, lifetime, tc) {
+		return qualifiedAmong(await this.findAll({ programId }, {
+			sort: { rank: 1 },
+			...tc
+		}), lifetime)?.name ?? null;
+	}
+	/**
+	* Re-place a member by lifetime points. `upgradeOnly` is the earn path: a credit
+	* may promote at once, while a downgrade waits for the periodic evaluation.
+	*/
+	async evaluateMember(memberId, ctx, options = {}) {
 		assertTenantContext(ctx, this.config.tenant);
 		const tenantId = getTenantValue(ctx, this.config.tenant);
 		const tc = tenantCtx(this.config.tenant, tenantId);
@@ -1930,12 +2970,12 @@ var TierDefinitionRepository = class extends Repository {
 			newTier: member.tier,
 			action: "unchanged"
 		};
-		const qualifiedTier = sortedTiers.find((t) => t.qualificationCriteria.minLifetimePoints !== void 0 && member.balance.lifetime >= t.qualificationCriteria.minLifetimePoints) ?? null;
+		const qualifiedTier = qualifiedAmong(sortedTiers, member.balance.lifetime);
 		const currentTierDef = member.tier ? sortedTiers.find((t) => t.name === member.tier) ?? null : null;
 		const currentRank = currentTierDef?.rank ?? -1;
 		const newRank = qualifiedTier?.rank ?? -1;
 		if (newRank > currentRank && qualifiedTier) return this.applyUpgrade(memberId, member, qualifiedTier.name, tc, ctx);
-		if (newRank < currentRank && currentTierDef) return this.applyDowngrade(memberId, member, currentTierDef, qualifiedTier?.name ?? null, tc, ctx);
+		if (newRank < currentRank && currentTierDef && !options.upgradeOnly) return this.applyDowngrade(memberId, member, currentTierDef, qualifiedTier?.name ?? null, tc, ctx);
 		return {
 			memberId,
 			previousTier: member.tier,
@@ -2170,7 +3210,7 @@ function asPlugins(p) {
 	return p ?? [];
 }
 function createRepositories(input) {
-	const { models, plugins, tenant, config, events, outbox, notifications, unitOfWork } = input;
+	const { models, plugins, tenant, config, events, outbox, notifications, unitOfWork, programSettings, rewardIssuer } = input;
 	const tenantPlugins = tenant?.enabled ? [multiTenantPlugin({
 		tenantField: tenant.tenantField,
 		contextKey: tenant.contextKey,
@@ -2183,10 +3223,14 @@ function createRepositories(input) {
 	const tierDefinition = new TierDefinitionRepository(models.TierDefinition, withTenant(plugins?.tierDefinition));
 	const redemption = new RedemptionRepository(models.Redemption, withTenant(plugins?.redemption));
 	const referral = new ReferralRepository(models.Referral, withTenant(plugins?.referral));
+	const stampProgram = new StampProgramRepository(models.StampProgram, withTenant(plugins?.stampProgram));
+	const stamps = new StampRepository(models.StampEntry, withTenant(plugins?.stampEntry));
+	const stampAward = new StampAwardRepository(models.StampAward, withTenant(plugins?.stampAward));
 	member.events = events;
 	member.outbox = outbox;
 	member.notifications = notifications;
 	member.config = config;
+	member.tierRepo = tierDefinition;
 	pointTransaction.memberRepo = member;
 	pointTransaction.events = events;
 	pointTransaction.outbox = outbox;
@@ -2195,6 +3239,9 @@ function createRepositories(input) {
 	pointTransaction.config = config;
 	earningRule.memberRepo = member;
 	earningRule.txRepo = pointTransaction;
+	earningRule.tierRepo = tierDefinition;
+	pointTransaction.program = programSettings;
+	redemption.program = programSettings;
 	earningRule.config = config;
 	tierDefinition.memberRepo = member;
 	tierDefinition.events = events;
@@ -2214,14 +3261,29 @@ function createRepositories(input) {
 	referral.outbox = outbox;
 	referral.notifications = notifications;
 	referral.config = config;
+	stampProgram.config = config;
+	stampProgram.rewardIssuer = rewardIssuer;
+	stampAward.config = config;
+	stamps.memberRepo = member;
+	stamps.txRepo = pointTransaction;
+	stamps.programRepo = stampProgram;
+	stamps.awardRepo = stampAward;
+	stamps.events = events;
+	stamps.outbox = outbox;
+	stamps.unitOfWork = unitOfWork;
+	stamps.config = config;
+	stamps.rewardIssuer = rewardIssuer;
 	return {
 		member,
 		pointTransaction,
 		earningRule,
 		tierDefinition,
 		redemption,
-		referral
+		referral,
+		stampProgram,
+		stamps,
+		stampAward
 	};
 }
 //#endregion
-export { SessionNotInTransactionError as C, ValidationError as D, UnmanagedSessionError as E, SelfReferralError as S, TierNotFoundError as T, RedemptionExpiredError as _, PointTransactionRepository as a, ReferralNotFoundError as b, flushPendingLoyaltyEvents as c, DuplicateReferralError as d, InsufficientPointsError as f, MemberNotFoundError as g, MemberInactiveError as h, RedemptionRepository as i, EarningRuleRepository as l, MemberAlreadyEnrolledError as m, TierDefinitionRepository as n, MemberRepository as o, LoyaltyCapabilityError as p, ReferralRepository as r, PENDING_EVENTS as s, createRepositories as t, CircularReferralError as u, RedemptionNotFoundError as v, TenantIsolationError as w, RuleNotFoundError as x, ReferralLimitExceededError as y };
+export { SessionNotInTransactionError as A, MemberNotFoundError as C, ReferralNotFoundError as D, ReferralLimitExceededError as E, TierNotFoundError as M, UnmanagedSessionError as N, RuleNotFoundError as O, ValidationError as P, MemberInactiveError as S, RedemptionNotFoundError as T, CircularReferralError as _, StampRepository as a, LoyaltyCapabilityError as b, stampProgramPatchSchema as c, RedemptionRepository as d, PointTransactionRepository as f, EarningRuleRepository as g, flushPendingLoyaltyEvents as h, StampAwardRepository as i, TenantIsolationError as j, SelfReferralError as k, stampsForOrder as l, PENDING_EVENTS as m, TierDefinitionRepository as n, assertStampProgram as o, MemberRepository as p, StampProgramRepository as r, stampProgramInputSchema as s, createRepositories as t, ReferralRepository as u, DuplicateReferralError as v, RedemptionExpiredError as w, MemberAlreadyEnrolledError as x, InsufficientPointsError as y };