@cosmicdrift/kumiko-bundled-features 0.387.0 → 0.389.0

package/dist/billing-foundation/web/plan-switch-confirm-dialog.js

@@ -0,0 +1,66 @@
+import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useLocale, useMutation, usePrimitives, useQuery, useTranslation, } from "@cosmicdrift/kumiko-renderer";
+import { formatMoney } from "@cosmicdrift/kumiko-renderer/web";
+import { useState } from "react";
+import { CONSENT_TEXT_OUTDATED_CODE, } from "./checkout-consent-dialog.js";
+import { SubscriptionFoundationHandlers, SubscriptionFoundationQueries } from "./constants.js";
+import { resolveConsentLocale } from "./consumer-protection/consent-locale.js";
+import { intervalKey } from "./plan-price.js";
+// 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, }) {
+    const t = useTranslation();
+    const locale = useLocale().locale();
+    const { Modal, Text, Field, Input, Button, Link, Banner } = usePrimitives();
+    const previewQuery = useQuery(SubscriptionFoundationQueries.planSwitchPreview, { tier });
+    const switchMutation = useMutation(SubscriptionFoundationHandlers.switchPlan);
+    const [earlyPerformance, setEarlyPerformance] = useState(false);
+    const [withdrawalLoss, setWithdrawalLoss] = useState(false);
+    const [submitting, setSubmitting] = useState(false);
+    const [errorText, setErrorText] = useState(null);
+    const consentLocale = resolveConsentLocale(locale);
+    const texts = consumerProtection?.consentTexts[consentLocale];
+    const legalLinks = consumerProtection?.legalLinks[consentLocale];
+    const consentGiven = consumerProtection === undefined || (earlyPerformance && withdrawalLoss);
+    async function confirm() {
+        setSubmitting(true);
+        setErrorText(null);
+        const consent = 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, currency) => 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 (_jsx(Modal, { open: open, onOpenChange: onOpenChange, title: t("billing-foundation.planSwitch.title"), testId: "plan-switch-confirm-dialog", children: _jsxs("div", { className: "flex flex-col gap-4", children: [_jsx(Text, { children: t("billing-foundation.planSwitch.summary", { from: fromPlanName, to: toPlanName }) }), previewQuery.error !== null && (_jsx(Banner, { variant: "error", testId: "plan-switch-preview-error", children: t(previewQuery.error.i18nKey, previewQuery.error.i18nParams) })), previewQuery.loading && reply === null && (_jsx(Banner, { variant: "loading", testId: "plan-switch-preview-loading", children: t("kumiko.widget.loading") })), reply !== null && (_jsxs("div", { className: "flex flex-col gap-1", "data-testid": "plan-switch-summary", children: [_jsxs(Text, { children: [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),
+                                    })})`] }), _jsx(Text, { variant: "muted", children: t("billing-foundation.planSwitch.credit", {
+                                amount: money(reply.preview.credit, reply.preview.currency),
+                            }) }), _jsx(Text, { variant: "muted", children: t("billing-foundation.planSwitch.recurring", {
+                                amount: recurringPrice,
+                            }) }), _jsx(Text, { variant: "muted", children: t("billing-foundation.planSwitch.effective") }), _jsx(Text, { variant: "muted", children: t("billing-foundation.planSwitch.pendingNote") })] })), legalLinks !== undefined && (_jsxs("div", { className: "flex flex-wrap gap-4", children: [_jsx(Link, { href: legalLinks.terms, target: "_blank", children: t("billing-foundation.consent.link.terms") }), _jsx(Link, { href: legalLinks.withdrawal, target: "_blank", children: t("billing-foundation.consent.link.withdrawal") }), _jsx(Link, { href: legalLinks.privacy, target: "_blank", children: t("billing-foundation.consent.link.privacy") })] })), texts !== undefined && (_jsxs(_Fragment, { children: [_jsx(Field, { id: "plan-switch-early-performance", label: texts.earlyPerformance, layout: "inline", children: _jsx(Input, { kind: "boolean", id: "plan-switch-early-performance", name: "plan-switch-early-performance", value: earlyPerformance, onChange: setEarlyPerformance, disabled: submitting }) }), _jsx(Field, { id: "plan-switch-withdrawal-loss", label: texts.withdrawalLoss, layout: "inline", children: _jsx(Input, { kind: "boolean", id: "plan-switch-withdrawal-loss", name: "plan-switch-withdrawal-loss", value: withdrawalLoss, onChange: setWithdrawalLoss, disabled: submitting }) })] })), errorText !== null && (_jsx(Banner, { variant: "error", testId: "plan-switch-confirm-error", children: errorText })), _jsxs("div", { className: "flex justify-end gap-2", children: [_jsx(Button, { variant: "secondary", disabled: submitting, onClick: () => onOpenChange(false), testId: "plan-switch-confirm-cancel", children: t("billing-foundation.consent.back") }), _jsx(Button, { disabled: !consentGiven || reply === null || submitting, loading: submitting, onClick: confirm, testId: "plan-switch-confirm-order", children: t("billing-foundation.planSwitch.order") })] })] }) }));
+}

package/dist/cap-counter/cap-reservation.js

@@ -186,6 +186,16 @@ function bookCalendarDelta(txDb, user, period, delta) {
         return Promise.resolve({ isSuccess: true, data: {} });
     return applyCapDeltaOn(txDb, user, { ...period, amount: Math.abs(delta) }, delta > 0 ? "add" : "subtract");
 }
+// 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, user, id) {
+    const settled = await txDb.fetchOne(capReservationsTable, {
+        id,
+        tenantId: user.tenantId,
+        settledAt: { ne: null },
+    });
+    return settled !== undefined;
+}
 async function settleInTransaction(txDb, user, id, options) {
     const ownRow = { id, tenantId: user.tenantId };
     const open = await txDb.fetchOne(capReservationsTable, {
@@ -205,12 +215,11 @@ async function settleInTransaction(txDb, user, id, options) {
         await txDb.updateMany(capReservationsTable, { settledAt: now, expiresAt: now.add({ minutes: CAP_SETTLED_TOMBSTONE_TTL_MINUTES }) }, ownRow);
         return booked;
     }
-    // The claim lost to a concurrent settle or release: a tombstone means the amount is booked.
-    if (await txDb.fetchOne(capReservationsTable, ownRow)) {
+    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);
@@ -269,7 +278,11 @@ async function consumeClaimedRow(txDb, user, claimed, options) {
         const booked = await bookCalendarDelta(txDb, user, options, options.units);
         if (!booked.isSuccess)
             return booked;
-        await txDb.updateMany(capReservationsTable, { consumedAmount: claimed.consumedAmount + options.units }, ownRow);
+        await txDb.updateMany(capReservationsTable, {
+            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;
     }
     if (options.units > claimed.amount) {
@@ -282,7 +295,7 @@ async function consumeClaimedRow(txDb, user, claimed, options) {
     return NOTHING_TO_RELEASE;
 }
 // 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, user, id, options) {
     // Booking first, for the same reason as settle's missing-row path.
     const booked = await bookCalendarDelta(txDb, user, options, options.units);
@@ -316,7 +329,7 @@ async function consumeInTransaction(txDb, user, id, options) {
     const claimed = open && (await claimReservationRow(txDb, user, open));
     if (claimed)
         return consumeClaimedRow(txDb, user, claimed, options);
-    if (await txDb.fetchOne(capReservationsTable, ownRow)) {
+    if (await hasSettledTombstone(txDb, user, id)) {
         throw new CapReservationSettledError(options.capName);
     }
     return consumeWithoutRow(txDb, user, id, options);

package/dist/cap-counter/enforce-cap.js

@@ -16,8 +16,9 @@ export const CAP_TOLERANCES = {
 };
 export function assertBelowHardCap(valueSeenByLastUnit, cap) {
     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/dist/cap-counter/feature.js

@@ -54,6 +54,7 @@ import { CAP_COUNTER_I18N } from "./i18n.js";
 import { capReservationsTableMeta } from "./tables.js";
 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.");
         r.uiHints({
             displayLabel: "Cap Counter · Usage Limits",

package/dist/cap-counter/stock-cap-guard.js

@@ -7,6 +7,12 @@ import { enforceStockCap } from "./enforce-cap.js";
 // pg_advisory_xact_lock namespace (int4): 'scap' as ASCII, disjoint from the
 // framework's other fixed advisory-lock keys.
 const STOCK_CAP_LOCK_NAMESPACE = 0x73636170;
+// 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) {
+    const where = Object.entries(spec.where ?? {}).sort(([a], [b]) => a.localeCompare(b));
+    return `${spec.table.tableName}:${JSON.stringify(where)}`;
+}
 export function createStockCapGuard(resolveTierCaps) {
     async function checkStockCap(db, spec, context = {}) {
         // Lock-free on its own: a direct call outside withStockCap is not atomic.
@@ -31,7 +37,7 @@ export function createStockCapGuard(resolveTierCaps) {
                 // 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/dist/cap-overview/feature.js

@@ -36,6 +36,7 @@ export function createCapOverviewFeature(opts) {
         }
     }
     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.");
         r.uiHints({
             displayLabel: "Cap Overview · Tier & Usage Visibility",

package/dist/channel-email/feature.js

@@ -6,7 +6,7 @@ import { smtpEnvSchema } from "./env.js";
 export function createChannelEmailFeature(options) {
     const channel = createEmailChannel(options);
     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.");
+        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, 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",
             category: "notifications",

package/dist/config/handlers/cascade.query.d.ts

@@ -2,4 +2,9 @@ import { type ConfigCascade } from "@cosmicdrift/kumiko-framework/engine";
 import * as z from "zod";
 export declare const cascadeQuery: import("@cosmicdrift/kumiko-types/define-handler").QueryHandlerDefinition<"cascade", z.ZodObject<{
     keys: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    scope: z.ZodOptional<z.ZodEnum<{
+        system: "system";
+        tenant: "tenant";
+        user: "user";
+    }>>;
 }, z.core.$strip>, Record<string, ConfigCascade>, import("@cosmicdrift/kumiko-types/event-type-map").KumikoEventTypeMap>;

package/dist/config/handlers/cascade.query.js

@@ -1,13 +1,14 @@
-import { defineQueryHandler, isEncryptedAtRest, } from "@cosmicdrift/kumiko-framework/engine";
+import { ConfigScopes, defineQueryHandler, isEncryptedAtRest, } from "@cosmicdrift/kumiko-framework/engine";
 import * as z from "zod";
 import { requireConfigResolver, requireSystemDb } from "../feature.js";
 import { MASKED, redactInheritedCascade, shouldRedactInherited } from "../read-redaction.js";
-import { hasConfigAccess } from "../write-helpers.js";
+import { hasConfigAccess, keyDefAtScope } from "../write-helpers.js";
 export const cascadeQuery = defineQueryHandler({
     name: "cascade",
     description: "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: {
@@ -34,7 +35,7 @@ export const cascadeQuery = defineQueryHandler({
                 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);
         }
         const cascades = await resolver.getCascadeBatch(filteredKeys, keyDefs, query.user.tenantId, query.user.id, db, ctx.secrets);

package/dist/config/handlers/set.write.js

@@ -4,7 +4,7 @@ import { createEventStoreExecutor, scopeTenantDbToTenant } from "@cosmicdrift/ku
 import { ConfigScopes, defineWriteHandler, isEncryptedAtRest, SYSTEM_TENANT_ID, } from "@cosmicdrift/kumiko-framework/engine";
 import { InternalError, isKumikoError, UnprocessableError, writeFailure, } from "@cosmicdrift/kumiko-framework/errors";
 import * as z from "zod";
-import { requireConfigEncryption, requireSystemDb } from "../feature.js";
+import { requireConfigEncryption, requireConfigResolver, requireSystemDb } from "../feature.js";
 import { MASKED } from "../read-redaction.js";
 import { configValueEntity, configValuesTable } from "../table.js";
 import { findConfigRow, prepareConfigWrite, resolvePiiSubject, validateBounds, validateExtensionPlugin, validatePattern, validateScope, validateType, } from "../write-helpers.js";
@@ -69,13 +69,23 @@ 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) {

package/dist/config/handlers/values.query.d.ts

@@ -2,6 +2,11 @@ import { type ConfigScope, type ConfigValueSource } from "@cosmicdrift/kumiko-fr
 import * as z from "zod";
 export declare const valuesQuery: import("@cosmicdrift/kumiko-types/define-handler").QueryHandlerDefinition<"values", z.ZodObject<{
     keys: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    scope: z.ZodOptional<z.ZodEnum<{
+        system: "system";
+        tenant: "tenant";
+        user: "user";
+    }>>;
 }, z.core.$strip>, Record<string, {
     value: string | number | boolean | undefined;
     scope: ConfigScope;

package/dist/config/handlers/values.query.js

@@ -1,13 +1,14 @@
-import { defineQueryHandler, isEncryptedAtRest, } from "@cosmicdrift/kumiko-framework/engine";
+import { ConfigScopes, defineQueryHandler, isEncryptedAtRest, } from "@cosmicdrift/kumiko-framework/engine";
 import * as z from "zod";
 import { requireConfigResolver, requireSystemDb } from "../feature.js";
 import { MASKED, redactInheritedCascade, shouldRedactInherited } from "../read-redaction.js";
-import { hasConfigAccess } from "../write-helpers.js";
+import { hasConfigAccess, keyDefAtScope } from "../write-helpers.js";
 export const valuesQuery = defineQueryHandler({
     name: "values",
     description: "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: {
@@ -34,7 +35,7 @@ export const valuesQuery = defineQueryHandler({
                 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);
         }
         // Resolve through the full cascade (rows → app-override → computed →

package/dist/config/write-helpers.d.ts

@@ -35,6 +35,7 @@ export declare function checkWriteAccess(keyDef: ConfigKeyDefinition, userRoles:
  */
 export declare function checkScopeWriteAccess(scope: ConfigScope, userRoles: readonly string[]): KumikoError | null;
 export declare function validateScope(requestedScope: ConfigScope, definedScope: ConfigScope, key: string): KumikoError | null;
+export declare function keyDefAtScope(keyDef: ConfigKeyDefinition, readScope: ConfigScope | undefined, roles: readonly string[]): ConfigKeyDefinition;
 export declare function resolveScopeIds(scope: ConfigScope, tenantId: TenantId, userId: string): {
     tenantId: TenantId;
     userId: string | null;

package/dist/config/write-helpers.js

@@ -33,10 +33,9 @@ export async function findConfigRow(db, key, tenantId, userId) {
 export async function configRowHoldsValue(row, keyDef, cipher, qualifiedKey, serializedValue) {
     if (row?.value === null || row?.value === undefined)
         return false;
-    if (!keyDef?.encrypted && !keyDef?.piiEncrypted)
+    if (keyDef === undefined || (!keyDef.encrypted && !keyDef.piiEncrypted)) {
         return row.value === serializedValue;
-    if (!keyDef)
-        return false;
+    }
     try {
         return (await decryptStoredValue(row.value, keyDef, cipher, qualifiedKey)) === serializedValue;
     }
@@ -112,12 +111,7 @@ export function checkScopeWriteAccess(scope, userRoles) {
     });
 }
 export function validateScope(requestedScope, definedScope, key) {
-    const levels = {
-        [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 },
@@ -125,6 +119,21 @@ export function validateScope(requestedScope, definedScope, key) {
     }
     return null;
 }
+const SCOPE_LEVEL = {
+    [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, readScope, roles) {
+    if (readScope === undefined ||
+        !roles.includes("SystemAdmin") ||
+        SCOPE_LEVEL[readScope] >= SCOPE_LEVEL[keyDef.scope]) {
+        return keyDef;
+    }
+    return { ...keyDef, scope: readScope };
+}
 export function resolveScopeIds(scope, tenantId, userId) {
     switch (scope) {
         case ConfigScopes.system:

package/dist/crypto-shredding/handlers/forget-subject.write.js

@@ -224,7 +224,6 @@ function sweepErrorLabel(err) {
 // Each step runs in its own savepoint: a database error must not abort the handler
 // transaction, and one failing step must not skip or roll back the others.
 async function sweepDerivedSubjectData(ctx, subject, subjectKey, crossTenantRunner, audit, rawSubject) {
-    const recordTenantId = await owningTenantOfRecordSubject(crossTenantRunner, ctx.registry.features, rawSubject);
     const failureLabels = [];
     const runStep = async (step) => {
         try {
@@ -254,15 +253,19 @@ async function sweepDerivedSubjectData(ctx, subject, subjectKey, crossTenantRunn
         }
     });
     // File columns hold only the fileRef id, so the key erase never reaches the bytes.
-    await runStep((crossTenantSubjectRunner) => purgeFilesReachingSubject({
-        registry: ctx.registry,
-        db: crossTenantSubjectRunner,
-        subject,
-        subjectKey,
-        ...(recordTenantId !== undefined && { recordTenantId }),
-        resolveDeleteBytes: resolveFileBytesDeleter(ctx),
-        missingStorage: { mode: "fail" },
-    }));
+    await runStep(async (crossTenantSubjectRunner) => {
+        // Inside the step: a failing owner lookup must land in the audit label, not abort the handler.
+        const recordTenantId = await owningTenantOfRecordSubject(crossTenantSubjectRunner, ctx.registry.features, rawSubject);
+        await purgeFilesReachingSubject({
+            registry: ctx.registry,
+            db: crossTenantSubjectRunner,
+            subject,
+            subjectKey,
+            ...(recordTenantId !== undefined && { recordTenantId }),
+            resolveDeleteBytes: resolveFileBytesDeleter(ctx),
+            missingStorage: { mode: "fail" },
+        });
+    });
     return failureLabels[0];
 }
 // Email subscribers and other non-user entities use user-style subject keys
@@ -396,7 +399,7 @@ export const forgetSubjectWrite = defineWriteHandler({
         //   - user.updated as lifecycle event (updateUserLifecycle), so a
         //     read_users rebuild doesn't wipe the flip
         //   - sessions don't need active revocation — session-callbacks
-        //     re-validate user.status on every request (isPrincipalBlocked
+        //     re-validate the user row on every request (isPrincipalRowBlocked
         //     blocks Deleted).
         // Both idempotent (status set / revokedAt IS NULL filter), retry after
         // crash recovery is safe. User-feature guard: without the user feature

package/dist/custom-fields/lib/parse-serialized-field.js

@@ -1,7 +1,7 @@
 // Centralised parser for `fieldDefinition.serializedField`.
 //
 // The column is stored as `text` in B1 (entity.ts) — what the db row hands
-// back depends on the driver: postgres-js returns text as a `string`, but
+// back depends on the driver: text normally arrives as a `string`, but
 // jsonb-tolerant drivers and middleware can deliver an already-parsed
 // object. This helper normalises both, validates the shape, and centralises
 // the single boundary cast so callers don't sprinkle `as { … }`-narrowings

package/dist/delivery/channel-context.js

@@ -1,7 +1,7 @@
 import { createTenantDb } from "@cosmicdrift/kumiko-framework/db";
 import { SYSTEM_TENANT_ID } from "@cosmicdrift/kumiko-framework/engine";
 import { createFallbackLogger } from "@cosmicdrift/kumiko-framework/logging";
-import { readFileRefContent } from "../file-foundation/index.js";
+import { FileStorageUnavailableError, readFileRefContent, } from "../file-foundation/index.js";
 import { collectRendererPlugins, createRendererFoundationApi, RendererError, } from "../renderer-foundation/index.js";
 import { FALLBACK_LOCALE } from "../template-resolver/index.js";
 export function createTemplateMailRenderer(db, registry, tenantId, config) {
@@ -44,15 +44,18 @@ function createPdfRenderer(db, registry, tenantId, config, filesForTenant) {
         return { content: response.pdfBytes, contentType: PDF_CONTENT_TYPE };
     };
 }
-// A decorative inline image (logo) that cannot be read must not fail the whole mail.
+// A decorative inline image (logo) of a tenant without file storage must not fail the whole mail;
+// transient read errors rethrow so the send job retries.
 async function readInlineImageOrNull(fileRefId, read) {
     try {
         return await read();
     }
     catch (err) {
+        if (!(err instanceof FileStorageUnavailableError))
+            throw err;
         createFallbackLogger("delivery").warn("inline image could not be read, sending without it", {
             fileRefId,
-            errorName: err instanceof Error ? err.name : typeof err,
+            errorName: err.name,
         });
         return null;
     }

package/dist/delivery/db/queries/preferences.js

@@ -1,4 +1,4 @@
-import { unsafeReadRetrying } from "@cosmicdrift/kumiko-framework/db";
+import { toPostgresArrayLiteral, unsafeReadRetrying } from "@cosmicdrift/kumiko-framework/db";
 // @wrapper-known semantic-alias
 export async function selectNotificationPreferences(db, tenantId, userId, notificationTypeNames, channelName) {
     return unsafeReadRetrying(db, `SELECT notification_type AS "notificationType", channel, enabled
@@ -9,5 +9,5 @@ export async function selectNotificationPreferences(db, tenantId, userId, notifi
          (notification_type = ANY($3::text[]) AND channel = $4)
          OR (notification_type = '*' AND channel = $4)
          OR (notification_type = ANY($3::text[]) AND channel = '*')
-       )`, [tenantId, userId, notificationTypeNames, channelName]);
+       )`, [tenantId, userId, toPostgresArrayLiteral(notificationTypeNames), channelName]);
 }

package/dist/delivery/delivery-service.js

@@ -266,9 +266,27 @@ export function createDeliveryService(options) {
             });
         }
     }
+    // The app's tenantOrigin callback typically hits the DB: once per run and tenant, not per recipient.
+    const unsubscribeOriginsByRun = new WeakMap();
+    function unsubscribeOriginOnce(run, links, channelCtx, notificationType) {
+        let originsByTenant = unsubscribeOriginsByRun.get(run);
+        if (originsByTenant === undefined) {
+            originsByTenant = new Map();
+            unsubscribeOriginsByRun.set(run, originsByTenant);
+        }
+        let origin = originsByTenant.get(channelCtx.tenantId);
+        if (origin === undefined) {
+            origin = unsubscribeLinkOrigin(links, channelCtx, (reason) => logError.warn(`unsubscribe link falls back to the app origin: ${reason}`, {
+                tenantId: channelCtx.tenantId,
+                notificationType,
+            }));
+            originsByTenant.set(channelCtx.tenantId, origin);
+        }
+        return origin;
+    }
     // A caller-supplied unsubscribeUrl wins; the recipient comes from the server-side notify
     // context, never from the notification data.
-    async function withUnsubscribeUrl(message, channelName, recipient, channelCtx) {
+    async function withUnsubscribeUrl(run, message, channelName, recipient, channelCtx) {
         if (!unsubscribeLinks || channelName !== EMAIL_CHANNEL_NAME)
             return message;
         if (registry.getAllNotifications().get(message.notificationType)?.unsubscribe !== true) {
@@ -277,10 +295,7 @@ export function createDeliveryService(options) {
         const supplied = message.data?.["unsubscribeUrl"];
         if (typeof supplied === "string" && supplied !== "")
             return message;
-        const origin = await unsubscribeLinkOrigin(unsubscribeLinks, channelCtx, (reason) => logError.warn(`unsubscribe link falls back to the app origin: ${reason}`, {
-            tenantId: channelCtx.tenantId,
-            notificationType: message.notificationType,
-        }));
+        const origin = await unsubscribeOriginOnce(run, unsubscribeLinks, channelCtx, message.notificationType);
         const unsubscribeUrl = await buildUnsubscribeUrl(unsubscribeLinks, origin, recipient, {
             tenantId: channelCtx.tenantId,
             notificationType: message.notificationType,
@@ -476,7 +491,7 @@ export function createDeliveryService(options) {
                     run,
                     channel,
                     address,
-                    message: await withUnsubscribeUrl(message, channel.name, { kind: "user", userId }, channelCtx),
+                    message: await withUnsubscribeUrl(run, message, channel.name, { kind: "user", userId }, channelCtx),
                     channelCtx,
                     tenantId,
                     recipientId: userId,
@@ -549,7 +564,7 @@ export function createDeliveryService(options) {
                     run,
                     channel,
                     address,
-                    message: await withUnsubscribeUrl(message, channel.name, { kind: "address", address }, channelCtx),
+                    message: await withUnsubscribeUrl(run, message, channel.name, { kind: "address", address }, channelCtx),
                     channelCtx,
                     tenantId,
                     recipientId,

package/dist/delivery/feature.js

@@ -21,6 +21,7 @@ export function createDeliveryFeature(options) {
     const resolvedAccess = options?.access ?? access.admin;
     const attemptLogRetentionDays = resolveAttemptLogRetentionDays(options?.attemptLogRetentionDays);
     return defineFeature("delivery", (r) => {
+        r.adoptsBundledLists();
         r.describe("The notification dispatch core: call `ctx.notify(notificationType, { to, route, data, priority, idempotencyKey })` from any handler to fan out a notification across all registered channels (email, in-app, push). Inside a write handler the delivery runs after the write has committed (the call returns `{ kind: \"deferred\" }`, a rolled-back write sends nothing); `immediate: true` delivers synchronously and returns `{ kind: \"dispatched\", deliveries }`. It stores per-user channel preferences in the `notification-preference` entity, opt-outs for no-account recipient addresses in `notification-address-opt-out` (keyed by a blind-index hash, never the plaintext address), logs every attempt to `store_delivery_attempts`, and enforces idempotency and rate-limiting \u2014 add `channel-email`, `channel-in-app`, or `channel-push` on top to actually send anything. Unsubscribe/resubscribe links are served by `createUnsubscribeRoutes({ secret })` mounted via the app's `extraRoutes` at `/api/delivery/unsubscribe` and `/api/delivery/resubscribe`: `GET /unsubscribe?token=` renders a confirmation page (no write), `POST /unsubscribe` performs the opt-out (RFC 8058 one-click, token from the form body or query), `POST /resubscribe` undoes it (JSON `{token}` or form body only, never the query — reachable by a mail-client link prefetcher) — sign links with `signUnsubscribeToken` / `signAddressUnsubscribeToken` using the same secret. `channel-email` sets `List-Unsubscribe` / `List-Unsubscribe-Post` automatically when a message's `data.unsubscribeUrl` points at the unsubscribe route. A notification declared with `unsubscribe: true` gets that link from delivery itself when the service has `unsubscribeLinks` (the `runProdApp` and `runDevApp` option `unsubscribe: { secret }` mounts the routes and wires it; base URL from `auth.publicOrigin`, `auth.mail.baseUrl` or `APP_BASE_URL`): user recipients get a user token, `route` recipients an address token (needs a blind-index key, otherwise no link); a `data.unsubscribeUrl` from the caller wins. `unsubscribe.tenantOrigin: (ctx) => origin | null` points the link at the tenant's own host (subdomain or custom domain, must serve this app's `/api`); null, a throw or a non-https value fall back to the app origin. The token carries the mail's locale, so the confirmation and result pages render in the mail's language. An app serving its own (e.g. legacy) unsubscribe links renders the same result page with `renderUnsubscribeResultPage({ kind, locale })`. To react to a no-account opt-out (e.g. remove the app's own subscriber row), declare `r.job(name, { trigger: { on: DeliveryHandlers.unsubscribeAddress } }, handler)` on a lane the app consumes: it runs after each committed opt-out, also an idempotent repeat, with `unsubscribeAddressPayloadSchema` (`addressHash`, `notificationType`, `channel`) as payload and the tenant in `ctx.triggeredBy.tenantId`; match the subscriber via `hashUnsubscribeAddress(email)`. Declare `unsubscribeUrl` as an optional template variable if the mail body shows it.");
         r.uiHints({
             displayLabel: "Notifications \u00b7 Dispatch Core",

package/dist/delivery/handlers/preferences.query.d.ts

@@ -1,4 +1,4 @@
 import * as z from "zod";
 export declare const preferencesQuery: import("@cosmicdrift/kumiko-types/define-handler").QueryHandlerDefinition<"preferences", z.ZodObject<{}, z.core.$strip>, {
-    rows: readonly any[];
+    rows: any[];
 }, import("@cosmicdrift/kumiko-types/event-type-map").KumikoEventTypeMap>;

package/dist/delivery/handlers/preferences.query.js

@@ -2,6 +2,7 @@ import { selectMany } from "@cosmicdrift/kumiko-framework/db";
 import { defineQueryHandler } from "@cosmicdrift/kumiko-framework/engine";
 import { InternalError } from "@cosmicdrift/kumiko-framework/errors";
 import * as z from "zod";
+import { currentNotificationType } from "../notification-type-aliases.js";
 import { notificationPreferencesTable } from "../tables.js";
 export const preferencesQuery = defineQueryHandler({
     name: "preferences",
@@ -31,6 +32,24 @@ export const preferencesQuery = defineQueryHandler({
             tenantId: query.user.tenantId,
             userId: query.user.id,
         });
-        return { rows };
+        // Rows stored under a former notification name are reported under the current
+        // one, collapsed with the same precedence as delivery: an exact row wins,
+        // otherwise any disabled former-name row disables.
+        const collapsed = new Map();
+        for (const row of rows) {
+            const notificationType = currentNotificationType(ctx.registry, row.notificationType);
+            const key = `${notificationType}\u0000${row.channel}`;
+            const isExact = row.notificationType === notificationType;
+            const existing = collapsed.get(key);
+            if (existing?.isExact)
+                continue;
+            const formerNameRowDisablesAlready = existing !== undefined &&
+                !isExact &&
+                (existing.row.enabled === false || row.enabled !== false);
+            if (formerNameRowDisablesAlready)
+                continue;
+            collapsed.set(key, { row: { ...row, notificationType }, isExact });
+        }
+        return { rows: [...collapsed.values()].map((entry) => entry.row) };
     },
 });

package/dist/delivery/handlers/unsubscribe-page-chrome.query.js

@@ -23,7 +23,7 @@ export const unsubscribePageChromeQuery = defineQueryHandler({
     // Only reachable via a system dispatch: the signed unsubscribe routes after verify(),
     // or createUnsubscribePageChromeReader for a tenant the app resolved server-side.
     agent: { expose: false },
-    description: "Returns the tenant's mail brand row and footer resolved for one locale, or null without a mail renderer; dispatched by the signed unsubscribe route to dress its pages like the mail, not meant for UI callers.",
+    description: "Returns the tenant's mail brand row and footer resolved for one locale, or null without a mail renderer; dispatched by the signed unsubscribe route or by createUnsubscribePageChromeReader for a tenant the app resolved server-side, to dress its pages like the mail; not meant for UI callers.",
     handler: async (query, ctx) => {
         const { tenantId } = query.user;
         if (!ctx.systemDb) {

package/dist/delivery/index.d.ts

@@ -12,6 +12,7 @@ export { createDeliveryFeature, type DeliveryFeatureOptions } from "./feature.ts
 export { type UnsubscribeAddressPayload, unsubscribeAddressPayloadSchema, } from "./handlers/unsubscribe-address.write.ts";
 export { currentNotificationType } from "./notification-type-aliases.ts";
 export { createDeliveryNotifyFactory } from "./notify-factory.ts";
+export { buildSystemChannelContext, type SystemChannelContextDeps, type SystemChannelContextOptions, } from "./system-channel-context.ts";
 export { deliveryAttemptsTable, notificationAddressOptOutEntity, notificationAddressOptOutsTable, notificationPreferenceEntity, notificationPreferencesTable, } from "./tables.ts";
 export { type CreateDeliveryTestContextOptions, createDeliveryTestContext } from "./testing.ts";
 export { type AttachmentOrigin, type ChannelContext, type ChannelMessage, type ChannelResult, type DeliveryChannel, type DeliveryChannelMode, type DeliveryChannelPlugin, type DeliveryLogEntry, type DeliveryService, isDeliveryChannelPlugin, type RenderedMessage, } from "./types.ts";

package/dist/delivery/index.js

@@ -11,6 +11,7 @@ export { createDeliveryFeature } from "./feature.js";
 export { unsubscribeAddressPayloadSchema, } from "./handlers/unsubscribe-address.write.js";
 export { currentNotificationType } from "./notification-type-aliases.js";
 export { createDeliveryNotifyFactory } from "./notify-factory.js";
+export { buildSystemChannelContext, } from "./system-channel-context.js";
 export { deliveryAttemptsTable, notificationAddressOptOutEntity, notificationAddressOptOutsTable, notificationPreferenceEntity, notificationPreferencesTable, } from "./tables.js";
 export { createDeliveryTestContext } from "./testing.js";
 export { isDeliveryChannelPlugin, } from "./types.js";