@cosmicdrift/kumiko-samples 0.363.0 → 0.364.0

package/packages/bundled-features/src/billing-foundation/consumer-protection/termination-record.ts

@@ -35,6 +35,7 @@ import type { ConsumerProtectionOptions, ResolvedBillingFoundationOptions } from
 import { CONSENT_LOCALES, FALLBACK_CONSENT_LOCALE } from "./consent-locale.js";
 import { notifyOperator } from "./termination-notify.js";
 import type { OperatorNoticeReason } from "./termination-texts.js";
+import { isWithinWithdrawalPeriod } from "./withdrawal-period.js";
 
 const REQUESTED_CANCEL_TIMINGS = [
   SubscriptionCancelTimings.periodEnd,
@@ -74,6 +75,8 @@ export type RecordContractTerminationResult = {
     OperatorNoticeReason,
     "provider_cannot_cancel" | "provider_error" | "no_active_subscription"
   > | null;
+  /** An account withdrawal arrived after the period: cancelled at period end instead. */
+  readonly withdrawalPeriodExpired: boolean;
 };
 
 export const recordUnmatchedContractTerminationSchema = z
@@ -210,14 +213,19 @@ export function createRecordContractTerminationHandler(
             effectiveAtIso: alreadyRecorded.effectiveAtIso,
             providerCancel: alreadyRecorded.providerCancel,
             noticeReason: null,
+            withdrawalPeriodExpired: false,
           } satisfies RecordContractTerminationResult,
         };
       }
 
+      const withdrawalPeriodExpired =
+        payload.declarationType === "withdrawal" &&
+        payload.when === SubscriptionCancelTimings.immediately &&
+        !isWithinWithdrawalPeriod(stream.events, options.now());
       const { providerCancel, effectiveAtIso, noticeReason } = await cancelAtProvider(
         ctx,
         tenantId,
-        payload.when,
+        withdrawalPeriodExpired ? SubscriptionCancelTimings.periodEnd : payload.when,
         receivedAtIso,
       );
 
@@ -260,6 +268,7 @@ export function createRecordContractTerminationHandler(
           effectiveAtIso,
           providerCancel,
           noticeReason,
+          withdrawalPeriodExpired,
         } satisfies RecordContractTerminationResult,
       };
     },

package/packages/bundled-features/src/billing-foundation/consumer-protection/termination-request.ts

@@ -33,10 +33,10 @@ import type { ConsumerProtectionOptions, ResolvedBillingFoundationOptions } from
 import { resolveConsentLocale } from "./consent-text.js";
 import { type TerminationDeclaration, terminationReceiptVariables } from "./termination-mail.js";
 import { notifyOperator, type OperatorNoticePlan, requireNotify } from "./termination-notify.js";
+import { mayMailReceipt } from "./termination-receipt-limit.js";
 import type { RecordContractTerminationResult } from "./termination-record.js";
 import type { OperatorNoticeReason } from "./termination-texts.js";
 
