@cosmicdrift/kumiko-samples 0.365.1 → 0.367.0

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

@@ -164,7 +164,11 @@ async function resolveAttachments(
 }
 
 export type EmailChannelOptions = {
+  /** The app-wide transport, used for every tenant `tenantTransport` returns null for. */
   readonly transport: EmailTransport;
+  /** Resolves the sending tenant's own transport, null when it has none. Built per send and
+   *  never cached, so a provider change applies to the next mail; a throw fails the send. */
+  readonly tenantTransport?: (ctx: ChannelContext) => Promise<EmailTransport | null>;
   readonly resolveEmail: (
     userId: string,
     ctx: { db: unknown; tenantId: TenantId },
@@ -172,7 +176,7 @@ export type EmailChannelOptions = {
 };
 
 export function createEmailChannel(options: EmailChannelOptions): DeliveryChannel {
-  const { transport, resolveEmail } = options;
+  const { transport, resolveEmail, tenantTransport } = options;
 
   // Render runs in the delivery.render job, decoupled from the SMTP send so
   // each can retry independently. Extracted so the inline path (no job runner)
@@ -209,6 +213,11 @@ export function createEmailChannel(options: EmailChannelOptions): DeliveryChanne
     };
   }
 
+  async function transportFor(ctx: ChannelContext): Promise<EmailTransport> {
+    if (tenantTransport === undefined) return transport;
+    return (await tenantTransport(ctx)) ?? transport;
+  }
+
   return {
     name: EMAIL_CHANNEL_NAME,
     mode: "queued",
@@ -251,7 +260,8 @@ export function createEmailChannel(options: EmailChannelOptions): DeliveryChanne
         return { status: "failed", error: "send_failed", address };
       }
       const resolvedAttachments = resolution.attachments;
-      await transport.send(
+      const sendTransport = await transportFor(ctx);
+      await sendTransport.send(
         guardEmailMessage({
           to: address,
           subject,

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

@@ -10,14 +10,14 @@ export function createChannelEmailFeature(options: EmailChannelOptions): Feature
 
   return 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.",
+      "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 each tenant's mail through its own configured provider: a broken provider fails the send, a tenant without one uses the 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",
       recommended: false,
     });
-    r.requires("delivery");
+    r.requires({ features: ["delivery"] });
 
     r.translations({ keys: { "delivery.channel.email": { en: "Email" } } });
     r.useExtension(DELIVERY_CHANNEL_EXTENSION, EMAIL_CHANNEL_NAME, {

package/packages/bundled-features/src/channel-in-app/feature.ts

@@ -17,7 +17,7 @@ export function createChannelInAppFeature(): FeatureDefinition {
       category: "notifications",
       recommended: false,
     });
-    r.requires("delivery");
+    r.requires({ features: ["delivery"] });
 
     r.storeTable(inAppMessagesTableMeta, {
       reason: "read_side.in_app_messages",

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

@@ -14,7 +14,7 @@ export function createChannelPushFeature(options: PushChannelOptions): FeatureDe
       category: "notifications",
       recommended: false,
     });
-    r.requires("delivery");
+    r.requires({ features: ["delivery"] });
 
     r.translations({ keys: { "delivery.channel.push": { en: "Push" } } });
     r.useExtension(DELIVERY_CHANNEL_EXTENSION, "push", {

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

@@ -21,8 +21,8 @@ export function createChannelSlackFeature(options: SlackChannelOptions = {}): Fe
       category: "notifications",
       recommended: false,
     });
-    r.requires("delivery");
-    r.requires("secrets");
+    r.requires({ features: ["delivery"] });
+    r.requires({ features: ["secrets"] });
 
     const webhookTarget = resolveChatWebhookTarget(
       { defaultAllowedHosts: SLACK_DEFAULT_ALLOWED_HOSTS },

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

@@ -21,8 +21,8 @@ export function createChannelTeamsFeature(options: TeamsChannelOptions = {}): Fe
       category: "notifications",
       recommended: false,
     });
-    r.requires("delivery");
-    r.requires("secrets");
+    r.requires({ features: ["delivery"] });
+    r.requires({ features: ["secrets"] });
 
     const webhookTarget = resolveChatWebhookTarget(
       { defaultAllowedHosts: TEAMS_DEFAULT_ALLOWED_HOSTS },

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

@@ -19,8 +19,8 @@ export function createChannelTelegramFeature(
       category: "notifications",
       recommended: false,
     });
-    r.requires("delivery");
-    r.requires("secrets");
+    r.requires({ features: ["delivery"] });
+    r.requires({ features: ["secrets"] });
 
     const botToken = r.secret("botToken", {
       label: { en: "Telegram bot token" },

package/packages/bundled-features/src/compliance-profiles/feature.ts

@@ -63,7 +63,7 @@ export function createComplianceProfilesFeature(
     // Context, Profile-Selection ist eigene Entity, sub-processor-Liste
     // sind Constants. Wenn S1.4+ Cross-Feature-Reads dazukommen, kommt
     // r.requires hier rein.
-    r.entity("tenant-compliance-profile", tenantComplianceProfileEntity);
+    r.entity({ name: "tenant-compliance-profile", ...tenantComplianceProfileEntity });
 
     r.exposesApi("compliance.forTenant");
 

package/packages/bundled-features/src/compliance-profiles-ops/index.ts

@@ -7,7 +7,7 @@
 // a separate feature (mirrors folders-user-data/notes-history-user-data)
 // rather than folded into compliance-profiles: this is the one genuinely
 // cross-tenant capability in the picker's orbit, and it alone needs
-// r.systemScope() + a hard r.requires("tenant") — apps that only want the
+// r.systemScope() + a hard r.requires({ features: ["tenant"] }) — apps that only want the
 // per-tenant picker (the vast majority) stay unaffected.
 
 import { defineFeature } from "@cosmicdrift/kumiko-framework/engine";
@@ -23,8 +23,8 @@ export const complianceProfilesOpsFeature = defineFeature("compliance-profiles-o
     recommended: false,
   });
   r.systemScope();
-  r.requires("compliance-profiles");
-  r.requires("tenant");
+  r.requires({ features: ["compliance-profiles"] });
+  r.requires({ features: ["tenant"] });
 
   const queries = {
     tenantsMissingProfile: r.queryHandler(tenantsMissingProfileQuery),

package/packages/bundled-features/src/config/feature.ts

@@ -45,7 +45,7 @@ export function createConfigFeature(): FeatureDefinition {
     // projection write in one TX. Subscribers that need config-change
     // semantics listen to those auto-events via r.multiStreamProjection
     // (see docs/plans/architecture/event-sourcing-pivot.md §4.7).
-    r.entity("config-value", configValueEntity);
+    r.entity({ name: "config-value", ...configValueEntity });
 
     const handlers = {
       set: r.writeHandler(setWrite),

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

@@ -1,4 +1,10 @@
 [
+  {
+    "version": "0.366.0",
+    "type": "fix",
+    "title": "forget-subject is covered for users stored before the KMS and users without an event stream",
+    "detail": "Tests now cover forget-subject for users stored as plaintext before the KMS was configured and for users without an event stream. Both succeed since the KMS tombstone fix, close the login door and write the audit event."
+  },
   {
     "version": "0.365.1",
     "type": "fix",

package/packages/bundled-features/src/custom-fields/feature.ts

@@ -10,7 +10,7 @@
 // (crypto-shredding, event ciphertext, forget pipeline).
 //
 // **Was diese Feature liefert (B1 + B2, 2026-05-23):**
-//   1. r.entity("field-definition") — Definition-Storage (event-sourced).
+//   1. r.entity({ name: "field-definition" }) — Definition-Storage (event-sourced).
 //   2. define-tenant-field / define-system-field — RBAC write-handlers für
 //      Definition-CRUD.
 //   3. delete-tenant-field / delete-system-field — RBAC write-handlers.
@@ -123,7 +123,7 @@ function registerCustomFields(
     category: "data",
     recommended: false,
   });
-  r.entity("field-definition", fieldDefinitionEntity);
+  r.entity({ name: "field-definition", ...fieldDefinitionEntity });
 
   // Event-types — qualified als "custom-fields:event:<short-name>".
   // Returned EventDefs liefern .name als compile-time literal-typed string,

package/packages/bundled-features/src/custom-fields/wire-for-entity.ts

@@ -44,8 +44,8 @@ export function customFieldsField(): JsonbFieldDef {
 // Consumer-side:
 //
 //   defineFeature("property-mgmt", (r) => {
-//     r.entity("property", propertyEntity);  // muss customFieldsField() haben
-//     r.requires(CUSTOM_FIELDS_FEATURE_NAME);
+//     r.entity({ name: "property", ...propertyEntity });  // muss customFieldsField() haben
+//     r.requires({ features: [CUSTOM_FIELDS_FEATURE_NAME] });
 //     wireCustomFieldsFor(r, "property", propertyTable);
 //   });
 //
@@ -198,18 +198,22 @@ export function wireCustomFieldsFor<TReg extends FeatureRegistrar<string>>(
 
   // postQuery-hook: flatten row.customFields jsonb auf root-level der
   // API-response. Spec-Promise Z.4 "indistinguishable von Stammfeldern".
-  r.hook("postQuery", { allOf: entityName }, async ({ rows }) => ({
-    rows: rows.map((row) => {
-      const customFields = row["customFields"];
-      if (customFields && typeof customFields === "object" && !Array.isArray(customFields)) {
-        return {
-          ...(customFields as Record<string, unknown>), // @cast-boundary db-row jsonb runtime-untyped
-          ...row, // base fields win: a custom fieldKey named `id`/`name` must not shadow the real column
-        };
-      }
-      return row;
+  r.hook({
+    type: "postQuery",
+    target: { allOf: entityName },
+    handler: async ({ rows }) => ({
+      rows: rows.map((row) => {
+        const customFields = row["customFields"];
+        if (customFields && typeof customFields === "object" && !Array.isArray(customFields)) {
+          return {
+            ...(customFields as Record<string, unknown>), // @cast-boundary db-row jsonb runtime-untyped
+            ...row, // base fields win: a custom fieldKey named `id`/`name` must not shadow the real column
+          };
+        }
+        return row;
+      }),
     }),
-  }));
+  });
 
   // Search-Payload-Extension: customFields-keys flach ins Index-Doc.
   // Anders als postQuery-hook (der ALLE keys merged) trägt der Search-

package/packages/bundled-features/src/data-retention/feature.ts

@@ -65,7 +65,7 @@ export function createDataRetentionFeature(): FeatureDefinition {
       category: "compliance",
       recommended: false,
     });
-    r.entity("tenant-retention-override", tenantRetentionOverrideEntity);
+    r.entity({ name: "tenant-retention-override", ...tenantRetentionOverrideEntity });
 
     // S2.D3: Cross-Feature-API fuer Forget-Flow + Cleanup-Job
     r.exposesApi("retention.policyFor");

package/packages/bundled-features/src/data-retention/presets.ts

@@ -13,10 +13,10 @@
 import type { RetentionDef } from "@cosmicdrift/kumiko-framework/engine";
 
 /**
- * Pro Entity-Name gemappte Retention-Policy. Entity-Namen sind der
- * String aus r.entity("name", ...) — kebab-case oder lowercase.
- * Cleanup-Job iteriert alle bekannten Entities; was nicht im Preset
- * steht, fällt auf Entity-Default (Layer 1) zurück.
+ * Retention policy keyed by entity name, i.e. the `name` from
+ * r.entity({ name, ... }) (kebab-case or lowercase). The cleanup job walks
+ * all known entities; anything missing from the preset falls back to the
+ * entity default (layer 1).
  */
 export type RetentionPreset = Readonly<Record<string, RetentionDef>>;
 

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

@@ -1,4 +1,22 @@
 [
+  {
+    "version": "0.367.0",
+    "type": "improvement",
+    "title": "Delivery signs unsubscribe links itself",
+    "detail": "r.notification(name, { unsubscribe: true }) makes delivery put a signed data.unsubscribeUrl into every email of that notification when the service has unsubscribeLinks. User recipients get a user token, route recipients an address token (only with a blind-index key, otherwise no link). The token is scoped to tenant, notification and channel; a link the caller passes in data.unsubscribeUrl wins. runProdApp option unsubscribe: { secret } mounts createUnsubscribeRoutes and wires the links; the base URL comes from auth.publicOrigin, auth.mail.baseUrl or APP_BASE_URL, and without one boot warns and no link is added."
+  },
+  {
+    "version": "0.367.0",
+    "type": "improvement",
+    "title": "Unsubscribe links use the tenant's host and the mail's language, apps learn about address opt-outs",
+    "detail": "unsubscribeLinks and the runProdApp option unsubscribe take tenantOrigin, an app callback that returns the sending tenant's own origin (subdomain or custom domain) per send; null, a throw or a non-https value fall back to the app origin and never fail the send. The signed token now carries the mail's locale (notify option locale), so the confirmation, result and undo pages render in that language; tokens without it keep working and show English. A form post to the resubscribe route now answers with an HTML page, JSON callers are unchanged. After a committed address opt-out an app job declared with trigger on DeliveryHandlers.unsubscribeAddress receives addressHash, notificationType and channel (unsubscribeAddressPayloadSchema) with the tenant in ctx.triggeredBy.tenantId; hashUnsubscribeAddress(email) matches it to the app's own subscriber. UNSUBSCRIBE_PAGE_EN exports the English page texts, German and Spanish come with the locale packages."
+  },
+  {
+    "version": "0.366.0",
+    "type": "improvement",
+    "title": "Renaming a notification type keeps user preferences and address opt-outs",
+    "detail": "r.notification accepts renamedFrom, a list of former qualified names. Preferences and address opt-outs stored under a former name keep applying to the renamed notification, and a stored choice under the current name wins over one under a former name. New writes via setPreference and the unsubscribe and resubscribe handlers are stored under the current name, resubscribeAddress also lifts opt-outs under former names. Boot fails if an alias is a current notification name, is the wildcard, or is claimed by two notifications."
+  },
   {
     "version": "0.365.0",
     "type": "fix",

package/packages/bundled-features/src/delivery/channel-context.ts

@@ -153,6 +153,7 @@ export function buildChannelContext(
     sseBroker,
     tenantId,
     secrets,
+    config: tenantConfig,
     renderMail: createTemplateMailRenderer(db, registry, tenantId, tenantConfig),
     ...(filesForTenant !== undefined && {
       readAttachment: createEmailAttachmentReader(

package/packages/bundled-features/src/delivery/db/queries/address-opt-outs.ts

@@ -16,14 +16,18 @@ export function addressOptOutKey(addressHash: string, channel: string): AddressO
 export async function selectOptedOutAddresses(
   db: DbConnection,
   tenantId: TenantId,
-  notificationType: string,
+  notificationTypeNames: readonly string[],
   addressHashes: readonly string[],
 ): Promise<ReadonlySet<AddressOptOutKey>> {
   if (addressHashes.length === 0) return new Set();
   const rows = await selectMany<{ readonly addressHash: string; readonly channel: string }>(
     db,
     notificationAddressOptOutsTable,
-    { tenantId, notificationType, addressHash: { in: addressHashes } },
+    {
+      tenantId,
+      notificationType: { in: notificationTypeNames },
+      addressHash: { in: addressHashes },
+    },
   );
   return new Set(rows.map((row) => addressOptOutKey(row.addressHash, row.channel)));
 }

package/packages/bundled-features/src/delivery/db/queries/preferences.ts

@@ -13,7 +13,7 @@ export async function selectNotificationPreferences(
   db: DbConnection,
   tenantId: TenantId,
   userId: string,
-  notificationType: string,
+  notificationTypeNames: readonly string[],
   channelName: string,
 ): Promise<readonly NotificationPreferenceRow[]> {
   return unsafeReadRetrying<NotificationPreferenceRow>(
@@ -23,10 +23,10 @@ export async function selectNotificationPreferences(
      WHERE tenant_id = $1
        AND user_id = $2
        AND (
-         (notification_type = $3 AND channel = $4)
+         (notification_type = ANY($3::text[]) AND channel = $4)
          OR (notification_type = '*' AND channel = $4)
-         OR (notification_type = $3 AND channel = '*')
+         OR (notification_type = ANY($3::text[]) AND channel = '*')
        )`,
-    [tenantId, userId, notificationType, channelName],
+    [tenantId, userId, notificationTypeNames, channelName],
   );
 }

package/packages/bundled-features/src/delivery/delivery-service.ts

@@ -37,6 +37,7 @@ import {
   DeliveryJobs,
   deliveryIdempotencyRedisKey,
   deliveryPriorityRank,
+  EMAIL_CHANNEL_NAME,
 } from "./constants.js";
 import {
   type AddressOptOutKey,
@@ -44,6 +45,7 @@ import {
   selectOptedOutAddresses,
 } from "./db/queries/address-opt-outs.js";
 import { selectNotificationPreferences } from "./db/queries/preferences.js";
+import { notificationTypeNames } from "./notification-type-aliases.js";
 import {
   type ChannelContext,
   type ChannelMessage,
@@ -54,6 +56,12 @@ import {
   isDeliveryChannelPlugin,
   type RenderedMessage,
 } from "./types.js";
+import {
+  buildUnsubscribeUrl,
+  type UnsubscribeLinkConfig,
+  type UnsubscribeLinkRecipient,
+  unsubscribeLinkOrigin,
+} from "./unsubscribe-link.js";
 
 export function redactedMessageOf(err: unknown): string {
   return redactErrorText(err instanceof Error ? err.message : String(err));
@@ -96,6 +104,9 @@ export type DeliveryServiceOptions = {
   // absent means an unattributed warn log (see fallbackEscapeHatchReporter).
   readonly escapeHatchAuditSink?: EscapeHatchAuditSink;
   readonly log?: Logger;
+  // Signs `data.unsubscribeUrl` for email notifications declared with `unsubscribe: true`.
+  // The secret must be the one `createUnsubscribeRoutes` verifies with.
+  readonly unsubscribeLinks?: UnsubscribeLinkConfig;
 };
 
 // Build channel list from registry extension usages
@@ -127,6 +138,7 @@ export function createDeliveryService(options: DeliveryServiceOptions): Delivery
     tenantConfigFor,
     escapeHatchAuditSink,
     log,
+    unsubscribeLinks,
   } = options;
   const idemRedis = idempotencyRedis ?? rateLimit?.redis;
   const logError = createFallbackLogger("delivery", log);
@@ -453,6 +465,37 @@ export function createDeliveryService(options: DeliveryServiceOptions): Delivery
     }
   }
 
+  // A caller-supplied unsubscribeUrl wins; the recipient comes from the server-side notify
+  // context, never from the notification data.
+  async function withUnsubscribeUrl(
+    message: ChannelMessage,
+    channelName: string,
+    recipient: UnsubscribeLinkRecipient,
+    channelCtx: ChannelContext,
+  ): Promise<ChannelMessage> {
+    if (!unsubscribeLinks || channelName !== EMAIL_CHANNEL_NAME) return message;
+    if (registry.getAllNotifications().get(message.notificationType)?.unsubscribe !== true) {
+      return message;
+    }
+    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 unsubscribeUrl = await buildUnsubscribeUrl(unsubscribeLinks, origin, recipient, {
+      tenantId: channelCtx.tenantId,
+      notificationType: message.notificationType,
+      channel: channelName,
+      locale: message.locale,
+    });
+    return unsubscribeUrl === undefined
+      ? message
+      : { ...message, data: { ...message.data, unsubscribeUrl } };
+  }
+
   function buildMessage(
     notificationType: string,
     data: Readonly<Record<string, unknown>> | undefined,
@@ -503,7 +546,12 @@ export function createDeliveryService(options: DeliveryServiceOptions): Delivery
       const addressHash = hashUnsubscribeAddress(address);
       if (addressHash !== undefined) addressHashes.add(addressHash);
     }
-    return selectOptedOutAddresses(run.db, tenantId, notificationType, [...addressHashes]);
+    return selectOptedOutAddresses(
+      run.db,
+      tenantId,
+      notificationTypeNames(registry, notificationType),
+      [...addressHashes],
+    );
   }
 
   function isAddressSuppressed(
@@ -617,7 +665,7 @@ export function createDeliveryService(options: DeliveryServiceOptions): Delivery
       run.db,
       tenantId,
       userId,
-      notificationType,
+      notificationTypeNames(registry, notificationType),
       channelName,
     );
 
@@ -629,6 +677,15 @@ export function createDeliveryService(options: DeliveryServiceOptions): Delivery
     );
     if (exact) return exact.enabled;
 
+    // Rows stored under a former name: the user's choice from before the rename
+    const aliasExact = prefs.filter(
+      (p) =>
+        p.notificationType !== "*" &&
+        p.notificationType !== notificationType &&
+        p.channel === channelName,
+    );
+    if (aliasExact.length > 0) return !aliasExact.some((p) => p.enabled === false);
+
     // Only wildcards matched: any disabled entry disables delivery (deterministic
     // and conservative — DB ordering no longer decides the outcome).
     return !prefs.some((p) => p.enabled === false);
@@ -729,7 +786,12 @@ export function createDeliveryService(options: DeliveryServiceOptions): Delivery
           run,
           channel,
           address,
-          message,
+          message: await withUnsubscribeUrl(
+            message,
+            channel.name,
+            { kind: "user", userId },
+            channelCtx,
+          ),
           channelCtx,
           tenantId,
           recipientId: userId,
@@ -827,7 +889,12 @@ export function createDeliveryService(options: DeliveryServiceOptions): Delivery
           run,
           channel,
           address,
-          message,
+          message: await withUnsubscribeUrl(
+            message,
+            channel.name,
+            { kind: "address", address },
+            channelCtx,
+          ),
           channelCtx,
           tenantId,
           recipientId,

package/packages/bundled-features/src/delivery/feature.ts

@@ -61,7 +61,7 @@ export function createDeliveryFeature(options?: DeliveryFeatureOptions): Feature
   const attemptLogRetentionDays = resolveAttemptLogRetentionDays(options?.attemptLogRetentionDays);
   return defineFeature("delivery", (r) => {
     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.',
+      "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` (`runProdApp` 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. 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",
@@ -70,18 +70,22 @@ export function createDeliveryFeature(options?: DeliveryFeatureOptions): Feature
     });
     r.systemScope();
     // delivery-log's tenantId column has refEntity: "tenant:tenant" (boot-checked).
-    r.requires("tenant");
+    r.requires({ features: ["tenant"] });
     // Backing table: the (tenant,user,type,channel) uniqueIndex lives only on
     // the physical table, not on the entity fields, so the generator would
     // otherwise omit it → duplicate preference rows on concurrent upserts.
-    r.entity("notification-preference", notificationPreferenceEntity, {
-      table: notificationPreferencesTable,
+    r.entity({
+      name: "notification-preference",
+      ...notificationPreferenceEntity,
+      backingTable: notificationPreferencesTable,
     });
     // Same ride-along reason as notification-preference above: the
     // (tenant,addressHash,type,channel) uniqueIndex lives only on the
     // physical table.
-    r.entity("notification-address-opt-out", notificationAddressOptOutEntity, {
-      table: notificationAddressOptOutsTable,
+    r.entity({
+      name: "notification-address-opt-out",
+      ...notificationAddressOptOutEntity,
+      backingTable: notificationAddressOptOutsTable,
     });
     r.storeTable(deliveryAttemptsTableMeta, {
       reason: "read_side.delivery_attempt_log",

package/packages/bundled-features/src/delivery/handlers/resubscribe-address.write.ts

@@ -2,6 +2,7 @@ import { access, defineWriteHandler } from "@cosmicdrift/kumiko-framework/engine
 import { InternalError } from "@cosmicdrift/kumiko-framework/errors";
 import * as z from "zod";
 import { removeAddressOptOut } from "../address-opt-out.js";
+import { currentNotificationType, notificationTypeNames } from "../notification-type-aliases.js";
 
 export const resubscribeAddressWrite = defineWriteHandler({
   name: "resubscribeAddress",
@@ -20,7 +21,8 @@ export const resubscribeAddressWrite = defineWriteHandler({
   description:
     "Removes a no-account address opt-out for one notificationType/channel combination; dispatched by the signed resubscribe route, not meant for UI callers.",
   handler: async (event, ctx) => {
-    const { addressHash, notificationType, channel } = event.payload;
+    const { addressHash, channel } = event.payload;
+    const notificationType = currentNotificationType(ctx.registry, event.payload.notificationType);
     const { tenantId } = event.user;
 
     if (!ctx.systemDb) {
@@ -30,13 +32,15 @@ export const resubscribeAddressWrite = defineWriteHandler({
     }
     const db = ctx.systemDb.assertTenantMatch(tenantId);
 
-    const result = await removeAddressOptOut(db, event.user, {
-      tenantId,
-      addressHash,
-      notificationType,
-      channel,
-    });
-    if (!result.isSuccess) return result;
+    for (const name of notificationTypeNames(ctx.registry, notificationType)) {
+      const result = await removeAddressOptOut(db, event.user, {
+        tenantId,
+        addressHash,
+        notificationType: name,
+        channel,
+      });
+      if (!result.isSuccess) return result;
+    }
     return { isSuccess: true, data: { notificationType, channel } };
   },
 });

package/packages/bundled-features/src/delivery/handlers/resubscribe-user.write.ts

@@ -1,6 +1,7 @@
 import { access, defineWriteHandler } 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 { upsertPreference } from "../upsert-preference.js";
 
 export const resubscribeUserWrite = defineWriteHandler({
@@ -18,7 +19,8 @@ export const resubscribeUserWrite = defineWriteHandler({
   description:
     "Re-enables one notification type and channel combination for the userId carried in a verified unsubscribe token; dispatched by the signed resubscribe route, not meant for UI callers.",
   handler: async (event, ctx) => {
-    const { userId, notificationType, channel } = event.payload;
+    const { userId, channel } = event.payload;
+    const notificationType = currentNotificationType(ctx.registry, event.payload.notificationType);
     const { tenantId } = event.user;
 
     if (!ctx.systemDb) {

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

@@ -1,6 +1,7 @@
 import { defineWriteHandler } 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 { upsertPreference } from "../upsert-preference.js";
 
 export const setPreferenceWrite = defineWriteHandler({
@@ -21,7 +22,8 @@ export const setPreferenceWrite = defineWriteHandler({
   description:
     "Enables or disables one notification type and channel combination for the calling user, where either side may be the wildcard * as a catch-all; use it when a user changes their own notification settings.",
   handler: async (event, ctx) => {
-    const { notificationType, channel, enabled } = event.payload;
+    const { channel, enabled } = event.payload;
+    const notificationType = currentNotificationType(ctx.registry, event.payload.notificationType);
     const { id: userId, tenantId } = event.user;
 
     // delivery runs in system-scope (feature.ts r.systemScope()) — ctx.systemDb