@terreno/mcp 0.31.0 → 56.0.0-beta.2

package/src/docs/versioned/next/implementationPlans/PLAN_INDEX.md

@@ -9,35 +9,47 @@ Umbrella plans that coordinate several IPs.
 | Program | Status | Created | IPs |
 |---------|--------|---------|-----|
 | [Open source launch](oss-launch-program.md) | Draft — decisions recorded; Vercel spike open | 2026-07-27 | 15 |
-| [B2B platform](b2b-platform-program.md) | Draft — decisions D1–D7 resolved | 2026-08-09 | 9 written (+ [rbac-permissions](rbac-permissions.md)); 29 roadmap items seeded |
 
 ## Active
 
 | Plan | Status | Created | Tasks |
 |------|--------|---------|-------|
+| [Migrate CI/CD to CircleCI](migrate-cicd-to-circleci.md) | Draft — decisions recorded | 2026-08-17 | [tasks](../tasks/migrate-cicd-to-circleci.md) |
 | [Admin UI v2 — Django-parity admin](admin-ui-v2-django-parity.md) | Approved | 2026-06-15 | [tasks](../tasks/admin-ui-v2-django-parity.md) |
-| [RBAC Permissions](rbac-permissions.md) | Draft (API design) | 2026-07-08 | TBD |
-| [SyncDB Local-First Data Layer](syncdb-local-first.md) | In progress ([PR #869](https://github.com/flourishhealth/terreno/pull/869)) | 2026-07-13 | [tasks](../tasks/syncdb-local-first.md) |
-| [MCP Boost parity](mcp-boost-parity.md) | In progress ([PR #802](https://github.com/flourishhealth/terreno/pull/802)) | 2026-06-21 | TBD |
-| [Infrastructure MCP server](infra-mcp.md) | Draft — blocked on [RBAC](rbac-permissions.md) | 2026-08-09 | [tasks](../tasks/infra-mcp.md) |
+| [@terreno/syncdb-codegen](syncdb-codegen.md) | Draft | 2026-07-08 | [tasks](../tasks/syncdb-codegen.md) |
+| [SyncDB local-first data layer (v2)](syncdb-local-first.md) | In progress — Phases 1–8 landed, Phase 9 follow-ups open | 2026-06-23 | [tasks](../tasks/syncdb-local-first.md) |
+| [SyncDB hardening (syncdb-2)](terreno-syncdb-2.md) | Implemented — Phases A–F landed; deviations carried into Phase 9 | 2026-07-11 | [tasks](../tasks/syncdb-local-first.md) (Phase 8/9) |
+| [SyncDB Phase C design](syncdb-phase-c-design.md) | Implemented — design authority for C1–C8 | 2026-07-11 | [tasks](../tasks/syncdb-local-first.md) (Phase 8) |
+
+## Completed
+
+| Plan | Status | Created | Tasks |
+|------|--------|---------|-------|
+| [APIError redesign — standards-first extension of Error](apierror-standard-error-redesign.md) | Complete | 2026-07-28 | n/a |
 
-## Open source launch IPs
+## Deferred / Closed
 
-All part of the [launch program](oss-launch-program.md). The **RTK flag** column marks dependence on the `@terreno/rtk` → `@terreno/syncdb` migration in PR #869: `None` is safe to implement now, `Partial` has some blocked tasks, `Blocked` cannot start until #869 merges.
+*(Plans parked or superseded.)*
 
-### Wave 0 — unblocked
+## Backlog
 
-| Plan | Status | RTK flag | Tasks |
-|------|--------|----------|-------|
+*(Links to ideas not yet promoted to a full IP.)*
+
+| Idea | Notes |
+|------|-------|
+| [Langfuse integration](terreno-langfuse-integration.md) | AI observability plugin |
+| [modelRouter MCP tools](model-router-mcp.md) | MCP surface for consumer app APIs |
+| [Offline mode](offline-mode.md) | Superseded in large part by [syncdb](syncdb-local-first.md) — confirm and close |
+| [modelRouter actions](model-router-actions.md) | — |
+| [B2B platform](b2b-platform-program.md) | Draft — decisions D1–D7 resolved | 2026-08-09 | 10 written (+ [rbac-permissions](rbac-permissions.md)); 30 roadmap items seeded |
+| [RBAC Permissions](rbac-permissions.md) | Draft (API design) | 2026-07-08 | TBD |
+| [SyncDB Local-First Data Layer](syncdb-local-first.md) | In progress ([PR #869](https://github.com/flourishhealth/terreno/pull/869)) | 2026-07-13 | [tasks](../tasks/syncdb-local-first.md) |
+| [MCP Boost parity](mcp-boost-parity.md) | In progress ([PR #802](https://github.com/flourishhealth/terreno/pull/802)) | 2026-06-21 | TBD |
+| [Infrastructure MCP server](infra-mcp.md) | Draft — blocked on [RBAC](rbac-permissions.md) | 2026-08-09 | [tasks](../tasks/infra-mcp.md) |
 | [OSS governance baseline](oss-governance-baseline.md) | Draft | None | [tasks](../tasks/oss-governance-baseline.md) |
 | [Public roadmap on GitHub](public-roadmap-github.md) | Draft | None | [tasks](../tasks/public-roadmap-github.md) |
 | [Deploy to GCP (generalized)](deploy-to-gcp.md) | Draft | None | [tasks](../tasks/deploy-to-gcp.md) |
 | [Agentic SDLC plugin (`/terreno-*`)](agentic-sdlc-plugin.md) | Draft | Partial | [tasks](../tasks/agentic-sdlc-plugin.md) |
-
-### Wave 1 — gated on PR #869
-
-| Plan | Status | RTK flag | Tasks |
-|------|--------|----------|-------|
 | [RTK deprecation and syncdb migration docs](rtk-to-syncdb-migration-docs.md) | Draft | **Blocked** (gating IP) | [tasks](../tasks/rtk-to-syncdb-migration-docs.md) |
 | [Positioning — Django/Rails for TypeScript](positioning-django-rails-universal.md) | Draft | Partial | [tasks](../tasks/positioning-django-rails-universal.md) |
 | [Reference documentation coverage](docs-reference-coverage.md) | Draft | Blocked | [tasks](../tasks/docs-reference-coverage.md) |
@@ -48,48 +60,14 @@ All part of the [launch program](oss-launch-program.md). The **RTK flag** column
 | [The AI development loop (Boost)](ai-dev-loop-boost.md) | Draft | Partial | [tasks](../tasks/ai-dev-loop-boost.md) |
 | [Dogfooding run and launch blog post](build-terreno-app-validation.md) | Draft | Blocked | [tasks](../tasks/build-terreno-app-validation.md) |
 | [Examples, demo, and test coverage](examples-demo-coverage.md) | Draft | Partial | [tasks](../tasks/examples-demo-coverage.md) |
-
-### Wave 2 — independent
-
-| Plan | Status | RTK flag | Tasks |
-|------|--------|----------|-------|
 | [Web SSR and admin SPA](web-ssr-and-admin-spa.md) | Draft | Partial | [tasks](../tasks/web-ssr-and-admin-spa.md) |
-
-## B2B platform IPs
-
-All part of the [B2B platform program](b2b-platform-program.md). Roadmap items for the
-full program (including items whose IPs are pending decisions D1–D4) are seeded in
-[roadmap-seed-issues.md](../explanation/roadmap-seed-issues.md).
-
-| Plan | Status | RTK flag | Tasks |
-|------|--------|----------|-------|
 | [Pluggable communications layer (@terreno/comms)](comms-abstraction.md) | Draft | None | [tasks](../tasks/comms-abstraction.md) |
 | [Comms adapter — Expo push](comms-adapter-expo-push.md) | Draft | None | [tasks](../tasks/comms-adapter-expo-push.md) |
 | [Comms adapter — Twilio SMS](comms-adapter-twilio-sms.md) | Draft | None | [tasks](../tasks/comms-adapter-twilio-sms.md) |
 | [Comms adapter — Twilio Verify (OTP)](comms-adapter-twilio-verify.md) | Draft | None | [tasks](../tasks/comms-adapter-twilio-verify.md) |
 | [Comms adapter — SendGrid email](comms-adapter-sendgrid.md) | Draft | None | [tasks](../tasks/comms-adapter-sendgrid.md) |
+| [Comms admin dashboard (errors, retries, log digging)](comms-admin-dashboard.md) | Draft | Partial | [tasks](../tasks/comms-admin-dashboard.md) |
 | [Password reset and email verification](password-reset-and-email-verification.md) | Draft | None | [tasks](../tasks/password-reset-and-email-verification.md) |
 | [Organizations, teams, and multi-tenant scoping](orgs-and-teams.md) | Draft | None | [tasks](../tasks/orgs-and-teams.md) |
 | [Stripe billing and subscriptions](billing-stripe.md) | Draft | None | [tasks](../tasks/billing-stripe.md) |
 | [Native module baseline (next major)](native-module-baseline.md) | Draft | None | [tasks](../tasks/native-module-baseline.md) |
-
-## Completed
-
-| Plan | Status | Created | Tasks |
-|------|--------|---------|-------|
-| [APIError redesign — standards-first extension of Error](apierror-standard-error-redesign.md) | Complete | 2026-07-28 | n/a |
-
-## Deferred / Closed
-
-*(Plans parked or superseded.)*
-
-## Backlog
-
-*(Links to ideas not yet promoted to a full IP.)*
-
-| Idea | Notes |
-|------|-------|
-| [Langfuse integration](terreno-langfuse-integration.md) | AI observability plugin |
-| [modelRouter MCP tools](model-router-mcp.md) | MCP surface for consumer app APIs |
-| [Offline mode](offline-mode.md) | Superseded in large part by [syncdb](syncdb-local-first.md) — confirm and close |
-| [modelRouter actions](model-router-actions.md) | — |

package/src/docs/versioned/next/implementationPlans/b2b-platform-program.md

@@ -1,6 +1,6 @@
 # Program: B2B platform
 
-**Status:** Draft — roadmap items drafted; decisions D1–D7 resolved 2026-08-09; first nine IPs open
+**Status:** Draft — roadmap items drafted; decisions D1–D7 resolved 2026-08-09; first ten IPs open
 **Owner:** unassigned
 **Created:** 2026-08-09
 
@@ -32,7 +32,7 @@ org switcher, dark mode).
 | Track | Theme | IPs / roadmap items |
 |---|---|---|
 | A | Tenancy & access | `orgs-and-teams`, `rbac-permissions` (existing draft), `invitations-and-seats`, `org-management-ui` |
-| C | Communications (pluggable) | `comms-abstraction`, one item **per adapter**: `comms-adapter-expo-push` (first push adapter, per D4), `comms-adapter-twilio-sms`, `comms-adapter-twilio-verify`, `comms-adapter-sendgrid` (first mail adapter, per D2); consumers: `password-reset-and-email-verification`, `notification-center` |
+| C | Communications (pluggable) | `comms-abstraction`, one item **per adapter**: `comms-adapter-expo-push` (first push adapter, per D4), `comms-adapter-twilio-sms`, `comms-adapter-twilio-verify`, `comms-adapter-sendgrid` (first mail adapter, per D2); operations: `comms-admin-dashboard`; consumers: `password-reset-and-email-verification`, `notification-center` |
 | B | Billing | `inbound-webhooks`, `billing-stripe` (web-first, per D1), `mobile-iap-revenuecat` (Future) |
 | D | Zero-to-deployed DX | `create-terreno-app`, `mongo-migrations` (deploy items already exist in the OSS launch program) |
 | E | B2B UI surfaces | `data-grid-server-filters`, `charts-and-dashboards`, `dark-mode-theme`, `command-palette`, `wizard-stepper`, `wysiwyg-editor` (markdown stays for now, per D3), `global-search` |
@@ -97,6 +97,7 @@ All decisions resolved by the maintainer on 2026-08-09:
 | [comms-adapter-twilio-sms](comms-adapter-twilio-sms.md) | Draft | [tasks](../tasks/comms-adapter-twilio-sms.md) |
 | [comms-adapter-twilio-verify](comms-adapter-twilio-verify.md) | Draft | [tasks](../tasks/comms-adapter-twilio-verify.md) |
 | [comms-adapter-sendgrid](comms-adapter-sendgrid.md) | Draft | [tasks](../tasks/comms-adapter-sendgrid.md) |
+| [comms-admin-dashboard](comms-admin-dashboard.md) | Draft | [tasks](../tasks/comms-admin-dashboard.md) |
 | [password-reset-and-email-verification](password-reset-and-email-verification.md) | Draft | [tasks](../tasks/password-reset-and-email-verification.md) |
 | [orgs-and-teams](orgs-and-teams.md) | Draft | [tasks](../tasks/orgs-and-teams.md) |
 | [billing-stripe](billing-stripe.md) | Draft | [tasks](../tasks/billing-stripe.md) |

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

@@ -45,6 +45,9 @@ consumer apps install only the SDKs they use.
 | 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
 
@@ -72,6 +75,8 @@ 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 {
@@ -111,17 +116,41 @@ export interface PushProvider {
 export interface VerificationProvider {
   readonly id: string;
   startVerification(options: {to: string; channel: "sms" | "email"}): Promise<SendResult>;
-  checkVerification(options: {to: string; code: string}): Promise<{valid: boolean}>;
+  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
@@ -132,6 +161,17 @@ export interface CommsOptions {
   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>;
 }
 
@@ -150,6 +190,25 @@ Unconfigured channel behavior: in production, throw `APIError({status: 501, titl
 "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`
@@ -162,8 +221,18 @@ 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"), `providerMessageId` (string, indexed), `error` (string, optional), `metadata`
-(Mixed). Static `logSend()` mirrors `AIRequest.logRequest`.
+"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
 
@@ -174,9 +243,12 @@ optional), `userId` (ref User, optional), `status` ("sent" | "failed" | "deliver
 | 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 routes via `modelRouter` with `preCreate` owner injection and
-`OwnerQueryFilter`; explorer via `createOpenApiBuilder`, modeled on
-`addAiRequestsExplorerRoutes`.
+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
 
@@ -209,9 +281,13 @@ updates.
 
 - Adapter IPs: `comms-adapter-expo-push`, `comms-adapter-twilio-sms`,
   `comms-adapter-twilio-verify`, `comms-adapter-sendgrid`.
-- Notification center, user notification preferences.
-- Queue-backed sending with retries — arrives with `job-queues`; until then sends are
-  inline with one retry.
+- 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
 
@@ -228,13 +304,20 @@ See [docs/tasks/comms-abstraction.md](../tasks/comms-abstraction.md).
 
 ## Acceptance Criteria
 
-- [ ] A Terreno app with only console adapters can call `sendMail`, `sendSms`,
+- [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.
-- [ ] `POST /comms/pushTokens` registers a device token for the authenticated user;
+- [ ] `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.
-- [ ] `GET /comms/messages` is admin-only, paginated, and filterable by channel and status.
-- [ ] Production apps with an unconfigured channel get a 501 `APIError`, not a silent no-op.
-- [ ] `@terreno/comms` core has zero provider SDKs in `dependencies`.
-- [ ] All routes appear in `/openapi.json` and the generated SDK compiles.
+- [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-sendgrid.md

@@ -32,7 +32,10 @@ transactional email. This unblocks `password-reset-and-email-verification` and
 | 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/bounce/dropped/open) with ECDSA signature verification via the inbound-webhooks framework, mapped to `DeliveryEvent`s |
+| 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
 
@@ -52,8 +55,42 @@ export class SendGridMailProvider implements MailProvider {
 
 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 retried once by the core facade. The provider never
-throws through `sendMail`.
+`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
 
@@ -61,12 +98,13 @@ None new. Phase 2 adds one webhook route via the inbound-webhooks framework.
 
 ## Phases
 
-1. **Send path:** provider, config resolution, sandbox mode, error mapping, mocked-client
-   tests; example-backend env-gated registration; docs (including the sender-verification
+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** *(gated on inbound-webhooks IP)*: Event Webhook route with ECDSA
-   signature verification; delivered/bounce/dropped/open → `DeliveryEvent` →
-   `CommsMessage.status`.
+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
 
@@ -78,7 +116,10 @@ All sends logged to `CommsMessage` with provider `sendgrid`.
 
 ## Not Included / Future Work
 
-- Suppression-list management, unsubscribe groups.
+- 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
@@ -99,9 +140,18 @@ See [docs/tasks/comms-adapter-sendgrid.md](../tasks/comms-adapter-sendgrid.md).
       given.
 - [ ] Sandbox mode is on by default under test and produces accepted results without real
       sends.
-- [ ] SendGrid 4xx errors surface as `accepted: false` with the SendGrid error message;
-      nothing throws through the facade.
+- [ ] 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` only for
-      signature-verified payloads.
+- [ ] (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`.

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

@@ -32,6 +32,10 @@ facade with delivery logging.
 | Number validation | Validate/normalize to E.164 with `libphonenumber-js` (already in catalog) before hitting the API |
 | Delivery status | Phase 2: status callback endpoint via the inbound-webhooks framework mapping Twilio statuses to `DeliveryEvent`s |
 | Secrets | `TWILIO_ACCOUNT_SID` + `TWILIO_AUTH_TOKEN` via env or the existing secret-provider layer |
+| Error classification | Adapter owns a Twilio error-code → `errorClass` map (table below) so the facade retries only transient failures and the admin dashboard gates manual retries correctly |
+| SDK failure handling | Twilio SDK calls wrapped with `withApiErrorHandling` from `@terreno/api` (per [call-external-apis](../how-to/call-external-apis.md)) — the SDK owns transport, the wrapper standardizes logging/normalization |
+| Opt-outs | Phase 2: inbound STOP/START (and 21610 send failures) surface as `OptOutEvent` → the consumer's `onOptOut` hook; enforcement stays consumer-side via `beforeSend` (Twilio blocks opted-out sends itself) |
+| Admin dashboard support | Every `CommsMessage` row stores the Twilio error code/class and a `metadata.consoleUrl` deep link to the message in the Twilio console for log digging |
 
 ## Architecture
 
@@ -50,9 +54,44 @@ export class TwilioSmsProvider implements SmsProvider {
 }
 ```
 
-Errors map Twilio exception codes to `SendResult.error` with the Twilio error code kept in
-`CommsMessage.metadata` for triage. Invalid destination numbers fail fast with a
-`BadRequestError` before any API call.
+Errors map Twilio exception codes to `SendResult.error`/`errorCode`/`errorClass`, with
+the full Twilio error payload kept in `CommsMessage.metadata` for triage. Invalid
+destination numbers fail fast with a `BadRequestError` before any API call.
+
+### Error classification
+
+The adapter classifies Twilio error codes into the abstraction's `errorClass` taxonomy.
+Permanent failures must never be auto-retried (retrying an unsubscribed number is a
+compliance problem, not a delivery problem); transient failures are retried once inline
+by the facade and stay manually retryable from the admin dashboard.
+
+| Twilio code(s) | Meaning | `errorClass` |
+|---|---|---|
+| 21211, 21214, 21217 | Invalid / unroutable destination number | `permanent` |
+| 21408 | SMS not enabled for destination region | `permanent` |
+| 21610 | Recipient has opted out (STOP) | `permanent` (also emits `OptOutEvent`) |
+| 30003, 30005, 30006 | Unreachable handset / unknown device / landline | `permanent` |
+| 30007 | Carrier content filtering | `permanent` (surface loudly — usually a sender-reputation problem) |
+| 20429, 429 responses | Rate limited / concurrency limit | `transient` |
+| 30001, 30002 | Queue overflow / account suspended-ish delivery interruption | `transient` |
+| 5xx / network errors | Twilio-side or transport failure | `transient` |
+| 20003, 20404 (auth/SID misconfig) | Bad credentials or missing resource | `config` |
+
+Unknown codes default to `transient` (safe for one retry) and are logged with the raw
+code so the map can be extended. `config` failures additionally `logger.error` at send
+time — they mean the app is misconfigured, not that the message was undeliverable.
+
+### Status callback mapping (Phase 2)
+
+| Twilio `MessageStatus` | `DeliveryEvent.status` | `CommsMessage.status` |
+|---|---|---|
+| `queued`, `accepted`, `sending`, `sent` | — (no event; already `sent`) | `sent` |
+| `delivered` | `delivered` | `delivered` |
+| `undelivered`, `failed` | `failed` (+ `errorCode` from `ErrorCode` param) | `failed` |
+
+Inbound `STOP`/`START` keyword webhooks (same inbound-webhooks registration) map to
+`OptOutEvent {channel: "sms", reason: "sms-stop"}` / opt-in, feeding the consumer's
+`onOptOut` hook and `CommsMessage.metadata` on subsequent 21610 failures.
 
 ## Models / APIs / Notifications / UI
 
@@ -60,11 +99,13 @@ None new — Phase 2 adds one webhook route via the inbound-webhooks framework.
 
 ## Phases
 
-1. **Send path:** provider, config resolution, E.164 validation, error mapping, tests with
-   mocked Twilio client; example-backend env-gated registration; docs.
-2. **Delivery callbacks** *(gated on inbound-webhooks IP)*: status callback route with
-   Twilio signature verification, statuses → `DeliveryEvent` → `CommsMessage.status`
-   updates.
+1. **Send path:** provider, config resolution, E.164 validation, error-code
+   classification map, `withApiErrorHandling` wrapping, console deep-link metadata, tests
+   with mocked Twilio client; example-backend env-gated registration; docs.
+2. **Delivery callbacks + opt-outs** *(gated on inbound-webhooks IP)*: status callback
+   route with Twilio signature verification, statuses → `DeliveryEvent` →
+   `CommsMessage.status` updates (with `errorCode`), STOP/START keyword handling →
+   `OptOutEvent` → `onOptOut`.
 
 ## Feature Flags & Migrations
 
@@ -76,8 +117,10 @@ All sends logged to `CommsMessage` with provider `twilio`.
 
 ## Not Included / Future Work
 
-- Inbound SMS (replies) handling.
+- Inbound SMS (replies) handling beyond STOP/START keywords.
 - Alphanumeric sender IDs, international compliance tooling.
+- Terreno-managed opt-out suppression list — the adapter emits `OptOutEvent`; storing and
+  enforcing preferences is consumer-side (`beforeSend`) until `notification-center` lands.
 
 ## Files to Create / Modify
 
@@ -95,8 +138,18 @@ See [docs/tasks/comms-adapter-twilio-sms.md](../tasks/comms-adapter-twilio-sms.m
 - [ ] `sendSms` delivers via messaging service or from-number config, preferring the
       messaging service when both are present.
 - [ ] A non-E.164 destination fails with a 400 `APIError` before any Twilio call.
-- [ ] Twilio API errors produce `accepted: false` results with the Twilio error code in
+- [ ] Twilio API errors produce `accepted: false` results with `errorCode` and a correct
+      `errorClass` per the classification table; the full Twilio error payload lands in
       `CommsMessage.metadata`; nothing throws through the facade.
+- [ ] Permanent-class failures (21610, 30003, …) are never retried inline and appear as
+      non-retryable in the admin dashboard; transient-class failures retry once and stay
+      manually retryable.
+- [ ] Each send stores `metadata.consoleUrl` linking the message SID to the Twilio
+      console.
+- [ ] Consumer `onError` fires with the classified `SendResult` on every failed send
+      (mocked-client test).
 - [ ] Apps not using the adapter do not install the `twilio` SDK.
-- [ ] (Phase 2) Status callbacks flip `CommsMessage.status` to `delivered`/`failed` with
-      verified Twilio signatures.
+- [ ] (Phase 2) Status callbacks flip `CommsMessage.status` to `delivered`/`failed` (with
+      `errorCode`) under verified Twilio signatures.
+- [ ] (Phase 2) An inbound STOP fires `onOptOut` with `reason: "sms-stop"`; a subsequent
+      send to that number records 21610 as `permanent`.

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

@@ -32,6 +32,9 @@ it is immediately usable for phone-number verification.
 | Channels | `sms` and `email` (Verify's email channel requires a configured Verify email integration; documented, not automated) |
 | Abuse control | Rely on Verify's built-in rate limits; add Terreno-side per-user attempt caps only when `rate-limiting` IP lands |
 | Logging | Start/check attempts logged to `CommsMessage` with channel `verification`, never logging the code |
+| Error classification | Verify errors map to the abstraction taxonomy: 20429/429 and 5xx → `transient`; max-attempts, expired, and invalid-destination → `permanent`; missing/invalid service SID → `config` |
+| Admin dashboard support | Verification rows appear in the [comms-admin-dashboard](comms-admin-dashboard.md) with `errorCode`/`errorClass` and a `metadata.consoleUrl` deep link to the Verify service logs — but the `verification` channel is **never retryable** from admin (codes expire; the user restarts the flow) |
+| Hooks | `onError` fires on failed starts/checks like any other channel; `beforeSend` can gate verification starts (e.g. per-user cool-downs) |
 
 ## Architecture
 
@@ -41,7 +44,7 @@ export class TwilioVerifyProvider implements VerificationProvider {
   readonly id = "twilio-verify";
   constructor(options?: {accountSid?: string; authToken?: string; verifyServiceSid?: string});
   startVerification(options: {to: string; channel: "sms" | "email"}): Promise<SendResult>;
-  checkVerification(options: {to: string; code: string}): Promise<{valid: boolean}>;
+  checkVerification(options: {to: string; code: string}): Promise<{valid: boolean; error?: string}>;
 }
 ```
 
@@ -64,8 +67,8 @@ None.
 
 ## Activity Log & User Updates
 
-Verification attempts logged to `CommsMessage` (no codes, destination redacted to
-last-4).
+Verification attempts logged to `CommsMessage` (no codes; destination fully redacted by core,
+with the verification channel stored in metadata).
 
 ## Not Included / Future Work
 
@@ -89,5 +92,8 @@ See [docs/tasks/comms-adapter-twilio-verify.md](../tasks/comms-adapter-twilio-ve
       and email channels.
 - [ ] `checkVerification` returns `valid: true` only for `approved`; expired and
       max-attempt states return `valid: false` with a reason.
+- [ ] Failed starts/checks record `errorCode`/`errorClass` per the classification row and
+      fire the consumer `onError` hook; verification rows are marked non-retryable for
+      the admin dashboard.
 - [ ] No OTP code ever appears in logs or `CommsMessage` rows; destinations are redacted.
 - [ ] Missing `TWILIO_VERIFY_SERVICE_SID` fails fast at registration with a clear error.