@classytic/loyalty 0.4.0 → 0.6.0

package/dist/{index-D_5Ojc2c.d.mts → index-YUFamhDk.d.mts}

@@ -1,25 +1,14 @@
-import { o as LoyaltyContext } from "./index-YSsi4e_G.mjs";
-import { DomainEvent, DomainEvent as DomainEvent$1, EventHandler, EventHandler as EventHandler$1, EventTransport, EventTransport as EventTransport$1 } from "@classytic/primitives/events";
+import { o as LoyaltyContext } from "./index-Cp_sXNpG.mjs";
+import { InProcessEventBus, InProcessEventBusOptions } from "@classytic/primitives/event-infra";
+import { DomainEvent, DomainEvent as DomainEvent$1, EventHandler, EventTransport as EventTransport$1 } from "@classytic/primitives/events";
 import { z } from "zod";
-
 //#region src/events/helpers.d.ts
 declare function createEvent$1<T>(type: string, payload: T, ctx?: LoyaltyContext, meta?: Partial<DomainEvent['meta']>): DomainEvent<T>;
 //#endregion
 //#region src/events/in-process-bus.d.ts
-interface InProcessLoyaltyBusOptions {
-  /** Logger for handler errors (default: console). */
-  logger?: {
-    error: (msg: string, ...args: unknown[]) => void;
-  };
-}
-declare class InProcessLoyaltyBus implements EventTransport {
-  readonly name = "in-process-loyalty";
-  private handlers;
-  private logger;
+type InProcessLoyaltyBusOptions = InProcessEventBusOptions;
+declare class InProcessLoyaltyBus extends InProcessEventBus {
   constructor(options?: InProcessLoyaltyBusOptions);
-  publish(event: DomainEvent): Promise<void>;
-  subscribe(pattern: string, handler: EventHandler): Promise<() => void>;
-  close(): Promise<void>;
 }
 //#endregion
 //#region src/events/loyalty-event-catalog.d.ts
@@ -318,6 +307,7 @@ interface RedemptionPayload {
   externalId: string;
   redemptionId: string;
   points: number;
+  /** Discount in integer minor units (paisa for BDT). */
   discountAmount: number;
   ownerType: string;
   ownerId: string;
@@ -397,4 +387,4 @@ interface LoyaltyEventMap {
 }
 type LoyaltyEventPayload<E extends LoyaltyEventName> = LoyaltyEventMap[E];
 //#endregion
-export { PointsExpired as A, ReferralRewarded as B, MemberDeactivated as C, MultiTierReferralAwarded as D, MemberSuspended as E, RedemptionReserved as F, TierUpgraded as G, TierGraceStarted as H, RedemptionReversed as I, InProcessLoyaltyBusOptions as J, loyaltyEventDefinitions as K, ReferralApproved as L, PointsRedeemed as M, RedemptionConfirmed as N, PointsAdjusted as O, RedemptionReleased as P, ReferralRecorded as R, LoyaltyEventSchema as S, MemberReactivated as T, TierOverrideCleared as U, TierDowngraded as V, TierOverrideExpired as W, createEvent$1 as Y, TierChangedPayload as _, LoyaltyEventMap as a, LoyaltyEventDefinition as b, LoyaltyEvents as c, PointsAdjustedPayload as d, PointsEarnedPayload as f, ReferralPayload as g, RedemptionReversedPayload as h, CampaignAwardedPayload as i, PointsExpiringSoon as j, PointsEarned as k, MemberLifecyclePayload as l, RedemptionPayload as m, EventHandler$1 as n, LoyaltyEventName as o, PointsExpiredPayload as p, InProcessLoyaltyBus as q, EventTransport$1 as r, LoyaltyEventPayload as s, DomainEvent$1 as t, MultiTierReferralAwardedPayload as u, TierOverrideLifecyclePayload as v, MemberEnrolled as w, LoyaltyEventPayloadOf as x, CampaignAwarded as y, ReferralRejected as z };
+export { PointsExpired as A, ReferralRewarded as B, MemberDeactivated as C, MultiTierReferralAwarded as D, MemberSuspended as E, RedemptionReserved as F, TierUpgraded as G, TierGraceStarted as H, RedemptionReversed as I, InProcessLoyaltyBusOptions as J, loyaltyEventDefinitions as K, ReferralApproved as L, PointsRedeemed as M, RedemptionConfirmed as N, PointsAdjusted as O, RedemptionReleased as P, ReferralRecorded as R, LoyaltyEventSchema as S, MemberReactivated as T, TierOverrideCleared as U, TierDowngraded as V, TierOverrideExpired as W, createEvent$1 as Y, TierChangedPayload as _, LoyaltyEventMap as a, LoyaltyEventDefinition as b, LoyaltyEvents as c, PointsAdjustedPayload as d, PointsEarnedPayload as f, ReferralPayload as g, RedemptionReversedPayload as h, CampaignAwardedPayload as i, PointsExpiringSoon as j, PointsEarned as k, MemberLifecyclePayload as l, RedemptionPayload as m, EventHandler as n, LoyaltyEventName as o, PointsExpiredPayload as p, InProcessLoyaltyBus as q, EventTransport$1 as r, LoyaltyEventPayload as s, DomainEvent$1 as t, MultiTierReferralAwardedPayload as u, TierOverrideLifecyclePayload as v, MemberEnrolled as w, LoyaltyEventPayloadOf as x, CampaignAwarded as y, ReferralRejected as z };

package/dist/index.d.mts

@@ -1,13 +1,13 @@
-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-YSsi4e_G.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-Dtun1duw.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-D_5Ojc2c.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-Dngaj21_.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-Cp_sXNpG.mjs";
+import { t as NotificationAdapter } from "./notification.port-wY4IKimz.mjs";
+import { c as ResolvedConfig, i as LoyaltyShape, l as ResolvedTenant, n as LoyaltyModelName, r as LoyaltyRuntime } from "./config-CtkGj3xZ.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-YUFamhDk.mjs";
+import { n as LoyaltyModels, r as defineLoyaltyModels, t as DefineLoyaltyModelsConfig } from "./index-D6GvuvmF.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-CR2k7jQ8.mjs";
+import { Connection } from "mongoose";
 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
@@ -122,6 +122,25 @@ declare class UnmanagedSessionError extends LoyaltyError {
   readonly status = 400;
   constructor();
 }
+/**
+ * A host passed `ctx.session`, but that session has no ACTIVE transaction.
+ *
+ * A bare `startSession()` provides NO atomicity — every write inside it
+ * commits independently. Accepting it as proof of a unit of work is the
+ * silent-permissiveness failure in its purest form: loyalty then saves the
+ * outbox row "in-session" and applies the balance `$inc` "in-session", and
+ * if the outbox save fails the balance mutation still stands with no ledger
+ * row behind it. Nothing throws; the points are simply wrong.
+ *
+ * `session.inTransaction()` is the driver's own answer, so this check cannot
+ * drift from what MongoDB actually thinks. `@classytic/access` refuses
+ * exactly this at `entitlement.repository.ts` — same rule, same reason.
+ */
+declare class SessionNotInTransactionError extends LoyaltyError {
+  readonly code = "loyalty.transaction.session_not_in_transaction";
+  readonly status = 409;
+  constructor();
+}
 /**
  * The backend doesn't declare the runtime capabilities loyalty's
  * transactional verbs require (earn / adjust / reserve / confirm / release /
@@ -132,7 +151,16 @@ declare class UnmanagedSessionError extends LoyaltyError {
 declare class LoyaltyCapabilityError extends LoyaltyError {
   readonly code = "loyalty.engine.missing_capabilities";
   readonly status = 500;
-  constructor(missing: readonly string[]);
+  /**
+   * `true` when the backend never ANSWERED (bound before the connection
+   * opened, a driver exposing no topology) rather than answering "no". Both
+   * refuse — an unobserved outcome is never a positive one (AGENTS.md FAIL
+   * LOUD rule 3) — but the operator's fix differs, so the message must.
+   */
+  readonly indeterminate: boolean;
+  constructor(missing: readonly string[], opts?: {
+    indeterminate?: boolean;
+  });
 }
 //#endregion
 //#region src/events/dispatch.d.ts
@@ -155,31 +183,34 @@ declare function flushPendingLoyaltyEvents(events: EventTransport$1 | undefined,
 } | undefined): Promise<void>;
 //#endregion
 //#region src/index.d.ts
