@cosmicdrift/kumiko-samples 0.387.0 → 0.388.0

package/packages/bundled-features/src/billing-foundation/web/checkout-consent-dialog.tsx

@@ -1,5 +1,6 @@
 import { useLocale, usePrimitives, useTranslation } from "@cosmicdrift/kumiko-renderer";
 import type { WriteResult } from "@cosmicdrift/kumiko-renderer/headless";
+import { ChoiceCards } from "@cosmicdrift/kumiko-renderer/web";
 import { type ReactNode, useState } from "react";
 import type { BillingPlansResult } from "../types.ts";
 import { resolveConsentLocale } from "./consumer-protection/consent-locale.ts";
@@ -24,8 +25,24 @@ export type CheckoutConsentDialogProps = {
     readonly renewalKey?: string;
     readonly count?: string;
   };
-  readonly consumerProtection: ConsumerProtectionView;
-  readonly onOrder: (consent: CheckoutConsentPayload) => Promise<WriteResult<{ url: string }>>;
+  /** Without it the dialog shows no legal links and no consent checkboxes and orders without a consent. */
+  readonly consumerProtection?: ConsumerProtectionView;
+  /** Several providers to pick from; the parent follows `value` for price and order. */
+  readonly providerChoice?: {
+    readonly options: readonly {
+      readonly value: string;
+      readonly title: string;
+      readonly description?: string;
+      readonly aside?: string;
+    }[];
+    readonly value: string;
+    readonly onChange: (value: string) => void;
+  };
+  /** Provider note under the price line when there is no provider choice. */
+  readonly note?: string;
+  readonly onOrder: (
+    consent: CheckoutConsentPayload | undefined,
+  ) => Promise<WriteResult<{ url: string }>>;
   readonly onConsentTextOutdated: () => void;
 };
 
