@classytic/loyalty 0.4.0 → 0.5.0

package/CHANGELOG.md

@@ -1,215 +1,231 @@
-# Changelog
-
-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] — addendum (2026-07-05)
-
-### Changed (behavioral)
-
-- **§P8.1 relay-only session guard** — `UnmanagedSessionError` now throws
-  only when a host session arrives with NEITHER a `[PENDING_EVENTS]`
-  queue NOR an outbox. Session + outbox + no queue is legal
-  durable-relay-only mode: the row commits with the host transaction, the
-  relay delivers post-commit, the immediate transport publish is skipped.
-  (Previously the guard was stricter than spec and threw even with an
-  outbox wired.) Aligns loyalty with invoice / catalog / order /
-  purchase / transfer / promo / payrun.
-- **Stack floors raised** — peers `@classytic/mongokit >=3.18.0`,
-  `@classytic/repo-core >=0.7.0`; full suite verified against those
-  versions.
-
-## [0.4.0] — 2026-07-03
-
-### Fixed
-
-- **`evaluateAction` is now idempotent per recurrence key.** The order path
-  dedupes with `${orderId}:${ruleId}`, but the action path (signup /
-  referral / birthday / review) never set an `idempotencyKey` — a retried
-  sweep or double-fired event double-awarded points. When `referenceId` is
-  supplied, each rule award now carries `${referenceId}:${ruleId}`; callers
-  encode the recurrence period in `referenceId` (e.g.
-  `birthday:2026:<memberId>`) and the unique partial index on
-  `idempotencyKey` becomes the authoritative once-only guard.
-- **Action rules honor `conditions` now.** `evaluateAction` skipped
-  `matchesConditions` entirely, silently ignoring admin-authored
-  `tiers` / `dateRange` / `dayOfWeek` on action-type rules ("only gold
-  members get birthday points" did nothing). Conditions now apply;
-  `minOrderAmount` is skipped for actions (no order to measure).
-- **`allowNonTransactional` now actually works at runtime.** The flag
-  silenced the boot capability gate but `MongoUnitOfWork.withTransaction`
-  still opened a real transaction unconditionally — on standalone Mongo
-  every `earnPoints`/`redeem` unit failed with "does not support retryable
-  writes" despite the documented escape hatch. The unit of work now
-  delegates to mongokit's `withTransaction` with `allowFallback` so the
-  transactions-unsupported error re-runs the unit on a plain session
-  (partial-write risk accepted, exactly what the flag opts into).
-- Day arithmetic (tier-downgrade grace expiry, referral rate-limit window)
-  now uses `addDays` from `@classytic/primitives/calendar` — exact 24h × n
-  durations instead of local `setDate`, which shifted with the deploy
-  machine's `TZ` env. Primitives peer bumped to `>=0.9.0`.
-
-## [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
-smaller, sharper surface organized around seven subpath exports
-(`/domain/enums`, `/models`, `/repositories`, `/events`, `/types`,
-`/notifications`, plus the root engine factory). Legacy barrel + service
-layers were removed; hosts wire business flows directly against the
-repositories and the engine factory.
-
-### Changed
-
-- **Domain restructure.** Dropped the `src/domain/ports/` + `src/services/`
-  layer in favor of thin repositories that expose exactly the operations
-  hosts need — `earn`, `redeem`, `adjust`, `expire`, referral credit,
-  tier recomputation. No more `earning.service` / `redemption.service` /
-  `tier.service` / `referral.service` / `ledger.service` / `member.service`
-  / `member-guard` indirections; the equivalent logic lives on the
-  repositories where it's naturally atomic.
-- **Events subsystem simplified.** Removed `events/event-bus.ts` +
-  `events/event-types.ts` (both are internal indirection that the engine
-  didn't need). Event payloads are now colocated with the repository
-  that emits them.
-- **Repositories updated to mongokit 3.11 + repo-core 0.2 conventions.**
-  Every repo extends `Repository<T>` directly, uses the tenant plugin via
-  `injectTenant`, and atomic state changes go through CAS guards.
-- **Peer deps** unchanged in spirit, tightened in range:
-  - `@classytic/mongokit >= 3.11`
-  - `@classytic/primitives >= 0.1`
-  - `@classytic/repo-core >= 0.2`
-  - `mongoose >= 9.4`, `zod >= 4`
-- **DevDeps:** `@classytic/primitives` devDep moved from `file:` to `>=0.1.0`
-  (now that primitives ships on npm); all `@classytic/*` dev ranges
-  standardized on `>=`.
-
-### Removed
-
-- `src/services/*` — logic folded into repositories.
-- `src/domain/ports/*` barrels and per-port files — structural types
-  now live with the repositories they describe.
-- Event-bus indirection — repositories emit via the engine's configured
-  transport directly.
-
-### Added
-
-- Subpath export `/notifications` — notification port + built-in
-  lifecycle payloads (tier up/down, points expiring, referral credit).
-- Test restructure — 257 tests across unit + integration projects; the
-  deleted legacy suites were collapsed into focused scenario files that
-  exercise the new public API.
-
-### Peer compatibility
-
-Anyone on 0.1.0 wiring against the old `*.service.ts` modules will need
-to migrate to the repository methods. Signatures are similar — earn /
-redeem / adjust remain the nouns — but the call sites move from
-`services.earning.earnPoints(...)` to `repositories.pointTransaction.earn(...)`
-and similar. No behavior changes in the ledger semantics.
-
-## [0.1.0]
-
-Initial release. Loyalty points, tiers, earning rules, referrals, and
-redemption engine for MongoDB. Tenant-scoped, event-emitting, atomic
-point-ledger with CAS guards.
+# Changelog
+
+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.5.0] — unpublished (2026-07-15)
+
+### Changed — mongokit 3.22 adopted (peer floors: mongokit >=3.22.0, repo-core >=0.13.0, primitives >=0.11.0)
+
+- **Points ledger fence enforced** — `PointTransaction` rows are the
+  balance audit trail; `appendOnlyPlugin` now refuses every mutation
+  path (405 `APPEND_ONLY_VIOLATION`). Previously nothing enforced it —
+  a stray `update()` could rewrite an earn/burn row and silently
+  desync the audit trail from member balances. The expiry sweeper's
+  `expiredAt` stamp is the one engine-owned lifecycle write and passes
+  the audited `bypassAppendOnly` escape.
+- No FSM boilerplate existed (no assert+claim sites, no
+  read-modify-write history) — loyalty was already clean there; this
+  release is the fence + kit refresh (clean registry install, no
+  legacy flags).
+
+## [0.4.0] — addendum (2026-07-05)
+
+### Changed (behavioral)
+
+- **§P8.1 relay-only session guard** — `UnmanagedSessionError` now throws
+  only when a host session arrives with NEITHER a `[PENDING_EVENTS]`
+  queue NOR an outbox. Session + outbox + no queue is legal
+  durable-relay-only mode: the row commits with the host transaction, the
+  relay delivers post-commit, the immediate transport publish is skipped.
+  (Previously the guard was stricter than spec and threw even with an
+  outbox wired.) Aligns loyalty with invoice / catalog / order /
+  purchase / transfer / promo / payrun.
+- **Stack floors raised** — peers `@classytic/mongokit >=3.18.0`,
+  `@classytic/repo-core >=0.7.0`; full suite verified against those
+  versions.
+
+## [0.4.0] — 2026-07-03
+
+### Fixed
+
+- **`evaluateAction` is now idempotent per recurrence key.** The order path
+  dedupes with `${orderId}:${ruleId}`, but the action path (signup /
+  referral / birthday / review) never set an `idempotencyKey` — a retried
+  sweep or double-fired event double-awarded points. When `referenceId` is
+  supplied, each rule award now carries `${referenceId}:${ruleId}`; callers
+  encode the recurrence period in `referenceId` (e.g.
+  `birthday:2026:<memberId>`) and the unique partial index on
+  `idempotencyKey` becomes the authoritative once-only guard.
+- **Action rules honor `conditions` now.** `evaluateAction` skipped
+  `matchesConditions` entirely, silently ignoring admin-authored
+  `tiers` / `dateRange` / `dayOfWeek` on action-type rules ("only gold
+  members get birthday points" did nothing). Conditions now apply;
+  `minOrderAmount` is skipped for actions (no order to measure).
+- **`allowNonTransactional` now actually works at runtime.** The flag
+  silenced the boot capability gate but `MongoUnitOfWork.withTransaction`
+  still opened a real transaction unconditionally — on standalone Mongo
+  every `earnPoints`/`redeem` unit failed with "does not support retryable
+  writes" despite the documented escape hatch. The unit of work now
+  delegates to mongokit's `withTransaction` with `allowFallback` so the
+  transactions-unsupported error re-runs the unit on a plain session
+  (partial-write risk accepted, exactly what the flag opts into).
+- Day arithmetic (tier-downgrade grace expiry, referral rate-limit window)
+  now uses `addDays` from `@classytic/primitives/calendar` — exact 24h × n
+  durations instead of local `setDate`, which shifted with the deploy
+  machine's `TZ` env. Primitives peer bumped to `>=0.9.0`.
+
+## [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
+smaller, sharper surface organized around seven subpath exports
+(`/domain/enums`, `/models`, `/repositories`, `/events`, `/types`,
+`/notifications`, plus the root engine factory). Legacy barrel + service
+layers were removed; hosts wire business flows directly against the
+repositories and the engine factory.
+
+### Changed
+
+- **Domain restructure.** Dropped the `src/domain/ports/` + `src/services/`
+  layer in favor of thin repositories that expose exactly the operations
+  hosts need — `earn`, `redeem`, `adjust`, `expire`, referral credit,
+  tier recomputation. No more `earning.service` / `redemption.service` /
+  `tier.service` / `referral.service` / `ledger.service` / `member.service`
+  / `member-guard` indirections; the equivalent logic lives on the
+  repositories where it's naturally atomic.
+- **Events subsystem simplified.** Removed `events/event-bus.ts` +
+  `events/event-types.ts` (both are internal indirection that the engine
+  didn't need). Event payloads are now colocated with the repository
+  that emits them.
+- **Repositories updated to mongokit 3.11 + repo-core 0.2 conventions.**
+  Every repo extends `Repository<T>` directly, uses the tenant plugin via
+  `injectTenant`, and atomic state changes go through CAS guards.
+- **Peer deps** unchanged in spirit, tightened in range:
+  - `@classytic/mongokit >= 3.11`
+  - `@classytic/primitives >= 0.1`
+  - `@classytic/repo-core >= 0.2`
+  - `mongoose >= 9.4`, `zod >= 4`
+- **DevDeps:** `@classytic/primitives` devDep moved from `file:` to `>=0.1.0`
+  (now that primitives ships on npm); all `@classytic/*` dev ranges
+  standardized on `>=`.
+
+### Removed
+
+- `src/services/*` — logic folded into repositories.
+- `src/domain/ports/*` barrels and per-port files — structural types
+  now live with the repositories they describe.
+- Event-bus indirection — repositories emit via the engine's configured
+  transport directly.
+
+### Added
+
+- Subpath export `/notifications` — notification port + built-in
+  lifecycle payloads (tier up/down, points expiring, referral credit).
+- Test restructure — 257 tests across unit + integration projects; the
+  deleted legacy suites were collapsed into focused scenario files that
+  exercise the new public API.
+
+### Peer compatibility
+
+Anyone on 0.1.0 wiring against the old `*.service.ts` modules will need
+to migrate to the repository methods. Signatures are similar — earn /
+redeem / adjust remain the nouns — but the call sites move from
+`services.earning.earnPoints(...)` to `repositories.pointTransaction.earn(...)`
+and similar. No behavior changes in the ledger semantics.
+
+## [0.1.0]
+
+Initial release. Loyalty points, tiers, earning rules, referrals, and
+redemption engine for MongoDB. Tenant-scoped, event-emitting, atomic
+point-ledger with CAS guards.

package/dist/index.mjs

@@ -1,5 +1,5 @@
 import { n as DEFAULT_TENANT_FIELD, r as DEFAULT_TENANT_TYPE } from "./constants-DkQYkOK1.mjs";
-import { C as TenantIsolationError, E as ValidationError, S as SelfReferralError, T as UnmanagedSessionError, _ as RedemptionExpiredError, a as PointTransactionRepository, b as ReferralNotFoundError, c as flushPendingLoyaltyEvents, d as DuplicateReferralError, f as InsufficientPointsError, g as MemberNotFoundError, h as MemberInactiveError, i as RedemptionRepository, l as EarningRuleRepository, m as MemberAlreadyEnrolledError, n as TierDefinitionRepository, o as MemberRepository, p as LoyaltyCapabilityError, r as ReferralRepository, s as PENDING_EVENTS, t as createRepositories, u as CircularReferralError, v as RedemptionNotFoundError, w as TierNotFoundError, x as RuleNotFoundError, y as ReferralLimitExceededError } from "./repositories-DEwCbLCh.mjs";
+import { C as TenantIsolationError, E as ValidationError, S as SelfReferralError, T as UnmanagedSessionError, _ as RedemptionExpiredError, a as PointTransactionRepository, b as ReferralNotFoundError, c as flushPendingLoyaltyEvents, d as DuplicateReferralError, f as InsufficientPointsError, g as MemberNotFoundError, h as MemberInactiveError, i as RedemptionRepository, l as EarningRuleRepository, m as MemberAlreadyEnrolledError, n as TierDefinitionRepository, o as MemberRepository, p as LoyaltyCapabilityError, r as ReferralRepository, s as PENDING_EVENTS, t as createRepositories, u as CircularReferralError, v as RedemptionNotFoundError, w as TierNotFoundError, x as RuleNotFoundError, y as ReferralLimitExceededError } from "./repositories-CjWfUlrA.mjs";
 import { E as InProcessLoyaltyBus, T as loyaltyEventDefinitions, _ as ReferralRecorded, a as MemberSuspended, b as TierDowngraded, c as PointsEarned, d as PointsRedeemed, f as RedemptionConfirmed, g as ReferralApproved, i as MemberReactivated, l as PointsExpired, m as RedemptionReserved, n as MemberDeactivated, p as RedemptionReleased, r as MemberEnrolled, s as PointsAdjusted, u as PointsExpiringSoon, v as ReferralRejected, w as TierUpgraded, x as TierGraceStarted, y as ReferralRewarded } from "./events-DN5_p6T0.mjs";
 import { n as createModels } from "./models-Ddh62lgO.mjs";
 import { n as createEvent, t as LoyaltyEvents } from "./loyalty-events-C38JA3cU.mjs";

package/dist/models/index.d.mts

@@ -86,9 +86,9 @@ declare function createModels(connection: Connection, tenant: ResolvedTenant, in
     _id: _$mongoose.Types.ObjectId;
   } & {
     __v: number;
-  }, "id"> & {
+  }, "id"> & _$mongoose.HydratedDocumentOverrides<{
     id: string;
-  }, _$mongoose.Schema<any, Model<any, any, any, any, any, any, any>, {}, {}, {}, {}, {
+  }>, _$mongoose.Schema<any, Model<any, any, any, any, any, any, any>, {}, {}, {}, {}, {
     timestamps: true;
   }, {
     programId: string;
@@ -167,9 +167,9 @@ declare function createModels(connection: Connection, tenant: ResolvedTenant, in
     _id: _$mongoose.Types.ObjectId;
   } & {
     __v: number;
-  }, "id"> & {
+  }, "id"> & _$mongoose.HydratedDocumentOverrides<{
     id: string;
-  }, unknown, {
+  }>, unknown, {
     programId: string;
     externalId: string;
     externalType: string;
@@ -298,9 +298,9 @@ declare function createModels(connection: Connection, tenant: ResolvedTenant, in
     _id: _$mongoose.Types.ObjectId;
   } & {
     __v: number;
-  }, "id"> & {
+  }, "id"> & _$mongoose.HydratedDocumentOverrides<{
     id: string;
-  }, _$mongoose.Schema<any, Model<any, any, any, any, any, any, any>, {}, {}, {}, {}, {
+  }>, _$mongoose.Schema<any, Model<any, any, any, any, any, any, any>, {}, {}, {}, {}, {
     timestamps: {
       createdAt: true;
       updatedAt: false;
@@ -373,9 +373,9 @@ declare function createModels(connection: Connection, tenant: ResolvedTenant, in
     _id: _$mongoose.Types.ObjectId;
   } & {
     __v: number;
-  }, "id"> & {
+  }, "id"> & _$mongoose.HydratedDocumentOverrides<{
     id: string;
-  }, unknown, {
+  }>, unknown, {
     programId: string;
     type: "earn" | "redeem" | "adjust" | "expire" | "transfer" | "referral_bonus";
     description: string;
@@ -519,9 +519,9 @@ declare function createModels(connection: Connection, tenant: ResolvedTenant, in
     _id: _$mongoose.Types.ObjectId;
   } & {
     __v: number;
-  }, "id"> & {
+  }, "id"> & _$mongoose.HydratedDocumentOverrides<{
     id: string;
-  }, _$mongoose.Schema<any, Model<any, any, any, any, any, any, any>, {}, {}, {}, {}, {
+  }>, _$mongoose.Schema<any, Model<any, any, any, any, any, any, any>, {}, {}, {}, {}, {
     timestamps: true;
   }, {
     programId: string;
@@ -618,9 +618,9 @@ declare function createModels(connection: Connection, tenant: ResolvedTenant, in
     _id: _$mongoose.Types.ObjectId;
   } & {
     __v: number;
-  }, "id"> & {
+  }, "id"> & _$mongoose.HydratedDocumentOverrides<{
     id: string;
-  }, unknown, {
+  }>, unknown, {
     programId: string;
     type: "order" | "action" | "category" | "tier_bonus";
     name: string;
@@ -764,9 +764,9 @@ declare function createModels(connection: Connection, tenant: ResolvedTenant, in
     _id: _$mongoose.Types.ObjectId;
   } & {
     __v: number;
-  }, "id"> & {
+  }, "id"> & _$mongoose.HydratedDocumentOverrides<{
     id: string;
-  }, _$mongoose.Schema<any, Model<any, any, any, any, any, any, any>, {}, {}, {}, {}, {
+  }>, _$mongoose.Schema<any, Model<any, any, any, any, any, any, any>, {}, {}, {}, {}, {
     timestamps: true;
   }, {
     programId: string;
@@ -839,9 +839,9 @@ declare function createModels(connection: Connection, tenant: ResolvedTenant, in
     _id: _$mongoose.Types.ObjectId;
   } & {
     __v: number;
-  }, "id"> & {
+  }, "id"> & _$mongoose.HydratedDocumentOverrides<{
     id: string;
-  }, unknown, {
+  }>, unknown, {
     programId: string;
     name: string;
     rank: number;
@@ -972,9 +972,9 @@ declare function createModels(connection: Connection, tenant: ResolvedTenant, in
     _id: _$mongoose.Types.ObjectId;
   } & {
     __v: number;
-  }, "id"> & {
+  }, "id"> & _$mongoose.HydratedDocumentOverrides<{
     id: string;
-  }, _$mongoose.Schema<any, Model<any, any, any, any, any, any, any>, {}, {}, {}, {}, {
+  }>, _$mongoose.Schema<any, Model<any, any, any, any, any, any, any>, {}, {}, {}, {}, {
     timestamps: true;
   }, {
     programId: string;
@@ -1050,9 +1050,9 @@ declare function createModels(connection: Connection, tenant: ResolvedTenant, in
     _id: _$mongoose.Types.ObjectId;
   } & {
     __v: number;
-  }, "id"> & {
+  }, "id"> & _$mongoose.HydratedDocumentOverrides<{
     id: string;
-  }, unknown, {
+  }>, unknown, {
     programId: string;
     status: "expired" | "reserved" | "confirmed" | "released" | "reversed";
     memberId: _$mongoose.Types.ObjectId;
@@ -1164,9 +1164,9 @@ declare function createModels(connection: Connection, tenant: ResolvedTenant, in
     _id: _$mongoose.Types.ObjectId;
   } & {
     __v: number;
-  }, "id"> & {
+  }, "id"> & _$mongoose.HydratedDocumentOverrides<{
     id: string;
-  }, _$mongoose.Schema<any, Model<any, any, any, any, any, any, any>, {}, {}, {}, {}, {
+  }>, _$mongoose.Schema<any, Model<any, any, any, any, any, any, any>, {}, {}, {}, {}, {
     timestamps: true;
   }, {
     programId: string;
@@ -1221,9 +1221,9 @@ declare function createModels(connection: Connection, tenant: ResolvedTenant, in
     _id: _$mongoose.Types.ObjectId;
   } & {
     __v: number;
-  }, "id"> & {
+  }, "id"> & _$mongoose.HydratedDocumentOverrides<{
     id: string;
-  }, unknown, {
+  }>, unknown, {
     programId: string;
     status: "expired" | "pending" | "approved" | "rejected";
     referralCode: string;

package/dist/repositories/index.mjs

@@ -1,2 +1,2 @@
-import { a as PointTransactionRepository, i as RedemptionRepository, l as EarningRuleRepository, n as TierDefinitionRepository, o as MemberRepository, r as ReferralRepository, t as createRepositories } from "../repositories-DEwCbLCh.mjs";
+import { a as PointTransactionRepository, i as RedemptionRepository, l as EarningRuleRepository, n as TierDefinitionRepository, o as MemberRepository, r as ReferralRepository, t as createRepositories } from "../repositories-CjWfUlrA.mjs";
 export { EarningRuleRepository, MemberRepository, PointTransactionRepository, RedemptionRepository, ReferralRepository, TierDefinitionRepository, createRepositories };

package/dist/{repositories-DEwCbLCh.mjs → repositories-CjWfUlrA.mjs}

@@ -1,5 +1,5 @@
 import { n as createEvent, t as LoyaltyEvents } from "./loyalty-events-C38JA3cU.mjs";
-import { Repository, multiTenantPlugin } from "@classytic/mongokit";
+import { Repository, appendOnlyPlugin, multiTenantPlugin } from "@classytic/mongokit";
 import { localTimeParts } from "@classytic/primitives/timezone";
 import { addDays, isoWeekday } from "@classytic/primitives/calendar";
 import { randomBytes } from "node:crypto";
@@ -709,7 +709,7 @@ var PointTransactionRepository = class extends Repository {
 	unitOfWork;
 	config;
 	constructor(model, plugins = []) {
-		super(model, plugins);
+		super(model, [...plugins, appendOnlyPlugin()]);
 	}
 	/** Session-bound outbox save + transport publish (PACKAGE_RULES §5.5 + P8). */
 	async _dispatch(event, ctx) {
@@ -1001,7 +1001,8 @@ var PointTransactionRepository = class extends Repository {
 				});
 				await this.update(tx._id, { expiredAt: now }, {
 					session,
-					...tc
+					...tc,
+					bypassAppendOnly: true
 				});
 				await this.memberRepo.updateBalance(tx.memberId, {
 					current: -tx.points,

package/package.json

@@ -1,116 +1,116 @@
-{
-  "name": "@classytic/loyalty",
-  "version": "0.4.0",
-  "description": "Loyalty points, tiers, earning rules, referrals, and redemption engine for MongoDB",
-  "author": "Classytic",
-  "homepage": "https://www.npmjs.com/package/@classytic/loyalty",
-  "bugs": {
-    "url": "https://github.com/classytic/loyalty/issues"
-  },
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/classytic/loyalty.git"
-  },
-  "publishConfig": {
-    "access": "public"
-  },
-  "type": "module",
-  "sideEffects": false,
-  "engines": {
-    "node": ">=22"
-  },
-  "exports": {
-    ".": {
-      "types": "./dist/index.d.mts",
-      "default": "./dist/index.mjs"
-    },
-    "./domain/enums": {
-      "types": "./dist/domain/enums/index.d.mts",
-      "default": "./dist/domain/enums/index.mjs"
-    },
-    "./models": {
-      "types": "./dist/models/index.d.mts",
-      "default": "./dist/models/index.mjs"
-    },
-    "./repositories": {
-      "types": "./dist/repositories/index.d.mts",
-      "default": "./dist/repositories/index.mjs"
-    },
-    "./events": {
-      "types": "./dist/events/index.d.mts",
-      "default": "./dist/events/index.mjs"
-    },
-    "./types": {
-      "types": "./dist/types/index.d.mts",
-      "default": "./dist/types/index.mjs"
-    },
-    "./notifications": {
-      "types": "./dist/notifications/index.d.mts",
-      "default": "./dist/notifications/index.mjs"
-    }
-  },
-  "main": "./dist/index.mjs",
-  "types": "./dist/index.d.mts",
-  "files": [
-    "dist",
-    "README.md",
-    "CHANGELOG.md",
-    "LICENSE"
-  ],
-  "scripts": {
-    "build": "tsdown",
-    "dev": "tsdown --watch",
-    "test": "vitest run --project unit --project integration",
-    "test:unit": "vitest run --project unit",
-    "test:integration": "vitest run --project integration",
-    "test:scenarios": "vitest run --project scenarios",
-    "test:all": "vitest run",
-    "test:watch": "vitest --project unit --project integration",
-    "test:coverage": "vitest run --coverage",
-    "typecheck": "tsc --noEmit",
-    "lint": "biome check src/ tests/",
-    "lint:fix": "biome check --write src/ tests/",
-    "format": "biome format --write src/ tests/",
-    "check": "biome check --write --unsafe src/ tests/",
-    "prepublishOnly": "npm run lint && npm run typecheck && npm run test && npm run build",
-    "push": "classytic-push",
-    "release:tag": "node -e \"require('child_process').execSync('npm run push -- v'+require('./package.json').version,{stdio:'inherit'})\"",
-    "release": "npm run push -- main && npm run release:tag && npm publish"
-  },
-  "peerDependencies": {
-    "@classytic/mongokit": ">=3.18.0",
-    "@classytic/primitives": ">=0.9.0",
-    "@classytic/repo-core": ">=0.7.0",
-    "mongoose": ">=9.4.1",
-    "zod": ">=4.0.0"
-  },
-  "devDependencies": {
-    "@biomejs/biome": "^2.4.9",
-    "@classytic/dev-tools": "^0.2.0",
-    "@classytic/mongokit": "^3.18.0",
-    "@classytic/primitives": "^0.9.0",
-    "@classytic/repo-core": "^0.7.0",
-    "@types/node": "^25.5.0",
-    "@vitest/coverage-v8": "^3.2.4",
-    "knip": "^6.3.0",
-    "mongodb-memory-server": "^10.2.3",
-    "mongoose": "^9.4.1",
-    "tsdown": "^0.21.5",
-    "typescript": "^5.7.0",
-    "vitest": "^3.0.0",
-    "zod": "^4.3.6"
-  },
-  "keywords": [
-    "loyalty",
-    "points",
-    "rewards",
-    "tiers",
-    "referral",
-    "membership",
-    "earning-rules",
-    "redemption",
-    "mongodb",
-    "mongoose"
-  ],
-  "license": "MIT"
-}
+{
+  "name": "@classytic/loyalty",
+  "version": "0.5.0",
+  "description": "Loyalty points, tiers, earning rules, referrals, and redemption engine for MongoDB",
+  "author": "Classytic",
+  "homepage": "https://www.npmjs.com/package/@classytic/loyalty",
+  "bugs": {
+    "url": "https://github.com/classytic/loyalty/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/classytic/loyalty.git"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "sideEffects": false,
+  "engines": {
+    "node": ">=22"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.mts",
+      "default": "./dist/index.mjs"
+    },
+    "./domain/enums": {
+      "types": "./dist/domain/enums/index.d.mts",
+      "default": "./dist/domain/enums/index.mjs"
+    },
+    "./models": {
+      "types": "./dist/models/index.d.mts",
+      "default": "./dist/models/index.mjs"
+    },
+    "./repositories": {
+      "types": "./dist/repositories/index.d.mts",
+      "default": "./dist/repositories/index.mjs"
+    },
+    "./events": {
+      "types": "./dist/events/index.d.mts",
+      "default": "./dist/events/index.mjs"
+    },
+    "./types": {
+      "types": "./dist/types/index.d.mts",
+      "default": "./dist/types/index.mjs"
+    },
+    "./notifications": {
+      "types": "./dist/notifications/index.d.mts",
+      "default": "./dist/notifications/index.mjs"
+    }
+  },
+  "main": "./dist/index.mjs",
+  "types": "./dist/index.d.mts",
+  "files": [
+    "dist",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsdown",
+    "dev": "tsdown --watch",
+    "test": "vitest run --project unit --project integration",
+    "test:unit": "vitest run --project unit",
+    "test:integration": "vitest run --project integration",
+    "test:scenarios": "vitest run --project scenarios",
+    "test:all": "vitest run",
+    "test:watch": "vitest --project unit --project integration",
+    "test:coverage": "vitest run --coverage",
+    "typecheck": "tsc --noEmit",
+    "lint": "biome check src/ tests/",
+    "lint:fix": "biome check --write src/ tests/",
+    "format": "biome format --write src/ tests/",
+    "check": "biome check --write --unsafe src/ tests/",
+    "prepublishOnly": "npm run lint && npm run typecheck && npm run test && npm run build",
+    "push": "classytic-push",
+    "release:tag": "node -e \"require('child_process').execSync('npm run push -- v'+require('./package.json').version,{stdio:'inherit'})\"",
+    "release": "npm run push -- main && npm run release:tag && npm publish"
+  },
+  "peerDependencies": {
+    "@classytic/mongokit": ">=3.22.0",
+    "@classytic/primitives": ">=0.11.0",
+    "@classytic/repo-core": ">=0.13.0",
+    "mongoose": ">=9.4.1",
+    "zod": ">=4.0.0"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.4.9",
+    "@classytic/dev-tools": "^0.2.0",
+    "@classytic/mongokit": "^3.22.0",
+    "@classytic/primitives": "^0.11.0",
+    "@classytic/repo-core": "^0.13.0",
+    "@types/node": "^25.5.0",
+    "@vitest/coverage-v8": "^3.2.4",
+    "knip": "^6.3.0",
+    "mongodb-memory-server": "^10.2.3",
+    "mongoose": "^9.4.1",
+    "tsdown": "^0.21.5",
+    "typescript": "^5.7.0",
+    "vitest": "^3.0.0",
+    "zod": "^4.3.6"
+  },
+  "keywords": [
+    "loyalty",
+    "points",
+    "rewards",
+    "tiers",
+    "referral",
+    "membership",
+    "earning-rules",
+    "redemption",
+    "mongodb",
+    "mongoose"
+  ],
+  "license": "MIT"
+}