suaveplan/openspec/specs/api-plugin-notifications/spec.md

<!-- markdownlint-disable MD024 -->

# Capability Spec Delta: api-plugin-notifications (add-api-plugin-notifications)

**Package**: `@suaveplan/api-plugin-notifications`
**Status**: PROPOSED

> Every requirement below carries a `**Verified by:**` line at authoring time.

## ADDED Requirements

### Requirement: Plugin factory and lifecycle

The package SHALL export `createNotificationsPlugin(options?:
NotificationsPluginConfigInput, services?: NotificationsPluginServices)`
returning a `PluginDescriptor<NotificationsPluginConfig>` that mounts
both the `/notifications` and `/push` route groups against
`@suaveplan/api`. The factory SHALL Zod-validate input via
`NotificationsPluginOptionsSchema` and throw
`NotificationsPluginError(INVALID_CONFIG)` carrying the `ZodError`
as `cause` on invalid input. `onInit` SHALL register
`notificationRepository`, `deviceTokenRepository`, and (when
`enablePush`) `apnService` in the host's `ServiceRegistry`. When the
caller supplies `services.emailService`, `onInit` SHALL register it
under the `emailService` slot. When the config has `enableDispatcher:
true`, `onInit` SHALL construct a `NotificationDispatcher` wired with
every available channel (`apn` if `apnService` is registered, `email`
if `emailService` is registered) and register it under
`notificationDispatcher`; the dispatcher SHALL refuse to construct
when zero channels are available
(`NotificationsPluginError(DISPATCH_CHANNEL_UNAVAILABLE)`). `onReady`
SHALL mount both route trees and refuse to double-mount. `onClose`
SHALL shut down the APN transport (if any), null the dispatcher
reference, and clear runtime state.

**Verified by:** `src/plugin/plugin.test.ts`, `src/schemas/options.test.ts`,
`src/api-plugin-notifications.spec-conformance.test.ts`.

#### Scenario: valid options produce a descriptor

- **WHEN** `createNotificationsPlugin({ basePath: "/v1/notifications" })` is called
- **THEN** the descriptor has `name === "notifications"`, `dependencies === ["database"]`, and `defaults.basePath === "/v1/notifications"`

#### Scenario: invalid options fail fast

- **WHEN** `createNotificationsPlugin({ basePath: "" } as never)` is called
- **THEN** the call throws `NotificationsPluginError` with `code === NOTIFICATIONS_PLUGIN_CODES.INVALID_CONFIG`

#### Scenario: onInit registers repositories

- **WHEN** `onInit(ctx)` runs with a real `db` service in the registry
- **THEN** `ctx.getService("notificationRepository")` and `ctx.getService("deviceTokenRepository")` resolve to non-null instances

#### Scenario: onInit fails without database service

- **WHEN** `onInit(ctx)` runs with no `db` service registered
- **THEN** it throws `NotificationsPluginError(SERVICE_NOT_AVAILABLE)`

#### Scenario: onInit registers APN when enabled

- **WHEN** `onInit(ctx)` runs with `enablePush === true` and a valid `apn` config
- **THEN** `ctx.getService("apnService")` resolves to an `ApnService` instance whose `isInitialized()` returns `true`

#### Scenario: onInit fails when enablePush without apn

- **WHEN** `onInit(ctx)` runs with `enablePush === true` and `apn === undefined`
- **THEN** it throws `NotificationsPluginError(APN_CONFIG_MISSING)`

#### Scenario: onInit registers notificationDispatcher when enableDispatcher is on

- **WHEN** `onInit(ctx)` runs with `enableDispatcher: true`, `enablePush: true`, and a valid APN config
- **THEN** `ctx.getService("notificationDispatcher")` resolves to a `NotificationDispatcher` whose `dispatch({ channel: "apn", … })` succeeds

#### Scenario: onInit refuses dispatcher with zero channels

- **WHEN** `onInit(ctx)` runs with `enableDispatcher: true`, `enablePush: false`, and no `emailService` injected
- **THEN** it throws `NotificationsPluginError(DISPATCH_CHANNEL_UNAVAILABLE)`

