@terreno/mcp 56.0.0-beta.0 → 57.0.0-beta.1

package/src/docs/versioned/next/implementationPlans/comms-abstraction.md

@@ -0,0 +1,323 @@
+# Implementation Plan: Pluggable communications layer (@terreno/comms)
+
+**Status:** Draft
+**Roadmap issue:** https://github.com/FlourishHealth/terreno/issues/1018
+**Priority:** High
+**Effort:** Big batch
+**Owner:** unassigned
+**Created:** 2026-08-09
+**Program:** [B2B platform](b2b-platform-program.md)
+**Depends on:** none (inbound-webhooks is needed only by adapter delivery-callback phases)
+**RTK deprecation flag:** None — backend-only package
+
+## Goal
+
+Terreno backends cannot send email, SMS, or push notifications: there is no mail
+integration at all, `expo-server-sdk` sits unused in `@terreno/api`, and the RTK client's
+`resetPassword` call has no backend to talk to. This IP creates `@terreno/comms`, a new
+workspace package that defines **provider interfaces** for the four outbound channels
+(mail, SMS, push, OTP verification), a **`CommsApp`** TerrenoPlugin that registers
+configured providers and exposes send services to routes and other plugins, **push-token
+registration** routes and model, a **delivery log**, and **console adapters** so every
+channel works in development with zero external accounts.
+
+Concrete providers (Twilio, SendGrid, Expo push) are separate IPs — one per adapter — so
+consumer apps install only the SDKs they use.
+
+## Non-Goals
+
+- Any concrete provider SDK integration (see `comms-adapter-*` IPs).
+- In-app notification center, inbox UI, or user notification preferences
+  (`notification-center` item).
+- Password reset / email verification flows (`password-reset-and-email-verification` item
+  — a consumer of this layer).
+- Inbound webhook handling (`inbound-webhooks` item); this IP only defines the
+  `DeliveryEvent` type adapters will feed from callbacks.
+- Broadcast/bulk campaign tooling.
+
+## Decisions
+
+| Question | Decision |
+|----------|----------|
+| New package or `@terreno/api` module? | New package `@terreno/comms`, mirroring `@terreno/feature-flags` — keeps provider SDKs out of the core dependency tree |
+| How do provider SDKs stay optional? | Adapters live in subpath exports (`@terreno/comms/adapters/<name>`) with their SDKs as `peerDependencies` marked optional; core package has zero provider SDKs |
+| Precedent to follow | `secretProviders.ts` (env + GCP behind one interface) and the OpenFeature provider in `@terreno/feature-flags` |
+| Templates | Minimal: `{subject, text, html}` render helper with variable interpolation; no template builder |
+| Where do send calls log? | `CommsMessage` Mongoose model, mirroring the `AIRequest.logRequest` pattern — logging failures never break the send |
+| Dev experience | `ConsoleMailProvider` / `ConsoleSmsProvider` / `ConsolePushProvider` / `ConsoleVerificationProvider` print to logger and record to `CommsMessage`; default when no provider configured in non-production |
+| Consumer lifecycle hooks | `CommsApp` options expose `beforeSend` / `onSend` / `onError` / `onRetry` / `onOptOut` / `onDeliveryEvent`. Hooks are awaited but wrapped: a throwing hook is logged (`logger.error`) and never breaks the send. `beforeSend` may mutate or cancel |
+| Error taxonomy | Every `SendResult` failure carries `errorCode` (provider-native code as a string) and `errorClass` (`"permanent"` \| `"transient"` \| `"config"`). Adapters own the mapping; the facade uses `errorClass` to decide its single inline retry (transient only) and the admin dashboard uses it to gate manual retries |
+| Payload retention | `retainPayloadDays` option (default 30) keeps the rendered message on the `CommsMessage` row (post `redactPayload` hook) so the admin dashboard can retry; a TTL-style cleanup clears expired payloads |
+
+## Architecture
+
+```
+@terreno/comms
+  src/
+    types.ts            # Provider interfaces + message/result types
+    commsApp.ts         # CommsApp TerrenoPlugin
+    commsService.ts     # sendMail/sendSms/sendPush/startVerification/checkVerification
+    models/
+      commsMessage.ts   # Delivery log
+      pushToken.ts      # Device push token registry
+    routes/
+      pushTokens.ts     # modelRouter for token registration
+      commsExplorer.ts  # Admin-only delivery log explorer
+    adapters/
+      console.ts        # Dev adapters for all four channels
+    templates.ts        # renderTemplate({subject, text, html}, data)
+```
+
+### Provider interfaces (types.ts)
+
+```typescript
+export interface SendResult {
+  providerMessageId?: string;
+  accepted: boolean;
+  error?: string;
+  errorCode?: string;                              // provider-native code, e.g. "21610", "sendgrid-400"
+  errorClass?: "permanent" | "transient" | "config"; // drives retry eligibility
+}
+
+export interface MailMessage {
+  to: string | string[];
+  from?: string;            // default from CommsApp options
+  subject: string;
+  text?: string;
+  html?: string;
+  replyTo?: string;
+  metadata?: Record<string, string>;
+}
+
+export interface MailProvider {
+  readonly id: string;      // "console" | "sendgrid" | ...
+  sendMail(message: MailMessage): Promise<SendResult>;
+}
+
+export interface SmsProvider {
+  readonly id: string;
+  sendSms(message: {to: string; body: string}): Promise<SendResult>;
+}
+
+export interface PushMessage {
+  tokens: string[];
+  title: string;
+  body: string;
+  data?: Record<string, unknown>;
+  badge?: number;
+  sound?: string | null;
+}
+
+export interface PushProvider {
+  readonly id: string;
+  sendPush(message: PushMessage): Promise<SendResult[]>; // one per token
+}
+
+export interface VerificationProvider {
+  readonly id: string;
+  startVerification(options: {to: string; channel: "sms" | "email"}): Promise<SendResult>;
+  checkVerification(options: {to: string; code: string}): Promise<{
+    valid: boolean;
+    error?: string;
+  }>;
+}
+
+export interface DeliveryEvent {
+  channel: "mail" | "sms" | "push";
+  providerMessageId: string;
+  status: "delivered" | "bounced" | "failed" | "opened";
+  errorCode?: string;   // provider failure code from the callback, when present
+  raw?: unknown;
+}
+
+export interface CommsHookContext {
+  channel: "mail" | "sms" | "push" | "verification";
+  provider: string;
+  message: MailMessage | {to: string; body: string} | PushMessage;
+  userId?: string;
+  isRetry: boolean;     // true for facade inline retries and admin-dashboard retries
+  messageId?: string;   // CommsMessage._id once the log row exists
+}
+
+export interface OptOutEvent {
+  channel: "mail" | "sms";
+  to: string;
+  provider: string;
+  reason: string;       // e.g. "sms-stop", "unsubscribe", "spam-report"
+  raw?: unknown;
+}
+```
+
+Verification start attempts store `metadata.verificationChannel` while recipient values remain
+redacted. Verification codes are never persisted.
+
+### CommsApp (TerrenoPlugin)
+
+```typescript
+export interface CommsOptions {
+  mail?: MailProvider;
+  sms?: SmsProvider;
+  push?: PushProvider;
+  verification?: VerificationProvider;
+  defaultFrom?: string;                       // mail from fallback
+  logMessages?: boolean;                      // default true → CommsMessage
+  retainPayloadDays?: number;                 // default 30; 0 disables retention (and admin retry)
+  redactPayload?: (context: CommsHookContext, payload: unknown) => unknown; // before storage
+
+  // Lifecycle hooks — all optional, all awaited, all wrapped so a throwing
+  // hook is logged and never breaks (or blocks) the send itself.
+  beforeSend?: (context: CommsHookContext) =>
+    Promise<{cancel?: boolean; message?: CommsHookContext["message"]} | void>;
+  onSend?: (context: CommsHookContext, result: SendResult) => Promise<void>;
+  onError?: (context: CommsHookContext, result: SendResult) => Promise<void>;
+  onRetry?: (context: CommsHookContext, attempt: number) => Promise<void>;
+  onOptOut?: (event: OptOutEvent) => Promise<void>;
+  onDeliveryEvent?: (event: DeliveryEvent) => Promise<void>;
+}
+
+new TerrenoApp({userModel: User})
+  .register(new CommsApp({mail: new ConsoleMailProvider(), push: new ExpoPushProvider()}))
+  .start();
+```
+
+`CommsApp.register()` mounts the push-token routes and admin explorer;
+`getCommsService()` (module-level accessor, mirroring how `FeatureFlagsApp` exposes
+evaluation) gives routes and other plugins `sendMail` / `sendSms` / `sendPushToUser` /
+`startVerification` / `checkVerification`. `sendPushToUser(userId, message)` resolves the
+user's active `PushToken`s and prunes tokens the provider reports dead.
+
+Unconfigured channel behavior: in production, throw `APIError({status: 501, title:
+"Comms channel not configured"})`; in development, fall back to the console adapter with a
+`logger.warn`.
+
+### Hook order and semantics
+
+For every send (including retries) the facade runs:
+
+1. `beforeSend` — may replace the message (`{message}`) or cancel (`{cancel: true}`,
+   logged as a `CommsMessage` with status `cancelled`). The consuming app uses this for
+   quiet hours, per-user notification preferences, and suppression lists.
+2. Provider `send*` → on transient failure (`errorClass: "transient"`), `onRetry` fires
+   and the facade retries once inline.
+3. `onSend` (accepted) or `onError` (final failure) — `onError` receives the full
+   `SendResult` (`errorCode`, `errorClass`) so apps can alert, escalate, or mark domain
+   objects without polling the delivery log.
+4. Asynchronously, adapters feed `onDeliveryEvent` (delivery callbacks) and `onOptOut`
+   (STOP replies, unsubscribes, spam reports) once their webhook phases land.
+
+Hooks are observation and shaping points, not error channels: exceptions thrown inside a
+hook are caught, logged with `logger.error`, and recorded in `CommsMessage.metadata` —
+they never change the send outcome.
+
+## Models
+
+All fields carry `description`; both models use `createdUpdatedPlugin` + `isDeletedPlugin`
+and live per the five-type pattern (`CommsMessageDocument`, etc.).
+
+**PushToken** — `userId` (ref User, required, indexed), `token` (string, required, unique),
+`platform` ("ios" | "android" | "web"), `deviceId` (string, optional), `active` (boolean,
+default true), `lastSeenAt` (date).
+
+**CommsMessage** — `channel` ("mail" | "sms" | "push" | "verification"), `provider`
+(string), `to` (string, redacted-at-rest for sms/mail per option), `subject` (string,
+optional), `userId` (ref User, optional), `status` ("sent" | "failed" | "delivered" |
+"bounced" | "cancelled"), `providerMessageId` (string, indexed), `error` (string,
+optional), `errorCode` (string, indexed), `errorClass` ("permanent" | "transient" |
+"config"), `templateId` (string, optional), `attempts` (array of `{at, provider,
+providerMessageId, errorCode, error}` — one entry per facade attempt including the inline
+retry), `attemptCount` (number), `lastAttemptAt` (date), `retriedFromId` / `retriedById`
+(ref CommsMessage — links between an original and its admin-dashboard retries), `payload`
+(Mixed, retained per `retainPayloadDays` after `redactPayload`, cleared on expiry),
+`metadata` (Mixed). Static `logSend()` mirrors `AIRequest.logRequest`.
+
+These fields exist so the [comms-admin-dashboard](comms-admin-dashboard.md) IP can filter
+on error codes/classes, show per-attempt history, and re-send from the retained payload
+without any further schema changes.
+
+## APIs
+
+| Method | Path | Permissions | Notes |
+|---|---|---|---|
+| POST | `/comms/pushTokens` | IsAuthenticated | Upsert by `token`; sets `userId`, `platform`, `lastSeenAt` |
+| GET | `/comms/pushTokens` | IsOwner via queryFilter | List own device tokens |
+| DELETE | `/comms/pushTokens/:id` | IsOwner | Deactivate on logout/uninstall |
+| GET | `/comms/messages` | IsAdmin | Paginated delivery log explorer; filters: `channel`, `status`, `userId`, date range |
+
+Push token registration, owner-scoped list, and deactivation use dedicated handlers because
+`modelRouter` create cannot provide idempotent upsert semantics and `OwnerQueryFilter` targets a
+persisted `ownerId` while `PushToken` persists `userId`. Owner read remains on `modelRouter`.
+The explorer uses `createOpenApiBuilder`, modeled on `addAiRequestsExplorerRoutes`, and is
+deliberately minimal here — the [comms-admin-dashboard](comms-admin-dashboard.md) IP upgrades it
+with error-code/class filtering, free-text search, a detail route, stats, and retry endpoints.
+
+## Notifications
+
+None beyond the feature itself.
+
+## UI
+
+None in this IP. example-frontend gains a settings row that registers the Expo push token
+(client helper already exists in `store/utils.ts`) once the Expo adapter lands.
+
+## Phases
+
+1. **Package + contracts:** `@terreno/comms` package scaffold, `types.ts`, console
+   adapters, `CommsMessage` + logging, `commsService`, unit tests.
+2. **CommsApp + routes:** plugin registration, `PushToken` model + routes, admin explorer,
+   OpenAPI, supertest coverage.
+3. **Integration:** example-backend registers `CommsApp` (console adapters), seed docs,
+   `docs/reference/comms.md`, catalog entries, publish wiring in `publish-on-tag.yml`.
+
+## Feature Flags & Migrations
+
+None. New collections only; no existing data touched.
+
+## Activity Log & User Updates
+
+Every send attempt is a `CommsMessage` row (that is the audit surface). No user-facing
+updates.
+
+## Not Included / Future Work
+
+- Adapter IPs: `comms-adapter-expo-push`, `comms-adapter-twilio-sms`,
+  `comms-adapter-twilio-verify`, `comms-adapter-sendgrid`.
+- Admin operations dashboard (rich filtering, log digging, manual retries) —
+  [comms-admin-dashboard](comms-admin-dashboard.md); this IP only ships the fields and
+  hooks it needs.
+- Notification center, user notification preferences (`beforeSend` is the extension
+  point they will plug into).
+- Queue-backed sending with automatic scheduled retries — arrives with `job-queues`;
+  until then sends are inline with one transient-error retry plus manual admin retries.
+
+## Files to Create / Modify
+
+- `comms/` (new workspace package: `package.json`, `tsconfig.json`, `biome.jsonc`, `src/*`
+  as in Architecture)
+- Root `package.json` — workspace entry + scripts (`comms:compile|lint|test`)
+- `example-backend/src/server.ts` — register `CommsApp`
+- `docs/reference/comms.md`, `.cursor/rules/comms/00-comms.mdc` (via rulesync)
+- `.github/workflows/publish-on-tag.yml`, new `comms-ci` workflow
+
+## Task List
+
+See [docs/tasks/comms-abstraction.md](../tasks/comms-abstraction.md).
+
+## Acceptance Criteria
+
+- [x] A Terreno app with only console adapters can call `sendMail`, `sendSms`,
+      `sendPushToUser`, and `startVerification`/`checkVerification` in development, each
+      producing a logger line and a `CommsMessage` row.
+- [ ] `beforeSend` can cancel and mutate; `onSend`/`onError` fire with the final
+      `SendResult`; `onRetry` fires on the inline transient retry — and a hook that throws
+      is logged without changing the send outcome (test per hook).
+- [ ] Failed sends record `errorCode` and `errorClass` on both the `SendResult` and the
+      `CommsMessage` row; only `transient` failures trigger the inline retry.
+- [ ] `CommsMessage.attempts` holds one entry per attempt with per-attempt error data;
+      `payload` is retained post-redaction and cleared after `retainPayloadDays`.
+- [x] `POST /comms/pushTokens` registers a device token for the authenticated user;
+      re-posting the same token updates rather than duplicates; other users cannot list or
+      delete it.
+- [x] `GET /comms/messages` is admin-only, paginated, and filterable by channel and status.
+- [x] Production apps with an unconfigured channel get a 501 `APIError`, not a silent no-op.
+- [x] `@terreno/comms` core has zero provider SDKs in `dependencies`.
+- [x] All routes appear in `/openapi.json` and the generated SDK compiles.

