@cosmicdrift/kumiko-samples 0.387.0 → 0.389.0

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

@@ -350,6 +350,21 @@ function bookCalendarDelta(
   );
 }
 
+// Asked after a missed or lost claim. A released tombstone committed since the first read does not
+// count: the caller's own tombstone insert then conflicts with it, and the retry claims that row.
+async function hasSettledTombstone(
+  txDb: TenantDb,
+  user: SessionUser,
+  id: string,
+): Promise<boolean> {
+  const settled = await txDb.fetchOne<CapReservationRow>(capReservationsTable, {
+    id,
+    tenantId: user.tenantId,
+    settledAt: { ne: null },
+  });
+  return settled !== undefined;
+}
+
 async function settleInTransaction(
   txDb: TenantDb,
   user: SessionUser,
@@ -386,12 +401,10 @@ async function settleInTransaction(
     );
     return booked;
   }
-  // The claim lost to a concurrent settle or release: a tombstone means the amount is booked.
-  if (await txDb.fetchOne<CapReservationRow>(capReservationsTable, ownRow)) {
-    return NOTHING_TO_RELEASE;
-  }
+  if (await hasSettledTombstone(txDb, user, id)) return NOTHING_TO_RELEASE;
   // Row swept or released: its amount was given back, so the full actual amount is booked and a
-  // tombstone makes a repeated settle a no-op. A parallel settle inserting first fails this insert.
+  // tombstone makes a repeated settle a no-op. A parallel settle or consume inserting first fails
+  // this insert.
   // Booking first: a lost counter race returns a result instead of throwing, so the transaction
   // commits and a tombstone written before it would turn the retry into a no-op.
   const booked = await bookCalendarDelta(txDb, user, options, options.actualAmount);
@@ -473,7 +486,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;
@@ -493,7 +510,7 @@ async function consumeClaimedRow(
 }
 
 // Row already expired away: the units are booked directly and a released tombstone remembers them