#### Scenario: onReady mounts both route trees

- **WHEN** `onReady(ctx)` runs after `onInit`
- **THEN** `ctx.getService("app").routes` contains entries whose `path` begins with the configured `basePath` AND with the configured `pushBasePath`

#### Scenario: onReady refuses to double-mount

- **WHEN** `onReady(ctx)` is invoked twice against the same app instance
- **THEN** the second call throws `NotificationsPluginError(ROUTE_PREFIX_COLLISION)`

#### Scenario: onClose clears repositories AND dispatcher

- **WHEN** `onClose()` is invoked after a successful boot with `enableDispatcher: true`
- **THEN** the dispatcher reference is nulled and subsequent `onReady` invocations against a fresh app raise `SERVICE_NOT_AVAILABLE`

### Requirement: NotificationRepository contract

The package SHALL export a `NotificationRepository` class implementing
`INotificationRepository` against the genesis `SurrealAdapter`. Every
statement SHALL use positional placeholders (`$p0`, `$p1`, …) matching
the `DatabaseAdapter.query(sql, params: readonly unknown[])` surface.
Twelve operations SHALL be present: `create`, `findById`,
`findByRecipient`, `getUnreadCount`, `update`, `markAsRead`,
`markManyAsRead`, `markAllAsRead`, `dismiss`, `delete`,
`findGroupedByType`, `deleteOldRead`. Record-id normalisation
SHALL accept both bare and prefixed ids; SurrealDB `RecordId` row
shapes SHALL collapse to string ids inside `transformRecord`.

**Verified by:** `src/repositories/notification-repository/notification-repository.test.ts`.

#### Scenario: create returns transformed row

- **WHEN** `repo.create({ type, recipient, content })` returns a fresh notification id
- **THEN** the returned `Notification.id` is a string, even when the adapter returned a `{ tb, id }` RecordId shape

#### Scenario: empty adapter row raises NOTIFICATION_CREATE_FAILED

- **WHEN** the adapter returns `[]` on CREATE
- **THEN** the repository throws `NotificationsPluginError(NOTIFICATION_CREATE_FAILED)`

#### Scenario: findByRecipient builds the SurrealQL filter

- **WHEN** `findByRecipient(userId, siteId, opts)` is called with every option
- **THEN** the SurQL string contains `WHERE recipient = type::thing('user', $p0)`, `AND site = type::thing('site', $p…)`, `AND read = false`, `AND type = $p…`, `AND created_at > $p…`, `LIMIT $p…`, and `START $p…`

#### Scenario: deleteOldRead rejects negative input

- **WHEN** `deleteOldRead(-1)` is invoked
- **THEN** the repository throws `NotificationsPluginError(INVALID_CONFIG)`

### Requirement: DeviceTokenRepository contract

The package SHALL export a `DeviceTokenRepository` class implementing
`IDeviceTokenRepository`. Eight operations SHALL be present:
`register`, `findById`, `findByToken`, `findActiveForUser`,
`deactivate`, `deactivateByToken`, `touchLastUsed`, `cleanup`.
Duplicate-token detection SHALL fold the SurrealDB UNIQUE-index
violation into `DEVICE_TOKEN_DUPLICATE`. Other adapter failures SHALL
fold into `DEVICE_TOKEN_CREATE_FAILED`.

**Verified by:** `src/repositories/device-token-repository/device-token-repository.test.ts`.

#### Scenario: duplicate token raises DEVICE_TOKEN_DUPLICATE

- **WHEN** the adapter throws an error mentioning `token` on CREATE
- **THEN** the repository throws `NotificationsPluginError(DEVICE_TOKEN_DUPLICATE)`

#### Scenario: generic create failure raises DEVICE_TOKEN_CREATE_FAILED

- **WHEN** the adapter throws an unrelated error on CREATE
- **THEN** the repository throws `NotificationsPluginError(DEVICE_TOKEN_CREATE_FAILED)`

#### Scenario: cleanup rejects negative daysOld

