Initial Commit

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

@@ -0,0 +1,565 @@
+<!-- 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