@classytic/loyalty 0.2.2 → 0.3.0

package/CHANGELOG.md

@@ -3,6 +3,107 @@
 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.3.0] — 2026-06-13
+
+Stack upgrade to mongokit 3.16 / repo-core 0.6 / primitives 0.7.2 plus
+verified correctness + PACKAGE_RULES compliance fixes. No new features.
+
+### Fixed
+
+- **Stack actually resolves the new floor now (CRITICAL).** The committed
+  lockfile silently served `@classytic/mongokit@3.13.0` +
+  `@classytic/repo-core@0.4.0` despite the `^3.13.3` / `^0.4.2` pins, so the
+  whole test suite ran against the OLD stack. Clean reinstall + peer/dev bumps
+  pin the resolved tree to mongokit **3.16.0**, repo-core **0.6.0**, primitives
+  **0.7.2** (verified with `npm ls`).
+- **§P8 outbox is now session-bound on the transactional verbs.** `earnPoints`,
+  `adjustPoints`, `reserve`, `confirm`, `release`, and `reverseConfirmed`
+  previously dispatched the event AFTER `withTransaction` committed, so
+  `outbox.save` ran OUTSIDE the unit of work — the business doc could commit
+  while the durable event row was lost (or vice-versa). Dispatch now runs
+  INSIDE the transaction (outbox row commits atomically with the write) and the
+  transport publish is deferred to a post-commit flush (`runLoyaltyUnit` +
+  `[PENDING_EVENTS]`), so in-process subscribers never see a state that may roll
+  back. A new integration test asserts the save is session-bound and that a
+  failing `outbox.save` rolls the `$inc` balance write back.
+- **Redemption slot no longer permanently blocked after release.** The
+  `{ ownerType, ownerId }` unique index spanned ALL statuses, so a released /
+  reversed reservation E11000-blocked any retry on the same order (payment
+  retry, cart re-attempt) forever. It is now a **partial** unique index scoped
+  to active statuses (`reserved`, `confirmed`) — terminal states free the slot
+  (PACKAGE_RULES rule 32/38/39). Re-reserve-after-release and second-active-
+  reserve-blocked tests added.
+
+### Added
+
+- **`UnmanagedSessionError` guard (§P8).** When a host passes `ctx.session`
+  (it owns the outer transaction) without attaching a `[PENDING_EVENTS]` queue,
+  dispatch throws BEFORE any side effect instead of publishing / saving outside
+  the host's unit of work (which would leak ghost events on rollback).
+  `PENDING_EVENTS` and `flushPendingLoyaltyEvents` are exported for hosts that
+  manage their own transaction.
+- **Capability boot gate.** `createLoyaltyEngine()` asserts the backend declares
+  the `transactions` capability (repo-core 0.6 / mongokit 3.16+) at engine
+  creation — fail loud at boot rather than with a cryptic driver error on the
+  first transactional call. `allowNonTransactional: true` opts out for local-dev
+  on standalone Mongo. New `LoyaltyCapabilityError`.
+- **Cooperative cancellation in cron loops.** `processExpirations`, `awardBatch`,
+  `cleanupExpired` (redemption + referral), `evaluateAll`, and
+  `sweepExpiredOverrides` check `ctx.signal` via `throwIfAborted` between items —
+  abortable batches; each per-item write is its own committed unit of work, so
+  aborting never rolls back already-processed rows. `LoyaltyContext` gained
+  `signal?: AbortSignal`.
+
+### Changed
+
+- **Domain errors implement `HttpError`** from `@classytic/repo-core/errors`
+  (was a bespoke `httpStatus` shape). Clean break: `httpStatus` → `status`,
+  and codes are now hierarchical + lowercase (`loyalty.<entity>.<problem>`,
+  e.g. `loyalty.member.not_found`, `loyalty.points.insufficient`) so arc
+  serializes them to `ErrorContract` correctly. No deprecation alias.
+- **Peer-dep ranges raised** — `@classytic/mongokit >=3.16.0`,
+  `@classytic/repo-core >=0.6.0` (`>=` style). devDeps bumped to match and
+  primitives devDep pinned to `^0.7.2`.
+- **`exactOptionalPropertyTypes: true`** enabled in tsconfig (mandatory per
+  PACKAGE_RULES Build Hygiene / P10); fixed the three pre-existing optional-vs-
+  undefined violations it surfaced.
+- **tsconfig no longer emits sourcemaps or declaration maps**
+  (`sourceMap: false`, `declarationMap: false`) — both leaked source. tsdown
+  was already correct; tsconfig now matches.
+
+## [0.2.3] — 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 swallowed them silently. 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 the failure meant a parent doc could commit while the event
+  vanished, with no relay row to recover from. Fix re-throws after logging.
+  `events.publish` failures continue to be swallowed (correctly, per §P8 —
+  the host's outbox relay re-publishes from the durable row), but now log
+  before swallowing so failures are observable.
+- **`DispatchDeps.logger` field added.** Optional. Both arms of the
+  dispatch helper log through it when set, surfacing failures in the host's
+  observability stack without coupling the package to a specific logger.
+
+### 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 redemption + tier-eval paths)
+  retry correctly under contention; 0.4.2 adds the typed `FindAllOptions`
+  shape with `limit?` for callers that need a bounded non-paginated read.
+
+### Internal
+
+- Replaced 4 `arr.find()!` non-null assertions in [src/index.ts](src/index.ts)
+  + scenario tests with explicit narrowing — TS now proves what the runtime
+  shape already guaranteed.
+
 ## [0.2.0]
 
 Structural rewrite on top of the 0.1.0 shape. The public API is now a

package/README.md

@@ -9,7 +9,8 @@ Framework-agnostic. Works with Fastify (Arc), Express, NestJS, Next.js, or any N
 ```bash
 npm install @classytic/loyalty
 # Peer deps:
-npm install mongoose@^9 @classytic/mongokit@^3.4
+npm install mongoose@^9 zod@^4 \
+  @classytic/mongokit@^3.16 @classytic/repo-core@^0.6 @classytic/primitives@^0.7
 ```
 
 ## Quick Start
@@ -26,15 +27,15 @@ const engine = createLoyaltyEngine({
   referral: { referrerRewardPoints: 200, refereeRewardPoints: 100 },
 });
 
-// 6 services ready to use
-const member = await engine.services.member.enroll(
+// Domain verbs live on the repositories (no service layer — PACKAGE_RULES §1–§3)
+const member = await engine.repositories.member.enroll(
   { externalId: 'cust_1', externalType: 'customer', cardId: 'MBR-001' },
-  { actorId: 'admin' },
+  { actorId: 'admin', organizationId: 'org_1' },
 );
 
-await engine.services.ledger.earnPoints(
+await engine.repositories.pointTransaction.earnPoints(
   { memberId: member._id, points: 500, description: 'Order #123' },
-  { actorId: 'system' },
+  { actorId: 'system', organizationId: 'org_1' },
 );
 ```
 
@@ -42,21 +43,29 @@ await engine.services.ledger.earnPoints(
 
 ```
 createLoyaltyEngine(config)
-  -> models         6 Mongoose models (auto-created, OverwriteModel-safe)
-  -> repositories   6 repos (tenant-scoped CRUD, pagination, atomic transitions)
-  -> services       6 services (the public API)
-  -> events         In-process event bus (or plug your own)
+  -> models         6 Mongoose models (auto-created, collision-safe)
+  -> repositories   6 repos = the public API (tenant-scoped CRUD + domain verbs)
+  -> events         Arc-compatible transport (in-process fallback, or plug your own)
+  -> syncIndexes()  deploy-time index builder
 ```
 
-### Services
+The capability boot gate asserts the backend supports multi-document
+`transactions` (MongoDB replica set / sharded cluster) — the point-mutation
+verbs are transactional. For local-dev on standalone Mongo, pass
+`allowNonTransactional: true` (accepts partial-write risk).
 
-| Service | Purpose |
-|---------|---------|
-| `member` | Enroll, deactivate, reactivate, suspend, getByCardId, getByExternalId |
-| `ledger` | Earn points, adjust points, transaction history, process expirations |
-| `earning` | CRUD earning rules (order, action, category, tier_bonus types) |
-| `tier` | CRUD tier definitions, evaluate members, set/clear overrides |
-| `redemption` | Validate, reserve, confirm, release, cleanup expired reservations |
+### Repositories (the public API)
+
+Domain verbs live on the repositories themselves — there is no service layer
+(PACKAGE_RULES §1–§3). Access via `engine.repositories.<name>`.
+
+| Repository | Purpose |
+|------------|---------|
+| `member` | Enroll, deactivate, reactivate, suspend |
+| `pointTransaction` | Earn points, adjust points, `awardBatch`, process expirations |
+| `earningRule` | CRUD earning rules (order, action, category, tier_bonus); `evaluateOrder` / `evaluateAction` |
+| `tierDefinition` | CRUD tier definitions, evaluate members, set/clear/sweep overrides |
+| `redemption` | Validate, reserve, confirm, release, reverse, cleanup expired reservations |
 | `referral` | Generate codes, record referrals, approve/reject, rate limiting |
 
 ### Key Design Decisions
@@ -148,42 +157,67 @@ as `PlatformConfig.membership.pointsPerAmount` or `amountPerPoint`. See
 
 ## Events
 
+`engine.events` is an arc-compatible `EventTransport` — subscribe glob-style.
+Drop in any arc transport (Memory/Redis/Kafka) via `eventTransport` in config.
+
 ```typescript
 import { LoyaltyEvents } from '@classytic/loyalty/events';
 
-engine.events.on(LoyaltyEvents.POINTS_EARNED, (payload) => { /* sync projection */ });
-engine.events.on(LoyaltyEvents.TIER_UPGRADED, (payload) => { /* notify customer */ });
-engine.events.on(LoyaltyEvents.REFERRAL_REWARDED, (payload) => { /* notify both */ });
+await engine.events.subscribe(LoyaltyEvents.POINTS_EARNED, (e) => { /* sync projection */ });
+await engine.events.subscribe('loyalty.tier.*', (e) => { /* notify customer */ });
+await engine.events.subscribe(LoyaltyEvents.REFERRAL_REWARDED, (e) => { /* notify both */ });
 ```
 
+For durable delivery, wire a host-owned `outbox` (PACKAGE_RULES §5.5 + §P8):
+the engine saves the event row inside the same transaction as the business
+write (atomic), then publishes after commit. Hosts that own the outer
+transaction must attach a `[PENDING_EVENTS]` queue and call
+`flushPendingLoyaltyEvents(transport, queue)` after their commit, or a bare
+`ctx.session` throws `UnmanagedSessionError`.
+
 ## Production Cron Jobs
 
+All cron loops accept `ctx.signal` (an `AbortSignal`) and check it between
+items, so a shutdown / timeout aborts cleanly between committed units of work.
+
 ```typescript
+const ctx = { actorId: 'cron', organizationId: 'org_1', signal: ac.signal };
+
 // Every 5 min — release expired point reservations
-await engine.services.redemption.cleanupExpired({ actorId: 'cron' });
+await engine.repositories.redemption.cleanupExpired(ctx);
 
 // Every hour — expire points past their expiresAt
-await engine.services.ledger.processExpirations({ actorId: 'cron' });
+await engine.repositories.pointTransaction.processExpirations(ctx);
 
 // Every 24h — re-evaluate all member tiers
-await engine.services.tier.evaluateAll({ actorId: 'cron' });
+await engine.repositories.tierDefinition.evaluateAll(ctx);
+
+// Hourly — clear expired tier overrides
+await engine.repositories.tierDefinition.sweepExpiredOverrides(ctx);
 ```
 
 ## Error Codes
 
+All domain errors implement `HttpError` from `@classytic/repo-core/errors`
+(arc serializes them to the canonical `ErrorContract`). Codes are hierarchical
+and lowercase.
+
 | Code | HTTP | When |
 |------|------|------|
-| `MEMBER_NOT_FOUND` | 404 | Member doesn't exist |
-| `MEMBER_ALREADY_ENROLLED` | 409 | Duplicate enrollment |
-| `MEMBER_INACTIVE` | 422 | Operating on inactive member |
-| `INSUFFICIENT_POINTS` | 400 | Not enough points to deduct |
-| `RULE_NOT_FOUND` | 404 | Earning rule doesn't exist |
-| `TIER_NOT_FOUND` | 404 | Tier definition doesn't exist |
-| `REDEMPTION_EXPIRED` | 410 | Reservation TTL exceeded |
-| `DUPLICATE_REFERRAL` | 409 | Referee already referred |
-| `SELF_REFERRAL` | 422 | Referring yourself |
-| `REFERRAL_LIMIT_EXCEEDED` | 429 | Max referrals per period |
-| `TENANT_ISOLATION` | 403 | Cross-tenant access attempt |
+| `loyalty.member.not_found` | 404 | Member doesn't exist |
+| `loyalty.member.already_enrolled` | 409 | Duplicate enrollment |
+| `loyalty.member.inactive` | 422 | Operating on inactive member |
+| `loyalty.points.insufficient` | 400 | Not enough points to deduct |
+| `loyalty.earning_rule.not_found` | 404 | Earning rule doesn't exist |
+| `loyalty.tier.not_found` | 404 | Tier definition doesn't exist |
+| `loyalty.redemption.expired` | 410 | Reservation TTL exceeded |
+| `loyalty.referral.duplicate` | 409 | Referee already referred |
+| `loyalty.referral.self` | 422 | Referring yourself |
+| `loyalty.referral.circular` | 422 | A↔B circular referral |
+| `loyalty.referral.limit_exceeded` | 429 | Max referrals per period |
+| `loyalty.tenant.isolation` | 403 | Missing tenant context |
+| `loyalty.transaction.unmanaged_session` | 400 | `ctx.session` passed without a `[PENDING_EVENTS]` queue |
+| `loyalty.engine.missing_capabilities` | 500 | Backend lacks `transactions` at boot |
 
 ## AI Agent Skill
 

package/dist/{config-96Sl6oNJ.d.mts → config-BdSyAdnF.d.mts}

@@ -99,6 +99,16 @@ interface LoyaltyConfig {
   outbox?: OutboxStore | undefined;
   notifications?: NotificationAdapter | undefined;
   plugins?: RepositoryPlugins | undefined;
+  /**
+   * Skip the boot-time capability gate that asserts the backend supports
+   * multi-document `transactions`. Loyalty's point-mutation verbs (earn,
+   * adjust, reserve, confirm, release, reverse, processExpirations) run inside
+   * `withTransaction`; without a replica set those writes are NOT atomic.
+   * Leave `false` (default) in production — set `true` only for local-dev on
+   * standalone Mongo, accepting partial-write risk. See PACKAGE_RULES
+   * "Runtime capabilities".
+   */
+  allowNonTransactional?: boolean | undefined;
 }
 interface ResolvedTenant {
   enabled: boolean;

package/dist/events/index.d.mts

@@ -1,2 +1,2 @@
-import { A as PointsExpired, B as ReferralRewarded, C as MemberDeactivated, D as MultiTierReferralAwarded, E as MemberSuspended, F as RedemptionReserved, G as TierUpgraded, H as TierGraceStarted, I as RedemptionReversed, J as InProcessLoyaltyBusOptions, K as loyaltyEventDefinitions, L as ReferralApproved, M as PointsRedeemed, N as RedemptionConfirmed, O as PointsAdjusted, P as RedemptionReleased, R as ReferralRecorded, S as LoyaltyEventSchema, T as MemberReactivated, U as TierOverrideCleared, V as TierDowngraded, W as TierOverrideExpired, Y as createEvent, _ as TierChangedPayload, a as LoyaltyEventMap, b as LoyaltyEventDefinition, c as LoyaltyEvents, d as PointsAdjustedPayload, f as PointsEarnedPayload, g as ReferralPayload, h as RedemptionReversedPayload, i as CampaignAwardedPayload, j as PointsExpiringSoon, k as PointsEarned, l as MemberLifecyclePayload, m as RedemptionPayload, n as EventHandler, o as LoyaltyEventName, p as PointsExpiredPayload, q as InProcessLoyaltyBus, r as EventTransport, s as LoyaltyEventPayload, t as DomainEvent, u as MultiTierReferralAwardedPayload, v as TierOverrideLifecyclePayload, w as MemberEnrolled, x as LoyaltyEventPayloadOf, y as CampaignAwarded, z as ReferralRejected } from "../index-xLLJ7jLy.mjs";
+import { A as PointsExpired, B as ReferralRewarded, C as MemberDeactivated, D as MultiTierReferralAwarded, E as MemberSuspended, F as RedemptionReserved, G as TierUpgraded, H as TierGraceStarted, I as RedemptionReversed, J as InProcessLoyaltyBusOptions, K as loyaltyEventDefinitions, L as ReferralApproved, M as PointsRedeemed, N as RedemptionConfirmed, O as PointsAdjusted, P as RedemptionReleased, R as ReferralRecorded, S as LoyaltyEventSchema, T as MemberReactivated, U as TierOverrideCleared, V as TierDowngraded, W as TierOverrideExpired, Y as createEvent, _ as TierChangedPayload, a as LoyaltyEventMap, b as LoyaltyEventDefinition, c as LoyaltyEvents, d as PointsAdjustedPayload, f as PointsEarnedPayload, g as ReferralPayload, h as RedemptionReversedPayload, i as CampaignAwardedPayload, j as PointsExpiringSoon, k as PointsEarned, l as MemberLifecyclePayload, m as RedemptionPayload, n as EventHandler, o as LoyaltyEventName, p as PointsExpiredPayload, q as InProcessLoyaltyBus, r as EventTransport, s as LoyaltyEventPayload, t as DomainEvent, u as MultiTierReferralAwardedPayload, v as TierOverrideLifecyclePayload, w as MemberEnrolled, x as LoyaltyEventPayloadOf, y as CampaignAwarded, z as ReferralRejected } from "../index-CnESLipu.mjs";
 export { CampaignAwarded, CampaignAwardedPayload, DomainEvent, EventHandler, EventTransport, InProcessLoyaltyBus, InProcessLoyaltyBusOptions, LoyaltyEventDefinition, LoyaltyEventMap, LoyaltyEventName, LoyaltyEventPayload, LoyaltyEventPayloadOf, LoyaltyEventSchema, LoyaltyEvents, MemberDeactivated, MemberEnrolled, MemberLifecyclePayload, MemberReactivated, MemberSuspended, MultiTierReferralAwarded, MultiTierReferralAwardedPayload, PointsAdjusted, PointsAdjustedPayload, PointsEarned, PointsEarnedPayload, PointsExpired, PointsExpiredPayload, PointsExpiringSoon, PointsRedeemed, RedemptionConfirmed, RedemptionPayload, RedemptionReleased, RedemptionReserved, RedemptionReversed, RedemptionReversedPayload, ReferralApproved, ReferralPayload, ReferralRecorded, ReferralRejected, ReferralRewarded, TierChangedPayload, TierDowngraded, TierGraceStarted, TierOverrideCleared, TierOverrideExpired, TierOverrideLifecyclePayload, TierUpgraded, createEvent, loyaltyEventDefinitions };

package/dist/events/index.mjs

@@ -1,3 +1,3 @@
-import { C as TierOverrideExpired, E as InProcessLoyaltyBus, S as TierOverrideCleared, T as loyaltyEventDefinitions, _ as ReferralRecorded, a as MemberSuspended, b as TierDowngraded, c as PointsEarned, d as PointsRedeemed, f as RedemptionConfirmed, g as ReferralApproved, h as RedemptionReversed, i as MemberReactivated, l as PointsExpired, m as RedemptionReserved, n as MemberDeactivated, o as MultiTierReferralAwarded, p as RedemptionReleased, r as MemberEnrolled, s as PointsAdjusted, t as CampaignAwarded, u as PointsExpiringSoon, v as ReferralRejected, w as TierUpgraded, x as TierGraceStarted, y as ReferralRewarded } from "../events-BtZOdiPw.mjs";
-import { n as createEvent, t as LoyaltyEvents } from "../loyalty-events-Cyt9TwX6.mjs";
+import { C as TierOverrideExpired, E as InProcessLoyaltyBus, S as TierOverrideCleared, T as loyaltyEventDefinitions, _ as ReferralRecorded, a as MemberSuspended, b as TierDowngraded, c as PointsEarned, d as PointsRedeemed, f as RedemptionConfirmed, g as ReferralApproved, h as RedemptionReversed, i as MemberReactivated, l as PointsExpired, m as RedemptionReserved, n as MemberDeactivated, o as MultiTierReferralAwarded, p as RedemptionReleased, r as MemberEnrolled, s as PointsAdjusted, t as CampaignAwarded, u as PointsExpiringSoon, v as ReferralRejected, w as TierUpgraded, x as TierGraceStarted, y as ReferralRewarded } from "../events-DN5_p6T0.mjs";
+import { n as createEvent, t as LoyaltyEvents } from "../loyalty-events-C38JA3cU.mjs";
 export { CampaignAwarded, InProcessLoyaltyBus, LoyaltyEvents, MemberDeactivated, MemberEnrolled, MemberReactivated, MemberSuspended, MultiTierReferralAwarded, PointsAdjusted, PointsEarned, PointsExpired, PointsExpiringSoon, PointsRedeemed, RedemptionConfirmed, RedemptionReleased, RedemptionReserved, RedemptionReversed, ReferralApproved, ReferralRecorded, ReferralRejected, ReferralRewarded, TierDowngraded, TierGraceStarted, TierOverrideCleared, TierOverrideExpired, TierUpgraded, createEvent, loyaltyEventDefinitions };

package/dist/{events-BtZOdiPw.mjs → events-DN5_p6T0.mjs}

@@ -1,4 +1,4 @@
-import { t as LoyaltyEvents } from "./loyalty-events-Cyt9TwX6.mjs";
+import { t as LoyaltyEvents } from "./loyalty-events-C38JA3cU.mjs";
 import { createEvent, matchEventPattern } from "@classytic/primitives/events";
 import { z } from "zod";
 //#region src/events/in-process-bus.ts

package/dist/{index-CMSNfGos.d.mts → index-BN96EDac.d.mts}

@@ -1,12 +1,13 @@
 import { i as ReferralStatus, r as RedemptionStatus } from "./index-DMK8a98J.mjs";
-import { S as EarningRule, _ as TierEvaluationBatch, d as EarningResult, f as ExpirationResult, g as TierEvaluation, h as RedemptionValidation, o as LoyaltyContext, v as PointTransaction, x as TierDefinition, y as Member } from "./index-Bo5YQ_fu.mjs";
+import { S as EarningRule, _ as TierEvaluationBatch, d as EarningResult, f as ExpirationResult, g as TierEvaluation, h as RedemptionValidation, o as LoyaltyContext, v as PointTransaction, x as TierDefinition, y as Member } from "./index-D20Cn4KB.mjs";
 import { t as NotificationAdapter } from "./notification.port-CJ9nXj0k.mjs";
-import { c as ResolvedTenant, o as RepositoryPlugins, s as ResolvedConfig } from "./config-96Sl6oNJ.mjs";
+import { c as ResolvedTenant, o as RepositoryPlugins, s as ResolvedConfig } from "./config-BdSyAdnF.mjs";
 import { LoyaltyModels } from "./models/index.mjs";
 import { EventTransport } from "@classytic/primitives/events";
 import { ClientSession, Model } from "mongoose";
 import { PluginType, Repository } from "@classytic/mongokit";
 import { OutboxStore } from "@classytic/primitives/outbox";
+import { ApprovalChain } from "@classytic/primitives/approval";
 
 //#region src/domain/ports/unit-of-work.port.d.ts
 interface UnitOfWork {
@@ -64,6 +65,7 @@ declare class PointTransactionRepository extends Repository<PointTransaction> {
   constructor(model: Model<PointTransaction>, plugins?: PluginType[]);
   /** Session-bound outbox save + transport publish (PACKAGE_RULES §5.5 + P8). */
   private _dispatch;
+  private get _dispatchDeps();
   /**
    * Auto-inject tenant id from options into doc payload. Matches
    * `@classytic/order` / `@classytic/promo` — see MemberRepository.
@@ -192,6 +194,18 @@ interface Redemption {
    */
   initialBalance?: number;
   remainingBalance?: number;
+  /**
+   * Optional multi-step approval chain (P7 canonical — same shape as
+   * `@classytic/purchase` / `@classytic/order`). High-value redemptions
+   * (gift cards above threshold, large discount vouchers) gate on
+   * `isApproved(approvals)` before `confirm()` flips the FSM. Single-tier
+   * flows skip the chain entirely.
+   */
+  approvals?: ApprovalChain | null;
+  /** Snapshot of the matrix policy id that produced this chain (host-managed). */
+  approvalPolicyId?: string | null;
+  /** Version of the matrix policy at submit time — frozen for audit. */
+  approvalPolicyVersion?: number | null;
   createdAt: Date;
   updatedAt: Date;
 }
@@ -211,6 +225,7 @@ declare class RedemptionRepository extends Repository<Redemption> {
   createMany(docs: Parameters<Repository<Redemption>['createMany']>[0], options?: Parameters<Repository<Redemption>['createMany']>[1]): Promise<Redemption[]>;
   /** Session-bound outbox save + transport publish (PACKAGE_RULES §5.5 + P8). */
   private _dispatch;
+  private get _dispatchDeps();
   /**
    * Atomic compare-and-set status transition.
    * Returns null if the current status doesn't match `expectedStatus` (CAS mismatch).
@@ -353,8 +368,8 @@ interface LoyaltyRepositories {
 }
 interface CreateRepositoriesInput {
   models: LoyaltyModels;
-  plugins?: RepositoryPlugins;
-  tenant?: ResolvedTenant;
+  plugins?: RepositoryPlugins | undefined;
+  tenant?: ResolvedTenant | undefined;
   config: ResolvedConfig;
   events: EventTransport;
   outbox?: OutboxStore | undefined;

package/dist/{index-xLLJ7jLy.d.mts → index-CnESLipu.d.mts}

@@ -1,4 +1,4 @@
-import { o as LoyaltyContext } from "./index-Bo5YQ_fu.mjs";
+import { o as LoyaltyContext } from "./index-D20Cn4KB.mjs";
 import { DomainEvent, DomainEvent as DomainEvent$1, EventHandler, EventHandler as EventHandler$1, EventTransport, EventTransport as EventTransport$1 } from "@classytic/primitives/events";
 import { z } from "zod";
 

package/dist/{index-Bo5YQ_fu.d.mts → index-D20Cn4KB.d.mts}

@@ -1,5 +1,6 @@
 import { a as RuleStatus, n as MemberStatus, o as RuleType, s as TransactionType } from "./index-DMK8a98J.mjs";
 import { OperationContext } from "@classytic/primitives/context";
+import { ApprovalChain } from "@classytic/primitives/approval";
 
 //#region src/domain/entities/earning-rule.d.ts
 interface EarningConditions {
@@ -124,6 +125,19 @@ interface PointTransaction {
   expiredAt?: Date;
   metadata?: Record<string, unknown>;
   actorId: string;
+  /**
+   * Optional multi-step approval chain (P7 canonical — same shape as
+   * `@classytic/purchase` / `@classytic/order`). Manual `adjustment` /
+   * `bonus` transactions above a host-defined threshold gate on
+   * `isApproved(approvals)` before the journal entry is committed.
+   * Automatic transactions (earn from purchase, expiry sweeps) skip the
+   * chain entirely — single-tier flows leave this null.
+   */
+  approvals?: ApprovalChain | null;
+  /** Snapshot of the matrix policy id that produced this chain (host-managed). */
+  approvalPolicyId?: string | null;
+  /** Version of the matrix policy at submit time — frozen for audit. */
+  approvalPolicyVersion?: number | null;
   createdAt: Date;
 }
 //#endregion
@@ -203,6 +217,15 @@ interface LoyaltyContext extends OperationContext {
   organizationId?: string;
   /** Override program ID for multi-program setups. */
   programId?: string;
+  /**
+   * Cooperative cancellation for long-running cron loops (point expiry,
+   * reservation cleanup, tier evaluation, override sweeps, campaign award).
+   * Checked at each loop boundary via `throwIfAborted` — aborting between
+   * iterations never rolls back an already-committed transaction, and each
+   * per-item write is its own unit of work. Threaded to mongokit round-trips
+   * by hosts that pass it; mongokit (3.16+) honours it at every op boundary.
+   */
+  signal?: AbortSignal | undefined;
   /** Dynamic tenant key support — e.g. `{ companyId: '...' }` — when a host
    *  configured a custom `contextKey`. */
   [key: string]: unknown;

package/dist/index.d.mts

@@ -1,11 +1,159 @@
-import { S as EarningRule, a as EnrollInput, b as MemberBalance, c as UpdateTierInput, d as EarningResult, g as TierEvaluation, h as RedemptionValidation, i as EarnPointsInput, l as BalanceSummary, n as CreateEarningRuleInput, o as LoyaltyContext, r as CreateTierInput, s as UpdateEarningRuleInput, t as AdjustPointsInput, v as PointTransaction, x as TierDefinition, y as Member } from "./index-Bo5YQ_fu.mjs";
+import { S as EarningRule, a as EnrollInput, b as MemberBalance, c as UpdateTierInput, d as EarningResult, g as TierEvaluation, h as RedemptionValidation, i as EarnPointsInput, l as BalanceSummary, n as CreateEarningRuleInput, o as LoyaltyContext, r as CreateTierInput, s as UpdateEarningRuleInput, t as AdjustPointsInput, v as PointTransaction, x as TierDefinition, y as Member } from "./index-D20Cn4KB.mjs";
 import { t as NotificationAdapter } from "./notification.port-CJ9nXj0k.mjs";
-import { c as ResolvedTenant, n as LoyaltyConfig, r as LoyaltyModelName, s as ResolvedConfig } from "./config-96Sl6oNJ.mjs";
-import { A as PointsExpired, B as ReferralRewarded, C as MemberDeactivated, E as MemberSuspended, F as RedemptionReserved, G as TierUpgraded, H as TierGraceStarted, J as InProcessLoyaltyBusOptions, K as loyaltyEventDefinitions, L as ReferralApproved, M as PointsRedeemed, N as RedemptionConfirmed, O as PointsAdjusted, P as RedemptionReleased, R as ReferralRecorded, S as LoyaltyEventSchema, T as MemberReactivated, V as TierDowngraded, Y as createEvent, _ as TierChangedPayload, a as LoyaltyEventMap, b as LoyaltyEventDefinition, c as LoyaltyEvents, d as PointsAdjustedPayload, f as PointsEarnedPayload, g as ReferralPayload, j as PointsExpiringSoon, k as PointsEarned, l as MemberLifecyclePayload, m as RedemptionPayload, o as LoyaltyEventName, p as PointsExpiredPayload, q as InProcessLoyaltyBus, s as LoyaltyEventPayload, w as MemberEnrolled, x as LoyaltyEventPayloadOf, z as ReferralRejected } from "./index-xLLJ7jLy.mjs";
+import { c as ResolvedTenant, n as LoyaltyConfig, r as LoyaltyModelName, s as ResolvedConfig } from "./config-BdSyAdnF.mjs";
+import { A as PointsExpired, B as ReferralRewarded, C as MemberDeactivated, E as MemberSuspended, F as RedemptionReserved, G as TierUpgraded, H as TierGraceStarted, J as InProcessLoyaltyBusOptions, K as loyaltyEventDefinitions, L as ReferralApproved, M as PointsRedeemed, N as RedemptionConfirmed, O as PointsAdjusted, P as RedemptionReleased, R as ReferralRecorded, S as LoyaltyEventSchema, T as MemberReactivated, V as TierDowngraded, Y as createEvent, _ as TierChangedPayload, a as LoyaltyEventMap, b as LoyaltyEventDefinition, c as LoyaltyEvents, d as PointsAdjustedPayload, f as PointsEarnedPayload, g as ReferralPayload, j as PointsExpiringSoon, k as PointsEarned, l as MemberLifecyclePayload, m as RedemptionPayload, o as LoyaltyEventName, p as PointsExpiredPayload, q as InProcessLoyaltyBus, s as LoyaltyEventPayload, w as MemberEnrolled, x as LoyaltyEventPayloadOf, z as ReferralRejected } from "./index-CnESLipu.mjs";
 import { LoyaltyModels } from "./models/index.mjs";
-import { a as ReferralRepository, c as Redemption, d as MemberRepository, f as UnitOfWork, i as TierDefinitionRepository, l as EarningRuleRepository, n as LoyaltyRepositories, o as Referral, s as RedemptionRepository, u as PointTransactionRepository } from "./index-CMSNfGos.mjs";
-import { DomainEvent, EventHandler, EventTransport, EventTransport as EventTransport$1 } from "@classytic/primitives/events";
+import { a as ReferralRepository, c as Redemption, d as MemberRepository, f as UnitOfWork, i as TierDefinitionRepository, l as EarningRuleRepository, n as LoyaltyRepositories, o as Referral, s as RedemptionRepository, u as PointTransactionRepository } from "./index-BN96EDac.mjs";
+import { DomainEvent, DomainEvent as DomainEvent$1, EventHandler, EventTransport, EventTransport as EventTransport$1 } from "@classytic/primitives/events";
+import { OutboxStore } from "@classytic/primitives/outbox";
+import { HttpError } from "@classytic/repo-core/errors";
 
+//#region src/domain/errors/base.d.ts
+/**
+ * Base for every loyalty throwable. Implements `HttpError` from
+ * `@classytic/repo-core/errors` (the org-canonical throwable contract) so arc
+ * catches and serializes them to `ErrorContract` via `toErrorContract()` with
+ * the right HTTP `status` and a stable, machine-readable `code`.
+ *
+ * Codes are hierarchical + lowercase per PACKAGE_RULES ("Errors and wire
+ * envelopes"): `loyalty.<entity>.<problem>`. The `status` field (not the old
+ * `httpStatus`) is what `HttpError` / arc read — a clean break, no alias.
+ */
+declare abstract class LoyaltyError extends Error implements HttpError {
+  abstract readonly code: string;
+  abstract readonly status: number;
+  constructor(message: string);
+  toJSON(): {
+    code: string;
+    message: string;
+    name: string;
+    status: number;
+  };
+}
+//#endregion
+//#region src/domain/errors/domain-errors.d.ts
+declare class InsufficientPointsError extends LoyaltyError {
+  readonly code = "loyalty.points.insufficient";
+  readonly status = 400;
+  constructor(available: number, requested: number);
+}
+declare class MemberNotFoundError extends LoyaltyError {
+  readonly code = "loyalty.member.not_found";
+  readonly status = 404;
+  constructor(id: string);
+}
+declare class MemberAlreadyEnrolledError extends LoyaltyError {
+  readonly code = "loyalty.member.already_enrolled";
+  readonly status = 409;
+  constructor(externalId: string);
+}
+declare class MemberInactiveError extends LoyaltyError {
+  readonly code = "loyalty.member.inactive";
+  readonly status = 422;
+  constructor(id: string);
+}
+declare class RuleNotFoundError extends LoyaltyError {
+  readonly code = "loyalty.earning_rule.not_found";
+  readonly status = 404;
+  constructor(id: string);
+}
+declare class TierNotFoundError extends LoyaltyError {
+  readonly code = "loyalty.tier.not_found";
+  readonly status = 404;
+  constructor(id: string);
+}
+declare class RedemptionNotFoundError extends LoyaltyError {
+  readonly code = "loyalty.redemption.not_found";
+  readonly status = 404;
+  constructor(id: string);
+}
+declare class RedemptionExpiredError extends LoyaltyError {
+  readonly code = "loyalty.redemption.expired";
+  readonly status = 410;
+  constructor(id: string);
+}
+declare class ReferralNotFoundError extends LoyaltyError {
+  readonly code = "loyalty.referral.not_found";
+  readonly status = 404;
+  constructor(id: string);
+}
+declare class DuplicateReferralError extends LoyaltyError {
+  readonly code = "loyalty.referral.duplicate";
+  readonly status = 409;
+  constructor(refereeId: string);
+}
+declare class ReferralLimitExceededError extends LoyaltyError {
+  readonly code = "loyalty.referral.limit_exceeded";
+  readonly status = 429;
+  constructor(limit: number, periodDays: number);
+}
+declare class SelfReferralError extends LoyaltyError {
+  readonly code = "loyalty.referral.self";
+  readonly status = 422;
+  constructor();
+}
+declare class CircularReferralError extends LoyaltyError {
+  readonly code = "loyalty.referral.circular";
+  readonly status = 422;
+  constructor();
+}
+declare class ValidationError extends LoyaltyError {
+  readonly code = "loyalty.validation.invalid";
+  readonly status = 400;
+}
+declare class TenantIsolationError extends LoyaltyError {
+  readonly code = "loyalty.tenant.isolation";
+  readonly status = 403;
+  constructor();
+}
+/**
+ * A host passed `ctx.session` (it owns the outer transaction) but did NOT
+ * attach a `[PENDING_EVENTS]` queue. Publishing to in-process subscribers
+ * BEFORE the host's commit would leak ghost events on rollback, and the
+ * outbox save would not be coordinated with the host's unit of work.
+ *
+ * Two safe patterns: (1) let loyalty own the transaction — call the verb
+ * WITHOUT `ctx.session`; or (2) attach a fresh `[PENDING_EVENTS]` array via
+ * `{ ...ctx, [PENDING_EVENTS]: queue }` and call `flushPendingLoyaltyEvents`
+ * after your transaction commits. Both are exported from the package root.
+ */
+declare class UnmanagedSessionError extends LoyaltyError {
+  readonly code = "loyalty.transaction.unmanaged_session";
+  readonly status = 400;
+  constructor();
+}
+/**
+ * The backend doesn't declare the runtime capabilities loyalty's
+ * transactional verbs require (earn / adjust / reserve / confirm / release /
+ * reverse all run inside `withTransaction`). MongoDB must run as a replica set
+ * or sharded cluster. Thrown at engine creation — fail loud at boot, not with
+ * a cryptic driver error on the first transactional call.
+ */
+declare class LoyaltyCapabilityError extends LoyaltyError {
+  readonly code = "loyalty.engine.missing_capabilities";
+  readonly status = 500;
+  constructor(missing: readonly string[]);
+}
+//#endregion
+//#region src/events/dispatch.d.ts
+/**
+ * Internal key under which the post-commit event-publish queue is threaded
+ * through the context. When set, `dispatchLoyaltyEvent` APPENDS to this queue
+ * instead of publishing immediately — the verb that owns the transaction
+ * flushes it after commit. A `Symbol.for` so it never collides with
+ * host-supplied context fields and never appears in the public type.
+ */
+declare const PENDING_EVENTS: unique symbol;
+/**
+ * Drains a queue of deferred events (the one attached under `[PENDING_EVENTS]`)
+ * through the transport, swallowing per-event errors. Called by transactional
+ * verbs AFTER `withTransaction` commits, and exported so hosts that own the
+ * outer transaction can flush after their own commit.
+ */
+declare function flushPendingLoyaltyEvents(events: EventTransport$1 | undefined, queue: DomainEvent$1[], logger?: {
+  error(message: string, ...args: unknown[]): void;
+} | undefined): Promise<void>;
+//#endregion
 //#region src/index.d.ts
 declare function resolveConfig(config: LoyaltyConfig): ResolvedConfig;
 /**
@@ -34,4 +182,4 @@ interface LoyaltyEngine {
 }
 declare function createLoyaltyEngine(config: LoyaltyConfig): LoyaltyEngine;
 //#endregion
-export { type AdjustPointsInput, type BalanceSummary, type CreateEarningRuleInput, type CreateTierInput, type DomainEvent, type EarnPointsInput, type EarningResult, type EarningRule, EarningRuleRepository, type EnrollInput, type EventHandler, type EventTransport, InProcessLoyaltyBus, type InProcessLoyaltyBusOptions, type LoyaltyConfig, type LoyaltyContext, LoyaltyEngine, type LoyaltyEventDefinition, type LoyaltyEventMap, type LoyaltyEventName, type LoyaltyEventPayload, type LoyaltyEventPayloadOf, type LoyaltyEventSchema, LoyaltyEvents, type LoyaltyModelName, type LoyaltyModels, type LoyaltyRepositories, type Member, type MemberBalance, MemberDeactivated, MemberEnrolled, type MemberLifecyclePayload, MemberReactivated, MemberRepository, MemberSuspended, type NotificationAdapter, type PointTransaction, PointTransactionRepository, PointsAdjusted, type PointsAdjustedPayload, PointsEarned, type PointsEarnedPayload, PointsExpired, type PointsExpiredPayload, PointsExpiringSoon, PointsRedeemed, type Redemption, RedemptionConfirmed, type RedemptionPayload, RedemptionReleased, RedemptionRepository, RedemptionReserved, type RedemptionValidation, type Referral, ReferralApproved, type ReferralPayload, ReferralRecorded, ReferralRejected, ReferralRepository, ReferralRewarded, type ResolvedConfig, type ResolvedTenant, type TierChangedPayload, type TierDefinition, TierDefinitionRepository, TierDowngraded, type TierEvaluation, TierGraceStarted, TierUpgraded, type UnitOfWork, type UpdateEarningRuleInput, type UpdateTierInput, createEvent, createLoyaltyEngine, loyaltyEventDefinitions, resolveConfig };
+export { type AdjustPointsInput, type BalanceSummary, CircularReferralError, type CreateEarningRuleInput, type CreateTierInput, type DomainEvent, DuplicateReferralError, type EarnPointsInput, type EarningResult, type EarningRule, EarningRuleRepository, type EnrollInput, type EventHandler, type EventTransport, InProcessLoyaltyBus, type InProcessLoyaltyBusOptions, InsufficientPointsError, LoyaltyCapabilityError, type LoyaltyConfig, type LoyaltyContext, LoyaltyEngine, type LoyaltyEventDefinition, type LoyaltyEventMap, type LoyaltyEventName, type LoyaltyEventPayload, type LoyaltyEventPayloadOf, type LoyaltyEventSchema, LoyaltyEvents, type LoyaltyModelName, type LoyaltyModels, type LoyaltyRepositories, type Member, MemberAlreadyEnrolledError, type MemberBalance, MemberDeactivated, MemberEnrolled, MemberInactiveError, type MemberLifecyclePayload, MemberNotFoundError, MemberReactivated, MemberRepository, MemberSuspended, type NotificationAdapter, PENDING_EVENTS, type PointTransaction, PointTransactionRepository, PointsAdjusted, type PointsAdjustedPayload, PointsEarned, type PointsEarnedPayload, PointsExpired, type PointsExpiredPayload, PointsExpiringSoon, PointsRedeemed, type Redemption, RedemptionConfirmed, RedemptionExpiredError, RedemptionNotFoundError, type RedemptionPayload, RedemptionReleased, RedemptionRepository, RedemptionReserved, type RedemptionValidation, type Referral, ReferralApproved, ReferralLimitExceededError, ReferralNotFoundError, type ReferralPayload, ReferralRecorded, ReferralRejected, ReferralRepository, ReferralRewarded, type ResolvedConfig, type ResolvedTenant, RuleNotFoundError, SelfReferralError, TenantIsolationError, type TierChangedPayload, type TierDefinition, TierDefinitionRepository, TierDowngraded, type TierEvaluation, TierGraceStarted, TierNotFoundError, TierUpgraded, type UnitOfWork, UnmanagedSessionError, type UpdateEarningRuleInput, type UpdateTierInput, ValidationError, createEvent, createLoyaltyEngine, flushPendingLoyaltyEvents, loyaltyEventDefinitions, resolveConfig };