@classytic/promo 0.2.0 → 0.2.2

package/dist/index.d.mts

@@ -1,91 +1,12 @@
 import { c as ProgramType, f as StackingMode, g as VoucherStatus, i as DiscountScope, m as TriggerMode, r as DiscountMode, s as ProgramStatus, u as RewardType } from "./constants-CrbSSQG5.mjs";
-import { ResolvedTenantConfig, TenantConfig } from "@classytic/primitives/tenant";
+import { PluginType as PluginType$1, Repository } from "@classytic/mongokit";
+import { ResolvedTenantConfig, TenantConfig, TenantFieldType } from "@classytic/primitives/tenant";
 import { DomainEvent, DomainEvent as DomainEvent$1, EventHandler, EventTransport, EventTransport as EventTransport$1 } from "@classytic/primitives/events";
 import { ClientSession, Connection, Model } from "mongoose";
-import { PluginType, Repository } from "@classytic/mongokit";
 import { z } from "zod";
 import { OutboxStore } from "@classytic/primitives/outbox";
 import { OperationContext } from "@classytic/primitives/context";
 
-//#region src/types/config.d.ts
-type TenantConfig$1 = false | TenantConfig;
-interface IndexDefinition {
-  fields: Record<string, 1 | -1>;
-  options?: Record<string, unknown> | undefined;
-}
-type ModelName = 'program' | 'rule' | 'reward' | 'voucher';
-interface RepositoryPlugins {
-  program?: PluginType[] | undefined;
-  rule?: PluginType[] | undefined;
-  reward?: PluginType[] | undefined;
-  voucher?: PluginType[] | undefined;
-}
-interface PromoConfig {
-  mongoose: Connection;
-  tenant?: TenantConfig$1 | undefined;
-  evaluation?: {
-    maxStackablePromotions?: number | undefined;
-    allowExclusiveAndStackable?: boolean | undefined;
-  } | undefined;
-  voucher?: {
-    codeLength?: number | undefined;
-    codePrefix?: string | undefined;
-    defaultExpiryDays?: number | undefined;
-  } | undefined;
-  giftCard?: {
-    allowNegativeBalance?: boolean | undefined;
-    maxBalance?: number | undefined;
-  } | undefined;
-  indexes?: Partial<Record<ModelName, IndexDefinition[]>> | undefined;
-  autoIndex?: boolean | Partial<Record<ModelName, boolean>> | undefined;
-  events?: {
-    transport?: EventTransport$1 | undefined;
-  } | undefined;
-  /**
-   * Host-provided outbox store (PACKAGE_RULES §5.5 + §P8). When wired, every
-   * domain event is persisted to the outbox inside the caller's `ctx.session`
-   * BEFORE being published to the transport — giving at-least-once delivery
-   * via the host-side relay. Absent → transport-only best-effort.
-   *
-   * Explicit `| undefined` per `exactOptionalPropertyTypes` convention.
-   */
-  outbox?: OutboxStore | undefined;
-  /**
-   * Optional logger for dispatch-layer errors. Used by the shared
-   * `dispatch()` helper to surface outbox/transport failures without
-   * aborting the domain mutation. Defaults to `console`.
-   */
-  logger?: {
-    error(message: string, ...args: unknown[]): void;
-  } | undefined;
-  plugins?: RepositoryPlugins | undefined;
-}
-type ResolvedTenant = ResolvedTenantConfig;
-interface ResolvedConfig {
-  evaluation: {
-    maxStackablePromotions: number;
-    allowExclusiveAndStackable: boolean;
-  };
-  voucher: {
-    codeLength: number;
-    codePrefix: string;
-    defaultExpiryDays: number | null;
-  };
-  giftCard: {
-    allowNegativeBalance: boolean;
-    maxBalance: number | null;
-  };
-  tenant: ResolvedTenant;
-}
-//#endregion
-//#region src/models/create-models.d.ts
-interface PromoModels {
-  Program: Model<unknown>;
-  Rule: Model<unknown>;
-  Reward: Model<unknown>;
-  Voucher: Model<unknown>;
-}
-//#endregion
 //#region src/types/inputs.d.ts
 /**
  * Extends `@classytic/primitives`' {@link OperationContext}. The
@@ -239,6 +160,295 @@ interface ListQuery {
   filters?: Record<string, unknown>;
 }
 //#endregion
+//#region src/types/results.d.ts
+interface DiscountLine {
+  programId: string;
+  programName: string;
+  rewardId: string;
+  type: 'percentage' | 'fixed';
+  scope: 'order' | 'cheapest' | 'specific_products';
+  amount: number;
+  description: string;
+  voucherCode?: string;
+}
+interface FreeProductLine {
+  programId: string;
+  programName: string;
+  rewardId: string;
+  productId?: string;
+  productSku?: string;
+  quantity: number;
+  description: string;
+}
+interface RejectedCode {
+  code: string;
+  reason: string;
+}
+interface EvaluationResult {
+  evaluationId: string;
+  /**
+   * Deterministic hash of the evaluated cart (items + subtotal + codes +
+   * customerId). Hosts that want tamper-proof commits pass this hash back
+   * to `EvaluationService.commit(evaluationId, orderId, ctx, { cartHash })`;
+   * the engine throws `CartHashMismatchError` when the caller's hash does
+   * not match what was evaluated. Omitting the hash at commit keeps the
+   * legacy "trusted host" behaviour.
+   */
+  cartHash: string;
+  appliedDiscounts: DiscountLine[];
+  freeProducts: FreeProductLine[];
+  totalDiscount: number;
+  subtotalAfterDiscount: number;
+  appliedCodes: string[];
+  rejectedCodes: RejectedCode[];
+  warnings: string[];
+  isPreview: boolean;
+  programsApplied: string[];
+}
+interface CommitResult {
+  evaluationId: string;
+  orderId: string;
+  totalDiscount: number;
+  programsCommitted: number;
+  vouchersUsed: number;
+}
+interface VoucherValidation {
+  valid: boolean;
+  voucher?: {
+    code: string;
+    programId: string;
+    programType: string;
+    status: string;
+    remainingUses: number;
+    currentBalance?: number;
+    expiresAt?: Date;
+  };
+  error?: string;
+}
+interface GiftCardBalance {
+  code: string;
+  initialBalance: number;
+  currentBalance: number;
+  spent: number;
+  voucherId: string;
+}
+interface PaginatedResult<T> {
+  docs: T[];
+  page: number;
+  limit: number;
+  total: number;
+  pages: number;
+  hasNext: boolean;
+  hasPrev: boolean;
+}
+//#endregion
+//#region src/domain/ports/evaluation-store.port.d.ts
+/**
+ * Snapshot the engine writes after `evaluate` and reads back at `commit`
+ * or `rollback`. Carries the materialised discount + the per-program /
+ * per-voucher usages the commit step must increment atomically.
+ *
+ * Mirrors the in-memory `StoredEvaluation` shape but moved out of the
+ * service file so storage adapters (Mongo, Redis, host-supplied) share
+ * one definition.
+ */
+interface StoredEvaluationSnapshot {
+  readonly result: EvaluationResult;
+  readonly ctx: PromoContext;
+  readonly customerId?: string;
+  readonly programUsages: ReadonlyArray<{
+    programId: string;
+  }>;
+  readonly voucherUsages: ReadonlyArray<{
+    voucherId: string;
+    code: string;
+    discountAmount: number;
+  }>;
+  readonly cartHash: string;
+  readonly createdAt: Date;
+}
+/**
+ * Per-call context for store operations. Carries:
+ *   - `tenantValue` — the tenant scope value (e.g. an org id, branch id,
+ *     workspace id). The store maps this onto whatever field name the
+ *     engine's resolved TenantConfig declared (`organizationId`,
+ *     `branchId`, `tenantId`, etc.). Storage adapters that don't tenant-
+ *     scope simply ignore this.
+ *   - `session` — Mongoose `ClientSession`. When set, the store
+ *     operation joins the caller's transaction so failures roll back
+ *     the read-and-delete atomically (the snapshot stays in the store
+ *     and the caller can retry).
+ *
+ * The shape is intentionally tenant-agnostic — it carries the VALUE
+ * but not the FIELD NAME, so hosts on `branchId`/`tenantId`/etc. don't
+ * have to translate between context shapes at the call site.
+ */
+interface EvaluationStoreContext {
+  readonly tenantValue?: string;
+  readonly session?: unknown;
+}
+/**
+ * Pluggable backing store for pending evaluation snapshots.
+ *
+ * **Why a port, not a hard-coded Map:** the previous implementation kept
+ * pending evaluations in a process-local `Map<string, StoredEvaluation>`.
+ * That works for a single long-lived dev server but breaks every real
+ * production topology:
+ *   - **Process restart** — every in-flight checkout's pending snapshot
+ *     vanishes; subsequent commit() calls throw `EvaluationNotFoundError`.
+ *   - **Horizontal scaling** — pod A's evaluate() snapshot is invisible
+ *     to pod B's commit(); load-balanced traffic randomly fails.
+ *   - **Serverless** — every cold start drops the Map; fits the worst
+ *     pattern of the topology.
+ *   - **Background worker handoff** — main pod evaluates, worker pod
+ *     commits asynchronously: never works.
+ *   - **Test isolation** — Map persists across vitest cases sharing the
+ *     same engine singleton, polluting tests that should be independent.
+ *
+ * The port lets the package ship a default Mongo-backed store (works
+ * everywhere mongokit already runs) while letting hosts plug in Redis,
+ * DynamoDB, or in-memory implementations as their topology demands.
+ *
+ * Contract notes:
+ *   - `take()` is **read-and-delete atomically**. This is the storage
+ *     defence for "no double-commit on the same evaluationId" — even if
+ *     the cap-CAS in the program repo were bypassed somehow, two
+ *     concurrent commit() calls cannot both observe the same snapshot.
+ *   - `take()` MUST honour `ctx.session` when provided. The service
+ *     calls `take` INSIDE its transaction so a transient transaction
+ *     failure rolls back the delete, leaving the snapshot for retry.
+ *     Without session-awareness, a transient DB error would consume
+ *     the snapshot permanently and force callers to re-evaluate.
+ *   - `delete()` exists for explicit `rollback()`, where we want to drop
+ *     the snapshot without consuming it.
+ *   - `put()` carries a TTL. The store SHOULD honour it (Mongo TTL index,
+ *     Redis EXPIRE, etc.) but the engine never relies on TTL alone for
+ *     correctness — it always checks `take()` returned a fresh snapshot.
+ *   - All methods take an optional `ctx` for tenant scoping. The store
+ *     applies the configured tenant field to its read/write filters so
+ *     pod A's snapshot in tenant X cannot be taken by a request in
+ *     tenant Y.
+ */
+interface EvaluationStore {
+  /**
+   * Persist a fresh evaluation snapshot. The store is expected to expire
+   * the entry after `ttlSeconds` so abandoned evaluations don't grow
+   * unbounded. Implementations MUST allow re-puts on the same id (a host
+   * that re-evaluates the same cart should see the latest snapshot).
+   */
+  put(id: string, snapshot: StoredEvaluationSnapshot, ttlSeconds: number, ctx?: EvaluationStoreContext): Promise<void>;
+  /**
+   * Atomically read AND delete the snapshot in a single operation. Used by
+   * `commit()` so two concurrent commits on the same evaluationId can
+   * never both succeed at the storage layer (one wins, the other gets
+   * `null` and surfaces as `EvaluationNotFoundError`).
+   *
+   * Honours `ctx.session` to participate in the caller's transaction —
+   * essential for transient-failure recovery (the delete rolls back if
+   * the transaction aborts, leaving the snapshot intact for retry).
+   */
+  take(id: string, ctx?: EvaluationStoreContext): Promise<StoredEvaluationSnapshot | null>;
+  /**
+   * Drop the snapshot without consuming it. Used by `rollback()`.
+   * Idempotent: if the entry doesn't exist, return without error.
+   */
+  delete(id: string, ctx?: EvaluationStoreContext): Promise<void>;
+}
+//#endregion
+//#region src/types/config.d.ts
+type TenantConfig$1 = false | TenantConfig;
+interface IndexDefinition {
+  fields: Record<string, 1 | -1>;
+  options?: Record<string, unknown> | undefined;
+}
+type ModelName = 'program' | 'rule' | 'reward' | 'voucher';
+type PluginType = PluginType$1;
+interface RepositoryPlugins {
+  program?: PluginType$1[] | undefined;
+  rule?: PluginType$1[] | undefined;
+  reward?: PluginType$1[] | undefined;
+  voucher?: PluginType$1[] | undefined;
+}
+interface PromoConfig {
+  mongoose: Connection;
+  tenant?: TenantConfig$1 | undefined;
+  evaluation?: {
+    maxStackablePromotions?: number | undefined;
+    allowExclusiveAndStackable?: boolean | undefined;
+  } | undefined;
+  voucher?: {
+    codeLength?: number | undefined;
+    codePrefix?: string | undefined;
+    defaultExpiryDays?: number | undefined;
+  } | undefined;
+  giftCard?: {
+    allowNegativeBalance?: boolean | undefined;
+    maxBalance?: number | undefined;
+  } | undefined;
+  indexes?: Partial<Record<ModelName, IndexDefinition[]>> | undefined;
+  autoIndex?: boolean | Partial<Record<ModelName, boolean>> | undefined;
+  events?: {
+    transport?: EventTransport$1 | undefined;
+  } | undefined;
+  /**
+   * Host-provided outbox store (PACKAGE_RULES §5.5 + §P8). When wired, every
+   * domain event is persisted to the outbox inside the caller's `ctx.session`
+   * BEFORE being published to the transport — giving at-least-once delivery
+   * via the host-side relay. Absent → transport-only best-effort.
+   *
+   * Explicit `| undefined` per `exactOptionalPropertyTypes` convention.
+   */
+  outbox?: OutboxStore | undefined;
+  /**
+   * Optional logger for dispatch-layer errors. Used by the shared
+   * `dispatch()` helper to surface outbox/transport failures without
+   * aborting the domain mutation. Defaults to `console`.
+   */
+  logger?: {
+    error(message: string, ...args: unknown[]): void;
+  } | undefined;
+  plugins?: RepositoryPlugins | undefined;
+  /**
+   * Override the pending-evaluation backing store. Defaults to a
+   * Mongo-backed implementation over the engine's own
+   * `pendingEvaluation` repository — works on every topology mongokit
+   * already runs on (single process, horizontal scaling, serverless,
+   * worker handoff).
+   *
+   * Hosts on Redis, DynamoDB, an existing cache layer, or any custom
+   * backend implement `EvaluationStore` and pass it here. The package
+   * never assumes one backend; the port is stable, the default is
+   * convenient.
+   */
+  evaluationStore?: EvaluationStore | undefined;
+}
+type ResolvedTenant = ResolvedTenantConfig;
+interface ResolvedConfig {
+  evaluation: {
+    maxStackablePromotions: number;
+    allowExclusiveAndStackable: boolean;
+  };
+  voucher: {
+    codeLength: number;
+    codePrefix: string;
+    defaultExpiryDays: number | null;
+  };
+  giftCard: {
+    allowNegativeBalance: boolean;
+    maxBalance: number | null;
+  };
+  tenant: ResolvedTenant;
+}
+//#endregion
+//#region src/models/create-models.d.ts
+interface PromoModels {
+  Program: Model<unknown>;
+  Rule: Model<unknown>;
+  Reward: Model<unknown>;
+  Voucher: Model<unknown>;
+  PendingEvaluation: Model<unknown>;
+}
+//#endregion
 //#region src/events/dispatch.d.ts
 interface DispatchLogger {
   error(message: string, ...args: unknown[]): void;
@@ -249,6 +459,92 @@ interface DispatchDeps {
   logger?: DispatchLogger | undefined;
 }
 //#endregion
+//#region src/repositories/pending-evaluation.repository.d.ts
+/**
+ * Persistence-layer document shape — flat blob of the snapshot fields
+ * the schema declares. The service layer maps to/from
+ * `StoredEvaluationSnapshot` so the storage shape stays decoupled from
+ * the domain shape.
+ */
+interface PendingEvaluationDocument {
+  _id: string;
+  evaluationId: string;
+  result: Record<string, unknown>;
+  ctx: Record<string, unknown>;
+  customerId: string | null;
+  programUsages: Array<Record<string, unknown>>;
+  voucherUsages: Array<Record<string, unknown>>;
+  cartHash: string;
+  expiresAt: Date;
+  createdAt: Date;
+  updatedAt: Date;
+}
+/**
+ * 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."*
+ */
+declare class PendingEvaluationRepository extends Repository<PendingEvaluationDocument> {
+  /**
+   * 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.
+   */
+  private readonly tenant;
+  constructor(model: Model<PendingEvaluationDocument>, plugins?: PluginType$1[], tenant?: ResolvedTenant);
+  /** The host-configured tenant field name (or `undefined` if single-tenant). */
+  get tenantField(): string | undefined;
+  /**
+   * 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.
+   */
+  takeByEvaluationId(evaluationId: string, ctx?: {
+    tenantValue?: string;
+    session?: ClientSession;
+  }): Promise<PendingEvaluationDocument | null>;
+  /**
+   * Idempotent delete. Returns whether anything was actually removed,
+   * so callers can distinguish "we cleaned it" from "already gone".
+   */
+  deleteByEvaluationId(evaluationId: string, ctx?: {
+    tenantValue?: string;
+    session?: ClientSession;
+  }): Promise<boolean>;
+  /**
+   * 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.
+   */
+  private scopedFilter;
+}
+//#endregion
 //#region src/domain/entities/program.d.ts
 interface Program {
   _id: string;
@@ -275,12 +571,29 @@ interface Program {
 //#region src/repositories/program.repository.d.ts
 declare class ProgramRepository extends Repository<Program> {
   private dispatchDeps;
-  constructor(model: Model<Program>, plugins?: PluginType[], dispatchDeps?: DispatchDeps);
+  constructor(model: Model<Program>, plugins?: PluginType$1[], dispatchDeps?: DispatchDeps);
   activate(id: string, ctx: PromoContext): Promise<Program>;
   pause(id: string, ctx: PromoContext): Promise<Program>;
   archive(id: string, ctx: PromoContext): Promise<Program>;
   private _transition;
   incrementUsage(id: string, ctx?: Record<string, unknown>): Promise<Program>;
+  /**
+   * 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.
+   */
+  tryIncrementUsage(id: string, ctx?: Record<string, unknown>): Promise<Program | null>;
   decrementUsage(id: string, ctx?: Record<string, unknown>): Promise<Program>;
   getCustomerUsage(id: string, customerId: string, ctx?: Record<string, unknown>): Promise<number>;
   incrementCustomerUsage(id: string, customerId: string, ctx?: Record<string, unknown>): Promise<Program>;
@@ -309,7 +622,7 @@ interface Reward {
 //#endregion
 //#region src/repositories/reward.repository.d.ts
 declare class RewardRepository extends Repository<Reward> {
-  constructor(model: Model<Reward>, plugins?: PluginType[]);
+  constructor(model: Model<Reward>, plugins?: PluginType$1[]);
 }
 //#endregion
 //#region src/domain/entities/rule.d.ts
@@ -333,7 +646,7 @@ interface Rule {
 //#endregion
 //#region src/repositories/rule.repository.d.ts
 declare class RuleRepository extends Repository<Rule> {
-  constructor(model: Model<Rule>, plugins?: PluginType[]);
+  constructor(model: Model<Rule>, plugins?: PluginType$1[]);
 }
 //#endregion
 //#region src/domain/entities/voucher.d.ts
@@ -343,6 +656,12 @@ interface BalanceLedgerEntry {
   description?: string;
   createdAt: Date;
   idempotencyKey?: string;
+  /** Branch / store / location where the spend or top-up was performed.
+   *  Stamped from `ctx.organizationId` at write time. Vouchers themselves
+   *  remain company-wide (`tenant: false` deployments included) — this
+   *  field is purely for analytics ("redemptions per branch") and audit
+   *  ("which staff branch credited this card?") without joining orders. */
+  organizationId?: string;
 }
 interface VoucherRedemption {
   orderId: string;
@@ -350,6 +669,9 @@ interface VoucherRedemption {
   discountAmount: number;
   redeemedAt: Date;
   idempotencyKey?: string;
+  /** Branch / store / location where the redemption happened. Stamped
+   *  from `ctx.organizationId` at write time. See `BalanceLedgerEntry`. */
+  organizationId?: string;
 }
 interface Voucher {
   _id: string;
@@ -373,14 +695,19 @@ interface Voucher {
 declare class VoucherRepository extends Repository<Voucher> {
   private dispatchDeps;
   private tenantField;
-  constructor(model: Model<Voucher>, plugins?: PluginType[], dispatchDeps?: DispatchDeps, tenantField?: string);
+  private tenantEnabled;
+  constructor(model: Model<Voucher>, plugins?: PluginType$1[], dispatchDeps?: DispatchDeps, tenantField?: string, tenantEnabled?: boolean);
   /**
    * 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.
    */
   private _injectTenant;
   create(data: Parameters<Repository<Voucher>['create']>[0], options?: Parameters<Repository<Voucher>['create']>[1]): Promise<Voucher>;
@@ -416,6 +743,10 @@ declare class VoucherRepository extends Repository<Voucher> {
    * (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.
    */
   getByCode(code: string, ctx?: Record<string, unknown>): Promise<Voucher | null>;
   /**
@@ -432,6 +763,19 @@ interface PromoRepositories {
   rule: RuleRepository;
   reward: RewardRepository;
   voucher: VoucherRepository;
+  pendingEvaluation: PendingEvaluationRepository;
+}
+interface RepositoryPluginsMap {
+  program?: PluginType$1[];
+  rule?: PluginType$1[];
+  reward?: PluginType$1[];
+  voucher?: PluginType$1[];
+  pendingEvaluation?: PluginType$1[];
+}
+interface RepositoryDispatchDeps {
+  events?: EventTransport$1 | undefined;
+  outbox?: OutboxStore | undefined;
+  logger?: DispatchLogger | undefined;
 }
 //#endregion
 //#region src/domain/ports/unit-of-work.port.d.ts
@@ -440,88 +784,6 @@ interface UnitOfWork {
   withTransaction<T>(cb: (session: TransactionSession) => Promise<T>): Promise<T>;
 }
 //#endregion
-//#region src/types/results.d.ts
-interface DiscountLine {
-  programId: string;
-  programName: string;
-  rewardId: string;
-  type: 'percentage' | 'fixed';
-  scope: 'order' | 'cheapest' | 'specific_products';
-  amount: number;
-  description: string;
-  voucherCode?: string;
-}
-interface FreeProductLine {
-  programId: string;
-  programName: string;
-  rewardId: string;
-  productId?: string;
-  productSku?: string;
-  quantity: number;
-  description: string;
-}
-interface RejectedCode {
-  code: string;
-  reason: string;
-}
-interface EvaluationResult {
-  evaluationId: string;
-  /**
-   * Deterministic hash of the evaluated cart (items + subtotal + codes +
-   * customerId). Hosts that want tamper-proof commits pass this hash back
-   * to `EvaluationService.commit(evaluationId, orderId, ctx, { cartHash })`;
-   * the engine throws `CartHashMismatchError` when the caller's hash does
-   * not match what was evaluated. Omitting the hash at commit keeps the
-   * legacy "trusted host" behaviour.
-   */
-  cartHash: string;
-  appliedDiscounts: DiscountLine[];
-  freeProducts: FreeProductLine[];
-  totalDiscount: number;
-  subtotalAfterDiscount: number;
-  appliedCodes: string[];
-  rejectedCodes: RejectedCode[];
-  warnings: string[];
-  isPreview: boolean;
-  programsApplied: string[];
-}
-interface CommitResult {
-  evaluationId: string;
-  orderId: string;
-  totalDiscount: number;
-  programsCommitted: number;
-  vouchersUsed: number;
-}
-interface VoucherValidation {
-  valid: boolean;
-  voucher?: {
-    code: string;
-    programId: string;
-    programType: string;
-    status: string;
-    remainingUses: number;
-    currentBalance?: number;
-    expiresAt?: Date;
-  };
-  error?: string;
-}
-interface GiftCardBalance {
-  code: string;
-  initialBalance: number;
-  currentBalance: number;
-  spent: number;
-  voucherId: string;
-}
-interface PaginatedResult<T> {
-  docs: T[];
-  page: number;
-  limit: number;
-  total: number;
-  pages: number;
-  hasNext: boolean;
-  hasPrev: boolean;
-}
-//#endregion
 //#region src/services/evaluation.service.d.ts
 interface CommitOptions {
   /**
@@ -543,11 +805,12 @@ declare class EvaluationService {
   private unitOfWork;
   private dispatchDeps;
   private config;
-  private pendingEvaluations;
-  constructor(programRepo: ProgramRepository, ruleRepo: RuleRepository, rewardRepo: RewardRepository, voucherRepo: VoucherRepository, unitOfWork: UnitOfWork, dispatchDeps: DispatchDeps, config: ResolvedConfig);
+  private store;
+  constructor(programRepo: ProgramRepository, ruleRepo: RuleRepository, rewardRepo: RewardRepository, voucherRepo: VoucherRepository, unitOfWork: UnitOfWork, dispatchDeps: DispatchDeps, config: ResolvedConfig, store: EvaluationStore);
   evaluate(input: EvaluateInput, ctx: PromoContext): Promise<EvaluationResult>;
   preview(input: EvaluateInput, ctx: PromoContext): Promise<EvaluationResult>;
   commit(evaluationId: string, orderId: string, ctx: PromoContext, options?: CommitOptions): Promise<CommitResult>;
+  private commitInTransaction;
   rollback(evaluationId: string, ctx: PromoContext): Promise<void>;
   private doEvaluate;
   private isCustomerEligible;
@@ -585,6 +848,7 @@ declare class VoucherService {
   spend(input: GiftCardSpendInput, ctx: PromoContext): Promise<GiftCardBalance>;
   private spendInTransaction;
   topUp(input: GiftCardTopUpInput, ctx: PromoContext): Promise<GiftCardBalance>;
+  private topUpInTransaction;
   private assertVoucherUsable;
 }
 //#endregion
@@ -594,6 +858,147 @@ interface PromoServices {
   evaluation: EvaluationService;
 }
 //#endregion
+//#region src/adapters/mongo-evaluation-store.d.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.
+ */
+declare class MongoEvaluationStore implements EvaluationStore {
+  private readonly repo;
+  constructor(repo: PendingEvaluationRepository);
+  put(id: string, snapshot: StoredEvaluationSnapshot, ttlSeconds: number, ctx?: EvaluationStoreContext): Promise<void>;
+  take(id: string, ctx?: EvaluationStoreContext): Promise<StoredEvaluationSnapshot | null>;
+  delete(id: string, ctx?: EvaluationStoreContext): Promise<void>;
+}
+/**
+ * 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.
+ */
+declare class InMemoryEvaluationStore implements EvaluationStore {
+  private readonly map;
+  put(id: string, snapshot: StoredEvaluationSnapshot, ttlSeconds: number, ctx?: EvaluationStoreContext): Promise<void>;
+  take(id: string, ctx?: EvaluationStoreContext): Promise<StoredEvaluationSnapshot | null>;
+  delete(id: string, ctx?: EvaluationStoreContext): Promise<void>;
+  private key;
+}
+//#endregion
+//#region src/domain/errors/base.d.ts
+declare abstract class PromoError extends Error {
+  abstract readonly code: string;
+  constructor(message: string);
+}
+//#endregion
+//#region src/domain/errors/domain-errors.d.ts
+declare class ValidationError extends PromoError {
+  readonly code = "VALIDATION_ERROR";
+}
+declare class ProgramNotFoundError extends PromoError {
+  readonly code = "PROGRAM_NOT_FOUND";
+  constructor(id?: string);
+}
+/**
+ * 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.
+ */
+declare class ProgramUsageCapExceededError extends PromoError {
+  readonly programId: string;
+  readonly maxUsageTotal: number;
+  readonly code = "PROGRAM_USAGE_CAP_EXCEEDED";
+  constructor(programId: string, maxUsageTotal: number);
+}
+declare class RuleNotFoundError extends PromoError {
+  readonly code = "RULE_NOT_FOUND";
+  constructor(id?: string);
+}
+declare class RewardNotFoundError extends PromoError {
+  readonly code = "REWARD_NOT_FOUND";
+  constructor(id?: string);
+}
+declare class VoucherNotFoundError extends PromoError {
+  readonly code = "VOUCHER_NOT_FOUND";
+  constructor(codeOrId?: string);
+}
+declare class InvalidTransitionError extends PromoError {
+  readonly code = "INVALID_TRANSITION";
+  constructor(from: string, to: string);
+}
+declare class VoucherExpiredError extends PromoError {
+  readonly code = "VOUCHER_EXPIRED";
+  constructor(code: string);
+}
+declare class VoucherExhaustedError extends PromoError {
+  readonly code = "VOUCHER_EXHAUSTED";
+  constructor(code: string);
+}
+/**
+ * Thrown when a gift card's balance has been fully spent and its status
+ * flipped to `'used'`. Distinct from `VoucherExhaustedError` (usage-limit
+ * exhaustion on a discount voucher) so hosts can show "top up" vs "retry
+ * later" messaging.
+ */
+declare class GiftCardExhaustedError extends PromoError {
+  readonly code = "GIFT_CARD_EXHAUSTED";
+  constructor(code: string);
+}
+/**
+ * Thrown when a MongoDB WriteConflict surfaces under voucher-spend
+ * contention. Losers see a stable domain shape rather than the raw
+ * `"Write conflict during plan execution"` string. Hosts can translate
+ * this to HTTP 409 + retry.
+ */
+declare class ConcurrencyConflictError extends PromoError {
+  readonly resource: 'voucher' | 'program' | 'rule' | 'reward';
+  readonly resourceId: string;
+  readonly cause?: unknown | undefined;
+  readonly code = "CONCURRENCY_CONFLICT";
+  readonly status = 409;
+  constructor(resource: 'voucher' | 'program' | 'rule' | 'reward', resourceId: string, cause?: unknown | undefined);
+}
+declare class InsufficientBalanceError extends PromoError {
+  readonly code = "INSUFFICIENT_BALANCE";
+  constructor(code: string, available: number, requested: number);
+}
+declare class TenantIsolationError extends PromoError {
+  readonly code = "TENANT_ISOLATION";
+  constructor();
+}
+declare class DuplicateRedemptionError extends PromoError {
+  readonly code = "DUPLICATE_REDEMPTION";
+  constructor(key: string);
+}
+declare class EvaluationNotFoundError extends PromoError {
+  readonly code = "EVALUATION_NOT_FOUND";
+  constructor(id: string);
+}
+/**
+ * Thrown by `EvaluationService.commit` when the cart hash provided by the
+ * caller does not match the cart hash computed at evaluation time. Guards
+ * against cart-tampering attacks where a user previews a large discount on
+ * a heavy cart, mutates the cart to something cheaper before committing, and
+ * tries to apply the stale discount to the altered order.
+ */
+declare class CartHashMismatchError extends PromoError {
+  readonly code = "CART_HASH_MISMATCH";
+  constructor(evaluationId: string);
+}
+//#endregion
 //#region src/events/event-constants.d.ts
 declare const PromoEvents: {
   readonly PROGRAM_CREATED: "promo.program.created";
@@ -619,6 +1024,13 @@ declare const PromoEvents: {
 };
 type PromoEventName = (typeof PromoEvents)[keyof typeof PromoEvents];
 //#endregion
+//#region src/events/in-process-bus.d.ts
+interface InProcessPromoBusOptions {
+  logger?: {
+    error(message: string, ...args: unknown[]): void;
+  };
+}
+//#endregion
 //#region src/events/promo-event-catalog.d.ts
 interface PromoEventSchema {
   type: 'object';
@@ -640,6 +1052,95 @@ interface PromoEventDefinition<TSchema extends z.ZodType = z.ZodType> {
   readonly __payload?: z.infer<TSchema>;
 }
 type PromoEventPayloadOf<D> = D extends PromoEventDefinition<infer S> ? z.infer<S> : never;
+/** Mirrors `ProgramLifecyclePayload`. */
+declare const programLifecycleSchema: z.ZodObject<{
+  programId: z.ZodString;
+  programType: z.ZodString;
+  status: z.ZodString;
+  actorId: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+/** Mirrors `RulePayload`. */
+declare const ruleSchema: z.ZodObject<{
+  programId: z.ZodString;
+  ruleId: z.ZodString;
+  actorId: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+/** Mirrors `RewardPayload`. */
+declare const rewardSchema: z.ZodObject<{
+  programId: z.ZodString;
+  rewardId: z.ZodString;
+  actorId: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+/** Mirrors `VoucherGeneratedPayload`. */
+declare const voucherGeneratedSchema: z.ZodObject<{
+  programId: z.ZodString;
+  voucherIds: z.ZodArray<z.ZodString>;
+  codes: z.ZodArray<z.ZodString>;
+  count: z.ZodNumber;
+  actorId: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+/** Mirrors `VoucherRedeemedPayload`. */
+declare const voucherRedeemedSchema: z.ZodObject<{
+  voucherId: z.ZodString;
+  code: z.ZodString;
+  orderId: z.ZodString;
+  discountAmount: z.ZodNumber;
+  customerId: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+/**
+ * Mirrors `VoucherLifecyclePayload` — shared by VOUCHER_CANCELLED,
+ * VOUCHER_EXPIRED, and GIFT_CARD_EXHAUSTED (repo emits `status: 'cancelled'`
+ * / `'used'` / host-supplied terminal value).
+ */
+declare const voucherLifecycleSchema: z.ZodObject<{
+  voucherId: z.ZodString;
+  code: z.ZodString;
+  status: z.ZodString;
+}, z.core.$strip>;
+/** Mirrors `GiftCardSpentPayload`. */
+declare const giftCardSpentSchema: z.ZodObject<{
+  voucherId: z.ZodString;
+  code: z.ZodString;
+  amount: z.ZodNumber;
+  remainingBalance: z.ZodNumber;
+  orderId: z.ZodString;
+}, z.core.$strip>;
+/** Mirrors `GiftCardToppedUpPayload`. */
+declare const giftCardToppedUpSchema: z.ZodObject<{
+  voucherId: z.ZodString;
+  code: z.ZodString;
+  amount: z.ZodNumber;
+  newBalance: z.ZodNumber;
+}, z.core.$strip>;
+/** Mirrors `EvaluationCompletedPayload`. */
+declare const evaluationCompletedSchema: z.ZodObject<{
+  evaluationId: z.ZodString;
+  totalDiscount: z.ZodNumber;
+  programsApplied: z.ZodNumber;
+  codesUsed: z.ZodArray<z.ZodString>;
+  isPreview: z.ZodBoolean;
+}, z.core.$strip>;
+/** Mirrors `EvaluationCommittedPayload`. */
+declare const evaluationCommittedSchema: z.ZodObject<{
+  evaluationId: z.ZodString;
+  orderId: z.ZodString;
+  totalDiscount: z.ZodNumber;
+}, z.core.$strip>;
+/** Single-field rollback payload — emitted by `evaluation.service.ts`. */
+declare const evaluationRolledBackSchema: z.ZodObject<{
+  evaluationId: z.ZodString;
+}, z.core.$strip>;
+type ProgramLifecyclePayloadSchema = z.infer<typeof programLifecycleSchema>;
+type RulePayloadSchema = z.infer<typeof ruleSchema>;
+type RewardPayloadSchema = z.infer<typeof rewardSchema>;
+type VoucherGeneratedPayloadSchema = z.infer<typeof voucherGeneratedSchema>;
+type VoucherRedeemedPayloadSchema = z.infer<typeof voucherRedeemedSchema>;
+type VoucherLifecyclePayloadSchema = z.infer<typeof voucherLifecycleSchema>;
+type GiftCardSpentPayloadSchema = z.infer<typeof giftCardSpentSchema>;
+type GiftCardToppedUpPayloadSchema = z.infer<typeof giftCardToppedUpSchema>;
+type EvaluationCompletedPayloadSchema = z.infer<typeof evaluationCompletedSchema>;
+type EvaluationCommittedPayloadSchema = z.infer<typeof evaluationCommittedSchema>;
+type EvaluationRolledBackPayloadSchema = z.infer<typeof evaluationRolledBackSchema>;
 declare const ProgramCreated: PromoEventDefinition<z.ZodObject<{
   programId: z.ZodString;
   programType: z.ZodString;
@@ -768,6 +1269,43 @@ interface PromoEngine {
   events: EventTransport$1;
   syncIndexes(): Promise<void>;
 }
+/**
+ * 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).
+ */
 declare function createPromoEngine(config: PromoConfig): PromoEngine;
 //#endregion
-export { type BalanceLedgerEntry, type CartItem, type CommitResult, type CreateProgramInput, type CreateRewardInput, type CreateRuleInput, type DiscountLine, type DomainEvent, type EvaluateInput, EvaluationCommitted, EvaluationCompleted, type EvaluationResult, EvaluationRolledBack, type EventHandler, type EventTransport, type FreeProductLine, type GenerateCodesInput, type GenerateSingleCodeInput, type GiftCardBalance, GiftCardExhausted, type GiftCardSpendInput, GiftCardSpent, type GiftCardTopUpInput, GiftCardToppedUp, type ListQuery, type PaginatedResult, type Program, ProgramActivated, ProgramArchived, ProgramCreated, ProgramPaused, ProgramRepository, type PromoConfig, type PromoContext, PromoEngine, type PromoEventDefinition, type PromoEventName, type PromoEventPayloadOf, type PromoEventSchema, PromoEvents, type PromoModels, type PromoRepositories, type PromoServices, type RedeemVoucherInput, type RejectedCode, type ResolvedConfig, type ResolvedTenant, type Reward, RewardAdded, RewardRemoved, RewardRepository, RewardUpdated, type Rule, RuleAdded, RuleRemoved, RuleRepository, RuleUpdated, type UpdateProgramInput, type UpdateRewardInput, type UpdateRuleInput, type Voucher, VoucherCancelled, VoucherExpired, VoucherGenerated, VoucherRedeemed, type VoucherRedemption, VoucherRepository, type VoucherValidation, createPromoEngine, promoEventDefinitions, resolveConfig };
+export { type BalanceLedgerEntry, CartHashMismatchError, type CartItem, type CommitOptions, type CommitResult, ConcurrencyConflictError, type CreateProgramInput, type CreateRewardInput, type CreateRuleInput, type DiscountLine, type DomainEvent, DuplicateRedemptionError, type EvaluateInput, EvaluationCommitted, type EvaluationCommittedPayloadSchema, EvaluationCompleted, type EvaluationCompletedPayloadSchema, EvaluationNotFoundError, type EvaluationResult, EvaluationRolledBack, type EvaluationRolledBackPayloadSchema, type EvaluationStore, type EvaluationStoreContext, type EventHandler, type EventTransport, type FreeProductLine, type GenerateCodesInput, type GenerateSingleCodeInput, type GiftCardBalance, GiftCardExhausted, GiftCardExhaustedError, type GiftCardSpendInput, GiftCardSpent, type GiftCardSpentPayloadSchema, type GiftCardTopUpInput, GiftCardToppedUp, type GiftCardToppedUpPayloadSchema, InMemoryEvaluationStore, type InProcessPromoBusOptions, InsufficientBalanceError, InvalidTransitionError, type ListQuery, MongoEvaluationStore, type PaginatedResult, type PendingEvaluationDocument, PendingEvaluationRepository, type PluginType, type Program, ProgramActivated, ProgramArchived, ProgramCreated, type ProgramLifecyclePayloadSchema, ProgramNotFoundError, ProgramPaused, ProgramRepository, ProgramUsageCapExceededError, type PromoConfig, type PromoContext, PromoEngine, PromoError, type PromoEventDefinition, type PromoEventName, type PromoEventPayloadOf, type PromoEventSchema, PromoEvents, type PromoModels, type PromoRepositories, type PromoServices, type RedeemVoucherInput, type RejectedCode, type RepositoryDispatchDeps, type RepositoryPluginsMap, type ResolvedConfig, type ResolvedTenant, type Reward, RewardAdded, RewardNotFoundError, type RewardPayloadSchema, RewardRemoved, RewardRepository, RewardUpdated, type Rule, RuleAdded, RuleNotFoundError, type RulePayloadSchema, RuleRemoved, RuleRepository, RuleUpdated, type StoredEvaluationSnapshot, type TenantFieldType, TenantIsolationError, type UpdateProgramInput, type UpdateRewardInput, type UpdateRuleInput, ValidationError, type Voucher, VoucherCancelled, VoucherExhaustedError, VoucherExpired, VoucherExpiredError, VoucherGenerated, type VoucherGeneratedPayloadSchema, type VoucherLifecyclePayloadSchema, VoucherNotFoundError, VoucherRedeemed, type VoucherRedeemedPayloadSchema, type VoucherRedemption, VoucherRepository, type VoucherValidation, createPromoEngine, promoEventDefinitions, resolveConfig };