@classytic/loyalty 0.5.0 → 0.7.0

package/CHANGELOG.md

@@ -1,231 +1,367 @@
-# 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.
+# 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.7.0
+
+### Fixed — a `UnitOfWork` yielding a non-transactional session ran the body anyway
+
+`runLoyaltyUnit` asserted `inTransaction()` on the HOST-session branch and not on
+the `unitOfWork.withTransaction` branch, so only one of the two ways a body gets
+a session was guarded. The comment above that check already stated the rule —
+"guard before the body runs, not at the first emit: a verb can mutate before it
+dispatches" — and it was applied to one branch.
+
+It matters because the balance verbs compensate by THROWING to roll an `$inc`
+back. Without a real transaction that buys nothing: `redeem` decrements a
+member's points, sees the balance go negative, throws — and the points stay
+gone while the caller is told the redemption failed. A lying `withTransaction`
+was previously caught at the first event DISPATCH, by which time the write had
+landed.
+
+3 cases in `tests/unit/unit-of-work-transaction-guard.test.ts`, asserting the
+body did NOT run — the rejection alone would pass even if it had mutated first.
+Falsified: removing the guard fails 2 of 3.
+
+### Fixed — the transaction guard must not override `allowNonTransactional`
+
+The fix above asserted `inTransaction()` unconditionally, which also made it
+wrong: `allowNonTransactional` is an explicit host opt-in (loyalty already
+warns about it at boot) for a standalone-Mongo deployment where
+`withTransaction({ allowFallback })` runs the callback with no transaction ON
+PURPOSE. The guard turned that documented degradation into a hard failure, so
+a standalone-Mongo host lost point earn / redemption / reversal entirely — a
+general rule silently defeating a specific decision, the inverse of what the
+guard exists to catch.
+
+`UnitOfWork` now states whether it may degrade, and the consent travels on the
+internal context because the same guard also runs from `dispatchLoyaltyEvent`,
+which never sees the unit of work. Absent still means no: an implementation
+that yields a bare session without saying so is still refused, and a
+host-supplied `ctx.session` has no opt-in and always asserts. Falsified both
+ways in `unit-of-work-transaction-guard.test.ts`.
+
+### Changed — peer floors raised to current
+
+- `@classytic/mongokit` `>=3.33.0` → **`>=3.38.1`**
+- `@classytic/primitives` `>=0.23.0` → **`>=0.27.0`**
+- `@classytic/repo-core` `>=0.24.0` → **`>=0.27.1`**
+- `@classytic/validation` `>=0.2.0` → **`>=0.5.0`**
+
+## [0.6.0] — 2026-08-17
+
+### Added
+- `SessionNotInTransactionError` — thrown when a host passes `ctx.session` that has no active transaction; a bare session provides no atomicity and would leave the points mutation standing if the outbox save fails
+- `ResolvedTenant` type alias (deprecated shim for `ResolvedTenantConfig` from `@classytic/repo-core/tenant`)
+
+### Changed
+- `TenantConfig` widened to `RepoTenantConfig | boolean` (was `false | PrimitivesTenantConfig`); hosts rename `field` → `tenantField` and `type` → `fieldType`
+- `in-process-bus` consolidated onto primitives `InProcessEventBus`; event catalog, dispatch, and repository types aligned
+- Schemas and repositories updated: earning-rule, redemption, tier-definition, point-transaction, referral
+- `src/index.ts` exports reorganised for tree-shaking
+
+## 1.0.0 - 2026-07-29
+
+### Changed
+- **License:** relicensed from MIT to the **Classytic Source-Available License** (Community & Commercial). Evaluation/development use remains free; production use now requires a commercial license from Classytic LLC. See `LICENSE`.
+- Major bump marks the license change; versions published before 1.0.0 remain under their original MIT terms.
+
+## 0.7.1 - 2026-07-22 (unpublished)
+
+### Changed
+- Internal: `InProcess*Bus` is now a thin subclass of `@classytic/primitives/event-infra`'s shared `InProcessEventBus` (dedup / error-isolation / close semantics unchanged); `MemoryOutboxStore` re-exported from the shared runtime where applicable. No public API, event-name, or wire-envelope change. Requires `@classytic/primitives >=0.13.0`.
+
+## [0.7.0] — unpublished (2026-07-22)
+
+### Added — engine lifecycle: `destroy()`
+
+- **`LoyaltyEngine.destroy()`** — closes the self-created
+  `InProcessLoyaltyBus` (skipped when the host injected `eventTransport`).
+- `destroy()` follows the fleet ownsBus convention (manufacturing/purchase
+  pattern): only what the engine itself created is closed; a host-injected
+  transport is the host's to close. Idempotent — a second call is a no-op.
+  Mongoose models/connection are untouched (host-owned).
+- Lifecycle coverage in `tests/integration/engine-lifecycle.test.ts`.
+
+## [0.6.0] — 2026-07-20
+
+### Changed — money contract: integer MINOR units + explicit rates, no major-unit ambiguity (BREAKING)
+
+Every monetary number in loyalty was an ambiguous major-currency float
+(unenforced), and both earning rates carried an implicit "per 1 MAJOR unit"
+basis. Aligned with `@classytic/flow@0.6.0`'s TOTAL-vs-RATE standardization
+(see flow `wiki/conventions.md` §15). Loyalty stays ambient-single-currency —
+NO currency field on any doc or API; the host owns currency.
+
+- **All money AMOUNTS are now integers in the host's minor unit** (paisa for
+  BDT), enforced by `mongooseMinorUnits()` from the new
+  **`@classytic/validation` dependency (`>=0.2.0`)**:
+  - `EarningConditions.minOrderAmount`
+  - `LoyaltyConfig.redemption.minOrderAmount` (`DEFAULT_MIN_ORDER_AMOUNT`
+    stays `0` — zero is unit-invariant)
+  - `Redemption.discountAmount`, `Redemption.initialBalance`,
+    `Redemption.remainingBalance`
+  - `TierQualification.minLifetimeSpend` (declared-only field — tier checks
+    still use lifetime POINTS; re-documented + validated, no math change)
+  - API inputs: `evaluateOrder({ orderTotal, items[].amount })` and
+    `validate`/`reserve({ orderTotal })`. `validateOrderTotal` now requires a
+    non-negative **safe integer** ("orderTotal must be a non-negative safe
+    integer (minor units)") — floats and majors fail loud.
+- **`EarningReward.amountPerPoint`** is now MINOR UNITS PER POINT (integer
+  ≥ 1, bespoke rate validator). "1 point per ৳100" = `amountPerPoint: 10000`.
+- **`EarningReward.pointsPerAmount` requires a new sibling `rateBasis`**
+  (integer minor units ≥ 1): `points = pointsPerAmount × (orderTotal /
+  rateBasis)`, rounded ONCE per the rule's `roundingMode`. The old implicit
+  "points per 1 MAJOR unit" basis was the bug being killed. Pairing enforced
+  at the schema level (pre-validate) AND by a runtime `ValidationError` guard
+  in the calculators (legacy/hand-written docs fail loud).
+- **`conversionRate` (points per 1 MAJOR unit) is REPLACED by
+  `pointValueMinor`** (integer minor units ONE point redeems for, ≥ 1) on
+  `LoyaltyConfig.program`, `ResolvedConfig`, and the `Redemption` doc snapshot.
+  `conversionRate: 10` (10 pts per ৳1) ≡ `pointValueMinor: 10` (1 pt = 10
+  paisa). `DEFAULT_CONVERSION_RATE` → `DEFAULT_POINT_VALUE_MINOR` (still `10`
+  — same economic default). Boot validation: "pointValueMinor must be a
+  positive integer (minor units per point)".
+- **Redemption math is now EXACT integer arithmetic** (no more floor-division
+  remainder): `requestedDiscountMinor = pointsToRedeem × pointValueMinor`;
+  percent cap `maxDiscountMinor = floor(orderTotal × maxRedeemPercent / 100)`
+  unchanged in shape; when capped, `actualPoints = floor(cappedDiscount /
+  pointValueMinor)` and the discount is **recomputed as `actualPoints ×
+  pointValueMinor`** — the granted discount ALWAYS equals exactly the points
+  charged (no orphaned remainder paisa; documented invariant).
+- **Event contract**: `RedemptionPayload.discountAmount` is integer minor
+  units; the Zod catalog schema now asserts `.int().nonnegative()` (Zod event
+  schemas are not tsc-checked against the TS interfaces — flow's lesson).
+
+**Migration**: clean cutover, no dual-read shim. Re-express persisted majors
+as minors (× minor-unit factor), rename `conversionRate` → `pointValueMinor`
+(config + redemption docs), and add `rateBasis` to every rule that sets
+`pointsPerAmount` (old implicit basis "per ৳1" = `rateBasis: 100`).
+
+## [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.