- **WHEN** `cleanup(-1)` is invoked
- **THEN** the repository throws `NotificationsPluginError(INVALID_CONFIG)`

### Requirement: ApnService with pluggable transport

The package SHALL export an `ApnService` class that validates its
config, builds an `ApnTransport` (default:
`createMemoryApnTransport`), and exposes
`initialize` / `sendNotification` / `sendBulkNotifications` /
`shutdown` / `isInitialized`. Per-device failures SHALL appear inside
the returned `PushNotificationResult.errors` array; the service SHALL
NOT throw for per-device delivery failures. Transport-init errors
SHALL fold into `APN_TRANSPORT_INIT_FAILED`; transport-shutdown
errors fold into `APN_TRANSPORT_SHUTDOWN_FAILED`. The
`MemoryApnTransport` ships as the deterministic default; hosts inject
their own transport for production `@parse/node-apn` delivery.

**Verified by:** `src/services/apn-service/apn-service.test.ts`,
`src/transport/apn-transport/apn-transport.test.ts`.

#### Scenario: missing auth material raises APN_CONFIG_MISSING

- **WHEN** `initialize()` runs with no `cert`, `key`, `pfx`, or `token`
- **THEN** the service throws `NotificationsPluginError(APN_CONFIG_MISSING)`

#### Scenario: incomplete token raises APN_CONFIG_INVALID

- **WHEN** `initialize()` runs with `token: { key, keyId: "", teamId }`
- **THEN** the service throws `NotificationsPluginError(APN_CONFIG_INVALID)`

#### Scenario: per-device failure surfaces in the result

- **WHEN** `sendNotification` is called against a transport whose `failurePlan` maps `bad` → `{ status: 410, reason: "Unregistered" }`
- **THEN** the call resolves with `{ sent: 0, failed: 1, errors: [{ status: 410, reason: "Unregistered" }] }` — no throw

#### Scenario: transport-thrown error folds into a synthetic failure

- **WHEN** `sendNotification` is called against a transport whose `send` throws
- **THEN** the call resolves with `{ sent: 0, failed: 1, errors: [{ error: <message> }] }` — no throw

#### Scenario: bulk send empty list returns 0/0

- **WHEN** `sendBulkNotifications([], payload)` is invoked
- **THEN** the call resolves with `{ sent: 0, failed: 0 }` without contacting the transport

### Requirement: Hono OpenAPI route groups

The package SHALL export `createNotificationsRoutes(config)` and
`createPushRoutes(config)` that return `OpenAPIHono` route bundles.
Notifications routes SHALL cover 11 endpoints (list, unread-count,
create, get, patch, mark-read, mark-many, mark-all, dismiss, delete,
grouped-by-type). Push routes SHALL cover 5 endpoints (register
token, unregister token, list tokens, send single, send bulk).
Every route SHALL require auth via `c.get("user")` and return
`401 { error, code: NOTIFICATIONS_PLUGIN.UNAUTHENTICATED }` when
missing. Mutating routes SHALL verify the notification belongs to
the authenticated user; mismatches return `403 { code: FORBIDDEN }`.
Delivery endpoints SHALL return `503` when `apnService === null`
(i.e. `enablePush === false`). Every successful mutation SHALL
forward a `NotificationsRouteEvent` to the host's `ctx.eventBus`
through the injected `emitEvent` callback.

**Verified by:** `src/routes/notifications-routes/notifications-routes.test.ts`,
`src/routes/push-routes/push-routes.test.ts`.

#### Scenario: missing user returns 401

- **WHEN** any route is hit without `c.get("user")` set
- **THEN** the response is `401` with body `{ error: "Authentication required", code: "NOTIFICATIONS_PLUGIN.UNAUTHENTICATED" }`

#### Scenario: ownership mismatch returns 403

- **WHEN** `PATCH /notifications/{id}` is invoked by a user whose id does not match the notification's `recipient`
- **THEN** the response is `403` with `code: NOTIFICATIONS_PLUGIN.FORBIDDEN`

#### Scenario: delivery without APN returns 503

