@classytic/promo 0.2.5 → 0.4.0

package/dist/index.d.mts

@@ -1,163 +1,191 @@
-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 { EvaluationCommitted, EvaluationCommittedPayloadSchema, EvaluationCompleted, EvaluationCompletedPayloadSchema, EvaluationRolledBack, EvaluationRolledBackPayloadSchema, GiftCardExhausted, GiftCardSpent, GiftCardSpentPayloadSchema, GiftCardToppedUp, GiftCardToppedUpPayloadSchema, ProgramActivated, ProgramArchived, ProgramCreated, ProgramLifecyclePayloadSchema, ProgramPaused, PromoEventDefinition, PromoEventPayloadOf, PromoEventSchema, RewardAdded, RewardPayloadSchema, RewardRemoved, RewardUpdated, RuleAdded, RulePayloadSchema, RuleRemoved, RuleUpdated, VoucherCancelled, VoucherExpired, VoucherGenerated, VoucherGeneratedPayloadSchema, VoucherLifecyclePayloadSchema, VoucherRedeemed, VoucherRedeemedPayloadSchema, promoEventDefinitions } from "./events/promo-event-catalog.mjs";
+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-hcMTDJml.mjs";
 import { PluginType as PluginType$1, Repository } from "@classytic/mongokit";
 import { ResolvedTenantConfig, TenantConfig, TenantFieldType } from "@classytic/repo-core/tenant";
 import { DomainEvent, DomainEvent as DomainEvent$1, EventHandler, EventTransport, EventTransport as EventTransport$1 } from "@classytic/primitives/events";
 import { ClientSession, Connection, Model } from "mongoose";
-import { z } from "zod";
+import { RetryPolicy } from "@classytic/repo-core/repository";
 import { OutboxStore } from "@classytic/primitives/outbox";
 import { OperationContext } from "@classytic/primitives/context";
+import { HttpError } from "@classytic/repo-core/errors";
 
 //#region src/types/inputs.d.ts
 /**
  * Extends `@classytic/primitives`' {@link OperationContext}. The
  * `[key: string]: unknown` fall-through lets hosts pass dynamic tenant keys
  * when they've configured a custom `contextKey` on `TenantConfig`.
+ *
+ * Primitives' `actorId` is replaced by `actorRef` — the commerce-wide
+ * convention (cart/order/flow) for "stable user id OR guest session id".
+ *
+ * **Option threading.** Promo deliberately spreads the WHOLE context into
+ * mongokit option bags (`{ lean: true, ...ctx }`) instead of using a
+ * fixed-key options extractor — the index-signature fall-through means a
+ * host's custom `contextKey` value reaches `multiTenantPlugin` without
+ * promo knowing its name. The typed fields below (`session`, `signal`,
+ * `retryPolicy`, `organizationId`) ride the same spread: mongokit 3.16
+ * reads them straight off the options bag (cancellation at every op
+ * boundary, `withRetry` around driver round-trips).
  */
