@classytic/revenue 2.1.0 → 2.2.0

package/dist/{settlement.repository-Ba2U17zY.mjs → settlement.repository-CfvgX3et.mjs}

@@ -1,43 +1,176 @@
 import { _ as TRANSACTION_STATUS, a as TRANSACTION_KIND, s as initialStatusFor } from "./bank-feed.enums-kYTLTTbe.mjs";
-import { n as createEvent, t as REVENUE_EVENTS } from "./event-constants-CTiDNWzc.mjs";
-import { g as SETTLEMENT_STATUS, r as SUBSCRIPTION_STATUS, w as HOLD_STATUS } from "./subscription.enums-DoIr56O6.mjs";
-import { f as SettlementNotFoundError, g as WrongTransactionKindError, h as ValidationError, m as TransactionNotFoundError, n as BankFeedImportError, p as SubscriptionNotFoundError } from "./errors-Dt46UZL_.mjs";
+import { n as createEvent, t as REVENUE_EVENTS } from "./event-constants-DM_-A57b.mjs";
+import { g as SETTLEMENT_STATUS, r as SUBSCRIPTION_STATUS, w as HOLD_STATUS } from "./subscription.enums-95othr0i.mjs";
+import { _ as WrongTransactionKindError, g as ValidationError, h as TransactionNotFoundError, m as SubscriptionNotFoundError, n as BankFeedImportError, o as MethodKindLockedError, p as SettlementNotFoundError } from "./errors-Bt5NRVMq.mjs";
 import { SETTLEMENT_STATE_MACHINE, SUBSCRIPTION_STATE_MACHINE, TRANSACTION_STATE_MACHINE, smFor } from "./core/state-machines.mjs";
-import { a as reverseTax, c as reverseCommission, n as calculateSplits, s as calculateCommission, t as calculateOrganizationPayout } from "./splits-D8XkNWgX.mjs";
-import { Repository, withTransaction } from "@classytic/mongokit";
+import { a as reverseTax, c as reverseCommission, n as calculateSplits, s as calculateCommission, t as calculateOrganizationPayout } from "./splits-CNfQj92L.mjs";
+import { Repository, repoOptionsFromCtx, withTransaction } from "@classytic/mongokit";
 