- **WHEN** `POST /push/send` is invoked with `apnService === null` in the route config
- **THEN** the response is `503` with `code: NOTIFICATIONS_PLUGIN.APN_SERVICE_UNAVAILABLE`

#### Scenario: successful create forwards event-bus event

- **WHEN** `POST /notifications` succeeds
- **THEN** the injected `emitEvent` callback receives `{ type: "notification:created", payload: { notificationId, recipientId, type } }`

#### Scenario: duplicate device token returns 409

- **WHEN** `POST /push/tokens` is invoked with a token that triggers `DEVICE_TOKEN_DUPLICATE`
- **THEN** the response is `409` with `code: NOTIFICATIONS_PLUGIN.DEVICE_TOKEN_DUPLICATE`

#### Scenario: bulk send caps recipients at maxBulkRecipients

- **WHEN** `POST /push/send-bulk` is invoked with `userIds` longer than `maxBulkRecipients`
- **THEN** the route processes only the first `maxBulkRecipients` entries; `totalUsers` reflects the cap

### Requirement: Error-code registry

The package SHALL export `NOTIFICATIONS_PLUGIN_CODES` (frozen
record built by `defineCodes("NOTIFICATIONS_PLUGIN", [...])`) and a
`NotificationsPluginError` class extending `SuaveplanError`. Every
code SHALL be reachable from at least one production source file;
the spec-conformance test SHALL grep the source tree to assert
reachability.

**Verified by:** `src/error-codes/error-codes.test.ts`.

#### Scenario: namespace literal is NOTIFICATIONS_PLUGIN

- **WHEN** every value of `NOTIFICATIONS_PLUGIN_CODES` is inspected
- **THEN** each value starts with `"NOTIFICATIONS_PLUGIN."`

#### Scenario: every code reachable from src/

- **WHEN** the spec test concatenates every non-test `.ts` under `src/`
- **THEN** the concatenation contains `NOTIFICATIONS_PLUGIN_CODES.<KEY>` for every key

### Requirement: OpenTelemetry instruments

The package SHALL expose `getNotificationsInstruments()` /
`resetNotificationsInstruments()` returning six counters
(`notificationsCreatedTotal`, `notificationsReadTotal`,
`notificationsDeletedTotal`, `pushSentTotal`, `pushFailedTotal`,
`deviceTokensRegisteredTotal`). Each counter SHALL be emitted from
at least one production code path and SHALL be observable through
an `InMemoryMetricExporter` in the test suite.

**Verified by:** `src/otel/instruments.test.ts`.

#### Scenario: bundle is memoised

- **WHEN** `getNotificationsInstruments()` is called twice without a reset
- **THEN** both calls return the same object reference

#### Scenario: counters emit on flush

- **WHEN** counters are incremented and `flushTestMetrics()` is called
- **THEN** the exporter snapshot contains every counter name

### Requirement: Service-registry augmentation

The package SHALL augment
`@suaveplan/api-plugin/service-registry`'s `ServiceRegistry`
interface with three slots: `notificationRepository`
(`INotificationRepository`), `deviceTokenRepository`
(`IDeviceTokenRepository`), and `apnService` (`ApnService`). The
package barrel SHALL side-effect import the augmentation so
consumers that import any public symbol pick up the type widening
automatically.

**Verified by:** `src/api-plugin-notifications.spec-conformance.test.ts`.

#### Scenario: registry slots typed

- **WHEN** a downstream consumer calls `ctx.getService("notificationRepository")` against the augmented registry
- **THEN** the result type narrows to `INotificationRepository | undefined` without a cast

### Requirement: NotificationDispatcher orchestrator