-// so a later settle subtracts them. A parallel consume inserting first fails this insert.
+// so a later settle subtracts them. A parallel consume or settle inserting first fails this insert.
 async function consumeWithoutRow(
   txDb: TenantDb,
   user: SessionUser,
@@ -538,7 +555,7 @@ async function consumeInTransaction(
   }
   const claimed = open && (await claimReservationRow(txDb, user, open));
   if (claimed) return consumeClaimedRow(txDb, user, claimed, options);
-  if (await txDb.fetchOne<CapReservationRow>(capReservationsTable, ownRow)) {
+  if (await hasSettledTombstone(txDb, user, id)) {
     throw new CapReservationSettledError(options.capName);
   }
   return consumeWithoutRow(txDb, user, id, options);

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

@@ -1,4 +1,34 @@
 [
+  {
+    "version": "0.389.0",
+    "type": "fix",
+    "title": "Settle and consume racing on a swept reservation book their units",
+    "detail": "After the sweep deleted a reservation's row, a consume could commit its released tombstone between the two reads of a parallel settle or consume. That call took the released tombstone for a settled one, so settle reported success without booking its amount and a second consume was rejected with cap_reservation_settled. Only a settled tombstone counts as settled now; a released one runs into the insert conflict and the retry books against it."
+  },
+  {
+    "version": "0.389.0",
+    "type": "fix",
+    "title": "Settle after a sweep survives a lost counter race",
+    "detail": "The amount is booked first and the tombstone written afterwards, so a version conflict on the counter retries the whole settle instead of leaving a tombstone that turns the retry into a no-op and drops the usage from the cap."
+  },
+  {
+    "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/feature.ts

@@ -71,6 +71,7 @@ export function createCapCounterFeature() {
   return defineFeature(
     CAP_COUNTER_FEATURE,
     (r) => {
+      r.adoptsBundledLists();
       r.describe(
         "Tracks per-tenant usage against configurable limits using two complementary storage models: calendar-period counters (one projection row per tenant/capName/period, reset implicitly by period rollover) and rolling-window counters (append-only event stream, no projection). Use `enforceCap` / `enforceRollingCap` (or the `withCapEnforcement` / `withRollingCapEnforcement` handler wrappers) in your write-handlers to check limits with soft-warn and hard-block tolerances; call `enforceCapAndMaybeNotify` when you also want to trigger a delivery notification on soft-threshold hits.",
       );

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/cap-overview/feature.ts

@@ -61,6 +61,7 @@ export function createCapOverviewFeature(opts: CreateCapOverviewOptions): Featur
   }
 
   return defineFeature(CAP_OVERVIEW_FEATURE, (r) => {
+    r.adoptsBundledLists();
     r.describe(
       "Read-only visibility into per-tenant tier assignment and cap usage. SystemAdmin gets a platform-wide tenant list with usage bars; tenant admins (or the roles in `usageVisibleTo`) get their own tenant's usage as dashboard cards. Reads tier-engine, billing-foundation, and tenant data plus app-owned usage tables via caller-supplied CapSpec callbacks — never writes.",
     );

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,22 @@
 [
+  {
+    "version": "0.389.0",
+    "type": "improvement",
+    "title": "config:write:set passes readCascade to validators",
+    "detail": "The set handler binds readCascade to the config resolver, the tenant-scoped db and the secrets reader, so validators see the same cascade as the value queries."
+  },
+  {
+    "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/set.write.ts

@@ -18,7 +18,7 @@ import {
   writeFailure,
 } from "@cosmicdrift/kumiko-framework/errors";
 import * as z from "zod";
-import { requireConfigEncryption, requireSystemDb } from "../feature.ts";
+import { requireConfigEncryption, requireConfigResolver, requireSystemDb } from "../feature.ts";
 import { MASKED } from "../read-redaction.ts";
 import { configValueEntity, configValuesTable } from "../table.ts";
 import {
@@ -106,13 +106,30 @@ export const setWrite = defineWriteHandler({
     if (patternError) return writeFailure(patternError);
 
     if (keyDef.validate) {
+      const validateDb = scopeTenantDbToTenant(db, tenantId);
       try {
         await keyDef.validate(event.payload.value, {
           key: event.payload.key,
           scope,
           tenantId,
           userId,
-          db: scopeTenantDbToTenant(db, tenantId),
+          db: validateDb,
+          readCascade: (qualifiedKey) => {
+            const cascadeKeyDef = ctx.registry.getConfigKey(qualifiedKey);
+            if (!cascadeKeyDef) {
+              throw new InternalError({
+                message: `[config:write:set] readCascade: unknown config key "${qualifiedKey}"`,
+              });
+            }
+            return requireConfigResolver(ctx, "config:write:set").getCascade(
+              qualifiedKey,
+              cascadeKeyDef,
+              tenantId,
+              event.user.id,
+              validateDb,
+              ctx.secrets,
+            );
+          },
         });
       } catch (error) {
         if (isKumikoError(error)) return writeFailure(error);

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);
     }
 

package/packages/bundled-features/src/config/write-helpers.ts

@@ -75,8 +75,9 @@ export async function configRowHoldsValue(
   serializedValue: string,
 ): Promise<boolean> {
   if (row?.value === null || row?.value === undefined) return false;
-  if (!keyDef?.encrypted && !keyDef?.piiEncrypted) return row.value === serializedValue;
-  if (!keyDef) return false;
+  if (keyDef === undefined || (!keyDef.encrypted && !keyDef.piiEncrypted)) {
+    return row.value === serializedValue;
+  }
   try {
     return (await decryptStoredValue(row.value, keyDef, cipher, qualifiedKey)) === serializedValue;
   } catch {
@@ -194,12 +195,7 @@ export function validateScope(
   definedScope: ConfigScope,
   key: string,
 ): KumikoError | null {
-  const levels: Record<ConfigScope, number> = {
-    [ConfigScopes.system]: 0,
-    [ConfigScopes.tenant]: 1,
-    [ConfigScopes.user]: 2,
-  };
-  if (levels[requestedScope] > levels[definedScope]) {
+  if (SCOPE_LEVEL[requestedScope] > SCOPE_LEVEL[definedScope]) {
     return new UnprocessableError("invalid_scope", {
       i18nKey: "config.errors.invalidScope",
       details: { key, definedScope, requestedScope },
@@ -208,6 +204,29 @@ export function validateScope(
   return null;
 }
 
+const SCOPE_LEVEL: Record<ConfigScope, number> = {
+  [ConfigScopes.system]: 0,
+  [ConfigScopes.tenant]: 1,
+  [ConfigScopes.user]: 2,
+};
+
+// Reads a tenant/user key at a narrower scope, e.g. system for a system-level screen.
+// Only a SystemAdmin may widen the read to the platform level; everyone else keeps the normal cascade.
+export function keyDefAtScope(
+  keyDef: ConfigKeyDefinition,
+  readScope: ConfigScope | undefined,
+  roles: readonly string[],
+): ConfigKeyDefinition {
+  if (
+    readScope === undefined ||
+    !roles.includes("SystemAdmin") ||
+    SCOPE_LEVEL[readScope] >= SCOPE_LEVEL[keyDef.scope]
+  ) {
+    return keyDef;
+  }
+  return { ...keyDef, scope: readScope };
+}
+
 export function resolveScopeIds(
   scope: ConfigScope,
   tenantId: TenantId,

package/packages/bundled-features/src/crypto-shredding/changes.json

@@ -1,4 +1,22 @@
 [
+  {
+    "version": "0.389.0",
+    "type": "improvement",
+    "title": "Tests pin the erasure write purpose in forget-subject and the forget cleanup",
+    "detail": "A pre-KMS user whose key was already erased still ends deleted, loses its tokens and gets the erased sentinel in the update event."
+  },
+  {
+    "version": "0.389.0",
+    "type": "improvement",
+    "title": "The subject file purge reads candidate rows in pages",
+    "detail": "A user owning many records no longer loads them all into memory at once; every page is purged, not only the first."
+  },
+  {
+    "version": "0.388.0",
+    "type": "fix",
+    "title": "forget-subject audit event survives a failing record owner lookup",
+    "detail": "The lookup of the record row's owning tenant now runs inside the file purge step, so a database error there is reported as cleanupError on the subject-forgotten event instead of aborting the handler after the key was erased."
+  },
   {
     "version": "0.377.0",
     "type": "fix",