unified-notification-core 0.1.0 → 0.1.2

package/dist/core.js

@@ -1,6 +1,13 @@
-import { and, asc, count, desc, eq, inArray, isNotNull, isNull, lt, lte, or, } from "drizzle-orm";
+import { and, asc, count, desc, eq, inArray, is, isNotNull, isNull, lt, lte, notInArray, or, sql, } from "drizzle-orm";
+import { PgTransaction } from "drizzle-orm/pg-core";
+import { performance } from "node:perf_hooks";
+import { types as nodeTypes } from "node:util";
 import { NotificationConfigurationError, NotificationDeliveryError, } from "./errors.js";
-import { resolvePreference } from "./preferences.js";
+import { canonicalNotificationKeySql, getOwnRecordValue, normalizeChannelRecord, normalizeNotificationKey, normalizePreferenceDefaults, normalizeUniqueNotificationKeys, } from "./keys.js";
+import { normalizeJsonObject } from "./json.js";
+import { captureArrayValues, capturePlainRecord, inspectArray, } from "./runtime.js";
+import { assertPostgresSafeString, isPostgresSafeString, sanitizeAndTruncatePostgresString, } from "./strings.js";
+import { createStoredPreferenceMap, resolvePreference, resolveNormalizedPreference, } from "./preferences.js";
 import { notificationSchema as defaultNotificationSchema, } from "./schema.js";
 import { BUILT_IN_CHANNELS, PREFERENCE_WILDCARD, } from "./types.js";
 const DEFAULT_RETRY_DELAYS_MS = [
@@ -13,42 +20,300 @@ const DEFAULT_RETRY_DELAYS_MS = [
 function defaultRetryDelayMs(attempt) {
     return (DEFAULT_RETRY_DELAYS_MS[Math.min(Math.max(attempt - 1, 0), DEFAULT_RETRY_DELAYS_MS.length - 1)] ?? 6 * 60 * 60_000);
 }
-function uniqueNonEmpty(values, label) {
-    const normalized = [...new Set(values.map((value) => value.trim()))].filter(Boolean);
-    if (normalized.length === 0) {
-        throw new NotificationConfigurationError(`${label} must not be empty`);
+const MAX_DISPATCH_LIMIT = 1_000;
+const MAX_DISPATCH_CONCURRENCY = 100;
+const MAX_ATTEMPTS = 2_147_483_647;
+const MAX_PROVIDER_MESSAGE_ID_LENGTH = 10_000;
+const MAX_DELIVERY_DIAGNOSTIC_LENGTH = 10_000;
+const RETRY_DELAY_POLICY_TIMEOUT_MS = 100;
+const DIAGNOSTIC_TRUNCATION_MARKER = "…";
+const CONFIG_KEYS = new Set([
+    "db",
+    "schema",
+    "adapters",
+    "defaultChannels",
+    "preferenceDefaults",
+    "defaultPreferenceEnabled",
+    "defaultMaxAttempts",
+    "retryDelayMs",
+    "lockTimeoutMs",
+    "now",
+    "logger",
+]);
+const PUBLISH_KEYS = new Set([
+    "recipientIds",
+    "topic",
+    "payload",
+    "channels",
+    "actorId",
+    "entityType",
+    "entityId",
+    "idempotencyKey",
+    "scheduledFor",
+    "preferencePolicy",
+    "maxAttempts",
+]);
+const NATIVE_PROMISE = Promise;
+const NATIVE_PROMISE_PROTOTYPE = Promise.prototype;
+const NATIVE_PROMISE_THEN = Promise.prototype.then;
+const NATIVE_PROMISE_SPECIES = Symbol.species;
+const MONOTONIC_NOW = performance.now.bind(performance);
+const IS_PROMISE = nodeTypes.isPromise.bind(nodeTypes);
+const OBJECT_GET_PROTOTYPE_OF = Object.getPrototypeOf.bind(Object);
+const OBJECT_HAS_OWN = Object.hasOwn.bind(Object);
+const OBJECT_GET_OWN_PROPERTY_DESCRIPTOR = Object.getOwnPropertyDescriptor.bind(Object);
+const REFLECT_APPLY = Reflect.apply.bind(Reflect);
+const NATIVE_SET_TIMEOUT = globalThis.setTimeout.bind(globalThis);
+const NATIVE_CLEAR_TIMEOUT = globalThis.clearTimeout.bind(globalThis);
+const NATIVE_PROMISE_CONSTRUCTOR_DESCRIPTOR = OBJECT_GET_OWN_PROPERTY_DESCRIPTOR(NATIVE_PROMISE_PROTOTYPE, "constructor");
+const NATIVE_PROMISE_SPECIES_DESCRIPTOR = OBJECT_GET_OWN_PROPERTY_DESCRIPTOR(Promise, NATIVE_PROMISE_SPECIES);
+function sameDescriptor(current, expected) {
+    return (current !== undefined &&
+        expected !== undefined &&
+        current.configurable === expected.configurable &&
+        current.enumerable === expected.enumerable &&
+        current.writable === expected.writable &&
+        current.value === expected.value &&
+        current.get === expected.get &&
+        current.set === expected.set);
+}
+function isExactNativePromise(value) {
+    if (!IS_PROMISE(value)) {
+        return false;
+    }
+    try {
+        return (OBJECT_GET_PROTOTYPE_OF(value) === NATIVE_PROMISE_PROTOTYPE &&
+            !OBJECT_HAS_OWN(value, "constructor") &&
+            !OBJECT_HAS_OWN(value, "then") &&
+            sameDescriptor(OBJECT_GET_OWN_PROPERTY_DESCRIPTOR(NATIVE_PROMISE_PROTOTYPE, "constructor"), NATIVE_PROMISE_CONSTRUCTOR_DESCRIPTOR) &&
+            sameDescriptor(OBJECT_GET_OWN_PROPERTY_DESCRIPTOR(NATIVE_PROMISE, NATIVE_PROMISE_SPECIES), NATIVE_PROMISE_SPECIES_DESCRIPTOR));
+    }
+    catch {
+        return false;
+    }
+}
+function attachNativePromiseObservation(promise, observe) {
+    try {
+        void REFLECT_APPLY(NATIVE_PROMISE_THEN, promise, [
+            (value) => observe({ status: "fulfilled", value }),
+            (reason) => observe({ status: "rejected", reason }),
+        ]);
+    }
+    catch (reason) {
+        observe({ status: "rejected", reason });
     }
-    return normalized;
 }
 function assertBounded(value, label, max) {
+    if (typeof value !== "string") {
+        throw new NotificationConfigurationError(`${label} must be a string`);
+    }
     if (!value.trim()) {
         throw new NotificationConfigurationError(`${label} must not be empty`);
     }
     if (value.length > max) {
         throw new NotificationConfigurationError(`${label} must be at most ${max} characters`);
     }
+    assertPostgresSafeString(value, label);
 }
-function errorDetails(error) {
-    if (error instanceof NotificationDeliveryError) {
+function normalizeOptionalIdentifier(value, label, maximum) {
+    if (value === undefined || value === null) {
+        return null;
+    }
+    return normalizeNotificationKey(value, label, maximum);
+}
+function normalizeNotificationKeyArray(values, label, maximum) {
+    const snapshot = captureArrayValues(values, label);
+    const normalized = [];
+    for (let index = 0; index < snapshot.length; index += 1) {
+        normalized.push(normalizeNotificationKey(snapshot[index], label, maximum));
+    }
+    return normalized;
+}
+function normalizeBoolean(value, label, fallback) {
+    if (value === undefined && fallback !== undefined) {
+        return fallback;
+    }
+    if (typeof value !== "boolean") {
+        throw new NotificationConfigurationError(`${label} must be a boolean`);
+    }
+    return value;
+}
+function normalizePositiveInteger(value, label, minimum = 1) {
+    if (typeof value !== "number" ||
+        !Number.isFinite(value) ||
+        !Number.isInteger(value) ||
+        value < minimum) {
+        throw new NotificationConfigurationError(`${label} must be an integer no less than ${minimum}`);
+    }
+    return value;
+}
+function normalizeMaxAttempts(value, label) {
+    if (typeof value !== "number" ||
+        !Number.isFinite(value) ||
+        !Number.isInteger(value) ||
+        value < 1 ||
+        value > MAX_ATTEMPTS) {
+        throw new NotificationConfigurationError(`${label} must be an integer from 1 through ${MAX_ATTEMPTS}`);
+    }
+    return value;
+}
+function normalizeDate(value, label) {
+    let time = Number.NaN;
+    try {
+        if (value instanceof Date) {
+            time = Date.prototype.getTime.call(value);
+        }
+    }
+    catch {
+        time = Number.NaN;
+    }
+    if (!Number.isFinite(time)) {
+        throw new NotificationConfigurationError(`${label} must be a valid Date`);
+    }
+    return new Date(time);
+}
+function normalizePreferencePolicy(value) {
+    if (value === "respect" || value === "ignore") {
+        return value;
+    }
+    throw new NotificationConfigurationError('preferencePolicy must be either "respect" or "ignore"');
+}
+function normalizeDispatchInteger(value, label, fallback, maximum) {
+    if (value === undefined) {
+        return fallback;
+    }
+    if (typeof value !== "number" ||
+        !Number.isFinite(value) ||
+        !Number.isInteger(value) ||
+        value < 1 ||
+        value > maximum) {
+        throw new NotificationConfigurationError(`${label} must be a positive integer no greater than ${maximum}`);
+    }
+    return value;
+}
+function capDiagnosticMessage(message) {
+    return sanitizeAndTruncatePostgresString(message, MAX_DELIVERY_DIAGNOSTIC_LENGTH, DIAGNOSTIC_TRUNCATION_MARKER);
+}
+function ownDataValue(value, key) {
+    if (value === null ||
+        (typeof value !== "object" && typeof value !== "function")) {
+        return undefined;
+    }
+    try {
+        const descriptor = Object.getOwnPropertyDescriptor(value, key);
+        return descriptor && "value" in descriptor
+            ? descriptor.value
+            : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function safeDiagnosticMessage(value, fallback) {
+    let message;
+    if (typeof value === "string") {
+        message = value;
+    }
+    else {
+        const ownMessage = ownDataValue(value, "message");
+        if (typeof ownMessage === "string") {
+            message = ownMessage;
+        }
+        else if (value === null ||
+            typeof value === "number" ||
+            typeof value === "boolean" ||
+            typeof value === "bigint" ||
+            typeof value === "symbol" ||
+            value === undefined) {
+            try {
+                message = String(value);
+            }
+            catch {
+                message = undefined;
+            }
+        }
+    }
+    return capDiagnosticMessage(message || fallback);
+}
+function adapterResultDiagnostic(error) {
+    const detail = safeDiagnosticMessage(error, "invalid adapter result");
+    return capDiagnosticMessage(`Adapter resolved successfully, but its optional result was discarded: ${detail}`);
+}
+function adapterResultValue(result, key) {
+    const descriptor = Object.getOwnPropertyDescriptor(result, key);
+    if (!descriptor) {
+        return undefined;
+    }
+    if (!("value" in descriptor)) {
+        throw new NotificationConfigurationError(`adapter result ${key} must be a data property`);
+    }
+    return descriptor.value;
+}
+function normalizeAdapterResult(result) {
+    if (result === undefined) {
+        return { providerMessageId: null, metadata: null, diagnostic: null };
+    }
+    try {
+        if (!result || typeof result !== "object" || Array.isArray(result)) {
+            throw new NotificationConfigurationError("adapter result must be an object or undefined");
+        }
+        const providerMessageId = adapterResultValue(result, "providerMessageId");
+        if (providerMessageId !== undefined) {
+            assertBounded(providerMessageId, "adapter result providerMessageId", MAX_PROVIDER_MESSAGE_ID_LENGTH);
+        }
+        const metadata = adapterResultValue(result, "metadata");
+        const normalizedMetadata = metadata === undefined
+            ? undefined
+            : normalizeJsonObject(metadata, "adapter result metadata");
         return {
-            code: error.code,
-            message: error.message,
-            retryable: error.retryable,
+            providerMessageId: providerMessageId ?? null,
+            metadata: normalizedMetadata ?? null,
+            diagnostic: null,
         };
     }
-    if (error instanceof Error) {
+    catch (error) {
         return {
-            code: "delivery_failed",
-            message: error.message,
-            retryable: true,
+            providerMessageId: null,
+            metadata: null,
+            diagnostic: adapterResultDiagnostic(error),
+        };
+    }
+}
+function persistenceSafeErrorCode(code) {
+    if (typeof code !== "string") {
+        return "delivery_failed";
+    }
+    const normalized = code.trim();
+    return normalized && normalized.length <= 191 && isPostgresSafeString(normalized)
+        ? normalized
+        : "delivery_failed";
+}
+function errorDetails(error) {
+    let isDeliveryError = false;
+    try {
+        isDeliveryError = error instanceof NotificationDeliveryError;
+    }
+    catch {
+        isDeliveryError = false;
+    }
+    if (isDeliveryError) {
+        return {
+            code: persistenceSafeErrorCode(ownDataValue(error, "code")),
+            message: safeDiagnosticMessage(error, "Notification delivery failed"),
+            retryable: ownDataValue(error, "retryable") !== false,
         };
     }
     return {
         code: "delivery_failed",
-        message: String(error),
+        message: safeDiagnosticMessage(error, "Unknown delivery failure"),
         retryable: true,
     };
 }
+function assertDispatchExecutor(db) {
+    if (is(db, PgTransaction)) {
+        throw new NotificationConfigurationError("dispatchDue() and publishAndDispatch() require a top-level PgDatabase; use publish() in the application transaction and dispatch from a top-level core after it commits");
+    }
+}
 export class UnifiedNotificationCore {
     #db;
     #schema;
@@ -62,201 +327,357 @@ export class UnifiedNotificationCore {
     #now;
     #logger;
     constructor(config) {
+        config = capturePlainRecord(config, "config", CONFIG_KEYS);
+        if (!config.db || typeof config.db !== "object") {
+            throw new NotificationConfigurationError("db must be a database object");
+        }
         this.#db = config.db;
-        this.#schema = config.schema ?? defaultNotificationSchema;
-        this.#adapters = config.adapters ?? {};
-        this.#defaultChannels =
-            config.defaultChannels ?? [BUILT_IN_CHANNELS.IN_APP];
-        this.#preferenceDefaults = config.preferenceDefaults ?? {};
-        this.#defaultPreferenceEnabled = config.defaultPreferenceEnabled ?? true;
-        this.#defaultMaxAttempts = config.defaultMaxAttempts ?? 5;
-        this.#retryDelayMs = config.retryDelayMs ?? defaultRetryDelayMs;
-        this.#lockTimeoutMs = config.lockTimeoutMs ?? 5 * 60_000;
-        this.#now = config.now ?? (() => new Date());
-        this.#logger = config.logger;
-        if (this.#defaultMaxAttempts < 1) {
-            throw new NotificationConfigurationError("defaultMaxAttempts must be at least 1");
+        const schema = Object.hasOwn(config, "schema")
+            ? config.schema
+            : defaultNotificationSchema;
+        if (!schema || typeof schema !== "object" || inspectArray(schema, "schema")) {
+            throw new NotificationConfigurationError("schema must be an object");
+        }
+        this.#schema = schema;
+        const adapters = Object.hasOwn(config, "adapters") ? config.adapters : {};
+        this.#adapters = normalizeChannelRecord(adapters, "adapters");
+        for (const channel of Object.keys(this.#adapters)) {
+            if (typeof this.#adapters[channel] !== "function") {
+                throw new NotificationConfigurationError(`adapters value for channel "${channel}" must be a function`);
+            }
+        }
+        this.#defaultChannels = normalizeUniqueNotificationKeys(Object.hasOwn(config, "defaultChannels")
+            ? config.defaultChannels
+            : [BUILT_IN_CHANNELS.IN_APP], "defaultChannels", 64);
+        this.#preferenceDefaults = normalizePreferenceDefaults(Object.hasOwn(config, "preferenceDefaults")
+            ? config.preferenceDefaults
+            : {});
+        this.#defaultPreferenceEnabled = Object.hasOwn(config, "defaultPreferenceEnabled")
+            ? normalizeBoolean(config.defaultPreferenceEnabled, "defaultPreferenceEnabled")
+            : true;
+        this.#defaultMaxAttempts = Object.hasOwn(config, "defaultMaxAttempts")
+            ? normalizeMaxAttempts(config.defaultMaxAttempts, "defaultMaxAttempts")
+            : 5;
+        const retryDelayMs = Object.hasOwn(config, "retryDelayMs")
+            ? config.retryDelayMs
+            : defaultRetryDelayMs;
+        if (typeof retryDelayMs !== "function") {
+            throw new NotificationConfigurationError("retryDelayMs must be a function");
+        }
+        this.#retryDelayMs = retryDelayMs;
+        this.#lockTimeoutMs = Object.hasOwn(config, "lockTimeoutMs")
+            ? normalizePositiveInteger(config.lockTimeoutMs, "lockTimeoutMs", 1_000)
+            : 5 * 60_000;
+        const now = Object.hasOwn(config, "now") ? config.now : () => new Date();
+        if (typeof now !== "function") {
+            throw new NotificationConfigurationError("now must be a function");
         }
-        if (this.#lockTimeoutMs < 1_000) {
-            throw new NotificationConfigurationError("lockTimeoutMs must be at least 1000");
+        this.#now = now;
+        const logger = Object.hasOwn(config, "logger") ? config.logger : undefined;
+        if (Object.hasOwn(config, "logger") &&
+            (!logger || typeof logger !== "object" || inspectArray(logger, "logger"))) {
+            throw new NotificationConfigurationError("logger must be an object");
         }
+        const loggerSnapshot = logger
+            ? capturePlainRecord(logger, "logger", new Set(["debug", "error"]))
+            : undefined;
+        for (const level of ["debug", "error"]) {
+            if (!loggerSnapshot || !Object.hasOwn(loggerSnapshot, level)) {
+                continue;
+            }
+            if (typeof loggerSnapshot[level] !== "function") {
+                throw new NotificationConfigurationError(`logger.${level} must be a function`);
+            }
+        }
+        this.#logger = loggerSnapshot;
         this.#validateChannels(this.#defaultChannels);
     }
     async publish(input) {
-        const recipientIds = uniqueNonEmpty(input.recipientIds, "recipientIds");
-        const topic = input.topic.trim();
-        assertBounded(topic, "topic", 191);
-        assertBounded(input.payload.title, "payload.title", 10_000);
-        assertBounded(input.payload.body, "payload.body", 100_000);
-        const channels = uniqueNonEmpty(input.channels ?? this.#defaultChannels, "channels");
+        input = capturePlainRecord(input, "publish input", PUBLISH_KEYS);
+        const recipientIds = normalizeUniqueNotificationKeys(input.recipientIds, "recipientId", 10_000);
+        const topic = normalizeNotificationKey(input.topic, "topic", 191);
+        const normalizedPayload = normalizeJsonObject(input.payload, "payload");
+        assertBounded(normalizedPayload.title, "payload.title", 10_000);
+        assertBounded(normalizedPayload.body, "payload.body", 100_000);
+        if (normalizedPayload.actionUrl !== undefined) {
+            assertBounded(normalizedPayload.actionUrl, "payload.actionUrl", 100_000);
+        }
+        if (normalizedPayload.data !== undefined) {
+            normalizeJsonObject(normalizedPayload.data, "payload.data");
+        }
+        const channels = normalizeUniqueNotificationKeys(Object.hasOwn(input, "channels")
+            ? input.channels
+            : this.#defaultChannels, "channels", 64);
         this.#validateChannels(channels);
+        let channelData;
+        if (normalizedPayload.channelData !== undefined) {
+            const normalizedChannelData = normalizeJsonObject(normalizedPayload.channelData, "payload.channelData");
+            channelData = normalizeChannelRecord(normalizedChannelData, "payload.channelData");
+        }
+        const payload = {
+            ...normalizedPayload,
+            ...(channelData ? { channelData } : {}),
+        };
+        let configuredMaxAttempts;
+        if (input.maxAttempts !== undefined) {
+            if (typeof input.maxAttempts === "number") {
+                configuredMaxAttempts = normalizeMaxAttempts(input.maxAttempts, "maxAttempts");
+            }
+            else {
+                const record = normalizeChannelRecord(input.maxAttempts, "maxAttempts");
+                for (const [channel, value] of Object.entries(record)) {
+                    normalizeMaxAttempts(value, `maxAttempts for channel "${channel}"`);
+                }
+                configuredMaxAttempts = record;
+            }
+        }
+        const maxAttemptsByChannel = new Map(channels.map((channel) => [
+            channel,
+            this.#maxAttemptsFor(channel, configuredMaxAttempts),
+        ]));
         if (input.idempotencyKey !== undefined) {
             assertBounded(input.idempotencyKey, "idempotencyKey", 255);
         }
-        const scheduledFor = input.scheduledFor ?? this.#now();
-        const preferencePolicy = input.preferencePolicy ?? "respect";
+        const actorId = normalizeOptionalIdentifier(input.actorId, "actorId", 10_000);
+        const entityType = normalizeOptionalIdentifier(input.entityType, "entityType", 191);
+        const entityId = normalizeOptionalIdentifier(input.entityId, "entityId", 10_000);
+        const scheduledFor = input.scheduledFor === undefined
+            ? this.#currentTime()
+            : normalizeDate(input.scheduledFor, "scheduledFor");
+        const preferencePolicy = Object.hasOwn(input, "preferencePolicy")
+            ? normalizePreferencePolicy(input.preferencePolicy)
+            : "respect";
         const { notifications, notificationDeliveries, notificationPreferences, } = this.#schema;
         return this.#db.transaction(async (tx) => {
-            const published = [];
-            for (const recipientId of recipientIds) {
-                let notification;
-                let created = true;
-                const values = {
-                    recipientId,
-                    topic,
-                    title: input.payload.title,
-                    body: input.payload.body,
-                    actionUrl: input.payload.actionUrl ?? null,
-                    data: input.payload.data ?? {},
-                    payload: input.payload,
-                    actorId: input.actorId ?? null,
-                    entityType: input.entityType ?? null,
-                    entityId: input.entityId ?? null,
-                    idempotencyKey: input.idempotencyKey ?? null,
-                    scheduledFor,
+            const preferencesByRecipient = new Map();
+            if (preferencePolicy === "respect") {
+                const selection = {
+                    recipientId: notificationPreferences.recipientId,
+                    topic: notificationPreferences.topic,
+                    channel: notificationPreferences.channel,
+                    enabled: notificationPreferences.enabled,
                 };
-                if (input.idempotencyKey) {
-                    const [inserted] = await tx
-                        .insert(notifications)
-                        .values(values)
-                        .onConflictDoNothing({
-                        target: [
-                            notifications.recipientId,
-                            notifications.idempotencyKey,
-                        ],
-                        where: isNotNull(notifications.idempotencyKey),
-                    })
-                        .returning();
-                    notification = inserted;
-                    if (!notification) {
-                        created = false;
-                        [notification] = await tx
-                            .select()
-                            .from(notifications)
-                            .where(and(eq(notifications.recipientId, recipientId), eq(notifications.idempotencyKey, input.idempotencyKey)))
-                            .limit(1);
-                    }
-                }
-                else {
-                    [notification] = await tx
-                        .insert(notifications)
-                        .values(values)
-                        .returning();
+                const exactPreferences = await tx
+                    .select(selection)
+                    .from(notificationPreferences)
+                    .where(inArray(notificationPreferences.recipientId, recipientIds));
+                const legacyPreferences = await tx
+                    .select(selection)
+                    .from(notificationPreferences)
+                    .where(and(notInArray(notificationPreferences.recipientId, recipientIds), inArray(canonicalNotificationKeySql(notificationPreferences.recipientId), recipientIds)));
+                for (const preference of [
+                    ...exactPreferences,
+                    ...legacyPreferences,
+                ]) {
+                    const recipientId = normalizeNotificationKey(preference.recipientId, "storedPreference.recipientId", 10_000);
+                    const stored = preferencesByRecipient.get(recipientId) ?? [];
+                    stored.push({
+                        topic: preference.topic,
+                        channel: preference.channel,
+                        enabled: preference.enabled,
+                    });
+                    preferencesByRecipient.set(recipientId, stored);
                 }
-                if (!notification) {
-                    throw new Error("notification insert did not return a row");
+            }
+            const notificationValues = recipientIds.map((recipientId) => ({
+                recipientId,
+                topic,
+                title: payload.title,
+                body: payload.body,
+                actionUrl: payload.actionUrl ?? null,
+                data: payload.data ?? {},
+                payload,
+                actorId,
+                entityType,
+                entityId,
+                idempotencyKey: input.idempotencyKey ?? null,
+                scheduledFor,
+            }));
+            let insertedNotifications;
+            let selectedNotifications;
+            if (input.idempotencyKey !== undefined) {
+                insertedNotifications = await tx
+                    .insert(notifications)
+                    .values(notificationValues)
+                    .onConflictDoNothing({
+                    target: [
+                        notifications.recipientId,
+                        notifications.idempotencyKey,
+                    ],
+                    where: isNotNull(notifications.idempotencyKey),
+                })
+                    .returning();
+                selectedNotifications = await tx
+                    .select()
+                    .from(notifications)
+                    .where(and(inArray(notifications.recipientId, recipientIds), eq(notifications.idempotencyKey, input.idempotencyKey)));
+            }
+            else {
+                insertedNotifications = await tx
+                    .insert(notifications)
+                    .values(notificationValues)
+                    .returning();
+                selectedNotifications = insertedNotifications;
+            }
+            const notificationsByRecipient = new Map(selectedNotifications.map((notification) => [
+                notification.recipientId,
+                notification,
+            ]));
+            if (notificationsByRecipient.size !== recipientIds.length) {
+                throw new Error("notification insert did not return every recipient row");
+            }
+            const createdNotificationIds = new Set(insertedNotifications.map((notification) => notification.id));
+            const storedPreferenceMaps = new Map();
+            for (const recipientId of recipientIds) {
+                storedPreferenceMaps.set(recipientId, createStoredPreferenceMap(preferencesByRecipient.get(recipientId) ?? []));
+            }
+            const deliveryValues = [];
+            for (const recipientId of recipientIds) {
+                const notification = notificationsByRecipient.get(recipientId);
+                if (!createdNotificationIds.has(notification.id)) {
+                    continue;
                 }
-                if (created) {
-                    const stored = preferencePolicy === "respect"
-                        ? await tx
-                            .select({
-                            topic: notificationPreferences.topic,
-                            channel: notificationPreferences.channel,
-                            enabled: notificationPreferences.enabled,
-                        })
-                            .from(notificationPreferences)
-                            .where(eq(notificationPreferences.recipientId, recipientId))
-                        : [];
-                    await tx.insert(notificationDeliveries).values(channels.map((channel) => {
-                        const enabled = preferencePolicy === "ignore"
-                            ? true
-                            : resolvePreference({
-                                topic,
-                                channel,
-                                stored,
-                                defaults: this.#preferenceDefaults,
-                                globalDefault: this.#defaultPreferenceEnabled,
-                            }).enabled;
-                        return {
-                            notificationId: notification.id,
+                const stored = storedPreferenceMaps.get(recipientId);
+                for (const channel of channels) {
+                    const enabled = preferencePolicy === "ignore"
+                        ? true
+                        : resolveNormalizedPreference({
+                            topic,
                             channel,
-                            status: enabled ? "pending" : "skipped",
-                            maxAttempts: this.#maxAttemptsFor(channel, input.maxAttempts),
-                            nextAttemptAt: enabled ? scheduledFor : null,
-                            errorCode: enabled ? null : "preference_disabled",
-                            errorMessage: enabled
-                                ? null
-                                : "Delivery disabled by recipient preference",
-                        };
-                    }));
+                            stored,
+                            defaults: this.#preferenceDefaults,
+                            globalDefault: this.#defaultPreferenceEnabled,
+                        }).enabled;
+                    deliveryValues.push({
+                        notificationId: notification.id,
+                        channel,
+                        status: enabled ? "pending" : "skipped",
+                        maxAttempts: maxAttemptsByChannel.get(channel),
+                        nextAttemptAt: enabled ? scheduledFor : null,
+                        errorCode: enabled ? null : "preference_disabled",
+                        errorMessage: enabled
+                            ? null
+                            : "Delivery disabled by recipient preference",
+                    });
                 }
-                const deliveryRows = await tx
-                    .select({
-                    deliveryId: notificationDeliveries.id,
-                    channel: notificationDeliveries.channel,
-                    status: notificationDeliveries.status,
-                })
-                    .from(notificationDeliveries)
-                    .where(eq(notificationDeliveries.notificationId, notification.id));
-                published.push({
+            }
+            if (deliveryValues.length > 0) {
+                await tx.insert(notificationDeliveries).values(deliveryValues);
+            }
+            const notificationIds = selectedNotifications.map((notification) => notification.id);
+            const deliveryRows = await tx
+                .select({
+                notificationId: notificationDeliveries.notificationId,
+                deliveryId: notificationDeliveries.id,
+                channel: notificationDeliveries.channel,
+                status: notificationDeliveries.status,
+            })
+                .from(notificationDeliveries)
+                .where(inArray(notificationDeliveries.notificationId, notificationIds));
+            const deliveriesByNotification = new Map();
+            for (const delivery of deliveryRows) {
+                const current = deliveriesByNotification.get(delivery.notificationId) ?? [];
+                current.push(delivery);
+                deliveriesByNotification.set(delivery.notificationId, current);
+            }
+            const channelOrder = new Map(channels.map((channel, index) => [channel, index]));
+            return recipientIds.map((recipientId) => {
+                const notification = notificationsByRecipient.get(recipientId);
+                const rows = deliveriesByNotification.get(notification.id) ?? [];
+                rows.sort((left, right) => (channelOrder.get(left.channel) ?? channels.length) -
+                    (channelOrder.get(right.channel) ?? channels.length) ||
+                    left.channel.localeCompare(right.channel));
+                return {
                     notificationId: notification.id,
                     recipientId,
-                    created,
-                    deliveries: deliveryRows.map((delivery) => ({
+                    created: createdNotificationIds.has(notification.id),
+                    deliveries: rows.map((delivery) => ({
                         deliveryId: delivery.deliveryId,
                         channel: delivery.channel,
                         status: delivery.status,
                     })),
-                });
-            }
-            return published;
+                };
+            });
         });
     }
     async publishAndDispatch(input, options = {}) {
+        options = capturePlainRecord(options, "publishAndDispatch options", new Set(["workerId", "concurrency"]));
+        assertDispatchExecutor(this.#db);
+        const concurrency = normalizeDispatchInteger(options.concurrency, "concurrency", 10, MAX_DISPATCH_CONCURRENCY);
+        const workerId = options.workerId === undefined
+            ? undefined
+            : normalizeNotificationKey(options.workerId, "workerId", 154);
         const published = await this.publish(input);
         const dispatched = await this.#dispatch({
-            limit: published.reduce((total, item) => total + item.deliveries.length, 0),
-            ...(options.workerId ? { workerId: options.workerId } : {}),
-            ...(options.concurrency
-                ? { concurrency: options.concurrency }
-                : {}),
+            limit: Math.min(published.reduce((total, item) => total + item.deliveries.length, 0), MAX_DISPATCH_LIMIT),
+            ...(workerId !== undefined ? { workerId } : {}),
+            concurrency,
             notificationIds: published.map((item) => item.notificationId),
         });
         return { published, dispatched };
     }
     async dispatchDue(options = {}) {
+        options = capturePlainRecord(options, "dispatch options", new Set(["limit", "workerId", "concurrency"]));
         return this.#dispatch(options);
     }
     async setPreference(preference) {
+        preference = capturePlainRecord(preference, "preference", new Set(["recipientId", "topic", "channel", "enabled"]));
         const { notificationPreferences } = this.#schema;
-        const topic = preference.topic.trim();
-        const channel = preference.channel.trim();
-        assertBounded(topic, "preference.topic", 191);
-        assertBounded(channel, "preference.channel", 64);
-        assertBounded(preference.recipientId, "preference.recipientId", 10_000);
-        const now = this.#now();
-        await this.#db
-            .insert(notificationPreferences)
-            .values({
-            recipientId: preference.recipientId,
-            topic,
-            channel,
-            enabled: preference.enabled,
-            updatedAt: now,
-        })
-            .onConflictDoUpdate({
-            target: [
-                notificationPreferences.recipientId,
-                notificationPreferences.topic,
-                notificationPreferences.channel,
-            ],
-            set: { enabled: preference.enabled, updatedAt: now },
+        const recipientId = normalizeNotificationKey(preference.recipientId, "preference.recipientId", 10_000);
+        const topic = normalizeNotificationKey(preference.topic, "preference.topic", 191);
+        const channel = normalizeNotificationKey(preference.channel, "preference.channel", 64);
+        const enabled = normalizeBoolean(preference.enabled, "preference.enabled");
+        const now = this.#currentTime();
+        await this.#db.transaction(async (tx) => {
+            await tx
+                .delete(notificationPreferences)
+                .where(and(eq(canonicalNotificationKeySql(notificationPreferences.recipientId), recipientId), eq(canonicalNotificationKeySql(notificationPreferences.topic), topic), eq(canonicalNotificationKeySql(notificationPreferences.channel), channel)));
+            await tx
+                .insert(notificationPreferences)
+                .values({
+                recipientId,
+                topic,
+                channel,
+                enabled,
+                updatedAt: now,
+            })
+                .onConflictDoUpdate({
+                target: [
+                    notificationPreferences.recipientId,
+                    notificationPreferences.topic,
+                    notificationPreferences.channel,
+                ],
+                set: { enabled, updatedAt: now },
+            });
         });
     }
     async setPreferences(recipientId, preferences) {
+        const normalizedRecipientId = normalizeNotificationKey(recipientId, "preference.recipientId", 10_000);
+        const preferenceSnapshot = captureArrayValues(preferences, "preferences");
+        const normalizedPreferences = [];
+        for (let index = 0; index < preferenceSnapshot.length; index += 1) {
+            const preference = capturePlainRecord(preferenceSnapshot[index], `preferences[${index}]`, new Set(["topic", "channel", "enabled"]));
+            normalizedPreferences.push({
+                topic: normalizeNotificationKey(preference.topic, "preference.topic", 191),
+                channel: normalizeNotificationKey(preference.channel, "preference.channel", 64),
+                enabled: normalizeBoolean(preference.enabled, "preference.enabled"),
+            });
+        }
+        const now = this.#currentTime();
         await this.#db.transaction(async (tx) => {
             const { notificationPreferences } = this.#schema;
-            const now = this.#now();
-            for (const preference of preferences) {
-                assertBounded(preference.topic.trim(), "preference.topic", 191);
-                assertBounded(preference.channel.trim(), "preference.channel", 64);
+            for (const preference of normalizedPreferences) {
+                const { topic, channel, enabled } = preference;
+                await tx
+                    .delete(notificationPreferences)
+                    .where(and(eq(canonicalNotificationKeySql(notificationPreferences.recipientId), normalizedRecipientId), eq(canonicalNotificationKeySql(notificationPreferences.topic), topic), eq(canonicalNotificationKeySql(notificationPreferences.channel), channel)));
                 await tx
                     .insert(notificationPreferences)
                     .values({
-                    recipientId,
-                    topic: preference.topic.trim(),
-                    channel: preference.channel.trim(),
-                    enabled: preference.enabled,
+                    recipientId: normalizedRecipientId,
+                    topic,
+                    channel,
+                    enabled,
                     updatedAt: now,
                 })
                     .onConflictDoUpdate({
@@ -265,21 +686,29 @@ export class UnifiedNotificationCore {
                         notificationPreferences.topic,
                         notificationPreferences.channel,
                     ],
-                    set: { enabled: preference.enabled, updatedAt: now },
+                    set: { enabled, updatedAt: now },
                 });
             }
         });
     }
     async clearPreference(input) {
+        input = capturePlainRecord(input, "clearPreference input", new Set(["recipientId", "topic", "channel"]));
         const { notificationPreferences } = this.#schema;
+        const recipientId = normalizeNotificationKey(input.recipientId, "preference.recipientId", 10_000);
+        const topic = normalizeNotificationKey(input.topic, "preference.topic", 191);
+        const channel = normalizeNotificationKey(input.channel, "preference.channel", 64);
         const deleted = await this.#db
             .delete(notificationPreferences)
-            .where(and(eq(notificationPreferences.recipientId, input.recipientId), eq(notificationPreferences.topic, input.topic), eq(notificationPreferences.channel, input.channel)))
+            .where(and(eq(canonicalNotificationKeySql(notificationPreferences.recipientId), recipientId), eq(canonicalNotificationKeySql(notificationPreferences.topic), topic), eq(canonicalNotificationKeySql(notificationPreferences.channel), channel)))
             .returning({ recipientId: notificationPreferences.recipientId });
         return deleted.length > 0;
     }
     async getPreferences(input) {
+        input = capturePlainRecord(input, "getPreferences input", new Set(["recipientId", "topics", "channels"]));
         const { notificationPreferences } = this.#schema;
+        const recipientId = normalizeNotificationKey(input.recipientId, "preference.recipientId", 10_000);
+        const topics = normalizeNotificationKeyArray(input.topics, "preference.topic", 191);
+        const channels = normalizeNotificationKeyArray(input.channels, "preference.channel", 64);
         const stored = await this.#db
             .select({
             topic: notificationPreferences.topic,
@@ -287,8 +716,8 @@ export class UnifiedNotificationCore {
             enabled: notificationPreferences.enabled,
         })
             .from(notificationPreferences)
-            .where(eq(notificationPreferences.recipientId, input.recipientId));
-        return input.topics.flatMap((topic) => input.channels.map((channel) => resolvePreference({
+            .where(eq(canonicalNotificationKeySql(notificationPreferences.recipientId), recipientId));
+        return topics.flatMap((topic) => channels.map((channel) => resolvePreference({
             topic,
             channel,
             stored,
@@ -297,10 +726,24 @@ export class UnifiedNotificationCore {
         })));
     }
     async listInbox(input) {
+        input = capturePlainRecord(input, "listInbox input", new Set(["recipientId", "limit", "cursor", "includeArchived"]));
         const { notifications, notificationDeliveries } = this.#schema;
-        const limit = Math.min(Math.max(input.limit ?? 30, 1), 100);
-        const cursorFilter = input.cursor
-            ? or(lt(notifications.createdAt, input.cursor.createdAt), and(eq(notifications.createdAt, input.cursor.createdAt), lt(notifications.id, input.cursor.id)))
+        const recipientId = normalizeNotificationKey(input.recipientId, "inbox.recipientId", 10_000);
+        const limit = normalizeDispatchInteger(input.limit, "inbox.limit", 30, 100);
+        const includeArchived = Object.hasOwn(input, "includeArchived")
+            ? normalizeBoolean(input.includeArchived, "includeArchived")
+            : false;
+        const cursor = Object.hasOwn(input, "cursor")
+            ? capturePlainRecord(input.cursor, "inbox.cursor", new Set(["createdAt", "id"]))
+            : undefined;
+        const cursorCreatedAt = cursor
+            ? normalizeDate(cursor.createdAt, "inbox.cursor.createdAt")
+            : undefined;
+        const cursorId = cursor
+            ? normalizeNotificationKey(cursor.id, "inbox.cursor.id", 191)
+            : undefined;
+        const cursorFilter = cursorCreatedAt && cursorId
+            ? or(lt(notifications.createdAt, cursorCreatedAt), and(eq(notifications.createdAt, cursorCreatedAt), lt(notifications.id, cursorId)))
             : undefined;
         const rows = await this.#db
             .select({
@@ -320,7 +763,7 @@ export class UnifiedNotificationCore {
         })
             .from(notifications)
             .innerJoin(notificationDeliveries, eq(notificationDeliveries.notificationId, notifications.id))
-            .where(and(eq(notifications.recipientId, input.recipientId), isNull(notifications.canceledAt), eq(notificationDeliveries.channel, BUILT_IN_CHANNELS.IN_APP), eq(notificationDeliveries.status, "sent"), input.includeArchived ? undefined : isNull(notifications.archivedAt), cursorFilter))
+            .where(and(eq(notifications.recipientId, recipientId), isNull(notifications.canceledAt), eq(notificationDeliveries.channel, BUILT_IN_CHANNELS.IN_APP), eq(notificationDeliveries.status, "sent"), includeArchived ? undefined : isNull(notifications.archivedAt), cursorFilter))
             .orderBy(desc(notifications.createdAt), desc(notifications.id))
             .limit(limit + 1);
         const hasMore = rows.length > limit;
@@ -336,49 +779,73 @@ export class UnifiedNotificationCore {
     }
     async unreadCount(recipientId) {
         const { notifications, notificationDeliveries } = this.#schema;
+        const normalizedRecipientId = normalizeNotificationKey(recipientId, "inbox.recipientId", 10_000);
         const [row] = await this.#db
             .select({ value: count() })
             .from(notifications)
             .innerJoin(notificationDeliveries, eq(notificationDeliveries.notificationId, notifications.id))
-            .where(and(eq(notifications.recipientId, recipientId), isNull(notifications.readAt), isNull(notifications.archivedAt), isNull(notifications.canceledAt), eq(notificationDeliveries.channel, BUILT_IN_CHANNELS.IN_APP), eq(notificationDeliveries.status, "sent")));
+            .where(and(eq(notifications.recipientId, normalizedRecipientId), isNull(notifications.readAt), isNull(notifications.archivedAt), isNull(notifications.canceledAt), eq(notificationDeliveries.channel, BUILT_IN_CHANNELS.IN_APP), eq(notificationDeliveries.status, "sent")));
         return row?.value ?? 0;
     }
     async markRead(input) {
+        input = capturePlainRecord(input, "markRead input", new Set(["notificationId", "recipientId", "read"]));
         const { notifications } = this.#schema;
+        const read = Object.hasOwn(input, "read")
+            ? normalizeBoolean(input.read, "read")
+            : true;
+        const notificationId = normalizeNotificationKey(input.notificationId, "notificationId", 191);
+        const recipientId = normalizeNotificationKey(input.recipientId, "inbox.recipientId", 10_000);
+        const now = this.#currentTime();
         const updated = await this.#db
             .update(notifications)
             .set({
-            readAt: input.read === false ? null : this.#now(),
-            updatedAt: this.#now(),
+            readAt: read ? now : null,
+            updatedAt: now,
         })
-            .where(and(eq(notifications.id, input.notificationId), eq(notifications.recipientId, input.recipientId)))
+            .where(and(eq(notifications.id, notificationId), eq(notifications.recipientId, recipientId)))
             .returning({ id: notifications.id });
         return updated.length > 0;
     }
     async archive(input) {
+        input = capturePlainRecord(input, "archive input", new Set(["notificationId", "recipientId", "archived"]));
         const { notifications } = this.#schema;
+        const archived = Object.hasOwn(input, "archived")
+            ? normalizeBoolean(input.archived, "archived")
+            : true;
+        const notificationId = normalizeNotificationKey(input.notificationId, "notificationId", 191);
+        const recipientId = normalizeNotificationKey(input.recipientId, "inbox.recipientId", 10_000);
+        const now = this.#currentTime();
         const updated = await this.#db
             .update(notifications)
             .set({
-            archivedAt: input.archived === false ? null : this.#now(),
-            updatedAt: this.#now(),
+            archivedAt: archived ? now : null,
+            updatedAt: now,
         })
-            .where(and(eq(notifications.id, input.notificationId), eq(notifications.recipientId, input.recipientId)))
+            .where(and(eq(notifications.id, notificationId), eq(notifications.recipientId, recipientId)))
             .returning({ id: notifications.id });
         return updated.length > 0;
     }
     async cancel(notificationId) {
         const { notifications, notificationDeliveries } = this.#schema;
+        const normalizedNotificationId = normalizeNotificationKey(notificationId, "notificationId", 191);
+        const now = this.#currentTime();
         return this.#db.transaction(async (tx) => {
-            const now = this.#now();
             const updated = await tx
                 .update(notifications)
                 .set({ canceledAt: now, updatedAt: now })
-                .where(and(eq(notifications.id, notificationId), isNull(notifications.canceledAt)))
+                .where(and(eq(notifications.id, normalizedNotificationId), isNull(notifications.canceledAt)))
                 .returning({ id: notifications.id });
             if (updated.length === 0) {
                 return false;
             }
+            await tx
+                .update(notificationDeliveries)
+                .set({
+                status: "canceled",
+                nextAttemptAt: null,
+                updatedAt: now,
+            })
+                .where(and(eq(notificationDeliveries.notificationId, normalizedNotificationId), eq(notificationDeliveries.status, "processing")));
             await tx
                 .update(notificationDeliveries)
                 .set({
@@ -388,41 +855,68 @@ export class UnifiedNotificationCore {
                 lockedBy: null,
                 updatedAt: now,
             })
-                .where(and(eq(notificationDeliveries.notificationId, notificationId), inArray(notificationDeliveries.status, [
-                "pending",
-                "retrying",
-                "processing",
-            ])));
+                .where(and(eq(notificationDeliveries.notificationId, normalizedNotificationId), inArray(notificationDeliveries.status, ["pending", "retrying"])));
             return true;
         });
     }
     async requeueDelivery(input) {
-        if (input.maxAttempts !== undefined && input.maxAttempts < 1) {
-            throw new NotificationConfigurationError("maxAttempts must be at least 1");
-        }
-        const { notificationDeliveries } = this.#schema;
-        const updated = await this.#db
-            .update(notificationDeliveries)
-            .set({
-            status: "retrying",
-            attempts: input.resetAttempts ? 0 : undefined,
-            maxAttempts: input.maxAttempts,
-            nextAttemptAt: this.#now(),
-            lockedAt: null,
-            lockedBy: null,
-            errorCode: null,
-            errorMessage: null,
-            updatedAt: this.#now(),
-        })
-            .where(eq(notificationDeliveries.id, input.deliveryId))
-            .returning({ id: notificationDeliveries.id });
-        return updated.length > 0;
+        input = capturePlainRecord(input, "requeueDelivery input", new Set(["deliveryId", "resetAttempts", "maxAttempts"]));
+        const deliveryId = normalizeNotificationKey(input.deliveryId, "deliveryId", 191);
+        const resetAttempts = Object.hasOwn(input, "resetAttempts")
+            ? normalizeBoolean(input.resetAttempts, "resetAttempts")
+            : false;
+        const configuredMaxAttempts = input.maxAttempts === undefined
+            ? undefined
+            : normalizeMaxAttempts(input.maxAttempts, "maxAttempts");
+        const now = this.#currentTime();
+        const { notifications, notificationDeliveries } = this.#schema;
+        return this.#db.transaction(async (tx) => {
+            const [delivery] = await tx
+                .select({
+                attempts: notificationDeliveries.attempts,
+                maxAttempts: notificationDeliveries.maxAttempts,
+            })
+                .from(notificationDeliveries)
+                .innerJoin(notifications, eq(notificationDeliveries.notificationId, notifications.id))
+                .where(and(eq(notificationDeliveries.id, deliveryId), eq(notificationDeliveries.status, "failed"), isNull(notifications.canceledAt)))
+                .limit(1)
+                .for("update");
+            if (!delivery) {
+                return false;
+            }
+            const attempts = resetAttempts ? 0 : delivery.attempts;
+            const maxAttempts = configuredMaxAttempts ?? delivery.maxAttempts;
+            if (attempts >= maxAttempts) {
+                return false;
+            }
+            const [updated] = await tx
+                .update(notificationDeliveries)
+                .set({
+                status: "retrying",
+                attempts,
+                maxAttempts,
+                nextAttemptAt: now,
+                lockedAt: null,
+                lockedBy: null,
+                sentAt: null,
+                providerMessageId: null,
+                metadata: null,
+                errorCode: null,
+                errorMessage: null,
+                updatedAt: now,
+            })
+                .where(and(eq(notificationDeliveries.id, deliveryId), eq(notificationDeliveries.status, "failed"), eq(notificationDeliveries.attempts, delivery.attempts), eq(notificationDeliveries.maxAttempts, delivery.maxAttempts)))
+                .returning({ id: notificationDeliveries.id });
+            return updated !== undefined;
+        });
     }
     async #dispatch(options) {
-        const limit = Math.min(Math.max(options.limit ?? 100, 1), 1_000);
-        const concurrency = Math.min(Math.max(options.concurrency ?? 10, 1), 100);
-        const workerId = options.workerId ??
-            `unf-${process.pid}-${crypto.randomUUID().slice(0, 8)}`;
+        options = capturePlainRecord(options, "dispatch options", new Set(["limit", "workerId", "concurrency", "notificationIds"]));
+        assertDispatchExecutor(this.#db);
+        const limit = normalizeDispatchInteger(options.limit, "limit", 100, MAX_DISPATCH_LIMIT);
+        const concurrency = normalizeDispatchInteger(options.concurrency, "concurrency", 10, MAX_DISPATCH_CONCURRENCY);
+        const workerId = normalizeNotificationKey(options.workerId ??
+            `unf-${process.pid}-${crypto.randomUUID().slice(0, 8)}`, "workerId", 154);
         const claimed = await this.#claimDue({
             limit,
             workerId,
@@ -438,7 +932,7 @@ export class UnifiedNotificationCore {
                 nextIndex += 1;
                 const item = claimed[index];
                 if (item) {
-                    results.push(await this.#deliver(item, workerId));
+                    results.push(await this.#deliver(item));
                 }
             }
         });
@@ -447,9 +941,28 @@ export class UnifiedNotificationCore {
     }
     async #claimDue(input) {
         const { notifications, notificationDeliveries } = this.#schema;
-        const now = this.#now();
+        const now = this.#currentTime();
         const staleBefore = new Date(now.getTime() - this.#lockTimeoutMs);
         return this.#db.transaction(async (tx) => {
+            await tx
+                .update(notificationDeliveries)
+                .set({
+                status: "failed",
+                nextAttemptAt: null,
+                lockedAt: null,
+                lockedBy: null,
+                errorCode: "max_attempts_exhausted",
+                errorMessage: "Maximum delivery attempts exhausted",
+                updatedAt: now,
+            })
+                .where(and(input.notificationIds?.length
+                ? inArray(notificationDeliveries.notificationId, [
+                    ...input.notificationIds,
+                ])
+                : undefined, or(sql `${notificationDeliveries.attempts} >= ${notificationDeliveries.maxAttempts}`, sql `${notificationDeliveries.attempts} >= ${MAX_ATTEMPTS}`), or(and(inArray(notificationDeliveries.status, [
+                "pending",
+                "retrying",
+            ]), lte(notificationDeliveries.nextAttemptAt, now)), and(eq(notificationDeliveries.status, "processing"), or(isNull(notificationDeliveries.lockedAt), lt(notificationDeliveries.lockedAt, staleBefore))))));
             const due = await tx
                 .select({
                 deliveryId: notificationDeliveries.id,
@@ -470,7 +983,7 @@ export class UnifiedNotificationCore {
                 .innerJoin(notifications, eq(notificationDeliveries.notificationId, notifications.id))
                 .where(and(isNull(notifications.canceledAt), lte(notifications.scheduledFor, now), input.notificationIds?.length
                 ? inArray(notifications.id, [...input.notificationIds])
-                : undefined, or(and(inArray(notificationDeliveries.status, [
+                : undefined, sql `${notificationDeliveries.attempts} < ${notificationDeliveries.maxAttempts}`, sql `${notificationDeliveries.attempts} < ${MAX_ATTEMPTS}`, or(and(inArray(notificationDeliveries.status, [
                 "pending",
                 "retrying",
             ]), lte(notificationDeliveries.nextAttemptAt, now)), and(eq(notificationDeliveries.status, "processing"), or(isNull(notificationDeliveries.lockedAt), lt(notificationDeliveries.lockedAt, staleBefore))))))
@@ -480,40 +993,59 @@ export class UnifiedNotificationCore {
             if (due.length === 0) {
                 return [];
             }
-            await tx
-                .update(notificationDeliveries)
-                .set({
-                status: "processing",
-                lockedAt: now,
-                lockedBy: input.workerId,
-                updatedAt: now,
-            })
-                .where(inArray(notificationDeliveries.id, due.map((item) => item.deliveryId)));
-            return due.map((item) => ({
-                ...item,
-                channel: item.channel,
-                payload: item.payload,
-            }));
+            const claimed = [];
+            for (const item of due) {
+                const claimToken = `${input.workerId}:${crypto.randomUUID()}`;
+                const [updated] = await tx
+                    .update(notificationDeliveries)
+                    .set({
+                    status: "processing",
+                    attempts: sql `${notificationDeliveries.attempts} + 1`,
+                    lastAttemptAt: now,
+                    lockedAt: now,
+                    lockedBy: claimToken,
+                    updatedAt: now,
+                })
+                    .where(and(eq(notificationDeliveries.id, item.deliveryId), sql `${notificationDeliveries.attempts} < ${notificationDeliveries.maxAttempts}`, sql `${notificationDeliveries.attempts} < ${MAX_ATTEMPTS}`))
+                    .returning({
+                    attempts: notificationDeliveries.attempts,
+                    maxAttempts: notificationDeliveries.maxAttempts,
+                });
+                if (!updated) {
+                    throw new Error(`delivery ${item.deliveryId} could not be claimed`);
+                }
+                claimed.push({
+                    ...item,
+                    attempts: updated.attempts,
+                    maxAttempts: updated.maxAttempts,
+                    channel: item.channel,
+                    payload: item.payload,
+                    claimToken,
+                    claimedAt: now,
+                });
+            }
+            return claimed;
         });
     }
-    async #deliver(delivery, workerId) {
+    async #deliver(delivery) {
         const { notificationDeliveries } = this.#schema;
-        const attempt = delivery.attempts + 1;
+        const attempt = delivery.attempts;
         const adapter = delivery.channel === BUILT_IN_CHANNELS.IN_APP
             ? async () => undefined
-            : this.#adapters[delivery.channel];
+            : getOwnRecordValue(this.#adapters, delivery.channel);
+        let rawResult;
         try {
             if (!adapter) {
                 throw new NotificationDeliveryError("adapter_not_configured", `No adapter is configured for channel "${delivery.channel}"`, { retryable: false });
             }
-            const result = await adapter({
+            rawResult = await adapter({
                 notificationId: delivery.notificationId,
                 deliveryId: delivery.deliveryId,
                 recipientId: delivery.recipientId,
                 topic: delivery.topic,
                 channel: delivery.channel,
                 payload: delivery.payload,
-                channelData: delivery.payload.channelData?.[delivery.channel],
+                channelData: getOwnRecordValue(delivery.payload.channelData, delivery.channel),
                 attempt,
                 maxAttempts: delivery.maxAttempts,
                 createdAt: delivery.createdAt,
@@ -522,92 +1054,230 @@ export class UnifiedNotificationCore {
                 entityType: delivery.entityType,
                 entityId: delivery.entityId,
             });
-            const now = this.#now();
-            await this.#db
-                .update(notificationDeliveries)
-                .set({
-                status: "sent",
-                attempts: attempt,
-                lastAttemptAt: now,
-                nextAttemptAt: null,
-                lockedAt: null,
-                lockedBy: null,
-                sentAt: now,
-                providerMessageId: result?.providerMessageId ?? null,
-                metadata: result?.metadata ?? null,
-                errorCode: null,
-                errorMessage: null,
-                updatedAt: now,
-            })
-                .where(and(eq(notificationDeliveries.id, delivery.deliveryId), eq(notificationDeliveries.lockedBy, workerId), eq(notificationDeliveries.status, "processing")));
-            return {
+        }
+        catch (error) {
+            return this.#finalizeDeliveryFailure(delivery, error);
+        }
+        const result = normalizeAdapterResult(rawResult);
+        const now = delivery.claimedAt;
+        const [persisted] = await this.#db
+            .update(notificationDeliveries)
+            .set({
+            status: "sent",
+            nextAttemptAt: null,
+            lockedAt: null,
+            lockedBy: null,
+            sentAt: now,
+            providerMessageId: result.providerMessageId,
+            metadata: result.metadata,
+            errorCode: result.diagnostic ? "invalid_adapter_result" : null,
+            errorMessage: result.diagnostic,
+            updatedAt: now,
+        })
+            .where(and(eq(notificationDeliveries.id, delivery.deliveryId), eq(notificationDeliveries.lockedBy, delivery.claimToken), inArray(notificationDeliveries.status, ["processing", "canceled"])))
+            .returning({
+            status: notificationDeliveries.status,
+            attempts: notificationDeliveries.attempts,
+            errorCode: notificationDeliveries.errorCode,
+            errorMessage: notificationDeliveries.errorMessage,
+        });
+        const durable = await this.#durableDispatchResult(delivery, persisted);
+        if (result.diagnostic) {
+            this.#safeLog("error", "Notification adapter result was discarded", {
                 deliveryId: delivery.deliveryId,
                 notificationId: delivery.notificationId,
-                recipientId: delivery.recipientId,
                 channel: delivery.channel,
-                status: "sent",
-                attempt,
-            };
+                attempt: durable.attempt,
+                durableStatus: durable.status,
+                code: "invalid_adapter_result",
+                message: result.diagnostic,
+            });
         }
-        catch (error) {
-            const details = errorDetails(error);
-            const shouldRetry = details.retryable && attempt < delivery.maxAttempts;
-            const now = this.#now();
-            const delay = shouldRetry ? this.#retryDelayMs(attempt, error) : 0;
-            const status = shouldRetry ? "retrying" : "failed";
-            await this.#db
-                .update(notificationDeliveries)
-                .set({
-                status,
-                attempts: attempt,
-                lastAttemptAt: now,
-                nextAttemptAt: shouldRetry
-                    ? new Date(now.getTime() + Math.max(delay, 0))
-                    : null,
-                lockedAt: null,
-                lockedBy: null,
-                errorCode: details.code,
-                errorMessage: details.message,
-                updatedAt: now,
-            })
-                .where(and(eq(notificationDeliveries.id, delivery.deliveryId), eq(notificationDeliveries.lockedBy, workerId), eq(notificationDeliveries.status, "processing")));
-            this.#logger?.error?.("Notification delivery failed", {
+        return durable;
+    }
+    async #finalizeDeliveryFailure(delivery, error) {
+        const { notificationDeliveries } = this.#schema;
+        const details = errorDetails(error);
+        const shouldRetry = details.retryable && delivery.attempts < delivery.maxAttempts;
+        const now = delivery.claimedAt;
+        const delay = shouldRetry
+            ? await this.#safeRetryDelayMs(delivery.attempts, error, delivery, now)
+            : 0;
+        const status = shouldRetry ? "retrying" : "failed";
+        const nextAttemptAt = shouldRetry
+            ? new Date(now.getTime() + delay)
+            : null;
+        const [persisted] = await this.#db
+            .update(notificationDeliveries)
+            .set({
+            status: sql `case when ${notificationDeliveries.status} = 'canceled' then 'canceled' else ${status} end`,
+            nextAttemptAt: sql `case when ${notificationDeliveries.status} = 'canceled' then null::timestamptz else ${nextAttemptAt}::timestamptz end`,
+            lockedAt: null,
+            lockedBy: null,
+            errorCode: details.code,
+            errorMessage: details.message,
+            updatedAt: now,
+        })
+            .where(and(eq(notificationDeliveries.id, delivery.deliveryId), eq(notificationDeliveries.lockedBy, delivery.claimToken), inArray(notificationDeliveries.status, ["processing", "canceled"])))
+            .returning({
+            status: notificationDeliveries.status,
+            attempts: notificationDeliveries.attempts,
+            errorCode: notificationDeliveries.errorCode,
+            errorMessage: notificationDeliveries.errorMessage,
+        });
+        const durable = await this.#durableDispatchResult(delivery, persisted);
+        this.#safeLog("error", "Notification delivery failed", {
+            deliveryId: delivery.deliveryId,
+            notificationId: delivery.notificationId,
+            channel: delivery.channel,
+            attempt: durable.attempt,
+            retrying: durable.status === "retrying",
+            durableStatus: durable.status,
+            code: details.code,
+            message: details.message,
+        });
+        return durable;
+    }
+    async #safeRetryDelayMs(attempt, error, delivery, now) {
+        let timeout;
+        const startedAt = MONOTONIC_NOW();
+        const timedOut = () => MONOTONIC_NOW() - startedAt >= RETRY_DELAY_POLICY_TIMEOUT_MS;
+        const timeoutObservation = () => ({
+            status: "rejected",
+            reason: new NotificationConfigurationError(`retryDelayMs did not settle within ${RETRY_DELAY_POLICY_TIMEOUT_MS}ms`),
+        });
+        let settleDeadline = () => { };
+        const deadlineSettlement = new NATIVE_PROMISE((resolve) => {
+            settleDeadline = resolve;
+        });
+        timeout = NATIVE_SET_TIMEOUT(() => settleDeadline(timeoutObservation()), RETRY_DELAY_POLICY_TIMEOUT_MS);
+        try {
+            let policyResult;
+            try {
+                policyResult = this.#retryDelayMs(attempt, error);
+            }
+            catch (policyError) {
+                throw policyError;
+            }
+            let delay = policyResult;
+            if (typeof policyResult !== "number") {
+                if (!isExactNativePromise(policyResult)) {
+                    throw new NotificationConfigurationError("retryDelayMs must return a number or an exact native Promise<number>");
+                }
+                attachNativePromiseObservation(policyResult, (observation) => {
+                    settleDeadline(timedOut() ? timeoutObservation() : observation);
+                });
+                if (timedOut()) {
+                    throw new NotificationConfigurationError(`retryDelayMs did not settle within ${RETRY_DELAY_POLICY_TIMEOUT_MS}ms`);
+                }
+                const observation = await deadlineSettlement;
+                if (observation.status === "rejected") {
+                    throw observation.reason;
+                }
+                delay = observation.value;
+            }
+            else if (timedOut()) {
+                throw new NotificationConfigurationError(`retryDelayMs did not settle within ${RETRY_DELAY_POLICY_TIMEOUT_MS}ms`);
+            }
+            const nextAttemptAt = typeof delay === "number" ? new Date(now.getTime() + delay) : null;
+            if (typeof delay !== "number" ||
+                !Number.isFinite(delay) ||
+                delay < 0 ||
+                !nextAttemptAt ||
+                Number.isNaN(nextAttemptAt.getTime())) {
+                throw new NotificationConfigurationError("retryDelayMs must return a finite non-negative number");
+            }
+            return delay;
+        }
+        catch (policyError) {
+            const details = errorDetails(policyError);
+            this.#safeLog("error", "Notification retryDelayMs policy failed", {
                 deliveryId: delivery.deliveryId,
                 notificationId: delivery.notificationId,
                 channel: delivery.channel,
                 attempt,
-                retrying: shouldRetry,
                 code: details.code,
                 message: details.message,
+                fallbackDelayMs: defaultRetryDelayMs(attempt),
             });
-            return {
-                deliveryId: delivery.deliveryId,
-                notificationId: delivery.notificationId,
-                recipientId: delivery.recipientId,
-                channel: delivery.channel,
-                status,
-                attempt,
-                errorCode: details.code,
-                errorMessage: details.message,
-            };
+            return defaultRetryDelayMs(attempt);
+        }
+        finally {
+            if (timeout !== undefined) {
+                NATIVE_CLEAR_TIMEOUT(timeout);
+            }
+        }
+    }
+    #safeLog(level, message, context) {
+        try {
+            const callback = this.#logger?.[level];
+            if (!callback) {
+                return;
+            }
+            const returned = callback(message, context);
+            if (isExactNativePromise(returned)) {
+                attachNativePromiseObservation(returned, () => { });
+            }
+        }
+        catch {
+            // Observability is deliberately isolated from durable delivery state.
         }
     }
+    async #durableDispatchResult(delivery, persisted) {
+        let state = persisted;
+        if (!state) {
+            const { notificationDeliveries } = this.#schema;
+            [state] = await this.#db
+                .select({
+                status: notificationDeliveries.status,
+                attempts: notificationDeliveries.attempts,
+                errorCode: notificationDeliveries.errorCode,
+                errorMessage: notificationDeliveries.errorMessage,
+            })
+                .from(notificationDeliveries)
+                .where(eq(notificationDeliveries.id, delivery.deliveryId))
+                .limit(1);
+        }
+        if (!state) {
+            throw new Error(`delivery ${delivery.deliveryId} no longer has a durable state`);
+        }
+        return {
+            deliveryId: delivery.deliveryId,
+            notificationId: delivery.notificationId,
+            recipientId: delivery.recipientId,
+            channel: delivery.channel,
+            status: state.status,
+            attempt: state.attempts,
+            ...(state.errorCode ? { errorCode: state.errorCode } : {}),
+            ...(state.errorMessage
+                ? { errorMessage: capDiagnosticMessage(state.errorMessage) }
+                : {}),
+        };
+    }
     #validateChannels(channels) {
         for (const channel of channels) {
             assertBounded(channel, "channel", 64);
             if (channel !== BUILT_IN_CHANNELS.IN_APP &&
-                !this.#adapters[channel]) {
+                !Object.hasOwn(this.#adapters, channel)) {
                 throw new NotificationConfigurationError(`No adapter is configured for channel "${channel}"`);
             }
         }
     }
+    #currentTime() {
+        let value;
+        try {
+            value = this.#now();
+        }
+        catch {
+            throw new NotificationConfigurationError("now must return a valid Date");
+        }
+        return normalizeDate(value, "now result");
+    }
     #maxAttemptsFor(channel, configured) {
         const value = typeof configured === "number"
             ? configured
-            : configured?.[channel] ?? this.#defaultMaxAttempts;
-        if (!Number.isInteger(value) || value < 1) {
-            throw new NotificationConfigurationError(`maxAttempts for channel "${channel}" must be a positive integer`);
-        }
+            : getOwnRecordValue(configured, channel) ??
+                this.#defaultMaxAttempts;
         return value;
     }
 }