package/src/docs/versioned/next/implementationPlans/comms-adapter-expo-push.md

@@ -0,0 +1,107 @@
+# Implementation Plan: Comms adapter — Expo push notifications
+
+**Status:** Draft
+**Roadmap issue:** https://github.com/FlourishHealth/terreno/issues/1019
+**Priority:** High
+**Effort:** Small batch
+**Owner:** unassigned
+**Created:** 2026-08-09
+**Program:** [B2B platform](b2b-platform-program.md)
+**Depends on:** [comms-abstraction](comms-abstraction.md)
+**RTK deprecation flag:** None — backend adapter; client token registration already exists
+
+## Goal
+
+Implement `PushProvider` on Expo's push service so `sendPushToUser` delivers real
+notifications to iOS/Android devices. `expo-server-sdk` is already a dependency of
+`@terreno/api` (currently unused — it moves to this adapter's peer deps); the client-side
+token fetch (`getExpoPushTokenAsync`) already exists in `example-frontend/store/utils.ts`.
+
+## Non-Goals
+
+- Direct FCM/APNs integration (future adapter if demand appears).
+- Notification center / inbox UI.
+- Rich notification content (images, actions) beyond title/body/data/badge/sound.
+
+## Decisions
+
+| Question | Decision |
+|----------|----------|
+| SDK | `expo-server-sdk` as optional peer of `@terreno/comms` (subpath `adapters/expoPush`); removed from `@terreno/api` deps |
+| Receipts | Poll receipts after send (Expo's required pattern); surface as `DeliveryEvent`s to `onDeliveryEvent` |
+| Dead tokens | `DeviceNotRegistered` receipt → `SendResult.accepted: false` with permanent-failure marker so core pruning deactivates the `PushToken` |
+| Chunking | Use the SDK's `chunkPushNotifications`; one `SendResult` per token preserved through chunks |
+
+## Architecture
+
+```typescript
+// @terreno/comms/adapters/expoPush
+export class ExpoPushProvider implements PushProvider {
+  readonly id = "expo";
+  constructor(options?: {accessToken?: string; receiptPollDelayMs?: number});
+  sendPush(message: PushMessage): Promise<SendResult[]>;
+}
+```
+
+Send flow: validate tokens with `Expo.isExpoPushToken` → chunk → send → collect tickets →
+schedule one receipt poll (default 15 min, configurable; inline timer until `job-queues`
+lands) → map receipt errors to `DeliveryEvent`s and permanent-failure results.
+
+## Models
+
+None new — uses `PushToken` and `CommsMessage` from the abstraction.
+
+## APIs
+
+None new.
+
+## Notifications
+
+This is the notification plumbing itself.
+
+## UI
+
+example-frontend: register the push token on login via `POST /comms/pushTokens` (guarded by
+`expo-device` physical-device check once the native baseline lands) and a profile-screen
+test-send row in dev builds.
+
+## Phases
+
+Single phase.
+
+## Feature Flags & Migrations
+
+None.
+
+## Activity Log & User Updates
+
+Sends and receipt failures logged to `CommsMessage`.
+
+## Not Included / Future Work
+
+- Queue-backed receipt polling (moves to `job-queues` when available).
+- Web push (Expo tokens cover native only; web is a future adapter).
+
+## Files to Create / Modify
+
+- `comms/src/adapters/expoPush.ts` + tests (mock `Expo` client)
+- `comms/package.json` — optional peer `expo-server-sdk`
+- `api/package.json` — remove unused `expo-server-sdk`
+- `example-frontend/app/(tabs)/profile.tsx`, `store/utils.ts` — token registration wiring
+- `docs/reference/comms.md` — adapter section
+
+## Task List
+
+See [docs/tasks/comms-adapter-expo-push.md](../tasks/comms-adapter-expo-push.md).
+
+## Acceptance Criteria
+
+- [ ] With a mocked Expo client, `sendPush` returns one `SendResult` per token across chunk
+      boundaries.
+- [ ] A `DeviceNotRegistered` receipt deactivates the corresponding `PushToken` via core
+      pruning.
+- [ ] Invalid tokens are rejected before hitting the SDK and logged as failed
+      `CommsMessage` rows.
+- [ ] `@terreno/api` no longer lists `expo-server-sdk`; apps not using the adapter install
+      nothing new.
+- [ ] example-frontend registers its token after login on a physical device build.

package/src/docs/versioned/next/implementationPlans/comms-adapter-sendgrid.md

@@ -0,0 +1,157 @@
+# Implementation Plan: Comms adapter — transactional email (SendGrid)
+
+**Status:** Draft
+**Roadmap issue:** https://github.com/FlourishHealth/terreno/issues/1022
+**Priority:** High
+**Effort:** Small batch
+**Owner:** unassigned
+**Created:** 2026-08-09
+**Program:** [B2B platform](b2b-platform-program.md)
+**Depends on:** [comms-abstraction](comms-abstraction.md); inbound-webhooks (Phase 2 only)
+**RTK deprecation flag:** None — backend only
+
+## Goal
+
+Implement `MailProvider` on Twilio SendGrid (decision D2 — first mail adapter, sharing the
+Twilio account story with the SMS and Verify adapters) so `sendMail` delivers real
+transactional email. This unblocks `password-reset-and-email-verification` and
+`invitations-and-seats`.
+
+## Non-Goals
+
+- Other mail providers (Resend/SES/SMTP — items when demand appears).
+- Marketing campaigns, contact lists, SendGrid dynamic template management.
+- Inbound email parsing.
+
+## Decisions
+
+| Question | Decision |
+|----------|----------|
+| SDK | `@sendgrid/mail` as optional peer, subpath `@terreno/comms/adapters/sendgrid` |
+| Auth | `SENDGRID_API_KEY` env or constructor option; fail fast at registration when missing |
+| From address | Constructor `fromEmail`/`fromName` falling back to `CommsApp.defaultFrom`; sender verification is a documented SendGrid prerequisite, not automated |
+| Templates | Terreno-side rendering (`templates.ts` from the abstraction) sent as `text`/`html`; SendGrid dynamic templates supported pass-through via `templateId` + `dynamicTemplateData` but not required |
+| Sandbox | SendGrid `mail_settings.sandbox_mode` toggle for CI/e2e so tests never send |
+| Delivery events | Phase 2: SendGrid Event Webhook (delivered/deferred/bounce/dropped/spamreport/unsubscribe/open) with ECDSA signature verification via the inbound-webhooks framework, mapped to `DeliveryEvent`s / `OptOutEvent`s |
+| Error classification | Adapter owns the HTTP-status + event-type → `errorClass` map (table below); 429/5xx are `transient`, other 4xx `permanent`, 401/403 `config` |
+| Suppression / opt-outs | Bounces, spam reports, and unsubscribes emit `OptOutEvent` → consumer `onOptOut`. SendGrid maintains its own suppression lists; a send to a suppressed address comes back as a `dropped` event with the suppression reason, classified `permanent` |
+| Admin dashboard support | Every `CommsMessage` row stores `errorCode`/`errorClass`, the `x-message-id`, and a `metadata.consoleUrl` deep link to SendGrid Email Activity for log digging |
+
+## Architecture
+
+```typescript
+// @terreno/comms/adapters/sendgrid
+export class SendGridMailProvider implements MailProvider {
+  readonly id = "sendgrid";
+  constructor(options?: {
+    apiKey?: string;          // default env SENDGRID_API_KEY
+    fromEmail?: string;
+    fromName?: string;
+    sandboxMode?: boolean;    // default true when NODE_ENV === "test"
+  });
+  sendMail(message: MailMessage): Promise<SendResult>;
+}
+```
+
+Error mapping: SendGrid 4xx (bad address, unverified sender) → `accepted: false` with the
+response body's first error message in `SendResult.error` and full body in
+`CommsMessage.metadata`; 429/5xx classified `transient` and retried once by the core
+facade. The provider never throws through `sendMail`.
+
+### Error classification
+
+Send-time failures classify by HTTP status; post-acceptance failures arrive as events
+(Phase 2) and reclassify the `CommsMessage`.
+
+| Signal | Meaning | `errorCode` | `errorClass` |
+|---|---|---|---|
+| 400 (bad address, missing field), 413 | Request is wrong | `sendgrid-<status>` + first body error | `permanent` |
+| 401, 403 (bad key, unverified sender) | App misconfiguration | `sendgrid-<status>` | `config` (also `logger.error` at send time) |
+| 429 | Rate limited | `sendgrid-429` | `transient` |
+| 5xx / network errors | SendGrid-side or transport failure | `sendgrid-<status>` | `transient` |
+| Event: `bounce` (hard) | Mailbox permanently rejects | `bounce` + reason | `permanent` |
+| Event: `bounce` (soft) / `deferred` | Temporary mailbox/receiver issue | `deferred` | `transient` |
+| Event: `dropped` | SendGrid suppressed (prior bounce, spam report, unsubscribe, invalid) | `dropped` + reason | `permanent` |
+| Event: `spamreport`, `unsubscribe`, `group_unsubscribe` | Recipient opted out | event type | `permanent` (also emits `OptOutEvent`) |
+
+Permanent-class failures are never auto-retried and show as non-retryable in the admin
+dashboard with the reason (retrying a suppressed or unsubscribed address damages sender
+reputation); transient-class failures retry once inline and stay manually retryable.
+
+### Event webhook mapping (Phase 2)
+
+| SendGrid event | `DeliveryEvent.status` | `CommsMessage.status` |
+|---|---|---|
+| `processed` | — | `sent` (unchanged) |
+| `delivered` | `delivered` | `delivered` |
+| `deferred` | — (attempt noted in metadata) | `sent` (SendGrid keeps retrying) |
+| `bounce`, `dropped` | `bounced` / `failed` (+ reason as `errorCode`) | `bounced` / `failed` |
+| `open` | `opened` | unchanged (recorded in metadata) |
+| `spamreport`, `unsubscribe`, `group_unsubscribe` | — | unchanged; emits `OptOutEvent` → `onOptOut` |
+
+Events correlate to rows via the `x-message-id` response header captured at send time
+(SendGrid appends per-recipient suffixes; match on the prefix).
+
+## Models / APIs / Notifications / UI
+
+None new. Phase 2 adds one webhook route via the inbound-webhooks framework.
+
+## Phases
+
+1. **Send path:** provider, config resolution, sandbox mode, error classification,
+   `x-message-id` capture + Email Activity deep link, mocked-client tests;
+   example-backend env-gated registration; docs (including the sender-verification
+   prerequisite checklist).
+2. **Delivery events + opt-outs** *(gated on inbound-webhooks IP)*: Event Webhook route
+   with ECDSA signature verification; event mapping per the table →
+   `DeliveryEvent`/`OptOutEvent` → `CommsMessage.status` + consumer hooks.
+
+## Feature Flags & Migrations
+
+None.
+
+## Activity Log & User Updates
+
+All sends logged to `CommsMessage` with provider `sendgrid`.
+
+## Not Included / Future Work
+
+- Suppression-list *management* (viewing/clearing SendGrid suppressions from admin) — the
+  adapter only reports suppression outcomes; a management surface can extend the
+  [comms-admin-dashboard](comms-admin-dashboard.md) later.
+- Unsubscribe-group configuration.
+- Batch sending beyond the multiple-recipient `to` array.
+
+## Files to Create / Modify
+
+- `comms/src/adapters/sendgrid.ts` + tests
+- `comms/package.json` — optional peer `@sendgrid/mail`
+- `example-backend/src/server.ts` — env-gated registration
+- `docs/reference/comms.md`, `docs/reference/environment-variables.md`
+
+## Task List
+
+See [docs/tasks/comms-adapter-sendgrid.md](../tasks/comms-adapter-sendgrid.md).
+
+## Acceptance Criteria
+
+- [ ] `sendMail` delivers text/html mail with from-address fallback chain (provider option
+      → `CommsApp.defaultFrom`), and passes `templateId`/`dynamicTemplateData` through when
+      given.
+- [ ] Sandbox mode is on by default under test and produces accepted results without real
+      sends.
+- [ ] SendGrid errors surface as `accepted: false` with the SendGrid error message and a
+      correct `errorCode`/`errorClass` per the classification table; nothing throws
+      through the facade.
+- [ ] 401/403 classify as `config` and `logger.error` at send time; 429/5xx classify as
+      `transient` and retry once; other 4xx are `permanent` and never retried.
+- [ ] Each accepted send captures the `x-message-id` and stores a `metadata.consoleUrl`
+      Email Activity deep link.
+- [ ] Consumer `onError` fires with the classified `SendResult` on every failed send
+      (mocked-client test).
+- [ ] Missing API key fails fast at `CommsApp` registration with a clear error.
+- [ ] Apps not using the adapter do not install `@sendgrid/mail`.
+- [ ] (Phase 2) Event webhook updates `CommsMessage.status` per the mapping table only
+      for signature-verified payloads; bounce/dropped reasons land as `errorCode`.
+- [ ] (Phase 2) `spamreport`/`unsubscribe` events fire `onOptOut`; later sends to the
+      suppressed address record `dropped` as `permanent`.