@classytic/promo 0.2.5 → 0.4.0

package/dist/index.mjs

@@ -1,10 +1,11 @@
-import { C as VoucherExhaustedError, E as PromoError, S as ValidationError, T as VoucherNotFoundError, _ as ProgramNotFoundError, a as PROGRAM_TYPES, b as RuleNotFoundError, c as TRIGGER_MODES, d as ConcurrencyConflictError, f as DuplicateRedemptionError, g as InvalidTransitionError, h as InsufficientBalanceError, i as PROGRAM_STATUSES, l as VOUCHER_STATUSES, m as GiftCardExhaustedError, n as DISCOUNT_SCOPES, o as REWARD_TYPES, p as EvaluationNotFoundError, r as PROGRAM_MACHINE, s as STACKING_MODES, t as DISCOUNT_MODES, u as CartHashMismatchError, v as ProgramUsageCapExceededError, w as VoucherExpiredError, x as TenantIsolationError, y as RewardNotFoundError } from "./constants-BB5O8zlN.mjs";
-import { Repository, multiTenantPlugin, withTransaction } from "@classytic/mongokit";
+import { C as TenantIsolationError, D as VoucherNotFoundError, E as VoucherExpiredError, O as PromoError, S as RuleNotFoundError, T as VoucherExhaustedError, _ as InvalidTransitionError, a as PROGRAM_TYPES, b as PromoModelCollisionError, c as TRIGGER_MODES, d as ConcurrencyConflictError, f as DuplicateRedemptionError, g as InsufficientBalanceError, h as GiftCardExhaustedError, i as PROGRAM_STATUSES, l as VOUCHER_STATUSES, m as EvaluationNotFoundError, n as DISCOUNT_SCOPES, o as REWARD_TYPES, p as DuplicateVoucherCodeError, r as PROGRAM_MACHINE, s as STACKING_MODES, t as DISCOUNT_MODES, u as CartHashMismatchError, v as ProgramNotFoundError, w as ValidationError, x as RewardNotFoundError, y as ProgramUsageCapExceededError } from "./constants-BE886vJk.mjs";
+import { S as PromoEvents, _ as VoucherCancelled, a as GiftCardSpent, b as VoucherRedeemed, c as ProgramArchived, d as RewardAdded, f as RewardRemoved, g as RuleUpdated, h as RuleRemoved, i as GiftCardExhausted, l as ProgramCreated, m as RuleAdded, n as EvaluationCompleted, o as GiftCardToppedUp, p as RewardUpdated, r as EvaluationRolledBack, s as ProgramActivated, t as EvaluationCommitted, u as ProgramPaused, v as VoucherExpired, x as promoEventDefinitions, y as VoucherGenerated } from "./promo-event-catalog-Dyh0xQ6w.mjs";
+import { Repository, isDuplicateKeyError, multiTenantPlugin, withTransaction } from "@classytic/mongokit";
 import { resolveTenantConfig } from "@classytic/repo-core/tenant";
 import { createEvent, matchEventPattern } from "@classytic/primitives/events";
 import mongoose, { Schema } from "mongoose";
+import { throwIfAborted } from "@classytic/repo-core/repository";
 import { createHash, randomBytes } from "node:crypto";