The package SHALL export a `NotificationDispatcher` class that
resolves `@suaveplan/notification-channel`'s `DeliveryChannel`
instances by the dispatcher-facing channel name and exposes a
`dispatch(input: DispatchInput): Promise<DispatchResult>` surface.
The dispatcher SHALL fan a single input out to one of the registered
delivery channels (defaulting to the configured `defaultChannel`),
record an OTel counter increment per dispatch
(`notificationsDispatchedTotal` on success,
`notificationsDispatchFailedTotal` on failure), and forward a
`delivery:sent` or `delivery:bounced` event through the configured
`DeliveryEventStore` (when one is supplied). Channel selection
failures SHALL surface as
`NotificationsPluginError(DISPATCH_CHANNEL_UNAVAILABLE)`. Underlying
transport failures returned by the channel as `success === false`
SHALL surface as `NotificationsPluginError(DISPATCH_FAILED)` carrying
the channel error as `cause`. Per-dispatch idempotency SHALL be
applied through an injected `DispatcherIdempotencyAdapter` whose
default implementation (`NoopIdempotencyAdapter`) is the identity.

**Verified by:** `src/dispatcher/notification-dispatcher/notification-dispatcher.test.ts::"dispatch routes to the default channel"`, `src/dispatcher/notification-dispatcher/notification-dispatcher.test.ts::"dispatch routes to an explicit channel"`, `src/dispatcher/notification-dispatcher/notification-dispatcher.test.ts::"dispatch raises DISPATCH_CHANNEL_UNAVAILABLE for an unknown channel"`, `src/dispatcher/notification-dispatcher/notification-dispatcher.test.ts::"dispatch raises DISPATCH_FAILED when the channel returns failed"`, `src/dispatcher/notification-dispatcher/notification-dispatcher.test.ts::"dispatch records delivery:sent through the configured store"`, `src/dispatcher/notification-dispatcher/notification-dispatcher.test.ts::"dispatch records delivery:bounced when the channel fails"`, `src/dispatcher/notification-dispatcher/notification-dispatcher.test.ts::"dispatch emits notificationsDispatchedTotal on success"`, `src/dispatcher/notification-dispatcher/notification-dispatcher.test.ts::"dispatch emits notificationsDispatchFailedTotal on failure"`.

#### Scenario: dispatch routes to the default channel when channel is unspecified

- **WHEN** `dispatcher.dispatch({ recipient, body })` is called and `defaultChannel === "apn"`
- **THEN** the registered APN `DeliveryChannel` receives `send(notification)` and the result `channel === "apn"`

#### Scenario: dispatch routes to an explicit channel when provided

- **WHEN** `dispatcher.dispatch({ recipient, body, channel: "email" })` is called against a dispatcher with both `apn` and `email` channels registered
- **THEN** only the email channel receives `send`, and the result `channel === "email"`

#### Scenario: unknown channel raises DISPATCH_CHANNEL_UNAVAILABLE

- **WHEN** `dispatcher.dispatch({ channel: "sms", … })` is called and no `sms` channel is registered
- **THEN** the call rejects with `NotificationsPluginError(DISPATCH_CHANNEL_UNAVAILABLE)`

#### Scenario: channel-returned failure raises DISPATCH_FAILED

- **WHEN** the underlying channel's `send` returns `{ success: false, error: "transport failed" }`
- **THEN** `dispatch` rejects with `NotificationsPluginError(DISPATCH_FAILED)` whose `context.channelError === "transport failed"`

#### Scenario: delivery-tracking sees a delivery:sent event on success

- **WHEN** `dispatch` succeeds and a `DeliveryEventStore` is configured
- **THEN** the store records a `DeliveryEvent` with `eventType === "sent"`, the dispatcher's tenantId, and `messageId === dispatchResult.id`

#### Scenario: delivery-tracking sees a delivery:bounced event on failure

- **WHEN** `dispatch` fails through a channel failure and a `DeliveryEventStore` is configured
- **THEN** the store records a `DeliveryEvent` with `eventType === "bounced"`

#### Scenario: idempotency adapter dedupes repeated dispatches

- **WHEN** the dispatcher is configured with an adapter that caches by key and `dispatch` is invoked twice with the same key
- **THEN** the underlying channel's `send` is called only once

### Requirement: ApnDeliveryChannel adapter

