@cosmicdrift/kumiko-samples 0.351.0 → 0.353.0

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

@@ -6,19 +6,20 @@
 // the wrapper keeps the pattern explicit and co-located.
 //
 // **Calendar reservation:** the wrapper only declares the cap; the dispatcher runs the
-// reservation (reserveBeforeTransaction) before the handler transaction opens, in its own short
-// committed write, and releases it after that transaction ended without committing (rollback,
-// failure result, failed COMMIT). No connection is held across the handler, so capped requests
-// cannot exhaust the pool, and the counter stream is not locked while the handler runs. If a
-// COMMIT fails with an unknown outcome the release can under-count; a wrapped handler must not
-// book the same counter itself. Reached through a nested ctx.write the cap is not reserved, so
-// the dispatcher rejects that call unless the top-level batch reserved the same handler.
+// reservation (reserveBeforeTransaction) after all pre-handler gates and before the handler
+// transaction opens, in its own short committed write (counter increment plus a
+// store_cap_reservations row). The handler transaction deletes the row on its own commit; a release
+// after a rollback, failure result or failed COMMIT only gives back what is still booked, so an
+// unknown COMMIT outcome cannot under-count. No connection is held across the handler. Rows a
+// crashed process left behind expire after CAP_RESERVATION_TTL_MINUTES and are given back before the
+// next reserve of the same cap. Reached through a nested ctx.write the cap is not reserved, so the
+// dispatcher rejects that call unless the top-level batch reserved the same handler.
 //
-// Rolling booking still dispatches the SystemAdmin-only increment-rolling
-// handler and has no reservation: it would need a compensating event type,
-// a changed readRollingCapUsage and a version-guarded append behind the
-// SystemAdmin dispatch. Rolling callers need a SystemAdmin identity until
-// cap-counter declares an explicit foreign-booking opt-in.
+// The wrapper spreads the wrapped handler and chains its reserveBeforeTransaction: inner reserves
+// first, release runs in reverse, and an outer failure gives the inner reservation back.
+//
+// Rolling caps reserve the same way: a version-guarded `rolling-incremented` append plus a
+// reservation row, undone by a `rolling-released` event. The window sum is incremented minus released.
 //
 // No automatic markSoftWarned here — that's inside enforceCapAndMaybeNotify
 // (enforce-cap.ts).
@@ -28,9 +29,11 @@ import type {
   WriteEvent,
   WriteHandlerDef,
 } from "@cosmicdrift/kumiko-framework/engine";