-import { z } from "zod";
 //#region src/events/in-process-bus.ts
 var InProcessPromoBus = class {
 	name = "in-process-promo";
@@ -367,6 +368,21 @@ const MODEL_NAMES = [
 	"PromoVoucher",
 	"PromoPendingEvaluation"
 ];
+/**
+* Explicit physical collection names (PACKAGE_RULES §20.1) — the values
+* Mongoose's pluralizer produced before they were pinned, so existing
+* deployments keep their data with zero migration. Passed as the third
+* arg of `connection.model()` so a host that disables/changes the
+* pluralizer can't silently rename collections. Changing any entry is a
+* BREAKING change (renames the physical collection — ship a migration).
+*/
+const DEFAULT_COLLECTIONS = {
+	PromoProgram: "promoprograms",
+	PromoRule: "promorules",
+	PromoReward: "promorewards",
+	PromoVoucher: "promovouchers",
+	PromoPendingEvaluation: "promopendingevaluations"
+};
 function applyAutoIndex(models, autoIndex) {
 	if (autoIndex === void 0) return;
 	for (const [configKey, modelKey] of [
@@ -379,8 +395,11 @@ function applyAutoIndex(models, autoIndex) {
 		if (value !== void 0) models[modelKey].schema.set("autoIndex", value);
 	}
 }
-function createModels(connection, tenant, indexes, autoIndex) {
-	for (const name of MODEL_NAMES) if (connection.models[name]) connection.deleteModel(name);
+function createModels(connection, tenant, options = {}) {
+	const { indexes, autoIndex } = options;
+	if (options.forceRecreate) {
+		for (const name of MODEL_NAMES) if (connection.models[name]) connection.deleteModel(name);
+	} else for (const name of MODEL_NAMES) if (connection.models[name]) throw new PromoModelCollisionError(name);
 	const programSchema = createProgramSchema();
 	const ruleSchema = createRuleSchema();
 	const rewardSchema = createRewardSchema();
@@ -396,12 +415,13 @@ function createModels(connection, tenant, indexes, autoIndex) {
 	if (indexes?.rule) applyUserIndexes(ruleSchema, indexes.rule, tenant);
 	if (indexes?.reward) applyUserIndexes(rewardSchema, indexes.reward, tenant);
 	if (indexes?.voucher) applyUserIndexes(voucherSchema, indexes.voucher, tenant);
+	const prefix = options.collectionPrefix ?? "";
 	const result = {
-		Program: connection.model("PromoProgram", programSchema),
-		Rule: connection.model("PromoRule", ruleSchema),
-		Reward: connection.model("PromoReward", rewardSchema),
-		Voucher: connection.model("PromoVoucher", voucherSchema),
-		PendingEvaluation: connection.model("PromoPendingEvaluation", pendingEvaluationSchema)
+		Program: connection.model("PromoProgram", programSchema, prefix + DEFAULT_COLLECTIONS.PromoProgram),
+		Rule: connection.model("PromoRule", ruleSchema, prefix + DEFAULT_COLLECTIONS.PromoRule),
+		Reward: connection.model("PromoReward", rewardSchema, prefix + DEFAULT_COLLECTIONS.PromoReward),
+		Voucher: connection.model("PromoVoucher", voucherSchema, prefix + DEFAULT_COLLECTIONS.PromoVoucher),
+		PendingEvaluation: connection.model("PromoPendingEvaluation", pendingEvaluationSchema, prefix + DEFAULT_COLLECTIONS.PromoPendingEvaluation)
 	};
 	applyAutoIndex(result, autoIndex);
 	return result;
@@ -490,8 +510,18 @@ var PendingEvaluationRepository = class extends Repository {
 //#endregion
 //#region src/events/dispatch.ts
 /**
+* Context key for the post-commit publish queue. Promo's transactional
+* verbs attach it automatically when they own the transaction; hosts that
+* own the outer transaction (`ctx.session`) MAY attach their own array and
+* drain it with {@link flushPendingPromoEvents} after commit for strict
+* no-ghost-event semantics. Symbol-keyed so it survives `{ ...ctx }`
+* spreads but never collides with host context fields.
+*/
+const PENDING_PROMO_EVENTS = Symbol.for("@classytic/promo:pendingEvents");
+/**
 * Canonical P8 shape — save to outbox first (with `ctx.session` when
-* present), then publish to transport. Both paths run independently.
+* present), then publish to transport (deferred to the pending queue when
+* one is attached — see module doc for the three regimes).
 */
 async function dispatchPromoEvent(deps, event, ctx) {
 	const logger = deps.logger ?? console;
@@ -503,47 +533,57 @@ async function dispatchPromoEvent(deps, event, ctx) {
 		logger.error(`[promo] outbox.save failed for ${event.type}:`, err);
 		throw err;
 	}
+	const pending = ctx?.[PENDING_PROMO_EVENTS];
+	if (pending) {
+		pending.push(event);
+		return;
+	}
 	if (deps.events) try {
 		await deps.events.publish(event);
 	} catch (err) {
 		logger.error(`[promo] events.publish failed for ${event.type}:`, err);
 	}
 }
-//#endregion
-//#region src/events/event-constants.ts
-const PromoEvents = {
-	PROGRAM_CREATED: "promo.program.created",
-	PROGRAM_ACTIVATED: "promo.program.activated",
-	PROGRAM_PAUSED: "promo.program.paused",
-	PROGRAM_ARCHIVED: "promo.program.archived",
-	RULE_ADDED: "promo.rule.added",
-	RULE_UPDATED: "promo.rule.updated",
-	RULE_REMOVED: "promo.rule.removed",
-	REWARD_ADDED: "promo.reward.added",
-	REWARD_UPDATED: "promo.reward.updated",
-	REWARD_REMOVED: "promo.reward.removed",
-	VOUCHER_GENERATED: "promo.voucher.generated",
-	VOUCHER_REDEEMED: "promo.voucher.redeemed",
-	VOUCHER_CANCELLED: "promo.voucher.cancelled",
-	VOUCHER_EXPIRED: "promo.voucher.expired",
-	GIFT_CARD_SPENT: "promo.gift_card.spent",
-	GIFT_CARD_TOPPED_UP: "promo.gift_card.topped_up",
-	GIFT_CARD_EXHAUSTED: "promo.gift_card.exhausted",
-	EVALUATION_COMPLETED: "promo.evaluation.completed",
-	EVALUATION_COMMITTED: "promo.evaluation.committed",
-	EVALUATION_ROLLED_BACK: "promo.evaluation.rolled_back"
-};
+/**
+* Drain a pending-events queue through the transport, swallowing per-event
+* publish errors (durable delivery is the outbox's job). Promo's
+* transactional verbs call this after commit; hosts that attached their own
+* `[PENDING_PROMO_EVENTS]` queue call it after their outer transaction
+* commits. The queue is emptied in place.
+*/
+async function flushPendingPromoEvents(deps, events) {
+	if (events.length === 0) return;
+	const logger = deps.logger ?? console;
+	const drained = events.splice(0, events.length);
+	if (!deps.events) return;
+	for (const event of drained) try {
+		await deps.events.publish(event);
+	} catch (err) {
+		logger.error(`[promo] events.publish failed for ${event.type}:`, err);
+	}
+}
 //#endregion
 //#region src/events/helpers.ts
 function createEvent$1(type, payload, ctx, meta) {
 	return createEvent(type, payload, {
 		resource: "promo",
-		...ctx?.actorId !== void 0 ? { userId: ctx.actorId } : {},
+		...ctx?.actorRef !== void 0 ? { userId: ctx.actorRef } : {},
 		...ctx?.organizationId !== void 0 ? { organizationId: ctx.organizationId } : {},
 		...meta
 	});
 }
 //#endregion
+//#region src/repositories/repo-options.ts
+function repoOptionsFromCtx(ctx) {
+	const out = {};
+	if (!ctx) return out;
+	for (const key of Object.keys(ctx)) {
+		const value = ctx[key];
+		if (value !== void 0) out[key] = value;
+	}
+	return out;
+}
+//#endregion
 //#region src/repositories/program.repository.ts
 var ProgramRepository = class extends Repository {
 	dispatchDeps;
@@ -564,14 +604,14 @@ var ProgramRepository = class extends Repository {
 		const program = await this.getById(id, {
 			throwOnNotFound: false,
 			lean: true,
-			...ctx
+			...repoOptionsFromCtx(ctx)
 		});
 		if (!program) throw new ProgramNotFoundError(id);
 		PROGRAM_MACHINE.assertTransition(String(program._id), program.status, targetStatus);
 		const updated = await this.update(id, { status: targetStatus }, {
 			throwOnNotFound: true,
 			lean: true,
-			...ctx
+			...repoOptionsFromCtx(ctx)
 		});
 		if (!updated) throw new ProgramNotFoundError(id);
 		const eventName = {
@@ -583,7 +623,7 @@ var ProgramRepository = class extends Repository {
 			programId: updated._id,
 			programType: updated.programType,
 			status: updated.status,
-			actorId: ctx.actorId
+			actorRef: ctx.actorRef
 		}, ctx), ctx);
 		return updated;
 	}
@@ -732,13 +772,13 @@ var VoucherRepository = class extends Repository {
 		const voucher = await this.getById(id, {
 			throwOnNotFound: false,
 			lean: true,
-			...ctx
+			...repoOptionsFromCtx(ctx)
 		});
 		if (!voucher) throw new VoucherNotFoundError(id);
 		const updated = await this.update(id, { status: "cancelled" }, {
 			throwOnNotFound: true,
 			lean: true,
-			...ctx
+			...repoOptionsFromCtx(ctx)
 		});
 		if (!updated) throw new VoucherNotFoundError(id);
 		await dispatchPromoEvent(this.dispatchDeps, createEvent$1(PromoEvents.VOUCHER_CANCELLED, {
@@ -798,11 +838,14 @@ var VoucherRepository = class extends Repository {
 			...ctx
 		});
 		let modified = 0;
-		for (const doc of docs) if (await this.update(doc._id, { status: "expired" }, {
-			throwOnNotFound: false,
-			lean: true,
-			...ctx
-		})) modified++;
+		for (const doc of docs) {
+			throwIfAborted(ctx?.signal);
+			if (await this.update(doc._id, { status: "expired" }, {
+				throwOnNotFound: false,
+				lean: true,
+				...ctx
+			})) modified++;
+		}
 		return modified;
 	}
 	/**
@@ -898,7 +941,7 @@ var MongoEvaluationStore = class {
 		if (tenantField && tenantValue !== void 0) update[tenantField] = tenantValue;
 		await this.repo.Model.updateOne(filter, { $set: update }, {
 			upsert: true,
-			session
+			...session !== void 0 ? { session } : {}
 		});
 	}
 	async take(id, ctx) {
@@ -1050,23 +1093,37 @@ var EvaluationService = class {
 	}
 	async commit(evaluationId, orderId, ctx, options = {}) {
 		let snapshotForCapMapping = null;
+		const run = async (txCtx) => {
+			const session = txCtx.session;
+			const stored = await this.store.take(evaluationId, {
+				tenantValue: ctx.organizationId,
+				session
+			});
+			if (!stored) throw new EvaluationNotFoundError(evaluationId);
+			if (options.cartHash !== void 0 && options.cartHash !== stored.cartHash) throw new CartHashMismatchError(evaluationId);
+			snapshotForCapMapping = stored;
+			return await this.commitInTransaction(stored, evaluationId, orderId, txCtx);
+		};
 		try {
-			return await this.unitOfWork.withTransaction(async (session) => {
-				const stored = await this.store.take(evaluationId, {
-					tenantValue: ctx.organizationId,
-					session
+			if (ctx.session) return await run(ctx);
+			const pending = [];
+			const result = await this.unitOfWork.withTransaction((session) => {
+				pending.length = 0;
+				return run({
+					...ctx,
+					session,
+					[PENDING_PROMO_EVENTS]: pending
 				});
-				if (!stored) throw new EvaluationNotFoundError(evaluationId);
-				if (options.cartHash !== void 0 && options.cartHash !== stored.cartHash) throw new CartHashMismatchError(evaluationId);
-				snapshotForCapMapping = stored;
-				return await this.commitInTransaction(stored, evaluationId, orderId, session, ctx);
 			});
+			await flushPendingPromoEvents(this.dispatchDeps, pending);
+			return result;
 		} catch (err) {
 			if (isWriteConflict(err) && snapshotForCapMapping) {
 				const firstUsage = snapshotForCapMapping.programUsages[0];
 				if (firstUsage) {
+					const { session: _aborted, ...readCtx } = ctx;
 					const program = await this.programRepo.getById(firstUsage.programId, {
-						...ctx,
+						...repoOptionsFromCtx(readCtx),
 						lean: true,
 						throwOnNotFound: false
 					});
@@ -1076,15 +1133,17 @@ var EvaluationService = class {
 			throw err;
 		}
 	}
-	async commitInTransaction(stored, evaluationId, orderId, session, ctx) {
+	async commitInTransaction(stored, evaluationId, orderId, txCtx) {
+		const ctx = txCtx;
+		const session = txCtx.session;
 		for (const usage of stored.programUsages) {
+			throwIfAborted(txCtx.signal);
 			if (!await this.programRepo.tryIncrementUsage(usage.programId, {
 				...ctx,
 				session
 			})) {
 				const program = await this.programRepo.getById(usage.programId, {
-					...ctx,
-					session,
+					...repoOptionsFromCtx(ctx),
 					lean: true,
 					throwOnNotFound: false
 				});
@@ -1115,14 +1174,14 @@ var EvaluationService = class {
 			evaluationId,
 			orderId,
 			totalDiscount: stored.result.totalDiscount
-		}, ctx), {
-			...ctx,
-			session
-		});
+		}, txCtx), txCtx);
 		return commitResult;
 	}
 	async rollback(evaluationId, ctx) {
-		await this.store.delete(evaluationId, { tenantValue: ctx.organizationId });
+		await this.store.delete(evaluationId, {
+			tenantValue: ctx.organizationId,
+			session: ctx.session
+		});
 		await dispatchPromoEvent(this.dispatchDeps, createEvent$1(PromoEvents.EVALUATION_ROLLED_BACK, { evaluationId }, ctx), ctx);
 	}
 	async doEvaluate(input, ctx, isPreview) {
@@ -1145,7 +1204,7 @@ var EvaluationService = class {
 		};
 		const programs = await this.programRepo.findActive(void 0, ctx);
 		const programIds = programs.map((p) => p._id);
-		const [allRules, allRewards] = await Promise.all([this.ruleRepo.findAll({ programId: { $in: programIds } }, ctx), this.rewardRepo.findAll({ programId: { $in: programIds } }, ctx)]);
+		const [allRules, allRewards] = await Promise.all([this.ruleRepo.findAll({ programId: { $in: programIds } }, repoOptionsFromCtx(ctx)), this.rewardRepo.findAll({ programId: { $in: programIds } }, repoOptionsFromCtx(ctx))]);
 		const rulesByProgram = groupBy(allRules, (r) => r.programId);
 		const rewardsByProgram = groupBy(allRewards, (r) => r.programId);
 		const voucherMap = /* @__PURE__ */ new Map();
@@ -1169,6 +1228,7 @@ var EvaluationService = class {
 		let exclusiveApplied = false;
 		let stackableCount = 0;
 		for (const program of programs) {
+			throwIfAborted(ctx.signal);
 			if (program.maxUsageTotal && program.usedCount >= program.maxUsageTotal) continue;
 			if (!this.isCustomerEligible(program, input)) continue;
 			if (program.maxUsagePerCustomer && input.customerId) {
@@ -1252,16 +1312,20 @@ var EvaluationService = class {
 			programsApplied
 		};
 		if (!isPreview) {
+			const { session: _liveSession, ...persistableCtx } = ctx;
 			const snapshot = {
 				result,
-				ctx,
+				ctx: persistableCtx,
 				customerId: input.customerId,
 				programUsages,
 				voucherUsages,
 				cartHash,
 				createdAt: /* @__PURE__ */ new Date()
 			};
-			await this.store.put(evaluationId, snapshot, DEFAULT_PENDING_EVALUATION_TTL_SECONDS, { tenantValue: ctx.organizationId });
+			await this.store.put(evaluationId, snapshot, DEFAULT_PENDING_EVALUATION_TTL_SECONDS, {
+				tenantValue: ctx.organizationId,
+				session: ctx.session
+			});
 		}
 		await dispatchPromoEvent(this.dispatchDeps, createEvent$1(PromoEvents.EVALUATION_COMPLETED, {
 			evaluationId,
@@ -1424,11 +1488,46 @@ var VoucherService = class {
 		this.dispatchDeps = dispatchDeps;
 		this.config = config;
 	}
+	/**
+	* Session threading — checkout-chain participation. When the host
+	* already owns a transaction (e.g. the cart → order → flow → promo →
+	* invoice chain runs as ONE atomic unit), it passes `ctx.session` and
+	* the transactional body JOINS that session: every write commits or
+	* aborts with the host's order. MongoDB has no nested transactions, so
+	* we must NOT open our own in that case — the host owns commit/abort/
+	* retry. Without a host session we own the transaction via the
+	* UnitOfWork (mongokit retry semantics included).
+	*
+	* **Post-commit publish (§P8 phased variant).** When promo owns the
+	* transaction, a pending queue is attached to the tx context so every
+	* `dispatchPromoEvent` inside the body defers its transport publish; the
+	* queue flushes only after the transaction commits — a rollback (or a
+	* transient retry of the body) can't leak ghost events to in-process
+	* subscribers. The queue resets at the start of each retry attempt.
+	* When the HOST owns the session, promo can't know when the host
+	* commits: with a host-attached `[PENDING_PROMO_EVENTS]` queue the
+	* deferral still applies (host flushes); without one, publish happens
+	* in-scope as the documented best effort (see events/dispatch.ts).
+	*/
+	async runTransactional(ctx, fn) {
+		if (ctx.session) return fn(ctx);
+		const pending = [];
+		const result = await this.unitOfWork.withTransaction((session) => {
+			pending.length = 0;
+			return fn({
+				...ctx,
+				session,
+				[PENDING_PROMO_EVENTS]: pending
+			});
+		});
+		await flushPendingPromoEvents(this.dispatchDeps, pending);
+		return result;
+	}
 	async generateCodes(input, ctx) {
 		const program = await this.programRepo.getById(input.programId, {
 			throwOnNotFound: false,
 			lean: true,
-			...ctx
+			...repoOptionsFromCtx(ctx)
 		});
 		if (!program) throw new ProgramNotFoundError(input.programId);
 		const { codeLength, codePrefix } = this.config.voucher;
@@ -1451,13 +1550,19 @@ var VoucherService = class {
 			redemptions: [],
 			...input.metadata ? { metadata: input.metadata } : {}
 		}));
-		const vouchers = await this.voucherRepo.createMany(data, ctx);
+		let vouchers;
+		try {
+			vouchers = await this.voucherRepo.createMany(data, repoOptionsFromCtx(ctx));
+		} catch (err) {
+			if (isDuplicateKeyError(err)) throw new DuplicateVoucherCodeError();
+			throw err;
+		}
 		await dispatchPromoEvent(this.dispatchDeps, createEvent$1(PromoEvents.VOUCHER_GENERATED, {
 			programId: input.programId,
 			voucherIds: vouchers.map((v) => v._id),
 			codes: vouchers.map((v) => v.code),
 			count: vouchers.length,
-			actorId: ctx.actorId
+			actorRef: ctx.actorRef
 		}, ctx), ctx);
 		return vouchers;
 	}
@@ -1465,7 +1570,7 @@ var VoucherService = class {
 		const program = await this.programRepo.getById(input.programId, {
 			throwOnNotFound: false,
 			lean: true,
-			...ctx
+			...repoOptionsFromCtx(ctx)
 		});
 		if (!program) throw new ProgramNotFoundError(input.programId);
 		const code = input.code?.toUpperCase() ?? generateCode(this.config.voucher.codeLength, this.config.voucher.codePrefix);
@@ -1488,13 +1593,19 @@ var VoucherService = class {
 			redemptions: [],
 			...input.metadata ? { metadata: input.metadata } : {}
 		};
-		const voucher = await this.voucherRepo.create(data, ctx);
+		let voucher;
+		try {
+			voucher = await this.voucherRepo.create(data, repoOptionsFromCtx(ctx));
+		} catch (err) {
+			if (isDuplicateKeyError(err)) throw new DuplicateVoucherCodeError(code);
+			throw err;
+		}
 		await dispatchPromoEvent(this.dispatchDeps, createEvent$1(PromoEvents.VOUCHER_GENERATED, {
 			programId: input.programId,
 			voucherIds: [voucher._id],
 			codes: [voucher.code],
 			count: 1,
-			actorId: ctx.actorId
+			actorRef: ctx.actorRef
 		}, ctx), ctx);
 		return voucher;
 	}
@@ -1527,7 +1638,7 @@ var VoucherService = class {
 		const program = await this.programRepo.getById(voucher.programId, {
 			throwOnNotFound: false,
 			lean: true,
-			...ctx
+			...repoOptionsFromCtx(ctx)
 		});
 		return {
 			valid: true,
@@ -1543,18 +1654,12 @@ var VoucherService = class {
 		};
 	}
 	async redeem(input, ctx) {
-		return this.unitOfWork.withTransaction(async (session) => {
-			const voucher = await this.voucherRepo.getByCode(input.code, {
-				...ctx,
-				session
-			});
+		return this.runTransactional(ctx, async (txCtx) => {
+			const voucher = await this.voucherRepo.getByCode(input.code, txCtx);
 			if (!voucher) throw new VoucherNotFoundError(input.code);
 			this.assertVoucherUsable(voucher);
 			if (input.idempotencyKey) {
-				if (await this.voucherRepo.hasIdempotencyKey(voucher._id, input.idempotencyKey, {
-					...ctx,
-					session
-				})) throw new DuplicateRedemptionError(input.idempotencyKey);
+				if (await this.voucherRepo.hasIdempotencyKey(voucher._id, input.idempotencyKey, txCtx)) throw new DuplicateRedemptionError(input.idempotencyKey);
 			}
 			const redemption = {
 				orderId: input.orderId,
@@ -1564,14 +1669,10 @@ var VoucherService = class {
 				...input.idempotencyKey ? { idempotencyKey: input.idempotencyKey } : {},
 				...ctx.organizationId !== void 0 ? { organizationId: ctx.organizationId } : {}
 			};
-			const updated = await this.voucherRepo.incrementUsage(voucher._id, redemption, {
-				...ctx,
-				session
-			});
+			const updated = await this.voucherRepo.incrementUsage(voucher._id, redemption, txCtx);
 			if (updated.usedCount >= updated.usageLimit) await this.voucherRepo.update(voucher._id, { status: "used" }, {
 				lean: true,
-				...ctx,
-				session
+				...repoOptionsFromCtx(txCtx)
 			});
 			await dispatchPromoEvent(this.dispatchDeps, createEvent$1(PromoEvents.VOUCHER_REDEEMED, {
 				voucherId: voucher._id,
@@ -1579,10 +1680,7 @@ var VoucherService = class {
 				orderId: input.orderId,
 				discountAmount: input.discountAmount,
 				customerId: input.customerId
-			}, ctx), {
-				...ctx,
-				session
-			});
+			}, txCtx), txCtx);
 			return updated;
 		});
 	}
@@ -1608,20 +1706,14 @@ var VoucherService = class {
 		}
 	}
 	async spendInTransaction(input, ctx) {
-		return this.unitOfWork.withTransaction(async (session) => {
-			const voucher = await this.voucherRepo.getByCode(input.code, {
-				...ctx,
-				session
-			});
+		return this.runTransactional(ctx, async (txCtx) => {
+			const voucher = await this.voucherRepo.getByCode(input.code, txCtx);
 			if (!voucher) throw new VoucherNotFoundError(input.code);
 			this.assertVoucherUsable(voucher);
 			const balance = voucher.currentBalance ?? 0;
 			if (!this.config.giftCard.allowNegativeBalance && balance < input.amount) throw new InsufficientBalanceError(input.code, balance, input.amount);
 			if (input.idempotencyKey) {
-				if (await this.voucherRepo.hasIdempotencyKey(voucher._id, input.idempotencyKey, {
-					...ctx,
-					session
-				})) throw new DuplicateRedemptionError(input.idempotencyKey);
+				if (await this.voucherRepo.hasIdempotencyKey(voucher._id, input.idempotencyKey, txCtx)) throw new DuplicateRedemptionError(input.idempotencyKey);
 			}
 			const entry = {
 				amount: -input.amount,
@@ -1631,10 +1723,7 @@ var VoucherService = class {
 				...input.idempotencyKey ? { idempotencyKey: input.idempotencyKey } : {},
 				...ctx.organizationId !== void 0 ? { organizationId: ctx.organizationId } : {}
 			};
-			const updated = await this.voucherRepo.addLedgerEntry(voucher._id, entry, -input.amount, {
-				...ctx,
-				session
-			});
+			const updated = await this.voucherRepo.addLedgerEntry(voucher._id, entry, -input.amount, txCtx);
 			const newBalance = updated.currentBalance ?? 0;
 			await dispatchPromoEvent(this.dispatchDeps, createEvent$1(PromoEvents.GIFT_CARD_SPENT, {
 				voucherId: voucher._id,
@@ -1642,24 +1731,17 @@ var VoucherService = class {
 				amount: input.amount,
 				remainingBalance: newBalance,
 				orderId: input.orderId
-			}, ctx), {
-				...ctx,
-				session
-			});
+			}, txCtx), txCtx);
 			if (newBalance <= 0) {
 				await this.voucherRepo.update(voucher._id, { status: "used" }, {
 					lean: true,
-					...ctx,
-					session
+					...repoOptionsFromCtx(txCtx)
 				});
 				await dispatchPromoEvent(this.dispatchDeps, createEvent$1(PromoEvents.GIFT_CARD_EXHAUSTED, {
 					voucherId: voucher._id,
 					code: voucher.code,
 					status: "used"
-				}, ctx), {
-					...ctx,
-					session
-				});
+				}, txCtx), txCtx);
 			}
 			return {
 				code: updated.code,
@@ -1680,19 +1762,13 @@ var VoucherService = class {
 		}
 	}
 	async topUpInTransaction(input, ctx) {
-		return this.unitOfWork.withTransaction(async (session) => {
-			const voucher = await this.voucherRepo.getByCode(input.code, {
-				...ctx,
-				session
-			});
+		return this.runTransactional(ctx, async (txCtx) => {
+			const voucher = await this.voucherRepo.getByCode(input.code, txCtx);
 			if (!voucher) throw new VoucherNotFoundError(input.code);
 			const maxBalance = this.config.giftCard.maxBalance;
 			if (maxBalance !== null && (voucher.currentBalance ?? 0) + input.amount > maxBalance) throw new ValidationError(`Top-up would exceed max balance of ${maxBalance}`);
 			if (input.idempotencyKey) {
-				if (await this.voucherRepo.hasIdempotencyKey(voucher._id, input.idempotencyKey, {
-					...ctx,
-					session
-				})) throw new DuplicateRedemptionError(input.idempotencyKey);
+				if (await this.voucherRepo.hasIdempotencyKey(voucher._id, input.idempotencyKey, txCtx)) throw new DuplicateRedemptionError(input.idempotencyKey);
 			}
 			const entry = {
 				amount: input.amount,
@@ -1701,24 +1777,17 @@ var VoucherService = class {
 				...input.idempotencyKey ? { idempotencyKey: input.idempotencyKey } : {},
 				...ctx.organizationId !== void 0 ? { organizationId: ctx.organizationId } : {}
 			};
-			const updated = await this.voucherRepo.addLedgerEntry(voucher._id, entry, input.amount, {
-				...ctx,
-				session
-			});
+			const updated = await this.voucherRepo.addLedgerEntry(voucher._id, entry, input.amount, txCtx);
 			if (voucher.status === "used") await this.voucherRepo.update(voucher._id, { status: "active" }, {
 				lean: true,
-				...ctx,
-				session
+				...repoOptionsFromCtx(txCtx)
 			});
 			await dispatchPromoEvent(this.dispatchDeps, createEvent$1(PromoEvents.GIFT_CARD_TOPPED_UP, {
 				voucherId: voucher._id,
 				code: voucher.code,
 				amount: input.amount,
 				newBalance: updated.currentBalance ?? 0
-			}, ctx), {
-				...ctx,
-				session
-			});
+			}, txCtx), txCtx);
 			return {
 				code: updated.code,
 				initialBalance: updated.initialBalance ?? 0,
@@ -1751,229 +1820,6 @@ function createServices(deps) {
 	};
 }
 //#endregion
-//#region src/events/promo-event-catalog.ts
-function definePromoEvent(input) {
-	const { name, version = 1, description, zodSchema } = input;
-	const def = {
-		name,
-		version,
-		schema: z.toJSONSchema(zodSchema),
-		zodSchema,
-		create(payload, meta) {
-			return createEvent(name, payload, {
-				source: "promo",
-				...meta
-			});
-		}
-	};
-	if (description !== void 0) def.description = description;
-	return def;
-}
-/** Mirrors `ProgramLifecyclePayload`. */
-const programLifecycleSchema = z.object({
-	programId: z.string(),
-	programType: z.string(),
-	status: z.string(),
-	actorId: z.string().optional()
-});
-/** Mirrors `RulePayload`. */
-const ruleSchema = z.object({
-	programId: z.string(),
-	ruleId: z.string(),
-	actorId: z.string().optional()
-});
-/** Mirrors `RewardPayload`. */
-const rewardSchema = z.object({
-	programId: z.string(),
-	rewardId: z.string(),
-	actorId: z.string().optional()
-});
-/** Mirrors `VoucherGeneratedPayload`. */
-const voucherGeneratedSchema = z.object({
-	programId: z.string(),
-	voucherIds: z.array(z.string()),
-	codes: z.array(z.string()),
-	count: z.number().int().nonnegative(),
-	actorId: z.string().optional()
-});
-/** Mirrors `VoucherRedeemedPayload`. */
-const voucherRedeemedSchema = z.object({
-	voucherId: z.string(),
-	code: z.string(),
-	orderId: z.string(),
-	discountAmount: z.number(),
-	customerId: z.string().optional()
-});
-/**
-* Mirrors `VoucherLifecyclePayload` — shared by VOUCHER_CANCELLED,
-* VOUCHER_EXPIRED, and GIFT_CARD_EXHAUSTED (repo emits `status: 'cancelled'`
-* / `'used'` / host-supplied terminal value).
-*/
-const voucherLifecycleSchema = z.object({
-	voucherId: z.string(),
-	code: z.string(),
-	status: z.string()
-});
-/** Mirrors `GiftCardSpentPayload`. */
-const giftCardSpentSchema = z.object({
-	voucherId: z.string(),
-	code: z.string(),
-	amount: z.number(),
-	remainingBalance: z.number(),
-	orderId: z.string()
-});
-/** Mirrors `GiftCardToppedUpPayload`. */
-const giftCardToppedUpSchema = z.object({
-	voucherId: z.string(),
-	code: z.string(),
-	amount: z.number(),
-	newBalance: z.number()
-});
-/** Mirrors `EvaluationCompletedPayload`. */
-const evaluationCompletedSchema = z.object({
-	evaluationId: z.string(),
-	totalDiscount: z.number(),
-	programsApplied: z.number().int().nonnegative(),
-	codesUsed: z.array(z.string()),
-	isPreview: z.boolean()
-});
-/** Mirrors `EvaluationCommittedPayload`. */
-const evaluationCommittedSchema = z.object({
-	evaluationId: z.string(),
-	orderId: z.string(),
-	totalDiscount: z.number()
-});
-/** Single-field rollback payload — emitted by `evaluation.service.ts`. */
-const evaluationRolledBackSchema = z.object({ evaluationId: z.string() });
-const ProgramCreated = definePromoEvent({
-	name: PromoEvents.PROGRAM_CREATED,
-	description: "A new promo program was created (starts in draft).",
-	zodSchema: programLifecycleSchema
-});
-const ProgramActivated = definePromoEvent({
-	name: PromoEvents.PROGRAM_ACTIVATED,
-	description: "A draft or paused program was activated.",
-	zodSchema: programLifecycleSchema
-});
-const ProgramPaused = definePromoEvent({
-	name: PromoEvents.PROGRAM_PAUSED,
-	description: "An active program was paused.",
-	zodSchema: programLifecycleSchema
-});
-const ProgramArchived = definePromoEvent({
-	name: PromoEvents.PROGRAM_ARCHIVED,
-	description: "A program was archived (terminal — no further transitions).",
-	zodSchema: programLifecycleSchema
-});
-const RuleAdded = definePromoEvent({
-	name: PromoEvents.RULE_ADDED,
-	description: "A new rule was added to a program.",
-	zodSchema: ruleSchema
-});
-const RuleUpdated = definePromoEvent({
-	name: PromoEvents.RULE_UPDATED,
-	description: "An existing rule on a program was updated.",
-	zodSchema: ruleSchema
-});
-const RuleRemoved = definePromoEvent({
-	name: PromoEvents.RULE_REMOVED,
-	description: "A rule was removed from a program.",
-	zodSchema: ruleSchema
-});
-const RewardAdded = definePromoEvent({
-	name: PromoEvents.REWARD_ADDED,
-	description: "A reward was added to a program.",
-	zodSchema: rewardSchema
-});
-const RewardUpdated = definePromoEvent({
-	name: PromoEvents.REWARD_UPDATED,
-	description: "A reward on a program was updated.",
-	zodSchema: rewardSchema
-});
-const RewardRemoved = definePromoEvent({
-	name: PromoEvents.REWARD_REMOVED,
-	description: "A reward was removed from a program.",
-	zodSchema: rewardSchema
-});
-const VoucherGenerated = definePromoEvent({
-	name: PromoEvents.VOUCHER_GENERATED,
-	description: "One or more vouchers were generated for a program.",
-	zodSchema: voucherGeneratedSchema
-});
-const VoucherRedeemed = definePromoEvent({
-	name: PromoEvents.VOUCHER_REDEEMED,
-	description: "A voucher was redeemed against an order.",
-	zodSchema: voucherRedeemedSchema
-});
-const VoucherCancelled = definePromoEvent({
-	name: PromoEvents.VOUCHER_CANCELLED,
-	description: "A voucher was cancelled by an operator.",
-	zodSchema: voucherLifecycleSchema
-});
-const VoucherExpired = definePromoEvent({
-	name: PromoEvents.VOUCHER_EXPIRED,
-	description: "A voucher reached its expiry date and was transitioned to expired.",
-	zodSchema: voucherLifecycleSchema
-});
-const GiftCardSpent = definePromoEvent({
-	name: PromoEvents.GIFT_CARD_SPENT,
-	description: "A gift-card voucher was debited against an order — remaining balance reported.",
-	zodSchema: giftCardSpentSchema
-});
-const GiftCardToppedUp = definePromoEvent({
-	name: PromoEvents.GIFT_CARD_TOPPED_UP,
-	description: "A gift-card voucher received a top-up — new balance reported.",
-	zodSchema: giftCardToppedUpSchema
-});
-const GiftCardExhausted = definePromoEvent({
-	name: PromoEvents.GIFT_CARD_EXHAUSTED,
-	description: "A gift-card voucher reached a zero balance and was marked used.",
-	zodSchema: voucherLifecycleSchema
-});
-const EvaluationCompleted = definePromoEvent({
-	name: PromoEvents.EVALUATION_COMPLETED,
-	description: "A cart evaluation finished (preview or pre-commit) — totals and applied codes reported.",
-	zodSchema: evaluationCompletedSchema
-});
-const EvaluationCommitted = definePromoEvent({
-	name: PromoEvents.EVALUATION_COMMITTED,
-	description: "A stored evaluation was committed against an order — usage counters moved.",
-	zodSchema: evaluationCommittedSchema
-});
-const EvaluationRolledBack = definePromoEvent({
-	name: PromoEvents.EVALUATION_ROLLED_BACK,
-	description: "A stored evaluation was discarded without commit.",
-	zodSchema: evaluationRolledBackSchema
-});
-/**
-* Every promo event defined in the package — pass to Arc's
-* `EventRegistry`. Hosts wire ONE array; the whole `promo.*` namespace
-* becomes introspectable via OpenAPI and auto-validated at publish time
-* when `eventPlugin({ validateMode: 'reject' })` is set.
-*/
-const promoEventDefinitions = [
-	ProgramCreated,
-	ProgramActivated,
-	ProgramPaused,
-	ProgramArchived,
-	RuleAdded,
-	RuleUpdated,
-	RuleRemoved,
-	RewardAdded,
-	RewardUpdated,
-	RewardRemoved,
-	VoucherGenerated,
-	VoucherRedeemed,
-	VoucherCancelled,
-	VoucherExpired,
-	GiftCardSpent,
-	GiftCardToppedUp,
-	GiftCardExhausted,
-	EvaluationCompleted,
-	EvaluationCommitted,
-	EvaluationRolledBack
-];
-//#endregion
 //#region src/index.ts
 function resolveConfig(config) {
 	const tenant = resolveTenantConfig(config.tenant);
@@ -2013,14 +1859,30 @@ function resolveConfig(config) {
 * that wires it. See packages/mongokit/src/transaction.ts.
 */
 var MongoUnitOfWork = class {
-	constructor(connection) {
+	constructor(connection, allowFallback = false) {
 		this.connection = connection;
+		this.allowFallback = allowFallback;
 	}
 	withTransaction(cb) {
-		return withTransaction(this.connection, cb);
+		return withTransaction(this.connection, cb, this.allowFallback ? { allowFallback: true } : {});
 	}
 };
 /**
+* Boot-time capability gate (PACKAGE_RULES "Runtime capabilities").
+* commit / redeem / spend / topUp are transactional — assert the backend
+* declares `transactions` at engine creation so misconfigured deployments
+* fail loud at boot instead of with a cryptic error on the first checkout.
+* `allowNonTransactional: true` is the explicit opt-out for standalone
+* MongoDB (dev / CI) — the unit-of-work then falls back to
+* non-transactional execution.
+*
+* Exported for unit testing; hosts never call it directly.
+*/
+function assertPromoCapabilities(capabilities) {
+	if (!capabilities) throw new Error("promo: backend declares no `capabilities` descriptor (repo-core 0.6 / mongokit 3.16+). Upgrade @classytic/mongokit, or pass `allowNonTransactional: true` to opt out.");
+	if (capabilities.transactions !== true) throw new Error("promo: backend missing required capability: transactions. commit/redeem/spend/topUp are transactional — MongoDB must run as a replica set. Pass `allowNonTransactional: true` to accept best-effort atomicity (dev/CI only).");
+}
+/**
 * Build the promo engine for a host application.
 *
 * **Index management — important for boot performance:**
@@ -2059,7 +1921,12 @@ var MongoUnitOfWork = class {
 */
 function createPromoEngine(config) {
 	const resolvedConfig = resolveConfig(config);
-	const models = createModels(config.mongoose, resolvedConfig.tenant, config.indexes, config.autoIndex);
+	const models = createModels(config.mongoose, resolvedConfig.tenant, {
+		indexes: config.indexes,
+		autoIndex: config.autoIndex,
+		collectionPrefix: config.collectionPrefix,
+		forceRecreate: config.forceRecreate
+	});
 	const events = config.events?.transport ?? new InProcessPromoBus();
 	const dispatchDeps = {
 		events,
@@ -2067,12 +1934,14 @@ function createPromoEngine(config) {
 		...config.logger !== void 0 ? { logger: config.logger } : {}
 	};
 	const repositories = createRepositories(models, config.plugins, resolvedConfig.tenant, dispatchDeps);
+	const allowNonTransactional = config.allowNonTransactional ?? false;
+	if (!allowNonTransactional) assertPromoCapabilities(repositories.program.capabilities);
 	return {
 		models,
 		repositories,
 		services: createServices({
 			repositories,
-			unitOfWork: new MongoUnitOfWork(config.mongoose),
+			unitOfWork: new MongoUnitOfWork(config.mongoose, allowNonTransactional),
 			dispatchDeps,
 			config: resolvedConfig,
 			...config.evaluationStore !== void 0 ? { evaluationStore: config.evaluationStore } : {}
@@ -2084,4 +1953,4 @@ function createPromoEngine(config) {
 	};
 }
 //#endregion
-export { CartHashMismatchError, ConcurrencyConflictError, DuplicateRedemptionError, EvaluationCommitted, EvaluationCompleted, EvaluationNotFoundError, EvaluationRolledBack, GiftCardExhausted, GiftCardExhaustedError, GiftCardSpent, GiftCardToppedUp, InMemoryEvaluationStore, InsufficientBalanceError, InvalidTransitionError, MongoEvaluationStore, PendingEvaluationRepository, ProgramActivated, ProgramArchived, ProgramCreated, ProgramNotFoundError, ProgramPaused, ProgramRepository, ProgramUsageCapExceededError, PromoError, PromoEvents, RewardAdded, RewardNotFoundError, RewardRemoved, RewardRepository, RewardUpdated, RuleAdded, RuleNotFoundError, RuleRemoved, RuleRepository, RuleUpdated, TenantIsolationError, ValidationError, VoucherCancelled, VoucherExhaustedError, VoucherExpired, VoucherExpiredError, VoucherGenerated, VoucherNotFoundError, VoucherRedeemed, VoucherRepository, createPromoEngine, promoEventDefinitions, resolveConfig };
+export { CartHashMismatchError, ConcurrencyConflictError, DEFAULT_COLLECTIONS, DuplicateRedemptionError, DuplicateVoucherCodeError, EvaluationCommitted, EvaluationCompleted, EvaluationNotFoundError, EvaluationRolledBack, GiftCardExhausted, GiftCardExhaustedError, GiftCardSpent, GiftCardToppedUp, InMemoryEvaluationStore, InsufficientBalanceError, InvalidTransitionError, MongoEvaluationStore, PENDING_PROMO_EVENTS, PendingEvaluationRepository, ProgramActivated, ProgramArchived, ProgramCreated, ProgramNotFoundError, ProgramPaused, ProgramRepository, ProgramUsageCapExceededError, PromoError, PromoEvents, PromoModelCollisionError, RewardAdded, RewardNotFoundError, RewardRemoved, RewardRepository, RewardUpdated, RuleAdded, RuleNotFoundError, RuleRemoved, RuleRepository, RuleUpdated, TenantIsolationError, ValidationError, VoucherCancelled, VoucherExhaustedError, VoucherExpired, VoucherExpiredError, VoucherGenerated, VoucherNotFoundError, VoucherRedeemed, VoucherRepository, assertPromoCapabilities, createPromoEngine, flushPendingPromoEvents, promoEventDefinitions, resolveConfig };