-declare function resolveConfig(config: LoyaltyConfig): ResolvedConfig;
-/**
- * LoyaltyEngine -- repositories + arc-compatible event transport.
- *
- * Domain verbs live on the repositories themselves (`engine.repositories.member.enroll(...)`,
- * `engine.repositories.pointTransaction.earnPoints(...)`, etc.). There is no separate
- * service layer. See PACKAGE_RULES S1-S3.
- *
- * `events` is structurally identical to `@classytic/arc`'s `EventTransport`.
- * Hosts can pass any arc transport (Memory/Redis/Kafka) via `eventTransport`
- * and subscribe glob-style:
- *
- *     const loyalty = createLoyaltyEngine({
- *       mongoose,
- *       eventTransport: new RedisEventTransport({ url }),
- *     });
- *
- *     await loyalty.events.subscribe('loyalty.points.*', handler);
- */
+declare function resolveConfig(config: LoyaltyShape): ResolvedConfig;
 interface LoyaltyEngine {
   models: LoyaltyModels;
   repositories: LoyaltyRepositories;
   events: EventTransport$1;
+  /** Build/align indexes. Call once per deploy when booted `autoIndex: false`. */
   syncIndexes(): Promise<void>;
+  /**
+   * Release resources owned by this engine. Closes the event bus ONLY when the
+   * engine created it itself (`InProcessLoyaltyBus`); a host-injected
+   * `eventTransport` is the host's to close. Idempotent.
+   */
+  close(): Promise<void>;
+}
+interface LoyaltyBlueprint {
+  readonly id: 'loyalty';
+  /** The model names this blueprint registers — known without a connection. */
+  readonly modelNames: readonly string[];
+  /**
+   * Compile + register the models on `connection`, wire the engine, verify
+   * capabilities. Synchronous: loyalty's construction performs no async work.
+   */
+  bind(connection: Connection, runtime?: LoyaltyRuntime): LoyaltyEngine;
 }