-import { reraiseAsKumikoError } from "@cosmicdrift/kumiko-framework/errors";
-import { bookCapUsage, releaseCapUsage } from "./book-cap-usage.js";
-import { CapCounterHandlers } from "./constants.js";
+import {
+  releaseExpiredCapReservations,
+  reserveCalendarCap,
+  reserveRollingCap,
+} from "./cap-reservation.js";
 import {
   assertBelowHardCap,
   type CapToleranceProfileName,
@@ -38,6 +41,7 @@ import {
   enforceRollingCapAndMaybeNotify,
   type SoftHitNotifier,
 } from "./enforce-cap.js";
+import { chainReservations } from "./reservation-chain.js";
 
 // =============================================================================
 // Calendar-Period-Wrapper
@@ -85,39 +89,31 @@ export function withCapEnforcement(
 ): WriteHandlerDef {
   return {
     ...handler,
-    reserveBeforeTransaction: async (event, ctx) => {
-      const cap = await capResolver(event, ctx);
-
-      await enforceCapAndMaybeNotify(ctx, {
-        capName: cap.capName,
-        periodStartIso: cap.periodStartIso,
-        limit: cap.limit,
-        profile: cap.profile,
-        notify: cap.notify,
-        markSoftWarnedOutsideTransaction: true,
-        ...(cap.amount !== undefined && { amount: cap.amount }),
-      });
+    reserveBeforeTransaction: chainReservations(
+      handler.reserveBeforeTransaction,
+      async (event, ctx) => {
+        const cap = await capResolver(event, ctx);
 
-      const amount = cap.amount ?? 1;
-      const reserved = await bookCapUsage(ctx, {
-        capName: cap.capName,
-        amount,
-        periodStartIso: cap.periodStartIso,
-        outsideTransaction: true,
-        guardCurrentValue: (currentValue) => assertBelowHardCap(currentValue + amount - 1, cap),
-      });
-      if (!reserved.isSuccess) throw reraiseAsKumikoError(reserved.error);
+        await releaseExpiredCapReservations(ctx, cap.capName);
+        await enforceCapAndMaybeNotify(ctx, {
+          capName: cap.capName,
+          periodStartIso: cap.periodStartIso,
+          limit: cap.limit,
+          profile: cap.profile,
+          notify: cap.notify,
+          markSoftWarnedOutsideTransaction: true,
+          ...(cap.amount !== undefined && { amount: cap.amount }),
+        });
 
-      return async () => {
-        const released = await releaseCapUsage(ctx, {
+        const amount = cap.amount ?? 1;
+        return reserveCalendarCap(ctx, {
           capName: cap.capName,
           amount,
           periodStartIso: cap.periodStartIso,
-          outsideTransaction: true,
+          guardCurrentValue: (currentValue) => assertBelowHardCap(currentValue + amount - 1, cap),
         });
-        if (!released.isSuccess) throw reraiseAsKumikoError(released.error);
-      };
-    },
+      },
+    ),
   };
 }
 
@@ -142,44 +138,41 @@ export type RollingCapResolver = (
 /**
  * Wrap a write-handler with rolling-window cap-enforcement.
  *
- * Same flow as `withCapEnforcement` but uses
- * `enforceRollingCapAndMaybeNotify` + dispatches
- * `cap-counter:write:increment-rolling` post-success.
+ * Same flow as `withCapEnforcement` but uses `enforceRollingCapAndMaybeNotify` and reserves by
+ * appending a `rolling-incremented` event before the handler transaction; a release appends
+ * `rolling-released`.
  *
- * **Notification-Storm-Caveat:** rolling-counter trackt KEIN
- * lastSoftWarnedAt — der Notifier feuert bei JEDEM Call solange
- * der counter im soft-Bereich ist. Caller sollte einen TTL-Cache
- * (`Map<capName, lastNotifiedAt>`) im notify-callback einbauen.
+ * Rolling counters track no lastSoftWarnedAt, so the notifier fires on every call while usage
+ * sits in the soft range; throttle inside the notify callback (e.g. a per-capName TTL cache).
  */
 export function withRollingCapEnforcement(
   handler: WriteHandlerDef,
   capResolver: RollingCapResolver,
 ): WriteHandlerDef {
   return {
-    name: handler.name,
-    schema: handler.schema,
-    access: handler.access,
-    handler: async (event, ctx) => {
-      const cap = await capResolver(event, ctx);
-
-      await enforceRollingCapAndMaybeNotify(ctx, {
-        capName: cap.capName,
-        windowDays: cap.windowDays,
-        limit: cap.limit,
-        profile: cap.profile,
-        notify: cap.notify,
-      });
-
-      const result = await handler.handler(event, ctx);
+    ...handler,
+    reserveBeforeTransaction: chainReservations(
+      handler.reserveBeforeTransaction,
+      async (event, ctx) => {
+        const cap = await capResolver(event, ctx);
 
-      if (result.isSuccess) {
-        await ctx.write(CapCounterHandlers.incrementRolling, {
+        await releaseExpiredCapReservations(ctx, cap.capName);
+        await enforceRollingCapAndMaybeNotify(ctx, {
           capName: cap.capName,
-          amount: cap.amount ?? 1,
+          windowDays: cap.windowDays,
+          limit: cap.limit,
+          profile: cap.profile,
+          notify: cap.notify,
         });
-      }
 
-      return result;
-    },
+        const amount = cap.amount ?? 1;
+        return reserveRollingCap(ctx, {
+          capName: cap.capName,
+          windowDays: cap.windowDays,
+          amount,
+          guardCurrentValue: (usage) => assertBelowHardCap(usage + amount - 1, cap),
+        });
+      },
+    ),
   };
 }

package/packages/bundled-features/src/cap-overview/access.ts

@@ -1,4 +1,4 @@
-import { access } from "@cosmicdrift/kumiko-framework/engine";
+import { access, BUILT_IN_MEMBERSHIP_ROLES } from "@cosmicdrift/kumiko-framework/engine";
 
 // Usage numbers are an operator concern by default; wider visibility is an
 // explicit `usageVisibleTo` opt-in on createCapOverviewFeature. The my-caps
@@ -9,14 +9,7 @@ export const DEFAULT_CAP_USAGE_ROLES: readonly string[] = access.roles(...access
 // Roles the engine itself knows (role-assignment.ts ranks). App-declared roles
 // (assignableRole) only exist once the registry is composed, which is after
 // this feature is defined, so they cannot be validated here.
-const BUILT_IN_USAGE_VISIBLE_ROLES: ReadonlySet<string> = new Set([
-  "User",
-  "Member",
-  "Editor",
-  "Admin",
-  "TenantAdmin",
-  "SystemAdmin",
-]);
+const BUILT_IN_USAGE_VISIBLE_ROLES: ReadonlySet<string> = new Set(BUILT_IN_MEMBERSHIP_ROLES);
 
 export function resolveCapUsageRoles(
   usageVisibleTo: readonly string[] | undefined,

package/packages/bundled-features/src/cap-overview/handlers/tenant-caps-list.query.ts

@@ -10,7 +10,7 @@ import { InternalError, ValidationError } from "@cosmicdrift/kumiko-framework/er
 import * as z from "zod";
 import { subscriptionsProjectionTable } from "../../billing-foundation/index.js";
 import type { CapLimitContext } from "../../cap-counter/index.js";
-import { tenantTable } from "../../tenant/index.js";
+import { decryptTenantNames, tenantTable } from "../../tenant/index.js";
 import { tierAssignmentEntity } from "../../tier-engine/index.js";
 import { capFieldName } from "../constants.js";
 import type { CapSpec, CapUsage } from "../types.js";
@@ -174,7 +174,10 @@ export function createTenantCapsListQuery(caps: readonly CapSpec[], listCaps: re
         "cap-overview:tenant-caps:list — SystemAdmin platform-wide tenant overview",
       );
 
-      const tenants = await selectMany<TenantRow>(db, tenantTable, {});
+      const tenants = await decryptTenantNames(
+        await selectMany<TenantRow>(db, tenantTable, {}),
+        "cap-overview:tenant-caps:list",
+      );
       const assignments = await selectMany<TierAssignmentRow>(db, tierAssignmentTable, {});
       const subscriptions = await selectMany<SubscriptionRow>(db, subscriptionsProjectionTable, {});
 

package/packages/bundled-features/src/cap-overview/handlers/tenant-options.query.ts

@@ -2,7 +2,7 @@ import { selectMany } from "@cosmicdrift/kumiko-framework/bun-db";
 import { defineQueryHandler } from "@cosmicdrift/kumiko-framework/engine";
 import { InternalError } from "@cosmicdrift/kumiko-framework/errors";
 import * as z from "zod";
-import { tenantTable } from "../../tenant/index.js";
+import { decryptTenantNames, tenantTable } from "../../tenant/index.js";
 
 type TenantRow = { readonly id: string; readonly name: string };
 
@@ -22,14 +22,11 @@ export const tenantOptionsQuery = defineQueryHandler({
     const db = ctx.systemDb.acknowledgeCrossTenant(
       "cap-overview:tenant-options — SystemAdmin dashboard tenant-filter options",
     );
-    const tenants = await selectMany<TenantRow>(
-      db,
-      tenantTable,
-      {},
-      {
-        orderBy: { col: "name", direction: "asc" },
-      },
+    const tenants = await decryptTenantNames(
+      await selectMany<TenantRow>(db, tenantTable, {}),
+      "cap-overview:tenant-options",
     );
-    return { rows: tenants.map((tenant) => ({ value: tenant.id, label: tenant.name })) };
+    const sorted = [...tenants].sort((a, b) => a.name.localeCompare(b.name));
+    return { rows: sorted.map((tenant) => ({ value: tenant.id, label: tenant.name })) };
   },
 });

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

@@ -50,6 +50,7 @@ export function createChannelDiscordFeature(
     r.translations({ keys: { "delivery.channel.discord": { en: "Discord" } } });
     r.useExtension(DELIVERY_CHANNEL_EXTENSION, "discord", {
       mode: channel.mode,
+      addressKind: "connection-name",
       send: channel.send,
     });
   });

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

@@ -44,6 +44,7 @@ export function createChannelSlackFeature(options: SlackChannelOptions = {}): Fe
     r.translations({ keys: { "delivery.channel.slack": { en: "Slack" } } });
     r.useExtension(DELIVERY_CHANNEL_EXTENSION, "slack", {
       mode: channel.mode,
+      addressKind: "connection-name",
       send: channel.send,
     });
   });

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

@@ -48,6 +48,7 @@ export function createChannelTeamsFeature(options: TeamsChannelOptions = {}): Fe
     r.translations({ keys: { "delivery.channel.teams": { en: "Microsoft Teams" } } });
     r.useExtension(DELIVERY_CHANNEL_EXTENSION, "teams", {
       mode: channel.mode,
+      addressKind: "connection-name",
       send: channel.send,
     });
   });

package/packages/bundled-features/src/compliance-profiles-ops/handlers/tenants-missing-profile.query.ts

@@ -3,7 +3,7 @@ import { defineQueryHandler, type TenantId } from "@cosmicdrift/kumiko-framework
 import { InternalError } from "@cosmicdrift/kumiko-framework/errors";
 import * as z from "zod";
 import { tenantComplianceProfileTable } from "../../compliance-profiles/index.js";
-import { tenantTable } from "../../tenant/index.js";
+import { decryptTenantNames, tenantTable } from "../../tenant/index.js";
 
 // SystemAdmin platform-wide counterpart to needs-profile (#2089).
 //
@@ -34,9 +34,10 @@ export const tenantsMissingProfileQuery = defineQueryHandler({
       "platform operator scans every tenant for a missing compliance-profile selection",
     );
 
-    const tenants = await db.selectMany<{ id: TenantId; name: string }>(tenantTable, {
-      isEnabled: true,
-    });
+    const tenants = await decryptTenantNames(
+      await db.selectMany<{ id: TenantId; name: string }>(tenantTable, { isEnabled: true }),
+      "compliance-profiles-ops:tenants-missing-profile",
+    );
     const profileRows = await db.selectMany<{ tenantId: TenantId }>(
       tenantComplianceProfileTable,
       {},

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

@@ -13,8 +13,10 @@ import { hasConfigAccess } 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, with encrypted and secret-backed values masked; use it to inspect the current settings.",
-  schema: z.object({}),
+    "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(),
+  }),
   // Per-key read access enforced via hasConfigAccess inside the handler.
   access: {
     openToAll: {
@@ -37,7 +39,10 @@ export const valuesQuery = defineQueryHandler({
     const allKeys = registry.getAllConfigKeys();
     const keyDefs = new Map<string, ConfigKeyDefinition>();
     const filteredKeys: string[] = [];
+    const requestedKeys =
+      query.payload.keys === undefined ? undefined : new Set(query.payload.keys);
     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);
       filteredKeys.push(qualifiedKey);

package/packages/bundled-features/src/delivery/attempt-log-retention.ts

@@ -0,0 +1,40 @@
+import { deleteManyBatched } from "@cosmicdrift/kumiko-framework/bun-db";
+import type { DbConnection } from "@cosmicdrift/kumiko-framework/db";
+import { type PruneEventsOptions, pruneEvents } from "@cosmicdrift/kumiko-framework/pipeline";
+import { deliveryAttemptsTable } from "./tables.js";
+
+export const DEFAULT_ATTEMPT_LOG_RETENTION_DAYS = 90;
+const ROW_DELETE_BATCH_SIZE = 1000;
+
+export type AttemptLogRetentionOptions = Pick<PruneEventsOptions, "olderThan" | "olderThanDays">;
+
+export function resolveAttemptLogRetentionDays(
+  option: number | false | undefined,
+): number | undefined {
+  if (option === false) return undefined;
+  const days = option ?? DEFAULT_ATTEMPT_LOG_RETENTION_DAYS;
+  if (!Number.isInteger(days) || days <= 0) {
+    throw new Error(
+      `delivery: attemptLogRetentionDays must be a positive integer or false, got ${String(option)}`,
+    );
+  }
+  return days;
+}
+
+// Prunes the attempt events first and then the projection rows older than the same cutoff: a
+// rebuild would not recreate rows whose events are gone, so they would otherwise stay forever.
+// A lagging event consumer makes pruneEvents throw ConsumerLagError before anything is deleted;
+// the caller retries on its next run.
+export async function runAttemptLogRetention(
+  db: DbConnection,
+  options: AttemptLogRetentionOptions,
+): Promise<{ readonly deletedEvents: number; readonly deletedRows: number }> {
+  const pruned = await pruneEvents(db, { ...options, aggregateTypes: ["deliveryAttempt"] });
+  const rows = await deleteManyBatched(
+    db,
+    deliveryAttemptsTable,
+    { createdAt: { lt: pruned.cutoff } },
+    { limit: ROW_DELETE_BATCH_SIZE },
+  );
+  return { deletedEvents: pruned.deletedCount, deletedRows: rows.deleted };
+}

package/packages/bundled-features/src/delivery/attempt-log.ts

@@ -8,9 +8,28 @@ import type { Registry } from "@cosmicdrift/kumiko-framework/engine";
 import { append, getStreamVersion } from "@cosmicdrift/kumiko-framework/event-store";
 import { runProjectionsForEvent } from "@cosmicdrift/kumiko-framework/pipeline";
 import { generateId } from "@cosmicdrift/kumiko-framework/utils";
-import { DELIVERY_ATTEMPT_EVENT } from "./constants.js";
+import { DELIVERY_ATTEMPT_EVENT, DELIVERY_CHANNEL_EXTENSION } from "./constants.js";
 import { deliveryAttemptSchema } from "./events.js";
-import type { DeliveryLogEntry } from "./types.js";
+import { maskRecipientAddress } from "./mask-recipient-address.js";
+import { type DeliveryLogEntry, isDeliveryChannelPlugin } from "./types.js";
+
+// Unknown channels count as personal: masking is the fail-closed default.
+function addressIsConnectionName(registry: Registry, channelName: string): boolean {
+  return registry
+    .getExtensionUsages(DELIVERY_CHANNEL_EXTENSION)
+    .some(
+      (usage) =>
+        usage.entityName === channelName &&
+        isDeliveryChannelPlugin(usage.options) &&
+        usage.options.addressKind === "connection-name",
+    );
+}
+
+function loggedAddress(registry: Registry, entry: DeliveryLogEntry): string | null {
+  return addressIsConnectionName(registry, entry.channel)
+    ? entry.recipientAddress
+    : maskRecipientAddress(entry.recipientAddress);
+}
 
 // Shared append + inline-projection write (low-level append() does not
 // auto-fire projections — only the dispatcher/executor paths do).
@@ -22,10 +41,14 @@ async function writeAttemptEvent(
   entry: DeliveryLogEntry,
 ): Promise<void> {
   const { tenantId, ...rest } = entry;
+  // Masked here, the only place attempt events are written, so no event or projection row ever holds the full address.
   // Schema-parse to match ctx.appendEvent's guarantee: a payload drift between
   // service/job + feature-registration fails loudly here instead of landing on
   // the events-table and crashing a consumer later.
-  const payload = deliveryAttemptSchema.parse(rest);
+  const payload = deliveryAttemptSchema.parse({
+    ...rest,
+    recipientAddress: loggedAddress(registry, entry),
+  });
   const stored = await append(db, {
     aggregateId: attemptId,
     aggregateType: "deliveryAttempt",

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

@@ -1,4 +1,16 @@
 [
+  {
+    "version": "0.352.0",
+    "type": "breaking",
+    "title": "Delivery attempt log stores masked recipient addresses; attempts older than 90 days are pruned",
+    "detail": "The log query, the export and the stored events show masked addresses, and the feature registers the daily attempt-log-retention job.",
+    "migration": "Read recipients from your own data, not from the attempt log, because it only shows masked addresses now. Set `attemptLogRetentionDays` on createDeliveryFeature to another number of days, or to `false` to keep the log, if 90 days does not fit. Schedule nothing extra, the feature registers the cron job itself. Existing full-address entries are removed by the retention job once they are older than the window, or erased when their user is forgotten."
+  },
+  {
+    "version": "0.352.0",
+    "type": "improvement",
+    "title": "Forgetting a user erases the recipient address of their delivery attempts in plaintext mode too, through an event that survives projection rebuilds"
+  },
   {
     "version": "0.343.0",
     "type": "improvement",

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

@@ -7,6 +7,7 @@ import { DELIVERY_FEATURE, DeliveryJobNames } from "./public-names.js";
 export const DELIVERY_CHANNEL_EXTENSION = "deliveryChannel" as const;
 
 export {
+  DELIVERY_ATTEMPT_ADDRESS_ERASED_EVENT,
   DELIVERY_ATTEMPT_EVENT,
   DELIVERY_CHANNEL_CELL_COMPONENT,
   DELIVERY_ERROR_CELL_COMPONENT,

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

@@ -36,3 +36,6 @@ export const deliveryAttemptSchema = z.object({
 });
 
 export type DeliveryAttemptPayload = z.infer<typeof deliveryAttemptSchema>;
+
+// No payload: the event only marks the attempt row's address as erased.
+export const deliveryAttemptAddressErasedSchema = z.object({});

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

@@ -1,12 +1,16 @@
-import { upsertByPk } from "@cosmicdrift/kumiko-framework/bun-db";
+import { updateMany, upsertByPk } from "@cosmicdrift/kumiko-framework/bun-db";
+import type { DbConnection } from "@cosmicdrift/kumiko-framework/db";
 import {
   access,
   defineFeature,
   type FeatureDefinition,
   i18nKey,
 } from "@cosmicdrift/kumiko-framework/engine";
+import { ConsumerLagError } from "@cosmicdrift/kumiko-framework/pipeline";
 import type * as z from "zod";
+import { resolveAttemptLogRetentionDays, runAttemptLogRetention } from "./attempt-log-retention.js";
 import {
+  DELIVERY_ATTEMPT_ADDRESS_ERASED_EVENT,
   DELIVERY_ATTEMPT_EVENT,
   DELIVERY_CHANNEL_CELL_COMPONENT,
   DELIVERY_CHANNEL_EXTENSION,
@@ -18,7 +22,7 @@ import {
   DeliveryJobNames,
   DeliveryQueries,
 } from "./constants.js";
-import { deliveryAttemptSchema } from "./events.js";
+import { deliveryAttemptAddressErasedSchema, deliveryAttemptSchema } from "./events.js";
 import { logQuery } from "./handlers/log.query.js";
 import { preferencesQuery } from "./handlers/preferences.query.js";
 import { resubscribeAddressWrite } from "./handlers/resubscribe-address.write.js";
@@ -44,10 +48,17 @@ export type DeliveryFeatureOptions = {
   // who in a line-of-business app is the operator, not the platform — pass
   // access.systemAdmin to keep this platform-only and out of their nav.
   readonly access?: readonly string[];
+  // Attempt events and log rows older than this many days are pruned by a daily job. Default 90;
+  // `false` keeps the log forever.
+  readonly attemptLogRetentionDays?: number | false;
 };
 
+const ATTEMPT_LOG_RETENTION_ESCAPE_HATCH_REASON =
+  "prunes delivery attempt events and log rows of every tenant";
+
 export function createDeliveryFeature(options?: DeliveryFeatureOptions): FeatureDefinition {
   const resolvedAccess = options?.access ?? access.admin;
+  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). 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.",
@@ -92,6 +103,12 @@ export function createDeliveryFeature(options?: DeliveryFeatureOptions): Feature
       },
     });
 
+    // Written when the recipient is forgotten: clears the address on the projection row and, being
+    // an event, survives a projection rebuild (a plain UPDATE would be undone by the replay).
+    r.defineEvent("attempt-address-erased", deliveryAttemptAddressErasedSchema, {
+      piiFields: "none",
+    });
+
     // Inline projection that materialises every delivery attempt into
     // deliveryAttemptsTable. Runs in the SAME transaction as the low-level
     // append(), so callers see their write immediately — no dispatcher
@@ -132,6 +149,14 @@ export function createDeliveryFeature(options?: DeliveryFeatureOptions): Feature
             },
           );
         },
+        [DELIVERY_ATTEMPT_ADDRESS_ERASED_EVENT]: async (event, tx) => {
+          await updateMany(
+            tx,
+            deliveryAttemptsTable,
+            { recipientAddress: null },
+            { id: event.aggregateId },
+          );
+        },
       },
     });
 
@@ -160,6 +185,29 @@ export function createDeliveryFeature(options?: DeliveryFeatureOptions): Feature
       deliverySendJob,
     );
 
+    if (attemptLogRetentionDays !== undefined) {
+      r.job({
+        name: DeliveryJobNames.attemptLogRetention,
+        trigger: { cron: "15 3 * * *" },
+        concurrency: "skip",
+        escapeHatch: { reason: ATTEMPT_LOG_RETENTION_ESCAPE_HATCH_REASON },
+        handler: async (_payload, ctx) => {
+          const db = ctx.db.unsafeRaw() as DbConnection; // @cast-boundary db-operator — jobs never run inside a DbTx
+          try {
+            const pruned = await runAttemptLogRetention(db, {
+              olderThanDays: attemptLogRetentionDays,
+            });
+            ctx.log.info("delivery attempt log pruned", pruned);
+          } catch (error) {
+            if (!(error instanceof ConsumerLagError)) throw error;
+            ctx.log.warn("delivery attempt log retention postponed: an event consumer lags", {
+              consumer: error.laggingConsumer,
+            });
+          }
+        },
+      });
+    }
+
     const handlers = {
       setPreference: r.writeHandler(setPreferenceWrite),
       unsubscribeAddress: r.writeHandler(unsubscribeAddressWrite),

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

@@ -1,4 +1,9 @@
 export { hashUnsubscribeAddress } from "./address-opt-out.js";
+export {
+  type AttemptLogRetentionOptions,
+  DEFAULT_ATTEMPT_LOG_RETENTION_DAYS,
+  runAttemptLogRetention,
+} from "./attempt-log-retention.js";
 export {
   type ChatWebhookChannelOptions,
   chatMessageText,
@@ -21,6 +26,7 @@ export {
 } from "./chat-webhook-sender.js";
 export type { DeliveryStatusValue } from "./constants.js";
 export {
+  DELIVERY_ATTEMPT_ADDRESS_ERASED_EVENT,
   DELIVERY_CHANNEL_EXTENSION,
   DELIVERY_FEATURE,
   DELIVERY_LOG_SCREEN_ID,

package/packages/bundled-features/src/delivery/mask-recipient-address.ts

@@ -0,0 +1,40 @@
+import { isPiiCiphertext } from "@cosmicdrift/kumiko-framework/crypto";
+
+const MASK = "***";
+const VISIBLE_TAIL_LENGTH = 4;
+const MIN_LENGTH_FOR_VISIBLE_TAIL = 8;
+
+function maskedUrl(address: string): string | undefined {
+  if (!URL.canParse(address)) return undefined;
+  const url = new URL(address);
+  if (url.protocol !== "http:" && url.protocol !== "https:") return undefined;
+  return `${url.origin}/${MASK}`;
+}
+
+function maskedEmail(address: string): string | undefined {
+  const parts = address.split("@");
+  const [local, domain] = parts;
+  if (parts.length !== 2 || !local || domain === undefined) return undefined;
+  return `${local.charAt(0)}${MASK}@${domain}`;
+}
+
+// The attempt log is an audit trail, not a contact list: it keeps enough of the address to
+// recognise where a message went, never the full value. URLs go first because webhook URLs can
+// contain an "@" and their path carries the secret.
+export function maskRecipientAddress(address: string | null): string | null {
+  if (address === null) return null;
+  return maskPlainAddress(address);
+}
+
+function maskPlainAddress(address: string): string {
+  // isPiiCiphertext is a type predicate; its false branch would narrow `string` to `never`.
+  if (isPiiCiphertext(address)) return MASK;
+  return maskStructuredOrTail(address);
+}
+
+function maskStructuredOrTail(address: string): string {
+  const structured = maskedUrl(address) ?? maskedEmail(address);
+  if (structured !== undefined) return structured;
+  if (address.length < MIN_LENGTH_FOR_VISIBLE_TAIL) return MASK;
+  return `${MASK}${address.slice(-VISIBLE_TAIL_LENGTH)}`;
+}

package/packages/bundled-features/src/delivery/public-names.ts

@@ -11,7 +11,7 @@ export const DeliveryHandlers = {
   resubscribeUser: "delivery:write:resubscribe-user",
 } as const;
 
-// Fixed so links mailed out today keep working — the unsubscribe route is
+// Stable path: links signed against it keep working. The unsubscribe route is
 // mounted at this exact path via `extraRoutes: [...createUnsubscribeRoutes(...)]`.
 export const DELIVERY_UNSUBSCRIBE_PATH = "/api/delivery/unsubscribe" as const;
 
@@ -61,4 +61,9 @@ export const DELIVERY_ATTEMPT_EVENT = "delivery:event:attempt" as const;
 export const DeliveryJobNames = {
   render: "render",
   send: "send",
+  attemptLogRetention: "attempt-log-retention",
 } as const;
+
+// Clears recipientAddress on an attempt row after its recipient was forgotten.
+export const DELIVERY_ATTEMPT_ADDRESS_ERASED_EVENT =
+  "delivery:event:attempt-address-erased" as const;