@classytic/promo 0.2.3 → 0.4.0

package/CHANGELOG.md

@@ -3,6 +3,186 @@
 Format based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 adhering to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.4.0] — 2026-06-12
+
+PACKAGE_RULES compliance pass on top of 0.3.0 (errors, rule 18/20.1/21,
+P8 post-commit publish, P10, signal/retryPolicy, boot gate).
+
+### BREAKING
+
+- **Error taxonomy → `HttpError`.** Every domain error now implements
+  `HttpError` from `@classytic/repo-core/errors`: hierarchical lowercase
+  `code` (`promo.voucher.exhausted`, `promo.evaluation.cart_hash_mismatch`,
+  …) plus an HTTP `status` (404/409/400). The old UPPER_SNAKE codes
+  (`VOUCHER_EXHAUSTED`, …) are GONE — hosts switching on `error.code`
+  strings must migrate; `instanceof` catches and messages are unchanged.
+  Arc serializes these via `toErrorContract()` with zero host mapping.
+- **Model-registry collisions throw (rule 21).** `createPromoEngine` no
+  longer silently `deleteModel`s pre-registered promo models; it throws
+  `PromoModelCollisionError`. Hot-reload / test fixtures opt in via
+  `forceRecreate: true`; two engines in one process need two connections.
+- **Boot capability gate.** `createPromoEngine` asserts the backend's
+  `capabilities.transactions` flag at creation (commit/redeem/spend/topUp
+  are transactional). `allowNonTransactional: true` skips the gate AND
+  enables mongokit's standalone-Mongo fallback on the internal
+  unit-of-work (dev/CI escape hatch).
+- **Post-commit transport publish (§P8 phased variant).** When promo owns
+  the transaction, in-process `transport.publish` now fires AFTER commit
+  (pending-queue flush) instead of inside the transaction — subscribers
+  no longer receive ghost events when the transaction rolls back, and
+  handlers that re-read the DB observe the committed state. Outbox saves
+  are unchanged (in-transaction, session-bound, failures propagate).
+  Subscribers that relied on publishes observing in-transaction timing
+  must adjust. When the HOST owns the session (`ctx.session`): attach a
+  `DomainEvent[]` under the exported `PENDING_PROMO_EVENTS` symbol and
+  drain it with `flushPendingPromoEvents` after your commit for the same
+  guarantee; without a queue the in-scope publish is the documented best
+  effort (promo cannot know when a host commits — rule 33; the durable
+  outbox row still rolls back correctly either way).
+
+### Added
+
+- **`@classytic/promo/events` subpath** — the Zod event catalog
+  (`promoEventDefinitions`, per-event definitions, payload types) without
+  pulling the engine factory (rule 18). Root re-exports unchanged.
+- **Explicit collection names + `collectionPrefix` (rule 20.1).**
+  Physical names are pinned to the historical pluralizer output
+  (`promoprograms`, `promorules`, `promorewards`, `promovouchers`,
+  `promopendingevaluations` — zero migration) via the exported
+  `DEFAULT_COLLECTIONS`; `collectionPrefix: 'commerce_'` re-namespaces
+  without touching model names (populate unaffected).
+- **`DuplicateVoucherCodeError`** (`promo.voucher.duplicate_code`, 409) —
+  residual E11000 on the voucher `code` unique index is classified via
+  mongokit's `isDuplicateKeyError` in `generateCodes` /
+  `generateSingleCode` instead of leaking a raw driver error.
+- **`ctx.signal` / `ctx.retryPolicy`** on `PromoContext` — mongokit 3.16
+  reads both off the forwarded context (cancellation at every op
+  boundary, `withRetry` on driver round-trips); promo additionally checks
+  `signal` between iterations of its batch loops (`expireByDate`, the
+  per-program evaluation loop, the commit usage loops).
+- `PENDING_PROMO_EVENTS` + `flushPendingPromoEvents` exported for hosts
+  coordinating post-commit publishes on host-owned sessions.
+
+### Changed
+
+- **`exactOptionalPropertyTypes: true`** (P10) — optional fields across
+  config/input/port interfaces are now `T | undefined`; internal repo
+  calls go through an undefined-stripping options forwarder
+  (`repoOptionsFromCtx`) that preserves promo's dynamic tenant
+  `contextKey` forwarding.
+- tsconfig `declarationMap` / `sourceMap` switched off (build hygiene —
+  tsdown output was already map-free; the published artifact is
+  unchanged).
+- Suite grown 339 → 380 tests (35 → 38 files): error-contract matrix,
+  pending-queue/flush unit tests, post-commit publish integration tests
+  (ghost-event regression), model-collision / collection-name /
+  duplicate-code / abort-signal / boot-gate coverage.
+
+### Audited (no change required)
+
+- §P8 `outbox.save` propagation — already correct since 0.2.5.
+- Rule 18 catalog — all 20 events had Zod definitions + the no-drift
+  test; only the `./events` subpath was missing.
+- "Raw `ZodError` thrown at service boundaries" (cross-package audit
+  claim) — did not reproduce: promo's services throw typed
+  `ValidationError`s; the `/schemas` subpath is host-facing only.
+- §P9 dual-ID — `customIdPlugin` not used, N/A.
+- No `file:` dev links; lockfile refreshed so the installed mongokit /
+  repo-core actually match the 0.3.0 peer floors (3.16.0 / 0.6.0 — the
+  lockfile still resolved 3.13.3 / 0.4.2).
+
+## [0.3.0] — 2026-06-11
+
+### BREAKING
+
+- **Context field renamed: `actorId` → `actorRef`** — aligns promo with the
+  commerce-wide convention used by `@classytic/cart`, `@classytic/order`, and
+  `@classytic/flow` ("stable user id OR guest session id"). Clean break, no
+  alias. Hosts must rename the field on every `PromoContext` they build.
+  Affects: `PromoContext` (`Omit`s primitives' `actorId`), event meta
+  (`ctx.actorRef` → `meta.userId`), and event payloads — the
+  `ProgramLifecycle` / `Rule` / `Reward` / `VoucherGenerated` payload schemas
+  now carry `actorRef` instead of `actorId`. Event subscribers reading
+  `payload.actorId` must switch to `payload.actorRef`.
+
+### Added
+
+- **Session threading — atomic checkout-chain participation.** When the host
+  passes a Mongoose `ClientSession` via `ctx.session`,
+  `evaluation.commit` / `rollback` and `voucher.redeem` / `spend` / `topUp`
+  now JOIN that transaction instead of opening their own — promo writes
+  (program usage, voucher redemptions, gift-card ledger, snapshot take)
+  commit or abort atomically with the host's order. The host owns
+  commit/abort/retry on a joined session (MongoDB has no nested
+  transactions). Without `ctx.session` each method owns its transaction via
+  mongokit's `withTransaction` as before.
+- `evaluate` now threads `ctx.session` into the snapshot `store.put` and
+  `rollback` into `store.delete`, so evaluate→commit inside one host
+  transaction is read-your-writes consistent. The live session is stripped
+  from the persisted snapshot ctx (a driver handle is not data).
+- Integration suite: `tests/integration/checkout-session-threading.test.ts`
+  — aborted host transaction leaves no voucher-usage/program-usage rows and
+  the snapshot survives for retry; evaluate+commit inside one committed
+  transaction works; redeem/spend join + roll back correctly.
+
+### Changed
+
+- Peer ranges raised: `@classytic/mongokit` `>=3.16.0` (was `>=3.13.3`),
+  `@classytic/repo-core` `>=0.6.0` (was `>=0.4.2`).
+
+## [0.2.5] — 2026-05-08
+
+### Fixed
+
+- **§P8 dispatch — `outbox.save` failures now propagate.** [src/events/dispatch.ts](src/events/dispatch.ts)
+  previously caught `outbox.save` errors and only logged them, swallowing
+  the failure. Per PACKAGE_RULES §P8 the outbox row is the durability
+  anchor for the transactional-outbox pattern: if the save fails, the
+  caller's transaction MUST roll back so the business doc and the event
+  row land atomically. Swallowing meant a parent doc could commit while
+  the event vanished, with no relay row to recover from. Fix re-throws
+  after logging, matching the textbook §P8 shape used in
+  `@classytic/loyalty` 0.2.3 and `@classytic/order`.
+- `events.publish` failures continue to be swallowed (correctly, per §P8 —
+  the host's outbox relay re-publishes from the durable row), with logging
+  preserved for observability.
+
+### Changed
+
+- **Peer-dep ranges tightened** — `@classytic/mongokit` `>=3.13.3`
+  (was `>=3.13.0`) and `@classytic/repo-core` `>=0.4.2` (was `>=0.4.0`).
+  3.13.3 preserves `errorLabels` on `MongoServerError` so concurrent
+  transactional writes (the `claim()`-based program / voucher state
+  transitions) retry correctly under contention; 0.4.2 adds the typed
+  `FindAllOptions` shape with optional `limit?` for callers that need
+  bounded non-paginated reads.
+
+### Audited (no change required)
+
+- Two `Model.*` raw-driver sites in
+  [src/repositories/pending-evaluation.repository.ts](src/repositories/pending-evaluation.repository.ts)
+  (`findOneAndDelete`, `deleteOne`) confirmed as the documented atomic
+  take-and-return semantic that mongokit's `delete()` doesn't expose.
+  Tenant scoping is re-implemented at the repository layer (mirrors
+  `multiTenantPlugin`'s injection) so the bypass keeps cross-tenant
+  isolation intact.
+- `customIdPlugin` not used — §P9 dual-id resolution N/A.
+
+## [0.2.4]
+
+### Fixed
+
+- **`evaluation.preview` / `evaluation.evaluate`**: submitted codes are now
+  trimmed (in addition to uppercased) before resolution. `'  bigboss10  '`
+  resolves to `'BIGBOSS10'` and is reported under that canonical form in
+  `appliedCodes`. Duplicates after normalization are de-duped (a single code
+  submitted multiple times appears once).
+- **Empty-cart preview**: when `items` is empty (or `subtotal <= 0`), the
+  engine now rejects all submitted codes with `reason: 'Cart is empty'`
+  instead of listing them under `appliedCodes` with `totalDiscount: 0`. Hosts
+  that surface `appliedCodes` directly to the UI no longer need to special-case
+  zero-item carts.
+
 ## [0.2.0]
 
 Structural rewrite on top of the 0.1.0 shape. The public API is now a

package/README.md

@@ -14,9 +14,9 @@ Peer deps (exactly what `package.json` declares):
 
 | Peer | Range |
 |---|---|
-| `@classytic/mongokit` | `>=3.11.0` |
-| `@classytic/primitives` | `>=0.1.0` |
-| `@classytic/repo-core` | `>=0.2.0` |
+| `@classytic/mongokit` | `>=3.16.0` |
+| `@classytic/primitives` | `>=0.5.0` |
+| `@classytic/repo-core` | `>=0.6.0` |
 | `mongoose` | `>=9.4.1` |
 | `zod` | `>=4.0.0` |
 
@@ -28,6 +28,7 @@ Node `>=22`. ESM only.
 |---|---|
 | `@classytic/promo` | Engine factory (`createPromoEngine`), `resolveConfig`, every repository class (`ProgramRepository`, `RuleRepository`, `RewardRepository`, `VoucherRepository`), domain entity types (`Program`, `Rule`, `Reward`, `Voucher`, `VoucherRedemption`, `BalanceLedgerEntry`), the `PromoEvents` constant + typed event catalog (`ProgramCreated`, `VoucherRedeemed`, `GiftCardSpent`, `EvaluationCompleted`, …), config types (`PromoConfig`, `ResolvedConfig`, `ResolvedTenant`), input DTOs, and result shapes (`EvaluationResult`, `CommitResult`, `GiftCardBalance`, `PaginatedResult`) |
 | `@classytic/promo/schemas` | Zod v4 validators: `programCreateSchema`, `programUpdateSchema`, `programActionSchema`, `ruleCreateSchema`, `rewardCreateSchema`, `voucherGenerateBatchSchema`, `voucherGenerateSingleSchema`, `voucherRedeemSchema`, `giftCardSpendSchema`, `giftCardTopUpSchema`, `evaluateSchema`, `commitEvaluationSchema`, the list-filter schemas, plus enum constants (`PROGRAM_TYPES`, `TRIGGER_MODES`, `STACKING_MODES`, `REWARD_TYPES`, `DISCOUNT_MODES`, `DISCOUNT_SCOPES`, `VOUCHER_STATUSES`) |
+| `@classytic/promo/events` | The Zod-source event catalog on its own: `promoEventDefinitions` (all 20 `promo.*` events), per-event definitions (`VoucherRedeemed`, `GiftCardSpent`, …), payload types, and the `PromoEventDefinition` shape — register straight into Arc's `EventRegistry` without pulling the engine factory |
 
 The `/schemas` entry depends only on zod — importing it does not pull mongoose, mongokit, or the engine factory into the bundle. Ideal for frontend form validation and SDK codegen.
 
@@ -42,14 +43,23 @@ import { createPromoEngine } from '@classytic/promo';
 await mongoose.connect(process.env.MONGO_URI!);
 
 // 1. Boot the engine against an existing mongoose connection.
+//    The factory asserts the backend supports transactions at boot
+//    (commit/redeem/spend/topUp are transactional) — pass
+//    `allowNonTransactional: true` on a standalone Mongo (dev/CI) to
+//    accept best-effort atomicity instead.
 const engine = createPromoEngine({
   mongoose: mongoose.connection,
   // tenant: false                       // disable scoping entirely
   // tenant: { tenantField: 'branchId' } // custom tenant field
+  // collectionPrefix: 'commerce_',      // namespace physical collections
+  // forceRecreate: true,                // hot-reload/test fixtures ONLY —
+  //                                     // re-registering promo's models on a
+  //                                     // connection otherwise throws
+  //                                     // PromoModelCollisionError
 });
 await engine.syncIndexes();
 
-const ctx = { organizationId: '64b0c0c0c0c0c0c0c0c0c0c0', actorId: 'admin' };
+const ctx = { organizationId: '64b0c0c0c0c0c0c0c0c0c0c0', actorRef: 'admin' };
 
 // 2. Create a program + rule + reward.
 const program = await engine.repositories.program.create(
@@ -158,6 +168,28 @@ if (result.appliedDiscounts.length > 0) {
 
 `preview(input, ctx)` runs the same algorithm with `isPreview: true` and skips the stash — safe for read-only quoting.
 
+### Atomic checkout-chain participation (`ctx.session`)
+
+Every service method honors a host-supplied Mongoose `ClientSession` on `ctx.session`. When present, `evaluation.evaluate` / `commit` / `rollback` and `voucher.redeem` / `spend` / `topUp` **join the host's transaction** instead of opening their own — all promo writes (program usage, voucher redemptions, gift-card ledger entries, evaluation-snapshot take) commit or abort atomically with the rest of the checkout chain (cart → order → flow reservation → promo commit → invoice). MongoDB has no nested transactions, so the host owns commit/abort/retry; promo never starts a second transaction on a joined session.
+
+```ts
+await withTransaction(mongoose.connection, async (session) => {
+  const order = await orderEngine.services.order.place(input, { ...ctx, session });
+  await promoEngine.services.evaluation.commit(
+    evaluationId,
+    String(order._id),
+    { ...ctx, session },              // ← promo joins the order's transaction
+    { cartHash },
+  );
+});
+// If order placement (or any later step) throws, voucher usage and
+// program counters roll back — no usage rows for a nonexistent order.
+```
+
+Without `ctx.session`, each method owns its own transaction via mongokit's `withTransaction` (auto-retry on transient errors) — the standalone behaviour is unchanged. Reads that feed writes (`getByCode`, `findActive`, idempotency checks, the snapshot `take`) also run on the session, so evaluate→commit inside one transaction is read-your-writes consistent.
+
+Event publish timing differs between the two modes — see [Publish timing](#publish-timing-ghost-event-prevention): promo-owned transactions flush in-process publishes after commit; on a joined host session, attach a `PENDING_PROMO_EVENTS` queue if your subscribers must never see uncommitted state.
+
 ---
 
 ## Repository pattern
@@ -203,7 +235,35 @@ engine.events.subscribe?.(PromoEvents.VOUCHER_REDEEMED, async (evt) => {
 });
 ```
 
-Representative event names: `promo.program.created` / `.activated` / `.paused` / `.archived`, `promo.rule.added` / `.updated` / `.removed`, `promo.reward.added` / `.updated` / `.removed`, `promo.voucher.generated` / `.redeemed` / `.cancelled` / `.expired`, `promo.gift_card.spent` / `.topped_up` / `.exhausted`, `promo.evaluation.completed` / `.committed` / `.rolled_back`. The full canonical list is exported as `PromoEvents` from the package root.
+Representative event names: `promo.program.created` / `.activated` / `.paused` / `.archived`, `promo.rule.added` / `.updated` / `.removed`, `promo.reward.added` / `.updated` / `.removed`, `promo.voucher.generated` / `.redeemed` / `.cancelled` / `.expired`, `promo.gift_card.spent` / `.topped_up` / `.exhausted`, `promo.evaluation.completed` / `.committed` / `.rolled_back`. The full canonical list is exported as `PromoEvents` from the package root; the Zod catalog (`promoEventDefinitions`) is also available standalone from `@classytic/promo/events`.
+
+### Publish timing (ghost-event prevention)
+
+`outbox.save` always runs **inside** the transaction (session-bound — a rollback discards the row; a save failure rolls the transaction back, per P8). The in-process `transport.publish` timing depends on who owns the transaction:
+
+- **Promo owns it** (no `ctx.session`): publishes are queued and flushed **after commit**. Subscribers never see events for state that rolled back, and a handler that re-reads the DB observes the committed write.
+- **Host owns it AND attached a queue**: pass `{ ...ctx, session, [PENDING_PROMO_EVENTS]: queue }` (a `DomainEvent[]`), then call `flushPendingPromoEvents({ events: transport }, queue)` after **your** commit — same guarantee, host-controlled.
+- **Host owns it, no queue** (the plain `ctx.session` contract): promo cannot know when your transaction commits, so the publish happens in-scope immediately after the write. This is a documented best effort — if you abort, in-process subscribers may have seen an event for state that never committed (the durable outbox row still rolls back correctly). Attach a queue if your subscribers need strict semantics.
+
+---
+
+## Errors
+
+Every domain error implements `HttpError` from `@classytic/repo-core/errors` — a stable hierarchical lowercase `code` (`promo.<entity>.<problem>`) plus an HTTP `status`. Arc serializes them via `toErrorContract()` with zero host-side mapping; hosts catch by `instanceof` or switch on `error.code`.
+
+| Error | `code` | `status` |
+|---|---|---|
+| `ValidationError` | `promo.validation.invalid_input` | 400 |
+| `TenantIsolationError` | `promo.tenant.missing_context` | 400 |
+| `ProgramNotFoundError` / `RuleNotFoundError` / `RewardNotFoundError` / `VoucherNotFoundError` / `EvaluationNotFoundError` | `promo.<entity>.not_found` | 404 |
+| `InvalidTransitionError` | `promo.program.invalid_transition` | 409 |
+| `ProgramUsageCapExceededError` | `promo.program.usage_cap_exceeded` | 409 |
+| `VoucherExpiredError` / `VoucherExhaustedError` | `promo.voucher.expired` / `.exhausted` | 409 |
+| `DuplicateRedemptionError` / `DuplicateVoucherCodeError` | `promo.voucher.duplicate_redemption` / `.duplicate_code` | 409 |
+| `GiftCardExhaustedError` / `InsufficientBalanceError` | `promo.gift_card.exhausted` / `.insufficient_balance` | 409 |
+| `ConcurrencyConflictError` | `promo.concurrency.write_conflict` | 409 |
+| `CartHashMismatchError` | `promo.evaluation.cart_hash_mismatch` | 409 |
+| `PromoModelCollisionError` | `promo.engine.model_collision` | 500 |
 
 ---
 
@@ -225,12 +285,12 @@ npm run test:unit
 npm run test:integration
 ```
 
-Current suite: approximately 325 tests across 33 files, split into two vitest projects:
+Current suite: 380 tests across 38 files, split into two vitest projects:
 
 | Project | Directories | Files |
 |---|---|---|
-| `unit` | `tests/unit/` | 6 — code generator, config resolution, constants, domain errors, event bus, event catalog |
-| `integration` | `tests/integration/`, `tests/services/`, `tests/domain/`, `tests/security/` | 27 — full workflows, commerce + vertical scenarios, gift-card concurrent-spend + lifecycle, voucher bulk generation, outbox dispatch, evaluation + voucher service edge cases, concurrency, tiered discounts, customer segmentation, cart-hash tamper guards, input validation |
+| `unit` | `tests/unit/` | 7 — code generator, config resolution, constants, domain errors (HttpError contract matrix), event bus, event catalog (no-drift invariant), pending-events dispatch + boot gate |
+| `integration` | `tests/integration/`, `tests/services/`, `tests/domain/`, `tests/security/` | 31 — full workflows, commerce + vertical scenarios, checkout-chain session threading, post-commit publish (ghost-event regression), engine compliance (model collision, collection names, duplicate code, abort signal), gift-card concurrent-spend + lifecycle, voucher bulk generation, outbox dispatch, evaluation + voucher service edge cases, concurrency, tiered discounts, customer segmentation, cart-hash tamper guards, input validation |
 
 Integration tests spin up `mongodb-memory-server` one connection per worker (`fileParallelism: false`, single-worker pool); unit tests require no Mongo.
 

package/dist/{constants-BB5O8zlN.mjs → constants-BE886vJk.mjs}

@@ -1,20 +1,29 @@
 import { defineStateMachine } from "@classytic/primitives/state-machine";
 //#region src/domain/errors/base.ts
 var PromoError = class extends Error {
-	constructor(message) {
+	constructor(message, code, status) {
 		super(message);
+		this.code = code;
+		this.status = status;
 		this.name = this.constructor.name;
 	}
 };
 //#endregion
 //#region src/domain/errors/domain-errors.ts
+/**
+* Promo domain errors — each implements `HttpError` (via {@link PromoError})
+* with a hierarchical lowercase code (`promo.<entity>.<problem>`) and an
+* HTTP status, so arc's `toErrorContract()` serializes them without any
+* host-side mapping. Hosts catch by `instanceof` OR switch on `error.code`.
+*/
 var ValidationError = class extends PromoError {
-	code = "VALIDATION_ERROR";
+	constructor(message) {
+		super(message, "promo.validation.invalid_input", 400);
+	}
 };
 var ProgramNotFoundError = class extends PromoError {
-	code = "PROGRAM_NOT_FOUND";
 	constructor(id) {
-		super(id ? `Program '${id}' not found` : "Program not found");
+		super(id ? `Program '${id}' not found` : "Program not found", "promo.program.not_found", 404);
 	}
 };
 /**
@@ -25,47 +34,40 @@ var ProgramNotFoundError = class extends PromoError {
 * 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}`);
+		super(`Program '${programId}' has reached its usage cap of ${maxUsageTotal}`, "promo.program.usage_cap_exceeded", 409);
 		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");
+		super(id ? `Rule '${id}' not found` : "Rule not found", "promo.rule.not_found", 404);
 	}
 };
 var RewardNotFoundError = class extends PromoError {
-	code = "REWARD_NOT_FOUND";
 	constructor(id) {
-		super(id ? `Reward '${id}' not found` : "Reward not found");
+		super(id ? `Reward '${id}' not found` : "Reward not found", "promo.reward.not_found", 404);
 	}
 };
 var VoucherNotFoundError = class extends PromoError {
-	code = "VOUCHER_NOT_FOUND";
 	constructor(codeOrId) {
-		super(codeOrId ? `Voucher '${codeOrId}' not found` : "Voucher not found");
+		super(codeOrId ? `Voucher '${codeOrId}' not found` : "Voucher not found", "promo.voucher.not_found", 404);
 	}
 };
 var InvalidTransitionError = class extends PromoError {
-	code = "INVALID_TRANSITION";
 	constructor(from, to) {
-		super(`Cannot transition from '${from}' to '${to}'`);
+		super(`Cannot transition from '${from}' to '${to}'`, "promo.program.invalid_transition", 409);
 	}
 };
 var VoucherExpiredError = class extends PromoError {
-	code = "VOUCHER_EXPIRED";
 	constructor(code) {
-		super(`Voucher '${code}' has expired`);
+		super(`Voucher '${code}' has expired`, "promo.voucher.expired", 409);
 	}
 };
 var VoucherExhaustedError = class extends PromoError {
-	code = "VOUCHER_EXHAUSTED";
 	constructor(code) {
-		super(`Voucher '${code}' has reached its usage limit`);
+		super(`Voucher '${code}' has reached its usage limit`, "promo.voucher.exhausted", 409);
 	}
 };
 /**
@@ -75,9 +77,8 @@ var VoucherExhaustedError = class extends PromoError {
 * later" messaging.
 */
 var GiftCardExhaustedError = class extends PromoError {
-	code = "GIFT_CARD_EXHAUSTED";
 	constructor(code) {
-		super(`Gift card '${code}' has been fully spent`);
+		super(`Gift card '${code}' has been fully spent`, "promo.gift_card.exhausted", 409);
 	}
 };
 /**
@@ -87,37 +88,43 @@ var GiftCardExhaustedError = class extends PromoError {
 * this to HTTP 409 + retry.
 */
 var ConcurrencyConflictError = class extends PromoError {
-	code = "CONCURRENCY_CONFLICT";
-	status = 409;
 	constructor(resource, resourceId, cause) {
-		super(`Concurrent modification on ${resource} '${resourceId}'`);
+		super(`Concurrent modification on ${resource} '${resourceId}'`, "promo.concurrency.write_conflict", 409);
 		this.resource = resource;
 		this.resourceId = resourceId;
 		this.cause = cause;
 	}
 };
 var InsufficientBalanceError = class extends PromoError {
-	code = "INSUFFICIENT_BALANCE";
 	constructor(code, available, requested) {
-		super(`Voucher '${code}' has insufficient balance: ${available} available, ${requested} requested`);
+		super(`Voucher '${code}' has insufficient balance: ${available} available, ${requested} requested`, "promo.gift_card.insufficient_balance", 409);
 	}
 };
 var TenantIsolationError = class extends PromoError {
-	code = "TENANT_ISOLATION";
 	constructor() {
-		super("Tenant context is required but was not provided");
+		super("Tenant context is required but was not provided", "promo.tenant.missing_context", 400);
 	}
 };
 var DuplicateRedemptionError = class extends PromoError {
-	code = "DUPLICATE_REDEMPTION";
 	constructor(key) {
-		super(`Duplicate redemption detected for idempotency key '${key}'`);
+		super(`Duplicate redemption detected for idempotency key '${key}'`, "promo.voucher.duplicate_redemption", 409);
+	}
+};
+/**
+* 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.
+*/
+var DuplicateVoucherCodeError = class extends PromoError {
+	constructor(code) {
+		super(code ? `Voucher code '${code}' already exists` : "Voucher code already exists", "promo.voucher.duplicate_code", 409);
 	}
 };
 var EvaluationNotFoundError = class extends PromoError {
-	code = "EVALUATION_NOT_FOUND";
 	constructor(id) {
-		super(`Evaluation '${id}' not found or already committed`);
+		super(`Evaluation '${id}' not found or already committed`, "promo.evaluation.not_found", 404);
 	}
 };
 /**
@@ -128,9 +135,20 @@ var EvaluationNotFoundError = class extends PromoError {
 * tries to apply the stale discount to the altered order.
 */
 var CartHashMismatchError = class extends PromoError {
-	code = "CART_HASH_MISMATCH";
 	constructor(evaluationId) {
-		super(`Evaluation '${evaluationId}' cart hash mismatch — the cart changed between evaluate and commit. Re-evaluate with the current cart.`);
+		super(`Evaluation '${evaluationId}' cart hash mismatch — the cart changed between evaluate and commit. Re-evaluate with the current cart.`, "promo.evaluation.cart_hash_mismatch", 409);
+	}
+};
+/**
+* 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.
+*/
+var PromoModelCollisionError = class extends PromoError {
+	constructor(modelName) {
+		super(`Mongoose model '${modelName}' is already registered on this connection. Pass \`forceRecreate: true\` to createPromoEngine for hot-reload/test fixtures, or use a separate connection (mongoose.createConnection()) to run two promo engines.`, "promo.engine.model_collision", 500);
 	}
 };
 //#endregion
@@ -189,4 +207,4 @@ const PROGRAM_MACHINE = defineStateMachine({
 	errorFactory: ({ from, to }) => new InvalidTransitionError(from, to)
 });
 //#endregion
-export { VoucherExhaustedError as C, PromoError as E, ValidationError as S, VoucherNotFoundError as T, ProgramNotFoundError as _, PROGRAM_TYPES as a, RuleNotFoundError as b, TRIGGER_MODES as c, ConcurrencyConflictError as d, DuplicateRedemptionError as f, InvalidTransitionError as g, InsufficientBalanceError as h, PROGRAM_STATUSES as i, VOUCHER_STATUSES as l, GiftCardExhaustedError as m, DISCOUNT_SCOPES as n, REWARD_TYPES as o, EvaluationNotFoundError as p, PROGRAM_MACHINE as r, STACKING_MODES as s, DISCOUNT_MODES as t, CartHashMismatchError as u, ProgramUsageCapExceededError as v, VoucherExpiredError as w, TenantIsolationError as x, RewardNotFoundError as y };
+export { TenantIsolationError as C, VoucherNotFoundError as D, VoucherExpiredError as E, PromoError as O, RuleNotFoundError as S, VoucherExhaustedError as T, InvalidTransitionError as _, PROGRAM_TYPES as a, PromoModelCollisionError as b, TRIGGER_MODES as c, ConcurrencyConflictError as d, DuplicateRedemptionError as f, InsufficientBalanceError as g, GiftCardExhaustedError as h, PROGRAM_STATUSES as i, VOUCHER_STATUSES as l, EvaluationNotFoundError as m, DISCOUNT_SCOPES as n, REWARD_TYPES as o, DuplicateVoucherCodeError as p, PROGRAM_MACHINE as r, STACKING_MODES as s, DISCOUNT_MODES as t, CartHashMismatchError as u, ProgramNotFoundError as v, ValidationError as w, RewardNotFoundError as x, ProgramUsageCapExceededError as y };