-declare function createLoyaltyEngine(config: LoyaltyConfig): LoyaltyEngine;
+/**
+ * Describe the loyalty engine. Pure — registers no model, builds no schema,
+ * performs no I/O. Config is resolved and validated here.
+ */
+declare function defineLoyalty(shape?: LoyaltyShape): LoyaltyBlueprint;
 //#endregion
-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 };
+export { type AdjustPointsInput, type BalanceSummary, CircularReferralError, type CreateEarningRuleInput, type CreateTierInput, type DefineLoyaltyModelsConfig, type DomainEvent, DuplicateReferralError, type EarnPointsInput, type EarningResult, type EarningRule, EarningRuleRepository, type EnrollInput, type EventHandler, type EventTransport, InProcessLoyaltyBus, type InProcessLoyaltyBusOptions, InsufficientPointsError, LoyaltyBlueprint, LoyaltyCapabilityError, type LoyaltyContext, LoyaltyEngine, type LoyaltyEventDefinition, type LoyaltyEventMap, type LoyaltyEventName, type LoyaltyEventPayload, type LoyaltyEventPayloadOf, type LoyaltyEventSchema, LoyaltyEvents, type LoyaltyModelName, type LoyaltyModels, type LoyaltyRepositories, type LoyaltyRuntime, type LoyaltyShape, 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, SessionNotInTransactionError, TenantIsolationError, type TierChangedPayload, type TierDefinition, TierDefinitionRepository, TierDowngraded, type TierEvaluation, TierGraceStarted, TierNotFoundError, TierUpgraded, type UnitOfWork, UnmanagedSessionError, type UpdateEarningRuleInput, type UpdateTierInput, ValidationError, createEvent, defineLoyalty, defineLoyaltyModels, flushPendingLoyaltyEvents, loyaltyEventDefinitions, resolveConfig };