The package SHALL export an `ApnDeliveryChannel` class implementing
`@suaveplan/notification-channel`'s `DeliveryChannel` interface
against the in-package `ApnService`. The channel SHALL be registered
under `name === "apn"` and SHALL accept the device token via
`Notification.metadata.deviceToken` (string) or
`Notification.metadata.deviceTokens` (string array, for fan-out).
Missing-token inputs SHALL return
`{ success: false, error: "deviceToken metadata required" }`. APN
per-device failures SHALL fold into a single `DeliveryResult` whose
`success` reflects whether at least one delivery succeeded.

**Verified by:** `src/channels/apn-channel/apn-channel.test.ts::"sends through ApnService for a single deviceToken"`, `src/channels/apn-channel/apn-channel.test.ts::"fans out to multiple deviceTokens via metadata.deviceTokens"`, `src/channels/apn-channel/apn-channel.test.ts::"returns success false when deviceToken metadata is missing"`, `src/channels/apn-channel/apn-channel.test.ts::"folds APN per-device failures into the DeliveryResult"`, `src/channels/apn-channel/apn-channel.test.ts::"reports canSend true only for push channel notifications"`.

#### Scenario: single deviceToken in metadata

- **WHEN** `apnChannel.send({ channel: "push", metadata: { deviceToken: "tok" }, body: "hi", … })` is called
- **THEN** `ApnService.sendNotification` is invoked with `payload.deviceToken === "tok"` and the returned `DeliveryResult.success === true`

#### Scenario: deviceTokens array fans out

- **WHEN** `apnChannel.send({ channel: "push", metadata: { deviceTokens: ["a","b"] }, body: "hi", … })` is called
- **THEN** `ApnService.sendBulkNotifications` is invoked with the two-element array and the returned `DeliveryResult.success === true`

#### Scenario: missing deviceToken metadata

- **WHEN** `apnChannel.send` is called with no `deviceToken` and no `deviceTokens`
- **THEN** the call resolves with `{ success: false, channel: "apn", error: "deviceToken metadata required" }`

#### Scenario: APN per-device failure surfaces as DeliveryResult.error

- **WHEN** the underlying `ApnService.sendNotification` returns `{ sent: 0, failed: 1, errors: [{ error: "Unregistered" }] }`
- **THEN** `apnChannel.send` resolves with `success: false` and `error: "Unregistered"`

#### Scenario: canSend gates on channel

- **WHEN** `apnChannel.canSend(notification)` is called
- **THEN** the result is `true` iff `notification.channel === "push"`

### Requirement: EmailDeliveryChannel adapter

The package SHALL export an `EmailDeliveryChannel` class implementing
`@suaveplan/notification-channel`'s `DeliveryChannel` interface
against `@suaveplan/emailer`'s `EmailService`. The channel SHALL be
registered under `name === "email"` and SHALL map
`Notification.recipient` → `EmailMessage.to`, `Notification.subject`
→ `EmailMessage.subject` (defaulting to the configured
`defaultSubject` when missing), `Notification.body` →
`EmailMessage.text` (or `html` when `metadata.html === true`).
Transport failures returned by `EmailService.send` SHALL surface as
`{ success: false, error: <error message> }`. The channel SHALL throw
`NotificationsPluginError(EMAIL_SERVICE_UNAVAILABLE)` at construction
when `emailService` is `null`.

**Verified by:** `src/channels/email-channel/email-channel.test.ts::"sends through EmailService with subject + text"`, `src/channels/email-channel/email-channel.test.ts::"falls back to defaultSubject when notification has no subject"`, `src/channels/email-channel/email-channel.test.ts::"sends HTML body when metadata.html is true"`, `src/channels/email-channel/email-channel.test.ts::"folds transport failure into DeliveryResult.error"`, `src/channels/email-channel/email-channel.test.ts::"throws EMAIL_SERVICE_UNAVAILABLE when constructed with null service"`, `src/channels/email-channel/email-channel.test.ts::"canSend gates on channel === email"`.

#### Scenario: success path with explicit subject