-const TENANT_ADMIN_ROLE = "TenantAdmin";
 const EXTRAORDINARY_REASON_MESSAGE = "reason is required for an extraordinary termination";
 
 const authUserRowSchema = z.object({
@@ -109,28 +109,38 @@ async function sendTerminationMails(
   consumerProtection: ConsumerProtectionOptions,
   plan: TerminationMailPlan,
 ): Promise<void> {
-  await requireNotify(ctx)(CONTRACT_TERMINATION_RECEIPT_NOTIFICATION_TYPE, {
-    route: { email: plan.declaration.email },
-    data: terminationReceiptVariables({
+  const receiptAllowed = await mayMailReceipt(ctx, plan.declaration.email);
+  if (receiptAllowed) {
+    await requireNotify(ctx)(CONTRACT_TERMINATION_RECEIPT_NOTIFICATION_TYPE, {
+      route: { email: plan.declaration.email },
+      data: terminationReceiptVariables({
+        locale: plan.locale,
+        requestId: plan.requestId,
+        receivedAtIso: plan.receivedAtIso,
+        declaration: {
+          declarationType: plan.declaration.declarationType,
+          terminationKind: plan.declaration.terminationKind,
+        },
+        operatorEmail: consumerProtection.operatorEmail,
+      }),
       locale: plan.locale,
-      requestId: plan.requestId,
-      receivedAtIso: plan.receivedAtIso,
-      declaration: plan.declaration,
-      operatorEmail: consumerProtection.operatorEmail,
-    }),
-    locale: plan.locale,
-    priority: "critical",
-  });
+      priority: "critical",
+    });
+  }
+  const reasons = receiptAllowed
+    ? plan.reasons
+    : [...plan.reasons, "receipt_rate_limited" as const];
   // skip: no operator notice needed for this declaration
-  if (plan.reasons.length === 0) return;
-  await notifyOperator(ctx, consumerProtection, plan);
+  if (reasons.length === 0) return;
+  await notifyOperator(ctx, consumerProtection, { ...plan, reasons });
 }
 
 // Tenants the entered email can terminate a contract for: tenants where the
-// user is TenantAdmin and the subscription is not terminal. Every identity
+// user holds a purchase role and the subscription is not terminal. Every identity
 // below comes from the trusted lookups, never from the payload.
 async function findTerminableTenantIds(
   ctx: HandlerContext,
+  options: ResolvedBillingFoundationOptions,
   requestTenantId: string,
   email: string,
 ): Promise<readonly string[]> {
@@ -148,10 +158,11 @@ async function findTerminableTenantIds(
     }),
   );
   if (!memberships.success) return [];
+  const purchaseRoles = purchaseRolesOf(options.catalog);
   const adminTenantIds = [
     ...new Set(
       memberships.data
-        .filter((membership) => membership.roles.includes(TENANT_ADMIN_ROLE))
+        .filter((membership) => membership.roles.some((role) => purchaseRoles.includes(role)))
         .map((membership) => membership.tenantId),
     ),
   ];
@@ -180,7 +191,6 @@ export function createRequestContractTerminationHandler(
     schema: requestContractTerminationSchema,
     access: { roles: ["anonymous"] },
     rateLimit: { per: "ip+handler", limit: 5, windowSeconds: 600 },
-    additionalRateLimits: [{ per: { payloadField: "email" }, limit: 3, windowSeconds: 86400 }],
     ...(consumerProtection.terminationScope === "platform" && { tenantlessAnonymous: true }),
     escapeHatch: {
       reason:
@@ -196,7 +206,12 @@ export function createRequestContractTerminationHandler(
       const locale = resolveConsentLocale(payload.locale);
       let matchedTenantId: string | undefined;
 
-      const candidates = await findTerminableTenantIds(ctx, event.user.tenantId, payload.email);
+      const candidates = await findTerminableTenantIds(
+        ctx,
+        options,
+        event.user.tenantId,
+        payload.email,
+      );
       const [onlyCandidate] = candidates;
       if (candidates.length === 1 && onlyCandidate !== undefined) {
         matchedTenantId = onlyCandidate;
@@ -257,7 +272,7 @@ export function createTerminateContractHandler(
   return {
     name: "terminate-contract",
     description:
-      "Terminates the tenant's subscription at the end of the billing period, or withdraws from the contract and cancels it immediately; sends a receipt to the caller's email.",
+      "Terminates the tenant's subscription at the end of the billing period, or withdraws from the contract and cancels it immediately within the 14-day withdrawal period (at period end after it); sends a receipt to the caller's email.",
     schema: terminateContractSchema,
     access: { roles: purchaseRolesOf(options.catalog) },
     escapeHatch: {
@@ -313,6 +328,7 @@ export function createTerminateContractHandler(
         },
         reasons: [
           ...(data.noticeReason !== null ? [data.noticeReason] : []),
+          ...(data.withdrawalPeriodExpired ? (["withdrawal_period_expired"] as const) : []),
           ...needsOperatorNotice(payload),
         ],
         tenantId,

package/packages/bundled-features/src/billing-foundation/consumer-protection/termination-texts.ts

@@ -72,6 +72,8 @@ export const OPERATOR_NOTICE_REASONS = [
   "provider_error",
   "no_active_subscription",
   "recording_failed",
+  "withdrawal_period_expired",
+  "receipt_rate_limited",
 ] as const;
 export type OperatorNoticeReason = (typeof OPERATOR_NOTICE_REASONS)[number];
 
@@ -116,6 +118,10 @@ export const TERMINATION_TEXTS: Readonly<Record<ConsentLocale, TerminationTexts>
       provider_error: "Die Kündigung beim Zahlungsanbieter ist fehlgeschlagen",
       no_active_subscription: "Keine laufende Subscription beim Anbieter",
       recording_failed: "Die Erklärung konnte nicht gespeichert werden",
+      withdrawal_period_expired:
+        "Widerruf nach Ablauf der Widerrufsfrist: zum Periodenende gekündigt, Anspruch prüfen",
+      receipt_rate_limited:
+        "Keine Eingangsbestätigung versendet: Limit pro Empfängeradresse erreicht",
     },
     noticeReasons: "Grund der Benachrichtigung",
     channel: "Kanal",
@@ -199,6 +205,9 @@ export const TERMINATION_TEXTS: Readonly<Record<ConsentLocale, TerminationTexts>
       provider_error: "Cancelling at the payment provider failed",
       no_active_subscription: "No running subscription at the provider",
       recording_failed: "The declaration could not be stored",
+      withdrawal_period_expired:
+        "Withdrawal after the withdrawal period: cancelled at period end, review the claim",
+      receipt_rate_limited: "No receipt mail sent: the per-recipient limit was reached",
     },
     noticeReasons: "Reason for this notice",
     channel: "Channel",

package/packages/bundled-features/src/billing-foundation/consumer-protection/withdrawal-period.ts

@@ -0,0 +1,35 @@
+import type { Temporal } from "@cosmicdrift/kumiko-types/temporal";
+import { CHECKOUT_CONSENT_RECORDED_EVENT_QN, SUBSCRIPTION_CREATED_EVENT_QN } from "../events.js";
+
+// § 355 BGB: the withdrawal period is 14 days from conclusion of the contract.
+export const WITHDRAWAL_PERIOD_DAYS = 14;
+const HOURS_PER_DAY = 24;
+
+const PERIOD_START_EVENT_TYPES: ReadonlySet<string> = new Set([
+  CHECKOUT_CONSENT_RECORDED_EVENT_QN,
+  SUBSCRIPTION_CREATED_EVENT_QN,
+]);
+
+type PeriodStartEvent = { readonly type: string; readonly createdAt: Temporal.Instant };
+
+/** The period runs from the latest consent or subscription start on the stream.
+ *  A stream with neither has no provable start and counts as expired. */
+export function isWithinWithdrawalPeriod(
+  events: readonly PeriodStartEvent[],
+  now: Temporal.Instant,
+): boolean {
+  let latestStart: Temporal.Instant | undefined;
+  for (const event of events) {
+    if (!PERIOD_START_EVENT_TYPES.has(event.type)) continue;
+    if (
+      latestStart === undefined ||
+      event.createdAt.epochMilliseconds > latestStart.epochMilliseconds
+    ) {
+      latestStart = event.createdAt;
+    }
+  }
+  // skip: no consent or subscription-created event, nothing proves a running period
+  if (latestStart === undefined) return false;
+  const periodEnd = latestStart.add({ hours: WITHDRAWAL_PERIOD_DAYS * HOURS_PER_DAY });
+  return now.epochMilliseconds <= periodEnd.epochMilliseconds;
+}

package/packages/bundled-features/src/billing-foundation/handlers/create-checkout-session.write.ts

@@ -23,7 +23,7 @@
 // hand-picked priceId.
 
 import type { HandlerContext, WriteHandlerDef } from "@cosmicdrift/kumiko-framework/engine";
-import { UnprocessableError } from "@cosmicdrift/kumiko-framework/errors";
+import { InternalError, UnprocessableError } from "@cosmicdrift/kumiko-framework/errors";
 import * as z from "zod";
 import {
   assertCheckoutAllowed,
@@ -32,6 +32,7 @@ import {
   startProviderCheckout,
 } from "../checkout-core.js";
 import {
+  assertValidOrderItem,
   type ConsentPayload,
   consentCheckoutFields,
   consentPayloadSchema,
@@ -104,11 +105,12 @@ export function createCheckoutSessionHandler(
 
       const mode = payload.mode ?? "subscription";
       const plugin = await assertCheckoutAllowed(ctx, openOptions, checkoutInput);
-      const price = await lookupPrice(ctx, plugin, payload.priceId);
+      const price = await lookupPrice(ctx, plugin, payload.providerName, payload.priceId);
       const orderItem =
         mode === "payment"
           ? await consumerProtection.oneOffItemLabel?.(ctx, payload.priceId)
           : undefined;
+      assertValidOrderItem(orderItem, payload.priceId);
       const consent = await prepareConsent(ctx, consumerProtection, payload.consent, mode);
       const result = await startProviderCheckout(ctx, plugin, {
         ...checkoutInput,
@@ -134,11 +136,17 @@ export function createCheckoutSessionHandler(
 async function lookupPrice(
   ctx: HandlerContext,
   plugin: SubscriptionProviderPlugin,
+  providerName: string,
   priceId: string,
 ): Promise<ProviderPrice> {
+  if (!plugin.retrievePrices) {
+    throw new InternalError({
+      message: `billing-foundation: provider "${providerName}" lacks retrievePrices, required by consumerProtection`,
+    });
+  }
   let price: ProviderPrice | undefined;
   try {
-    const prices = (await plugin.retrievePrices?.(ctx, [priceId])) ?? [];
+    const prices = await plugin.retrievePrices(ctx, [priceId]);
     price = prices.find((p) => p.priceId === priceId);
   } catch (cause) {
     throw priceUnavailable(priceId, cause);

package/packages/bundled-features/src/billing-foundation/handlers/process-event.write.ts

@@ -21,6 +21,7 @@ import * as z from "zod";
 import { subscriptionAggregateId } from "../aggregate-id.js";
 import {
   isSubscriptionBlockingCheckout,
+  isSwitchableSubscriptionStatus,
   SubscriptionEventTypes,
   SubscriptionStatuses,
 } from "../constants.js";
@@ -199,19 +200,24 @@ export async function appendSubscriptionEvent(
 // Tenant-Admin direkt.
 // One subscription aggregate exists per tenant, but a tenant can legitimately hold two provider
 // subscriptions over time (a stale `incomplete` one superseded by a fresh checkout). A late or
-// retried event of the old subscription must not overwrite the row of the live one, so only a
-// `created` event may replace a blocking row that belongs to a different provider subscription.
+// retried event of the old subscription must not overwrite the row of the live one, so an event of a
+// different provider subscription only replaces a row that no longer blocks a checkout. The exception
+// is a `created` of a subscription that is itself live (a provider switch); a late `created` of a
+// never-completed `incomplete` one stays stale, since delivery order is not guaranteed.
 function isStaleSubscriptionEvent(
   current: SubscriptionView | null,
   payload: ProcessEventPayload,
   now: Temporal.Instant,
 ): boolean {
   if (current === null) return false;
-  if (payload.type === SubscriptionEventTypes.created) return false;
   const sameSubscription =
     current.providerName === payload.providerName &&
     current.providerSubscriptionId === payload.providerSubscriptionId;
-  return !sameSubscription && isSubscriptionBlockingCheckout(current, now);
+  if (sameSubscription || !isSubscriptionBlockingCheckout(current, now)) return false;
+  const supersedesCurrent =
+    payload.type === SubscriptionEventTypes.created &&
+    isSwitchableSubscriptionStatus(payload.status);
+  return !supersedesCurrent;
 }
 
 export function createProcessEventHandler(now: () => Temporal.Instant): WriteHandlerDef {

package/packages/bundled-features/src/billing-foundation/i18n.ts

@@ -95,6 +95,9 @@ export const BILLING_FOUNDATION_I18N: Readonly<Record<string, LocalizedString>>
   "billing-foundation.errors.redirectOriginNotAllowed": {
     en: "This redirect URL is not allowed for this app.",
   },
+  "billing-foundation.errors.providerCustomerUnknown": {
+    en: "The billing account for this subscription no longer exists. Subscribe again to continue.",
+  },
   "billing-foundation.errors.providerHasNoPriceCatalog": {
     en: "This provider has no known prices configured.",
   },

package/packages/bundled-features/src/billing-foundation/subscription-tier-sync.ts

@@ -38,6 +38,10 @@ export type SubscriptionTierSyncDeps<TTier extends string> = {
   readonly onSyncError?: "log" | "fail-webhook";
 };
 
+// A manual grant that differs from what billing would assign is reported with this
+// code but never fails the webhook: a provider retry cannot resolve it.
+export const TIER_SYNC_MANUAL_GRANT_SKIPPED = "tier_sync_manual_grant_skipped";
+
 export function effectiveTierFromSubscription<TTier extends string>(
   status: string | undefined,
   tier: string | undefined,
@@ -82,7 +86,7 @@ export function createSubscriptionTierSync<TTier extends string>(
 ) {
   async function syncTierFromSubscription(
     tenantId: TenantId,
-    routeDeps: SignatureExtraRouteDeps,
+    routeDeps: Pick<SignatureExtraRouteDeps, "dispatchSystemQuery" | "dispatchSystemWrite">,
   ): Promise<{ code: string; message: string } | null> {
     try {
       const subscriptionId = subscriptionAggregateId(tenantId);
@@ -129,8 +133,13 @@ export function createSubscriptionTierSync<TTier extends string>(
         }
         return null;
       }
-      if (assignment.source === TierAssignmentSources.manual) return null;
       if (assignment.tier === effective) return null;
+      if (assignment.source === TierAssignmentSources.manual) {
+        return {
+          code: TIER_SYNC_MANUAL_GRANT_SKIPPED,
+          message: `manual tier grant "${String(assignment.tier)}" kept although the subscription yields "${effective}"`,
+        };
+      }
 
       const result = await routeDeps.dispatchSystemWrite({
         handlerQn: TierEngineHandlers.update,
@@ -169,9 +178,12 @@ export function createSubscriptionTierSync<TTier extends string>(
         if (syncError) {
           // biome-ignore lint/suspicious/noConsole: operator visibility for a post-commit sync failure
           console.warn(
-            `[subscription-tier-sync] tier sync failed for tenant ${tenantId} after successful webhook write: ${syncError.code} ${syncError.message}`,
+            `[subscription-tier-sync] tier sync for tenant ${tenantId} after successful webhook write: ${syncError.code} ${syncError.message}`,
           );
-          if (deps.onSyncError === "fail-webhook") {
+          if (
+            deps.onSyncError === "fail-webhook" &&
+            syncError.code !== TIER_SYNC_MANUAL_GRANT_SKIPPED
+          ) {
             return {
               isSuccess: false,
               error: {
@@ -188,5 +200,5 @@ export function createSubscriptionTierSync<TTier extends string>(
     });
   }
 
-  return { createWebhookRoute };
+  return { createWebhookRoute, syncTierFromSubscription };
 }

package/packages/bundled-features/src/billing-foundation/types.ts

@@ -396,7 +396,10 @@ export function isLegalLinkSet(
 
 /** Consumer-protection consent gate (§ 312j / § 356 BGB style). When set,
  *  `start-plan-checkout` and `create-checkout-session` require a `consent`
- *  payload and record it as an event before the buyer reaches the provider. */
+ *  payload and record it as an event before the buyer reaches the provider.
+ *  Every provider used with `create-checkout-session` must implement
+ *  `retrievePrices`: the live price is part of the consent record, and a
+ *  provider without it fails the checkout with an InternalError. */
 export type ConsumerProtectionOptions = {
   /** Slug of the template-resolver `text-block` holding the terms text; its
    *  content hash is stored with every recorded consent. */
@@ -411,7 +414,9 @@ export type ConsumerProtectionOptions = {
   readonly terminationScope?: TerminationScope;
   /** Names the item of a one-off payment (mode "payment") for the consent record
    *  and the confirmation mail; the label key is resolved through the registry
-   *  i18n, so it must be qualified with the registering feature. */
+   *  i18n, so it must be qualified with the registering feature. The label key
+   *  is 1-200 characters, string params at most 100; a violation fails the
+   *  checkout with an InternalError before the provider session is created. */
   readonly oneOffItemLabel?: (
     ctx: HandlerContext,
     priceId: string,

package/packages/bundled-features/src/cap-counter/calendar-cap-usage-reservation.ts

@@ -44,6 +44,8 @@ export async function reserveEnforcedCalendarCap(
       profile: cap.profile,
       notify: cap.notify,
       amount: cap.amount,
+      ...(cap.periodEndIso !== undefined && { periodEndIso: cap.periodEndIso }),
+      ...(cap.i18nKey !== undefined && { i18nKey: cap.i18nKey }),
       markSoftWarnedOutsideTransaction: outsideTransaction,
     });
   }

package/packages/bundled-features/src/cap-counter/changes.json

@@ -1,4 +1,10 @@
 [
+  {
+    "version": "0.364.0",
+    "type": "breaking",
+    "title": "CapExceededError carries resetAt and retryAfterSeconds, API sets Retry-After",
+    "migration": "Periodic caps no longer need RateLimitError({ windowSeconds: 0, ... }). Where you catch CapExceededError from enforceCap and rethrow it as RateLimitError, drop the catch and let CapExceededError pass: the response stays 429 with a correct Retry-After, error.code becomes cap_exceeded instead of rate_limited, and error.details carries resetAt and retryAfterSeconds. Keep a feature-specific message with enforceCap({ ..., i18nKey }) and pass a period end other than the calendar month with periodEndIso (e.g. a budget's resetsAtIso). Clients matching on rate_limited for these caps must also accept cap_exceeded. Any KumikoError with retryAfterSeconds (including RateLimitError thrown in a handler) now gets a Retry-After header from /api/write, /api/batch and /api/query."
+  },
   {
     "version": "0.361.0",
     "type": "improvement",

package/packages/bundled-features/src/cap-counter/enforce-cap.ts

@@ -66,14 +66,38 @@ export function assertBelowHardCap(
     readonly capName: string;
     readonly limit: number;
     readonly profile: CapToleranceProfileName;
+    // Rolling caps have no fixed period, so they pass neither period field.
+    readonly periodStartIso?: string;
+    readonly periodEndIso?: string;
+    readonly i18nKey?: string;
   },
 ): void {
   const tolerance = CAP_TOLERANCES[cap.profile];
   if (valueSeenByLastUnit >= cap.limit * tolerance.hard) {
-    throw new CapExceededError(cap.capName, cap.limit, valueSeenByLastUnit, tolerance);
+    const resetAt = resolvePeriodEndIso(cap.periodStartIso, cap.periodEndIso);
+    throw new CapExceededError(cap.capName, cap.limit, valueSeenByLastUnit, tolerance, {
+      ...(resetAt !== undefined && { resetAt }),
+      ...(cap.i18nKey !== undefined && { i18nKey: cap.i18nKey }),
+    });
   }
 }
 
+function resolvePeriodEndIso(
+  periodStartIso: string | undefined,
+  periodEndIso: string | undefined,
+): string | undefined {
+  if (periodStartIso === undefined) return periodEndIso;
+  if (periodEndIso === undefined) return calendarMonthPeriodEndIso(periodStartIso);
+  const start = Temporal.Instant.from(periodStartIso);
+  const end = Temporal.Instant.from(periodEndIso);
+  if (Temporal.Instant.compare(end, start) <= 0) {
+    throw new Error(
+      `cap-counter: periodEndIso (${periodEndIso}) must be after periodStartIso (${periodStartIso})`,
+    );
+  }
+  return end.toString();
+}
+
 // =============================================================================
 // Enforce-Cap helper
 // =============================================================================
@@ -109,6 +133,9 @@ export async function enforceCap(
     // Units the caller is about to book in one go (default 1), checked with
     // the same outcome as booking them one by one.
     readonly amount?: number;
+    // Default: end of the calendar month that starts at periodStartIso.
+    readonly periodEndIso?: string;
+    readonly i18nKey?: string;
   },
 ): Promise<EnforceCapResult> {
   const { user, readDb } = resolveCapCounterScope(ctx, false);
@@ -211,23 +238,54 @@ export async function enforceRollingCap(
  * Thrown by enforceCap/enforceRollingCap when value ≥ hard-threshold.
  * Extends `KumikoError` — the dispatcher auto-maps this to HTTP 429
  * with `code: "cap_exceeded"`, no caller-side catch needed.
+ *
+ * Calendar caps carry `resetAt` (end of the period) and `retryAfterSeconds`, which the API
+ * answers as Retry-After. Rolling caps have no fixed reset instant, so both stay undefined.
  */
 export class CapExceededError extends KumikoError {
   readonly code = "cap_exceeded" as const;
   readonly httpStatus = 429;
+  readonly resetAt: string | undefined;
 
   constructor(
     readonly capName: string,
     readonly limit: number,
     readonly currentValue: number,
     readonly tolerance: CapToleranceProfile,
+    options?: {
+      readonly resetAt?: string;
+      readonly i18nKey?: string;
+      readonly cause?: Error;
+      // Deterministic tests only.
+      readonly now?: Temporal.Instant;
+    },
   ) {
+    const resetAt = options?.resetAt;
+    const retryAfterSeconds =
+      resetAt === undefined
+        ? undefined
+        : Math.max(
+            0,
+            Math.ceil(
+              Temporal.Instant.from(resetAt).epochMilliseconds / 1000 -
+                (options?.now ?? Temporal.Now.instant()).epochMilliseconds / 1000,
+            ),
+          );
     super({
-      message: `Cap "${capName}" exceeded: current=${currentValue}, limit=${limit}, hard-threshold=${limit * tolerance.hard}. Upgrade tier or wait for next period reset.`,
-      i18nKey: "errors.cap.exceeded",
-      i18nParams: { capName, limit, currentValue },
-      details: { capName, limit, currentValue, tolerance },
+      message: `Cap "${capName}" exceeded: current=${currentValue}, limit=${limit}, hard-threshold=${limit * tolerance.hard}. Upgrade tier or wait for next period reset.${resetAt === undefined ? "" : ` Resets at ${resetAt}.`}`,
+      i18nKey: options?.i18nKey ?? "errors.cap.exceeded",
+      i18nParams: { capName, limit, currentValue, ...(resetAt !== undefined && { resetAt }) },
+      details: {
+        capName,
+        limit,
+        currentValue,
+        tolerance,
+        ...(resetAt !== undefined && { resetAt, retryAfterSeconds }),
+      },
+      ...(retryAfterSeconds !== undefined && { retryAfterSeconds }),
+      ...(options?.cause && { cause: options.cause }),
     });
+    this.resetAt = resetAt;
   }
 }
 
@@ -257,6 +315,14 @@ export function currentCalendarMonthStartIso(
   return start.toInstant().toString();
 }
 
+export function calendarMonthPeriodEndIso(periodStartIso: string): string {
+  return Temporal.Instant.from(periodStartIso)
+    .toZonedDateTimeISO("UTC")
+    .add({ months: 1 })
+    .toInstant()
+    .toString();
+}
+
 // =============================================================================
 // Notification-Wiring helpers — convenience-wrapper für enforceCap +
 // enforceRollingCap, die einen Caller-supplied delivery-emit beim
@@ -299,6 +365,8 @@ export async function enforceCapAndMaybeNotify(
     readonly profile: CapToleranceProfileName;
     readonly notify: SoftHitNotifier;
     readonly amount?: number;
+    readonly periodEndIso?: string;
+    readonly i18nKey?: string;
     readonly markSoftWarnedOutsideTransaction?: boolean;
   },
 ): Promise<EnforceCapResult> {
@@ -308,6 +376,8 @@ export async function enforceCapAndMaybeNotify(
     limit: options.limit,
     profile: options.profile,
     ...(options.amount !== undefined && { amount: options.amount }),
+    ...(options.periodEndIso !== undefined && { periodEndIso: options.periodEndIso }),
+    ...(options.i18nKey !== undefined && { i18nKey: options.i18nKey }),
   });
 
   if (result.state === "soft-hit" && result.crossed) {

package/packages/bundled-features/src/cap-counter/index.ts

@@ -29,6 +29,7 @@ export {
   CapExceededError,
   type CapToleranceProfile,
   type CapToleranceProfileName,
+  calendarMonthPeriodEndIso,
   currentCalendarMonthStartIso,
   type EnforceCapResult,
   enforceCap,

package/packages/bundled-features/src/cap-counter/with-cap-enforcement.ts

@@ -53,6 +53,9 @@ import { chainReservations } from "./reservation-chain.js";
 export type CalendarCapDef = {
   readonly capName: string;
   readonly periodStartIso: string;
+  // Default: end of the calendar month that starts at periodStartIso.
+  readonly periodEndIso?: string;
+  readonly i18nKey?: string;
   readonly limit: number;
   readonly profile: CapToleranceProfileName;
   /** Increment-amount post-success. Default 1. */

package/packages/bundled-features/src/channel-email/email-channel.ts

@@ -191,13 +191,20 @@ export function createEmailChannel(options: EmailChannelOptions): DeliveryChanne
       );
     }
     const unsubscribeUrl = message.data?.["unsubscribeUrl"];
-    const { subject, html, text, attachments } = await ctx.renderMail({
+    const { subject, html, text, attachments, fromName, replyTo } = await ctx.renderMail({
       slug: notificationType,
       locale: message.locale ?? "en",
       variables: message.data ?? {},
       ...(typeof unsubscribeUrl === "string" && { unsubscribeUrl }),
     });
-    return { html, subject, text, ...(attachments !== undefined && { attachments }) };
+    return {
+      html,
+      subject,
+      text,
+      ...(fromName !== undefined && { fromName }),
+      ...(replyTo !== undefined && { replyTo }),
+      ...(attachments !== undefined && { attachments }),
+    };
   }
 
   return {
@@ -217,8 +224,14 @@ export function createEmailChannel(options: EmailChannelOptions): DeliveryChanne
     },
 
     async send(address, message, ctx, rendered) {
-      const { html, subject, text, attachments } = rendered ?? (await renderMessage(message, ctx));
-      const envelope = emailEnvelopeFrom(message.data);
+      const { html, subject, text, attachments, fromName, replyTo } =
+        rendered ?? (await renderMessage(message, ctx));
+      // Template-level sender defaults; notify data wins.
+      const envelope = {
+        ...(fromName && { fromName }),
+        ...(replyTo && { replyTo }),
+        ...emailEnvelopeFrom(message.data),
+      };
       const resolvedAttachments = await resolveAttachments(
         [
           ...(attachments ?? []).map((ref): AttachmentSource => ({ ref, origin: "template" })),

package/packages/bundled-features/src/config/changes.json

@@ -1,4 +1,10 @@
 [
+  {
+    "version": "0.364.0",
+    "type": "fix",
+    "title": "Config key validate() receives a db scoped to the written tenant",
+    "detail": "A SystemAdmin writing a config value for another tenant previously handed the validator a system-mode db that could read every tenant. `ConfigValidateContext.db` is now a `TenantDb` locked to the tenant the value is written for. The validator runs inside the write transaction, so a slow query there should set its own timeout."
+  },
   {
     "version": "0.338.0",
     "type": "improvement",

package/packages/bundled-features/src/config/handlers/set.write.ts

@@ -4,7 +4,7 @@ import {
   encryptPiiValueForSubject,
   type KmsContext,
 } from "@cosmicdrift/kumiko-framework/crypto";
-import { createEventStoreExecutor } from "@cosmicdrift/kumiko-framework/db";
+import { createEventStoreExecutor, scopeTenantDbToTenant } from "@cosmicdrift/kumiko-framework/db";
 import {
   ConfigScopes,
   defineWriteHandler,
@@ -111,7 +111,7 @@ export const setWrite = defineWriteHandler({
           scope,
           tenantId,
           userId,
-          db,
+          db: scopeTenantDbToTenant(db, tenantId),
         });
       } catch (error) {
         if (isKumikoError(error)) return writeFailure(error);