@@ -36,6 +53,8 @@ export function CheckoutConsentDialog({
   planName,
   price,
   consumerProtection,
+  providerChoice,
+  note,
   onOrder,
   onConsentTextOutdated,
 }: CheckoutConsentDialogProps): ReactNode {
@@ -48,18 +67,23 @@ export function CheckoutConsentDialog({
   const [errorText, setErrorText] = useState<string | null>(null);
 
   const consentLocale = resolveConsentLocale(uiLocale);
-  const texts = consumerProtection.consentTexts[consentLocale];
-  const legalLinks = consumerProtection.legalLinks[consentLocale];
+  const texts = consumerProtection?.consentTexts[consentLocale];
+  const legalLinks = consumerProtection?.legalLinks[consentLocale];
+  const consentGiven = consumerProtection === undefined || (earlyPerformance && withdrawalLoss);
 
   async function order(): Promise<void> {
     setSubmitting(true);
     setErrorText(null);
-    const result = await onOrder({
-      earlyPerformanceRequested: true,
-      withdrawalLossAcknowledged: true,
-      consentTextVersion: texts.consentTextVersion,
-      locale: consentLocale,
-    });
+    const result = await onOrder(
+      texts === undefined
+        ? undefined
+        : {
+            earlyPerformanceRequested: true,
+            withdrawalLossAcknowledged: true,
+            consentTextVersion: texts.consentTextVersion,
+            locale: consentLocale,
+          },
+    );
     if (result.isSuccess) return;
     setSubmitting(false);
     setErrorText(t(result.error.i18nKey, result.error.i18nParams));
@@ -78,6 +102,18 @@ export function CheckoutConsentDialog({
       testId="checkout-consent-dialog"
     >
       <div className="flex flex-col gap-4">
+        {providerChoice !== undefined && (
+          <div className="flex flex-col gap-2">
+            <Text variant="muted">{t("billing-foundation.consent.chooseProvider")}</Text>
+            <ChoiceCards
+              value={providerChoice.value}
+              options={providerChoice.options}
+              onChange={providerChoice.onChange}
+              ariaLabel={t("billing-foundation.consent.chooseProvider")}
+              testId="checkout-provider-choice"
+            />
+          </div>
+        )}
         <div className="flex flex-col gap-1" data-testid="checkout-consent-summary">
           <Text>
             {planName} — {price.amount}
@@ -93,38 +129,49 @@ export function CheckoutConsentDialog({
               <Text variant="muted">{t("billing-foundation.consent.cancelAnytime")}</Text>
             </>
           )}
+          {note !== undefined && (
+            <Text variant="muted" testId="checkout-consent-note">
+              {note}
+            </Text>
+          )}
         </div>
-        <div className="flex flex-wrap gap-4">
-          <Link href={legalLinks.terms} target="_blank">
-            {t("billing-foundation.consent.link.terms")}
-          </Link>
-          <Link href={legalLinks.withdrawal} target="_blank">
-            {t("billing-foundation.consent.link.withdrawal")}
-          </Link>
-          <Link href={legalLinks.privacy} target="_blank">
-            {t("billing-foundation.consent.link.privacy")}
-          </Link>
-        </div>
-        <Field id="consent-early-performance" label={texts.earlyPerformance} layout="inline">
-          <Input
-            kind="boolean"
-            id="consent-early-performance"
-            name="consent-early-performance"
-            value={earlyPerformance}
-            onChange={setEarlyPerformance}
-            disabled={submitting}
-          />
-        </Field>
-        <Field id="consent-withdrawal-loss" label={texts.withdrawalLoss} layout="inline">
-          <Input
-            kind="boolean"
-            id="consent-withdrawal-loss"
-            name="consent-withdrawal-loss"
-            value={withdrawalLoss}
-            onChange={setWithdrawalLoss}
-            disabled={submitting}
-          />
-        </Field>
+        {legalLinks !== undefined && (
+          <div className="flex flex-wrap gap-4">
+            <Link href={legalLinks.terms} target="_blank">
+              {t("billing-foundation.consent.link.terms")}
+            </Link>
+            <Link href={legalLinks.withdrawal} target="_blank">
+              {t("billing-foundation.consent.link.withdrawal")}
+            </Link>
+            <Link href={legalLinks.privacy} target="_blank">
+              {t("billing-foundation.consent.link.privacy")}
+            </Link>
+          </div>
+        )}
+        {texts !== undefined && (
+          <>
+            <Field id="consent-early-performance" label={texts.earlyPerformance} layout="inline">
+              <Input
+                kind="boolean"
+                id="consent-early-performance"
+                name="consent-early-performance"
+                value={earlyPerformance}
+                onChange={setEarlyPerformance}
+                disabled={submitting}
+              />
+            </Field>
+            <Field id="consent-withdrawal-loss" label={texts.withdrawalLoss} layout="inline">
+              <Input
+                kind="boolean"
+                id="consent-withdrawal-loss"
+                name="consent-withdrawal-loss"
+                value={withdrawalLoss}
+                onChange={setWithdrawalLoss}
+                disabled={submitting}
+              />
+            </Field>
+          </>
+        )}
         {errorText !== null && (
           <Banner variant="error" testId="checkout-consent-error">
             {errorText}
@@ -140,7 +187,7 @@ export function CheckoutConsentDialog({
             {t("billing-foundation.consent.back")}
           </Button>
           <Button
-            disabled={!earlyPerformance || !withdrawalLoss || submitting}
+            disabled={!consentGiven || submitting}
             loading={submitting}
             onClick={order}
             testId="checkout-consent-order"

package/packages/bundled-features/src/billing-foundation/web/constants.ts

@@ -95,6 +95,10 @@ export const SubscriptionFoundationQueries = {
    *  current tier and per-plan action. Only registered when a `catalog` is
    *  configured. */
   billingPlans: "billing-foundation:query:billing-plans",
+  /** What switching to a tier would cost right now, for providers that switch
+   *  plans in-app (preview + apply). Only registered when a `catalog` is
+   *  configured. */
+  planSwitchPreview: "billing-foundation:query:plan-switch-preview",
   /** System-only probe: does the caller tenant hold a non-terminal
    *  subscription (consumerProtection only). */
   terminableSubscription: "billing-foundation:query:terminable-subscription",

package/packages/bundled-features/src/billing-foundation/web/plan-price.ts

@@ -0,0 +1,55 @@
+import type { BillingPlanView } from "../types.ts";
+
+type Recurrence = {
+  readonly interval: string | null;
+  readonly intervalCount: number | null;
+};
+
+export function intervalKey(price: Recurrence | null): string | undefined {
+  if (price === null || price.interval === null) return undefined;
+  return price.intervalCount !== null && price.intervalCount > 1
+    ? `billing-foundation.plans.everyInterval.${price.interval}`
+    : `billing-foundation.plans.perInterval.${price.interval}`;
+}
+
+export function renewalKey(price: Recurrence | null): string | undefined {
+  if (price === null || price.interval === null) return undefined;
+  return price.intervalCount !== null && price.intervalCount > 1
+    ? `billing-foundation.consent.renewsEvery.${price.interval}`
+    : `billing-foundation.consent.renews.${price.interval}`;
+}
+
+type PlanPrice = NonNullable<BillingPlanView["price"]>;
+
+export function pricesDiffer(prices: readonly PlanPrice[]): boolean {
+  const [first, ...rest] = prices;
+  return (
+    first !== undefined &&
+    rest.some(
+      (price) =>
+        price.unitAmount !== first.unitAmount ||
+        price.currency !== first.currency ||
+        price.interval !== first.interval ||
+        price.intervalCount !== first.intervalCount,
+    )
+  );
+}
+
+/** Price of `tier` at every provider that offers it, in provider order. */
+export function tierPrices(
+  providers: readonly { readonly plans: readonly BillingPlanView[] }[],
+  tier: string,
+): PlanPrice[] {
+  return providers.flatMap((provider) => {
+    const price = provider.plans.find((plan) => plan.tier === tier)?.price;
+    return price ? [price] : [];
+  });
+}
+
+export function cheapestPrice(prices: readonly PlanPrice[]): PlanPrice | undefined {
+  return prices.reduce<PlanPrice | undefined>(
+    (lowest, price) =>
+      lowest === undefined || price.unitAmount < lowest.unitAmount ? price : lowest,
+    undefined,
+  );
+}

package/packages/bundled-features/src/billing-foundation/web/plan-switch-confirm-dialog.tsx

@@ -0,0 +1,224 @@
+import {
+  useLocale,
+  useMutation,
+  usePrimitives,
+  useQuery,
+  useTranslation,
+} from "@cosmicdrift/kumiko-renderer";
+import { formatMoney } from "@cosmicdrift/kumiko-renderer/web";
+import { type ReactNode, useState } from "react";
+import type { BillingPlansResult, PlanSwitchPreview } from "../types.ts";
+import {
+  type CheckoutConsentPayload,
+  CONSENT_TEXT_OUTDATED_CODE,
+} from "./checkout-consent-dialog.tsx";
+import { SubscriptionFoundationHandlers, SubscriptionFoundationQueries } from "./constants.ts";
+import { resolveConsentLocale } from "./consumer-protection/consent-locale.ts";
+import { intervalKey } from "./plan-price.ts";
+
+type ConsumerProtectionView = NonNullable<BillingPlansResult["consumerProtection"]>;
+
+type PlanSwitchPreviewReply = {
+  readonly preview: PlanSwitchPreview;
+  readonly target: {
+    readonly unitAmount: number;
+    readonly currency: string;
+    readonly interval: string | null;
+    readonly intervalCount: number | null;
+  };
+};
+
+export type PlanSwitchConfirmDialogProps = {
+  readonly open: boolean;
+  readonly onOpenChange: (open: boolean) => void;
+  readonly tier: string;
+  readonly fromPlanName: string;
+  readonly toPlanName: string;
+  readonly consumerProtection?: ConsumerProtectionView;
+  readonly onApplied: () => void;
+  readonly onConsentTextOutdated: () => void;
+};
+
+// kumiko-lint-ignore no-custom-primitives Uses usePrimitives().Modal internally, name is a billing domain action, not a primitive reimplementation
+export function PlanSwitchConfirmDialog({
+  open,
+  onOpenChange,
+  tier,
+  fromPlanName,
+  toPlanName,
+  consumerProtection,
+  onApplied,
+  onConsentTextOutdated,
+}: PlanSwitchConfirmDialogProps): ReactNode {
+  const t = useTranslation();
+  const locale = useLocale().locale();
+  const { Modal, Text, Field, Input, Button, Link, Banner } = usePrimitives();
+  const previewQuery = useQuery<PlanSwitchPreviewReply>(
+    SubscriptionFoundationQueries.planSwitchPreview,
+    { tier },
+  );
+  const switchMutation = useMutation<{ readonly applied: true }>(
+    SubscriptionFoundationHandlers.switchPlan,
+  );
+  const [earlyPerformance, setEarlyPerformance] = useState(false);
+  const [withdrawalLoss, setWithdrawalLoss] = useState(false);
+  const [submitting, setSubmitting] = useState(false);
+  const [errorText, setErrorText] = useState<string | null>(null);
+
+  const consentLocale = resolveConsentLocale(locale);
+  const texts = consumerProtection?.consentTexts[consentLocale];
+  const legalLinks = consumerProtection?.legalLinks[consentLocale];
+  const consentGiven = consumerProtection === undefined || (earlyPerformance && withdrawalLoss);
+
+  async function confirm(): Promise<void> {
+    setSubmitting(true);
+    setErrorText(null);
+    const consent: CheckoutConsentPayload | undefined =
+      texts === undefined
+        ? undefined
+        : {
+            earlyPerformanceRequested: true,
+            withdrawalLossAcknowledged: true,
+            consentTextVersion: texts.consentTextVersion,
+            locale: consentLocale,
+          };
+    const result = await switchMutation.mutate({ tier, ...(consent && { consent }) });
+    if (result.isSuccess) {
+      onApplied();
+      return;
+    }
+    setSubmitting(false);
+    setErrorText(t(result.error.i18nKey, result.error.i18nParams));
+    if (result.error.code === CONSENT_TEXT_OUTDATED_CODE) {
+      setEarlyPerformance(false);
+      setWithdrawalLoss(false);
+      onConsentTextOutdated();
+    }
+  }
+
+  const reply = previewQuery.data;
+  const money = (amount: number, currency: string) => formatMoney(amount, currency, locale);
+  const recurringKey = reply === null ? undefined : intervalKey(reply.target);
+  const recurringPrice =
+    reply === null
+      ? ""
+      : `${money(reply.target.unitAmount, reply.target.currency)}${
+          recurringKey === undefined
+            ? ""
+            : ` ${t(recurringKey, { count: new Intl.NumberFormat(locale).format(reply.target.intervalCount ?? 1) })}`
+        }`;
+
+  return (
+    <Modal
+      open={open}
+      onOpenChange={onOpenChange}
+      title={t("billing-foundation.planSwitch.title")}
+      testId="plan-switch-confirm-dialog"
+    >
+      <div className="flex flex-col gap-4">
+        <Text>
+          {t("billing-foundation.planSwitch.summary", { from: fromPlanName, to: toPlanName })}
+        </Text>
+        {previewQuery.error !== null && (
+          <Banner variant="error" testId="plan-switch-preview-error">
+            {t(previewQuery.error.i18nKey, previewQuery.error.i18nParams)}
+          </Banner>
+        )}
+        {previewQuery.loading && reply === null && (
+          <Banner variant="loading" testId="plan-switch-preview-loading">
+            {t("kumiko.widget.loading")}
+          </Banner>
+        )}
+        {reply !== null && (
+          <div className="flex flex-col gap-1" data-testid="plan-switch-summary">
+            <Text>
+              {t("billing-foundation.planSwitch.dueNow", {
+                amount: money(reply.preview.amountDueNow, reply.preview.currency),
+              })}
+              {reply.preview.tax !== null &&
+                ` (${t("billing-foundation.planSwitch.includesTax", {
+                  tax: money(reply.preview.tax, reply.preview.currency),
+                })})`}
+            </Text>
+            <Text variant="muted">
+              {t("billing-foundation.planSwitch.credit", {
+                amount: money(reply.preview.credit, reply.preview.currency),
+              })}
+            </Text>
+            <Text variant="muted">
+              {t("billing-foundation.planSwitch.recurring", {
+                amount: recurringPrice,
+              })}
+            </Text>
+            <Text variant="muted">{t("billing-foundation.planSwitch.effective")}</Text>
+            <Text variant="muted">{t("billing-foundation.planSwitch.pendingNote")}</Text>
+          </div>
+        )}
+        {legalLinks !== undefined && (
+          <div className="flex flex-wrap gap-4">
+            <Link href={legalLinks.terms} target="_blank">
+              {t("billing-foundation.consent.link.terms")}
+            </Link>
+            <Link href={legalLinks.withdrawal} target="_blank">
+              {t("billing-foundation.consent.link.withdrawal")}
+            </Link>
+            <Link href={legalLinks.privacy} target="_blank">
+              {t("billing-foundation.consent.link.privacy")}
+            </Link>
+          </div>
+        )}
+        {texts !== undefined && (
+          <>
+            <Field
+              id="plan-switch-early-performance"
+              label={texts.earlyPerformance}
+              layout="inline"
+            >
+              <Input
+                kind="boolean"
+                id="plan-switch-early-performance"
+                name="plan-switch-early-performance"
+                value={earlyPerformance}
+                onChange={setEarlyPerformance}
+                disabled={submitting}
+              />
+            </Field>
+            <Field id="plan-switch-withdrawal-loss" label={texts.withdrawalLoss} layout="inline">
+              <Input
+                kind="boolean"
+                id="plan-switch-withdrawal-loss"
+                name="plan-switch-withdrawal-loss"
+                value={withdrawalLoss}
+                onChange={setWithdrawalLoss}
+                disabled={submitting}
+              />
+            </Field>
+          </>
+        )}
+        {errorText !== null && (
+          <Banner variant="error" testId="plan-switch-confirm-error">
+            {errorText}
+          </Banner>
+        )}
+        <div className="flex justify-end gap-2">
+          <Button
+            variant="secondary"
+            disabled={submitting}
+            onClick={() => onOpenChange(false)}
+            testId="plan-switch-confirm-cancel"
+          >
+            {t("billing-foundation.consent.back")}
+          </Button>
+          <Button
+            disabled={!consentGiven || reply === null || submitting}
+            loading={submitting}
+            onClick={confirm}
+            testId="plan-switch-confirm-order"
+          >
+            {t("billing-foundation.planSwitch.order")}
+          </Button>
+        </div>
+      </div>
+    </Modal>
+  );
+}

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

@@ -473,7 +473,11 @@ async function consumeClaimedRow(
     if (!booked.isSuccess) return booked;
     await txDb.updateMany(
       capReservationsTable,
-      { consumedAmount: claimed.consumedAmount + options.units },
+      {
+        consumedAmount: claimed.consumedAmount + options.units,
+        // Keep the tombstone alive past its last consume, else a later consume would start a fresh one and double count.
+        expiresAt: Temporal.Now.instant().add({ minutes: CAP_SETTLED_TOMBSTONE_TTL_MINUTES }),
+      },
       ownRow,
     );
     return booked;

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

@@ -1,4 +1,22 @@
 [
+  {
+    "version": "0.388.0",
+    "type": "fix",
+    "title": "Consume on a released reservation extends its tombstone",
+    "detail": "Every consume against a released reservation tombstone now pushes its expiry out, so a long-running job that consumes across the sweep can no longer lose the tombstone and have its earlier units counted twice at settle."
+  },
+  {
+    "version": "0.388.0",
+    "type": "fix",
+    "title": "Misconfigured cap period fails on every enforcement",
+    "detail": "A periodEndIso that is unparsable or not after periodStartIso now throws on each enforceCap or reservation call instead of only once the hard cap is reached, so a bad period no longer turns into a 500 at the limit instead of cap_exceeded."
+  },
+  {
+    "version": "0.388.0",
+    "type": "fix",
+    "title": "Stock cap lock covers the counted rows, not the error code",
+    "detail": "withStockCap serializes on the table and where filter that are counted, so two handlers capping the same rows under different codes can no longer both pass the check in parallel and exceed the cap together."
+  },
   {
     "version": "0.378.0",
     "type": "fix",

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

@@ -71,8 +71,9 @@ export function assertBelowHardCap(
   },
 ): void {
   const tolerance = CAP_TOLERANCES[cap.profile];
+  // Validated on every call so a misconfigured period fails deterministically, not only at the limit.
+  const resetAt = resolvePeriodEndIso(cap.periodStartIso, cap.periodEndIso);
   if (valueSeenByLastUnit >= cap.limit * tolerance.hard) {
-    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 }),

package/packages/bundled-features/src/cap-counter/stock-cap-guard.ts

@@ -40,6 +40,13 @@ export type StockCapSpec<TCaps> = {
   readonly field: string;
 };
 
+// Lock on the counted set, not on `code`: two handlers capping the same rows under
+// different codes must still serialize against each other.
+function countedSetKey(spec: Pick<StockCapSpec<unknown>, "table" | "where">): string {
+  const where = Object.entries(spec.where ?? {}).sort(([a], [b]) => a.localeCompare(b));
+  return `${spec.table.tableName}:${JSON.stringify(where)}`;
+}
+
 export type StockCapGuard<TCaps> = {
   readonly checkStockCap: (
     db: TenantDb,
@@ -81,7 +88,7 @@ export function createStockCapGuard<TCaps>(
         // ctx.db is the handler's transaction, so the xact lock releases with its commit or
         // rollback. A handler wrapped in several caps must list them in the same order
         // everywhere; Postgres aborts one side of an inverse order with a deadlock error.
-        await ctx.db.advisoryXactLock(STOCK_CAP_LOCK_NAMESPACE, spec.code);
+        await ctx.db.advisoryXactLock(STOCK_CAP_LOCK_NAMESPACE, countedSetKey(spec));
         const failure = await checkStockCap(ctx.db, spec, { config: ctx.config });
         return failure ?? handler.handler(event, ctx);
       },

package/packages/bundled-features/src/channel-email/changes.json

@@ -1,4 +1,10 @@
 [
+  {
+    "version": "0.388.0",
+    "type": "fix",
+    "title": "Corrected description of an email channel without app transport",
+    "detail": "Without an app transport only notifications declared with tenantTransport true are delivered; all others fail with missing_credentials, so such apps must mark every outgoing notification or keep an app transport."
+  },
   {
     "version": "0.376.0",
     "type": "improvement",

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

@@ -12,7 +12,7 @@ export function createChannelEmailFeature(options: EmailChannelOptions) {
 
   const feature = defineFeature("channel-email", (r) => {
     r.describe(
-      "Wires an `EmailTransport` (typically `mail-transport-smtp` in production, `createInMemoryTransport()` in tests) into the delivery system as the `email` channel. Requires `delivery`; pass an `EmailChannelOptions` with a `transport` and a `resolveEmail` function that maps a user ID to their email address. Mails render from stored templates (`renderer-mail-html`): a notification routed to this channel needs `template` + `meta` on `r.notification`, otherwise its delivery fails. Pass `tenantTransport: tenantMailTransport` (from `mail-foundation`) to send the notifications declared with `tenantTransport: true` through the sending tenant's own configured provider: a broken provider fails the send, a tenant without one uses the app `transport`; every other notification (password reset, sign-in) always goes through the app `transport`. `transport` may be left out when `tenantTransport` is set; a mail that then has no transport fails with `missing_credentials`. Notifications declared with `unsubscribe: true` get a signed `data.unsubscribeUrl` from delivery, which turns into the `List-Unsubscribe` headers.",
+      "Wires an `EmailTransport` (typically `mail-transport-smtp` in production, `createInMemoryTransport()` in tests) into the delivery system as the `email` channel. Requires `delivery`; pass an `EmailChannelOptions` with a `transport` and a `resolveEmail` function that maps a user ID to their email address. Mails render from stored templates (`renderer-mail-html`): a notification routed to this channel needs `template` + `meta` on `r.notification`, otherwise its delivery fails. Pass `tenantTransport: tenantMailTransport` (from `mail-foundation`) to send the notifications declared with `tenantTransport: true` through the sending tenant's own configured provider: a broken provider fails the send, a tenant without one uses the app `transport`; every other notification (password reset, sign-in) always goes through the app `transport`. `transport` may be left out when `tenantTransport` is set, but then only notifications declared with `tenantTransport: true` are delivered: every other notification (password reset, sign-in, invitations) fails with `missing_credentials`, so an app without an app SMTP server must mark every notification that should go out or keep an app `transport`. Notifications declared with `unsubscribe: true` get a signed `data.unsubscribeUrl` from delivery, which turns into the `List-Unsubscribe` headers.",
     );
     r.uiHints({
       displayLabel: "Email Channel",

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

@@ -1,4 +1,16 @@
 [
+  {
+    "version": "0.388.0",
+    "type": "improvement",
+    "title": "config:query:values and config:query:cascade accept a read scope",
+    "detail": "Both queries take an optional scope (system, tenant, user). With scope system the cascade of a tenant or user key is evaluated at system level, so the system row is returned even when the caller's own tenant has a row for the key. Only a SystemAdmin gets the narrowed read; other callers keep the normal cascade. Inherited-value redaction still applies. Without scope the behavior is unchanged."
+  },
+  {
+    "version": "0.388.0",
+    "type": "fix",
+    "title": "Remove unreachable branch in configRowHoldsValue",
+    "detail": "The undefined key definition is now handled together with the plaintext comparison, dropping a dead return without changing behavior."
+  },
   {
     "version": "0.364.0",
     "type": "fix",

package/packages/bundled-features/src/config/handlers/cascade.query.ts

@@ -1,13 +1,14 @@
 import {
   type ConfigCascade,
   type ConfigCascadeLevel,
+  ConfigScopes,
   defineQueryHandler,
   isEncryptedAtRest,
 } from "@cosmicdrift/kumiko-framework/engine";
 import * as z from "zod";
 import { requireConfigResolver, requireSystemDb } from "../feature.ts";
 import { MASKED, redactInheritedCascade, shouldRedactInherited } from "../read-redaction.ts";
-import { hasConfigAccess } from "../write-helpers.ts";
+import { hasConfigAccess, keyDefAtScope } from "../write-helpers.ts";
 
 export const cascadeQuery = defineQueryHandler({
   name: "cascade",
@@ -15,6 +16,7 @@ export const cascadeQuery = defineQueryHandler({
     "Shows, per config key the caller may read, the value at every cascade level (user, tenant, system, app override, default) and which level won; use it to explain where a setting's current value comes from.",
   schema: z.object({
     keys: z.array(z.string()).optional(),
+    scope: z.enum([ConfigScopes.system, ConfigScopes.tenant, ConfigScopes.user]).optional(),
   }),
   access: {
     openToAll: {
@@ -47,7 +49,7 @@ export const cascadeQuery = defineQueryHandler({
       const keyDef = allKeys.get(key);
       if (!keyDef) continue;
       if (!hasConfigAccess(keyDef.access.read, query.user.roles)) continue;
-      keyDefs.set(key, keyDef);
+      keyDefs.set(key, keyDefAtScope(keyDef, query.payload.scope, query.user.roles));
       filteredKeys.push(key);
     }
 

package/packages/bundled-features/src/config/handlers/values.query.ts

@@ -1,6 +1,7 @@
 import {
   type ConfigKeyDefinition,
   type ConfigScope,
+  ConfigScopes,
   type ConfigValueSource,
   defineQueryHandler,
   isEncryptedAtRest,
@@ -8,7 +9,7 @@ import {
 import * as z from "zod";
 import { requireConfigResolver, requireSystemDb } from "../feature.ts";
 import { MASKED, redactInheritedCascade, shouldRedactInherited } from "../read-redaction.ts";
-import { hasConfigAccess } from "../write-helpers.ts";
+import { hasConfigAccess, keyDefAtScope } from "../write-helpers.ts";
 
 export const valuesQuery = defineQueryHandler({
   name: "values",
@@ -16,6 +17,7 @@ export const valuesQuery = defineQueryHandler({
     "Returns the effective value, scope and winning source for every config key the caller may read (optionally narrowed to `keys`), with encrypted and secret-backed values masked; use it to inspect the current settings.",
   schema: z.object({
     keys: z.array(z.string()).optional(),
+    scope: z.enum([ConfigScopes.system, ConfigScopes.tenant, ConfigScopes.user]).optional(),
   }),
   // Per-key read access enforced via hasConfigAccess inside the handler.
   access: {
@@ -44,7 +46,7 @@ export const valuesQuery = defineQueryHandler({
     for (const [qualifiedKey, keyDef] of allKeys) {
       if (requestedKeys !== undefined && !requestedKeys.has(qualifiedKey)) continue;
       if (!hasConfigAccess(keyDef.access.read, query.user.roles)) continue;
-      keyDefs.set(qualifiedKey, keyDef);
+      keyDefs.set(qualifiedKey, keyDefAtScope(keyDef, query.payload.scope, query.user.roles));
       filteredKeys.push(qualifiedKey);
     }