@classytic/promo 0.2.0 → 0.2.1

package/dist/index.mjs

@@ -1,8 +1,8 @@
 import { a as PROGRAM_TYPES, c as TRIGGER_MODES, i as PROGRAM_TRANSITIONS, l as VOUCHER_STATUSES, n as DISCOUNT_SCOPES, o as REWARD_TYPES, r as PROGRAM_STATUSES, s as STACKING_MODES, t as DISCOUNT_MODES } from "./constants-D0Rntp2f.mjs";
+import { Repository, multiTenantPlugin, withTransaction } from "@classytic/mongokit";
 import { resolveTenantConfig } from "@classytic/primitives/tenant";
 import { createEvent, matchEventPattern } from "@classytic/primitives/events";
-import mongoose from "mongoose";
-import { Repository, multiTenantPlugin } from "@classytic/mongokit";
+import mongoose, { Schema } from "mongoose";
 import { createHash, randomBytes } from "node:crypto";
 import { z } from "zod";
 //#region src/domain/errors/base.ts
@@ -23,6 +23,33 @@ var ProgramNotFoundError = class extends PromoError {
 		super(id ? `Program '${id}' not found` : "Program not found");
 	}
 };
+/**
+* Raised when a commit-time atomic CAS on `usedCount < maxUsageTotal`
+* fails — i.e. the program's cap was exhausted by another concurrent
+* commit between this caller's evaluate and its commit. The host should
+* surface this as a "promo no longer available" failure to the user; the
+* order itself can still proceed without the discount if the host wishes.
+*/
+var ProgramUsageCapExceededError = class extends PromoError {
+	code = "PROGRAM_USAGE_CAP_EXCEEDED";
+	constructor(programId, maxUsageTotal) {
+		super(`Program '${programId}' has reached its usage cap of ${maxUsageTotal}`);
+		this.programId = programId;
+		this.maxUsageTotal = maxUsageTotal;
+	}
+};
+var RuleNotFoundError = class extends PromoError {
+	code = "RULE_NOT_FOUND";
+	constructor(id) {
+		super(id ? `Rule '${id}' not found` : "Rule not found");
+	}
+};
+var RewardNotFoundError = class extends PromoError {
+	code = "REWARD_NOT_FOUND";
+	constructor(id) {
+		super(id ? `Reward '${id}' not found` : "Reward not found");
+	}
+};
 var VoucherNotFoundError = class extends PromoError {
 	code = "VOUCHER_NOT_FOUND";
 	constructor(codeOrId) {
@@ -81,6 +108,12 @@ var InsufficientBalanceError = class extends PromoError {
 		super(`Voucher '${code}' has insufficient balance: ${available} available, ${requested} requested`);
 	}
 };
+var TenantIsolationError = class extends PromoError {
+	code = "TENANT_ISOLATION";
+	constructor() {
+		super("Tenant context is required but was not provided");
+	}
+};
 var DuplicateRedemptionError = class extends PromoError {
 	code = "DUPLICATE_REDEMPTION";
 	constructor(key) {
@@ -169,10 +202,81 @@ function applyUserIndexes(schema, indexes, tenant) {
 	}
 }
 //#endregion
+//#region src/models/schemas/pending-evaluation.schema.ts
+/**
+* Persisted snapshot of an `evaluate()` outcome, awaiting a follow-up
+* `commit()` or `rollback()`.
+*
+* Why a Mongo collection (not a process-local Map): pending evaluations
+* MUST survive process restart, horizontal scaling, serverless cold
+* starts, and worker handoff. Stale snapshots auto-clean via the TTL
+* index — same pattern cart uses for guest drafts (see
+* cart/src/models/draft.model.ts:131-135).
+*
+* Stored fields are intentionally minimal — only what `commit()` and
+* `rollback()` need:
+*   - the materialised result (returned to caller for telemetry)
+*   - per-program / per-voucher usages (incremented atomically at commit)
+*   - cartHash (anti-tamper guard between evaluate and commit)
+*   - expiresAt (TTL drives auto-cleanup; engine never relies on it for
+*     correctness — the atomic `findOneAndDelete` in `take()` is the
+*     authoritative single-commit guard)
+*/
+function createPendingEvaluationSchema() {
+	return new Schema({
+		evaluationId: {
+			type: String,
+			required: true,
+			unique: true,
+			index: true
+		},
+		result: {
+			type: Schema.Types.Mixed,
+			required: true
+		},
+		ctx: {
+			type: Schema.Types.Mixed,
+			required: true
+		},
+		customerId: {
+			type: String,
+			default: null
+		},
+		programUsages: {
+			type: [Schema.Types.Mixed],
+			default: []
+		},
+		voucherUsages: {
+			type: [Schema.Types.Mixed],
+			default: []
+		},
+		cartHash: {
+			type: String,
+			required: true,
+			index: true
+		},
+		expiresAt: {
+			type: Date,
+			required: true
+		}
+	}, {
+		timestamps: true,
+		minimize: false
+	});
+}
+/**
+* Wire the TTL index. Mongo evaluates `expireAfterSeconds: 0` against the
+* `expiresAt` field's value — when `expiresAt < now`, the doc is purged
+* by the background TTL monitor (~60s granularity).
+*/
+function applyPendingEvaluationIndexes(schema) {
+	schema.index({ expiresAt: 1 }, { expireAfterSeconds: 0 });
+}
+//#endregion
 //#region src/models/schemas/program.schema.ts
-const { Schema: Schema$3 } = mongoose;
+const { Schema: Schema$4 } = mongoose;
 function createProgramSchema() {
-	const schema = new Schema$3({
+	const schema = new Schema$4({
 		name: {
 			type: String,
 			required: true
@@ -217,7 +321,7 @@ function createProgramSchema() {
 			of: Number,
 			default: () => /* @__PURE__ */ new Map()
 		},
-		metadata: { type: Schema$3.Types.Mixed }
+		metadata: { type: Schema$4.Types.Mixed }
 	}, { timestamps: true });
 	schema.index({
 		status: 1,
@@ -238,14 +342,14 @@ function createProgramSchema() {
 }
 //#endregion
 //#region src/models/schemas/reward.schema.ts
-const { Schema: Schema$2 } = mongoose;
+const { Schema: Schema$3 } = mongoose;
 function createRewardSchema() {
-	const schema = new Schema$2({
+	const schema = new Schema$3({
 		programId: {
-			type: Schema$2.Types.ObjectId,
+			type: Schema$3.Types.ObjectId,
 			required: true
 		},
-		ruleId: { type: Schema$2.Types.ObjectId },
+		ruleId: { type: Schema$3.Types.ObjectId },
 		rewardType: {
 			type: String,
 			enum: REWARD_TYPES,
@@ -270,7 +374,7 @@ function createRewardSchema() {
 			default: 1
 		},
 		giftCardAmount: { type: Number },
-		metadata: { type: Schema$2.Types.Mixed }
+		metadata: { type: Schema$3.Types.Mixed }
 	}, { timestamps: true });
 	schema.index({ programId: 1 });
 	schema.index({ ruleId: 1 }, { sparse: true });
@@ -278,11 +382,11 @@ function createRewardSchema() {
 }
 //#endregion
 //#region src/models/schemas/rule.schema.ts
-const { Schema: Schema$1 } = mongoose;
+const { Schema: Schema$2 } = mongoose;
 function createRuleSchema() {
-	const schema = new Schema$1({
+	const schema = new Schema$2({
 		programId: {
-			type: Schema$1.Types.ObjectId,
+			type: Schema$2.Types.ObjectId,
 			required: true
 		},
 		name: { type: String },
@@ -305,7 +409,7 @@ function createRuleSchema() {
 		},
 		startsAt: { type: Date },
 		endsAt: { type: Date },
-		metadata: { type: Schema$1.Types.Mixed }
+		metadata: { type: Schema$2.Types.Mixed }
 	}, { timestamps: true });
 	schema.index({ programId: 1 });
 	schema.index({ code: 1 }, { sparse: true });
@@ -313,11 +417,11 @@ function createRuleSchema() {
 }
 //#endregion
 //#region src/models/schemas/voucher.schema.ts
-const { Schema } = mongoose;
+const { Schema: Schema$1 } = mongoose;
 function createVoucherSchema() {
-	const schema = new Schema({
+	const schema = new Schema$1({
 		programId: {
-			type: Schema.Types.ObjectId,
+			type: Schema$1.Types.ObjectId,
 			required: true,
 			index: true
 		},
@@ -354,7 +458,8 @@ function createVoucherSchema() {
 				type: Date,
 				default: Date.now
 			},
-			idempotencyKey: { type: String }
+			idempotencyKey: { type: String },
+			organizationId: { type: String }
 		}],
 		expiresAt: { type: Date },
 		redemptions: [{
@@ -371,9 +476,10 @@ function createVoucherSchema() {
 				type: Date,
 				default: Date.now
 			},
-			idempotencyKey: { type: String }
+			idempotencyKey: { type: String },
+			organizationId: { type: String }
 		}],
-		metadata: { type: Schema.Types.Mixed }
+		metadata: { type: Schema$1.Types.Mixed }
 	}, { timestamps: true });
 	schema.index({ code: 1 }, { unique: true });
 	schema.index({
@@ -393,7 +499,8 @@ const MODEL_NAMES = [
 	"PromoProgram",
 	"PromoRule",
 	"PromoReward",
-	"PromoVoucher"
+	"PromoVoucher",
+	"PromoPendingEvaluation"
 ];
 function applyAutoIndex(models, autoIndex) {
 	if (autoIndex === void 0) return;
@@ -413,10 +520,13 @@ function createModels(connection, tenant, indexes, autoIndex) {
 	const ruleSchema = createRuleSchema();
 	const rewardSchema = createRewardSchema();
 	const voucherSchema = createVoucherSchema();
+	const pendingEvaluationSchema = createPendingEvaluationSchema();
 	injectTenantField(programSchema, tenant);
 	injectTenantField(ruleSchema, tenant);
 	injectTenantField(rewardSchema, tenant);
 	injectTenantField(voucherSchema, tenant);
+	injectTenantField(pendingEvaluationSchema, tenant);
+	applyPendingEvaluationIndexes(pendingEvaluationSchema);
 	if (indexes?.program) applyUserIndexes(programSchema, indexes.program, tenant);
 	if (indexes?.rule) applyUserIndexes(ruleSchema, indexes.rule, tenant);
 	if (indexes?.reward) applyUserIndexes(rewardSchema, indexes.reward, tenant);
@@ -425,12 +535,94 @@ function createModels(connection, tenant, indexes, autoIndex) {
 		Program: connection.model("PromoProgram", programSchema),
 		Rule: connection.model("PromoRule", ruleSchema),
 		Reward: connection.model("PromoReward", rewardSchema),
-		Voucher: connection.model("PromoVoucher", voucherSchema)
+		Voucher: connection.model("PromoVoucher", voucherSchema),
+		PendingEvaluation: connection.model("PromoPendingEvaluation", pendingEvaluationSchema)
 	};
 	applyAutoIndex(result, autoIndex);
 	return result;
 }
 //#endregion
+//#region src/repositories/pending-evaluation.repository.ts
+/**
+* Pending-evaluation repository. Extends mongokit's `Repository<TDoc>`
+* directly per package rules (no service wrapper, no aliased verbs).
+* Adds one custom domain method: `takeByEvaluationId` — atomic
+* read-and-delete via raw `Model.findOneAndDelete`.
+*
+* **Why raw `findOneAndDelete` (escape from mongokit's `delete()`)**:
+* mongokit's `Repository.delete()` returns `{success, message}` only —
+* it doesn't surface the deleted document. `take` semantics require
+* "atomically remove AND return", which is the canonical defence
+* against double-commit on the same evaluationId at the storage layer
+* (one caller wins the document, the other gets `null`). This is the
+* narrow exception PACKAGE_RULES.md / order/CLAUDE.md sanction:
+* *"Raw findOneAndUpdate/findOneAndDelete is allowed ONLY for atomic
+* state-machine transitions — flag each one with a comment."*
+*/
+var PendingEvaluationRepository = class extends Repository {
+	/**
+	* The repository owns its tenant config so its raw-driver methods
+	* (`findOneAndDelete`, `deleteOne`) can apply the SAME scoping rule
+	* the mongokit hook pipeline would apply on standard methods —
+	* specifically using `tenant.tenantField` (host-configurable as
+	* `organizationId`, `branchId`, `tenantId`, etc.) NOT a hardcoded
+	* `organizationId`. Without this, deployments that configure custom
+	* tenant fields would silently lose isolation on the cache layer.
+	*/
+	tenant;
+	constructor(model, plugins = [], tenant) {
+		super(model, plugins);
+		this.tenant = tenant;
+	}
+	/** The host-configured tenant field name (or `undefined` if single-tenant). */
+	get tenantField() {
+		return this.tenant?.enabled ? this.tenant.tenantField : void 0;
+	}
+	/**
+	* Atomic read-and-delete by evaluationId. Two concurrent commit calls
+	* on the same id race here at the database layer — the winner gets
+	* the document, the loser gets `null` and the calling service throws
+	* `EvaluationNotFoundError`. No way both succeed.
+	*
+	* Honours `ctx.session` so the operation joins the caller's
+	* transaction. If the transaction aborts (transient DB error, cap
+	* exceeded, etc.) the delete rolls back and the snapshot stays in
+	* the store — letting the caller retry without re-evaluation.
+	*
+	* Tenant scoping uses the configured `tenant.tenantField` (NOT a
+	* hardcoded `organizationId`) so hosts on `branchId`/`tenantId`/etc.
+	* keep cross-tenant isolation on the cache layer too.
+	*/
+	async takeByEvaluationId(evaluationId, ctx) {
+		const filter = this.scopedFilter({ evaluationId }, ctx);
+		const session = ctx?.session ?? null;
+		return await this.Model.findOneAndDelete(filter).session(session).lean();
+	}
+	/**
+	* Idempotent delete. Returns whether anything was actually removed,
+	* so callers can distinguish "we cleaned it" from "already gone".
+	*/
+	async deleteByEvaluationId(evaluationId, ctx) {
+		const filter = this.scopedFilter({ evaluationId }, ctx);
+		const session = ctx?.session ?? null;
+		return (await this.Model.deleteOne(filter).session(session)).deletedCount > 0;
+	}
+	/**
+	* Build a query filter with the configured tenant scope appended,
+	* mirroring what mongokit's `multiTenantPlugin` injects on standard
+	* Repository methods. We re-implement here because raw driver calls
+	* (`findOneAndDelete`, `deleteOne`) bypass the plugin pipeline.
+	*/
+	scopedFilter(base, ctx) {
+		const field = this.tenantField;
+		if (!field || ctx?.tenantValue === void 0) return base;
+		return {
+			...base,
+			[field]: ctx.tenantValue
+		};
+	}
+};
+//#endregion
 //#region src/events/dispatch.ts
 /**
 * Canonical P8 shape — save to outbox first (with `ctx.session` when
@@ -538,6 +730,34 @@ var ProgramRepository = class extends Repository {
 		if (!updated) throw new ProgramNotFoundError(id);
 		return updated;
 	}
+	/**
+	* Atomic compare-and-set increment: succeeds only if the program either
+	* has no cap (`maxUsageTotal == null`) OR `usedCount < maxUsageTotal`.
+	* If the cap is already saturated, returns `null` so the caller can
+	* decide whether to throw (commit-time enforcement) or skip silently
+	* (best-effort eligibility check).
+	*
+	* Industry-standard primitive for "promo with finite supply" — without
+	* this, two evaluations both see the program as available and both
+	* commit, leading to oversell. The atomic filter on the same write
+	* eliminates the race entirely; concurrent losers see a `null` return
+	* and can downgrade their commit (apply order without the discount,
+	* surface "promo no longer available" to the user, etc.).
+	*
+	* Routes through mongokit's `update` so tenant scoping + hooks fire.
+	*/
+	async tryIncrementUsage(id, ctx) {
+		return await this.update(id, { $inc: { usedCount: 1 } }, {
+			query: { $or: [
+				{ maxUsageTotal: { $exists: false } },
+				{ maxUsageTotal: null },
+				{ $expr: { $lt: ["$usedCount", "$maxUsageTotal"] } }
+			] },
+			throwOnNotFound: false,
+			lean: true,
+			...ctx
+		}) ?? null;
+	}
 	async decrementUsage(id, ctx) {
 		const updated = await this.update(id, { $inc: { usedCount: -1 } }, {
 			throwOnNotFound: true,
@@ -607,20 +827,27 @@ var RuleRepository = class extends Repository {
 var VoucherRepository = class extends Repository {
 	dispatchDeps;
 	tenantField;
-	constructor(model, plugins = [], dispatchDeps = {}, tenantField = "organizationId") {
+	tenantEnabled;
+	constructor(model, plugins = [], dispatchDeps = {}, tenantField = "organizationId", tenantEnabled = true) {
 		super(model, plugins);
 		this.dispatchDeps = dispatchDeps;
 		this.tenantField = tenantField;
+		this.tenantEnabled = tenantEnabled;
 	}
 	/**
 	* Copy the tenant id from `ctx` onto the write payload so the doc persists
 	* with the correct `organizationId` even when the host has opted OUT of the
-	* auto-wired `multiTenantPlugin` (e.g. arc hosts that scope at the
-	* framework layer — see `@classytic/order` CLAUDE.md: "Child repos set
-	* `organizationId` explicitly on the doc"). No-op when `ctx` omits the
-	* tenant id or the payload already carries it.
+	* auto-wired `multiTenantPlugin` but still scopes at its framework layer
+	* (e.g. arc's preset + `BaseController` — see `@classytic/order` CLAUDE.md:
+	* "Child repos set `organizationId` explicitly on the doc").
+	*
+	* Skipped entirely when the engine was configured with `tenant: false` —
+	* the host's intent is company-wide rows (no `organizationId` on disk),
+	* and injecting it from `ctx` would silently re-scope writes per branch
+	* while reads still look at the unscoped collection.
 	*/
 	_injectTenant(data, ctx) {
+		if (!this.tenantEnabled) return data;
 		const tenantValue = ctx?.[this.tenantField];
 		if (tenantValue != null && data[this.tenantField] == null) data[this.tenantField] = tenantValue;
 		return data;
@@ -722,11 +949,17 @@ var VoucherRepository = class extends Repository {
 	* (e.g. arc's preset + `BaseController`). Without this, a host that
 	* runs the plugin off would leak vouchers across branches at
 	* validate/redeem/spend/topUp call sites.
+	*
+	* When the engine is configured with `tenant: false`, the filter is
+	* code-only — vouchers are company-wide and the docs carry no
+	* `organizationId`, so injecting one would always miss.
 	*/
 	async getByCode(code, ctx) {
 		const filter = { code: code.toUpperCase() };
-		const tenantValue = ctx?.[this.tenantField];
-		if (tenantValue != null) filter[this.tenantField] = tenantValue;
+		if (this.tenantEnabled) {
+			const tenantValue = ctx?.[this.tenantField];
+			if (tenantValue != null) filter[this.tenantField] = tenantValue;
+		}
 		return this.getByQuery(filter, {
 			throwOnNotFound: false,
 			lean: true,
@@ -758,12 +991,148 @@ function createRepositories(models, plugins, tenant, dispatchDeps = {}) {
 		program: new ProgramRepository(models.Program, [...tenantPlugins, ...plugins?.program ?? []], dispatchDeps),
 		rule: new RuleRepository(models.Rule, [...tenantPlugins, ...plugins?.rule ?? []]),
 		reward: new RewardRepository(models.Reward, [...tenantPlugins, ...plugins?.reward ?? []]),
-		voucher: new VoucherRepository(models.Voucher, [...tenantPlugins, ...plugins?.voucher ?? []], dispatchDeps, tenant?.tenantField)
+		voucher: new VoucherRepository(models.Voucher, [...tenantPlugins, ...plugins?.voucher ?? []], dispatchDeps, tenant?.tenantField, tenant?.enabled ?? false),
+		pendingEvaluation: new PendingEvaluationRepository(models.PendingEvaluation, [...tenantPlugins, ...plugins?.pendingEvaluation ?? []], tenant)
 	};
 }
 //#endregion
+//#region src/adapters/mongo-evaluation-store.ts
+/**
+* Default Mongo-backed implementation of {@link EvaluationStore}. Translates
+* between the domain snapshot shape and the persistence document shape,
+* forwards atomic `take`/`delete` semantics to the repository, and
+* applies the engine's configured tenant field on writes (the repo
+* applies it on reads).
+*
+* Hosts that prefer a different backend (Redis, DynamoDB, in-memory for
+* tests) can implement `EvaluationStore` directly and pass it via engine
+* config — this class isn't load-bearing.
+*/
+var MongoEvaluationStore = class {
+	constructor(repo) {
+		this.repo = repo;
+	}
+	async put(id, snapshot, ttlSeconds, ctx) {
+		const expiresAt = new Date(Date.now() + ttlSeconds * 1e3);
+		const session = ctx?.session;
+		const tenantField = this.repo.tenantField;
+		const tenantValue = ctx?.tenantValue ?? snapshot.ctx.organizationId;
+		const filter = { evaluationId: id };
+		if (tenantField && tenantValue !== void 0) filter[tenantField] = tenantValue;
+		const update = {
+			evaluationId: id,
+			result: snapshot.result,
+			ctx: snapshot.ctx,
+			customerId: snapshot.customerId ?? null,
+			programUsages: snapshot.programUsages,
+			voucherUsages: snapshot.voucherUsages,
+			cartHash: snapshot.cartHash,
+			expiresAt
+		};
+		if (tenantField && tenantValue !== void 0) update[tenantField] = tenantValue;
+		await this.repo.Model.updateOne(filter, { $set: update }, {
+			upsert: true,
+			session
+		});
+	}
+	async take(id, ctx) {
+		const doc = await this.repo.takeByEvaluationId(id, {
+			tenantValue: ctx?.tenantValue,
+			session: ctx?.session
+		});
+		if (!doc) return null;
+		return {
+			result: doc.result,
+			ctx: doc.ctx,
+			customerId: doc.customerId ?? void 0,
+			programUsages: doc.programUsages,
+			voucherUsages: doc.voucherUsages,
+			cartHash: doc.cartHash,
+			createdAt: doc.createdAt
+		};
+	}
+	async delete(id, ctx) {
+		await this.repo.deleteByEvaluationId(id, {
+			tenantValue: ctx?.tenantValue,
+			session: ctx?.session
+		});
+	}
+};
+/**
+* In-memory fallback. Useful for unit tests, single-process dev servers,
+* and hosts that consciously opt out of persistence (knowing they lose
+* pending evaluations on restart). NOT recommended for production
+* topologies — see EvaluationStore docblock for why.
+*
+* Tenant scoping uses `ctx.tenantValue` as part of the in-memory key
+* (the field-name layer doesn't matter here — we just namespace by
+* value). No transaction semantics (in-memory has nothing to roll
+* back), no TTL refinement beyond initial expiry check.
+*/
+var InMemoryEvaluationStore = class {
+	map = /* @__PURE__ */ new Map();
+	async put(id, snapshot, ttlSeconds, ctx) {
+		this.map.set(this.key(id, ctx), {
+			snapshot,
+			expiresAt: Date.now() + ttlSeconds * 1e3
+		});
+	}
+	async take(id, ctx) {
+		const k = this.key(id, ctx);
+		const entry = this.map.get(k);
+		if (!entry) return null;
+		this.map.delete(k);
+		if (entry.expiresAt < Date.now()) return null;
+		return entry.snapshot;
+	}
+	async delete(id, ctx) {
+		this.map.delete(this.key(id, ctx));
+	}
+	key(id, ctx) {
+		return ctx?.tenantValue ? `${ctx.tenantValue}:${id}` : id;
+	}
+};
+//#endregion
+//#region src/utils/is-write-conflict.ts
+/**
+* Detect MongoDB's transient WriteConflict error across the shapes it
+* arrives in (raw driver error, mongoose-wrapped VersionError, mongokit
+* rethrows). Centralised so every contended write site (gift card spend,
+* gift card top-up, evaluation commit) can opt into uniform mapping
+* to the same typed `ConcurrencyConflictError` / `*UsageCapExceededError`
+* shape — hosts catch one type, decide retry-or-409 once.
+*
+* Why detection is a layered match: under heavy contention MongoDB
+* surfaces the same physical race in different ways depending on which
+* layer caught it first (driver vs mongoose vs mongokit), and each
+* wrapper preserves a slightly different subset of the original error
+* fields. Matching against ALL of them avoids false negatives that
+* would otherwise let the raw error escape to the host with no useful
+* type information.
+*/
+function isWriteConflict(err) {
+	if (typeof err !== "object" || err === null) return false;
+	const e = err;
+	if (e.code === 112 || e.codeName === "WriteConflict") return true;
+	if (e.name === "MongoServerError" && typeof e.message === "string" && /write conflict/i.test(e.message)) 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/services/evaluation.service.ts
 /**
+* Default TTL for pending evaluation snapshots in the store. 30 minutes
+* comfortably exceeds any realistic evaluate→commit window (typical
+* checkout: seconds to a few minutes; long-tail: ~10 min) without
+* hoarding abandoned evaluations forever. The Mongo TTL index purges
+* expired entries; the engine itself never relies on the TTL for
+* correctness — `store.take()` is atomic and returns `null` when an
+* id was already consumed or never existed.
+*/
+const DEFAULT_PENDING_EVALUATION_TTL_SECONDS = 1800;
+/**
 * Deterministic, collision-resistant hash of the evaluated cart. The hash
 * covers everything the evaluation algorithm depends on: normalized line
 * items (sorted), subtotal, applied codes, and customer identity. Two
@@ -797,8 +1166,7 @@ function computeCartHash(input) {
 	return createHash("sha256").update(canonical).digest("hex");
 }
 var EvaluationService = class {
-	pendingEvaluations = /* @__PURE__ */ new Map();
-	constructor(programRepo, ruleRepo, rewardRepo, voucherRepo, unitOfWork, dispatchDeps, config) {
+	constructor(programRepo, ruleRepo, rewardRepo, voucherRepo, unitOfWork, dispatchDeps, config, store) {
 		this.programRepo = programRepo;
 		this.ruleRepo = ruleRepo;
 		this.rewardRepo = rewardRepo;
@@ -806,6 +1174,7 @@ var EvaluationService = class {
 		this.unitOfWork = unitOfWork;
 		this.dispatchDeps = dispatchDeps;
 		this.config = config;
+		this.store = store;
 	}
 	async evaluate(input, ctx) {
 		return this.doEvaluate(input, ctx, false);
@@ -814,50 +1183,80 @@ var EvaluationService = class {
 		return this.doEvaluate(input, ctx, true);
 	}
 	async commit(evaluationId, orderId, ctx, options = {}) {
-		const stored = this.pendingEvaluations.get(evaluationId);
-		if (!stored) throw new EvaluationNotFoundError(evaluationId);
-		if (options.cartHash !== void 0 && options.cartHash !== stored.cartHash) throw new CartHashMismatchError(evaluationId);
-		return this.unitOfWork.withTransaction(async (session) => {
-			for (const usage of stored.programUsages) {
-				await this.programRepo.incrementUsage(usage.programId, {
-					...ctx,
-					session
-				});
-				if (stored.customerId) await this.programRepo.incrementCustomerUsage(usage.programId, stored.customerId, {
-					...ctx,
+		let snapshotForCapMapping = null;
+		try {
+			return await this.unitOfWork.withTransaction(async (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, session, ctx);
+			});
+		} catch (err) {
+			if (isWriteConflict(err) && snapshotForCapMapping) {
+				const firstUsage = snapshotForCapMapping.programUsages[0];
+				if (firstUsage) {
+					const program = await this.programRepo.getById(firstUsage.programId, {
+						...ctx,
+						lean: true,
+						throwOnNotFound: false
+					});
+					throw new ProgramUsageCapExceededError(firstUsage.programId, program?.maxUsageTotal ?? 0);
+				}
 			}
-			for (const usage of stored.voucherUsages) await this.voucherRepo.incrementUsage(usage.voucherId, {
-				orderId,
-				discountAmount: usage.discountAmount,
-				redeemedAt: /* @__PURE__ */ new Date()
-			}, {
+			throw err;
+		}
+	}
+	async commitInTransaction(stored, evaluationId, orderId, session, ctx) {
+		for (const usage of stored.programUsages) {
+			if (!await this.programRepo.tryIncrementUsage(usage.programId, {
 				...ctx,
 				session
-			});
-			this.pendingEvaluations.delete(evaluationId);
-			const commitResult = {
-				evaluationId,
-				orderId,
-				totalDiscount: stored.result.totalDiscount,
-				programsCommitted: stored.programUsages.length,
-				vouchersUsed: stored.voucherUsages.length
-			};
-			await dispatchPromoEvent(this.dispatchDeps, createEvent$1(PromoEvents.EVALUATION_COMMITTED, {
-				evaluationId,
-				orderId,
-				totalDiscount: stored.result.totalDiscount
-			}, ctx), {
+			})) {
+				const program = await this.programRepo.getById(usage.programId, {
+					...ctx,
+					session,
+					lean: true,
+					throwOnNotFound: false
+				});
+				throw new ProgramUsageCapExceededError(usage.programId, program?.maxUsageTotal ?? 0);
+			}
+			if (stored.customerId) await this.programRepo.incrementCustomerUsage(usage.programId, stored.customerId, {
 				...ctx,
 				session
 			});
-			return commitResult;
+		}
+		for (const usage of stored.voucherUsages) await this.voucherRepo.incrementUsage(usage.voucherId, {
+			orderId,
+			discountAmount: usage.discountAmount,
+			redeemedAt: /* @__PURE__ */ new Date(),
+			...ctx.organizationId !== void 0 ? { organizationId: ctx.organizationId } : {}
+		}, {
+			...ctx,
+			session
+		});
+		const commitResult = {
+			evaluationId,
+			orderId,
+			totalDiscount: stored.result.totalDiscount,
+			programsCommitted: stored.programUsages.length,
+			vouchersUsed: stored.voucherUsages.length
+		};
+		await dispatchPromoEvent(this.dispatchDeps, createEvent$1(PromoEvents.EVALUATION_COMMITTED, {
+			evaluationId,
+			orderId,
+			totalDiscount: stored.result.totalDiscount
+		}, ctx), {
+			...ctx,
+			session
 		});
+		return commitResult;
 	}
 	async rollback(evaluationId, ctx) {
-		if (!this.pendingEvaluations.get(evaluationId)) return;
-		this.pendingEvaluations.delete(evaluationId);
+		await this.store.delete(evaluationId, { tenantValue: ctx.organizationId });
 		await dispatchPromoEvent(this.dispatchDeps, createEvent$1(PromoEvents.EVALUATION_ROLLED_BACK, { evaluationId }, ctx), ctx);
 	}
 	async doEvaluate(input, ctx, isPreview) {
@@ -970,15 +1369,18 @@ var EvaluationService = class {
 			isPreview,
 			programsApplied
 		};
-		if (!isPreview) this.pendingEvaluations.set(evaluationId, {
-			result,
-			ctx,
-			customerId: input.customerId,
-			programUsages,
-			voucherUsages,
-			createdAt: Date.now(),
-			cartHash
-		});
+		if (!isPreview) {
+			const snapshot = {
+				result,
+				ctx,
+				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 dispatchPromoEvent(this.dispatchDeps, createEvent$1(PromoEvents.EVALUATION_COMPLETED, {
 			evaluationId,
 			totalDiscount,
@@ -1267,14 +1669,18 @@ var VoucherService = class {
 			if (!voucher) throw new VoucherNotFoundError(input.code);
 			this.assertVoucherUsable(voucher);
 			if (input.idempotencyKey) {
-				if (await this.voucherRepo.hasIdempotencyKey(voucher._id, input.idempotencyKey)) throw new DuplicateRedemptionError(input.idempotencyKey);
+				if (await this.voucherRepo.hasIdempotencyKey(voucher._id, input.idempotencyKey, {
+					...ctx,
+					session
+				})) throw new DuplicateRedemptionError(input.idempotencyKey);
 			}
 			const redemption = {
 				orderId: input.orderId,
 				customerId: input.customerId,
 				discountAmount: input.discountAmount,
 				redeemedAt: /* @__PURE__ */ new Date(),
-				...input.idempotencyKey ? { idempotencyKey: input.idempotencyKey } : {}
+				...input.idempotencyKey ? { idempotencyKey: input.idempotencyKey } : {},
+				...ctx.organizationId !== void 0 ? { organizationId: ctx.organizationId } : {}
 			};
 			const updated = await this.voucherRepo.incrementUsage(voucher._id, redemption, {
 				...ctx,
@@ -1330,14 +1736,18 @@ var VoucherService = class {
 			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)) throw new DuplicateRedemptionError(input.idempotencyKey);
+				if (await this.voucherRepo.hasIdempotencyKey(voucher._id, input.idempotencyKey, {
+					...ctx,
+					session
+				})) throw new DuplicateRedemptionError(input.idempotencyKey);
 			}
 			const entry = {
 				amount: -input.amount,
 				orderId: input.orderId,
 				description: input.description ?? `Spent on order ${input.orderId}`,
 				createdAt: /* @__PURE__ */ new Date(),
-				...input.idempotencyKey ? { idempotencyKey: input.idempotencyKey } : {}
+				...input.idempotencyKey ? { idempotencyKey: input.idempotencyKey } : {},
+				...ctx.organizationId !== void 0 ? { organizationId: ctx.organizationId } : {}
 			};
 			const updated = await this.voucherRepo.addLedgerEntry(voucher._id, entry, -input.amount, {
 				...ctx,
@@ -1380,37 +1790,61 @@ var VoucherService = class {
 	}
 	async topUp(input, ctx) {
 		if (input.amount <= 0) throw new ValidationError("Top-up amount must be positive");
-		const voucher = await this.voucherRepo.getByCode(input.code, ctx);
-		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)) throw new DuplicateRedemptionError(input.idempotencyKey);
+		try {
+			return await this.topUpInTransaction(input, ctx);
+		} catch (err) {
+			if (isWriteConflict(err)) throw new ConcurrencyConflictError("voucher", input.code, err);
+			throw err;
 		}
-		const entry = {
-			amount: input.amount,
-			description: input.description ?? "Top-up",
-			createdAt: /* @__PURE__ */ new Date(),
-			...input.idempotencyKey ? { idempotencyKey: input.idempotencyKey } : {}
-		};
-		const updated = await this.voucherRepo.addLedgerEntry(voucher._id, entry, input.amount, ctx);
-		if (voucher.status === "used") await this.voucherRepo.update(voucher._id, { status: "active" }, {
-			lean: true,
-			...ctx
+	}
+	async topUpInTransaction(input, ctx) {
+		return this.unitOfWork.withTransaction(async (session) => {
+			const voucher = await this.voucherRepo.getByCode(input.code, {
+				...ctx,
+				session
+			});
+			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);
+			}
+			const entry = {
+				amount: input.amount,
+				description: input.description ?? "Top-up",
+				createdAt: /* @__PURE__ */ new Date(),
+				...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
+			});
+			if (voucher.status === "used") await this.voucherRepo.update(voucher._id, { status: "active" }, {
+				lean: true,
+				...ctx,
+				session
+			});
+			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
+			});
+			return {
+				code: updated.code,
+				initialBalance: updated.initialBalance ?? 0,
+				currentBalance: updated.currentBalance ?? 0,
+				spent: (updated.initialBalance ?? 0) - (updated.currentBalance ?? 0),
+				voucherId: updated._id
+			};
 		});
-		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);
-		return {
-			code: updated.code,
-			initialBalance: updated.initialBalance ?? 0,
-			currentBalance: updated.currentBalance ?? 0,
-			spent: (updated.initialBalance ?? 0) - (updated.currentBalance ?? 0),
-			voucherId: updated._id
-		};
 	}
 	assertVoucherUsable(voucher) {
 		if (voucher.status === "expired") throw new VoucherExpiredError(voucher.code);
@@ -1423,61 +1857,19 @@ var VoucherService = class {
 		if (voucher.usedCount >= voucher.usageLimit) throw new VoucherExhaustedError(voucher.code);
 	}
 };
-/**
-* Detect MongoDB's transient WriteConflict error across the shapes it
-* arrives in (raw driver error, mongoose-wrapped VersionError, mongokit
-* rethrows). Centralised so every contended write site can opt-in.
-*/
-function isWriteConflict(err) {
-	if (typeof err !== "object" || err === null) return false;
-	const e = err;
-	if (e.code === 112 || e.codeName === "WriteConflict") return true;
-	if (e.name === "MongoServerError" && typeof e.message === "string" && /write conflict/i.test(e.message)) 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/services/create-services.ts
 function createServices(deps) {
-	const { repositories, unitOfWork, dispatchDeps, config } = deps;
+	const { repositories, unitOfWork, dispatchDeps, config, evaluationStore } = deps;
+	const voucher = new VoucherService(repositories.voucher, repositories.program, unitOfWork, dispatchDeps, config);
+	const store = evaluationStore ?? new MongoEvaluationStore(repositories.pendingEvaluation);
 	return {
-		voucher: new VoucherService(repositories.voucher, repositories.program, unitOfWork, dispatchDeps, config),
-		evaluation: new EvaluationService(repositories.program, repositories.rule, repositories.reward, repositories.voucher, unitOfWork, dispatchDeps, config)
+		voucher,
+		evaluation: new EvaluationService(repositories.program, repositories.rule, repositories.reward, repositories.voucher, unitOfWork, dispatchDeps, config, store)
 	};
 }
 //#endregion
 //#region src/events/promo-event-catalog.ts
-/**
-* Promo event catalog — Zod-source-of-truth definitions for every
-* `promo.*` event.
-*
-* Each definition exposes:
-*   - `.zodSchema`   — source of truth, used by host code's `.safeParse()`
-*   - `.schema`      — JSON Schema derived via `z.toJSONSchema()`, consumed
-*                     by Arc's EventRegistry + OpenAPI plugin
-*   - `.create(...)` — DomainEvent envelope builder, structurally compatible
-*                     with `@classytic/arc`'s `EventDefinitionOutput`
-*
-* Structurally compatible with Arc 2.10's `EventRegistry` — hosts register
-* `promoEventDefinitions` directly, no adapter code. Promo does NOT import
-* from `@classytic/arc` (PACKAGE_RULES §11); compatibility is purely
-* structural.
-*
-* Payload schemas mirror the typed interfaces in
-* [event-payloads.ts](./event-payloads.ts). See PACKAGE_RULES §18.5 for
-* the pattern.
-*
-* @example Wiring into an Arc app
-* ```ts
-* import { createEventRegistry } from '@classytic/arc/events';
-* import { promoEventDefinitions } from '@classytic/promo';
-*
-* const registry = createEventRegistry();
-* for (const def of promoEventDefinitions) registry.register(def);
-* ```
-*/
 function definePromoEvent(input) {
 	const { name, version = 1, description, zodSchema } = input;
 	const def = {
@@ -1727,23 +2119,62 @@ function resolveConfig(config) {
 	if (resolved.evaluation.maxStackablePromotions < 1) throw new ValidationError("maxStackablePromotions must be >= 1");
 	return resolved;
 }
+/**
+* Thin adapter over `mongokit.withTransaction` so the engine's local
+* `UnitOfWork` port stays driver-agnostic while inheriting mongokit's
+* battle-tested transaction handling: auto-retry on
+* `TransientTransactionError` + `UnknownTransactionCommitResult`,
+* standalone-Mongo fallback for dev, consistent session lifecycle.
+*
+* Don't replace this with hand-rolled `session.withTransaction()` — the
+* underlying helper centralises retry semantics across every package
+* that wires it. See packages/mongokit/src/transaction.ts.
+*/
 var MongoUnitOfWork = class {
 	constructor(connection) {
 		this.connection = connection;
 	}
-	async withTransaction(cb) {
-		const session = await this.connection.startSession();
-		try {
-			let result;
-			await session.withTransaction(async () => {
-				result = await cb(session);
-			});
-			return result;
-		} finally {
-			await session.endSession();
-		}
+	withTransaction(cb) {
+		return withTransaction(this.connection, cb);
 	}
 };
+/**
+* Build the promo engine for a host application.
+*
+* **Index management — important for boot performance:**
+*
+* `createPromoEngine` itself is non-blocking. It registers Mongoose models
+* and returns immediately. Index creation is delegated to Mongoose's
+* standard lazy-init: with `autoIndex: true` (default in dev) Mongoose
+* builds indexes in the background after the first query touches each
+* model; with `autoIndex: false` (recommended for production) hosts
+* control index creation explicitly.
+*
+* The returned `engine.syncIndexes()` helper is opt-in and **MUST NOT be
+* `await`ed during Fastify plugin registration / boot** — Atlas index
+* creation can take 10s+ on fresh collections, longer than typical
+* plugin timeouts. Three safe patterns:
+*
+*   1. **Migration script** (recommended for production):
+*      ```ts
+*      // scripts/sync-indexes.ts
+*      await engine.syncIndexes();
+*      ```
+*      Run before deploying / serving traffic.
+*
+*   2. **Background fire-and-log** during boot:
+*      ```ts
+*      engine.syncIndexes().catch((err) => log.warn({ err }, 'index sync'));
+*      ```
+*      App accepts traffic immediately; first queries may wait briefly
+*      on still-building indexes.
+*
+*   3. **Lazy init** (`autoIndex: true` in dev): just don't call
+*      `syncIndexes()` at all. Mongoose schedules creation on first
+*      query per model.
+*
+* Production hosts should set `autoIndex: false` and use option (1).
+*/
 function createPromoEngine(config) {
 	const resolvedConfig = resolveConfig(config);
 	const models = createModels(config.mongoose, resolvedConfig.tenant, config.indexes, config.autoIndex);
@@ -1761,7 +2192,8 @@ function createPromoEngine(config) {
 			repositories,
 			unitOfWork: new MongoUnitOfWork(config.mongoose),
 			dispatchDeps,
-			config: resolvedConfig
+			config: resolvedConfig,
+			...config.evaluationStore !== void 0 ? { evaluationStore: config.evaluationStore } : {}
 		}),
 		events,
 		async syncIndexes() {
@@ -1770,4 +2202,4 @@ function createPromoEngine(config) {
 	};
 }
 //#endregion
-export { EvaluationCommitted, EvaluationCompleted, EvaluationRolledBack, GiftCardExhausted, GiftCardSpent, GiftCardToppedUp, ProgramActivated, ProgramArchived, ProgramCreated, ProgramPaused, ProgramRepository, PromoEvents, RewardAdded, RewardRemoved, RewardRepository, RewardUpdated, RuleAdded, RuleRemoved, RuleRepository, RuleUpdated, VoucherCancelled, VoucherExpired, VoucherGenerated, VoucherRedeemed, VoucherRepository, createPromoEngine, promoEventDefinitions, resolveConfig };
+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 };