-interface PromoContext extends OperationContext {
-  /** Narrowed from primitives' `IdLike` to string. */
-  actorId?: string;
+interface PromoContext extends Omit<OperationContext, 'actorId' | 'organizationId'> {
+  /**
+   * Actor identity — a stable user ID (authenticated) or a session ID
+   * (guest). Matches the `actorRef` convention used by `@classytic/cart`,
+   * `@classytic/order`, and `@classytic/flow`.
+   */
+  actorRef?: string | undefined;
   /** Narrowed from primitives' `IdLike` to string. */
-  organizationId?: string;
+  organizationId?: string | undefined;
   /** Narrows primitives' `session: unknown` to the concrete Mongoose type so
    *  this context flows directly into mongokit repository calls. */
-  session?: ClientSession;
+  session?: ClientSession | undefined;
+  /**
+   * Cooperative cancellation. Mongokit checks the signal at every op
+   * boundary; promo additionally checks it between iterations of its own
+   * batch loops (`expireByDate`, the per-program evaluation loop, the
+   * commit usage loops). Aborting never rolls back a committed write.
+   */
+  signal?: AbortSignal | undefined;
+  /** Per-call retry policy — mongokit wraps driver round-trips in
+   *  `withRetry` (never hooks; hooks run exactly once). */
+  retryPolicy?: RetryPolicy | undefined;
   [key: string]: unknown;
 }
 interface CreateProgramInput {
   name: string;
-  description?: string;
+  description?: string | undefined;
   programType: ProgramType;
   triggerMode: TriggerMode;
-  stackingMode?: StackingMode;
-  priority?: number;
-  startsAt?: Date;
-  endsAt?: Date;
-  maxUsageTotal?: number;
-  maxUsagePerCustomer?: number;
-  applicableCustomerIds?: string[];
-  applicableCustomerTags?: string[];
-  metadata?: Record<string, unknown>;
+  stackingMode?: StackingMode | undefined;
+  priority?: number | undefined;
+  startsAt?: Date | undefined;
+  endsAt?: Date | undefined;
+  maxUsageTotal?: number | undefined;
+  maxUsagePerCustomer?: number | undefined;
+  applicableCustomerIds?: string[] | undefined;
+  applicableCustomerTags?: string[] | undefined;
+  metadata?: Record<string, unknown> | undefined;
 }
 interface UpdateProgramInput {
-  name?: string;
-  description?: string;
-  stackingMode?: StackingMode;
-  priority?: number;
-  startsAt?: Date;
-  endsAt?: Date;
-  maxUsageTotal?: number;
-  maxUsagePerCustomer?: number;
-  applicableCustomerIds?: string[];
-  applicableCustomerTags?: string[];
-  metadata?: Record<string, unknown>;
+  name?: string | undefined;
+  description?: string | undefined;
+  stackingMode?: StackingMode | undefined;
+  priority?: number | undefined;
+  startsAt?: Date | undefined;
+  endsAt?: Date | undefined;
+  maxUsageTotal?: number | undefined;
+  maxUsagePerCustomer?: number | undefined;
+  applicableCustomerIds?: string[] | undefined;
+  applicableCustomerTags?: string[] | undefined;
+  metadata?: Record<string, unknown> | undefined;
 }
 interface CreateRuleInput {
-  name?: string;
-  minimumAmount?: number;
-  minimumQuantity?: number;
-  applicableProductIds?: string[];
-  applicableCategories?: string[];
-  applicableSkus?: string[];
-  buyQuantity?: number;
-  code?: string;
-  startsAt?: Date;
-  endsAt?: Date;
-  metadata?: Record<string, unknown>;
+  name?: string | undefined;
+  minimumAmount?: number | undefined;
+  minimumQuantity?: number | undefined;
+  applicableProductIds?: string[] | undefined;
+  applicableCategories?: string[] | undefined;
+  applicableSkus?: string[] | undefined;
+  buyQuantity?: number | undefined;
+  code?: string | undefined;
+  startsAt?: Date | undefined;
+  endsAt?: Date | undefined;
+  metadata?: Record<string, unknown> | undefined;
 }
 interface UpdateRuleInput {
-  name?: string;
-  minimumAmount?: number;
-  minimumQuantity?: number;
-  applicableProductIds?: string[];
-  applicableCategories?: string[];
-  applicableSkus?: string[];
-  buyQuantity?: number;
-  code?: string;
-  startsAt?: Date;
-  endsAt?: Date;
-  metadata?: Record<string, unknown>;
+  name?: string | undefined;
+  minimumAmount?: number | undefined;
+  minimumQuantity?: number | undefined;
+  applicableProductIds?: string[] | undefined;
+  applicableCategories?: string[] | undefined;
+  applicableSkus?: string[] | undefined;
+  buyQuantity?: number | undefined;
+  code?: string | undefined;
+  startsAt?: Date | undefined;
+  endsAt?: Date | undefined;
+  metadata?: Record<string, unknown> | undefined;
 }
 interface CreateRewardInput {
-  ruleId?: string;
+  ruleId?: string | undefined;
   rewardType: RewardType;
-  discountMode?: DiscountMode;
-  discountAmount?: number;
-  maxDiscountAmount?: number;
-  discountScope?: DiscountScope;
-  applicableProductIds?: string[];
-  freeProductId?: string;
-  freeProductSku?: string;
-  freeQuantity?: number;
-  giftCardAmount?: number;
-  metadata?: Record<string, unknown>;
+  discountMode?: DiscountMode | undefined;
+  discountAmount?: number | undefined;
+  maxDiscountAmount?: number | undefined;
+  discountScope?: DiscountScope | undefined;
+  applicableProductIds?: string[] | undefined;
+  freeProductId?: string | undefined;
+  freeProductSku?: string | undefined;
+  freeQuantity?: number | undefined;
+  giftCardAmount?: number | undefined;
+  metadata?: Record<string, unknown> | undefined;
 }
 interface UpdateRewardInput {
-  discountMode?: DiscountMode;
-  discountAmount?: number;
-  maxDiscountAmount?: number;
-  discountScope?: DiscountScope;
-  applicableProductIds?: string[];
-  freeProductId?: string;
-  freeProductSku?: string;
-  freeQuantity?: number;
-  giftCardAmount?: number;
-  metadata?: Record<string, unknown>;
+  discountMode?: DiscountMode | undefined;
+  discountAmount?: number | undefined;
+  maxDiscountAmount?: number | undefined;
+  discountScope?: DiscountScope | undefined;
+  applicableProductIds?: string[] | undefined;
+  freeProductId?: string | undefined;
+  freeProductSku?: string | undefined;
+  freeQuantity?: number | undefined;
+  giftCardAmount?: number | undefined;
+  metadata?: Record<string, unknown> | undefined;
 }
 interface GenerateCodesInput {
   programId: string;
   count: number;
-  customerId?: string;
-  expiresAt?: Date;
-  metadata?: Record<string, unknown>;
+  customerId?: string | undefined;
+  expiresAt?: Date | undefined;
+  metadata?: Record<string, unknown> | undefined;
 }
 interface GenerateSingleCodeInput {
   programId: string;
-  code?: string;
-  customerId?: string;
-  expiresAt?: Date;
-  initialBalance?: number;
-  metadata?: Record<string, unknown>;
+  code?: string | undefined;
+  customerId?: string | undefined;
+  expiresAt?: Date | undefined;
+  initialBalance?: number | undefined;
+  metadata?: Record<string, unknown> | undefined;
 }
 interface RedeemVoucherInput {
   code: string;
   orderId: string;
-  customerId?: string;
+  customerId?: string | undefined;
   discountAmount: number;
-  idempotencyKey?: string;
+  idempotencyKey?: string | undefined;
 }
 interface GiftCardSpendInput {
   code: string;
   amount: number;
   orderId: string;
-  description?: string;
-  idempotencyKey?: string;
+  description?: string | undefined;
+  idempotencyKey?: string | undefined;
 }
 interface GiftCardTopUpInput {
   code: string;
   amount: number;
-  description?: string;
-  idempotencyKey?: string;
+  description?: string | undefined;
+  idempotencyKey?: string | undefined;
 }
 interface CartItem {
   productId: string;
-  sku?: string;
-  categoryId?: string;
+  sku?: string | undefined;
+  categoryId?: string | undefined;
   quantity: number;
   unitPrice: number;
-  lineTotal?: number;
+  lineTotal?: number | undefined;
 }
 interface EvaluateInput {
   items: CartItem[];
   subtotal: number;
-  codes?: string[];
-  customerId?: string;
-  customerTags?: string[];
+  codes?: string[] | undefined;
+  customerId?: string | undefined;
+  customerTags?: string[] | undefined;
 }
 interface ListQuery {
-  page?: number;
-  limit?: number;
-  sort?: string;
-  filters?: Record<string, unknown>;
+  page?: number | undefined;
+  limit?: number | undefined;
+  sort?: string | undefined;
+  filters?: Record<string, unknown> | undefined;
 }
 //#endregion
 //#region src/types/results.d.ts
@@ -169,14 +197,14 @@ interface DiscountLine {
   scope: 'order' | 'cheapest' | 'specific_products';
   amount: number;
   description: string;
-  voucherCode?: string;
+  voucherCode?: string | undefined;
 }
 interface FreeProductLine {
   programId: string;
   programName: string;
   rewardId: string;
-  productId?: string;
-  productSku?: string;
+  productId?: string | undefined;
+  productSku?: string | undefined;
   quantity: number;
   description: string;
 }
@@ -220,10 +248,10 @@ interface VoucherValidation {
     programType: string;
     status: string;
     remainingUses: number;
-    currentBalance?: number;
-    expiresAt?: Date;
+    currentBalance?: number | undefined;
+    expiresAt?: Date | undefined;
   };
-  error?: string;
+  error?: string | undefined;
 }
 interface GiftCardBalance {
   code: string;
@@ -255,7 +283,7 @@ interface PaginatedResult<T> {
 interface StoredEvaluationSnapshot {
   readonly result: EvaluationResult;
   readonly ctx: PromoContext;
-  readonly customerId?: string;
+  readonly customerId?: string | undefined;
   readonly programUsages: ReadonlyArray<{
     programId: string;
   }>;
@@ -284,7 +312,7 @@ interface StoredEvaluationSnapshot {
  * have to translate between context shapes at the call site.
  */
 interface EvaluationStoreContext {
-  readonly tenantValue?: string;
+  readonly tenantValue?: string | undefined;
   readonly session?: unknown;
 }
 /**
@@ -387,6 +415,34 @@ interface PromoConfig {
   } | undefined;
   indexes?: Partial<Record<ModelName, IndexDefinition[]>> | undefined;
   autoIndex?: boolean | Partial<Record<ModelName, boolean>> | undefined;
+  /**
+   * Optional namespace prepended to every physical collection promo
+   * creates (PACKAGE_RULES §20.1) — e.g. `'commerce_'` →
+   * `commerce_promoprograms`. Model names are never prefixed, so `ref:`
+   * populate keeps working. Unset → the historical default names
+   * (`promoprograms`, `promorules`, `promorewards`, `promovouchers`,
+   * `promopendingevaluations`).
+   */
+  collectionPrefix?: string | undefined;
+  /**
+   * When true, existing Mongoose models with promo's names on the
+   * connection are deleted and re-registered — hot-reload / test fixtures
+   * only. Default `false`: a name collision throws
+   * `PromoModelCollisionError` (rule 21). Two promo engines in one
+   * process need two Mongoose connections.
+   */
+  forceRecreate?: boolean | undefined;
+  /**
+   * Escape hatch for the boot-time capability gate. Promo's commit /
+   * redeem / spend / topUp paths are transactional; by default
+   * `createPromoEngine` asserts the backend's `capabilities.transactions`
+   * flag at boot (fail loud at boot, not with a cryptic error 263 on the
+   * first checkout). `allowNonTransactional: true` skips the gate AND lets
+   * the internal unit-of-work fall back to non-transactional execution on
+   * standalone MongoDB (dev / CI without a replica set) — atomicity across
+   * documents is then best-effort.
+   */
+  allowNonTransactional?: boolean | undefined;
   events?: {
     transport?: EventTransport$1 | undefined;
   } | undefined;
@@ -448,6 +504,21 @@ interface PromoModels {
   Voucher: Model<unknown>;
   PendingEvaluation: Model<unknown>;
 }
+/**
+ * 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).
+ */
+declare const DEFAULT_COLLECTIONS: {
+  readonly PromoProgram: "promoprograms";
+  readonly PromoRule: "promorules";
+  readonly PromoReward: "promorewards";
+  readonly PromoVoucher: "promovouchers";
+  readonly PromoPendingEvaluation: "promopendingevaluations";
+};
 //#endregion
 //#region src/events/dispatch.d.ts
 interface DispatchLogger {
@@ -458,6 +529,23 @@ interface DispatchDeps {
   outbox?: OutboxStore | undefined;
   logger?: DispatchLogger | undefined;
 }
+/**
+ * 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.
+ */
+declare const PENDING_PROMO_EVENTS: unique symbol;
+/**
+ * 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.
+ */
+declare function flushPendingPromoEvents(deps: DispatchDeps, events: DomainEvent$1[]): Promise<void>;
 //#endregion
 //#region src/repositories/pending-evaluation.repository.d.ts
 /**
@@ -525,16 +613,16 @@ declare class PendingEvaluationRepository extends Repository<PendingEvaluationDo
    * keep cross-tenant isolation on the cache layer too.
    */
   takeByEvaluationId(evaluationId: string, ctx?: {
-    tenantValue?: string;
-    session?: ClientSession;
+    tenantValue?: string | undefined;
+    session?: ClientSession | undefined;
   }): 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;
+    tenantValue?: string | undefined;
+    session?: ClientSession | undefined;
   }): Promise<boolean>;
   /**
    * Build a query filter with the configured tenant scope appended,
@@ -766,11 +854,11 @@ interface PromoRepositories {
   pendingEvaluation: PendingEvaluationRepository;
 }
 interface RepositoryPluginsMap {
-  program?: PluginType$1[];
-  rule?: PluginType$1[];
-  reward?: PluginType$1[];
-  voucher?: PluginType$1[];
-  pendingEvaluation?: PluginType$1[];
+  program?: PluginType$1[] | undefined;
+  rule?: PluginType$1[] | undefined;
+  reward?: PluginType$1[] | undefined;
+  voucher?: PluginType$1[] | undefined;
+  pendingEvaluation?: PluginType$1[] | undefined;
 }
 interface RepositoryDispatchDeps {
   events?: EventTransport$1 | undefined;
@@ -840,6 +928,28 @@ declare class VoucherService {
   private dispatchDeps;
   private config;
   constructor(voucherRepo: VoucherRepository, programRepo: ProgramRepository, unitOfWork: UnitOfWork, dispatchDeps: DispatchDeps, config: ResolvedConfig);
+  /**
+   * 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).
+   */
+  private runTransactional;
   generateCodes(input: GenerateCodesInput, ctx: PromoContext): Promise<Voucher[]>;
   generateSingleCode(input: GenerateSingleCodeInput, ctx: PromoContext): Promise<Voucher>;
   validateCode(code: string, ctx: PromoContext): Promise<VoucherValidation>;
@@ -897,17 +1007,17 @@ declare class InMemoryEvaluationStore implements EvaluationStore {
 }
 //#endregion
 //#region src/domain/errors/base.d.ts
-declare abstract class PromoError extends Error {
-  abstract readonly code: string;
-  constructor(message: string);
+declare class PromoError extends Error implements HttpError {
+  readonly code: string;
+  readonly status: number;
+  constructor(message: string, code: string, status: number);
 }
 //#endregion
 //#region src/domain/errors/domain-errors.d.ts
 declare class ValidationError extends PromoError {
-  readonly code = "VALIDATION_ERROR";
+  constructor(message: string);
 }
 declare class ProgramNotFoundError extends PromoError {
-  readonly code = "PROGRAM_NOT_FOUND";
   constructor(id?: string);
 }
 /**
@@ -920,31 +1030,24 @@ declare class ProgramNotFoundError extends PromoError {
 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);
 }
 /**
@@ -954,7 +1057,6 @@ declare class VoucherExhaustedError extends PromoError {
  * later" messaging.
  */
 declare class GiftCardExhaustedError extends PromoError {
-  readonly code = "GIFT_CARD_EXHAUSTED";
   constructor(code: string);
 }
 /**
@@ -967,24 +1069,28 @@ 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);
 }
+/**
+ * Residual E11000 on the voucher `code` unique index, classified via
+ * mongokit's `isDuplicateKeyError` and re-thrown as this typed shape
+ * (Concurrency House Rules: "typed collision errors are the contract;
+ * the unique index is the authoritative guard"). Realistic path:
+ * `generateSingleCode` with a caller-supplied code that already exists.
+ */
+declare class DuplicateVoucherCodeError extends PromoError {
+  constructor(code?: string);
+}
 declare class EvaluationNotFoundError extends PromoError {
-  readonly code = "EVALUATION_NOT_FOUND";
   constructor(id: string);
 }
 /**
@@ -995,9 +1101,18 @@ declare class EvaluationNotFoundError extends PromoError {
  * tries to apply the stale discount to the altered order.
  */
 declare class CartHashMismatchError extends PromoError {
-  readonly code = "CART_HASH_MISMATCH";
   constructor(evaluationId: string);
 }
+/**
+ * Thrown by `createModels` when a Mongoose model with one of promo's names
+ * is already registered on the connection (rule 21). Silent `deleteModel`
+ * would clobber another engine's models; the throw makes the collision
+ * loud. Hot-reload / test fixtures opt in via `forceRecreate: true`; two
+ * promo engines in one process need two Mongoose connections.
+ */
+declare class PromoModelCollisionError extends PromoError {
+  constructor(modelName: string);
+}
 //#endregion
 //#region src/events/event-constants.d.ts
 declare const PromoEvents: {
@@ -1031,237 +1146,20 @@ interface InProcessPromoBusOptions {
   };
 }
 //#endregion
-//#region src/events/promo-event-catalog.d.ts
-interface PromoEventSchema {
-  type: 'object';
-  properties?: Record<string, {
-    type?: string;
-    format?: string;
-    [key: string]: unknown;
-  }>;
-  required?: string[];
-  [key: string]: unknown;
-}
-interface PromoEventDefinition<TSchema extends z.ZodType = z.ZodType> {
-  readonly name: string;
-  readonly version: number;
-  readonly description?: string;
-  readonly schema: PromoEventSchema;
-  readonly zodSchema: TSchema;
-  create(payload: z.infer<TSchema>, meta?: Partial<DomainEvent$1['meta']>): DomainEvent$1<z.infer<TSchema>>;
-  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;
-  status: z.ZodString;
-  actorId: z.ZodOptional<z.ZodString>;
-}, z.core.$strip>>;
-declare const ProgramActivated: PromoEventDefinition<z.ZodObject<{
-  programId: z.ZodString;
-  programType: z.ZodString;
-  status: z.ZodString;
-  actorId: z.ZodOptional<z.ZodString>;
-}, z.core.$strip>>;
-declare const ProgramPaused: PromoEventDefinition<z.ZodObject<{
-  programId: z.ZodString;
-  programType: z.ZodString;
-  status: z.ZodString;
-  actorId: z.ZodOptional<z.ZodString>;
-}, z.core.$strip>>;
-declare const ProgramArchived: PromoEventDefinition<z.ZodObject<{
-  programId: z.ZodString;
-  programType: z.ZodString;
-  status: z.ZodString;
-  actorId: z.ZodOptional<z.ZodString>;
-}, z.core.$strip>>;
-declare const RuleAdded: PromoEventDefinition<z.ZodObject<{
-  programId: z.ZodString;
-  ruleId: z.ZodString;
-  actorId: z.ZodOptional<z.ZodString>;
-}, z.core.$strip>>;
-declare const RuleUpdated: PromoEventDefinition<z.ZodObject<{
-  programId: z.ZodString;
-  ruleId: z.ZodString;
-  actorId: z.ZodOptional<z.ZodString>;
-}, z.core.$strip>>;
-declare const RuleRemoved: PromoEventDefinition<z.ZodObject<{
-  programId: z.ZodString;
-  ruleId: z.ZodString;
-  actorId: z.ZodOptional<z.ZodString>;
-}, z.core.$strip>>;
-declare const RewardAdded: PromoEventDefinition<z.ZodObject<{
-  programId: z.ZodString;
-  rewardId: z.ZodString;
-  actorId: z.ZodOptional<z.ZodString>;
-}, z.core.$strip>>;
-declare const RewardUpdated: PromoEventDefinition<z.ZodObject<{
-  programId: z.ZodString;
-  rewardId: z.ZodString;
-  actorId: z.ZodOptional<z.ZodString>;
-}, z.core.$strip>>;
-declare const RewardRemoved: PromoEventDefinition<z.ZodObject<{
-  programId: z.ZodString;
-  rewardId: z.ZodString;
-  actorId: z.ZodOptional<z.ZodString>;
-}, z.core.$strip>>;
-declare const VoucherGenerated: PromoEventDefinition<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>>;
-declare const VoucherRedeemed: PromoEventDefinition<z.ZodObject<{
-  voucherId: z.ZodString;
-  code: z.ZodString;
-  orderId: z.ZodString;
-  discountAmount: z.ZodNumber;
-  customerId: z.ZodOptional<z.ZodString>;
-}, z.core.$strip>>;
-declare const VoucherCancelled: PromoEventDefinition<z.ZodObject<{
-  voucherId: z.ZodString;
-  code: z.ZodString;
-  status: z.ZodString;
-}, z.core.$strip>>;
-declare const VoucherExpired: PromoEventDefinition<z.ZodObject<{
-  voucherId: z.ZodString;
-  code: z.ZodString;
-  status: z.ZodString;
-}, z.core.$strip>>;
-declare const GiftCardSpent: PromoEventDefinition<z.ZodObject<{
-  voucherId: z.ZodString;
-  code: z.ZodString;
-  amount: z.ZodNumber;
-  remainingBalance: z.ZodNumber;
-  orderId: z.ZodString;
-}, z.core.$strip>>;
-declare const GiftCardToppedUp: PromoEventDefinition<z.ZodObject<{
-  voucherId: z.ZodString;
-  code: z.ZodString;
-  amount: z.ZodNumber;
-  newBalance: z.ZodNumber;
-}, z.core.$strip>>;
-declare const GiftCardExhausted: PromoEventDefinition<z.ZodObject<{
-  voucherId: z.ZodString;
-  code: z.ZodString;
-  status: z.ZodString;
-}, z.core.$strip>>;
-declare const EvaluationCompleted: PromoEventDefinition<z.ZodObject<{
-  evaluationId: z.ZodString;
-  totalDiscount: z.ZodNumber;
-  programsApplied: z.ZodNumber;
-  codesUsed: z.ZodArray<z.ZodString>;
-  isPreview: z.ZodBoolean;
-}, z.core.$strip>>;
-declare const EvaluationCommitted: PromoEventDefinition<z.ZodObject<{
-  evaluationId: z.ZodString;
-  orderId: z.ZodString;
-  totalDiscount: z.ZodNumber;
-}, z.core.$strip>>;
-declare const EvaluationRolledBack: PromoEventDefinition<z.ZodObject<{
-  evaluationId: z.ZodString;
-}, z.core.$strip>>;
-/**
- * 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.
- */
-declare const promoEventDefinitions: ReadonlyArray<PromoEventDefinition>;
-//#endregion
 //#region src/index.d.ts
 declare function resolveConfig(config: PromoConfig): ResolvedConfig;
+/**
+ * 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.
+ */
+declare function assertPromoCapabilities(capabilities: Record<string, unknown> | undefined): void;
 interface PromoEngine {
   models: PromoModels;
   repositories: PromoRepositories;
@@ -1308,4 +1206,4 @@ interface PromoEngine {
  */
 declare function createPromoEngine(config: PromoConfig): PromoEngine;
 //#endregion
-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 };
+export { type BalanceLedgerEntry, CartHashMismatchError, type CartItem, type CommitOptions, type CommitResult, ConcurrencyConflictError, type CreateProgramInput, type CreateRewardInput, type CreateRuleInput, DEFAULT_COLLECTIONS, type DiscountLine, type DispatchDeps, type DispatchLogger, type DomainEvent, DuplicateRedemptionError, DuplicateVoucherCodeError, 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, PENDING_PROMO_EVENTS, 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, PromoModelCollisionError, 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, assertPromoCapabilities, createPromoEngine, flushPendingPromoEvents, promoEventDefinitions, resolveConfig };