@fluojs/notifications 1.0.2 → 2.0.0

package/README.ko.md

@@ -2,6 +2,8 @@
 
 <p><a href="./README.md"><kbd>English</kbd></a> <strong><kbd>한국어</kbd></strong></p>
 
+Node.js 지원 범위는 `>=24.0.0 <27`입니다. 업그레이드 절차는 [Node.js 지원 및 마이그레이션](../../docs/reference/node-support.ko.md)을 참조하세요.
+
 fluo를 위한 채널 중립(notification channel-agnostic) 알림 오케스트레이션 패키지입니다. 알림 채널의 공통 계약을 고정하고, 친숙한 dynamic-module 사용감을 가진 명시적 모듈 등록 API를 제공하며, 선택적인 큐 기반 전달 심(seam)과 라이프사이클 이벤트 발행 심을 노출합니다.
 
 ## 목차
@@ -104,10 +106,10 @@ NotificationsModule.forRoot({
   channels: [emailChannel],
   queue: {
     adapter: {
-      async enqueue(job) {
+      async enqueue(job, context) {
         return queue.enqueue(job);
       },
-      async enqueueMany(jobs) {
+      async enqueueMany(jobs, context) {
         return Promise.all(jobs.map((job) => queue.enqueue(job)));
       },
     },
@@ -118,11 +120,16 @@ NotificationsModule.forRoot({
 
 Behavioral contract 메모:
 
-- 알림 개수가 `bulkThreshold` 이상이면 대량 큐 위임이 시작됩니다.
+- `bulkThreshold`를 생략하면 기본값 `10`을 사용합니다. 명시적 값은 유한한 양의 정수여야 하며, 잘못된 값은 notification service provider가 생성되기 전에 module option 해석을 `NotificationsConfigurationError`로 실패시킵니다.
+- 알림 개수가 `bulkThreshold` 이상이면 대량 큐 위임이 시작되며, `dispatchMany(..., { queue: true })`는 batch가 threshold보다 작아도 queue-backed delivery를 명시적으로 강제합니다.
 - `dispatch()`는 queue adapter가 구성되어 있어도 기본적으로 직접 전달을 유지합니다. 단건 알림을 큐로 보내려면 `dispatch(..., { queue: true })`를 사용합니다.
 - queue adapter가 있어도 직접 전달을 강제하려면 `dispatch(..., { queue: false })`를 사용합니다.
-- 큐 기반 전달은 단건 dispatch에서는 opt-in이고, `dispatchMany(...)`에서는 threshold 기반으로 동작합니다.
-- Queue job에는 `notification.id`가 있으면 그 값을, 없으면 notification envelope에서 파생한 deterministic `id` idempotency key가 포함됩니다. Queue adapter는 deduplication을 지원하는 backing queue에 이 값을 전달해야 합니다.
+- 큐 기반 전달은 단건 dispatch에서는 opt-in이고, `dispatchMany(...)`에서는 caller가 `{ queue: true }`를 명시하지 않는 한 threshold 기반으로 동작합니다.
+- `NotificationsQueueContext`는 `enqueue(...)`와 `enqueueMany(...)`의 선택적인 두 번째 인자입니다. dispatch의 정확한 caller-owned `AbortSignal`을 전달하며, 기존의 한 인자 adapter도 계속 유효합니다.
+- 서비스는 모든 queue handoff 직전에 signal을 확인한 뒤 같은 live signal을 adapter에 전달합니다. 이미 abort된 queued dispatch는 lifecycle event가 활성화된 경우 `requested` 다음 `failed`를 발행하지만 `enqueue(...)`나 `enqueueMany(...)`를 호출하지 않습니다. Adapter가 job을 수락한 뒤 발생한 abort signal은 이미 수락된 queue job을 취소하지 못합니다.
+- Queue adapter는 queue별 cancellation policy와 enqueue operation이 settle될 때 abort listener를 제거할 책임을 집니다. Adapter가 signal abort로 reject하면 native bulk dispatch는 reject되고 모든 requested job에 `failed`를 발행합니다. Sequential fallback은 이후 job을 queue에 넘기지 않습니다. `continueOnError: true`이면 앞서 수락된 job은 `results`에 남고 abort된 현재/나머지 job은 `failures`에 들어갑니다.
+- Queue adapter는 모든 `enqueue()` 결과와 모든 `enqueueMany()` 결과 항목을 non-empty string identifier로 resolve해야 합니다. Native `enqueueMany()`는 admission된 job count와 정확히 일치하는 own data-property 항목의 dense array를 반환해야 하며, accessor-backed 항목, sparse array, length drift는 거부됩니다. 서비스는 malformed value를 `NotificationQueueResultIntegrityError`로 거부하며 notification envelope에서 queued delivery id를 fabricate하지 않습니다.
+- Queue job은 caller가 제공한 `notification.id`를 authoritative idempotency key로 보존합니다. 값이 없으면 object key를 locale-independent code-unit order로 정렬하는 runtime-neutral serialization과 더 넓은 64-bit digest에서 deterministic fallback `id`를 파생합니다. Queue adapter는 deduplication을 지원하는 backing queue에 이 값을 전달해야 합니다. 생성된 fallback key는 cyclic opaque payload를 포함해 동등한 지원 입력에 대해 deterministic하지만, cross-release durable identity 계약은 아닙니다. 애플리케이션 또는 package upgrade를 넘어 안정적인 identity가 필요하면 `notification.id`를 설정하세요.
 - `dispatchMany(..., { continueOnError: true })`는 direct delivery 또는 순차 queue fallback enqueue에서 첫 실패를 던지는 대신 실패들을 수집합니다.
 - queue enqueue가 실패하면 서비스는 enqueue 에러를 다시 던지기 전에 결정적인 `notification.dispatch.failed` 라이프사이클 이벤트를 발행합니다. queued bulk dispatch는 queue 미구성, channel 해석, provider/adapter failure 경로를 포함해 이미 `requested`를 발행한 모든 notification에 대해 terminal `queued` 또는 `failed` 이벤트도 발행합니다.
 - `enqueueMany(...)`가 없으면 대량 queue delivery는 input order대로 각 job을 개별 enqueue하는 방식으로 fallback합니다. `continueOnError: true`이면 성공한 enqueue는 `results`에 남고 실패한 enqueue는 `failures`로 반환됩니다. 그렇지 않으면 첫 enqueue failure를 다시 던지기 전에 아직 terminal 상태가 없는 나머지 requested fallback job에 `failed` 라이프사이클 이벤트를 발행합니다.
@@ -153,7 +160,20 @@ NotificationsModule.forRoot({
 - `notification.dispatch.delivered`
 - `notification.dispatch.failed`
 
-`events.publisher`가 구성되어 있으면 `publishLifecycleEvents: false`를 설정하지 않는 한 lifecycle event publication은 기본으로 켜집니다. 채널 delivery가 `externalId`를 생략하면 시간이나 난수에 의존하지 않고 notification envelope에서 파생한 deterministic fallback delivery id가 부여되어 dispatch result가 호출자에게 안정적으로 유지됩니다. 채널 해석 실패는 `NotificationChannelNotFoundError`를 던지기 전에 `requested` 이후 `failed` 이벤트를 발행하며, 이는 영구적인 구성 오류로 취급해야 합니다. Queue enqueue와 provider delivery 실패도 `failed` 이벤트를 발행하지만, retry 여부는 underlying adapter/provider error를 기준으로 분류해야 합니다. 성공 경로 lifecycle event의 publication failure는 이미 전달된 알림을 애플리케이션 실패로 바꾸지 않도록 best-effort로 유지됩니다. `notification.dispatch.failed` publication failure는 원래 dispatch error와 publisher error를 모두 포함하는 `AggregateError`로 호출자에게 드러나므로 failed-event 보장이 조용히 약해지지 않습니다.
+`events.publisher`가 구성되어 있으면 `publishLifecycleEvents: false`를 설정하지 않는 한 lifecycle event publication은 기본으로 켜집니다. 서비스는 비어 있지 않은 `dispatchMany(...)` batch 전체를 첫 lifecycle publication 전에 admission 시점에 snapshot하고, 단건 `dispatch(...)` envelope도 channel resolution, queue job, generated identity, provider delivery에 사용하기 위해 admission 시점에 snapshot한 뒤, 별도의 immutable lifecycle event snapshot을 발행합니다. Lifecycle snapshot은 native mutable built-in을 노출하지 않습니다. `ArrayBuffer`는 byte length와 bytes를 저장하고 `ArrayBufferView` 값은 byte offset과 view kind도 보존합니다. `Map`과 `Set`은 순서가 보존된 entry/value data가 되고, `Date`는 epoch milliseconds(유효하지 않은 날짜는 `null`), `URL`은 `href`, `URLSearchParams`는 query string, `RegExp`는 source, flags, `lastIndex`를 저장합니다. Publisher는 lifecycle event를 observation-only로 다뤄야 하며 mutation으로 delivery에 영향을 주어서는 안 됩니다. 채널 delivery가 `externalId`를 생략하면 시간이나 난수에 의존하지 않는 deterministic fallback delivery id가 부여되어 dispatch result가 호출자에게 안정적으로 유지됩니다. 생성된 fallback id는 queue job id와 동일한 locale-independent key ordering 및 64-bit runtime-neutral digest를 사용하며, caller가 제공한 `notification.id`는 계속 authoritative합니다. 생성 값은 현재 envelope shape를 위한 key이지, 문서화된 full-payload hash 계약이 아닙니다. release를 넘어 durable identity가 필요하면 `notification.id`를 설정하세요. 채널 해석 실패는 `NotificationChannelNotFoundError`를 던지기 전에 `requested` 이후 `failed` 이벤트를 발행하며, 이는 영구적인 구성 오류로 취급해야 합니다. Queue enqueue와 provider delivery 실패도 `failed` 이벤트를 발행하지만, retry 여부는 underlying adapter/provider error를 기준으로 분류해야 합니다. 성공 경로 lifecycle event의 publication failure는 이미 전달된 알림을 애플리케이션 실패로 바꾸지 않도록 best-effort로 유지됩니다. `notification.dispatch.failed` publication failure는 원래 dispatch error와 publisher error를 모두 포함하는 `AggregateError`로 호출자에게 드러나므로 failed-event 보장이 조용히 약해지지 않습니다.
+
+### Lifecycle 내장 표현
+
+| 인터페이스 | 불변 필드 |
+| --- | --- |
+| `NotificationSnapshotArrayBuffer` | `kind: 'ArrayBuffer'`, `byteLength`, `bytes` |
+| `NotificationSnapshotArrayBufferView` | `kind: 'ArrayBufferView'`, `byteOffset`, `byteLength`, `bytes`, `view` |
+| `NotificationSnapshotDate` | `kind: 'Date'`, `epochMilliseconds: number \| null` |
+| `NotificationSnapshotMap<TKey, TValue>` | `kind: 'Map'`, `entries` |
+| `NotificationSnapshotRegExp` | `kind: 'RegExp'`, `source`, `flags`, `lastIndex` |
+| `NotificationSnapshotSet<TValue>` | `kind: 'Set'`, `values` |
+| `NotificationSnapshotUrl` | `kind: 'URL'`, `href` |
+| `NotificationSnapshotUrlSearchParams` | `kind: 'URLSearchParams'`, `query` |
 
 ### 의도적인 제한 사항
 
@@ -191,7 +211,17 @@ foundation 패키지는 의도적으로 다음을 **포함하지 않습니다**:
 - `NotificationChannelContext`
 - `NotificationChannelDelivery`
 - `NotificationPayload`
+- `NotificationSnapshot`
+- `NotificationSnapshotDate`
+- `NotificationSnapshotMap<TKey, TValue>`
+- `NotificationSnapshotRegExp`
+- `NotificationSnapshotSet<TValue>`
+- `NotificationSnapshotUrl`
+- `NotificationSnapshotUrlSearchParams`
+- `NotificationSnapshotArrayBuffer`
+- `NotificationSnapshotArrayBufferView`
 - `NotificationsQueueAdapter`
+- `NotificationsQueueContext`
 - `NotificationsQueueJob`
 - `NotificationsQueueOptions`
 - `NotificationsModuleOptions`
@@ -204,14 +234,19 @@ foundation 패키지는 의도적으로 다음을 **포함하지 않습니다**:
 ### 상태 및 에러
 
 - `createNotificationsPlatformStatusSnapshot(...)`
+- `NotificationsOperationMode`
 - `NotificationsPlatformStatusSnapshot`
 - `NotificationsStatusAdapterInput`
+- `NotificationsStatusDetails`
 - `NotificationsConfigurationError`
 - `NotificationChannelNotFoundError`
 - `NotificationQueueNotConfiguredError`
+- `NotificationQueueResultIntegrityError`
+
+상태 snapshot은 platform diagnostics를 위해 `readiness`, `health`, `ownership`, 그리고 `details` object를 포함합니다.
+`operationMode`, `dependencies`, `bulkQueueThreshold`, `queueConfigured`, `eventPublisherConfigured`, `eventPublicationEnabled`는 `details` 아래에 있으며 top-level snapshot field가 아닙니다. `eventPublisherConfigured`는 publisher wiring을, `eventPublicationEnabled`는 해당 publisher가 lifecycle event를 실제로 발행하는지를 기록합니다. Queue adapter가 구성되면 `details.dependencies`에 `notifications.queue-adapter`가 포함되고, lifecycle event가 event publisher를 통해 활성화되면 `notifications.event-publisher`가 포함됩니다. `publishLifecycleEvents: false`인 configured publisher는 configured 상태로 남지만 active dependency, event-backed operation mode, external ownership을 추가하지 않습니다. 활성화된 선택적 통합은 `ownership.externallyManaged: true`로 표시되지만, foundation 패키지가 concrete queue 또는 event-bus 리소스를 create/close/drain하지 않으므로 `ownsResources: false`를 유지합니다.
 
-상태 snapshot은 platform diagnostics를 위해 `operationMode`, dependency diagnostics, ownership, readiness, health 필드를 포함합니다.
-Queue adapter가 구성되면 `details.dependencies`에 `notifications.queue-adapter`가 포함되고, lifecycle event가 event publisher를 통해 발행되면 `notifications.event-publisher`가 포함됩니다. 이러한 선택적 통합은 `ownership.externallyManaged: true`로 표시되지만, foundation 패키지가 concrete queue 또는 event-bus 리소스를 create/close/drain하지 않으므로 `ownsResources: false`를 유지합니다.
+<!-- notifications-status-contract: health=eventPublisherConfigured;operationMode=eventPublicationEnabled;dependencies=eventPublicationEnabled;externalOwnership=eventPublicationEnabled;configured-but-disabled-no-channels=degraded -->
 
 ## 관련 패키지
 

package/README.md

@@ -2,6 +2,8 @@
 
 <p><strong><kbd>English</kbd></strong> <a href="./README.ko.md"><kbd>한국어</kbd></a></p>
 
+Node.js support is `>=24.0.0 <27`. See [Node.js support and migration](../../docs/reference/node-support.md) before upgrading.
+
 Channel-agnostic notification orchestration for fluo. It freezes the shared contract for notification channels, provides explicit module registration with familiar dynamic-module ergonomics, and exposes optional queue-backed delivery and lifecycle event publication seams.
 
 ## Table of Contents
@@ -104,10 +106,10 @@ NotificationsModule.forRoot({
   channels: [emailChannel],
   queue: {
     adapter: {
-      async enqueue(job) {
+      async enqueue(job, context) {
         return queue.enqueue(job);
       },
-      async enqueueMany(jobs) {
+      async enqueueMany(jobs, context) {
         return Promise.all(jobs.map((job) => queue.enqueue(job)));
       },
     },
@@ -118,11 +120,16 @@ NotificationsModule.forRoot({
 
 Behavioral contract notes:
 
-- Bulk queue delegation starts when the notification count reaches `bulkThreshold`.
+- `bulkThreshold` defaults to `10` when omitted. Explicit values must be finite positive integers; invalid values cause module options resolution to throw `NotificationsConfigurationError` before notification service providers can be constructed.
+- Bulk queue delegation starts when the notification count reaches `bulkThreshold`, and `dispatchMany(..., { queue: true })` explicitly forces queue-backed delivery even when the batch is below that threshold.
 - `dispatch()` stays direct by default even when a queue adapter is configured. Use `dispatch(..., { queue: true })` to opt one single notification into queue-backed delivery.
 - Use `dispatch(..., { queue: false })` to force direct delivery even when a queue adapter exists.
-- Queue-backed delivery is opt-in for single dispatch and threshold-driven for `dispatchMany(...)`.
-- Queue jobs include a deterministic `id` idempotency key derived from `notification.id` when present, otherwise from the notification envelope. Queue adapters should pass this value to backing queues that support deduplication.
+- Queue-backed delivery is opt-in for single dispatch and threshold-driven for `dispatchMany(...)` unless the caller explicitly passes `{ queue: true }`.
+- `NotificationsQueueContext` is the optional second argument of `enqueue(...)` and `enqueueMany(...)`. It carries the exact caller-owned `AbortSignal` from dispatch; existing one-argument adapters remain valid.
+- Before every queue handoff, the service checks the signal and then passes that same live signal to the adapter. A pre-aborted queued dispatch emits `requested` then `failed` when lifecycle events are enabled, but never calls `enqueue(...)` or `enqueueMany(...)`. A signal that aborts after an adapter accepts a job cannot revoke that accepted queue job.
+- Queue adapters own queue-specific cancellation policy and must remove any abort listeners when their enqueue operation settles. If an adapter rejects because the signal aborts, native bulk dispatch rejects and publishes `failed` for every requested job; sequential fallback never hands subsequent jobs to the queue. With `continueOnError: true`, earlier accepted jobs remain in `results` and aborted current/remaining jobs appear in `failures`.
+- Queue adapters must resolve every `enqueue()` result and every `enqueueMany()` result entry with a non-empty string identifier. Native `enqueueMany()` must return a dense array whose own data-property entries exactly match the admitted job count; accessor-backed entries, sparse arrays, and length drift are rejected. The service rejects malformed values with `NotificationQueueResultIntegrityError`; it never fabricates a queued delivery id from the notification envelope.
+- Queue jobs preserve caller-provided `notification.id` as the authoritative idempotency key. Otherwise, they derive a deterministic fallback `id` from a runtime-neutral serialization that orders object keys by locale-independent code-unit order and uses a wider 64-bit digest. Queue adapters should pass this value to backing queues that support deduplication. The generated fallback key is deterministic for equivalent supported inputs, including cyclic opaque payloads, but it is not a durable cross-release identity contract; set `notification.id` when callers need stable identity across application or package upgrades.
 - `dispatchMany(..., { continueOnError: true })` collects failures instead of throwing on the first failed direct delivery or sequential queue fallback enqueue.
 - When queue enqueue fails, the service emits deterministic `notification.dispatch.failed` lifecycle events before rethrowing the enqueue error to the caller. Queued bulk dispatch also publishes a terminal `queued` or `failed` event for every notification that already emitted `requested`, including queue-missing, channel-resolution, and provider/adapter failure paths.
 - If `enqueueMany(...)` is unavailable, bulk queue delivery falls back to enqueueing each job individually in input order. With `continueOnError: true`, successful enqueues remain visible in `results` while failed enqueues are returned in `failures`; without it, the first enqueue failure is rethrown after the remaining requested fallback jobs receive `failed` lifecycle events.
@@ -153,7 +160,20 @@ Published event names:
 - `notification.dispatch.delivered`
 - `notification.dispatch.failed`
 
-If `events.publisher` is configured, lifecycle event publication defaults to on unless `publishLifecycleEvents: false` is set. Channel deliveries that omit `externalId` receive a deterministic fallback delivery id derived from the notification envelope so dispatch results remain stable for callers without relying on time or random data. Channel resolution failures publish `requested` and then `failed` events before throwing `NotificationChannelNotFoundError`; treat those failures as permanent configuration errors. Queue enqueue and provider delivery failures also publish `failed` events, but callers should classify their retry behavior from the underlying adapter/provider error. Publication failures for success-path lifecycle events remain best-effort so a delivered notification is not converted into an application failure. Publication failures for `notification.dispatch.failed` are caller-visible as `AggregateError` values that include both the original dispatch error and the publisher error so failed-event guarantees are not silently weakened.
+If `events.publisher` is configured, lifecycle event publication defaults to on unless `publishLifecycleEvents: false` is set. The service snapshots every non-empty `dispatchMany(...)` batch at admission before its first lifecycle publication, and snapshots a single `dispatch(...)` envelope at admission for channel resolution, queue jobs, generated identity, and provider delivery. It then publishes a separate immutable lifecycle event snapshot. Lifecycle snapshots never expose native mutable built-ins: `ArrayBuffer` stores byte length and bytes, while `ArrayBufferView` values additionally preserve byte offset and view kind; `Map` and `Set` become ordered entry/value data, `Date` stores epoch milliseconds (`null` for an invalid date), `URL` stores `href`, `URLSearchParams` stores its query string, and `RegExp` stores source, flags, and `lastIndex`. Publishers must treat lifecycle events as observation-only and must not mutate them to influence delivery. Channel deliveries that omit `externalId` receive a deterministic fallback delivery id so dispatch results remain stable for callers without relying on time or random data. Generated fallback ids use the same locale-independent key ordering and 64-bit runtime-neutral digest as queue job ids, while caller-provided `notification.id` remains authoritative. They are keys for the current envelope shape, not a documented full-payload hash contract; set `notification.id` when callers need durable identity across releases. Channel resolution failures publish `requested` and then `failed` events before throwing `NotificationChannelNotFoundError`; treat those failures as permanent configuration errors. Queue enqueue and provider delivery failures also publish `failed` events, but callers should classify their retry behavior from the underlying adapter/provider error. Publication failures for success-path lifecycle events remain best-effort so a delivered notification is not converted into an application failure. Publication failures for `notification.dispatch.failed` are caller-visible as `AggregateError` values that include both the original dispatch error and the publisher error so failed-event guarantees are not silently weakened.
+
+### Lifecycle built-in representations
+
+| Interface | Immutable fields |
+| --- | --- |
+| `NotificationSnapshotArrayBuffer` | `kind: 'ArrayBuffer'`, `byteLength`, `bytes` |
+| `NotificationSnapshotArrayBufferView` | `kind: 'ArrayBufferView'`, `byteOffset`, `byteLength`, `bytes`, `view` |
+| `NotificationSnapshotDate` | `kind: 'Date'`, `epochMilliseconds: number \| null` |
+| `NotificationSnapshotMap<TKey, TValue>` | `kind: 'Map'`, `entries` |
+| `NotificationSnapshotRegExp` | `kind: 'RegExp'`, `source`, `flags`, `lastIndex` |
+| `NotificationSnapshotSet<TValue>` | `kind: 'Set'`, `values` |
+| `NotificationSnapshotUrl` | `kind: 'URL'`, `href` |
+| `NotificationSnapshotUrlSearchParams` | `kind: 'URLSearchParams'`, `query` |
 
 ### Intentional limitations
 
@@ -191,7 +211,17 @@ These limitations are part of the package contract so leaf packages can evolve i
 - `NotificationChannelContext`
 - `NotificationChannelDelivery`
 - `NotificationPayload`
+- `NotificationSnapshot`
+- `NotificationSnapshotDate`
+- `NotificationSnapshotMap<TKey, TValue>`
+- `NotificationSnapshotRegExp`
+- `NotificationSnapshotSet<TValue>`
+- `NotificationSnapshotUrl`
+- `NotificationSnapshotUrlSearchParams`
+- `NotificationSnapshotArrayBuffer`
+- `NotificationSnapshotArrayBufferView`
 - `NotificationsQueueAdapter`
+- `NotificationsQueueContext`
 - `NotificationsQueueJob`
 - `NotificationsQueueOptions`
 - `NotificationsModuleOptions`
@@ -204,14 +234,19 @@ These limitations are part of the package contract so leaf packages can evolve i
 ### Status and errors
 
 - `createNotificationsPlatformStatusSnapshot(...)`
+- `NotificationsOperationMode`
 - `NotificationsPlatformStatusSnapshot`
 - `NotificationsStatusAdapterInput`
+- `NotificationsStatusDetails`
 - `NotificationsConfigurationError`
 - `NotificationChannelNotFoundError`
 - `NotificationQueueNotConfiguredError`
+- `NotificationQueueResultIntegrityError`
+
+Status snapshots include `readiness`, `health`, `ownership`, and a `details` object for platform diagnostics.
+`operationMode`, `dependencies`, `bulkQueueThreshold`, `queueConfigured`, `eventPublisherConfigured`, and `eventPublicationEnabled` live under `details`; they are not top-level snapshot fields. `eventPublisherConfigured` records publisher wiring, while `eventPublicationEnabled` records whether that publisher emits lifecycle events. When a queue adapter is configured, `details.dependencies` includes `notifications.queue-adapter`; when lifecycle events are enabled through an event publisher, it includes `notifications.event-publisher`. A configured publisher with `publishLifecycleEvents: false` remains visible as configured but does not add an active dependency, event-backed operation mode, or external ownership. Active optional integrations mark `ownership.externallyManaged: true` while the foundation package still reports `ownsResources: false` because it does not create, close, or drain concrete queue or event-bus resources.
 
-Status snapshots include `operationMode`, dependency diagnostics, ownership, readiness, and health fields for platform diagnostics.
-When a queue adapter is configured, `details.dependencies` includes `notifications.queue-adapter`; when lifecycle events are published through an event publisher, it includes `notifications.event-publisher`. Those optional integrations mark `ownership.externallyManaged: true` while the foundation package still reports `ownsResources: false` because it does not create, close, or drain concrete queue or event-bus resources.
+<!-- notifications-status-contract: health=eventPublisherConfigured;operationMode=eventPublicationEnabled;dependencies=eventPublicationEnabled;externalOwnership=eventPublicationEnabled;configured-but-disabled-no-channels=degraded -->
 
 ## Related Packages
 

package/dist/errors.d.ts

@@ -17,4 +17,11 @@ export declare class NotificationChannelNotFoundError extends Error {
 export declare class NotificationQueueNotConfiguredError extends Error {
     constructor();
 }
+/**
+ * Thrown when a queue adapter returns an invalid queue-assigned delivery identifier.
+ */
+export declare class NotificationQueueResultIntegrityError extends Error {
+    readonly operation: 'enqueue' | 'enqueueMany';
+    constructor(operation: 'enqueue' | 'enqueueMany', message: string);
+}
 //# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,qBAAa,+BAAgC,SAAQ,KAAK;gBAC5C,OAAO,EAAE,MAAM;CAI5B;AAED;;GAEG;AACH,qBAAa,gCAAiC,SAAQ,KAAK;IAC7C,QAAQ,CAAC,OAAO,EAAE,MAAM;gBAAf,OAAO,EAAE,MAAM;CAIrC;AAED;;GAEG;AACH,qBAAa,mCAAoC,SAAQ,KAAK;;CAK7D"}
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,qBAAa,+BAAgC,SAAQ,KAAK;gBAC5C,OAAO,EAAE,MAAM;CAI5B;AAED;;GAEG;AACH,qBAAa,gCAAiC,SAAQ,KAAK;IAC7C,QAAQ,CAAC,OAAO,EAAE,MAAM;gBAAf,OAAO,EAAE,MAAM;CAIrC;AAED;;GAEG;AACH,qBAAa,mCAAoC,SAAQ,KAAK;;CAK7D;AAED;;GAEG;AACH,qBAAa,qCAAsC,SAAQ,KAAK;IAE5D,QAAQ,CAAC,SAAS,EAAE,SAAS,GAAG,aAAa;gBAApC,SAAS,EAAE,SAAS,GAAG,aAAa,EAC7C,OAAO,EAAE,MAAM;CAKlB"}

package/dist/errors.js

@@ -27,4 +27,15 @@ export class NotificationQueueNotConfiguredError extends Error {
     super('Queue-backed notification delivery requires a configured queue adapter.');
     this.name = 'NotificationQueueNotConfiguredError';
   }
+}
+
+/**
+ * Thrown when a queue adapter returns an invalid queue-assigned delivery identifier.
+ */
+export class NotificationQueueResultIntegrityError extends Error {
+  constructor(operation, message) {
+    super(`Notifications queue adapter returned an invalid ${operation}() result: ${message}.`);
+    this.operation = operation;
+    this.name = 'NotificationQueueResultIntegrityError';
+  }
 }

package/dist/index.d.ts

@@ -1,8 +1,8 @@
-export { NotificationChannelNotFoundError, NotificationQueueNotConfiguredError, NotificationsConfigurationError, } from './errors.js';
+export { NotificationChannelNotFoundError, NotificationQueueNotConfiguredError, NotificationQueueResultIntegrityError, NotificationsConfigurationError, } from './errors.js';
 export { NotificationsModule } from './module.js';
 export { NotificationsService } from './service.js';
+export type { NotificationsOperationMode, NotificationsPlatformStatusSnapshot, NotificationsStatusAdapterInput, NotificationsStatusDetails, } from './status.js';
 export { createNotificationsPlatformStatusSnapshot } from './status.js';
-export type { NotificationsPlatformStatusSnapshot, NotificationsStatusAdapterInput } from './status.js';
 export { NOTIFICATION_CHANNELS, NOTIFICATIONS } from './tokens.js';
-export type { NotificationChannel, NotificationChannelContext, NotificationChannelDelivery, NotificationDispatchBatchResult, NotificationDispatchFailure, NotificationDispatchManyOptions, NotificationDispatchOptions, NotificationDispatchRequest, NotificationDispatchResult, NotificationDispatchStatus, NotificationLifecycleEvent, NotificationLifecycleEventName, NotificationPayload, Notifications, NotificationsAsyncModuleOptions, NotificationsEventPublisher, NotificationsEventsOptions, NotificationsModuleOptions, NotificationsQueueAdapter, NotificationsQueueJob, NotificationsQueueOptions, } from './types.js';
+export type { NotificationChannel, NotificationChannelContext, NotificationChannelDelivery, NotificationDispatchBatchResult, NotificationDispatchFailure, NotificationDispatchManyOptions, NotificationDispatchOptions, NotificationDispatchRequest, NotificationDispatchResult, NotificationDispatchStatus, NotificationLifecycleEvent, NotificationLifecycleEventName, NotificationPayload, NotificationSnapshot, NotificationSnapshotArrayBuffer, NotificationSnapshotArrayBufferView, NotificationSnapshotDate, NotificationSnapshotMap, NotificationSnapshotRegExp, NotificationSnapshotSet, NotificationSnapshotUrl, NotificationSnapshotUrlSearchParams, Notifications, NotificationsAsyncModuleOptions, NotificationsEventPublisher, NotificationsEventsOptions, NotificationsModuleOptions, NotificationsQueueAdapter, NotificationsQueueContext, NotificationsQueueJob, NotificationsQueueOptions, } from './types.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,gCAAgC,EAChC,mCAAmC,EACnC,+BAA+B,GAChC,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AAClD,OAAO,EAAE,oBAAoB,EAAE,MAAM,cAAc,CAAC;AACpD,OAAO,EAAE,yCAAyC,EAAE,MAAM,aAAa,CAAC;AACxE,YAAY,EAAE,mCAAmC,EAAE,+BAA+B,EAAE,MAAM,aAAa,CAAC;AACxG,OAAO,EAAE,qBAAqB,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AACnE,YAAY,EACV,mBAAmB,EACnB,0BAA0B,EAC1B,2BAA2B,EAC3B,+BAA+B,EAC/B,2BAA2B,EAC3B,+BAA+B,EAC/B,2BAA2B,EAC3B,2BAA2B,EAC3B,0BAA0B,EAC1B,0BAA0B,EAC1B,0BAA0B,EAC1B,8BAA8B,EAC9B,mBAAmB,EACnB,aAAa,EACb,+BAA+B,EAC/B,2BAA2B,EAC3B,0BAA0B,EAC1B,0BAA0B,EAC1B,yBAAyB,EACzB,qBAAqB,EACrB,yBAAyB,GAC1B,MAAM,YAAY,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,gCAAgC,EAChC,mCAAmC,EACnC,qCAAqC,EACrC,+BAA+B,GAChC,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AAClD,OAAO,EAAE,oBAAoB,EAAE,MAAM,cAAc,CAAC;AACpD,YAAY,EACV,0BAA0B,EAC1B,mCAAmC,EACnC,+BAA+B,EAC/B,0BAA0B,GAC3B,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,yCAAyC,EAAE,MAAM,aAAa,CAAC;AACxE,OAAO,EAAE,qBAAqB,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AACnE,YAAY,EACV,mBAAmB,EACnB,0BAA0B,EAC1B,2BAA2B,EAC3B,+BAA+B,EAC/B,2BAA2B,EAC3B,+BAA+B,EAC/B,2BAA2B,EAC3B,2BAA2B,EAC3B,0BAA0B,EAC1B,0BAA0B,EAC1B,0BAA0B,EAC1B,8BAA8B,EAC9B,mBAAmB,EACnB,oBAAoB,EACpB,+BAA+B,EAC/B,mCAAmC,EACnC,wBAAwB,EACxB,uBAAuB,EACvB,0BAA0B,EAC1B,uBAAuB,EACvB,uBAAuB,EACvB,mCAAmC,EACnC,aAAa,EACb,+BAA+B,EAC/B,2BAA2B,EAC3B,0BAA0B,EAC1B,0BAA0B,EAC1B,yBAAyB,EACzB,yBAAyB,EACzB,qBAAqB,EACrB,yBAAyB,GAC1B,MAAM,YAAY,CAAC"}

package/dist/index.js

@@ -1,4 +1,4 @@
-export { NotificationChannelNotFoundError, NotificationQueueNotConfiguredError, NotificationsConfigurationError } from './errors.js';
+export { NotificationChannelNotFoundError, NotificationQueueNotConfiguredError, NotificationQueueResultIntegrityError, NotificationsConfigurationError } from './errors.js';
 export { NotificationsModule } from './module.js';
 export { NotificationsService } from './service.js';
 export { createNotificationsPlatformStatusSnapshot } from './status.js';

package/dist/module.d.ts

@@ -6,7 +6,8 @@ export declare class NotificationsModule {
      * Registers notifications providers using static options.
      *
      * @param options Static notifications module options including channels and optional queue/event integrations.
-     * @returns A global module definition that exports {@link NotificationsService}, `NOTIFICATIONS`, and `NOTIFICATION_CHANNELS`.
+     * @returns A module definition that exports {@link NotificationsService}, `NOTIFICATIONS`, and `NOTIFICATION_CHANNELS`; exports are global unless `global: false`.
+     * @throws {NotificationsConfigurationError} When channel registrations are duplicated or `queue.bulkThreshold` is not a finite positive integer.
      *
      * @example
      * ```ts
@@ -20,7 +21,8 @@ export declare class NotificationsModule {
      * Registers notifications providers from an async DI factory.
      *
      * @param options Async module options that resolve channels and optional integration seams.
-     * @returns A global module definition that memoizes async options resolution per module instance.
+     * @returns A module definition that resolves async options once per application container and exports {@link NotificationsService}, `NOTIFICATIONS`, and `NOTIFICATION_CHANNELS`; exports are global unless `global: false`.
+     * @throws {NotificationsConfigurationError} During options resolution when channel registrations are duplicated or `queue.bulkThreshold` is not a finite positive integer.
      *
      * @example
      * ```ts

package/dist/module.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"module.d.ts","sourceRoot":"","sources":["../src/module.ts"],"names":[],"mappings":"AAEA,OAAO,EAAgB,KAAK,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAKhE,OAAO,KAAK,EAMV,+BAA+B,EAC/B,0BAA0B,EAC3B,MAAM,YAAY,CAAC;AA2GpB,gEAAgE;AAChE,qBAAa,mBAAmB;IAC9B;;;;;;;;;;;;OAYG;IACH,MAAM,CAAC,OAAO,CAAC,OAAO,GAAE,0BAA+B,GAAG,UAAU;IAIpE;;;;;;;;;;;;;;;OAeG;IACH,MAAM,CAAC,YAAY,CAAC,OAAO,EAAE,+BAA+B,GAAG,UAAU;CAG1E"}
+{"version":3,"file":"module.d.ts","sourceRoot":"","sources":["../src/module.ts"],"names":[],"mappings":"AAEA,OAAO,EAAgB,KAAK,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAKhE,OAAO,KAAK,EAMV,+BAA+B,EAC/B,0BAA0B,EAC3B,MAAM,YAAY,CAAC;AA8GpB,gEAAgE;AAChE,qBAAa,mBAAmB;IAC9B;;;;;;;;;;;;;OAaG;IACH,MAAM,CAAC,OAAO,CAAC,OAAO,GAAE,0BAA+B,GAAG,UAAU;IAIpE;;;;;;;;;;;;;;;;OAgBG;IACH,MAAM,CAAC,YAAY,CAAC,OAAO,EAAE,+BAA+B,GAAG,UAAU;CAG1E"}

package/dist/module.js

@@ -12,6 +12,9 @@ function normalizeNotificationsModuleOptions(options = {}) {
     }
     seenChannelNames.add(channel.channel);
   }
+  if (options.queue?.bulkThreshold !== undefined && (!Number.isFinite(options.queue.bulkThreshold) || !Number.isInteger(options.queue.bulkThreshold) || options.queue.bulkThreshold <= 0)) {
+    throw new NotificationsConfigurationError('Notifications queue bulkThreshold must be a finite positive integer.');
+  }
   return {
     channels: Object.freeze(channels),
     events: options.events ? {
@@ -20,7 +23,7 @@ function normalizeNotificationsModuleOptions(options = {}) {
     } : undefined,
     queue: options.queue ? {
       adapter: options.queue.adapter,
-      bulkThreshold: Math.max(1, options.queue.bulkThreshold ?? DEFAULT_BULK_QUEUE_THRESHOLD)
+      bulkThreshold: options.queue.bulkThreshold ?? DEFAULT_BULK_QUEUE_THRESHOLD
     } : undefined
   };
 }
@@ -55,13 +58,6 @@ function buildNotificationsModule(options) {
 function buildNotificationsModuleAsync(options) {
   class NotificationsAsyncModuleDefinition {}
   const factory = options.useFactory;
-  let cachedResult;
-  const memoizedFactory = (...deps) => {
-    if (!cachedResult) {
-      cachedResult = Promise.resolve(factory(...deps)).then(resolved => normalizeNotificationsModuleOptions(resolved));
-    }
-    return cachedResult;
-  };
   return defineModule(NotificationsAsyncModuleDefinition, {
     exports: [NotificationsService, NOTIFICATIONS, NOTIFICATION_CHANNELS],
     global: options.global ?? true,
@@ -69,7 +65,7 @@ function buildNotificationsModuleAsync(options) {
       inject: options.inject,
       provide: NOTIFICATIONS_OPTIONS,
       scope: 'singleton',
-      useFactory: (...deps) => memoizedFactory(...deps)
+      useFactory: (...deps) => Promise.resolve(factory(...deps)).then(resolved => normalizeNotificationsModuleOptions(resolved))
     })
   });
 }
@@ -80,7 +76,8 @@ export class NotificationsModule {
    * Registers notifications providers using static options.
    *
    * @param options Static notifications module options including channels and optional queue/event integrations.
-   * @returns A global module definition that exports {@link NotificationsService}, `NOTIFICATIONS`, and `NOTIFICATION_CHANNELS`.
+   * @returns A module definition that exports {@link NotificationsService}, `NOTIFICATIONS`, and `NOTIFICATION_CHANNELS`; exports are global unless `global: false`.
+   * @throws {NotificationsConfigurationError} When channel registrations are duplicated or `queue.bulkThreshold` is not a finite positive integer.
    *
    * @example
    * ```ts
@@ -97,7 +94,8 @@ export class NotificationsModule {
    * Registers notifications providers from an async DI factory.
    *
    * @param options Async module options that resolve channels and optional integration seams.
-   * @returns A global module definition that memoizes async options resolution per module instance.
+   * @returns A module definition that resolves async options once per application container and exports {@link NotificationsService}, `NOTIFICATIONS`, and `NOTIFICATION_CHANNELS`; exports are global unless `global: false`.
+   * @throws {NotificationsConfigurationError} During options resolution when channel registrations are duplicated or `queue.bulkThreshold` is not a finite positive integer.
    *
    * @example
    * ```ts

package/dist/service.d.ts

@@ -20,6 +20,7 @@ export declare class NotificationsService implements Notifications {
      * @returns A normalized dispatch result describing direct vs queued delivery.
      * @throws {NotificationChannelNotFoundError} When no registered channel matches `notification.channel`.
      * @throws {NotificationQueueNotConfiguredError} When queue delivery is requested without a queue adapter.
+     * @throws {NotificationQueueResultIntegrityError} When a queue adapter returns an invalid delivery identifier.
      *
      * @example
      * ```ts
@@ -32,6 +33,7 @@ export declare class NotificationsService implements Notifications {
      * ```
      */
     dispatch<TRequest extends NotificationDispatchRequest>(notification: TRequest, options?: NotificationDispatchOptions): Promise<NotificationDispatchResult>;
+    private dispatchAdmitted;
     /**
      * Dispatches multiple notifications in input order with optional bulk queue delegation.
      *
@@ -40,6 +42,7 @@ export declare class NotificationsService implements Notifications {
      * @param options Optional queue preference and tolerant error-handling controls.
      * @returns A batch summary containing successes and captured failures.
      * @throws {NotificationQueueNotConfiguredError} When queue-backed bulk delivery is requested without a queue adapter.
+     * @throws {NotificationQueueResultIntegrityError} When a queue adapter returns invalid delivery identifiers.
      */
     dispatchMany<TRequest extends NotificationDispatchRequest>(notifications: readonly TRequest[], options?: NotificationDispatchManyOptions): Promise<NotificationDispatchBatchResult<TRequest>>;
     /**

package/dist/service.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"service.d.ts","sourceRoot":"","sources":["../src/service.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EACV,oCAAoC,EACpC,mBAAmB,EACnB,+BAA+B,EAC/B,+BAA+B,EAC/B,2BAA2B,EAC3B,2BAA2B,EAC3B,0BAA0B,EAE1B,aAAa,EAEd,MAAM,YAAY,CAAC;AAEpB;;;;;;;GAOG;AACH,qBACa,oBAAqB,YAAW,aAAa;IAItD,OAAO,CAAC,QAAQ,CAAC,OAAO;IAH1B,OAAO,CAAC,QAAQ,CAAC,cAAc,CAA0C;gBAGtD,OAAO,EAAE,oCAAoC,EAC9D,QAAQ,EAAE,SAAS,mBAAmB,EAAE;IAO1C;;;;;;;;;;;;;;;;;;;OAmBG;IACG,QAAQ,CAAC,QAAQ,SAAS,2BAA2B,EACzD,YAAY,EAAE,QAAQ,EACtB,OAAO,GAAE,2BAAgC,GACxC,OAAO,CAAC,0BAA0B,CAAC;IAmEtC;;;;;;;;OAQG;IACG,YAAY,CAAC,QAAQ,SAAS,2BAA2B,EAC7D,aAAa,EAAE,SAAS,QAAQ,EAAE,EAClC,OAAO,GAAE,+BAAoC,GAC5C,OAAO,CAAC,+BAA+B,CAAC,QAAQ,CAAC,CAAC;IAiGrD;;;;OAIG;IACH,4BAA4B;IAS5B,OAAO,CAAC,cAAc;IAStB,OAAO,CAAC,gBAAgB;IAQxB,OAAO,CAAC,cAAc;IAUtB,OAAO,CAAC,mBAAmB;IAY3B,OAAO,CAAC,mBAAmB;IAQ3B,OAAO,CAAC,4BAA4B;IAQpC,OAAO,CAAC,yBAAyB;IAIjC,OAAO,CAAC,WAAW;YAYL,qBAAqB;YA4BrB,+BAA+B;YAgB/B,4BAA4B;YAmB5B,6BAA6B;YA0B7B,+BAA+B;YAmB/B,0CAA0C;CA4DzD"}
+{"version":3,"file":"service.d.ts","sourceRoot":"","sources":["../src/service.ts"],"names":[],"mappings":"AAaA,OAAO,KAAK,EACV,oCAAoC,EACpC,mBAAmB,EACnB,+BAA+B,EAC/B,+BAA+B,EAC/B,2BAA2B,EAC3B,2BAA2B,EAC3B,0BAA0B,EAE1B,aAAa,EAEd,MAAM,YAAY,CAAC;AAEpB;;;;;;;GAOG;AACH,qBACa,oBAAqB,YAAW,aAAa;IAItD,OAAO,CAAC,QAAQ,CAAC,OAAO;IAH1B,OAAO,CAAC,QAAQ,CAAC,cAAc,CAA0C;gBAGtD,OAAO,EAAE,oCAAoC,EAC9D,QAAQ,EAAE,SAAS,mBAAmB,EAAE;IAO1C;;;;;;;;;;;;;;;;;;;;OAoBG;IACG,QAAQ,CAAC,QAAQ,SAAS,2BAA2B,EACzD,YAAY,EAAE,QAAQ,EACtB,OAAO,GAAE,2BAAgC,GACxC,OAAO,CAAC,0BAA0B,CAAC;YAMxB,gBAAgB;IA6E9B;;;;;;;;;OASG;IACG,YAAY,CAAC,QAAQ,SAAS,2BAA2B,EAC7D,aAAa,EAAE,SAAS,QAAQ,EAAE,EAClC,OAAO,GAAE,+BAAoC,GAC5C,OAAO,CAAC,+BAA+B,CAAC,QAAQ,CAAC,CAAC;IAiHrD;;;;OAIG;IACH,4BAA4B;IAU5B,OAAO,CAAC,cAAc;IAStB,OAAO,CAAC,gBAAgB;IAQxB,OAAO,CAAC,cAAc;IAUtB,OAAO,CAAC,mBAAmB;IAY3B,OAAO,CAAC,mBAAmB;IAQ3B,OAAO,CAAC,4BAA4B;IAQpC,OAAO,CAAC,yBAAyB;IAIjC,OAAO,CAAC,WAAW;YAYL,qBAAqB;YA4BrB,+BAA+B;YAgB/B,4BAA4B;YAmB5B,6BAA6B;YA0B7B,+BAA+B;YAmB/B,0CAA0C;CA6DzD"}