@cosmicdrift/kumiko-samples 0.351.0 → 0.352.0

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

@@ -0,0 +1,51 @@
+import type {
+  PreTransactionReservation,
+  ReservationHandle,
+} from "@cosmicdrift/kumiko-types/handlers";
+
+type ReservationOutcome = Awaited<ReturnType<PreTransactionReservation>>;
+
+function toHandle(outcome: ReservationOutcome): ReservationHandle {
+  if (outcome === undefined)
+    return { release: async () => {}, confirmInTransaction: async () => {} };
+  if (typeof outcome === "function") {
+    return { release: outcome, confirmInTransaction: async () => {} };
+  }
+  return outcome;
+}
+
+// Runs `inner` first, then `own`; a failing `own` gives the inner reservation back before it
+// throws. Release goes in reverse order, confirm covers both.
+export function chainReservations(
+  inner: PreTransactionReservation | undefined,
+  own: PreTransactionReservation,
+): PreTransactionReservation {
+  if (!inner) return own;
+  return async (event, ctx) => {
+    const innerHandle = toHandle(await inner(event, ctx));
+    let ownHandle: ReservationHandle;
+    try {
+      ownHandle = toHandle(await own(event, ctx));
+    } catch (error) {
+      try {
+        await innerHandle.release();
+      } catch (releaseError) {
+        ctx.log?.error("releasing the inner cap reservation failed", { error: releaseError });
+      }
+      throw error;
+    }
+    return {
+      release: async () => {
+        try {
+          await ownHandle.release();
+        } finally {
+          await innerHandle.release();
+        }
+      },
+      confirmInTransaction: async (confirm) => {
+        await innerHandle.confirmInTransaction(confirm);
+        await ownHandle.confirmInTransaction(confirm);
+      },
+    };
+  };
+}

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

@@ -24,6 +24,9 @@ export type CapLimitContext = {
   readonly config?: ConfigAccessor;
 };
 
+// What the cap guards need from a write handler's ctx.
+export type CapGuardContext = CapLimitContext & { readonly db: TenantDb };
+
 export type StockCapSpec<TCaps> = {
   readonly table: SchemaTable | EntityTableMeta;
   readonly limit: (caps: TCaps) => number;

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

@@ -0,0 +1,53 @@
+import {
+  defineUnmanagedTable,
+  type EntityTableMeta,
+  index,
+  instant,
+  integer,
+  table as pgTable,
+  text,
+  uuid,
+} from "@cosmicdrift/kumiko-framework/db";
+
+const CAP_RESERVATIONS_TENANT_CAP_EXPIRES_INDEX =
+  "store_cap_reservations_tenant_id_cap_name_expires_at_idx";
+
+// One row per capacity that was booked before a handler transaction and is not settled yet. The
+// handler transaction deletes it on its own commit (confirm); a release or the TTL sweep deletes it
+// together with the counter decrement. Unmanaged: the rows are a coordination aid, not state with
+// an event history.
+export const capReservationsTable = pgTable(
+  "store_cap_reservations",
+  {
+    id: uuid("id").primaryKey(),
+    tenantId: uuid("tenant_id").notNull(),
+    capName: text("cap_name").notNull(),
+    kind: text("kind").notNull().$type<"calendar" | "rolling">(),
+    // Calendar only: raw string the counter's aggregate id was derived from; a normalized instant could point at another counter.
+    periodStartIso: text("period_start_iso"),
+    amount: integer("amount").notNull(),
+    expiresAt: instant("expires_at").notNull(),
+    createdAt: instant("created_at").notNull(),
+  },
+  (t) => [index(CAP_RESERVATIONS_TENANT_CAP_EXPIRES_INDEX).on(t.tenantId, t.capName, t.expiresAt)],
+);
+
+export const capReservationsTableMeta: EntityTableMeta = defineUnmanagedTable({
+  tableName: "store_cap_reservations",
+  indexes: [
+    {
+      name: CAP_RESERVATIONS_TENANT_CAP_EXPIRES_INDEX,
+      columns: ["tenant_id", "cap_name", "expires_at"],
+    },
+  ],
+  columns: [
+    { name: "id", pgType: "uuid", notNull: true, primaryKey: true },
+    { name: "tenant_id", pgType: "uuid", notNull: true },
+    { name: "cap_name", pgType: "text", notNull: true },
+    { name: "kind", pgType: "text", notNull: true },
+    { name: "period_start_iso", pgType: "text", notNull: false },
+    { name: "amount", pgType: "integer", notNull: true },
+    { name: "expires_at", pgType: "timestamptz", notNull: true },
+    { name: "created_at", pgType: "timestamptz", notNull: true },
+  ],
+});

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

@@ -0,0 +1,70 @@
+// Per-tier bounds on a single written number (e.g. a retention period or a page size),
+// next to the stock-cap guard, which bounds how many rows may exist.
+
+import type { TenantDb } from "@cosmicdrift/kumiko-framework/db";
+import type { WriteHandlerDef } from "@cosmicdrift/kumiko-framework/engine";
+import {
+  UnprocessableError,
+  type WriteFailure,
+  writeFailure,
+} from "@cosmicdrift/kumiko-framework/errors";
+import { readPayloadField } from "./payload-field.js";
+import type { CapGuardContext, CapLimitContext } from "./stock-cap-guard.js";
+
+export type ValueCapSpec<TCaps> = {
+  readonly field: string;
+  /** `undefined` = no lower bound for this tier. */
+  readonly min?: (caps: TCaps) => number | undefined;
+  /** `undefined` = no upper bound for this tier. */
+  readonly max?: (caps: TCaps) => number | undefined;
+  readonly code: string;
+  readonly i18nKey: string;
+};
+
+export type ValueCapGuard<TCaps> = {
+  readonly checkValueCap: (
+    ctx: CapGuardContext,
+    value: unknown,
+    spec: ValueCapSpec<TCaps>,
+  ) => Promise<WriteFailure | null>;
+  readonly withValueCap: (handler: WriteHandlerDef, spec: ValueCapSpec<TCaps>) => WriteHandlerDef;
+};
+
+function isOutOfBounds(value: number, min: number | undefined, max: number | undefined): boolean {
+  return (min !== undefined && value < min) || (max !== undefined && value > max);
+}
+
+export function createValueCapGuard<TCaps>(
+  resolveTierCaps: (db: TenantDb, context: CapLimitContext) => Promise<TCaps>,
+): ValueCapGuard<TCaps> {
+  async function checkValueCap(
+    ctx: CapGuardContext,
+    value: unknown,
+    spec: ValueCapSpec<TCaps>,
+  ): Promise<WriteFailure | null> {
+    // skip: an absent or non-numeric value is the schema's business, not a cap violation.
+    if (typeof value !== "number") return null;
+    const caps = await resolveTierCaps(ctx.db, ctx.config ? { config: ctx.config } : {});
+    const min = spec.min?.(caps);
+    const max = spec.max?.(caps);
+    if (!isOutOfBounds(value, min, max)) return null;
+    return writeFailure(
+      new UnprocessableError(spec.code, {
+        i18nKey: spec.i18nKey,
+        details: { field: spec.field, value, min, max },
+      }),
+    );
+  }
+
+  function withValueCap(handler: WriteHandlerDef, spec: ValueCapSpec<TCaps>): WriteHandlerDef {
+    return {
+      ...handler,
+      handler: async (event, ctx) => {
+        const failure = await checkValueCap(ctx, readPayloadField(event.payload, spec.field), spec);
+        return failure ?? handler.handler(event, ctx);
+      },
+    };
+  }
+
+  return { checkValueCap, withValueCap };
+}

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/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/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,