- **WHEN** `emailChannel.send({ channel: "email", recipient: "x@y.z", subject: "S", body: "B", … })` is called
- **THEN** `EmailService.send` receives `{ to: "x@y.z", subject: "S", text: "B" }` and the channel returns `{ success: true, channel: "email" }`

#### Scenario: default subject fallback

- **WHEN** the notification has no `subject` and the channel was constructed with `defaultSubject: "Notification"`
- **THEN** `EmailService.send` receives `subject: "Notification"`

#### Scenario: HTML body via metadata

- **WHEN** `emailChannel.send({ channel: "email", metadata: { html: true }, body: "<p>x</p>", … })` is called
- **THEN** `EmailService.send` receives `{ html: "<p>x</p>" }` instead of `text`

#### Scenario: transport failure

- **WHEN** the underlying `EmailService.send` returns `{ success: false, error: new Error("smtp dead"), … }`
- **THEN** the channel returns `{ success: false, error: "smtp dead" }`

#### Scenario: null service refused at construction

- **WHEN** `new EmailDeliveryChannel({ emailService: null, … })` is invoked
- **THEN** the constructor throws `NotificationsPluginError(EMAIL_SERVICE_UNAVAILABLE)`

#### Scenario: canSend gating

- **WHEN** `emailChannel.canSend({ channel: "email", … })` versus `{ channel: "push", … }`
- **THEN** the first returns `true`, the second returns `false`

### Requirement: DispatcherIdempotencyAdapter contract

The package SHALL export a `DispatcherIdempotencyAdapter` interface
exposing exactly one method
`execute<T>(key: string, fn: () => Promise<T>): Promise<T>` and a
default `NoopIdempotencyAdapter` class that simply calls `fn()`.
Callers SHALL be able to plug `@suaveplan/idempotency`'s
`IdempotencyGuard` (whose `execute(key, fn, opts?)` signature is
structurally compatible) without the package importing the guard at
runtime. The dispatcher SHALL call `adapter.execute(key, () =>
underlyingDispatch())` when a `key` is derivable from the input,
short-circuiting duplicate dispatches with the adapter's cached
return value.

**Verified by:** `src/dispatcher/idempotency-adapter/idempotency-adapter.test.ts::"NoopIdempotencyAdapter calls fn exactly once"`, `src/dispatcher/idempotency-adapter/idempotency-adapter.test.ts::"a caching adapter dedupes repeated executions"`, `src/dispatcher/notification-dispatcher/notification-dispatcher.test.ts::"idempotency adapter dedupes repeated dispatches"`.

#### Scenario: noop adapter is the identity

- **WHEN** `new NoopIdempotencyAdapter().execute("k", fn)` is invoked
- **THEN** `fn()` is called exactly once and its result is returned

#### Scenario: caching adapter dedupes

- **WHEN** the same `key` is passed twice and the adapter caches by key
- **THEN** the underlying `fn` is invoked only once and both calls return the same result

### Requirement: Dispatch input/result schemas

The package SHALL export `DispatchInputSchema` and
`DispatchResultSchema` (Zod) plus matching `DispatchInput` /
`DispatchResult` types. `DispatchInputSchema` SHALL accept
`recipient` (non-empty string), `body` (non-empty string), optional
`channel` (one of the `notification-channel` channel literals),
optional `subject`, optional `metadata` (record),
optional `priority`, and an optional `idempotencyKey`. Invalid input
SHALL produce `NotificationsPluginError(DISPATCH_INPUT_INVALID)`
carrying the `ZodError` as `cause`.

**Verified by:** `src/schemas/dispatch-schemas.test.ts::"DispatchInputSchema rejects empty recipient"`, `src/schemas/dispatch-schemas.test.ts::"DispatchInputSchema rejects empty body"`, `src/schemas/dispatch-schemas.test.ts::"DispatchInputSchema accepts a minimal payload"`, `src/schemas/dispatch-schemas.test.ts::"DispatchInputSchema accepts idempotencyKey"`, `src/schemas/dispatch-schemas.test.ts::"DispatchResultSchema accepts canonical shape"`.

#### Scenario: empty recipient rejected