package/dist/index.mjs

@@ -1,35 +1,18 @@
-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 { 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";
-import { withTransaction } from "@classytic/mongokit";
+import "./constants-DOPBh6kt.mjs";
+import { C as SessionNotInTransactionError, D as ValidationError, E as UnmanagedSessionError, S as SelfReferralError, T as TierNotFoundError, _ 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 TenantIsolationError, x as RuleNotFoundError, y as ReferralLimitExceededError } from "./repositories-B676z4bE.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-BLjg3uLA.mjs";
+import { t as defineLoyaltyModels } from "./models-weWqS5Bc.mjs";
+import { n as createEvent, t as LoyaltyEvents } from "./loyalty-events-DXirolM_.mjs";
+import { transactionResolutionOf, withTransaction } from "@classytic/mongokit";
 import { isValidTimeZone } from "@classytic/primitives/timezone";
+import { assertNoLegacyTenantKeys, resolveTenantConfig } from "@classytic/repo-core/tenant";
 //#region src/index.ts
 function resolveConfig(config) {
-	let tenant;
-	if (config.tenant === false) tenant = {
-		enabled: false,
-		tenantField: DEFAULT_TENANT_FIELD,
-		fieldType: DEFAULT_TENANT_TYPE,
-		contextKey: DEFAULT_TENANT_FIELD
-	};
-	else if (config.tenant === void 0) tenant = {
-		enabled: true,
-		tenantField: DEFAULT_TENANT_FIELD,
-		fieldType: DEFAULT_TENANT_TYPE,
-		contextKey: DEFAULT_TENANT_FIELD
-	};
-	else tenant = {
-		enabled: true,
-		tenantField: config.tenant.tenantField ?? "organizationId",
-		fieldType: config.tenant.fieldType ?? "objectId",
-		contextKey: config.tenant.contextKey ?? config.tenant.tenantField ?? "organizationId",
-		...config.tenant.ref ? { ref: config.tenant.ref } : {}
-	};
+	const tenant = resolveTenantConfig(config.tenant);
+	if (tenant.strategy === "custom") throw new Error("[loyalty] tenant.strategy 'custom' is unsupported: loyalty repositories require one concrete tenant field");
 	const resolved = {
 		programId: config.program?.id ?? "default",
-		conversionRate: config.program?.conversionRate ?? 10,
+		pointValueMinor: config.program?.pointValueMinor ?? 10,
 		redemption: {
 			minPoints: config.redemption?.minPoints ?? 0,
 			minOrderAmount: config.redemption?.minOrderAmount ?? 0,
@@ -54,12 +37,14 @@ function resolveConfig(config) {
 		tenant
 	};
 	if (config.timezone !== void 0 && !isValidTimeZone(config.timezone)) throw new ValidationError(`Invalid IANA timezone: '${config.timezone}'`);
-	if (resolved.conversionRate <= 0) throw new ValidationError("conversionRate must be positive");
+	if (!Number.isSafeInteger(resolved.pointValueMinor) || resolved.pointValueMinor <= 0) throw new ValidationError("pointValueMinor must be a positive integer (minor units per point)");
 	if (resolved.referral.codeLength < 4) throw new ValidationError("referral codeLength must be >= 4");
 	if (resolved.redemption.maxRedeemPercent < 0 || resolved.redemption.maxRedeemPercent > 100) throw new ValidationError("maxRedeemPercent must be between 0 and 100");
 	return resolved;
 }
 var MongoUnitOfWork = class {
+	connection;
+	allowFallback;
 	constructor(connection, allowFallback) {
 		this.connection = connection;
 		this.allowFallback = allowFallback;
@@ -68,34 +53,96 @@ var MongoUnitOfWork = class {
 		return withTransaction(this.connection, cb, this.allowFallback ? { allowFallback: true } : {});
 	}
 };
-function createLoyaltyEngine(config) {
-	const resolvedConfig = resolveConfig(config);
-	const models = createModels(config.mongoose, resolvedConfig.tenant, config.indexes, config.autoIndex, config.collectionPrefix, config.forceRecreate);
-	const unitOfWork = new MongoUnitOfWork(config.mongoose, config.allowNonTransactional ?? false);
-	const events = config.eventTransport ?? new InProcessLoyaltyBus();
-	const repositories = createRepositories({
-		models,
-		plugins: config.plugins,
+/**
+* Describe the loyalty engine. Pure — registers no model, builds no schema,
+* performs no I/O. Config is resolved and validated here.
+*/
+function defineLoyalty(shape = {}) {
+	assertNoLegacyTenantKeys(shape, "defineLoyalty", [["tenantFieldType", "tenant.fieldType"]]);
+	const resolvedConfig = resolveConfig(shape);
+	const modelBlueprint = defineLoyaltyModels({
 		tenant: resolvedConfig.tenant,
-		config: resolvedConfig,
-		events,
-		outbox: config.outbox,
-		notifications: config.notifications ?? null,
-		unitOfWork
+		indexes: shape.indexes,
+		autoIndex: shape.autoIndex,
+		collectionPrefix: shape.collectionPrefix,
+		forceRecreate: shape.forceRecreate
 	});
-	if (!config.allowNonTransactional) {
-		const caps = repositories.pointTransaction.capabilities;
-		if (!caps) throw new LoyaltyCapabilityError(["capabilities descriptor (repo-core 0.6 / mongokit 3.16+) — backend declares none"]);
-		if (caps.transactions !== true) throw new LoyaltyCapabilityError(["transactions"]);
-	}
 	return {
-		models,
-		repositories,
-		events,
-		async syncIndexes() {
-			await Promise.all(Object.values(models).map((m) => m.createIndexes()));
+		id: "loyalty",
+		modelNames: modelBlueprint.modelNames,
+		bind(connection, runtime = {}) {
+			/**
+			* VERIFY (boot gate) — an injected outbox MUST enlist `ctx.session`.
+			*
+			* Checked FIRST, before the model blueprint binds: a cheaper error should report
+			* before a costlier one, and a bind that throws here must not have already mutated
+			* the connection's model registry.
+			*
+			* `OutboxWriteOptions.session` is best-effort BY CONTRACT (see
+			* `@classytic/primitives/outbox`) — "stores may ignore fields they don't support".
+			* A hand-rolled host store therefore satisfies `OutboxStore` structurally, compiles,
+			* runs, and persists the event row OUTSIDE the caller's transaction.
+			*
+			* Points are STORED VALUE, so that lands on the worst path this kernel has.
+			* `earn` / `redeem` / `reverse` `$inc` the member balance and insert the ledger row
+			* in ONE transaction while `dispatchLoyaltyEvent` saves the event in-session
+			* (`events/dispatch.ts`), so the row must vanish with them on rollback. A store that
+			* drops the session emits `loyalty.points.earned` for a balance that rolled back —
+			* a tier recalculation or a notification then credits a customer with points the
+			* ledger never recorded. Nothing throws.
+			*
+			* `dispatch.ts` treats an outbox as licence for "durable-relay-only mode" (a bare
+			* host session with no PENDING_EVENTS queue is legal *because* the row is assumed to
+			* commit with the host transaction) — that assumption is exactly what this verifies.
+			* `UnmanagedSessionError` guards the OPPOSITE hole (session, NO outbox) and cannot
+			* see this one: the store is present and `save()` resolves.
+			*
+			* NOT waived by `allowNonTransactional` — that opts into standalone-Mongo partial
+			* writes, a different requirement entirely.
+			*
+			* `!== true`, not `=== false`: a hand-rolled store has the flag ABSENT.
+			*/
+			if (runtime.outbox && runtime.outbox.transactionalSave !== true) throw new LoyaltyCapabilityError(["outbox.transactionalSave (the configured OutboxStore does not declare that save() enlists ctx.session — see @classytic/primitives/outbox)"]);
+			const models = modelBlueprint.bind(connection);
+			const allowNonTransactional = runtime.allowNonTransactional ?? false;
+			const unitOfWork = new MongoUnitOfWork(connection, allowNonTransactional);
+			const ownsBus = runtime.eventTransport === void 0;
+			const events = runtime.eventTransport ?? new InProcessLoyaltyBus();
+			const repositories = createRepositories({
+				models,
+				plugins: runtime.plugins,
+				tenant: resolvedConfig.tenant,
+				config: resolvedConfig,
+				events,
+				outbox: runtime.outbox,
+				notifications: runtime.notifications ?? null,
+				unitOfWork
+			});
+			{
+				const caps = repositories.pointTransaction.capabilities;
+				if (!caps) throw new LoyaltyCapabilityError(["capabilities descriptor (repo-core 0.6 / mongokit 3.16+) — backend declares none"]);
+				if (caps.transactions !== true) {
+					const indeterminate = transactionResolutionOf(caps) === "unknown";
+					if (allowNonTransactional) (runtime.logger ?? console).warn?.(`[loyalty] the backend ${indeterminate ? "could NOT be confirmed to support" : "does NOT support"} transactions. allowNonTransactional=true: point earn / redemption / reversal run WITHOUT atomicity — a crash mid-verb can leave a balance no transaction explains. Development only.`);
+					else throw new LoyaltyCapabilityError(["transactions"], { indeterminate });
+				}
+			}
+			let closed = false;
+			return {
+				models,
+				repositories,
+				events,
+				async syncIndexes() {
+					await Promise.all(Object.values(models).map((m) => m.createIndexes()));
+				},
+				async close() {
+					if (closed) return;
+					closed = true;
+					if (ownsBus) await events.close?.();
+				}
+			};
 		}
 	};
 }
 //#endregion
-export { CircularReferralError, DuplicateReferralError, EarningRuleRepository, InProcessLoyaltyBus, InsufficientPointsError, LoyaltyCapabilityError, LoyaltyEvents, MemberAlreadyEnrolledError, MemberDeactivated, MemberEnrolled, MemberInactiveError, MemberNotFoundError, MemberReactivated, MemberRepository, MemberSuspended, PENDING_EVENTS, PointTransactionRepository, PointsAdjusted, PointsEarned, PointsExpired, PointsExpiringSoon, PointsRedeemed, RedemptionConfirmed, RedemptionExpiredError, RedemptionNotFoundError, RedemptionReleased, RedemptionRepository, RedemptionReserved, ReferralApproved, ReferralLimitExceededError, ReferralNotFoundError, ReferralRecorded, ReferralRejected, ReferralRepository, ReferralRewarded, RuleNotFoundError, SelfReferralError, TenantIsolationError, TierDefinitionRepository, TierDowngraded, TierGraceStarted, TierNotFoundError, TierUpgraded, UnmanagedSessionError, ValidationError, createEvent, createLoyaltyEngine, flushPendingLoyaltyEvents, loyaltyEventDefinitions, resolveConfig };
+export { CircularReferralError, DuplicateReferralError, EarningRuleRepository, InProcessLoyaltyBus, InsufficientPointsError, LoyaltyCapabilityError, LoyaltyEvents, MemberAlreadyEnrolledError, MemberDeactivated, MemberEnrolled, MemberInactiveError, MemberNotFoundError, MemberReactivated, MemberRepository, MemberSuspended, PENDING_EVENTS, PointTransactionRepository, PointsAdjusted, PointsEarned, PointsExpired, PointsExpiringSoon, PointsRedeemed, RedemptionConfirmed, RedemptionExpiredError, RedemptionNotFoundError, RedemptionReleased, RedemptionRepository, RedemptionReserved, ReferralApproved, ReferralLimitExceededError, ReferralNotFoundError, ReferralRecorded, ReferralRejected, ReferralRepository, ReferralRewarded, RuleNotFoundError, SelfReferralError, SessionNotInTransactionError, TenantIsolationError, TierDefinitionRepository, TierDowngraded, TierGraceStarted, TierNotFoundError, TierUpgraded, UnmanagedSessionError, ValidationError, createEvent, defineLoyalty, defineLoyaltyModels, flushPendingLoyaltyEvents, loyaltyEventDefinitions, resolveConfig };