-//#region src/repositories/transaction.repository.ts
-var TransactionRepository = class extends Repository {
+//#region src/repositories/base.repository.ts
+/**
+* RevenueRepositoryBase — shared scaffolding for every revenue repo.
+*
+* Eliminates the three places ctx-threading and event-dispatch were
+* hand-rolled (transaction / subscription / settlement) and previously
+* drifted: subscription + settlement repos forgot to forward
+* `ctx.organizationId` into their inner `getById` / `update` calls,
+* which surfaced as `Missing 'organizationId' in context for 'getById'`
+* the moment a host enabled `multiTenantPlugin` (the canonical 2026-Q2
+* bug — fixed in 2.1.1).
+*
+* Two responsibilities:
+*
+*   1. **Thread request context into mongokit options.** Every domain
+*      verb that touches the DB (read or write) ends with a mongokit
+*      method whose options bag is what `multiTenantPlugin`,
+*      `softDeletePlugin`, the audit plugins, and `withTransaction`
+*      read from. {@link optsFromCtx} centralises that translation
+*      using mongokit's typed extractor — adding a new canonical field
+*      to `RevenueContext` is now a single line, not three.
+*
+*   2. **Dispatch domain events.** Outbox-save (session-bound when the
+*      caller threads a Mongoose `ClientSession`) followed by
+*      transport-publish, with isolated try/catch so a transport
+*      failure never aborts the business write. PACKAGE_RULES P8 / §5.5.
+*
+* Subclasses inject their domain-specific deps via {@link inject}; this
+* base only requires the cross-cutting trio (events / outbox / logger)
+* which every revenue repo has.
+*
+* @typeParam TDoc - The Mongoose document type the subclass operates on.
+* @typeParam TDeps - The full deps shape (must extend `BaseRevenueRepoDeps`).
+*
+* @example
+* ```ts
+* export class SubscriptionRepository extends RevenueRepositoryBase<
+*   SubscriptionDocument,
+*   SubscriptionRepoDeps
+* > {
+*   async activate(id: string, ctx: RevenueContext = {}) {
+*     const sub = await this.getById(id, this.optsFromCtx(ctx));
+*     // ...
+*     await this.dispatch(createEvent(...), ctx);
+*     return updated;
+*   }
+* }
+* ```
+*/
+/**
+* Abstract base for `TransactionRepository`, `SubscriptionRepository`,
+* `SettlementRepository`.
+*
+* Concrete subclasses MUST:
+* - declare a `Deps` interface that extends {@link BaseRevenueRepoDeps}
+* - call `super(model, plugins)` from the constructor
+* - call `inject(deps)` once during engine boot
+*
+* Subclasses SHOULD use {@link optsFromCtx} for every mongokit call
+* that takes an options bag, and {@link dispatch} for every event
+* publish.
+*/
+var RevenueRepositoryBase = class extends Repository {
+	/**
+	* Subclass-specific deps. `!` because the engine wires this once via
+	* `inject(deps)` immediately after construction; calling any domain
+	* verb before injection is a programming error and the runtime
+	* will fail-loud with `Cannot read properties of undefined`.
+	*/
 	deps;
 	constructor(model, plugins = []) {
 		super(model, plugins);
 	}
+	/**
+	* Wire engine-managed deps. Called exactly once per repository
+	* instance during {@link createRevenue} bootstrap. Subclasses with
+	* extra steps (caching, prebuilding state machine maps) override and
+	* call `super.inject(deps)`.
+	*/
 	inject(deps) {
 		this.deps = deps;
 	}
 	/**
-	* Thread `ctx.organizationId` (and future ctx fields) into mongokit
-	* options so the `multiTenantPlugin` can auto-scope filters, queries,
-	* and inserts. Merges any caller-supplied extras. Centralizing this
-	* here means every domain verb participates in scope isolation without
-	* per-call boilerplate.
+	* Translate {@link RevenueContext} into a mongokit options bag.
+	*
+	* Forwards every canonical field mongokit's bundled plugins read —
+	* `organizationId` (multiTenant), `userId` / `user` (audit),
+	* `session` (transactions), `requestId` (observability) — plus
+	* the revenue-specific `_bypassTenant` flag for platform-admin
+	* cross-org reads.
+	*
+	* Pass `extra` for caller-specific options like `throwOnNotFound`,
+	* `lean`, `populate`, `select` — the spread is `extra`-first so
+	* ctx wins on a key collision (intentional: callers shouldn't
+	* be smuggling tenant fields through `extra`).
+	*
+	* @param ctx - The request-scoped revenue context.
+	* @param extra - Additional mongokit options merged in.
 	*/
-	optsFromCtx(ctx, extra = {}) {
-		const out = { ...extra };
-		if (ctx.organizationId !== void 0) out.organizationId = ctx.organizationId;
-		if (ctx.session !== void 0) out.session = ctx.session;
+	optsFromCtx(ctx = {}, extra = {}) {
+		const out = {
+			...extra,
+			...repoOptionsFromCtx(ctx)
+		};
+		if (ctx._bypassTenant === true) out._bypassTenant = true;
 		return out;
 	}
 	/**
+	* Persist an event to the host outbox, then publish to the in-process
+	* transport. The two sides have asymmetric failure handling — see
+	* PACKAGE_RULES §P8.
+	*
+	* When `ctx.session` is set, the outbox `save` runs inside the same
+	* Mongoose transaction (true P8 session-bound write); when absent, the
+	* outbox row lands after commit — still durable via the host's relay,
+	* with only a small at-most-once window on process crash.
+	*
+	*   1. **`outbox.save` failures PROPAGATE.** If we can't durably record
+	*      the event, the caller's transaction MUST roll back so the
+	*      business doc and the event row land atomically (or neither
+	*      lands). Swallowing a save failure breaks the transactional-
+	*      outbox correctness argument — the parent doc would land while
+	*      the event vanishes.
+	*
+	*   2. **`events.publish` failures are SWALLOWED.** The host's outbox
+	*      relay re-publishes from the durable row on its next poll. Even
+	*      without an outbox, in-process subscribers shouldn't be able to
+	*      break the business operation — they're best-effort consumers.
+	*
+	* @param event - Pre-built domain event (use `createEvent(REVENUE_EVENTS.X, payload, ctx, meta)`).
+	* @param ctx - The same context that produced the business write.
+	*/
+	async dispatch(event, ctx = {}) {
+		if (this.deps.outbox) try {
+			await this.deps.outbox.save(event, ctx.session !== void 0 ? { session: ctx.session } : {});
+		} catch (err) {
+			this.deps.logger?.error("[revenue] outbox.save failed for", event.type, err);
+			throw err;
+		}
+		try {
+			await this.deps.events.publish(event);
+		} catch (err) {
+			this.deps.logger?.error("[revenue] events.publish failed for", event.type, err);
+		}
+	}
+};
+
+//#endregion
+//#region src/repositories/transaction.repository.ts
+var TransactionRepository = class extends RevenueRepositoryBase {
+	constructor(model, plugins = []) {
+		super(model, plugins);
+	}
+	/**
 	* Save an event to the host-owned outbox, session-bound when available.
 	*
-	* When `session` is passed, the outbox row commits atomically with the
-	* business write (P8 true session-bound write). When absent, the save
-	* happens after commit — still durable via the host's relay, but with a
-	* small at-most-once window on process crash.
+	* Called INSIDE a `withTransaction` body. The outbox row commits
+	* atomically with the business write (P8 true session-bound write) —
+	* if outbox.save fails, this method re-throws so `withTransaction`
+	* rolls the parent write back. Without propagation, the parent doc
+	* would commit while the event row vanishes, defeating the whole
+	* transactional-outbox correctness argument.
 	*
-	* Isolated try/catch: an outbox failure never throws out of this helper;
-	* the caller still issues a transport.publish.
+	* Logging happens before the re-throw so the failure surfaces in
+	* observability without losing the original stack trace.
 	*/
 	async saveToOutbox(event, session) {
 		if (!this.deps.outbox) return;
@@ -45,12 +178,14 @@ var TransactionRepository = class extends Repository {
 			await this.deps.outbox.save(event, session !== void 0 ? { session } : {});
 		} catch (err) {
 			this.deps.logger?.error("[revenue] outbox.save failed for", event.type, err);
+			throw err;
 		}
 	}
 	/**
 	* Publish an event to the in-process `EventTransport` after commit.
-	* Transport failure is logged — the host relay will still redeliver from
-	* the outbox, so in-process subscribers missing an event is recoverable.
+	* Transport failure is logged and swallowed — the host relay re-delivers
+	* from the durable outbox row on the next poll, so in-process
+	* subscribers missing an event is recoverable. Best-effort by design.
 	*/
 	async publishToTransport(event) {
 		try {
@@ -59,16 +194,6 @@ var TransactionRepository = class extends Repository {
 			this.deps.logger?.error("[revenue] events.publish failed for", event.type, err);
 		}
 	}
-	/**
-	* Non-transactional dispatch (used by verbs that don't open their own
-	* `withTransaction` block): outbox.save (session-bound when ctx provides
-	* one) → transport.publish. Matches arc's EventOutbox + MemoryEventTransport
-	* wiring bit-for-bit.
-	*/
-	async dispatch(event, ctx = {}) {
-		await this.saveToOutbox(event, ctx.session);
-		await this.publishToTransport(event);
-	}
 	/** Creates transaction + calls provider. Returns the created transaction doc. */
 	async createPaymentIntent(params, ctx = {}) {
 		const currency = params.currency ?? this.deps.defaultCurrency;
@@ -87,6 +212,7 @@ var TransactionRepository = class extends Repository {
 					amount: params.amount,
 					currency
 				},
+				methodKind: params.methodKind,
 				metadata: params.metadata,
 				...params.paymentData
 			});
@@ -113,6 +239,7 @@ var TransactionRepository = class extends Repository {
 			tax: 0,
 			net: params.amount - (commission?.gatewayFeeAmount ?? 0),
 			method: params.gateway,
+			methodKind: params.methodKind,
 			status: params.amount === 0 ? TRANSACTION_STATUS.VERIFIED : TRANSACTION_STATUS.PENDING,
 			gateway: gatewayData,
 			commission: commission ?? void 0,
@@ -217,6 +344,7 @@ var TransactionRepository = class extends Repository {
 				tax: reversedTax?.taxAmount ?? 0,
 				net: refundAmount - (reversedCommission?.gatewayFeeAmount ?? 0) - (reversedTax?.taxAmount ?? 0),
 				method: transaction.method,
+				methodKind: transaction.methodKind,
 				status: TRANSACTION_STATUS.VERIFIED,
 				gateway: transaction.gateway,
 				commission: reversedCommission ?? void 0,
@@ -267,10 +395,10 @@ var TransactionRepository = class extends Repository {
 			processedAt: /* @__PURE__ */ new Date(),
 			data: webhookEvent.data
 		};
-		const updated = await this.Model.findOneAndUpdate({
+		const updated = await this.findOneAndUpdate({
 			_id: transaction._id,
 			"webhook.eventId": { $ne: webhookEvent.id }
-		}, { $set: { webhook: nextWebhook } }, { returnDocument: "after" }).lean();
+		}, { $set: { webhook: nextWebhook } }, { returnDocument: "after" });
 		if (!updated) return await this.getByQuery({ _id: transaction._id }, readOpts) ?? transaction;
 		await this.dispatch(createEvent(REVENUE_EVENTS.WEBHOOK_PROCESSED, {
 			webhookType: webhookEvent.type,
@@ -354,6 +482,7 @@ var TransactionRepository = class extends Repository {
 				tax: 0,
 				net: releaseAmount,
 				method: transaction.method,
+				methodKind: transaction.methodKind,
 				status: TRANSACTION_STATUS.VERIFIED,
 				relatedTransactionId: transaction._id,
 				sourceId: transaction.sourceId,
@@ -408,6 +537,7 @@ var TransactionRepository = class extends Repository {
 				tax: 0,
 				net: s.netAmount,
 				method: transaction.method,
+				methodKind: transaction.methodKind,
 				status: TRANSACTION_STATUS.VERIFIED,
 				relatedTransactionId: transaction._id,
 				sourceId: transaction.sourceId,
@@ -432,6 +562,7 @@ var TransactionRepository = class extends Repository {
 				tax: 0,
 				net: orgPayout,
 				method: transaction.method,
+				methodKind: transaction.methodKind,
 				status: TRANSACTION_STATUS.VERIFIED,
 				relatedTransactionId: transaction._id,
 				verifiedAt: /* @__PURE__ */ new Date()
@@ -479,6 +610,7 @@ var TransactionRepository = class extends Repository {
 	*              `source` (provenance — `'plaid'`, `'ofx'`, …).
 	*/
 	async import(rows, opts, ctx = {}) {
+		if (!opts.methodKind) throw new BankFeedImportError("`opts.methodKind` is required on TransactionRepository.import() — pick the canonical PaymentMethodKind for the source (e.g. `'bank_transfer'` for Plaid/OFX, `'card'` for a Stripe balance, `'wallet'` for PayPal, `'cryptocurrency'` for an exchange).");
 		const startedAt = Date.now();
 		if (!Array.isArray(rows) || rows.length === 0) return {
 			inserted: 0,
@@ -538,6 +670,7 @@ var TransactionRepository = class extends Repository {
 				source: opts.source,
 				type: "bank_feed",
 				tags: ["bank_feed", opts.source],
+				methodKind: opts.methodKind,
 				fee: 0,
 				tax: 0,
 				net: absoluteAmount,
@@ -622,7 +755,8 @@ var TransactionRepository = class extends Repository {
 			if (page.transactions && page.transactions.length > 0) {
 				const report = await this.import(page.transactions, {
 					bankAccountId: params.bankAccountId,
-					source: providerName
+					source: providerName,
+					methodKind: params.methodKind
 				}, ctx);
 				totalImported += report.inserted;
 				totalUpdated += report.updated;
@@ -664,7 +798,8 @@ var TransactionRepository = class extends Repository {
 		});
 		return this.import(parsed.transactions, {
 			bankAccountId: upload.bankAccountId,
-			source: providerName
+			source: providerName,
+			methodKind: upload.methodKind
 		}, ctx);
 	}
 	/**
@@ -687,6 +822,7 @@ var TransactionRepository = class extends Repository {
 			tax: 0,
 			net: data.amount,
 			method: "manual",
+			methodKind: data.methodKind,
 			status: initialStatusFor(TRANSACTION_KIND.MANUAL),
 			source: "manual",
 			...data.description !== void 0 ? { description: data.description } : {},
@@ -701,6 +837,56 @@ var TransactionRepository = class extends Repository {
 		}, this.optsFromCtx(ctx));
 	}
 	/**
+	* Backfill the `methodKind` on a Transaction created with kind
+	* unknown — the canonical use case is hosted-checkout (Stripe
+	* Checkout, PayPal redirect, Razorpay Checkout) where the customer
+	* picks their payment method on the gateway's UI, AFTER the host has
+	* already created the PaymentIntent + Transaction with
+	* `methodKind: 'other'`.
+	*
+	* Call this from your verification / webhook handler once you know
+	* the customer's actual choice — e.g. inside
+	* `payment_intent.succeeded`:
+	*
+	* ```ts
+	* await transactionRepository.backfillMethodKind(
+	*   tx._id,
+	*   stripePaymentIntentToKind(event.data.object),
+	*   ctx,
+	* );
+	* ```
+	*
+	* **Guard rule.** Atomic CAS — succeeds only when the doc has
+	* `methodKind === 'other'` AND `status === 'pending'`. Any other
+	* combination throws `MethodKindLockedError` (HTTP 409): once a
+	* transaction has a specific kind (or has settled past pending),
+	* silently overwriting it would corrupt downstream analytics and
+	* accounting reports.
+	*
+	* Emits `revenue:transaction.updated` with `changedFields:
+	* ['methodKind']` so subscribers can re-bucket the row.
+	*/
+	async backfillMethodKind(transactionId, methodKind, ctx = {}) {
+		const updated = await this.findOneAndUpdate({
+			_id: transactionId,
+			methodKind: "other",
+			status: TRANSACTION_STATUS.PENDING
+		}, { $set: { methodKind } }, { returnDocument: "after" });
+		if (!updated) {
+			const existing = await this.getById(transactionId, this.optsFromCtx(ctx, { throwOnNotFound: false }));
+			if (!existing) throw new TransactionNotFoundError(transactionId);
+			throw new MethodKindLockedError(transactionId, existing.methodKind ?? "unknown", existing.status ?? "unknown");
+		}
+		await this.dispatch(createEvent(REVENUE_EVENTS.TRANSACTION_UPDATED, {
+			transaction: updated,
+			changedFields: ["methodKind"]
+		}, ctx, {
+			resource: "transaction",
+			resourceId: updated.publicId
+		}), ctx);
+		return updated;
+	}
+	/**
 	* Match a bank-feed / manual transaction to GL accounts, optionally
 	* cross-linking to an upstream payment-flow transaction.
 	*
@@ -937,20 +1123,25 @@ var TransactionRepository = class extends Repository {
 		const minAmount = filter.amount * (1 - pct);
 		const maxAmount = filter.amount * (1 + pct);
 		const targetKind = filter.kind ?? TRANSACTION_KIND.PAYMENT_FLOW;
+		const validStatuses = targetKind === TRANSACTION_KIND.PAYMENT_FLOW ? [TRANSACTION_STATUS.VERIFIED, TRANSACTION_STATUS.COMPLETED] : [TRANSACTION_STATUS.IMPORTED, TRANSACTION_STATUS.MATCHED];
+		const dateClauses = targetKind === TRANSACTION_KIND.BANK_FEED ? [{ postedDate: {
+			$gte: start,
+			$lte: end
+		} }] : [{ verifiedAt: {
+			$gte: start,
+			$lte: end
+		} }, { createdAt: {
+			$gte: start,
+			$lte: end
+		} }];
 		const query = {
 			kind: targetKind,
-			status: { $in: targetKind === TRANSACTION_KIND.PAYMENT_FLOW ? [TRANSACTION_STATUS.VERIFIED, TRANSACTION_STATUS.COMPLETED] : [TRANSACTION_STATUS.IMPORTED, TRANSACTION_STATUS.MATCHED] },
+			status: { $in: validStatuses },
 			amount: {
 				$gte: minAmount,
 				$lte: maxAmount
 			},
-			$or: [{ postedDate: {
-				$gte: start,
-				$lte: end
-			} }, { createdAt: {
-				$gte: start,
-				$lte: end
-			} }]
+			$or: dateClauses
 		};
 		if (filter.currency !== void 0) query.currency = filter.currency;
 		if (filter.counterpartyName !== void 0) query["counterparty.name"] = {
@@ -1004,41 +1195,48 @@ function escapeRegex(input) {
 //#endregion
 //#region src/repositories/subscription.repository.ts
 /**
-* SubscriptionRepository — data layer + domain verbs.
+* SubscriptionRepository — data layer + domain verbs for the recurring-
+* billing lifecycle.
+*
+* **CRUD inherited** from mongokit (via {@link RevenueRepositoryBase}):
+* `getById`, `getByQuery`, `getAll`, `create`, `update`, `delete`,
+* `findOneAndUpdate`, `count`, `exists`, `claim`, `cursor`, `updateMany`,
+* `deleteMany`. All participate in `multiTenantPlugin` scope filtering
+* when wired.
 *
-* CRUD inherited from mongokit. Domain verbs: activate, cancel, pause, resume.
+* **Domain verbs (state transitions):** `activate`, `cancel`, `pause`,
+* `resume`. Each runs the state-machine guard (`SUBSCRIPTION_STATE_MACHINE`
+* — invalid transitions throw, never silently no-op), persists the
+* resulting writes through {@link RevenueRepositoryBase.optsFromCtx} so
+* tenant scope is preserved end-to-end, then dispatches its
+* `revenue:subscription.*` event via {@link RevenueRepositoryBase.dispatch}.
 *
-* Events: each domain verb calls `this.deps.events.publish(createEvent(...))`
-* with a fully-qualified `REVENUE_EVENTS.*` name. Hosts can subscribe glob-style
-* via `revenue.events.subscribe('revenue:subscription.*', handler)` — the
-* injected transport is arc-compatible (PACKAGE_RULES §13–§14).
+* **Multi-tenant correctness.** Every internal `getById`/`update` call
+* threads `ctx.organizationId` through `optsFromCtx(ctx)`. Without this
+* threading the inner read would either throw
+* `Missing 'organizationId' in context` (when `multiTenantPlugin` is
+* required) or — worse — return another tenant's subscription matching
+* the same `_id` shape (when `required: false`). 2.1.0 had this bug; 2.1.1+
+* is correct.
+*
+* @example Activate a pending sub
+* ```ts
+* const ctx = { organizationId: 'org_42', actorId: 'user_99' };
+* const sub = await subRepo.create(
+*   { customerId: 'cust_1', planKey: 'monthly', amount: 999, currency: 'USD',
+*     status: SUBSCRIPTION_STATUS.PENDING, isActive: false },
+*   ctx,
+* );
+* await subRepo.activate(String(sub._id), {}, ctx);
+* ```
 */
-var SubscriptionRepository = class extends Repository {
-	deps;
+var SubscriptionRepository = class extends RevenueRepositoryBase {
 	constructor(model, plugins = []) {
 		super(model, plugins);
 	}
-	inject(deps) {
-		this.deps = deps;
-	}
-	/**
-	* Host-owned outbox save → in-process transport publish (PACKAGE_RULES P8).
-	* Session-bound when `ctx.session` is present (atomic outbox row write).
-	*/
-	async dispatch(event, ctx = {}) {
-		if (this.deps.outbox) try {
-			await this.deps.outbox.save(event, ctx.session !== void 0 ? { session: ctx.session } : {});
-		} catch (err) {
-			this.deps.logger?.error("[revenue] outbox.save failed for", event.type, err);
-		}
-		try {
-			await this.deps.events.publish(event);
-		} catch (err) {
-			this.deps.logger?.error("[revenue] events.publish failed for", event.type, err);
-		}
-	}
 	async activate(subscriptionId, options = {}, ctx = {}) {
-		const sub = await this.getById(subscriptionId);
+		const opts = this.optsFromCtx(ctx);
+		const sub = await this.getById(subscriptionId, opts);
 		if (!sub) throw new SubscriptionNotFoundError(subscriptionId);
 		SUBSCRIPTION_STATE_MACHINE.validate(sub.status, SUBSCRIPTION_STATUS.ACTIVE, subscriptionId);
 		const now = options.timestamp ?? /* @__PURE__ */ new Date();
@@ -1052,7 +1250,7 @@ var SubscriptionRepository = class extends Repository {
 			isActive: true,
 			activatedAt: now,
 			endDate
-		}, { throwOnNotFound: true });
+		}, this.optsFromCtx(ctx, { throwOnNotFound: true }));
 		if (!updated) throw new SubscriptionNotFoundError(subscriptionId);
 		await this.dispatch(createEvent(REVENUE_EVENTS.SUBSCRIPTION_ACTIVATED, {
 			subscription: updated,
@@ -1064,7 +1262,8 @@ var SubscriptionRepository = class extends Repository {
 		return updated;
 	}
 	async cancel(subscriptionId, options = {}, ctx = {}) {
-		const sub = await this.getById(subscriptionId);
+		const opts = this.optsFromCtx(ctx);
+		const sub = await this.getById(subscriptionId, opts);
 		if (!sub) throw new SubscriptionNotFoundError(subscriptionId);
 		SUBSCRIPTION_STATE_MACHINE.validate(sub.status, SUBSCRIPTION_STATUS.CANCELLED, subscriptionId);
 		const updates = {
@@ -1079,7 +1278,7 @@ var SubscriptionRepository = class extends Repository {
 			updates.isActive = sub.isActive;
 			delete updates.canceledAt;
 		}
-		const updated = await this.update(subscriptionId, updates, { throwOnNotFound: true });
+		const updated = await this.update(subscriptionId, updates, this.optsFromCtx(ctx, { throwOnNotFound: true }));
 		if (!updated) throw new SubscriptionNotFoundError(subscriptionId);
 		await this.dispatch(createEvent(REVENUE_EVENTS.SUBSCRIPTION_CANCELLED, {
 			subscription: updated,
@@ -1092,7 +1291,8 @@ var SubscriptionRepository = class extends Repository {
 		return updated;
 	}
 	async pause(subscriptionId, options = {}, ctx = {}) {
-		const sub = await this.getById(subscriptionId);
+		const opts = this.optsFromCtx(ctx);
+		const sub = await this.getById(subscriptionId, opts);
 		if (!sub) throw new SubscriptionNotFoundError(subscriptionId);
 		SUBSCRIPTION_STATE_MACHINE.validate(sub.status, SUBSCRIPTION_STATUS.PAUSED, subscriptionId);
 		const updated = await this.update(subscriptionId, {
@@ -1100,7 +1300,7 @@ var SubscriptionRepository = class extends Repository {
 			isActive: false,
 			pausedAt: /* @__PURE__ */ new Date(),
 			pauseReason: options.reason
-		}, { throwOnNotFound: true });
+		}, this.optsFromCtx(ctx, { throwOnNotFound: true }));
 		if (!updated) throw new SubscriptionNotFoundError(subscriptionId);
 		await this.dispatch(createEvent(REVENUE_EVENTS.SUBSCRIPTION_PAUSED, {
 			subscription: updated,
@@ -1112,7 +1312,8 @@ var SubscriptionRepository = class extends Repository {
 		return updated;
 	}
 	async resume(subscriptionId, options = {}, ctx = {}) {
-		const sub = await this.getById(subscriptionId);
+		const opts = this.optsFromCtx(ctx);
+		const sub = await this.getById(subscriptionId, opts);
 		if (!sub) throw new SubscriptionNotFoundError(subscriptionId);
 		SUBSCRIPTION_STATE_MACHINE.validate(sub.status, SUBSCRIPTION_STATUS.ACTIVE, subscriptionId);
 		const updates = {
@@ -1123,7 +1324,7 @@ var SubscriptionRepository = class extends Repository {
 			const pauseDuration = Date.now() - sub.pausedAt.getTime();
 			updates.endDate = new Date(sub.endDate.getTime() + pauseDuration);
 		}
-		const updated = await this.update(subscriptionId, updates, { throwOnNotFound: true });
+		const updated = await this.update(subscriptionId, updates, this.optsFromCtx(ctx, { throwOnNotFound: true }));
 		if (!updated) throw new SubscriptionNotFoundError(subscriptionId);
 		await this.dispatch(createEvent(REVENUE_EVENTS.SUBSCRIPTION_RESUMED, {
 			subscription: updated,
@@ -1139,45 +1340,34 @@ var SubscriptionRepository = class extends Repository {
 //#endregion
 //#region src/repositories/settlement.repository.ts
 /**
-* SettlementRepository — data layer + domain verbs.
+* SettlementRepository — payouts to recipients (organizations, vendors,
+* affiliates).
 *
-* CRUD inherited from mongokit. Domain verbs: schedule, processPending, complete, fail.
+* **CRUD inherited** via {@link RevenueRepositoryBase}. **Domain verbs:**
+* `schedule`, `processPending`, `complete`, `fail`. State machine:
+* `pending → processing → completed | failed`; `failed` with
+* `retry: true` resets to `pending` with a delayed `scheduledAt`.
 *
-* Events are published via the injected `events` transport (arc-compatible).
-* Hosts subscribe glob-style via `revenue.events.subscribe('revenue:settlement.*', h)`.
-* See PACKAGE_RULES §13–§14.
+* **Multi-tenant correctness.** Every read/write threads `ctx` through
+* {@link RevenueRepositoryBase.optsFromCtx} so `multiTenantPlugin`
+* scope filters apply. 2.1.0 had several `getById`/`update` calls that
+* dropped ctx — fixed in 2.1.1+.
+*
+* Bridges (`ledger`, `notification`) fire on `complete()` so a host
+* can pin double-entry book-keeping or push a "you got paid" email
+* without the repo knowing about either subsystem.
 */
-var SettlementRepository = class extends Repository {
-	deps;
+var SettlementRepository = class extends RevenueRepositoryBase {
 	constructor(model, plugins = []) {
 		super(model, plugins);
 	}
-	inject(deps) {
-		this.deps = deps;
-	}
-	/**
-	* Host-owned outbox save → in-process transport publish (PACKAGE_RULES P8).
-	* Session-bound when `ctx.session` is present (atomic outbox row write).
-	*/
-	async dispatch(event, ctx = {}) {
-		if (this.deps.outbox) try {
-			await this.deps.outbox.save(event, ctx.session !== void 0 ? { session: ctx.session } : {});
-		} catch (err) {
-			this.deps.logger?.error("[revenue] outbox.save failed for", event.type, err);
-		}
-		try {
-			await this.deps.events.publish(event);
-		} catch (err) {
-			this.deps.logger?.error("[revenue] events.publish failed for", event.type, err);
-		}
-	}
 	async schedule(params, ctx = {}) {
 		const settlement = await this.create({
 			...params,
 			status: SETTLEMENT_STATUS.PENDING,
 			scheduledAt: params.scheduledAt ?? /* @__PURE__ */ new Date(),
 			retryCount: 0
-		});
+		}, this.optsFromCtx(ctx));
 		await this.dispatch(createEvent(REVENUE_EVENTS.SETTLEMENT_SCHEDULED, {
 			settlement,
 			scheduledAt: settlement.scheduledAt
@@ -1198,7 +1388,7 @@ var SettlementRepository = class extends Repository {
 			filters: query,
 			limit: options.limit ?? 50,
 			sort: { scheduledAt: 1 }
-		})).data ?? [];
+		}, this.optsFromCtx(ctx))).data ?? [];
 		if (options.dryRun) return {
 			processed: pending.length,
 			succeeded: 0,
@@ -1206,7 +1396,7 @@ var SettlementRepository = class extends Repository {
 			settlements: pending,
 			errors: []
 		};
-		const results = {
+		const out = {
 			processed: 0,
 			succeeded: 0,
 			failed: 0,
@@ -1219,9 +1409,9 @@ var SettlementRepository = class extends Repository {
 				await this.update(settlement._id, {
 					status: SETTLEMENT_STATUS.PROCESSING,
 					processedAt: /* @__PURE__ */ new Date()
-				});
-				results.succeeded++;
-				results.settlements.push(settlement);
+				}, this.optsFromCtx(ctx));
+				out.succeeded++;
+				out.settlements.push(settlement);
 				await this.dispatch(createEvent(REVENUE_EVENTS.SETTLEMENT_PROCESSING, {
 					settlement,
 					processedAt: /* @__PURE__ */ new Date()
@@ -1230,18 +1420,19 @@ var SettlementRepository = class extends Repository {
 					resourceId: settlement.publicId
 				}), ctx);
 			} catch (err) {
-				results.failed++;
-				results.errors.push({
+				out.failed++;
+				out.errors.push({
 					settlementId: settlement._id,
 					error: err
 				});
 			}
-			results.processed++;
+			out.processed++;
 		}
-		return results;
+		return out;
 	}
 	async complete(settlementId, details = {}, ctx = {}) {
-		const settlement = await this.getById(settlementId);
+		const opts = this.optsFromCtx(ctx);
+		const settlement = await this.getById(settlementId, opts);
 		if (!settlement) throw new SettlementNotFoundError(settlementId);
 		SETTLEMENT_STATE_MACHINE.validate(settlement.status, SETTLEMENT_STATUS.COMPLETED, settlementId);
 		const updates = {
@@ -1263,7 +1454,7 @@ var SettlementRepository = class extends Repository {
 			transactionHash: details.transactionHash,
 			transferredAt: details.transferredAt ?? /* @__PURE__ */ new Date()
 		};
-		const updated = await this.update(settlementId, updates, { throwOnNotFound: true });
+		const updated = await this.update(settlementId, updates, this.optsFromCtx(ctx, { throwOnNotFound: true }));
 		if (!updated) throw new SettlementNotFoundError(settlementId);
 		await this.deps.bridges.ledger?.onSettlementCompleted?.(updated, ctx);
 		await this.deps.bridges.notification?.onSettlementCompleted?.(updated, ctx);
@@ -1277,7 +1468,8 @@ var SettlementRepository = class extends Repository {
 		return updated;
 	}
 	async fail(settlementId, reason, options = {}, ctx = {}) {
-		const settlement = await this.getById(settlementId);
+		const opts = this.optsFromCtx(ctx);
+		const settlement = await this.getById(settlementId, opts);
 		if (!settlement) throw new SettlementNotFoundError(settlementId);
 		if (options.retry) await this.update(settlementId, {
 			status: SETTLEMENT_STATUS.PENDING,
@@ -1285,7 +1477,7 @@ var SettlementRepository = class extends Repository {
 			failureReason: reason,
 			failureCode: options.code,
 			scheduledAt: new Date(Date.now() + 36e5)
-		});
+		}, opts);
 		else {
 			SETTLEMENT_STATE_MACHINE.validate(settlement.status, SETTLEMENT_STATUS.FAILED, settlementId);
 			await this.update(settlementId, {
@@ -1293,9 +1485,9 @@ var SettlementRepository = class extends Repository {
 				failedAt: /* @__PURE__ */ new Date(),
 				failureReason: reason,
 				failureCode: options.code
-			});
+			}, opts);
 		}
-		const updated = await this.getById(settlementId);
+		const updated = await this.getById(settlementId, opts);
 		await this.dispatch(createEvent(REVENUE_EVENTS.SETTLEMENT_FAILED, {
 			settlement: updated,
 			reason,