@cosmicdrift/kumiko-bundled-features 0.351.0 → 0.352.0

package/dist/cap-counter/with-cap-enforcement.d.ts

@@ -44,13 +44,11 @@ export type RollingCapResolver = (event: WriteEvent, ctx: HandlerContext) => Pro
 /**
  * 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 declare function withRollingCapEnforcement(handler: WriteHandlerDef, capResolver: RollingCapResolver): WriteHandlerDef;

package/dist/cap-counter/with-cap-enforcement.js

@@ -6,26 +6,26 @@
 // 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).
-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, enforceCapAndMaybeNotify, enforceRollingCapAndMaybeNotify, } from "./enforce-cap.js";
+import { chainReservations } from "./reservation-chain.js";
 /**
  * Wrap a write-handler with calendar-period cap-enforcement.
  *
@@ -39,8 +39,9 @@ import { assertBelowHardCap, enforceCapAndMaybeNotify, enforceRollingCapAndMaybe
 export function withCapEnforcement(handler, capResolver) {
     return {
         ...handler,
-        reserveBeforeTransaction: async (event, ctx) => {
+        reserveBeforeTransaction: chainReservations(handler.reserveBeforeTransaction, async (event, ctx) => {
             const cap = await capResolver(event, ctx);
+            await releaseExpiredCapReservations(ctx, cap.capName);
             await enforceCapAndMaybeNotify(ctx, {
                 capName: cap.capName,
                 periodStartIso: cap.periodStartIso,
@@ -51,47 +52,31 @@ export function withCapEnforcement(handler, capResolver) {
                 ...(cap.amount !== undefined && { amount: cap.amount }),
             });
             const amount = cap.amount ?? 1;
-            const reserved = await bookCapUsage(ctx, {
+            return reserveCalendarCap(ctx, {
                 capName: cap.capName,
                 amount,
                 periodStartIso: cap.periodStartIso,
-                outsideTransaction: true,
                 guardCurrentValue: (currentValue) => assertBelowHardCap(currentValue + amount - 1, cap),
             });
-            if (!reserved.isSuccess)
-                throw reraiseAsKumikoError(reserved.error);
-            return async () => {
-                const released = await releaseCapUsage(ctx, {
-                    capName: cap.capName,
-                    amount,
-                    periodStartIso: cap.periodStartIso,
-                    outsideTransaction: true,
-                });
-                if (!released.isSuccess)
-                    throw reraiseAsKumikoError(released.error);
-            };
-        },
+        }),
     };
 }
 /**
  * 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, capResolver) {
     return {
-        name: handler.name,
-        schema: handler.schema,
-        access: handler.access,
-        handler: async (event, ctx) => {
+        ...handler,
+        reserveBeforeTransaction: chainReservations(handler.reserveBeforeTransaction, async (event, ctx) => {
             const cap = await capResolver(event, ctx);
+            await releaseExpiredCapReservations(ctx, cap.capName);
             await enforceRollingCapAndMaybeNotify(ctx, {
                 capName: cap.capName,
                 windowDays: cap.windowDays,
@@ -99,14 +84,13 @@ export function withRollingCapEnforcement(handler, capResolver) {
                 profile: cap.profile,
                 notify: cap.notify,
             });
-            const result = await handler.handler(event, ctx);
-            if (result.isSuccess) {
-                await ctx.write(CapCounterHandlers.incrementRolling, {
-                    capName: cap.capName,
-                    amount: cap.amount ?? 1,
-                });
-            }
-            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/dist/channel-discord/feature.js

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

package/dist/channel-slack/feature.js

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

package/dist/channel-teams/feature.js

@@ -31,6 +31,7 @@ export function createChannelTeamsFeature(options = {}) {
         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/dist/compliance-profiles/schema/profile-selection.d.ts

@@ -18,6 +18,7 @@ export declare const tenantComplianceProfileEntity: import("@cosmicdrift/kumiko-
         } | undefined;
         readonly optionsQuery?: string;
         readonly optionsQueryPayload?: import("@cosmicdrift/kumiko-types/fields").OptionsQueryPayload;
+        readonly optionsAvailabilityQuery?: string;
     } & import("@cosmicdrift/kumiko-types/fields").ResolvedPiiFlags & {
         required: true;
     };
@@ -58,6 +59,7 @@ export declare const tenantComplianceProfileTable: import("@cosmicdrift/kumiko-f
         } | undefined;
         readonly optionsQuery?: string;
         readonly optionsQueryPayload?: import("@cosmicdrift/kumiko-types/fields").OptionsQueryPayload;
+        readonly optionsAvailabilityQuery?: string;
     } & import("@cosmicdrift/kumiko-types/fields").ResolvedPiiFlags & {
         required: true;
     };

package/dist/delivery/attempt-log-retention.d.ts

@@ -0,0 +1,9 @@
+import type { DbConnection } from "@cosmicdrift/kumiko-framework/db";
+import { type PruneEventsOptions } from "@cosmicdrift/kumiko-framework/pipeline";
+export declare const DEFAULT_ATTEMPT_LOG_RETENTION_DAYS = 90;
+export type AttemptLogRetentionOptions = Pick<PruneEventsOptions, "olderThan" | "olderThanDays">;
+export declare function resolveAttemptLogRetentionDays(option: number | false | undefined): number | undefined;
+export declare function runAttemptLogRetention(db: DbConnection, options: AttemptLogRetentionOptions): Promise<{
+    readonly deletedEvents: number;
+    readonly deletedRows: number;
+}>;

package/dist/delivery/attempt-log-retention.js

@@ -0,0 +1,23 @@
+import { deleteManyBatched } from "@cosmicdrift/kumiko-framework/bun-db";
+import { 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 function resolveAttemptLogRetentionDays(option) {
+    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, options) {
+    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/dist/delivery/attempt-log.d.ts

@@ -1,5 +1,5 @@
 import type { DbConnection } from "@cosmicdrift/kumiko-framework/db";
 import type { Registry } from "@cosmicdrift/kumiko-framework/engine";
-import type { DeliveryLogEntry } from "./types.js";
+import { type DeliveryLogEntry } from "./types.js";
 export declare function appendAttemptEvent(db: DbConnection, registry: Registry, attemptId: string, entry: DeliveryLogEntry): Promise<void>;
 export declare function logAttempt(db: DbConnection, registry: Registry, entry: DeliveryLogEntry): Promise<string>;

package/dist/delivery/attempt-log.js

@@ -5,16 +5,35 @@
 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 { maskRecipientAddress } from "./mask-recipient-address.js";
+import { isDeliveryChannelPlugin } from "./types.js";
+// Unknown channels count as personal: masking is the fail-closed default.
+function addressIsConnectionName(registry, channelName) {
+    return registry
+        .getExtensionUsages(DELIVERY_CHANNEL_EXTENSION)
+        .some((usage) => usage.entityName === channelName &&
+        isDeliveryChannelPlugin(usage.options) &&
+        usage.options.addressKind === "connection-name");
+}
+function loggedAddress(registry, entry) {
+    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).
 async function writeAttemptEvent(db, registry, attemptId, expectedVersion, entry) {
     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/dist/delivery/constants.d.ts

@@ -1,6 +1,6 @@
 import type { NotifyPriority } from "@cosmicdrift/kumiko-framework/engine";
 export declare const DELIVERY_CHANNEL_EXTENSION: "deliveryChannel";
-export { DELIVERY_ATTEMPT_EVENT, DELIVERY_CHANNEL_CELL_COMPONENT, DELIVERY_ERROR_CELL_COMPONENT, DELIVERY_FEATURE, DELIVERY_LOG_SCREEN_ID, DELIVERY_RESUBSCRIBE_PATH, DELIVERY_STATUS_CELL_COMPONENT, DELIVERY_TIME_CELL_COMPONENT, DELIVERY_TYPE_CELL_COMPONENT, DELIVERY_UNSUBSCRIBE_PATH, DeliveryErrors, DeliveryHandlers, DeliveryJobNames, DeliveryQueries, DeliveryStatus, type DeliveryStatusValue, } from "./public-names.js";
+export { DELIVERY_ATTEMPT_ADDRESS_ERASED_EVENT, DELIVERY_ATTEMPT_EVENT, DELIVERY_CHANNEL_CELL_COMPONENT, DELIVERY_ERROR_CELL_COMPONENT, DELIVERY_FEATURE, DELIVERY_LOG_SCREEN_ID, DELIVERY_RESUBSCRIBE_PATH, DELIVERY_STATUS_CELL_COMPONENT, DELIVERY_TIME_CELL_COMPONENT, DELIVERY_TYPE_CELL_COMPONENT, DELIVERY_UNSUBSCRIBE_PATH, DeliveryErrors, DeliveryHandlers, DeliveryJobNames, DeliveryQueries, DeliveryStatus, type DeliveryStatusValue, } from "./public-names.js";
 export declare const deliveryPriorityRank: Record<NotifyPriority, number>;
 export declare const DeliveryJobs: {
     readonly render: string;

package/dist/delivery/constants.js

@@ -3,7 +3,7 @@ import { DELIVERY_FEATURE, DeliveryJobNames } from "./public-names.js";
 // Extension-point name for delivery-channel plugins (channel-email,
 // channel-in-app, channel-push, ...).
 export const DELIVERY_CHANNEL_EXTENSION = "deliveryChannel";
-export { DELIVERY_ATTEMPT_EVENT, DELIVERY_CHANNEL_CELL_COMPONENT, DELIVERY_ERROR_CELL_COMPONENT, DELIVERY_FEATURE, DELIVERY_LOG_SCREEN_ID, DELIVERY_RESUBSCRIBE_PATH, DELIVERY_STATUS_CELL_COMPONENT, DELIVERY_TIME_CELL_COMPONENT, DELIVERY_TYPE_CELL_COMPONENT, DELIVERY_UNSUBSCRIBE_PATH, DeliveryErrors, DeliveryHandlers, DeliveryJobNames, DeliveryQueries, DeliveryStatus, } from "./public-names.js";
+export { DELIVERY_ATTEMPT_ADDRESS_ERASED_EVENT, DELIVERY_ATTEMPT_EVENT, DELIVERY_CHANNEL_CELL_COMPONENT, DELIVERY_ERROR_CELL_COMPONENT, DELIVERY_FEATURE, DELIVERY_LOG_SCREEN_ID, DELIVERY_RESUBSCRIBE_PATH, DELIVERY_STATUS_CELL_COMPONENT, DELIVERY_TIME_CELL_COMPONENT, DELIVERY_TYPE_CELL_COMPONENT, DELIVERY_UNSUBSCRIBE_PATH, DeliveryErrors, DeliveryHandlers, DeliveryJobNames, DeliveryQueries, DeliveryStatus, } from "./public-names.js";
 // notify() priority → BullMQ job priority. Lower number = processed first; all
 // > 0 so prioritised delivery jobs never mix with BullMQ's "0 = unprioritised
 // FIFO" bucket. critical jobs jump ahead of normal/low in the worker queue.

package/dist/delivery/events.d.ts

@@ -36,3 +36,4 @@ export declare const deliveryAttemptSchema: z.ZodObject<{
     confirmed: z.ZodOptional<z.ZodLiteral<false>>;
 }, z.core.$strip>;
 export type DeliveryAttemptPayload = z.infer<typeof deliveryAttemptSchema>;
+export declare const deliveryAttemptAddressErasedSchema: z.ZodObject<{}, z.core.$strip>;

package/dist/delivery/events.js

@@ -28,3 +28,5 @@ export const deliveryAttemptSchema = z.object({
     // Provider accepted the request but does not confirm delivery (e.g. Teams 202).
     confirmed: z.literal(false).optional(),
 });
+// No payload: the event only marks the attempt row's address as erased.
+export const deliveryAttemptAddressErasedSchema = z.object({});

package/dist/delivery/feature.d.ts

@@ -1,5 +1,6 @@
 import { type FeatureDefinition } from "@cosmicdrift/kumiko-framework/engine";
 export type DeliveryFeatureOptions = {
     readonly access?: readonly string[];
+    readonly attemptLogRetentionDays?: number | false;
 };
 export declare function createDeliveryFeature(options?: DeliveryFeatureOptions): FeatureDefinition;

package/dist/delivery/feature.js

@@ -1,7 +1,9 @@
-import { upsertByPk } from "@cosmicdrift/kumiko-framework/bun-db";
+import { updateMany, upsertByPk } from "@cosmicdrift/kumiko-framework/bun-db";
 import { access, defineFeature, i18nKey, } from "@cosmicdrift/kumiko-framework/engine";
-import { DELIVERY_ATTEMPT_EVENT, DELIVERY_CHANNEL_CELL_COMPONENT, DELIVERY_CHANNEL_EXTENSION, DELIVERY_ERROR_CELL_COMPONENT, DELIVERY_LOG_SCREEN_ID, DELIVERY_STATUS_CELL_COMPONENT, DELIVERY_TIME_CELL_COMPONENT, DELIVERY_TYPE_CELL_COMPONENT, DeliveryJobNames, DeliveryQueries, } from "./constants.js";
-import { deliveryAttemptSchema } from "./events.js";
+import { ConsumerLagError } from "@cosmicdrift/kumiko-framework/pipeline";
+import { resolveAttemptLogRetentionDays, runAttemptLogRetention } from "./attempt-log-retention.js";
+import { DELIVERY_ATTEMPT_ADDRESS_ERASED_EVENT, DELIVERY_ATTEMPT_EVENT, DELIVERY_CHANNEL_CELL_COMPONENT, DELIVERY_CHANNEL_EXTENSION, DELIVERY_ERROR_CELL_COMPONENT, DELIVERY_LOG_SCREEN_ID, DELIVERY_STATUS_CELL_COMPONENT, DELIVERY_TIME_CELL_COMPONENT, DELIVERY_TYPE_CELL_COMPONENT, DeliveryJobNames, DeliveryQueries, } from "./constants.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";
@@ -12,8 +14,10 @@ import { unsubscribeUserWrite } from "./handlers/unsubscribe-user.write.js";
 import { DELIVERY_I18N } from "./i18n.js";
 import { deliveryRenderJob, deliverySendJob } from "./jobs.js";
 import { deliveryAttemptsTable, deliveryAttemptsTableMeta, notificationAddressOptOutEntity, notificationAddressOptOutsTable, notificationPreferenceEntity, notificationPreferencesTable, } from "./tables.js";
+const ATTEMPT_LOG_RETENTION_ESCAPE_HATCH_REASON = "prunes delivery attempt events and log rows of every tenant";
 export function createDeliveryFeature(options) {
     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.");
         r.uiHints({
@@ -54,6 +58,11 @@ export function createDeliveryFeature(options) {
                 recipientAddress: { personal: { of: "recipientId", whenAbsent: "tenant" } },
             },
         });
+        // 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
@@ -89,6 +98,9 @@ export function createDeliveryFeature(options) {
                         confirmed: p.confirmed ?? null,
                     });
                 },
+                [DELIVERY_ATTEMPT_ADDRESS_ERASED_EVENT]: async (event, tx) => {
+                    await updateMany(tx, deliveryAttemptsTable, { recipientAddress: null }, { id: event.aggregateId });
+                },
             },
         });
         // Extension point: delivery-channels (email/in-app/push). Renderer-
@@ -106,6 +118,30 @@ export function createDeliveryFeature(options) {
         // from the delivery-service, hence manual trigger.
         r.job(DeliveryJobNames.render, { trigger: { manual: true }, retries: 3, backoff: "exponential" }, deliveryRenderJob);
         r.job(DeliveryJobNames.send, { trigger: { manual: true }, retries: 3, backoff: "exponential" }, 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(); // @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/dist/delivery/index.d.ts

@@ -1,8 +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, createChatWebhookChannel, resolveChatWebhookTarget, toChannelResult, } from "./chat-webhook-channel.js";
 export { type ChatSendFailureCode, type ChatSendResult, type ChatWebhookRequest, type ChatWebhookResponse, type ChatWebhookTarget, chatConnectionNameSchema, chatWebhookUrlSchema, checkChatWebhookTarget, DEFAULT_CHAT_TIMEOUT_MS, postChatWebhook, truncateChars, } from "./chat-webhook-sender.js";
 export type { DeliveryStatusValue } from "./constants.js";
-export { DELIVERY_CHANNEL_EXTENSION, DELIVERY_FEATURE, DELIVERY_LOG_SCREEN_ID, DELIVERY_UNSUBSCRIBE_PATH, DeliveryErrors, DeliveryHandlers, DeliveryJobs, DeliveryQueries, DeliveryStatus, } from "./constants.js";
+export { DELIVERY_ATTEMPT_ADDRESS_ERASED_EVENT, DELIVERY_CHANNEL_EXTENSION, DELIVERY_FEATURE, DELIVERY_LOG_SCREEN_ID, DELIVERY_UNSUBSCRIBE_PATH, DeliveryErrors, DeliveryHandlers, DeliveryJobs, DeliveryQueries, DeliveryStatus, } from "./constants.js";
 export { collectChannels, createDeliveryService, type DeliveryServiceOptions, type KillSwitchResolver, type RateLimitConfig, } from "./delivery-service.js";
 export { createDeliveryFeature, type DeliveryFeatureOptions } from "./feature.js";
 export { createDeliveryNotifyFactory } from "./notify-factory.js";

package/dist/delivery/index.js

@@ -1,7 +1,8 @@
 export { hashUnsubscribeAddress } from "./address-opt-out.js";
+export { DEFAULT_ATTEMPT_LOG_RETENTION_DAYS, runAttemptLogRetention, } from "./attempt-log-retention.js";
 export { chatMessageText, createChatWebhookChannel, resolveChatWebhookTarget, toChannelResult, } from "./chat-webhook-channel.js";
 export { chatConnectionNameSchema, chatWebhookUrlSchema, checkChatWebhookTarget, DEFAULT_CHAT_TIMEOUT_MS, postChatWebhook, truncateChars, } from "./chat-webhook-sender.js";
-export { DELIVERY_CHANNEL_EXTENSION, DELIVERY_FEATURE, DELIVERY_LOG_SCREEN_ID, DELIVERY_UNSUBSCRIBE_PATH, DeliveryErrors, DeliveryHandlers, DeliveryJobs, DeliveryQueries, DeliveryStatus, } from "./constants.js";
+export { DELIVERY_ATTEMPT_ADDRESS_ERASED_EVENT, DELIVERY_CHANNEL_EXTENSION, DELIVERY_FEATURE, DELIVERY_LOG_SCREEN_ID, DELIVERY_UNSUBSCRIBE_PATH, DeliveryErrors, DeliveryHandlers, DeliveryJobs, DeliveryQueries, DeliveryStatus, } from "./constants.js";
 export { collectChannels, createDeliveryService, } from "./delivery-service.js";
 export { createDeliveryFeature } from "./feature.js";
 export { createDeliveryNotifyFactory } from "./notify-factory.js";

package/dist/delivery/mask-recipient-address.d.ts

@@ -0,0 +1 @@
+export declare function maskRecipientAddress(address: string | null): string | null;

package/dist/delivery/mask-recipient-address.js

@@ -0,0 +1,41 @@
+import { isPiiCiphertext } from "@cosmicdrift/kumiko-framework/crypto";
+const MASK = "***";
+const VISIBLE_TAIL_LENGTH = 4;
+const MIN_LENGTH_FOR_VISIBLE_TAIL = 8;
+function maskedUrl(address) {
+    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) {
+    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) {
+    if (address === null)
+        return null;
+    return maskPlainAddress(address);
+}
+function maskPlainAddress(address) {
+    // isPiiCiphertext is a type predicate; its false branch would narrow `string` to `never`.
+    if (isPiiCiphertext(address))
+        return MASK;
+    return maskStructuredOrTail(address);
+}
+function maskStructuredOrTail(address) {
+    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/dist/delivery/public-names.d.ts

@@ -34,4 +34,6 @@ export declare const DELIVERY_ATTEMPT_EVENT: "delivery:event:attempt";
 export declare const DeliveryJobNames: {
     readonly render: "render";
     readonly send: "send";
+    readonly attemptLogRetention: "attempt-log-retention";
 };
+export declare const DELIVERY_ATTEMPT_ADDRESS_ERASED_EVENT: "delivery:event:attempt-address-erased";

package/dist/delivery/public-names.js

@@ -48,4 +48,7 @@ export const DELIVERY_ATTEMPT_EVENT = "delivery:event:attempt";
 export const DeliveryJobNames = {
     render: "render",
     send: "send",
+    attemptLogRetention: "attempt-log-retention",
 };
+// Clears recipientAddress on an attempt row after its recipient was forgotten.
+export const DELIVERY_ATTEMPT_ADDRESS_ERASED_EVENT = "delivery:event:attempt-address-erased";

package/dist/delivery/types.d.ts

@@ -34,6 +34,7 @@ export type DeliveryChannel = {
     readonly name: string;
     readonly mode: DeliveryChannelMode;
     resolve?(userId: string, ctx: ChannelContext): Promise<string | null>;
+    readonly addressKind?: "connection-name";
     render?(message: ChannelMessage, ctx: ChannelContext): Promise<RenderedMessage>;
     send(address: string, message: ChannelMessage, ctx: ChannelContext, rendered?: RenderedMessage): Promise<ChannelResult>;
 };

package/dist/delivery/types.js

@@ -4,13 +4,17 @@ import { DELIVERY_CHANNEL_EXTENSION } from "./constants.js";
 //   queued — sent asynchronously via the delivery.send job; channels with a
 //            render() additionally run through delivery.render first.
 export const DELIVERY_CHANNEL_MODES = ["inline", "queued"];
+function hasOptionalHooks(o) {
+    return ((!("render" in o) || o.render === undefined || typeof o.render === "function") &&
+        (!("resolve" in o) || o.resolve === undefined || typeof o.resolve === "function") &&
+        (!("addressKind" in o) || o.addressKind === undefined || o.addressKind === "connection-name"));
+}
 export function isDeliveryChannelPlugin(o) {
     return (typeof o === "object" &&
         o !== null &&
         "mode" in o &&
         DELIVERY_CHANNEL_MODES.some((mode) => mode === o.mode) &&
-        (!("render" in o) || o.render === undefined || typeof o.render === "function") &&
-        (!("resolve" in o) || o.resolve === undefined || typeof o.resolve === "function") &&
+        hasOptionalHooks(o) &&
         "send" in o &&
         typeof o.send === "function");
 }

package/dist/ledger/entity.d.ts

@@ -40,6 +40,7 @@ export declare const accountEntity: import("@cosmicdrift/kumiko-types/fields").E
         } | undefined;
         readonly optionsQuery?: string;
         readonly optionsQueryPayload?: import("@cosmicdrift/kumiko-types/fields").OptionsQueryPayload;
+        readonly optionsAvailabilityQuery?: string;
     } & import("@cosmicdrift/kumiko-types/fields").ResolvedPiiFlags & {
         required: true;
     };
@@ -160,6 +161,7 @@ export declare const transactionEntity: import("@cosmicdrift/kumiko-types/fields
         } | undefined;
         readonly optionsQuery?: string;
         readonly optionsQueryPayload?: import("@cosmicdrift/kumiko-types/fields").OptionsQueryPayload;
+        readonly optionsAvailabilityQuery?: string;
     } & import("@cosmicdrift/kumiko-types/fields").ResolvedPiiFlags & {
         required: true;
     };
@@ -288,6 +290,7 @@ export declare const scheduleEntity: import("@cosmicdrift/kumiko-types/fields").
         } | undefined;
         readonly optionsQuery?: string;
         readonly optionsQueryPayload?: import("@cosmicdrift/kumiko-types/fields").OptionsQueryPayload;
+        readonly optionsAvailabilityQuery?: string;
     } & import("@cosmicdrift/kumiko-types/fields").ResolvedPiiFlags & {
         required: true;
     };

package/dist/renderer-foundation/types.d.ts

@@ -19,6 +19,7 @@ export type RenderRequest = {
 export type RenderResponse = {
     kind: "notification";
     html: string;
+    text?: string;
 } | {
     kind: "mail-html";
     html: string;

package/dist/renderer-simple/feature.js

@@ -16,12 +16,10 @@ export async function adaptToFoundation(req, ctx, renderer = simpleRenderer) {
         throw new RendererError(`renderer-simple supports only kind="notification", got "${req.kind}"`, "invalid_payload");
     }
     const variables = await resolveNotificationVariables(req, ctx);
-    const html = await renderer.render({
-        template: req.payload.template ?? "",
-        variables,
-        locale: req.payload.locale,
-    });
-    return { kind: "notification", html };
+    const input = { template: req.payload.template ?? "", variables, locale: req.payload.locale };
+    const html = await renderer.render(input);
+    const text = renderer.renderText ? await renderer.renderText(input) : undefined;
+    return text === undefined ? { kind: "notification", html } : { kind: "notification", html, text };
 }
 export function createRendererSimpleFeature(options) {
     const renderer = options?.mailBranding

package/dist/renderer-simple/index.d.ts

@@ -1,2 +1,3 @@
 export { createRendererSimpleFeature, type RendererSimpleOptions } from "./feature.js";
+export type { MailBadge, MailChip, MailStage, MailStageState, MailTone } from "./mail-blocks.js";
 export { createSimpleRenderer, type LocalizedText, type MailBranding, simpleRenderer, } from "./simple-renderer.js";

package/dist/renderer-simple/mail-blocks.d.ts

@@ -0,0 +1,21 @@
+export type MailTone = "neutral" | "info" | "success" | "warning" | "danger";
+export type MailStageState = "done" | "current" | "upcoming";
+export type MailBadge = {
+    readonly label: string;
+    readonly tone?: MailTone;
+};
+export type MailStage = {
+    readonly label: string;
+    readonly state: MailStageState;
+};
+export type MailChip = {
+    readonly label: string;
+    readonly tone?: MailTone;
+};
+export declare function parseBadge(value: unknown): MailBadge | undefined;
+export declare function renderBadge(badge: MailBadge): string;
+export declare function renderChips(chips: unknown): string;
+export declare function renderStages(stages: unknown, primaryColor: string): string;
+export declare function badgeText(badge: MailBadge): string;
+export declare function stagesText(stages: unknown): string;
+export declare function chipsText(chips: unknown): string;