- **WHEN** `DispatchInputSchema.safeParse({ recipient: "", body: "x" })` is invoked
- **THEN** the result `success === false`

#### Scenario: minimal payload accepted

- **WHEN** `DispatchInputSchema.safeParse({ recipient: "u", body: "b" })` is invoked
- **THEN** the result `success === true`

### Requirement: Dispatcher error codes wired into production paths

The registry SHALL include `DISPATCH_FAILED`,
`DISPATCH_CHANNEL_UNAVAILABLE`, `DISPATCH_INPUT_INVALID`, and
`EMAIL_SERVICE_UNAVAILABLE` codes, and every one SHALL be thrown
from at least one production source under `src/`. The
`error-codes.test.ts` reachability scan SHALL include all four codes.

**Verified by:** `src/error-codes/error-codes.test.ts::"every NOTIFICATIONS_PLUGIN_CODES value is referenced by src/"`.

#### Scenario: registry exposes the four dispatcher codes

- **WHEN** `Object.values(NOTIFICATIONS_PLUGIN_CODES)` is inspected
- **THEN** the array contains `NOTIFICATIONS_PLUGIN.DISPATCH_FAILED`, `NOTIFICATIONS_PLUGIN.DISPATCH_CHANNEL_UNAVAILABLE`, `NOTIFICATIONS_PLUGIN.DISPATCH_INPUT_INVALID`, and `NOTIFICATIONS_PLUGIN.EMAIL_SERVICE_UNAVAILABLE`

#### Scenario: every dispatcher code reachable from src

- **WHEN** the spec-conformance scan concatenates every non-test `.ts` under `src/`
- **THEN** the concatenation contains `NOTIFICATIONS_PLUGIN_CODES.DISPATCH_FAILED`, `…DISPATCH_CHANNEL_UNAVAILABLE`, `…DISPATCH_INPUT_INVALID`, and `…EMAIL_SERVICE_UNAVAILABLE`

### Requirement: Dispatcher OTel counters

`getNotificationsInstruments()` SHALL expose two additional counters
beyond the original six: `notificationsDispatchedTotal` (incremented
by `NotificationDispatcher` on a successful dispatch, with `channel`
attribute) and `notificationsDispatchFailedTotal` (incremented on a
failed dispatch, with `channel` + `reason` attributes). Both SHALL
be observable through an `InMemoryMetricExporter` in the OTel test.

**Verified by:** `src/otel/instruments.test.ts::"exposes dispatcher counters"`, `src/otel/instruments.test.ts::"dispatcher counters emit on flush"`.

#### Scenario: instrument bundle exposes the two new counters

- **WHEN** `getNotificationsInstruments()` is called
- **THEN** the returned object has `notificationsDispatchedTotal` and `notificationsDispatchFailedTotal` properties

#### Scenario: counters appear in the exporter snapshot

- **WHEN** both counters are incremented and `flushTestMetrics()` is called
- **THEN** the exporter snapshot includes both metric names

### Requirement: Dispatcher service-registry slots

The package SHALL extend the existing `ServiceRegistry` module
augmentation with two optional slots:
`notificationDispatcher` (`NotificationDispatcher`) and
`emailService` (`EmailService` from `@suaveplan/emailer`). The slots
SHALL only be populated when the plugin's `enableDispatcher` option
is `true` (dispatcher) or when the host injects an `EmailService`
(email).

**Verified by:** `src/api-plugin-notifications.spec-conformance.test.ts::"registry slots include dispatcher and emailService"`, `src/plugin/plugin.test.ts::"onInit registers notificationDispatcher when enableDispatcher is on"`.

#### Scenario: dispatcher slot populated when enabled

- **WHEN** `onInit` runs with `enableDispatcher: true`
- **THEN** `ctx.getService("notificationDispatcher")` resolves to a `NotificationDispatcher` instance

#### Scenario: emailService slot populated when injected

- **WHEN** the host calls `createNotificationsPlugin({}, { emailService })` and `onInit` runs
- **THEN** `ctx.getService("emailService")` resolves to the same `EmailService` instance